diff -pruN 16.3-5/bfd/doc/aoutx.texi 16.3-5ubuntu1/bfd/doc/aoutx.texi --- 16.3-5/bfd/doc/aoutx.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/aoutx.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,170 @@ +@section a.out backends + +BFD supports a number of different flavours of a.out format, +though the major differences are only the sizes of the +structures on disk, and the shape of the relocation +information. + +The support is split into a basic support file @file{aoutx.h} +and other files which derive functions from the base. One +derivation file is @file{aoutf1.h} (for a.out flavour 1), and +adds to the basic a.out functions support for sun3, sun4, and +386 a.out files, to create a target jump vector for a specific +target. + +This information is further split out into more specific files +for each machine, including @file{sunos.c} for sun3 and sun4, +and @file{demo64.c} for a demonstration of a 64 bit a.out format. + +The base file @file{aoutx.h} defines general mechanisms for +reading and writing records to and from disk and various +other methods which BFD requires. It is included by +@file{aout32.c} and @file{aout64.c} to form the names +@code{aout_32_swap_exec_header_in}, @code{aout_64_swap_exec_header_in}, etc. + +As an example, this is what goes on to make the back end for a +sun4, from @file{aout32.c}: + +@example + #define ARCH_SIZE 32 + #include "aoutx.h" +@end example + +Which exports names: + +@example + ... + aout_32_canonicalize_reloc + aout_32_find_nearest_line + aout_32_get_lineno + aout_32_get_reloc_upper_bound + ... +@end example + +from @file{sunos.c}: + +@example + #define TARGET_NAME "a.out-sunos-big" + #define VECNAME sparc_aout_sunos_be_vec + #include "aoutf1.h" +@end example + +requires all the names from @file{aout32.c}, and produces the jump vector + +@example + sparc_aout_sunos_be_vec +@end example + +The file @file{host-aout.c} is a special case. It is for a large set +of hosts that use ``more or less standard'' a.out files, and +for which cross-debugging is not interesting. It uses the +standard 32-bit a.out support routines, but determines the +file offsets and addresses of the text, data, and BSS +sections, the machine architecture and machine type, and the +entry point address, in a host-dependent manner. Once these +values have been determined, generic code is used to handle +the object file. + +When porting it to run on a new system, you must supply: + +@example + HOST_PAGE_SIZE + HOST_SEGMENT_SIZE + HOST_MACHINE_ARCH (optional) + HOST_MACHINE_MACHINE (optional) + HOST_TEXT_START_ADDR + HOST_STACK_END_ADDR +@end example + +in the file @file{../include/sys/h-@var{XXX}.h} (for your host). These +values, plus the structures and macros defined in @file{a.out.h} on +your host system, will produce a BFD target that will access +ordinary a.out files on your host. To configure a new machine +to use @file{host-aout.c}, specify: + +@example + TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec + TDEPFILES= host-aout.o trad-core.o +@end example + +in the @file{config/@var{XXX}.mt} file, and modify @file{configure.ac} +to use the +@file{@var{XXX}.mt} file (by setting "@code{bfd_target=XXX}") when your +configuration is selected. + +@subsection Relocations + + +The file @file{aoutx.h} provides for both the @emph{standard} +and @emph{extended} forms of a.out relocation records. + +The standard records contain only an address, a symbol index, +and a type field. The extended records also have a full +integer for an addend. + +@subsection Internal entry points + + +@file{aoutx.h} exports several routines for accessing the +contents of an a.out file, which are gathered and exported in +turn by various format specific files (eg sunos.c). + +@findex aout_@var{size}_swap_exec_header_in +@subsubsection @code{aout_@var{size}_swap_exec_header_in} +@deftypefn {Function} void aout_@var{size}_swap_exec_header_in, (bfd *abfd, struct external_exec *bytes, struct internal_exec *execp); +Swap the information in an executable header @var{raw_bytes} taken +from a raw byte stream memory image into the internal exec header +structure @var{execp}. + +@end deftypefn +@findex aout_@var{size}_swap_exec_header_out +@subsubsection @code{aout_@var{size}_swap_exec_header_out} +@deftypefn {Function} bool aout_@var{size}_swap_exec_header_out (bfd *abfd, struct internal_exec *execp, struct external_exec *raw_bytes); +Swap the information in an internal exec header structure +@var{execp} into the buffer @var{raw_bytes} ready for writing to disk. + +@end deftypefn +@findex aout_@var{size}_some_aout_object_p +@subsubsection @code{aout_@var{size}_some_aout_object_p} +@deftypefn {Function} bfd_cleanup aout_@var{size}_some_aout_object_p (bfd *abfd, struct internal_exec *execp, bfd_cleanup (*callback_to_real_object_p) (bfd *)); +Some a.out variant thinks that the file open in @var{abfd} +checking is an a.out file. Do some more checking, and set up +for access if it really is. Call back to the calling +environment's "finish up" function just before returning, to +handle any last-minute setup. + +@end deftypefn +@findex aout_@var{size}_mkobject +@subsubsection @code{aout_@var{size}_mkobject} +@deftypefn {Function} bool aout_@var{size}_mkobject, (bfd *abfd); +Initialize BFD @var{abfd} for use with a.out files. + +@end deftypefn +@findex aout_@var{size}_machine_type +@subsubsection @code{aout_@var{size}_machine_type} +@deftypefn {Function} enum machine_type aout_@var{size}_machine_type (enum bfd_architecture arch, unsigned long machine, bool *unknown); +Keep track of machine architecture and machine type for +a.out's. Return the @code{machine_type} for a particular +architecture and machine, or @code{M_UNKNOWN} if that exact architecture +and machine can't be represented in a.out format. + +If the architecture is understood, machine type 0 (default) +is always understood. + +@end deftypefn +@findex aout_@var{size}_set_arch_mach +@subsubsection @code{aout_@var{size}_set_arch_mach} +@deftypefn {Function} bool aout_@var{size}_set_arch_mach, (bfd *, enum bfd_architecture arch, unsigned long machine); +Set the architecture and the machine of the BFD @var{abfd} to the +values @var{arch} and @var{machine}. Verify that @var{abfd}'s format +can support the architecture required. + +@end deftypefn +@findex aout_@var{size}_new_section_hook +@subsubsection @code{aout_@var{size}_new_section_hook} +@deftypefn {Function} bool aout_@var{size}_new_section_hook, (bfd *abfd, asection *newsect); +Called by the BFD in response to a @code{bfd_make_section} +request. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/archive.texi 16.3-5ubuntu1/bfd/doc/archive.texi --- 16.3-5/bfd/doc/archive.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/archive.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,95 @@ +@section Archives + +An archive (or library) is just another BFD. It has a symbol +table, although there's not much a user program will do with it. + +The big difference between an archive BFD and an ordinary BFD +is that the archive doesn't have sections. Instead it has a +chain of BFDs that are considered its contents. These BFDs can +be manipulated like any other. The BFDs contained in an +archive opened for reading will all be opened for reading. You +may put either input or output BFDs into an archive opened for +output; they will be handled correctly when the archive is closed. + +Use @code{bfd_openr_next_archived_file} to step through +the contents of an archive opened for input. You don't +have to read the entire archive if you don't want +to! Read it until you find what you want. + +A BFD returned by @code{bfd_openr_next_archived_file} can be +closed manually with @code{bfd_close}. If you do not close it, +then a second iteration through the members of an archive may +return the same BFD. If you close the archive BFD, then all +the member BFDs will automatically be closed as well. + +Archive contents of output BFDs are chained through the +@code{archive_next} pointer in a BFD. The first one is findable +through the @code{archive_head} slot of the archive. Set it with +@code{bfd_set_archive_head} (q.v.). A given BFD may be in only +one open output archive at a time. + +As expected, the BFD archive code is more general than the +archive code of any given environment. BFD archives may +contain files of different formats (e.g., a.out and coff) and +even different architectures. You may even place archives +recursively into archives! + +This can cause unexpected confusion, since some archive +formats are more expressive than others. For instance, Intel +COFF archives can preserve long filenames; SunOS a.out archives +cannot. If you move a file from the first to the second +format and back again, the filename may be truncated. +Likewise, different a.out environments have different +conventions as to how they truncate filenames, whether they +preserve directory names in filenames, etc. When +interoperating with native tools, be sure your files are +homogeneous. + +Beware: most of these formats do not react well to the +presence of spaces in filenames. We do the best we can, but +can't always handle this case due to restrictions in the format of +archives. Many Unix utilities are braindead in regards to +spaces and such in filenames anyway, so this shouldn't be much +of a restriction. + +Archives are supported in BFD in @code{archive.c}. + +@subsection Archive functions + + +@findex bfd_get_next_mapent +@subsubsection @code{bfd_get_next_mapent} +@deftypefn {Function} symindex bfd_get_next_mapent (bfd *abfd, symindex previous, carsym **sym); +Step through archive @var{abfd}'s symbol table (if it +has one). Successively update @var{sym} with the next symbol's +information, returning that symbol's (internal) index into the +symbol table. + +Supply @code{BFD_NO_MORE_SYMBOLS} as the @var{previous} entry to get +the first one; returns @code{BFD_NO_MORE_SYMBOLS} when you've already +got the last one. + +A @code{carsym} is a canonical archive symbol. The only +user-visible element is its name, a null-terminated string. + +@end deftypefn +@findex bfd_set_archive_head +@subsubsection @code{bfd_set_archive_head} +@deftypefn {Function} bool bfd_set_archive_head (bfd *output, bfd *new_head); +Set the head of the chain of +BFDs contained in the archive @var{output} to @var{new_head}. + +@end deftypefn +@findex bfd_openr_next_archived_file +@subsubsection @code{bfd_openr_next_archived_file} +@deftypefn {Function} bfd *bfd_openr_next_archived_file (bfd *archive, bfd *previous); +Provided a BFD, @var{archive}, containing an archive and NULL, open +an input BFD on the first contained element and returns that. +Subsequent calls should pass the archive and the previous return +value to return a created BFD to the next contained element. NULL +is returned when there are no more. +Note - if you want to process the bfd returned by this call be +sure to call bfd_check_format() on it first. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/archures.texi 16.3-5ubuntu1/bfd/doc/archures.texi --- 16.3-5/bfd/doc/archures.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/archures.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,742 @@ +@section Architectures +BFD keeps one atom in a BFD describing the +architecture of the data attached to the BFD: a pointer to a +@code{bfd_arch_info_type}. +Pointers to structures can be requested independently of a BFD +so that an architecture's information can be interrogated +without access to an open BFD. + +The architecture information is provided by each architecture package. +The set of default architectures is selected by the macro +@code{SELECT_ARCHITECTURES}. This is normally set up in the +@file{config/@var{target}.mt} file of your choice. If the name is not +defined, then all the architectures supported are included. + +When BFD starts up, all the architectures are called with an +initialize method. It is up to the architecture back end to +insert as many items into the list of architectures as it wants to; +generally this would be one for each machine and one for the +default case (an item with a machine field of 0). + +BFD's idea of an architecture is implemented in @file{archures.c}. + +@subsection bfd_architecture + + +This enum gives the object file's CPU architecture, in a +global sense---i.e., what processor family does it belong to? +Another field indicates which processor within +the family is in use. The machine gives a number which +distinguishes different versions of the architecture, +containing, for example, 68020 for Motorola 68020. +@example +enum bfd_architecture +@{ + bfd_arch_unknown, /* File arch not known. */ + bfd_arch_obscure, /* Arch known, not one of these. */ + bfd_arch_m68k, /* Motorola 68xxx. */ +#define bfd_mach_m68000 1 +#define bfd_mach_m68008 2 +#define bfd_mach_m68010 3 +#define bfd_mach_m68020 4 +#define bfd_mach_m68030 5 +#define bfd_mach_m68040 6 +#define bfd_mach_m68060 7 +#define bfd_mach_cpu32 8 +#define bfd_mach_fido 9 +#define bfd_mach_mcf_isa_a_nodiv 10 +#define bfd_mach_mcf_isa_a 11 +#define bfd_mach_mcf_isa_a_mac 12 +#define bfd_mach_mcf_isa_a_emac 13 +#define bfd_mach_mcf_isa_aplus 14 +#define bfd_mach_mcf_isa_aplus_mac 15 +#define bfd_mach_mcf_isa_aplus_emac 16 +#define bfd_mach_mcf_isa_b_nousp 17 +#define bfd_mach_mcf_isa_b_nousp_mac 18 +#define bfd_mach_mcf_isa_b_nousp_emac 19 +#define bfd_mach_mcf_isa_b 20 +#define bfd_mach_mcf_isa_b_mac 21 +#define bfd_mach_mcf_isa_b_emac 22 +#define bfd_mach_mcf_isa_b_float 23 +#define bfd_mach_mcf_isa_b_float_mac 24 +#define bfd_mach_mcf_isa_b_float_emac 25 +#define bfd_mach_mcf_isa_c 26 +#define bfd_mach_mcf_isa_c_mac 27 +#define bfd_mach_mcf_isa_c_emac 28 +#define bfd_mach_mcf_isa_c_nodiv 29 +#define bfd_mach_mcf_isa_c_nodiv_mac 30 +#define bfd_mach_mcf_isa_c_nodiv_emac 31 + bfd_arch_vax, /* DEC Vax. */ + + bfd_arch_or1k, /* OpenRISC 1000. */ +#define bfd_mach_or1k 1 +#define bfd_mach_or1knd 2 + + bfd_arch_sparc, /* SPARC. */ +#define bfd_mach_sparc 1 +/* The difference between v8plus and v9 is that v9 is a true 64 bit env. */ +#define bfd_mach_sparc_sparclet 2 +#define bfd_mach_sparc_sparclite 3 +#define bfd_mach_sparc_v8plus 4 +#define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */ +#define bfd_mach_sparc_sparclite_le 6 +#define bfd_mach_sparc_v9 7 +#define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */ +#define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */ +#define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */ +#define bfd_mach_sparc_v8plusc 11 /* with UA2005 and T1 add'ns. */ +#define bfd_mach_sparc_v9c 12 /* with UA2005 and T1 add'ns. */ +#define bfd_mach_sparc_v8plusd 13 /* with UA2007 and T3 add'ns. */ +#define bfd_mach_sparc_v9d 14 /* with UA2007 and T3 add'ns. */ +#define bfd_mach_sparc_v8pluse 15 /* with OSA2001 and T4 add'ns (no IMA). */ +#define bfd_mach_sparc_v9e 16 /* with OSA2001 and T4 add'ns (no IMA). */ +#define bfd_mach_sparc_v8plusv 17 /* with OSA2011 and T4 and IMA and FJMAU add'ns. */ +#define bfd_mach_sparc_v9v 18 /* with OSA2011 and T4 and IMA and FJMAU add'ns. */ +#define bfd_mach_sparc_v8plusm 19 /* with OSA2015 and M7 add'ns. */ +#define bfd_mach_sparc_v9m 20 /* with OSA2015 and M7 add'ns. */ +#define bfd_mach_sparc_v8plusm8 21 /* with OSA2017 and M8 add'ns. */ +#define bfd_mach_sparc_v9m8 22 /* with OSA2017 and M8 add'ns. */ +/* Nonzero if MACH has the v9 instruction set. */ +#define bfd_mach_sparc_v9_p(mach) \ + ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9m8 \ + && (mach) != bfd_mach_sparc_sparclite_le) +/* Nonzero if MACH is a 64 bit sparc architecture. */ +#define bfd_mach_sparc_64bit_p(mach) \ + ((mach) >= bfd_mach_sparc_v9 \ + && (mach) != bfd_mach_sparc_v8plusb \ + && (mach) != bfd_mach_sparc_v8plusc \ + && (mach) != bfd_mach_sparc_v8plusd \ + && (mach) != bfd_mach_sparc_v8pluse \ + && (mach) != bfd_mach_sparc_v8plusv \ + && (mach) != bfd_mach_sparc_v8plusm \ + && (mach) != bfd_mach_sparc_v8plusm8) + bfd_arch_spu, /* PowerPC SPU. */ +#define bfd_mach_spu 256 + bfd_arch_mips, /* MIPS Rxxxx. */ +#define bfd_mach_mips3000 3000 +#define bfd_mach_mips3900 3900 +#define bfd_mach_mips4000 4000 +#define bfd_mach_mips4010 4010 +#define bfd_mach_mips4100 4100 +#define bfd_mach_mips4111 4111 +#define bfd_mach_mips4120 4120 +#define bfd_mach_mips4300 4300 +#define bfd_mach_mips4400 4400 +#define bfd_mach_mips4600 4600 +#define bfd_mach_mips4650 4650 +#define bfd_mach_mips5000 5000 +#define bfd_mach_mips5400 5400 +#define bfd_mach_mips5500 5500 +#define bfd_mach_mips5900 5900 +#define bfd_mach_mips6000 6000 +#define bfd_mach_mips7000 7000 +#define bfd_mach_mips8000 8000 +#define bfd_mach_mips9000 9000 +#define bfd_mach_mips10000 10000 +#define bfd_mach_mips12000 12000 +#define bfd_mach_mips14000 14000 +#define bfd_mach_mips16000 16000 +#define bfd_mach_mips16 16 +#define bfd_mach_mips5 5 +#define bfd_mach_mips_allegrex 10111431 /* octal 'AL', 31. */ +#define bfd_mach_mips_loongson_2e 3001 +#define bfd_mach_mips_loongson_2f 3002 +#define bfd_mach_mips_gs464 3003 +#define bfd_mach_mips_gs464e 3004 +#define bfd_mach_mips_gs264e 3005 +#define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01. */ +#define bfd_mach_mips_octeon 6501 +#define bfd_mach_mips_octeonp 6601 +#define bfd_mach_mips_octeon2 6502 +#define bfd_mach_mips_octeon3 6503 +#define bfd_mach_mips_xlr 887682 /* decimal 'XLR'. */ +#define bfd_mach_mips_interaptiv_mr2 736550 /* decimal 'IA2'. */ +#define bfd_mach_mipsisa32 32 +#define bfd_mach_mipsisa32r2 33 +#define bfd_mach_mipsisa32r3 34 +#define bfd_mach_mipsisa32r5 36 +#define bfd_mach_mipsisa32r6 37 +#define bfd_mach_mipsisa64 64 +#define bfd_mach_mipsisa64r2 65 +#define bfd_mach_mipsisa64r3 66 +#define bfd_mach_mipsisa64r5 68 +#define bfd_mach_mipsisa64r6 69 +#define bfd_mach_mips_micromips 96 + bfd_arch_i386, /* Intel 386. */ +#define bfd_mach_i386_intel_syntax (1 << 0) +#define bfd_mach_i386_i8086 (1 << 1) +#define bfd_mach_i386_i386 (1 << 2) +#define bfd_mach_x86_64 (1 << 3) +#define bfd_mach_x64_32 (1 << 4) +#define bfd_mach_i386_i386_intel_syntax (bfd_mach_i386_i386 | bfd_mach_i386_intel_syntax) +#define bfd_mach_x86_64_intel_syntax (bfd_mach_x86_64 | bfd_mach_i386_intel_syntax) +#define bfd_mach_x64_32_intel_syntax (bfd_mach_x64_32 | bfd_mach_i386_intel_syntax) + bfd_arch_iamcu, /* Intel MCU. */ +#define bfd_mach_iamcu (1 << 8) +#define bfd_mach_i386_iamcu (bfd_mach_i386_i386 | bfd_mach_iamcu) +#define bfd_mach_i386_iamcu_intel_syntax (bfd_mach_i386_iamcu | bfd_mach_i386_intel_syntax) + bfd_arch_romp, /* IBM ROMP PC/RT. */ + bfd_arch_convex, /* Convex. */ + bfd_arch_m98k, /* Motorola 98xxx. */ + bfd_arch_pyramid, /* Pyramid Technology. */ + bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300). */ +#define bfd_mach_h8300 1 +#define bfd_mach_h8300h 2 +#define bfd_mach_h8300s 3 +#define bfd_mach_h8300hn 4 +#define bfd_mach_h8300sn 5 +#define bfd_mach_h8300sx 6 +#define bfd_mach_h8300sxn 7 + bfd_arch_pdp11, /* DEC PDP-11. */ + bfd_arch_powerpc, /* PowerPC. */ +#define bfd_mach_ppc 32 +#define bfd_mach_ppc64 64 +#define bfd_mach_ppc_403 403 +#define bfd_mach_ppc_403gc 4030 +#define bfd_mach_ppc_405 405 +#define bfd_mach_ppc_505 505 +#define bfd_mach_ppc_601 601 +#define bfd_mach_ppc_602 602 +#define bfd_mach_ppc_603 603 +#define bfd_mach_ppc_ec603e 6031 +#define bfd_mach_ppc_604 604 +#define bfd_mach_ppc_620 620 +#define bfd_mach_ppc_630 630 +#define bfd_mach_ppc_750 750 +#define bfd_mach_ppc_860 860 +#define bfd_mach_ppc_a35 35 +#define bfd_mach_ppc_rs64ii 642 +#define bfd_mach_ppc_rs64iii 643 +#define bfd_mach_ppc_7400 7400 +#define bfd_mach_ppc_e500 500 +#define bfd_mach_ppc_e500mc 5001 +#define bfd_mach_ppc_e500mc64 5005 +#define bfd_mach_ppc_e5500 5006 +#define bfd_mach_ppc_e6500 5007 +#define bfd_mach_ppc_titan 83 +#define bfd_mach_ppc_vle 84 + bfd_arch_rs6000, /* IBM RS/6000. */ +#define bfd_mach_rs6k 6000 +#define bfd_mach_rs6k_rs1 6001 +#define bfd_mach_rs6k_rsc 6003 +#define bfd_mach_rs6k_rs2 6002 + bfd_arch_hppa, /* HP PA RISC. */ +#define bfd_mach_hppa10 10 +#define bfd_mach_hppa11 11 +#define bfd_mach_hppa20 20 +#define bfd_mach_hppa20w 25 + bfd_arch_d10v, /* Mitsubishi D10V. */ +#define bfd_mach_d10v 1 +#define bfd_mach_d10v_ts2 2 +#define bfd_mach_d10v_ts3 3 + bfd_arch_d30v, /* Mitsubishi D30V. */ + bfd_arch_dlx, /* DLX. */ + bfd_arch_m68hc11, /* Motorola 68HC11. */ + bfd_arch_m68hc12, /* Motorola 68HC12. */ +#define bfd_mach_m6812_default 0 +#define bfd_mach_m6812 1 +#define bfd_mach_m6812s 2 + bfd_arch_m9s12x, /* Freescale S12X. */ + bfd_arch_m9s12xg, /* Freescale XGATE. */ + bfd_arch_s12z, /* Freescale S12Z. */ +#define bfd_mach_s12z_default 0 + bfd_arch_z8k, /* Zilog Z8000. */ +#define bfd_mach_z8001 1 +#define bfd_mach_z8002 2 + bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH). */ +#define bfd_mach_sh 1 +#define bfd_mach_sh2 0x20 +#define bfd_mach_sh_dsp 0x2d +#define bfd_mach_sh2a 0x2a +#define bfd_mach_sh2a_nofpu 0x2b +#define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1 +#define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2 +#define bfd_mach_sh2a_or_sh4 0x2a3 +#define bfd_mach_sh2a_or_sh3e 0x2a4 +#define bfd_mach_sh2e 0x2e +#define bfd_mach_sh3 0x30 +#define bfd_mach_sh3_nommu 0x31 +#define bfd_mach_sh3_dsp 0x3d +#define bfd_mach_sh3e 0x3e +#define bfd_mach_sh4 0x40 +#define bfd_mach_sh4_nofpu 0x41 +#define bfd_mach_sh4_nommu_nofpu 0x42 +#define bfd_mach_sh4a 0x4a +#define bfd_mach_sh4a_nofpu 0x4b +#define bfd_mach_sh4al_dsp 0x4d + bfd_arch_alpha, /* Dec Alpha. */ +#define bfd_mach_alpha_ev4 0x10 +#define bfd_mach_alpha_ev5 0x20 +#define bfd_mach_alpha_ev6 0x30 + bfd_arch_arm, /* Advanced Risc Machines ARM. */ +#define bfd_mach_arm_unknown 0 +#define bfd_mach_arm_2 1 +#define bfd_mach_arm_2a 2 +#define bfd_mach_arm_3 3 +#define bfd_mach_arm_3M 4 +#define bfd_mach_arm_4 5 +#define bfd_mach_arm_4T 6 +#define bfd_mach_arm_5 7 +#define bfd_mach_arm_5T 8 +#define bfd_mach_arm_5TE 9 +#define bfd_mach_arm_XScale 10 +#define bfd_mach_arm_ep9312 11 +#define bfd_mach_arm_iWMMXt 12 +#define bfd_mach_arm_iWMMXt2 13 +#define bfd_mach_arm_5TEJ 14 +#define bfd_mach_arm_6 15 +#define bfd_mach_arm_6KZ 16 +#define bfd_mach_arm_6T2 17 +#define bfd_mach_arm_6K 18 +#define bfd_mach_arm_7 19 +#define bfd_mach_arm_6M 20 +#define bfd_mach_arm_6SM 21 +#define bfd_mach_arm_7EM 22 +#define bfd_mach_arm_8 23 +#define bfd_mach_arm_8R 24 +#define bfd_mach_arm_8M_BASE 25 +#define bfd_mach_arm_8M_MAIN 26 +#define bfd_mach_arm_8_1M_MAIN 27 +#define bfd_mach_arm_9 28 + bfd_arch_nds32, /* Andes NDS32. */ +#define bfd_mach_n1 1 +#define bfd_mach_n1h 2 +#define bfd_mach_n1h_v2 3 +#define bfd_mach_n1h_v3 4 +#define bfd_mach_n1h_v3m 5 + bfd_arch_ns32k, /* National Semiconductors ns32000. */ + bfd_arch_tic30, /* Texas Instruments TMS320C30. */ + bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X. */ +#define bfd_mach_tic3x 30 +#define bfd_mach_tic4x 40 + bfd_arch_tic54x, /* Texas Instruments TMS320C54X. */ + bfd_arch_tic6x, /* Texas Instruments TMS320C6X. */ + bfd_arch_v850, /* NEC V850. */ + bfd_arch_v850_rh850,/* NEC V850 (using RH850 ABI). */ +#define bfd_mach_v850 1 +#define bfd_mach_v850e 'E' +#define bfd_mach_v850e1 '1' +#define bfd_mach_v850e2 0x4532 +#define bfd_mach_v850e2v3 0x45325633 +#define bfd_mach_v850e3v5 0x45335635 /* ('E'|'3'|'V'|'5'). */ + bfd_arch_arc, /* ARC Cores. */ +#define bfd_mach_arc_a4 0 +#define bfd_mach_arc_a5 1 +#define bfd_mach_arc_arc600 2 +#define bfd_mach_arc_arc601 4 +#define bfd_mach_arc_arc700 3 +#define bfd_mach_arc_arcv2 5 + bfd_arch_m32c, /* Renesas M16C/M32C. */ +#define bfd_mach_m16c 0x75 +#define bfd_mach_m32c 0x78 + bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D). */ +#define bfd_mach_m32r 1 /* For backwards compatibility. */ +#define bfd_mach_m32rx 'x' +#define bfd_mach_m32r2 '2' + bfd_arch_mn10200, /* Matsushita MN10200. */ + bfd_arch_mn10300, /* Matsushita MN10300. */ +#define bfd_mach_mn10300 300 +#define bfd_mach_am33 330 +#define bfd_mach_am33_2 332 + bfd_arch_fr30, +#define bfd_mach_fr30 0x46523330 + bfd_arch_frv, +#define bfd_mach_frv 1 +#define bfd_mach_frvsimple 2 +#define bfd_mach_fr300 300 +#define bfd_mach_fr400 400 +#define bfd_mach_fr450 450 +#define bfd_mach_frvtomcat 499 /* fr500 prototype. */ +#define bfd_mach_fr500 500 +#define bfd_mach_fr550 550 + bfd_arch_moxie, /* The moxie processor. */ +#define bfd_mach_moxie 1 + bfd_arch_ft32, /* The ft32 processor. */ +#define bfd_mach_ft32 1 +#define bfd_mach_ft32b 2 + bfd_arch_mcore, + bfd_arch_mep, +#define bfd_mach_mep 1 +#define bfd_mach_mep_h1 0x6831 +#define bfd_mach_mep_c5 0x6335 + bfd_arch_metag, +#define bfd_mach_metag 1 + bfd_arch_ia64, /* HP/Intel ia64. */ +#define bfd_mach_ia64_elf64 64 +#define bfd_mach_ia64_elf32 32 + bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */ +#define bfd_mach_ip2022 1 +#define bfd_mach_ip2022ext 2 + bfd_arch_iq2000, /* Vitesse IQ2000. */ +#define bfd_mach_iq2000 1 +#define bfd_mach_iq10 2 + bfd_arch_bpf, /* Linux eBPF. */ +#define bfd_mach_bpf 1 +#define bfd_mach_xbpf 2 + bfd_arch_epiphany, /* Adapteva EPIPHANY. */ +#define bfd_mach_epiphany16 1 +#define bfd_mach_epiphany32 2 + bfd_arch_mt, +#define bfd_mach_ms1 1 +#define bfd_mach_mrisc2 2 +#define bfd_mach_ms2 3 + bfd_arch_pj, + bfd_arch_avr, /* Atmel AVR microcontrollers. */ +#define bfd_mach_avr1 1 +#define bfd_mach_avr2 2 +#define bfd_mach_avr25 25 +#define bfd_mach_avr3 3 +#define bfd_mach_avr31 31 +#define bfd_mach_avr35 35 +#define bfd_mach_avr4 4 +#define bfd_mach_avr5 5 +#define bfd_mach_avr51 51 +#define bfd_mach_avr6 6 +#define bfd_mach_avrtiny 100 +#define bfd_mach_avrxmega1 101 +#define bfd_mach_avrxmega2 102 +#define bfd_mach_avrxmega3 103 +#define bfd_mach_avrxmega4 104 +#define bfd_mach_avrxmega5 105 +#define bfd_mach_avrxmega6 106 +#define bfd_mach_avrxmega7 107 + bfd_arch_bfin, /* ADI Blackfin. */ +#define bfd_mach_bfin 1 + bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */ +#define bfd_mach_cr16 1 + bfd_arch_crx, /* National Semiconductor CRX. */ +#define bfd_mach_crx 1 + bfd_arch_cris, /* Axis CRIS. */ +#define bfd_mach_cris_v0_v10 255 +#define bfd_mach_cris_v32 32 +#define bfd_mach_cris_v10_v32 1032 + bfd_arch_riscv, +#define bfd_mach_riscv32 132 +#define bfd_mach_riscv64 164 + bfd_arch_rl78, +#define bfd_mach_rl78 0x75 + bfd_arch_rx, /* Renesas RX. */ +#define bfd_mach_rx 0x75 +#define bfd_mach_rx_v2 0x76 +#define bfd_mach_rx_v3 0x77 + bfd_arch_s390, /* IBM s390. */ +#define bfd_mach_s390_31 31 +#define bfd_mach_s390_64 64 + bfd_arch_score, /* Sunplus score. */ +#define bfd_mach_score3 3 +#define bfd_mach_score7 7 + bfd_arch_mmix, /* Donald Knuth's educational processor. */ + bfd_arch_xstormy16, +#define bfd_mach_xstormy16 1 + bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */ +#define bfd_mach_msp11 11 +#define bfd_mach_msp110 110 +#define bfd_mach_msp12 12 +#define bfd_mach_msp13 13 +#define bfd_mach_msp14 14 +#define bfd_mach_msp15 15 +#define bfd_mach_msp16 16 +#define bfd_mach_msp20 20 +#define bfd_mach_msp21 21 +#define bfd_mach_msp22 22 +#define bfd_mach_msp23 23 +#define bfd_mach_msp24 24 +#define bfd_mach_msp26 26 +#define bfd_mach_msp31 31 +#define bfd_mach_msp32 32 +#define bfd_mach_msp33 33 +#define bfd_mach_msp41 41 +#define bfd_mach_msp42 42 +#define bfd_mach_msp43 43 +#define bfd_mach_msp44 44 +#define bfd_mach_msp430x 45 +#define bfd_mach_msp46 46 +#define bfd_mach_msp47 47 +#define bfd_mach_msp54 54 + bfd_arch_xgate, /* Freescale XGATE. */ +#define bfd_mach_xgate 1 + bfd_arch_xtensa, /* Tensilica's Xtensa cores. */ +#define bfd_mach_xtensa 1 + bfd_arch_z80, +/* Zilog Z80 without undocumented opcodes. */ +#define bfd_mach_z80strict 1 +/* Zilog Z180: successor with additional instructions, but without + halves of ix and iy. */ +#define bfd_mach_z180 2 +/* Zilog Z80 with ixl, ixh, iyl, and iyh. */ +#define bfd_mach_z80 3 +/* Zilog eZ80 (successor of Z80 & Z180) in Z80 (16-bit address) mode. */ +#define bfd_mach_ez80_z80 4 +/* Zilog eZ80 (successor of Z80 & Z180) in ADL (24-bit address) mode. */ +#define bfd_mach_ez80_adl 5 +/* Z80N */ +#define bfd_mach_z80n 6 +/* Zilog Z80 with all undocumented instructions. */ +#define bfd_mach_z80full 7 +/* GameBoy Z80 (reduced instruction set). */ +#define bfd_mach_gbz80 8 +/* ASCII R800: successor with multiplication. */ +#define bfd_mach_r800 11 + bfd_arch_lm32, /* Lattice Mico32. */ +#define bfd_mach_lm32 1 + bfd_arch_microblaze,/* Xilinx MicroBlaze. */ + bfd_arch_kvx, /* Kalray VLIW core of the MPPA processor family */ +#define bfd_mach_kv3_unknown 0 +#define bfd_mach_kv3_1 1 +#define bfd_mach_kv3_1_64 2 +#define bfd_mach_kv3_1_usr 3 +#define bfd_mach_kv3_2 4 +#define bfd_mach_kv3_2_64 5 +#define bfd_mach_kv3_2_usr 6 +#define bfd_mach_kv4_1 7 +#define bfd_mach_kv4_1_64 8 +#define bfd_mach_kv4_1_usr 9 + bfd_arch_tilepro, /* Tilera TILEPro. */ + bfd_arch_tilegx, /* Tilera TILE-Gx. */ +#define bfd_mach_tilepro 1 +#define bfd_mach_tilegx 1 +#define bfd_mach_tilegx32 2 + bfd_arch_aarch64, /* AArch64. */ +#define bfd_mach_aarch64 0 +#define bfd_mach_aarch64_8R 1 +#define bfd_mach_aarch64_ilp32 32 +#define bfd_mach_aarch64_llp64 64 + bfd_arch_visium, /* Visium. */ +#define bfd_mach_visium 1 + bfd_arch_wasm32, /* WebAssembly. */ +#define bfd_mach_wasm32 1 + bfd_arch_pru, /* PRU. */ +#define bfd_mach_pru 0 + bfd_arch_nfp, /* Netronome Flow Processor */ +#define bfd_mach_nfp3200 0x3200 +#define bfd_mach_nfp6000 0x6000 + bfd_arch_csky, /* C-SKY. */ +#define bfd_mach_ck_unknown 0 +#define bfd_mach_ck510 1 +#define bfd_mach_ck610 2 +#define bfd_mach_ck801 3 +#define bfd_mach_ck802 4 +#define bfd_mach_ck803 5 +#define bfd_mach_ck807 6 +#define bfd_mach_ck810 7 +#define bfd_mach_ck860 8 + bfd_arch_loongarch, /* LoongArch */ +#define bfd_mach_loongarch32 1 +#define bfd_mach_loongarch64 2 + bfd_arch_amdgcn, /* AMDGCN */ +#define bfd_mach_amdgcn_unknown 0x000 +#define bfd_mach_amdgcn_gfx900 0x02c +#define bfd_mach_amdgcn_gfx904 0x02e +#define bfd_mach_amdgcn_gfx906 0x02f +#define bfd_mach_amdgcn_gfx908 0x030 +#define bfd_mach_amdgcn_gfx90a 0x03f +#define bfd_mach_amdgcn_gfx1010 0x033 +#define bfd_mach_amdgcn_gfx1011 0x034 +#define bfd_mach_amdgcn_gfx1012 0x035 +#define bfd_mach_amdgcn_gfx1030 0x036 +#define bfd_mach_amdgcn_gfx1031 0x037 +#define bfd_mach_amdgcn_gfx1032 0x038 +#define bfd_mach_amdgcn_gfx1100 0x041 +#define bfd_mach_amdgcn_gfx1101 0x046 +#define bfd_mach_amdgcn_gfx1102 0x047 + bfd_arch_last + @}; +@end example + +@subsection bfd_arch_info + + +This structure contains information on architectures for use +within BFD. +@example + +typedef struct bfd_arch_info +@{ + int bits_per_word; + int bits_per_address; + int bits_per_byte; + enum bfd_architecture arch; + unsigned long mach; + const char *arch_name; + const char *printable_name; + unsigned int section_align_power; + /* TRUE if this is the default machine for the architecture. + The default arch should be the first entry for an arch so that + all the entries for that arch can be accessed via @code{next}. */ + bool the_default; + const struct bfd_arch_info * (*compatible) (const struct bfd_arch_info *, + const struct bfd_arch_info *); + + bool (*scan) (const struct bfd_arch_info *, const char *); + + /* Allocate via bfd_malloc and return a fill buffer of size COUNT. If + IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is + TRUE, the buffer contains code. */ + void *(*fill) (bfd_size_type count, bool is_bigendian, bool code); + + const struct bfd_arch_info *next; + + /* On some architectures the offset for a relocation can point into + the middle of an instruction. This field specifies the maximum + offset such a relocation can have (in octets). This affects the + behaviour of the disassembler, since a value greater than zero + means that it may need to disassemble an instruction twice, once + to get its length and then a second time to display it. If the + value is negative then this has to be done for every single + instruction, regardless of the offset of the reloc. */ + signed int max_reloc_offset_into_insn; +@} +bfd_arch_info_type; + +@end example + +@findex bfd_printable_name +@subsubsection @code{bfd_printable_name} +@deftypefn {Function} const char *bfd_printable_name (bfd *abfd); +Return a printable string representing the architecture and machine +from the pointer to the architecture info structure. + +@end deftypefn +@findex bfd_scan_arch +@subsubsection @code{bfd_scan_arch} +@deftypefn {Function} const bfd_arch_info_type *bfd_scan_arch (const char *string); +Figure out if BFD supports any cpu which could be described with +the name @var{string}. Return a pointer to an @code{arch_info} +structure if a machine is found, otherwise NULL. + +@end deftypefn +@findex bfd_arch_list +@subsubsection @code{bfd_arch_list} +@deftypefn {Function} const char **bfd_arch_list (void); +Return a freshly malloced NULL-terminated vector of the names +of all the valid BFD architectures. Do not modify the names. + +@end deftypefn +@findex bfd_arch_get_compatible +@subsubsection @code{bfd_arch_get_compatible} +@deftypefn {Function} const bfd_arch_info_type *bfd_arch_get_compatible (const bfd *abfd, const bfd *bbfd, bool accept_unknowns); +Determine whether two BFDs' architectures and machine types +are compatible. Calculates the lowest common denominator +between the two architectures and machine types implied by +the BFDs and returns a pointer to an @code{arch_info} structure +describing the compatible machine. + +@end deftypefn +@findex bfd_default_arch_struct +@subsubsection @code{bfd_default_arch_struct} +The @code{bfd_default_arch_struct} is an item of +@code{bfd_arch_info_type} which has been initialized to a fairly +generic state. A BFD starts life by pointing to this +structure, until the correct back end has determined the real +architecture of the file. +@example +extern const bfd_arch_info_type bfd_default_arch_struct; + +@end example + +@findex bfd_set_arch_info +@subsubsection @code{bfd_set_arch_info} +@deftypefn {Function} void bfd_set_arch_info (bfd *abfd, const bfd_arch_info_type *arg); +Set the architecture info of @var{abfd} to @var{arg}. + +@end deftypefn +@findex bfd_default_set_arch_mach +@subsubsection @code{bfd_default_set_arch_mach} +@deftypefn {Function} bool bfd_default_set_arch_mach (bfd *abfd, enum bfd_architecture arch, unsigned long mach); +Set the architecture and machine type in BFD @var{abfd} +to @var{arch} and @var{mach}. Find the correct +pointer to a structure and insert it into the @code{arch_info} +pointer. + +@end deftypefn +@findex bfd_get_arch +@subsubsection @code{bfd_get_arch} +@deftypefn {Function} enum bfd_architecture bfd_get_arch (const bfd *abfd); +Return the enumerated type which describes the BFD @var{abfd}'s +architecture. + +@end deftypefn +@findex bfd_get_mach +@subsubsection @code{bfd_get_mach} +@deftypefn {Function} unsigned long bfd_get_mach (const bfd *abfd); +Return the long type which describes the BFD @var{abfd}'s +machine. + +@end deftypefn +@findex bfd_arch_bits_per_byte +@subsubsection @code{bfd_arch_bits_per_byte} +@deftypefn {Function} unsigned int bfd_arch_bits_per_byte (const bfd *abfd); +Return the number of bits in one of the BFD @var{abfd}'s +architecture's bytes. + +@end deftypefn +@findex bfd_arch_bits_per_address +@subsubsection @code{bfd_arch_bits_per_address} +@deftypefn {Function} unsigned int bfd_arch_bits_per_address (const bfd *abfd); +Return the number of bits in one of the BFD @var{abfd}'s +architecture's addresses. + +@end deftypefn +@findex bfd_default_compatible +@subsubsection @code{bfd_default_compatible} +@deftypefn {Function} const bfd_arch_info_type *bfd_default_compatible (const bfd_arch_info_type *a, const bfd_arch_info_type *b); +The default function for testing for compatibility. + +@end deftypefn +@findex bfd_default_scan +@subsubsection @code{bfd_default_scan} +@deftypefn {Function} bool bfd_default_scan (const struct bfd_arch_info *info, const char *string); +The default function for working out whether this is an +architecture hit and a machine hit. + +@end deftypefn +@findex bfd_get_arch_info +@subsubsection @code{bfd_get_arch_info} +@deftypefn {Function} const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd); +Return the architecture info struct in @var{abfd}. + +@end deftypefn +@findex bfd_lookup_arch +@subsubsection @code{bfd_lookup_arch} +@deftypefn {Function} const bfd_arch_info_type *bfd_lookup_arch (enum bfd_architecture arch, unsigned long machine); +Look for the architecture info structure which matches the +arguments @var{arch} and @var{machine}. A machine of 0 matches the +machine/architecture structure which marks itself as the +default. + +@end deftypefn +@findex bfd_printable_arch_mach +@subsubsection @code{bfd_printable_arch_mach} +@deftypefn {Function} const char *bfd_printable_arch_mach (enum bfd_architecture arch, unsigned long machine); +Return a printable string representing the architecture and +machine type. + +This routine is depreciated. + +@end deftypefn +@findex bfd_octets_per_byte +@subsubsection @code{bfd_octets_per_byte} +@deftypefn {Function} unsigned int bfd_octets_per_byte (const bfd *abfd, const asection *sec); +Return the number of octets (8-bit quantities) per target byte +(minimum addressable unit). In most cases, this will be one, but some +DSP targets have 16, 32, or even 48 bits per byte. + +@end deftypefn +@findex bfd_arch_mach_octets_per_byte +@subsubsection @code{bfd_arch_mach_octets_per_byte} +@deftypefn {Function} unsigned int bfd_arch_mach_octets_per_byte (enum bfd_architecture arch, unsigned long machine); +See bfd_octets_per_byte. + +This routine is provided for those cases where a bfd * is not +available + +@end deftypefn +@findex bfd_arch_default_fill +@subsubsection @code{bfd_arch_default_fill} +@deftypefn {Function} void *bfd_arch_default_fill (bfd_size_type count, bool is_bigendian, bool code); +Allocate via bfd_malloc and return a fill buffer of size COUNT. +If IS_BIGENDIAN is TRUE, the order of bytes is big endian. If +CODE is TRUE, the buffer contains code. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/bfd.info 16.3-5ubuntu1/bfd/doc/bfd.info --- 16.3-5/bfd/doc/bfd.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfd.info 2025-04-20 17:24:59.000000000 +0000 @@ -0,0 +1,14762 @@ +This is bfd.info, produced by makeinfo version 6.8 from bfd.texi. + +This file documents the BFD library. + + Copyright (C) 1991-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "GNU General Public License" and "Funding Free +Software", the Front-Cover texts being (a) (see below), and with the +Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled "GNU Free Documentation License". + + (a) The FSF's Front-Cover Text is: + + A GNU Manual + + (b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU +software. Copies published by the Free Software Foundation raise funds +for GNU development. +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Bfd: (bfd). The Binary File Descriptor library. +END-INFO-DIR-ENTRY + + +File: bfd.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir) + +This file documents the binary file descriptor library libbfd. + +* Menu: + +* Overview:: Overview of BFD +* BFD front end:: BFD front end +* BFD back ends:: BFD back ends +* GNU Free Documentation License:: GNU Free Documentation License +* BFD Index:: BFD Index + + +File: bfd.info, Node: Overview, Next: BFD front end, Prev: Top, Up: Top + +1 Introduction +************** + +BFD is a package which allows applications to use the same routines to +operate on object files whatever the object file format. A new object +file format can be supported simply by creating a new BFD back end and +adding it to the library. + + BFD is split into two parts: the front end, and the back ends (one +for each object file format). + * The front end of BFD provides the interface to the user. It + manages memory and various canonical data structures. The front + end also decides which back end to use and when to call back end + routines. + * The back ends provide BFD its view of the real world. Each back + end provides a set of calls which the BFD front end can use to + maintain its canonical form. The back ends also may keep around + information for their own use, for greater efficiency. +* Menu: + +* History:: History +* How It Works:: How It Works +* What BFD Version 2 Can Do:: What BFD Version 2 Can Do + + +File: bfd.info, Node: History, Next: How It Works, Prev: Overview, Up: Overview + +1.1 History +=========== + +One spur behind BFD was the desire, on the part of the GNU 960 team at +Intel Oregon, for interoperability of applications on their COFF and +b.out file formats. Cygnus was providing GNU support for the team, and +was contracted to provide the required functionality. + + The name came from a conversation David Wallace was having with +Richard Stallman about the library: RMS said that it would be quite +hard--David said "BFD". Stallman was right, but the name stuck. + + At the same time, Ready Systems wanted much the same thing, but for +different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k +coff. + + BFD was first implemented by members of Cygnus Support; Steve +Chamberlain ('sac@cygnus.com'), John Gilmore ('gnu@cygnus.com'), K. +Richard Pixley ('rich@cygnus.com') and David Henkel-Wallace +('gumby@cygnus.com'). + + +File: bfd.info, Node: How It Works, Next: What BFD Version 2 Can Do, Prev: History, Up: Overview + +1.2 How To Use BFD +================== + +To use the library, include 'bfd.h' and link with 'libbfd.a'. + + BFD provides a common interface to the parts of an object file for a +calling application. + + When an application successfully opens a target file (object, +archive, or whatever), a pointer to an internal structure is returned. +This pointer points to a structure called 'bfd', described in 'bfd.h'. +Our convention is to call this pointer a BFD, and instances of it within +code 'abfd'. All operations on the target object file are applied as +methods to the BFD. The mapping is defined within 'bfd.h' in a set of +macros, all beginning with 'bfd_' to reduce namespace pollution. + + For example, this sequence does what you would probably expect: +return the number of sections in an object file attached to a BFD +'abfd'. + + #include "bfd.h" + + unsigned int number_of_sections (abfd) + bfd *abfd; + { + return bfd_count_sections (abfd); + } + + The abstraction used within BFD is that an object file has: + + * a header, + * a number of sections containing raw data (*note Sections::), + * a set of relocations (*note Relocations::), and + * some symbol information (*note Symbols::). +Also, BFDs opened for archives have the additional attribute of an index +and contain subordinate BFDs. This approach is fine for a.out and coff, +but loses efficiency when applied to formats such as S-records and +IEEE-695. + + +File: bfd.info, Node: What BFD Version 2 Can Do, Prev: How It Works, Up: Overview + +1.3 What BFD Version 2 Can Do +============================= + +When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file's data structures. + + As different information from the object files is required, BFD reads +from different sections of the file and processes them. For example, a +very common operation for the linker is processing symbol tables. Each +BFD back end provides a routine for converting between the object file's +representation of symbols and an internal canonical format. When the +linker asks for the symbol table of an object file, it calls through a +memory pointer to the routine from the relevant BFD back end which reads +and converts the table into a canonical form. The linker then operates +upon the canonical form. When the link is finished and the linker +writes the output file's symbol table, another BFD back end routine is +called to take the newly created symbol table and convert it into the +chosen output format. + +* Menu: + +* BFD information loss:: Information Loss +* Canonical format:: The BFD canonical object-file format + + +File: bfd.info, Node: BFD information loss, Next: Canonical format, Up: What BFD Version 2 Can Do + +1.3.1 Information Loss +---------------------- + +_Information can be lost during output._ The output formats supported +by BFD do not provide identical facilities, and information which can be +described in one form has nowhere to go in another format. One example +of this is alignment information in 'b.out'. There is nowhere in an +'a.out' format file to store alignment information on the contained +data, so when a file is linked from 'b.out' and an 'a.out' image is +produced, alignment information will not propagate to the output file. +(The linker will still use the alignment information internally, so the +link is performed correctly). + + Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections +(e.g., 'a.out') or has sections without names (e.g., the Oasys format), +the link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker +command language. + + _Information can be lost during canonicalization._ The BFD internal +canonical form of the external formats is not exhaustive; there are +structures in input formats for which there is no direct representation +internally. This means that the BFD back ends cannot maintain all +possible data richness through the transformation between external to +internal and back to external formats. + + This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD canonical +form has structures which are opaque to the BFD core, and exported only +to the back ends. When a file is read in one format, the canonical form +is generated for BFD and the application. At the same time, the back +end saves away any information which may otherwise be lost. If the data +is then written back in the same format, the back end routine will be +able to use the canonical form provided by the BFD core as well as the +information it prepared earlier. Since there is a great deal of +commonality between back ends, there is no information lost when linking +or copying big endian COFF to little endian COFF, or 'a.out' to 'b.out'. +When a mixture of formats is linked, the information is only lost from +the files whose format differs from the destination. + + +File: bfd.info, Node: Canonical format, Prev: BFD information loss, Up: What BFD Version 2 Can Do + +1.3.2 The BFD canonical object-file format +------------------------------------------ + +The greatest potential for loss of information occurs when there is the +least overlap between the information provided by the source format, +that stored by the canonical format, and that needed by the destination +format. A brief description of the canonical form may help you +understand which kinds of data you can count on preserving across +conversions. + +_files_ + Information stored on a per-file basis includes target machine + architecture, particular implementation format type, a demand + pageable bit, and a write protected bit. Information like Unix + magic numbers is not stored here--only the magic numbers' meaning, + so a 'ZMAGIC' file would have both the demand pageable bit and the + write protected text bit set. The byte order of the target is + stored on a per-file basis, so that big- and little-endian object + files may be used with one another. + +_sections_ + Each section in the input file contains the name of the section, + the section's original address in the object file, size and + alignment information, various flags, and pointers into other BFD + data structures. + +_symbols_ + Each symbol contains a pointer to the information for the object + file which originally defined it, its name, its value, and various + flag bits. When a BFD back end reads in a symbol table, it + relocates all symbols to make them relative to the base of the + section where they were defined. Doing this ensures that each + symbol points to its containing section. Each symbol also has a + varying amount of hidden private data for the BFD back end. Since + the symbol points to the original file, the private data format for + that symbol is accessible. 'ld' can operate on a collection of + symbols of wildly different formats without problems. + + Normal global and simple local symbols are maintained on output, so + an output file (no matter its format) will retain symbols pointing + to functions and to global, static, and common variables. Some + symbol information is not worth retaining; in 'a.out', type + information is stored in the symbol table as long symbol names. + This information would be useless to most COFF debuggers; the + linker has command-line switches to allow users to throw it away. + + There is one word of type information within the symbol, so if the + format supports symbol type information within symbols (for + example, COFF, Oasys) and the type is simple enough to fit within + one word (nearly everything but aggregates), the information will + be preserved. + +_relocation level_ + Each canonical BFD relocation record contains a pointer to the + symbol to relocate to, the offset of the data to relocate, the + section the data is in, and a pointer to a relocation type + descriptor. Relocation is performed by passing messages through + the relocation type descriptor and the symbol pointer. Therefore, + relocations can be performed on output data using a relocation + method that is only available in one of the input formats. For + instance, Oasys provides a byte relocation format. A relocation + record requesting this relocation type would point indirectly to a + routine to perform this, so the relocation may be performed on a + byte being written to a 68k COFF file, even though 68k COFF has no + such relocation type. + +_line numbers_ + Object formats can contain, for debugging purposes, some form of + mapping between symbols, source line numbers, and addresses in the + output file. These addresses have to be relocated along with the + symbol information. Each symbol with an associated list of line + number records points to the first record of the list. The head of + a line number list consists of a pointer to the symbol, which + allows finding out the address of the function whose line number is + being described. The rest of the list is made up of pairs: offsets + into the section and line numbers. Any format which can simply + derive this information can pass it successfully between formats. + + +File: bfd.info, Node: BFD front end, Next: BFD back ends, Prev: Overview, Up: Top + +2 BFD Front End +*************** + +* Menu: + +* typedef bfd:: +* Error reporting:: +* Initialization:: +* Threading:: +* Miscellaneous:: +* Memory Usage:: +* Sections:: +* Symbols:: +* Archives:: +* Formats:: +* Relocations:: +* Core Files:: +* Targets:: +* Architectures:: +* Opening and Closing:: +* Internal:: +* File Caching:: +* Linker Functions:: +* Hash Tables:: + + +File: bfd.info, Node: typedef bfd, Next: Error reporting, Prev: BFD front end, Up: BFD front end + +2.1 'typedef bfd' +================= + +A BFD has type 'bfd'; objects of this type are the cornerstone of any +application using BFD. Using BFD consists of making references though +the BFD and to data in the BFD. + + Here is the structure that defines the type 'bfd'. It contains the +major data about the file and pointers to the rest of the data. + + struct bfd + { + /* The filename the application opened the BFD with. */ + const char *filename; + + /* A pointer to the target jump table. */ + const struct bfd_target *xvec; + + /* The IOSTREAM, and corresponding IO vector that provide access + to the file backing the BFD. */ + void *iostream; + const struct bfd_iovec *iovec; + + /* The caching routines use these to maintain a + least-recently-used list of BFDs. */ + struct bfd *lru_prev, *lru_next; + + /* Track current file position (or current buffer offset for + in-memory BFDs). When a file is closed by the caching routines, + BFD retains state information on the file here. */ + ufile_ptr where; + + /* File modified time, if mtime_set is TRUE. */ + long mtime; + + /* A unique identifier of the BFD */ + unsigned int id; + + /* Format_specific flags. */ + flagword flags; + + /* Values that may appear in the flags field of a BFD. These also + appear in the object_flags field of the bfd_target structure, where + they indicate the set of flags used by that backend (not all flags + are meaningful for all object file formats) (FIXME: at the moment, + the object_flags values have mostly just been copied from backend + to another, and are not necessarily correct). */ + + #define BFD_NO_FLAGS 0x0 + + /* BFD contains relocation entries. */ + #define HAS_RELOC 0x1 + + /* BFD is directly executable. */ + #define EXEC_P 0x2 + + /* BFD has line number information (basically used for F_LNNO in a + COFF header). */ + #define HAS_LINENO 0x4 + + /* BFD has debugging information. */ + #define HAS_DEBUG 0x08 + + /* BFD has symbols. */ + #define HAS_SYMS 0x10 + + /* BFD has local symbols (basically used for F_LSYMS in a COFF + header). */ + #define HAS_LOCALS 0x20 + + /* BFD is a dynamic object. */ + #define DYNAMIC 0x40 + + /* Text section is write protected (if D_PAGED is not set, this is + like an a.out NMAGIC file) (the linker sets this by default, but + clears it for -r or -N). */ + #define WP_TEXT 0x80 + + /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the + linker sets this by default, but clears it for -r or -n or -N). */ + #define D_PAGED 0x100 + + /* BFD is relaxable (this means that bfd_relax_section may be able to + do something) (sometimes bfd_relax_section can do something even if + this is not set). */ + #define BFD_IS_RELAXABLE 0x200 + + /* This may be set before writing out a BFD to request using a + traditional format. For example, this is used to request that when + writing out an a.out object the symbols not be hashed to eliminate + duplicates. */ + #define BFD_TRADITIONAL_FORMAT 0x400 + + /* This flag indicates that the BFD contents are actually cached + in memory. If this is set, iostream points to a malloc'd + bfd_in_memory struct. */ + #define BFD_IN_MEMORY 0x800 + + /* This BFD has been created by the linker and doesn't correspond + to any input file. */ + #define BFD_LINKER_CREATED 0x1000 + + /* This may be set before writing out a BFD to request that it + be written using values for UIDs, GIDs, timestamps, etc. that + will be consistent from run to run. */ + #define BFD_DETERMINISTIC_OUTPUT 0x2000 + + /* Compress sections in this BFD. */ + #define BFD_COMPRESS 0x4000 + + /* Decompress sections in this BFD. */ + #define BFD_DECOMPRESS 0x8000 + + /* BFD is a dummy, for plugins. */ + #define BFD_PLUGIN 0x10000 + + /* Compress sections in this BFD with SHF_COMPRESSED from gABI. */ + #define BFD_COMPRESS_GABI 0x20000 + + /* Convert ELF common symbol type to STT_COMMON or STT_OBJECT in this + BFD. */ + #define BFD_CONVERT_ELF_COMMON 0x40000 + + /* Use the ELF STT_COMMON type in this BFD. */ + #define BFD_USE_ELF_STT_COMMON 0x80000 + + /* Put pathnames into archives (non-POSIX). */ + #define BFD_ARCHIVE_FULL_PATH 0x100000 + + #define BFD_CLOSED_BY_CACHE 0x200000 + /* Compress sections in this BFD with SHF_COMPRESSED zstd. */ + #define BFD_COMPRESS_ZSTD 0x400000 + + /* Don't generate ELF section header. */ + #define BFD_NO_SECTION_HEADER 0x800000 + + /* Flags bits which are for BFD use only. */ + #define BFD_FLAGS_FOR_BFD_USE_MASK \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_LINKER_CREATED \ + | BFD_PLUGIN | BFD_TRADITIONAL_FORMAT | BFD_DETERMINISTIC_OUTPUT \ + | BFD_COMPRESS_GABI | BFD_CONVERT_ELF_COMMON | BFD_USE_ELF_STT_COMMON \ + | BFD_NO_SECTION_HEADER) + + /* The format which belongs to the BFD. (object, core, etc.) */ + ENUM_BITFIELD (bfd_format) format : 3; + + /* The direction with which the BFD was opened. */ + ENUM_BITFIELD (bfd_direction) direction : 2; + + /* POSIX.1-2017 (IEEE Std 1003.1) says of fopen : "When a file is + opened with update mode ('+' as the second or third character in + the mode argument), both input and output may be performed on + the associated stream. However, the application shall ensure + that output is not directly followed by input without an + intervening call to fflush() or to a file positioning function + (fseek(), fsetpos(), or rewind()), and input is not directly + followed by output without an intervening call to a file + positioning function, unless the input operation encounters + end-of-file." + This field tracks the last IO operation, so that bfd can insert + a seek when IO direction changes. */ + ENUM_BITFIELD (bfd_last_io) last_io : 2; + + /* Is the file descriptor being cached? That is, can it be closed as + needed, and re-opened when accessed later? */ + unsigned int cacheable : 1; + + /* Marks whether there was a default target specified when the + BFD was opened. This is used to select which matching algorithm + to use to choose the back end. */ + unsigned int target_defaulted : 1; + + /* ... and here: (``once'' means at least once). */ + unsigned int opened_once : 1; + + /* Set if we have a locally maintained mtime value, rather than + getting it from the file each time. */ + unsigned int mtime_set : 1; + + /* Flag set if symbols from this BFD should not be exported. */ + unsigned int no_export : 1; + + /* Remember when output has begun, to stop strange things + from happening. */ + unsigned int output_has_begun : 1; + + /* Have archive map. */ + unsigned int has_armap : 1; + + /* Set if this is a thin archive. */ + unsigned int is_thin_archive : 1; + + /* Set if this archive should not cache element positions. */ + unsigned int no_element_cache : 1; + + /* Set if only required symbols should be added in the link hash table for + this object. Used by VMS linkers. */ + unsigned int selective_search : 1; + + /* Set if this is the linker output BFD. */ + unsigned int is_linker_output : 1; + + /* Set if this is the linker input BFD. */ + unsigned int is_linker_input : 1; + + /* If this is an input for a compiler plug-in library. */ + ENUM_BITFIELD (bfd_plugin_format) plugin_format : 2; + + /* Set if this is a plugin output file. */ + unsigned int lto_output : 1; + + /* Do not attempt to modify this file. Set when detecting errors + that BFD is not prepared to handle for objcopy/strip. */ + unsigned int read_only : 1; + + /* LTO object type. */ + ENUM_BITFIELD (bfd_lto_object_type) lto_type : 2; + + /* Set if this BFD is currently being processed by + bfd_check_format_matches. This is checked by the cache to + avoid closing the BFD in this case. This should only be + examined or modified while the BFD lock is held. */ + unsigned int in_format_matches : 1; + + /* Set to dummy BFD created when claimed by a compiler plug-in + library. */ + bfd *plugin_dummy_bfd; + + /* The offset of this bfd in the file, typically 0 if it is not + contained in an archive. */ + ufile_ptr origin; + + /* The origin in the archive of the proxy entry. This will + normally be the same as origin, except for thin archives, + when it will contain the current offset of the proxy in the + thin archive rather than the offset of the bfd in its actual + container. */ + ufile_ptr proxy_origin; + + /* A hash table for section names. */ + struct bfd_hash_table section_htab; + + /* Pointer to linked list of sections. */ + struct bfd_section *sections; + + /* The last section on the section list. */ + struct bfd_section *section_last; + + /* The number of sections. */ + unsigned int section_count; + + /* The archive plugin file descriptor. */ + int archive_plugin_fd; + + /* The number of opens on the archive plugin file descriptor. */ + unsigned int archive_plugin_fd_open_count; + + /* A field used by _bfd_generic_link_add_archive_symbols. This will + be used only for archive elements. */ + int archive_pass; + + /* The total size of memory from bfd_alloc. */ + bfd_size_type alloc_size; + + /* Stuff only useful for object files: + The start address. */ + bfd_vma start_address; + + /* Symbol table for output BFD (with symcount entries). + Also used by the linker to cache input BFD symbols. */ + struct bfd_symbol **outsymbols; + + /* Used for input and output. */ + unsigned int symcount; + + /* Used for slurped dynamic symbol tables. */ + unsigned int dynsymcount; + + /* Pointer to structure which contains architecture information. */ + const struct bfd_arch_info *arch_info; + + /* Cached length of file for bfd_get_size. 0 until bfd_get_size is + called, 1 if stat returns an error or the file size is too large to + return in ufile_ptr. Both 0 and 1 should be treated as "unknown". */ + ufile_ptr size; + + /* Stuff only useful for archives. */ + void *arelt_data; + struct bfd *my_archive; /* The containing archive BFD. */ + struct bfd *archive_next; /* The next BFD in the archive. */ + struct bfd *archive_head; /* The first BFD in the archive. */ + struct bfd *nested_archives; /* List of nested archive in a flattened + thin archive. */ + + union { + /* For input BFDs, a chain of BFDs involved in a link. */ + struct bfd *next; + /* For output BFD, the linker hash table. */ + struct bfd_link_hash_table *hash; + } link; + + /* Used by the back end to hold private data. */ + union + { + struct aout_data_struct *aout_data; + struct artdata *aout_ar_data; + struct coff_tdata *coff_obj_data; + struct pe_tdata *pe_obj_data; + struct xcoff_tdata *xcoff_obj_data; + struct ecoff_tdata *ecoff_obj_data; + struct srec_data_struct *srec_data; + struct verilog_data_struct *verilog_data; + struct ihex_data_struct *ihex_data; + struct tekhex_data_struct *tekhex_data; + struct elf_obj_tdata *elf_obj_data; + struct mmo_data_struct *mmo_data; + struct trad_core_struct *trad_core_data; + struct som_data_struct *som_data; + struct hpux_core_struct *hpux_core_data; + struct hppabsd_core_struct *hppabsd_core_data; + struct sgi_core_struct *sgi_core_data; + struct lynx_core_struct *lynx_core_data; + struct osf_core_struct *osf_core_data; + struct cisco_core_struct *cisco_core_data; + struct netbsd_core_struct *netbsd_core_data; + struct mach_o_data_struct *mach_o_data; + struct mach_o_fat_data_struct *mach_o_fat_data; + struct plugin_data_struct *plugin_data; + struct bfd_pef_data_struct *pef_data; + struct bfd_pef_xlib_data_struct *pef_xlib_data; + struct bfd_sym_data_struct *sym_data; + void *any; + } + tdata; + + /* Used by the application to hold private data. */ + void *usrdata; + + /* Where all the allocated stuff under this BFD goes. This is a + struct objalloc *, but we use void * to avoid requiring the inclusion + of objalloc.h. */ + void *memory; + + /* For input BFDs, the build ID, if the object has one. */ + const struct bfd_build_id *build_id; + + /* For input BFDs, mmapped entries. */ + struct bfd_mmapped *mmapped; + }; + + + +File: bfd.info, Node: Error reporting, Next: Initialization, Prev: typedef bfd, Up: BFD front end + +2.2 Error reporting +=================== + +Most BFD functions return nonzero on success (check their individual +documentation for precise semantics). On an error, they call +'bfd_set_error' to set an error condition that callers can check by +calling 'bfd_get_error'. If that returns 'bfd_error_system_call', then +check 'errno'. + + The easiest way to report a BFD error to the user is to use +'bfd_perror'. + + The BFD error is thread-local. + +2.2.1 Type 'bfd_error_type' +--------------------------- + +The values returned by 'bfd_get_error' are defined by the enumerated +type 'bfd_error_type'. + + typedef enum bfd_error + { + bfd_error_no_error = 0, + bfd_error_system_call, + bfd_error_invalid_target, + bfd_error_wrong_format, + bfd_error_wrong_object_format, + bfd_error_invalid_operation, + bfd_error_no_memory, + bfd_error_no_symbols, + bfd_error_no_armap, + bfd_error_no_more_archived_files, + bfd_error_malformed_archive, + bfd_error_missing_dso, + bfd_error_file_not_recognized, + bfd_error_file_ambiguously_recognized, + bfd_error_no_contents, + bfd_error_nonrepresentable_section, + bfd_error_no_debug_section, + bfd_error_bad_value, + bfd_error_file_truncated, + bfd_error_file_too_big, + bfd_error_sorry, + bfd_error_on_input, + bfd_error_invalid_error_code + } + bfd_error_type; + + +2.2.1.1 'bfd_get_error' +....................... + + -- Function: bfd_error_type bfd_get_error (void); + Return the current BFD error condition. + +2.2.1.2 'bfd_set_error' +....................... + + -- Function: void bfd_set_error (bfd_error_type error_tag); + Set the BFD error condition to be ERROR_TAG. + + ERROR_TAG must not be bfd_error_on_input. Use bfd_set_input_error + for input errors instead. + +2.2.1.3 'bfd_set_input_error' +............................. + + -- Function: void bfd_set_input_error (bfd *input, bfd_error_type + error_tag); + Set the BFD error condition to be bfd_error_on_input. INPUT is the + input bfd where the error occurred, and ERROR_TAG the + bfd_error_type error. + +2.2.1.4 'bfd_errmsg' +.................... + + -- Function: const char *bfd_errmsg (bfd_error_type error_tag); + Return a string describing the error ERROR_TAG, or the system error + if ERROR_TAG is 'bfd_error_system_call'. + +2.2.1.5 'bfd_perror' +.................... + + -- Function: void bfd_perror (const char *message); + Print to the standard error stream a string describing the last BFD + error that occurred, or the last system error if the last BFD error + was a system call failure. If MESSAGE is non-NULL and non-empty, + the error string printed is preceded by MESSAGE, a colon, and a + space. It is followed by a newline. + +2.2.1.6 '_bfd_clear_error_data' +............................... + + -- Function: void _bfd_clear_error_data (void); + Free any data associated with the BFD error. + +2.2.1.7 'bfd_asprintf' +...................... + + -- Function: char *bfd_asprintf (const char *fmt, ...); + Primarily for error reporting, this function is like libiberty's + xasprintf except that it can return NULL on no memory and the + returned string should not be freed. Uses a thread-local malloc'd + buffer managed by libbfd, _bfd_error_buf. Be aware that a call to + this function frees the result of any previous call. bfd_errmsg + (bfd_error_on_input) also calls this function. + +2.2.2 BFD error handler +----------------------- + +Some BFD functions want to print messages describing the problem. They +call a BFD error handler function. This function may be overridden by +the program. + + The BFD error handler acts like vprintf. + + typedef void (*bfd_error_handler_type) (const char *, va_list); + + + typedef int (*bfd_print_callback) (void *, const char *, ...); + +2.2.2.1 'bfd_print_error' +......................... + + -- Function: void bfd_print_error (bfd_print_callback print_func, void + *stream, const char *fmt, va_list ap); + This formats FMT and AP according to BFD "printf" rules, sending + the output to STREAM by repeated calls to PRINT_FUNC. PRINT_FUNC is + a printf-like function; it does not need to implement the BFD + printf format extensions. This can be used in a callback that is + set via bfd_set_error_handler to turn the error into ordinary + output. + +2.2.2.2 '_bfd_error_handler' +............................ + + -- Function: void _bfd_error_handler (const char *fmt, ...) + ATTRIBUTE_PRINTF_1; + This is the default routine to handle BFD error messages. Like + fprintf (stderr, ...), but also handles some extra format + specifiers. + + %pA section name from section. For group components, prints group + name too. %pB file name from bfd. For archive components, prints + archive too. + + Beware: Only supports a maximum of 9 format arguments. + +2.2.2.3 'bfd_set_error_handler' +............................... + + -- Function: bfd_error_handler_type bfd_set_error_handler + (bfd_error_handler_type); + Set the BFD error handler function. Returns the previous function. + +2.2.2.4 '_bfd_set_error_handler_caching' +........................................ + + -- Function: struct per_xvec_messages *_bfd_set_error_handler_caching + (struct per_xvec_messages *); + Set the BFD error handler function to one that stores messages to + the per_xvec_messages object. Returns the previous object to which + messages are stored. Note that two sequential calls to this with a + non-NULL argument will cause output to be dropped, rather than + gathered. + +2.2.2.5 '_bfd_restore_error_handler_caching' +............................................ + + -- Function: void _bfd_restore_error_handler_caching (struct + per_xvec_messages *); + Reset the BFD error handler object to an earlier value. + +2.2.2.6 'bfd_set_error_program_name' +.................................... + + -- Function: void bfd_set_error_program_name (const char *); + Set the program name to use when printing a BFD error. This is + printed before the error message followed by a colon and space. + The string must not be changed after it is passed to this function. + +2.2.2.7 '_bfd_get_error_program_name' +..................................... + + -- Function: const char *_bfd_get_error_program_name (void); + Get the program name used when printing a BFD error. + +2.2.3 BFD assert handler +------------------------ + +If BFD finds an internal inconsistency, the bfd assert handler is called +with information on the BFD version, BFD source file and line. If this +happens, most programs linked against BFD are expected to want to exit +with an error, or mark the current BFD operation as failed, so it is +recommended to override the default handler, which just calls +_bfd_error_handler and continues. + + typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg, + const char *bfd_version, + const char *bfd_file, + int bfd_line); + + +2.2.3.1 'bfd_set_assert_handler' +................................ + + -- Function: bfd_assert_handler_type bfd_set_assert_handler + (bfd_assert_handler_type); + Set the BFD assert handler function. Returns the previous + function. + + +File: bfd.info, Node: Initialization, Next: Threading, Prev: Error reporting, Up: BFD front end + +2.2.3.2 'bfd_init' +.................. + + -- Function: unsigned int bfd_init (void); + This routine must be called before any other BFD function to + initialize magical internal data structures. Returns a magic + number, which may be used to check that the bfd library is + configured as expected by users. + /* Value returned by bfd_init. */ + #define BFD_INIT_MAGIC (sizeof (struct bfd_section)) + + + +File: bfd.info, Node: Threading, Next: Miscellaneous, Prev: Initialization, Up: BFD front end + +2.3 Threading +============= + +BFD has limited support for thread-safety. Most BFD globals are +protected by locks, while the error-related globals are thread-local. A +given BFD cannot safely be used from two threads at the same time; it is +up to the application to do any needed locking. However, it is ok for +different threads to work on different BFD objects at the same time. + +2.3.1 Thread functions. +----------------------- + + typedef bool (*bfd_lock_unlock_fn_type) (void *); + +2.3.1.1 '_bfd_threading_enabled' +................................ + + -- Function: bool _bfd_threading_enabled (void); + Return true if threading is enabled, false if not. + +2.3.1.2 'bfd_thread_init' +......................... + + -- Function: bool bfd_thread_init (bfd_lock_unlock_fn_type lock, + bfd_lock_unlock_fn_type unlock, void *data); + Initialize BFD threading. The functions passed in will be used to + lock and unlock global data structures. This may only be called a + single time in a given process. Returns true on success and false + on error. DATA is passed verbatim to the lock and unlock + functions. The lock and unlock functions should return true on + success, or set the BFD error and return false on failure. Note + also that the lock must be a recursive lock: BFD may attempt to + acquire the lock when it is already held by the current thread. + +2.3.1.3 'bfd_thread_cleanup' +............................ + + -- Function: void bfd_thread_cleanup (void); + Clean up any thread-local state. This should be called by a thread + that uses any BFD functions, before the thread exits. It is fine + to call this multiple times, or to call it and then later call BFD + functions on the same thread again. + +2.3.1.4 'bfd_lock' +.................. + + -- Function: bool bfd_lock (void); + Acquire the global BFD lock, if needed. Returns true on success, + false on error. + +2.3.1.5 'bfd_unlock' +.................... + + -- Function: bool bfd_unlock (void); + Release the global BFD lock, if needed. Returns true on success, + false on error. + + +File: bfd.info, Node: Miscellaneous, Next: Memory Usage, Prev: Threading, Up: BFD front end + +2.4 Miscellaneous +================= + +2.4.1 Miscellaneous functions +----------------------------- + +2.4.1.1 'bfd_get_reloc_upper_bound' +................................... + + -- Function: long bfd_get_reloc_upper_bound (bfd *abfd, asection + *sect); + Return the number of bytes required to store the relocation + information associated with section SECT attached to bfd ABFD. If + an error occurs, return -1. + +2.4.1.2 'bfd_canonicalize_reloc' +................................ + + -- Function: long bfd_canonicalize_reloc (bfd *abfd, asection *sec, + arelent **loc, asymbol **syms); + Call the back end associated with the open BFD ABFD and translate + the external form of the relocation information attached to SEC + into the internal canonical form. Place the table into memory at + LOC, which has been preallocated, usually by a call to + 'bfd_get_reloc_upper_bound'. Returns the number of relocs, or -1 + on error. + + The SYMS table is also needed for horrible internal magic reasons. + +2.4.1.3 'bfd_set_reloc' +....................... + + -- Function: void bfd_set_reloc (bfd *abfd, asection *sec, arelent + **rel, unsigned int count); + Set the relocation pointer and count within section SEC to the + values REL and COUNT. The argument ABFD is ignored. + #define bfd_set_reloc(abfd, asect, location, count) \ + BFD_SEND (abfd, _bfd_set_reloc, (abfd, asect, location, count)) + +2.4.1.4 'bfd_set_file_flags' +............................ + + -- Function: bool bfd_set_file_flags (bfd *abfd, flagword flags); + Set the flag word in the BFD ABFD to the value FLAGS. + + Possible errors are: + + * 'bfd_error_wrong_format' - The target bfd was not of object + format. + * 'bfd_error_invalid_operation' - The target bfd was open for + reading. + * 'bfd_error_invalid_operation' - The flag word contained a bit + which was not applicable to the type of file. E.g., an + attempt was made to set the 'D_PAGED' bit on a BFD format + which does not support demand paging. + +2.4.1.5 'bfd_get_arch_size' +........................... + + -- Function: int bfd_get_arch_size (bfd *abfd); + Returns the normalized architecture address size, in bits, as + determined by the object file's format. By normalized, we mean + either 32 or 64. For ELF, this information is included in the + header. Use bfd_arch_bits_per_address for number of bits in the + architecture address. + + Returns the arch size in bits if known, '-1' otherwise. + +2.4.1.6 'bfd_get_sign_extend_vma' +................................. + + -- Function: int bfd_get_sign_extend_vma (bfd *abfd); + Indicates if the target architecture "naturally" sign extends an + address. Some architectures implicitly sign extend address values + when they are converted to types larger than the size of an + address. For instance, bfd_get_start_address() will return an + address sign extended to fill a bfd_vma when this is the case. + + Returns '1' if the target architecture is known to sign extend + addresses, '0' if the target architecture is known to not sign + extend addresses, and '-1' otherwise. + +2.4.1.7 'bfd_set_start_address' +............................... + + -- Function: bool bfd_set_start_address (bfd *abfd, bfd_vma vma); + Make VMA the entry point of output BFD ABFD. + + Returns 'TRUE' on success, 'FALSE' otherwise. + +2.4.1.8 'bfd_get_gp_size' +......................... + + -- Function: unsigned int bfd_get_gp_size (bfd *abfd); + Return the maximum size of objects to be optimized using the GP + register under MIPS ECOFF. This is typically set by the '-G' + argument to the compiler, assembler or linker. + +2.4.1.9 'bfd_set_gp_size' +......................... + + -- Function: void bfd_set_gp_size (bfd *abfd, unsigned int i); + Set the maximum size of objects to be optimized using the GP + register under ECOFF or MIPS ELF. This is typically set by the '-G' + argument to the compiler, assembler or linker. + +2.4.1.10 'bfd_set_gp_value' +........................... + + -- Function: void bfd_set_gp_value (bfd *abfd, bfd_vma v); + Allow external access to the fucntion to set the GP value. This is + specifically added for gdb-compile support. + +2.4.1.11 'bfd_scan_vma' +....................... + + -- Function: bfd_vma bfd_scan_vma (const char *string, const char + **end, int base); + Convert, like 'strtoul' or 'stdtoull'depending on the size of a + 'bfd_vma', a numerical expression STRING into a 'bfd_vma' integer, + and return that integer. + +2.4.1.12 'bfd_copy_private_header_data' +....................................... + + -- Function: bool bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); + Copy private BFD header information from the BFD IBFD to the the + BFD OBFD. This copies information that may require sections to + exist, but does not require symbol tables. Return 'true' on + success, 'false' on error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OBFD. + #define bfd_copy_private_header_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_header_data, \ + (ibfd, obfd)) + +2.4.1.13 'bfd_copy_private_bfd_data' +.................................... + + -- Function: bool bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); + Copy private BFD information from the BFD IBFD to the the BFD OBFD. + Return 'TRUE' on success, 'FALSE' on error. Possible error returns + are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OBFD. + #define bfd_copy_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ + (ibfd, obfd)) + +2.4.1.14 'bfd_set_private_flags' +................................ + + -- Function: bool bfd_set_private_flags (bfd *abfd, flagword flags); + Set private BFD flag information in the BFD ABFD. Return 'TRUE' on + success, 'FALSE' on error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OBFD. + #define bfd_set_private_flags(abfd, flags) \ + BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) + +2.4.1.15 'Other functions' +.......................... + +The following functions exist but have not yet been documented. + #define bfd_sizeof_headers(abfd, info) \ + BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) + + #define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, syms, sec, off, file, func, line, NULL)) + + #define bfd_find_nearest_line_with_alt(abfd, alt_filename, sec, syms, off, \ + file, func, line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line_with_alt, \ + (abfd, alt_filename, syms, sec, off, file, func, line, disc)) + + #define bfd_find_nearest_line_discriminator(abfd, sec, syms, off, file, func, \ + line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, syms, sec, off, file, func, line, disc)) + + #define bfd_find_line(abfd, syms, sym, file, line) \ + BFD_SEND (abfd, _bfd_find_line, \ + (abfd, syms, sym, file, line)) + + #define bfd_find_inliner_info(abfd, file, func, line) \ + BFD_SEND (abfd, _bfd_find_inliner_info, \ + (abfd, file, func, line)) + + #define bfd_debug_info_start(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) + + #define bfd_debug_info_end(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) + + #define bfd_debug_info_accumulate(abfd, section) \ + BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) + + #define bfd_stat_arch_elt(abfd, stat) \ + BFD_SEND (abfd->my_archive ? abfd->my_archive : abfd, \ + _bfd_stat_arch_elt, (abfd, stat)) + + #define bfd_update_armap_timestamp(abfd) \ + BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) + + #define bfd_set_arch_mach(abfd, arch, mach)\ + BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) + + #define bfd_relax_section(abfd, section, link_info, again) \ + BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) + + #define bfd_gc_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) + + #define bfd_lookup_section_flags(link_info, flag_info, section) \ + BFD_SEND (abfd, _bfd_lookup_section_flags, (link_info, flag_info, section)) + + #define bfd_merge_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) + + #define bfd_is_group_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) + + #define bfd_group_name(abfd, sec) \ + BFD_SEND (abfd, _bfd_group_name, (abfd, sec)) + + #define bfd_discard_group(abfd, sec) \ + BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) + + #define bfd_link_hash_table_create(abfd) \ + BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) + + #define bfd_link_add_symbols(abfd, info) \ + BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) + + #define bfd_link_just_syms(abfd, sec, info) \ + BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) + + #define bfd_final_link(abfd, info) \ + BFD_SEND (abfd, _bfd_final_link, (abfd, info)) + + #define bfd_free_cached_info(abfd) \ + BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) + + #define bfd_get_dynamic_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) + + #define bfd_print_private_bfd_data(abfd, file)\ + BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) + + #define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) + + #define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ + BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ + dyncount, dynsyms, ret)) + + #define bfd_get_dynamic_reloc_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) + + #define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) + + +2.4.1.16 'bfd_get_relocated_section_contents' +............................................. + + -- Function: bfd_byte *bfd_get_relocated_section_contents (bfd *, + struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, + bool, asymbol **); + Read and relocate the indirect link_order section, into DATA (if + non-NULL) or to a malloc'd buffer. Return the buffer, or NULL on + errors. + +2.4.1.17 'bfd_record_phdr' +.......................... + + -- Function: bool bfd_record_phdr (bfd *, unsigned long, bool, + flagword, bool, bfd_vma, bool, bool, unsigned int, struct + bfd_section **); + Record information about an ELF program header. + +2.4.1.18 'bfd_sprintf_vma' +.......................... + + -- Function: void bfd_sprintf_vma (bfd *, char *, bfd_vma); void + bfd_fprintf_vma (bfd *, void *, bfd_vma); + bfd_sprintf_vma and bfd_fprintf_vma display an address in the + target's address size. + +2.4.1.19 'bfd_alt_mach_code' +............................ + + -- Function: bool bfd_alt_mach_code (bfd *abfd, int alternative); + When more than one machine code number is available for the same + machine type, this function can be used to switch between the + preferred one (alternative == 0) and any others. Currently, only + ELF supports this feature, with up to two alternate machine codes. + +2.4.1.20 'bfd_emul_get_maxpagesize' +................................... + + -- Function: bfd_vma bfd_emul_get_maxpagesize (const char *); + Returns the maximum page size, in bytes, as determined by + emulation. + +2.4.1.21 'bfd_emul_get_commonpagesize' +...................................... + + -- Function: bfd_vma bfd_emul_get_commonpagesize (const char *); + Returns the common page size, in bytes, as determined by emulation. + +2.4.1.22 'bfd_demangle' +....................... + + -- Function: char *bfd_demangle (bfd *, const char *, int); + Wrapper around cplus_demangle. Strips leading underscores and + other such chars that would otherwise confuse the demangler. If + passed a g++ v3 ABI mangled name, returns a buffer allocated with + malloc holding the demangled name. Returns NULL otherwise and on + memory alloc failure. + +2.4.1.23 'struct bfd_iovec' +........................... + +The 'struct bfd_iovec' contains the internal file I/O class. Each 'BFD' +has an instance of this class and all file I/O is routed through it (it +is assumed that the instance implements all methods listed below). + struct bfd_iovec + { + /* To avoid problems with macros, a "b" rather than "f" + prefix is prepended to each method name. */ + /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching + bytes starting at PTR. Return the number of bytes actually + transfered (a read past end-of-file returns less than NBYTES), + or -1 (setting bfd_error) if an error occurs. */ + file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); + file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, + file_ptr nbytes); + /* Return the current IOSTREAM file offset, or -1 (setting bfd_error + if an error occurs. */ + file_ptr (*btell) (struct bfd *abfd); + /* For the following, on successful completion a value of 0 is returned. + Otherwise, a value of -1 is returned (and bfd_error is set). */ + int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); + int (*bclose) (struct bfd *abfd); + int (*bflush) (struct bfd *abfd); + int (*bstat) (struct bfd *abfd, struct stat *sb); + /* Mmap a part of the files. ADDR, LEN, PROT, FLAGS and OFFSET are the usual + mmap parameter, except that LEN and OFFSET do not need to be page + aligned. Returns (void *)-1 on failure, mmapped address on success. + Also write in MAP_ADDR the address of the page aligned buffer and in + MAP_LEN the size mapped (a page multiple). Use unmap with MAP_ADDR and + MAP_LEN to unmap. */ + void *(*bmmap) (struct bfd *abfd, void *addr, size_t len, + int prot, int flags, file_ptr offset, + void **map_addr, size_t *map_len); + }; + extern const struct bfd_iovec _bfd_memory_iovec; + + +2.4.1.24 'bfd_read' +................... + + -- Function: bfd_size_type bfd_read (void *, bfd_size_type, bfd *) + ATTRIBUTE_WARN_UNUSED_RESULT; + Attempt to read SIZE bytes from ABFD's iostream to PTR. Return the + amount read. + +2.4.1.25 'bfd_write' +.................... + + -- Function: bfd_size_type bfd_write (const void *, bfd_size_type, bfd + *) ATTRIBUTE_WARN_UNUSED_RESULT; + Attempt to write SIZE bytes to ABFD's iostream from PTR. Return the + amount written. + +2.4.1.26 'bfd_tell' +................... + + -- Function: file_ptr bfd_tell (bfd *) ATTRIBUTE_WARN_UNUSED_RESULT; + Return ABFD's iostream file position. + +2.4.1.27 'bfd_flush' +.................... + + -- Function: int bfd_flush (bfd *); + Flush ABFD's iostream pending IO. + +2.4.1.28 'bfd_stat' +................... + + -- Function: int bfd_stat (bfd *, struct stat *) + ATTRIBUTE_WARN_UNUSED_RESULT; + Call fstat on ABFD's iostream. Return 0 on success, and a negative + value on failure. + +2.4.1.29 'bfd_seek' +................... + + -- Function: int bfd_seek (bfd *, file_ptr, int) + ATTRIBUTE_WARN_UNUSED_RESULT; + Call fseek on ABFD's iostream. Return 0 on success, and a negative + value on failure. + +2.4.1.30 'bfd_get_mtime' +........................ + + -- Function: long bfd_get_mtime (bfd *abfd); + Return the file modification time (as read from the file system, or + from the archive header for archive members). + +2.4.1.31 'bfd_get_size' +....................... + + -- Function: ufile_ptr bfd_get_size (bfd *abfd); + Return the file size (as read from file system) for the file + associated with BFD ABFD. + + The initial motivation for, and use of, this routine is not so we + can get the exact size of the object the BFD applies to, since that + might not be generally possible (archive members for example). It + would be ideal if someone could eventually modify it so that such + results were guaranteed. + + Instead, we want to ask questions like "is this NNN byte sized + object I'm about to try read from file offset YYY reasonable?" As + as example of where we might do this, some object formats use + string tables for which the first 'sizeof (long)' bytes of the + table contain the size of the table itself, including the size + bytes. If an application tries to read what it thinks is one of + these string tables, without some way to validate the size, and for + some reason the size is wrong (byte swapping error, wrong location + for the string table, etc.), the only clue is likely to be a read + error when it tries to read the table, or a "virtual memory + exhausted" error when it tries to allocate 15 bazillon bytes of + space for the 15 bazillon byte table it is about to read. This + function at least allows us to answer the question, "is the size + reasonable?". + + A return value of zero indicates the file size is unknown. + +2.4.1.32 'bfd_get_file_size' +............................ + + -- Function: ufile_ptr bfd_get_file_size (bfd *abfd); + Return the file size (as read from file system) for the file + associated with BFD ABFD. It supports both normal files and + archive elements. + +2.4.1.33 'bfd_mmap' +................... + + -- Function: void *bfd_mmap (bfd *abfd, void *addr, size_t len, int + prot, int flags, file_ptr offset, void **map_addr, size_t + *map_len) ATTRIBUTE_WARN_UNUSED_RESULT; + Return mmap()ed region of the file, if possible and implemented. + LEN and OFFSET do not need to be page aligned. The page aligned + address and length are written to MAP_ADDR and MAP_LEN. + +2.4.1.34 'bfd_get_current_time' +............................... + + -- Function: time_t bfd_get_current_time (time_t now); + Returns the current time. + + If the environment variable SOURCE_DATE_EPOCH is defined then this + is parsed and its value is returned. Otherwise if the paramter NOW + is non-zero, then that is returned. Otherwise the result of the + system call "time(NULL)" is returned. + + +File: bfd.info, Node: Memory Usage, Next: Sections, Prev: Miscellaneous, Up: BFD front end + +2.5 Memory Usage +================ + +BFD keeps all of its internal structures in obstacks. There is one +obstack per open BFD file, into which the current state is stored. When +a BFD is closed, the obstack is deleted, and so everything which has +been allocated by BFD for the closing file is thrown away. + + BFD does not free anything created by an application, but pointers +into 'bfd' structures become invalid on a 'bfd_close'; for example, +after a 'bfd_close' the vector passed to 'bfd_canonicalize_symtab' is +still around, since it has been allocated by the application, but the +data that it pointed to are lost. + + The general rule is to not close a BFD until all operations dependent +upon data from the BFD have been completed, or all the data from within +the file has been copied. To help with the management of memory, there +is a function ('bfd_alloc_size') which returns the number of bytes in +obstacks associated with the supplied BFD. This could be used to select +the greediest open BFD, close it to reclaim the memory, perform some +operation and reopen the BFD again, to get a fresh copy of the data +structures. + + +File: bfd.info, Node: Sections, Next: Symbols, Prev: Memory Usage, Up: BFD front end + +2.6 Sections +============ + +The raw data contained within a BFD is maintained through the section +abstraction. A single BFD may have any number of sections. It keeps +hold of them by pointing to the first; each one points to the next in +the list. + + Sections are supported in BFD in 'section.c'. + +* Menu: + +* Section Input:: +* Section Output:: +* typedef asection:: +* section prototypes:: + + +File: bfd.info, Node: Section Input, Next: Section Output, Prev: Sections, Up: Sections + +2.6.1 Section input +------------------- + +When a BFD is opened for reading, the section structures are created and +attached to the BFD. + + Each section has a name which describes the section in the outside +world--for example, 'a.out' would contain at least three sections, +called '.text', '.data' and '.bss'. + + Names need not be unique; for example a COFF file may have several +sections named '.data'. + + Sometimes a BFD will contain more than the "natural" number of +sections. A back end may attach other sections containing constructor +data, or an application may add a section (using 'bfd_make_section') to +the sections attached to an already open BFD. For example, the linker +creates an extra section 'COMMON' for each input file's BFD to hold +information about common storage. + + The raw data is not necessarily read in when the section descriptor +is created. Some targets may leave the data in place until a +'bfd_get_section_contents' call is made. Other back ends may read in +all the data at once. For example, an S-record file has to be read once +to determine the size of the data. + + +File: bfd.info, Node: Section Output, Next: typedef asection, Prev: Section Input, Up: Sections + +2.6.2 Section output +-------------------- + +To write a new object style BFD, the various sections to be written have +to be created. They are attached to the BFD in the same way as input +sections; data is written to the sections using +'bfd_set_section_contents'. + + Any program that creates or combines sections (e.g., the assembler +and linker) must use the 'asection' fields 'output_section' and +'output_offset' to indicate the file sections to which each section must +be written. (If the section is being created from scratch, +'output_section' should probably point to the section itself and +'output_offset' should probably be zero.) + + The data to be written comes from input sections attached (via +'output_section' pointers) to the output sections. The output section +structure can be considered a filter for the input section: the output +section determines the vma of the output data and the name, but the +input section determines the offset into the output section of the data +to be written. + + E.g., to create a section "O", starting at 0x100, 0x123 long, +containing two subsections, "A" at offset 0x0 (i.e., at vma 0x100) and +"B" at offset 0x20 (i.e., at vma 0x120) the 'asection' structures would +look like: + + section name "A" + output_offset 0x00 + size 0x20 + output_section -----------> section name "O" + | vma 0x100 + section name "B" | size 0x123 + output_offset 0x20 | + size 0x103 | + output_section --------| + +2.6.3 Link orders +----------------- + +The data within a section is stored in a "link_order". These are much +like the fixups in 'gas'. The link_order abstraction allows a section +to grow and shrink within itself. + + A link_order knows how big it is, and which is the next link_order +and where the raw data for it is; it also points to a list of +relocations which apply to it. + + The link_order is used by the linker to perform relaxing on final +code. The compiler creates code which is as big as necessary to make it +work without relaxing, and the user can select whether to relax. +Sometimes relaxing takes a lot of time. The linker runs around the +relocations to see if any are attached to data which can be shrunk, if +so it does it on a link_order by link_order basis. + + +File: bfd.info, Node: typedef asection, Next: section prototypes, Prev: Section Output, Up: Sections + +2.6.4 typedef asection +---------------------- + +Here is the section structure: + + typedef struct bfd_section + { + /* The name of the section; the name isn't a copy, the pointer is + the same as that passed to bfd_make_section. */ + const char *name; + + /* The next section in the list belonging to the BFD, or NULL. */ + struct bfd_section *next; + + /* The previous section in the list belonging to the BFD, or NULL. */ + struct bfd_section *prev; + + /* A unique sequence number. */ + unsigned int id; + + /* A unique section number which can be used by assembler to + distinguish different sections with the same section name. */ + unsigned int section_id; + + /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ + unsigned int index; + + /* The field flags contains attributes of the section. Some + flags are read in from the object file, and some are + synthesized from other information. */ + flagword flags; + + #define SEC_NO_FLAGS 0x0 + + /* Tells the OS to allocate space for this section when loading. + This is clear for a section containing debug information only. */ + #define SEC_ALLOC 0x1 + + /* Tells the OS to load the section from the file when loading. + This is clear for a .bss section. */ + #define SEC_LOAD 0x2 + + /* The section contains data still to be relocated, so there is + some relocation information too. */ + #define SEC_RELOC 0x4 + + /* A signal to the OS that the section contains read only data. */ + #define SEC_READONLY 0x8 + + /* The section contains code only. */ + #define SEC_CODE 0x10 + + /* The section contains data only. */ + #define SEC_DATA 0x20 + + /* The section will reside in ROM. */ + #define SEC_ROM 0x40 + + /* The section contains constructor information. This section + type is used by the linker to create lists of constructors and + destructors used by g++. When a back end sees a symbol + which should be used in a constructor list, it creates a new + section for the type of name (e.g., __CTOR_LIST__), attaches + the symbol to it, and builds a relocation. To build the lists + of constructors, all the linker has to do is catenate all the + sections called __CTOR_LIST__ and relocate the data + contained within - exactly the operations it would peform on + standard data. */ + #define SEC_CONSTRUCTOR 0x80 + + /* The section has contents - a data section could be + SEC_ALLOC | SEC_HAS_CONTENTS; a debug section could be + SEC_HAS_CONTENTS */ + #define SEC_HAS_CONTENTS 0x100 + + /* An instruction to the linker to not output the section + even if it has information which would normally be written. */ + #define SEC_NEVER_LOAD 0x200 + + /* The section contains thread local data. */ + #define SEC_THREAD_LOCAL 0x400 + + /* The section's size is fixed. Generic linker code will not + recalculate it and it is up to whoever has set this flag to + get the size right. */ + #define SEC_FIXED_SIZE 0x800 + + /* The section contains common symbols (symbols may be defined + multiple times, the value of a symbol is the amount of + space it requires, and the largest symbol value is the one + used). Most targets have exactly one of these (which we + translate to bfd_com_section_ptr), but ECOFF has two. */ + #define SEC_IS_COMMON 0x1000 + + /* The section contains only debugging information. For + example, this is set for ELF .debug and .stab sections. + strip tests this flag to see if a section can be + discarded. */ + #define SEC_DEBUGGING 0x2000 + + /* The contents of this section are held in memory pointed to + by the contents field. This is checked by bfd_get_section_contents, + and the data is retrieved from memory if appropriate. */ + #define SEC_IN_MEMORY 0x4000 + + /* The contents of this section are to be excluded by the + linker for executable and shared objects unless those + objects are to be further relocated. */ + #define SEC_EXCLUDE 0x8000 + + /* The contents of this section are to be sorted based on the sum of + the symbol and addend values specified by the associated relocation + entries. Entries without associated relocation entries will be + appended to the end of the section in an unspecified order. */ + #define SEC_SORT_ENTRIES 0x10000 + + /* When linking, duplicate sections of the same name should be + discarded, rather than being combined into a single section as + is usually done. This is similar to how common symbols are + handled. See SEC_LINK_DUPLICATES below. */ + #define SEC_LINK_ONCE 0x20000 + + /* If SEC_LINK_ONCE is set, this bitfield describes how the linker + should handle duplicate sections. */ + #define SEC_LINK_DUPLICATES 0xc0000 + + /* This value for SEC_LINK_DUPLICATES means that duplicate + sections with the same name should simply be discarded. */ + #define SEC_LINK_DUPLICATES_DISCARD 0x0 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if there are any duplicate sections, although + it should still only link one copy. */ + #define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections are a different size. */ + #define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections contain different + contents. */ + #define SEC_LINK_DUPLICATES_SAME_CONTENTS \ + (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE) + + /* This section was created by the linker as part of dynamic + relocation or other arcane processing. It is skipped when + going through the first-pass output, trusting that someone + else up the line will take care of it later. */ + #define SEC_LINKER_CREATED 0x100000 + + /* This section contains a section ID to distinguish different + sections with the same section name. */ + #define SEC_ASSEMBLER_SECTION_ID 0x100000 + + /* This section should not be subject to garbage collection. + Also set to inform the linker that this section should not be + listed in the link map as discarded. */ + #define SEC_KEEP 0x200000 + + /* This section contains "short" data, and should be placed + "near" the GP. */ + #define SEC_SMALL_DATA 0x400000 + + /* Attempt to merge identical entities in the section. + Entity size is given in the entsize field. */ + #define SEC_MERGE 0x800000 + + /* If given with SEC_MERGE, entities to merge are zero terminated + strings where entsize specifies character size instead of fixed + size entries. */ + #define SEC_STRINGS 0x1000000 + + /* This section contains data about section groups. */ + #define SEC_GROUP 0x2000000 + + /* The section is a COFF shared library section. This flag is + only for the linker. If this type of section appears in + the input file, the linker must copy it to the output file + without changing the vma or size. FIXME: Although this + was originally intended to be general, it really is COFF + specific (and the flag was renamed to indicate this). It + might be cleaner to have some more general mechanism to + allow the back end to control what the linker does with + sections. */ + #define SEC_COFF_SHARED_LIBRARY 0x4000000 + + /* This input section should be copied to output in reverse order + as an array of pointers. This is for ELF linker internal use + only. */ + #define SEC_ELF_REVERSE_COPY 0x4000000 + + /* This section contains data which may be shared with other + executables or shared objects. This is for COFF only. */ + #define SEC_COFF_SHARED 0x8000000 + + /* Indicate that section has the purecode flag set. */ + #define SEC_ELF_PURECODE 0x8000000 + + /* When a section with this flag is being linked, then if the size of + the input section is less than a page, it should not cross a page + boundary. If the size of the input section is one page or more, + it should be aligned on a page boundary. This is for TI + TMS320C54X only. */ + #define SEC_TIC54X_BLOCK 0x10000000 + + /* This section has the SHF_X86_64_LARGE flag. This is ELF x86-64 only. */ + #define SEC_ELF_LARGE 0x10000000 + + /* Conditionally link this section; do not link if there are no + references found to any symbol in the section. This is for TI + TMS320C54X only. */ + #define SEC_TIC54X_CLINK 0x20000000 + + /* This section contains vliw code. This is for Toshiba MeP only. */ + #define SEC_MEP_VLIW 0x20000000 + + /* All symbols, sizes and relocations in this section are octets + instead of bytes. Required for DWARF debug sections as DWARF + information is organized in octets, not bytes. */ + #define SEC_ELF_OCTETS 0x40000000 + + /* Indicate that section has the no read flag set. This happens + when memory read flag isn't set. */ + #define SEC_COFF_NOREAD 0x40000000 + + /* End of section flags. */ + + /* Some internal packed boolean fields. */ + + /* See the vma field. */ + unsigned int user_set_vma : 1; + + /* A mark flag used by some of the linker backends. */ + unsigned int linker_mark : 1; + + /* Another mark flag used by some of the linker backends. Set for + output sections that have an input section. */ + unsigned int linker_has_input : 1; + + /* Mark flag used by some linker backends for garbage collection. */ + unsigned int gc_mark : 1; + + /* Section compression status. */ + unsigned int compress_status : 2; + #define COMPRESS_SECTION_NONE 0 + #define COMPRESS_SECTION_DONE 1 + #define DECOMPRESS_SECTION_ZLIB 2 + #define DECOMPRESS_SECTION_ZSTD 3 + + /* The following flags are used by the ELF linker. */ + + /* Mark sections which have been allocated to segments. */ + unsigned int segment_mark : 1; + + /* Type of sec_info information. */ + unsigned int sec_info_type:3; + #define SEC_INFO_TYPE_NONE 0 + #define SEC_INFO_TYPE_STABS 1 + #define SEC_INFO_TYPE_MERGE 2 + #define SEC_INFO_TYPE_EH_FRAME 3 + #define SEC_INFO_TYPE_JUST_SYMS 4 + #define SEC_INFO_TYPE_TARGET 5 + #define SEC_INFO_TYPE_EH_FRAME_ENTRY 6 + #define SEC_INFO_TYPE_SFRAME 7 + + /* Nonzero if this section uses RELA relocations, rather than REL. */ + unsigned int use_rela_p:1; + + /* Nonzero if this section contents are mmapped, rather than malloced. */ + unsigned int mmapped_p:1; + + /* Bits used by various backends. The generic code doesn't touch + these fields. */ + + unsigned int sec_flg0:1; + unsigned int sec_flg1:1; + unsigned int sec_flg2:1; + unsigned int sec_flg3:1; + unsigned int sec_flg4:1; + unsigned int sec_flg5:1; + + /* End of internal packed boolean fields. */ + + /* The virtual memory address of the section - where it will be + at run time. The symbols are relocated against this. The + user_set_vma flag is maintained by bfd; if it's not set, the + backend can assign addresses (for example, in a.out, where + the default address for .data is dependent on the specific + target and various flags). */ + bfd_vma vma; + + /* The load address of the section - where it would be in a + rom image; really only used for writing section header + information. */ + bfd_vma lma; + + /* The size of the section in *octets*, as it will be output. + Contains a value even if the section has no contents (e.g., the + size of .bss). */ + bfd_size_type size; + + /* For input sections, the original size on disk of the section, in + octets. This field should be set for any section whose size is + changed by linker relaxation. It is required for sections where + the linker relaxation scheme doesn't cache altered section and + reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing + targets), and thus the original size needs to be kept to read the + section multiple times. For output sections, rawsize holds the + section size calculated on a previous linker relaxation pass. */ + bfd_size_type rawsize; + + /* The compressed size of the section in octets. */ + bfd_size_type compressed_size; + + /* If this section is going to be output, then this value is the + offset in *bytes* into the output section of the first byte in the + input section (byte ==> smallest addressable unit on the + target). In most cases, if this was going to start at the + 100th octet (8-bit quantity) in the output section, this value + would be 100. However, if the target byte size is 16 bits + (bfd_octets_per_byte is "2"), this value would be 50. */ + bfd_vma output_offset; + + /* The output section through which to map on output. */ + struct bfd_section *output_section; + + /* If an input section, a pointer to a vector of relocation + records for the data in this section. */ + struct reloc_cache_entry *relocation; + + /* If an output section, a pointer to a vector of pointers to + relocation records for the data in this section. */ + struct reloc_cache_entry **orelocation; + + /* The number of relocation records in one of the above. */ + unsigned reloc_count; + + /* The alignment requirement of the section, as an exponent of 2 - + e.g., 3 aligns to 2^3 (or 8). */ + unsigned int alignment_power; + + /* Information below is back end specific - and not always used + or updated. */ + + /* File position of section data. */ + file_ptr filepos; + + /* File position of relocation info. */ + file_ptr rel_filepos; + + /* File position of line data. */ + file_ptr line_filepos; + + /* Pointer to data for applications. */ + void *userdata; + + /* If the SEC_IN_MEMORY flag is set, this points to the actual + contents. */ + bfd_byte *contents; + + /* Attached line number information. */ + alent *lineno; + + /* Number of line number records. */ + unsigned int lineno_count; + + /* Entity size for merging purposes. */ + unsigned int entsize; + + /* Points to the kept section if this section is a link-once section, + and is discarded. */ + struct bfd_section *kept_section; + + /* When a section is being output, this value changes as more + linenumbers are written out. */ + file_ptr moving_line_filepos; + + /* What the section number is in the target world. */ + int target_index; + + void *used_by_bfd; + + /* If this is a constructor section then here is a list of the + relocations created to relocate items within it. */ + struct relent_chain *constructor_chain; + + /* The BFD which owns the section. */ + bfd *owner; + + /* A symbol which points at this section only. */ + struct bfd_symbol *symbol; + + /* Early in the link process, map_head and map_tail are used to build + a list of input sections attached to an output section. Later, + output sections use these fields for a list of bfd_link_order + structs. The linked_to_symbol_name field is for ELF assembler + internal use. */ + union { + struct bfd_link_order *link_order; + struct bfd_section *s; + const char *linked_to_symbol_name; + } map_head, map_tail; + + /* Points to the output section this section is already assigned to, + if any. This is used when support for non-contiguous memory + regions is enabled. */ + struct bfd_section *already_assigned; + + /* Explicitly specified section type, if non-zero. */ + unsigned int type; + + } asection; + + + +File: bfd.info, Node: section prototypes, Prev: typedef asection, Up: Sections + +2.6.5 Section prototypes +------------------------ + +These are the functions exported by the section handling part of BFD. + +2.6.5.1 'bfd_section_list_clear' +................................ + + -- Function: void bfd_section_list_clear (bfd *); + Clears the section list, and also resets the section count and hash + table entries. + +2.6.5.2 'bfd_get_section_by_name' +................................. + + -- Function: asection *bfd_get_section_by_name (bfd *abfd, const char + *name); + Return the most recently created section attached to ABFD named + NAME. Return NULL if no such section exists. + +2.6.5.3 'bfd_get_next_section_by_name' +...................................... + + -- Function: asection *bfd_get_next_section_by_name (bfd *ibfd, + asection *sec); + Given SEC is a section returned by 'bfd_get_section_by_name', + return the next most recently created section attached to the same + BFD with the same name, or if no such section exists in the same + BFD and IBFD is non-NULL, the next section with the same name in + any input BFD following IBFD. Return NULL on finding no section. + +2.6.5.4 'bfd_get_linker_section' +................................ + + -- Function: asection *bfd_get_linker_section (bfd *abfd, const char + *name); + Return the linker created section attached to ABFD named NAME. + Return NULL if no such section exists. + +2.6.5.5 'bfd_get_section_by_name_if' +.................................... + + -- Function: asection *bfd_get_section_by_name_if (bfd *abfd, const + char *name, bool (*func) (bfd *abfd, asection *sect, void + *obj), void *obj); + Call the provided function FUNC for each section attached to the + BFD ABFD whose name matches NAME, passing OBJ as an argument. The + function will be called as if by + + func (abfd, the_section, obj); + + It returns the first section for which FUNC returns true, otherwise + 'NULL'. + +2.6.5.6 'bfd_get_unique_section_name' +..................................... + + -- Function: char *bfd_get_unique_section_name (bfd *abfd, const char + *templat, int *count); + Invent a section name that is unique in ABFD by tacking a dot and a + digit suffix onto the original TEMPLAT. If COUNT is non-NULL, then + it specifies the first number tried as a suffix to generate a + unique name. The value pointed to by COUNT will be incremented in + this case. + +2.6.5.7 'bfd_make_section_old_way' +.................................. + + -- Function: asection *bfd_make_section_old_way (bfd *abfd, const char + *name); + Create a new empty section called NAME and attach it to the end of + the chain of sections for the BFD ABFD. An attempt to create a + section with a name which is already in use returns its pointer + without changing the section chain. + + It has the funny name since this is the way it used to be before it + was rewritten.... + + Possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started + for this BFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.8 'bfd_make_section_anyway_with_flags' +............................................ + + -- Function: asection *bfd_make_section_anyway_with_flags (bfd *abfd, + const char *name, flagword flags); + Create a new empty section called NAME and attach it to the end of + the chain of sections for ABFD. Create a new section even if there + is already a section with that name. Also set the attributes of + the new section to the value FLAGS. + + Return 'NULL' and set 'bfd_error' on error; possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started + for ABFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.9 'bfd_make_section_anyway' +................................. + + -- Function: asection *bfd_make_section_anyway (bfd *abfd, const char + *name); + Create a new empty section called NAME and attach it to the end of + the chain of sections for ABFD. Create a new section even if there + is already a section with that name. + + Return 'NULL' and set 'bfd_error' on error; possible errors are: + + * 'bfd_error_invalid_operation' - If output has already started + for ABFD. + * 'bfd_error_no_memory' - If memory allocation fails. + +2.6.5.10 'bfd_make_section_with_flags' +...................................... + + -- Function: asection *bfd_make_section_with_flags (bfd *, const char + *name, flagword flags); + Like 'bfd_make_section_anyway', but return 'NULL' (without calling + bfd_set_error ()) without changing the section chain if there is + already a section named NAME. Also set the attributes of the new + section to the value FLAGS. If there is an error, return 'NULL' + and set 'bfd_error'. + +2.6.5.11 'bfd_make_section' +........................... + + -- Function: asection *bfd_make_section (bfd *, const char *name); + Like 'bfd_make_section_anyway', but return 'NULL' (without calling + bfd_set_error ()) without changing the section chain if there is + already a section named NAME. If there is an error, return 'NULL' + and set 'bfd_error'. + +2.6.5.12 'bfd_set_section_flags' +................................ + + -- Function: bool bfd_set_section_flags (asection *sec, flagword + flags); + Set the attributes of the section SEC to the value FLAGS. Return + 'TRUE' on success, 'FALSE' on error. Possible error returns are: + + * 'bfd_error_invalid_operation' - The section cannot have one or + more of the attributes requested. For example, a .bss section + in 'a.out' may not have the 'SEC_HAS_CONTENTS' field set. + +2.6.5.13 'bfd_rename_section' +............................. + + -- Function: void bfd_rename_section (asection *sec, const char + *newname); + Rename section SEC to NEWNAME. + +2.6.5.14 'bfd_map_over_sections' +................................ + + -- Function: void bfd_map_over_sections (bfd *abfd, void (*func) (bfd + *abfd, asection *sect, void *obj), void *obj); + Call the provided function FUNC for each section attached to the + BFD ABFD, passing OBJ as an argument. The function will be called + as if by + + func (abfd, the_section, obj); + + This is the preferred method for iterating over sections; an + alternative would be to use a loop: + + asection *p; + for (p = abfd->sections; p != NULL; p = p->next) + func (abfd, p, ...) + +2.6.5.15 'bfd_sections_find_if' +............................... + + -- Function: asection *bfd_sections_find_if (bfd *abfd, bool + (*operation) (bfd *abfd, asection *sect, void *obj), void + *obj); + Call the provided function OPERATION for each section attached to + the BFD ABFD, passing OBJ as an argument. The function will be + called as if by + + operation (abfd, the_section, obj); + + It returns the first section for which OPERATION returns true. + +2.6.5.16 'bfd_set_section_size' +............................... + + -- Function: bool bfd_set_section_size (asection *sec, bfd_size_type + val); + Set SEC to the size VAL. If the operation is ok, then 'TRUE' is + returned, else 'FALSE'. + + Possible error returns: + + * 'bfd_error_invalid_operation' - Writing has started to the + BFD, so setting the size is invalid. + +2.6.5.17 'bfd_set_section_contents' +................................... + + -- Function: bool bfd_set_section_contents (bfd *abfd, asection + *section, const void *data, file_ptr offset, bfd_size_type + count); + Sets the contents of the section SECTION in BFD ABFD to the data + starting in memory at LOCATION. The data is written to the output + section starting at offset OFFSET for COUNT octets. + + Normally 'TRUE' is returned, but 'FALSE' is returned if there was + an error. Possible error returns are: + + * 'bfd_error_no_contents' - The output section does not have the + 'SEC_HAS_CONTENTS' attribute, so nothing can be written to it. + * 'bfd_error_bad_value' - The section is unable to contain all + of the data. + * 'bfd_error_invalid_operation' - The BFD is not writeable. + * and some more too. + This routine is front end to the back end function + '_bfd_set_section_contents'. + +2.6.5.18 'bfd_get_section_contents' +................................... + + -- Function: bool bfd_get_section_contents (bfd *abfd, asection + *section, void *location, file_ptr offset, bfd_size_type + count); + Read data from SECTION in BFD ABFD into memory starting at + LOCATION. The data is read at an offset of OFFSET from the start + of the input section, and is read for COUNT bytes. + + If the contents of a constructor with the 'SEC_CONSTRUCTOR' flag + set are requested or if the section does not have the + 'SEC_HAS_CONTENTS' flag set, then the LOCATION is filled with + zeroes. If no errors occur, 'TRUE' is returned, else 'FALSE'. + +2.6.5.19 'bfd_malloc_and_get_section' +..................................... + + -- Function: bool bfd_malloc_and_get_section (bfd *abfd, asection + *section, bfd_byte **buf); + Read all data from SECTION in BFD ABFD into a buffer, *BUF, + malloc'd by this function. Return 'true' on success, 'false' on + failure in which case *BUF will be NULL. + +2.6.5.20 'bfd_copy_private_section_data' +........................................ + + -- Function: bool bfd_copy_private_section_data (bfd *ibfd, asection + *isec, bfd *obfd, asection *osec); + Copy private section information from ISEC in the BFD IBFD to the + section OSEC in the BFD OBFD. Return 'TRUE' on success, 'FALSE' on + error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OSEC. + #define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ + BFD_SEND (obfd, _bfd_copy_private_section_data, \ + (ibfd, isection, obfd, osection)) + +2.6.5.21 'bfd_generic_is_group_section' +....................................... + + -- Function: bool bfd_generic_is_group_section (bfd *, const asection + *sec); + Returns TRUE if SEC is a member of a group. + +2.6.5.22 'bfd_generic_group_name' +................................. + + -- Function: const char *bfd_generic_group_name (bfd *, const asection + *sec); + Returns group name if SEC is a member of a group. + +2.6.5.23 'bfd_generic_discard_group' +.................................... + + -- Function: bool bfd_generic_discard_group (bfd *abfd, asection + *group); + Remove all members of GROUP from the output. + +2.6.5.24 'bfd_section_size_insane' +.................................. + + -- Function: bool bfd_section_size_insane (bfd *abfd, asection *sec); + Returns true if the given section has a size that indicates it + cannot be read from file. Return false if the size is OK or* this + function can't say one way or the other. + + +File: bfd.info, Node: Symbols, Next: Archives, Prev: Sections, Up: BFD front end + +2.7 Symbols +=========== + +BFD tries to maintain as much symbol information as it can when it moves +information from file to file. BFD passes information to applications +though the 'asymbol' structure. When the application requests the +symbol table, BFD reads the table in the native form and translates +parts of it into the internal format. To maintain more than the +information passed to applications, some targets keep some information +"behind the scenes" in a structure only the particular back end knows +about. For example, the coff back end keeps the original symbol table +structure as well as the canonical structure when a BFD is read in. On +output, the coff back end can reconstruct the output symbol table so +that no information is lost, even information unique to coff which BFD +doesn't know or understand. If a coff symbol table were read, but were +written through an a.out back end, all the coff specific information +would be lost. The symbol table of a BFD is not necessarily read in +until a canonicalize request is made. Then the BFD back end fills in a +table provided by the application with pointers to the canonical +information. To output symbols, the application provides BFD with a +table of pointers to pointers to 'asymbol's. This allows applications +like the linker to output a symbol as it was read, since the "behind the +scenes" information will be still available. +* Menu: + +* Reading Symbols:: +* Writing Symbols:: +* Mini Symbols:: +* typedef asymbol:: +* symbol handling functions:: + + +File: bfd.info, Node: Reading Symbols, Next: Writing Symbols, Prev: Symbols, Up: Symbols + +2.7.1 Reading symbols +--------------------- + +There are two stages to reading a symbol table from a BFD: allocating +storage, and the actual reading process. This is an excerpt from an +application which reads the symbol table: + + long storage_needed; + asymbol **symbol_table; + long number_of_symbols; + long i; + + storage_needed = bfd_get_symtab_upper_bound (abfd); + + if (storage_needed < 0) + FAIL + + if (storage_needed == 0) + return; + + symbol_table = xmalloc (storage_needed); + ... + number_of_symbols = + bfd_canonicalize_symtab (abfd, symbol_table); + + if (number_of_symbols < 0) + FAIL + + for (i = 0; i < number_of_symbols; i++) + process_symbol (symbol_table[i]); + + All storage for the symbols themselves is in an objalloc connected to +the BFD; it is freed when the BFD is closed. + + +File: bfd.info, Node: Writing Symbols, Next: Mini Symbols, Prev: Reading Symbols, Up: Symbols + +2.7.2 Writing symbols +--------------------- + +Writing of a symbol table is automatic when a BFD open for writing is +closed. The application attaches a vector of pointers to pointers to +symbols to the BFD being written, and fills in the symbol count. The +close and cleanup code reads through the table provided and performs all +the necessary operations. The BFD output code must always be provided +with an "owned" symbol: one which has come from another BFD, or one +which has been created using 'bfd_make_empty_symbol'. Here is an +example showing the creation of a symbol table with only one element: + + #include "sysdep.h" + #include "bfd.h" + int main (void) + { + bfd *abfd; + asymbol *ptrs[2]; + asymbol *new; + + abfd = bfd_openw ("foo","a.out-sunos-big"); + bfd_set_format (abfd, bfd_object); + new = bfd_make_empty_symbol (abfd); + new->name = "dummy_symbol"; + new->section = bfd_make_section_old_way (abfd, ".text"); + new->flags = BSF_GLOBAL; + new->value = 0x12345; + + ptrs[0] = new; + ptrs[1] = 0; + + bfd_set_symtab (abfd, ptrs, 1); + bfd_close (abfd); + return 0; + } + + ./makesym + nm foo + 00012345 A dummy_symbol + + Many formats cannot represent arbitrary symbol information; for +instance, the 'a.out' object format does not allow an arbitrary number +of sections. A symbol pointing to a section which is not one of +'.text', '.data' or '.bss' cannot be described. + + +File: bfd.info, Node: Mini Symbols, Next: typedef asymbol, Prev: Writing Symbols, Up: Symbols + +2.7.3 Mini Symbols +------------------ + +Mini symbols provide read-only access to the symbol table. They use +less memory space, but require more time to access. They can be useful +for tools like nm or objdump, which may have to handle symbol tables of +extremely large executables. + + The 'bfd_read_minisymbols' function will read the symbols into memory +in an internal form. It will return a 'void *' pointer to a block of +memory, a symbol count, and the size of each symbol. The pointer is +allocated using 'malloc', and should be freed by the caller when it is +no longer needed. + + The function 'bfd_minisymbol_to_symbol' will take a pointer to a +minisymbol, and a pointer to a structure returned by +'bfd_make_empty_symbol', and return a 'asymbol' structure. The return +value may or may not be the same as the value from +'bfd_make_empty_symbol' which was passed in. + + +File: bfd.info, Node: typedef asymbol, Next: symbol handling functions, Prev: Mini Symbols, Up: Symbols + +2.7.4 typedef asymbol +--------------------- + +An 'asymbol' has the form: + + typedef struct bfd_symbol + { + /* A pointer to the BFD which owns the symbol. This information + is necessary so that a back end can work out what additional + information (invisible to the application writer) is carried + with the symbol. + + This field is *almost* redundant, since you can use section->owner + instead, except that some symbols point to the global sections + bfd_{abs,com,und}_section. This could be fixed by making + these globals be per-bfd (or per-target-flavor). FIXME. */ + struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */ + + /* The text of the symbol. The name is left alone, and not copied; the + application may not alter it. */ + const char *name; + + /* The value of the symbol. This really should be a union of a + numeric value with a pointer, since some flags indicate that + a pointer to another symbol is stored here. */ + symvalue value; + + /* Attributes of a symbol. */ + #define BSF_NO_FLAGS 0 + + /* The symbol has local scope; static in C. The value + is the offset into the section of the data. */ + #define BSF_LOCAL (1 << 0) + + /* The symbol has global scope; initialized data in C. The + value is the offset into the section of the data. */ + #define BSF_GLOBAL (1 << 1) + + /* The symbol has global scope and is exported. The value is + the offset into the section of the data. */ + #define BSF_EXPORT BSF_GLOBAL /* No real difference. */ + + /* A normal C symbol would be one of: + BSF_LOCAL, BSF_UNDEFINED or BSF_GLOBAL. */ + + /* The symbol is a debugging record. The value has an arbitrary + meaning, unless BSF_DEBUGGING_RELOC is also set. */ + #define BSF_DEBUGGING (1 << 2) + + /* The symbol denotes a function entry point. Used in ELF, + perhaps others someday. */ + #define BSF_FUNCTION (1 << 3) + + /* Used by the linker. */ + #define BSF_KEEP (1 << 5) + + /* An ELF common symbol. */ + #define BSF_ELF_COMMON (1 << 6) + + /* A weak global symbol, overridable without warnings by + a regular global symbol of the same name. */ + #define BSF_WEAK (1 << 7) + + /* This symbol was created to point to a section, e.g. ELF's + STT_SECTION symbols. */ + #define BSF_SECTION_SYM (1 << 8) + + /* The symbol used to be a common symbol, but now it is + allocated. */ + #define BSF_OLD_COMMON (1 << 9) + + /* In some files the type of a symbol sometimes alters its + location in an output file - ie in coff a ISFCN symbol + which is also C_EXT symbol appears where it was + declared and not at the end of a section. This bit is set + by the target BFD part to convey this information. */ + #define BSF_NOT_AT_END (1 << 10) + + /* Signal that the symbol is the label of constructor section. */ + #define BSF_CONSTRUCTOR (1 << 11) + + /* Signal that the symbol is a warning symbol. The name is a + warning. The name of the next symbol is the one to warn about; + if a reference is made to a symbol with the same name as the next + symbol, a warning is issued by the linker. */ + #define BSF_WARNING (1 << 12) + + /* Signal that the symbol is indirect. This symbol is an indirect + pointer to the symbol with the same name as the next symbol. */ + #define BSF_INDIRECT (1 << 13) + + /* BSF_FILE marks symbols that contain a file name. This is used + for ELF STT_FILE symbols. */ + #define BSF_FILE (1 << 14) + + /* Symbol is from dynamic linking information. */ + #define BSF_DYNAMIC (1 << 15) + + /* The symbol denotes a data object. Used in ELF, and perhaps + others someday. */ + #define BSF_OBJECT (1 << 16) + + /* This symbol is a debugging symbol. The value is the offset + into the section of the data. BSF_DEBUGGING should be set + as well. */ + #define BSF_DEBUGGING_RELOC (1 << 17) + + /* This symbol is thread local. Used in ELF. */ + #define BSF_THREAD_LOCAL (1 << 18) + + /* This symbol represents a complex relocation expression, + with the expression tree serialized in the symbol name. */ + #define BSF_RELC (1 << 19) + + /* This symbol represents a signed complex relocation expression, + with the expression tree serialized in the symbol name. */ + #define BSF_SRELC (1 << 20) + + /* This symbol was created by bfd_get_synthetic_symtab. */ + #define BSF_SYNTHETIC (1 << 21) + + /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT. + The dynamic linker will compute the value of this symbol by + calling the function that it points to. BSF_FUNCTION must + also be also set. */ + #define BSF_GNU_INDIRECT_FUNCTION (1 << 22) + /* This symbol is a globally unique data object. The dynamic linker + will make sure that in the entire process there is just one symbol + with this name and type in use. BSF_OBJECT must also be set. */ + #define BSF_GNU_UNIQUE (1 << 23) + + /* This section symbol should be included in the symbol table. */ + #define BSF_SECTION_SYM_USED (1 << 24) + + flagword flags; + + /* A pointer to the section to which this symbol is + relative. This will always be non NULL, there are special + sections for undefined and absolute symbols. */ + struct bfd_section *section; + + /* Back end special data. */ + union + { + void *p; + bfd_vma i; + } + udata; + } + asymbol; + + + +File: bfd.info, Node: symbol handling functions, Prev: typedef asymbol, Up: Symbols + +2.7.5 Symbol handling functions +------------------------------- + +2.7.5.1 'bfd_get_symtab_upper_bound' +.................................... + +Return the number of bytes required to store a vector of pointers to +'asymbols' for all the symbols in the BFD ABFD, including a terminal +NULL pointer. If there are no symbols in the BFD, then return 0. If an +error occurs, return -1. + #define bfd_get_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd)) + + +2.7.5.2 'bfd_is_local_label' +............................ + + -- Function: bool bfd_is_local_label (bfd *abfd, asymbol *sym); + Return TRUE if the given symbol SYM in the BFD ABFD is a compiler + generated local label, else return FALSE. + +2.7.5.3 'bfd_is_local_label_name' +................................. + + -- Function: bool bfd_is_local_label_name (bfd *abfd, const char + *name); + Return TRUE if a symbol with the name NAME in the BFD ABFD is a + compiler generated local label, else return FALSE. This just checks + whether the name has the form of a local label. + #define bfd_is_local_label_name(abfd, name) \ + BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name)) + + +2.7.5.4 'bfd_is_target_special_symbol' +...................................... + + -- Function: bool bfd_is_target_special_symbol (bfd *abfd, asymbol + *sym); + Return TRUE iff a symbol SYM in the BFD ABFD is something special + to the particular target represented by the BFD. Such symbols + should normally not be mentioned to the user. + #define bfd_is_target_special_symbol(abfd, sym) \ + BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) + + +2.7.5.5 'bfd_canonicalize_symtab' +................................. + +Read the symbols from the BFD ABFD, and fills in the vector LOCATION +with pointers to the symbols and a trailing NULL. Return the actual +number of symbol pointers, not including the NULL. + #define bfd_canonicalize_symtab(abfd, location) \ + BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location)) + + +2.7.5.6 'bfd_set_symtab' +........................ + + -- Function: bool bfd_set_symtab (bfd *abfd, asymbol **location, + unsigned int count); + Arrange that when the output BFD ABFD is closed, the table LOCATION + of COUNT pointers to symbols will be written. + +2.7.5.7 'bfd_print_symbol_vandf' +................................ + + -- Function: void bfd_print_symbol_vandf (bfd *abfd, void *file, + asymbol *symbol); + Print the value and flags of the SYMBOL supplied to the stream + FILE. + +2.7.5.8 'bfd_make_empty_symbol' +............................... + +Create a new 'asymbol' structure for the BFD ABFD and return a pointer +to it. + + This routine is necessary because each back end has private +information surrounding the 'asymbol'. Building your own 'asymbol' and +pointing to it will not create the private information, and will cause +problems later on. + #define bfd_make_empty_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) + + +2.7.5.9 '_bfd_generic_make_empty_symbol' +........................................ + + -- Function: asymbol *_bfd_generic_make_empty_symbol (bfd *); + Create a new 'asymbol' structure for the BFD ABFD and return a + pointer to it. Used by core file routines, binary back-end and + anywhere else where no private info is needed. + +2.7.5.10 'bfd_make_debug_symbol' +................................ + +Create a new 'asymbol' structure for the BFD ABFD, to be used as a +debugging symbol. + #define bfd_make_debug_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd)) + + +2.7.5.11 'bfd_decode_symclass' +.............................. + + -- Function: int bfd_decode_symclass (asymbol *symbol); + Return a character corresponding to the symbol class of SYMBOL, or + '?' for an unknown class. + +2.7.5.12 'bfd_is_undefined_symclass' +.................................... + + -- Function: bool bfd_is_undefined_symclass (int symclass); + Returns non-zero if the class symbol returned by + bfd_decode_symclass represents an undefined symbol. Returns zero + otherwise. + +2.7.5.13 'bfd_symbol_info' +.......................... + + -- Function: void bfd_symbol_info (asymbol *symbol, symbol_info *ret); + Fill in the basic info about symbol that nm needs. Additional info + may be added by the back-ends after calling this function. + +2.7.5.14 'bfd_copy_private_symbol_data' +....................................... + + -- Function: bool bfd_copy_private_symbol_data (bfd *ibfd, asymbol + *isym, bfd *obfd, asymbol *osym); + Copy private symbol information from ISYM in the BFD IBFD to the + symbol OSYM in the BFD OBFD. Return 'TRUE' on success, 'FALSE' on + error. Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OSEC. + #define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ + BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ + (ibfd, isymbol, obfd, osymbol)) + + + +File: bfd.info, Node: Archives, Next: Formats, Prev: Symbols, Up: BFD front end + +2.8 Archives +============ + +An archive (or library) is just another BFD. It has a symbol table, +although there's not much a user program will do with it. + + The big difference between an archive BFD and an ordinary BFD is that +the archive doesn't have sections. Instead it has a chain of BFDs that +are considered its contents. These BFDs can be manipulated like any +other. The BFDs contained in an archive opened for reading will all be +opened for reading. You may put either input or output BFDs into an +archive opened for output; they will be handled correctly when the +archive is closed. + + Use 'bfd_openr_next_archived_file' to step through the contents of an +archive opened for input. You don't have to read the entire archive if +you don't want to! Read it until you find what you want. + + A BFD returned by 'bfd_openr_next_archived_file' can be closed +manually with 'bfd_close'. If you do not close it, then a second +iteration through the members of an archive may return the same BFD. If +you close the archive BFD, then all the member BFDs will automatically +be closed as well. + + Archive contents of output BFDs are chained through the +'archive_next' pointer in a BFD. The first one is findable through the +'archive_head' slot of the archive. Set it with 'bfd_set_archive_head' +(q.v.). A given BFD may be in only one open output archive at a time. + + As expected, the BFD archive code is more general than the archive +code of any given environment. BFD archives may contain files of +different formats (e.g., a.out and coff) and even different +architectures. You may even place archives recursively into archives! + + This can cause unexpected confusion, since some archive formats are +more expressive than others. For instance, Intel COFF archives can +preserve long filenames; SunOS a.out archives cannot. If you move a +file from the first to the second format and back again, the filename +may be truncated. Likewise, different a.out environments have different +conventions as to how they truncate filenames, whether they preserve +directory names in filenames, etc. When interoperating with native +tools, be sure your files are homogeneous. + + Beware: most of these formats do not react well to the presence of +spaces in filenames. We do the best we can, but can't always handle +this case due to restrictions in the format of archives. Many Unix +utilities are braindead in regards to spaces and such in filenames +anyway, so this shouldn't be much of a restriction. + + Archives are supported in BFD in 'archive.c'. + +2.8.1 Archive functions +----------------------- + +2.8.1.1 'bfd_get_next_mapent' +............................. + + -- Function: symindex bfd_get_next_mapent (bfd *abfd, symindex + previous, carsym **sym); + Step through archive ABFD's symbol table (if it has one). + Successively update SYM with the next symbol's information, + returning that symbol's (internal) index into the symbol table. + + Supply 'BFD_NO_MORE_SYMBOLS' as the PREVIOUS entry to get the first + one; returns 'BFD_NO_MORE_SYMBOLS' when you've already got the last + one. + + A 'carsym' is a canonical archive symbol. The only user-visible + element is its name, a null-terminated string. + +2.8.1.2 'bfd_set_archive_head' +.............................. + + -- Function: bool bfd_set_archive_head (bfd *output, bfd *new_head); + Set the head of the chain of BFDs contained in the archive OUTPUT + to NEW_HEAD. + +2.8.1.3 'bfd_openr_next_archived_file' +...................................... + + -- Function: bfd *bfd_openr_next_archived_file (bfd *archive, bfd + *previous); + Provided a BFD, ARCHIVE, containing an archive and NULL, open an + input BFD on the first contained element and returns that. + Subsequent calls should pass the archive and the previous return + value to return a created BFD to the next contained element. NULL + is returned when there are no more. Note - if you want to process + the bfd returned by this call be sure to call bfd_check_format() on + it first. + + +File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end + +2.9 File formats +================ + +A format is a BFD concept of high level file contents type. The formats +supported by BFD are: + + * 'bfd_object' + The BFD may contain data, symbols, relocations and debug info. + + * 'bfd_archive' + The BFD contains other BFDs and an optional index. + + * 'bfd_core' + The BFD contains the result of an executable core dump. + +2.9.1 File format functions +--------------------------- + +2.9.1.1 'bfd_check_format' +.......................... + + -- Function: bool bfd_check_format (bfd *abfd, bfd_format format); + Verify if the file attached to the BFD ABFD is compatible with the + format FORMAT (i.e., one of 'bfd_object', 'bfd_archive' or + 'bfd_core'). + + If the BFD has been set to a specific target before the call, only + the named target and format combination is checked. If the target + has not been set, or has been set to 'default', then all the known + target backends is interrogated to determine a match. If the + default target matches, it is used. If not, exactly one target + must recognize the file, or an error results. + + The function returns 'TRUE' on success, otherwise 'FALSE' with one + of the following error codes: + + * 'bfd_error_invalid_operation' - if 'format' is not one of + 'bfd_object', 'bfd_archive' or 'bfd_core'. + + * 'bfd_error_system_call' - if an error occured during a read - + even some file mismatches can cause bfd_error_system_calls. + + * 'file_not_recognised' - none of the backends recognised the + file format. + + * 'bfd_error_file_ambiguously_recognized' - more than one + backend recognised the file format. + When calling bfd_check_format (or bfd_check_format_matches), any + underlying file descriptor will be kept open for the duration of + the call. This is done to avoid races when another thread calls + bfd_cache_close_all. In this scenario, the thread calling + bfd_check_format must call bfd_cache_close itself. + +2.9.1.2 'bfd_check_format_matches' +.................................. + + -- Function: bool bfd_check_format_matches (bfd *abfd, bfd_format + format, char ***matching); + Like 'bfd_check_format', except when it returns FALSE with + 'bfd_errno' set to 'bfd_error_file_ambiguously_recognized'. In + that case, if MATCHING is not NULL, it will be filled in with a + NULL-terminated list of the names of the formats that matched, + allocated with 'malloc'. Then the user may choose a format and try + again. + + When done with the list that MATCHING points to, the caller should + free it. + +2.9.1.3 'bfd_set_format' +........................ + + -- Function: bool bfd_set_format (bfd *abfd, bfd_format format); + This function sets the file format of the BFD ABFD to the format + FORMAT. If the target set in the BFD does not support the format + requested, the format is invalid, or the BFD is not open for + writing, then an error occurs. + +2.9.1.4 'bfd_format_string' +........................... + + -- Function: const char *bfd_format_string (bfd_format format); + Return a pointer to a const string 'invalid', 'object', 'archive', + 'core', or 'unknown', depending upon the value of FORMAT. + + +File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end + +2.10 Relocations +================ + +BFD maintains relocations in much the same way it maintains symbols: +they are left alone until required, then read in en-masse and translated +into an internal form. A common routine 'bfd_perform_relocation' acts +upon the canonical form to do the fixup. + + Relocations are maintained on a per section basis, while symbols are +maintained on a per BFD basis. + + All that a back end has to do to fit the BFD interface is to create a +'struct reloc_cache_entry' for each relocation in a particular section, +and fill in the right bits of the structures. + +* Menu: + +* typedef arelent:: +* howto manager:: + + +File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations + +2.10.1 typedef arelent +---------------------- + +This is the structure of a relocation entry: + + struct reloc_cache_entry + { + /* A pointer into the canonical table of pointers. */ + struct bfd_symbol **sym_ptr_ptr; + + /* offset in section. */ + bfd_size_type address; + + /* addend for relocation value. */ + bfd_vma addend; + + /* Pointer to how to perform the required relocation. */ + reloc_howto_type *howto; + + }; + + Here is a description of each of the fields within an 'arelent': + + * 'sym_ptr_ptr' + The symbol table pointer points to a pointer to the symbol associated +with the relocation request. It is the pointer into the table returned +by the back end's 'canonicalize_symtab' action. *Note Symbols::. The +symbol is referenced through a pointer to a pointer so that tools like +the linker can fix up all the symbols of the same name by modifying only +one pointer. The relocation routine looks in the symbol and uses the +base of the section the symbol is attached to and the value of the +symbol as the initial relocation offset. If the symbol pointer is zero, +then the section provided is looked up. + + * 'address' + The 'address' field gives the offset in bytes from the base of the +section data which owns the relocation record to the first byte of +relocatable information. The actual data relocated will be relative to +this point; for example, a relocation type which modifies the bottom two +bytes of a four byte word would not touch the first byte pointed to in a +big endian world. + + * 'addend' + The 'addend' is a value provided by the back end to be added (!) to +the relocation offset. Its interpretation is dependent upon the howto. +For example, on the 68k the code: + + char foo[]; + main() + { + return foo[0x12345678]; + } + + Could be compiled into: + + linkw fp,#-4 + moveb @#12345678,d0 + extbl d0 + unlk fp + rts + + This could create a reloc pointing to 'foo', but leave the offset in +the data, something like: + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000006 32 _foo + + 00000000 4e56 fffc ; linkw fp,#-4 + 00000004 1039 1234 5678 ; moveb @#12345678,d0 + 0000000a 49c0 ; extbl d0 + 0000000c 4e5e ; unlk fp + 0000000e 4e75 ; rts + + Using coff and an 88k, some instructions don't have enough space in +them to represent the full address range, and pointers have to be loaded +in two parts. So you'd get something like: + + or.u r13,r0,hi16(_foo+0x12345678) + ld.b r2,r13,lo16(_foo+0x12345678) + jmp r1 + + This should create two relocs, both pointing to '_foo', and with +0x12340000 in their addend field. The data would consist of: + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000002 HVRT16 _foo+0x12340000 + 00000006 LVRT16 _foo+0x12340000 + + 00000000 5da05678 ; or.u r13,r0,0x5678 + 00000004 1c4d5678 ; ld.b r2,r13,0x5678 + 00000008 f400c001 ; jmp r1 + + The relocation routine digs out the value from the data, adds it to +the addend to get the original offset, and then adds the value of +'_foo'. Note that all 32 bits have to be kept around somewhere, to cope +with carry from bit 15 to bit 16. + + One further example is the sparc and the a.out format. The sparc has +a similar problem to the 88k, in that some instructions don't have room +for an entire offset, but on the sparc the parts are created in odd +sized lumps. The designers of the a.out format chose to not use the +data within the section for storing part of the offset; all the offset +is kept within the reloc. Anything in the data should be ignored. + + save %sp,-112,%sp + sethi %hi(_foo+0x12345678),%g2 + ldsb [%g2+%lo(_foo+0x12345678)],%i0 + ret + restore + + Both relocs contain a pointer to 'foo', and the offsets contain junk. + + RELOCATION RECORDS FOR [.text]: + offset type value + 00000004 HI22 _foo+0x12345678 + 00000008 LO10 _foo+0x12345678 + + 00000000 9de3bf90 ; save %sp,-112,%sp + 00000004 05000000 ; sethi %hi(_foo+0),%g2 + 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 + 0000000c 81c7e008 ; ret + 00000010 81e80000 ; restore + + * 'howto' + The 'howto' field can be imagined as a relocation instruction. It is +a pointer to a structure which contains information on what to do with +all of the other information in the reloc record and data section. A +back end would normally have a relocation instruction set and turn +relocations into pointers to the correct structure on input - but it +would be possible to create each howto field on demand. + +2.10.1.1 'enum complain_overflow' +................................. + +Indicates what sort of overflow checking should be done when performing +a relocation. + + enum complain_overflow + { + /* Do not complain on overflow. */ + complain_overflow_dont, + + /* Complain if the value overflows when considered as a signed + number one bit larger than the field. ie. A bitfield of N bits + is allowed to represent -2**n to 2**n-1. */ + complain_overflow_bitfield, + + /* Complain if the value overflows when considered as a signed + number. */ + complain_overflow_signed, + + /* Complain if the value overflows when considered as an + unsigned number. */ + complain_overflow_unsigned + }; + + +2.10.1.2 'reloc_howto_type' +........................... + +The 'reloc_howto_type' is a structure which contains all the information +that libbfd needs to know to tie up a back end's data. + + struct reloc_howto_struct + { + /* The type field has mainly a documentary use - the back end can + do what it wants with it, though normally the back end's idea of + an external reloc number is stored in this field. */ + unsigned int type; + + /* The size of the item to be relocated in bytes. */ + unsigned int size:4; + + /* The number of bits in the field to be relocated. This is used + when doing overflow checking. */ + unsigned int bitsize:7; + + /* The value the final relocation is shifted right by. This drops + unwanted data from the relocation. */ + unsigned int rightshift:6; + + /* The bit position of the reloc value in the destination. + The relocated value is left shifted by this amount. */ + unsigned int bitpos:6; + + /* What type of overflow error should be checked for when + relocating. */ + ENUM_BITFIELD (complain_overflow) complain_on_overflow:2; + + /* The relocation value should be negated before applying. */ + unsigned int negate:1; + + /* The relocation is relative to the item being relocated. */ + unsigned int pc_relative:1; + + /* Some formats record a relocation addend in the section contents + rather than with the relocation. For ELF formats this is the + distinction between USE_REL and USE_RELA (though the code checks + for USE_REL == 1/0). The value of this field is TRUE if the + addend is recorded with the section contents; when performing a + partial link (ld -r) the section contents (the data) will be + modified. The value of this field is FALSE if addends are + recorded with the relocation (in arelent.addend); when performing + a partial link the relocation will be modified. + All relocations for all ELF USE_RELA targets should set this field + to FALSE (values of TRUE should be looked on with suspicion). + However, the converse is not true: not all relocations of all ELF + USE_REL targets set this field to TRUE. Why this is so is peculiar + to each particular target. For relocs that aren't used in partial + links (e.g. GOT stuff) it doesn't matter what this is set to. */ + unsigned int partial_inplace:1; + + /* When some formats create PC relative instructions, they leave + the value of the pc of the place being relocated in the offset + slot of the instruction, so that a PC relative relocation can + be made just by adding in an ordinary offset (e.g., sun3 a.out). + Some formats leave the displacement part of an instruction + empty (e.g., ELF); this flag signals the fact. */ + unsigned int pcrel_offset:1; + + /* Whether bfd_install_relocation should just install the addend, + or should follow the practice of some older object formats and + install a value including the symbol. */ + unsigned int install_addend:1; + + /* src_mask selects the part of the instruction (or data) to be used + in the relocation sum. If the target relocations don't have an + addend in the reloc, eg. ELF USE_REL, src_mask will normally equal + dst_mask to extract the addend from the section contents. If + relocations do have an addend in the reloc, eg. ELF USE_RELA, this + field should normally be zero. Non-zero values for ELF USE_RELA + targets should be viewed with suspicion as normally the value in + the dst_mask part of the section contents should be ignored. */ + bfd_vma src_mask; + + /* dst_mask selects which parts of the instruction (or data) are + replaced with a relocated value. */ + bfd_vma dst_mask; + + /* If this field is non null, then the supplied function is + called rather than the normal function. This allows really + strange relocation methods to be accommodated. */ + bfd_reloc_status_type (*special_function) + (bfd *, arelent *, struct bfd_symbol *, void *, asection *, + bfd *, char **); + + /* The textual name of the relocation type. */ + const char *name; + }; + + +2.10.1.3 'The HOWTO Macro' +.......................... + +The HOWTO macro fills in a reloc_howto_type (a typedef for const struct +reloc_howto_struct). + #define HOWTO_INSTALL_ADDEND 0 + #define HOWTO_RSIZE(sz) ((sz) < 0 ? -(sz) : (sz)) + #define HOWTO(type, right, size, bits, pcrel, left, ovf, func, name, \ + inplace, src_mask, dst_mask, pcrel_off) \ + { (unsigned) type, HOWTO_RSIZE (size), bits, right, left, ovf, \ + size < 0, pcrel, inplace, pcrel_off, HOWTO_INSTALL_ADDEND, \ + src_mask, dst_mask, func, name } + + This is used to fill in an empty howto entry in an array. + #define EMPTY_HOWTO(C) \ + HOWTO ((C), 0, 1, 0, false, 0, complain_overflow_dont, NULL, \ + NULL, false, 0, 0, false) + + static inline unsigned int + bfd_get_reloc_size (reloc_howto_type *howto) + { + return howto->size; + } + + +2.10.1.4 'arelent_chain' +........................ + +How relocs are tied together in an 'asection': + typedef struct relent_chain + { + arelent relent; + struct relent_chain *next; + } + arelent_chain; + + +2.10.1.5 'bfd_check_overflow' +............................. + + -- Function: bfd_reloc_status_type bfd_check_overflow (enum + complain_overflow how, unsigned int bitsize, unsigned int + rightshift, unsigned int addrsize, bfd_vma relocation); + Perform overflow checking on RELOCATION which has BITSIZE + significant bits and will be shifted right by RIGHTSHIFT bits, on a + machine with addresses containing ADDRSIZE significant bits. The + result is either of 'bfd_reloc_ok' or 'bfd_reloc_overflow'. + +2.10.1.6 'bfd_reloc_offset_in_range' +.................................... + + -- Function: bool bfd_reloc_offset_in_range (reloc_howto_type *howto, + bfd *abfd, asection *section, bfd_size_type offset); + Returns TRUE if the reloc described by HOWTO can be applied at + OFFSET octets in SECTION. + +2.10.1.7 'bfd_perform_relocation' +................................. + + -- Function: bfd_reloc_status_type bfd_perform_relocation (bfd *abfd, + arelent *reloc_entry, void *data, asection *input_section, bfd + *output_bfd, char **error_message); + If OUTPUT_BFD is supplied to this function, the generated image + will be relocatable; the relocations are copied to the output file + after they have been changed to reflect the new state of the world. + There are two ways of reflecting the results of partial linkage in + an output file: by modifying the output data in place, and by + modifying the relocation record. Some native formats (e.g., basic + a.out and basic coff) have no way of specifying an addend in the + relocation type, so the addend has to go in the output data. This + is no big deal since in these formats the output data slot will + always be big enough for the addend. Complex reloc types with + addends were invented to solve just this problem. The + ERROR_MESSAGE argument is set to an error message if this return + 'bfd_reloc_dangerous'. + +2.10.1.8 'bfd_install_relocation' +................................. + + -- Function: bfd_reloc_status_type bfd_install_relocation (bfd *abfd, + arelent *reloc_entry, void *data, bfd_vma data_start, asection + *input_section, char **error_message); + This looks remarkably like 'bfd_perform_relocation', except it does + not expect that the section contents have been filled in. I.e., + it's suitable for use when creating, rather than applying a + relocation. + + For now, this function should be considered reserved for the + assembler. + + +File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations + +2.10.2 The howto manager +------------------------ + +When an application wants to create a relocation, but doesn't know what +the target machine might call it, it can find out by using this bit of +code. + +2.10.2.1 'bfd_reloc_code_real_type' +................................... + +The insides of a reloc code. The idea is that, eventually, there will +be one enumerator for every type of relocation we ever do. Pass one of +these values to 'bfd_reloc_type_lookup', and it'll return a howto +pointer. + + This does mean that the application must determine the correct +enumerator value; you can't get a howto pointer from a random set of +attributes. + + Here are the possible values for 'enum bfd_reloc_code_real': + + -- : BFD_RELOC_64 + -- : BFD_RELOC_32 + -- : BFD_RELOC_26 + -- : BFD_RELOC_24 + -- : BFD_RELOC_16 + -- : BFD_RELOC_14 + -- : BFD_RELOC_8 + Basic absolute relocations of N bits. + -- : BFD_RELOC_64_PCREL + -- : BFD_RELOC_32_PCREL + -- : BFD_RELOC_24_PCREL + -- : BFD_RELOC_16_PCREL + -- : BFD_RELOC_12_PCREL + -- : BFD_RELOC_8_PCREL + PC-relative relocations. Sometimes these are relative to the + address of the relocation itself; sometimes they are relative to + the start of the section containing the relocation. It depends on + the specific target. + -- : BFD_RELOC_32_SECREL + -- : BFD_RELOC_16_SECIDX + Section relative relocations. Some targets need this for DWARF2. + -- : BFD_RELOC_32_GOT_PCREL + -- : BFD_RELOC_16_GOT_PCREL + -- : BFD_RELOC_8_GOT_PCREL + -- : BFD_RELOC_32_GOTOFF + -- : BFD_RELOC_16_GOTOFF + -- : BFD_RELOC_LO16_GOTOFF + -- : BFD_RELOC_HI16_GOTOFF + -- : BFD_RELOC_HI16_S_GOTOFF + -- : BFD_RELOC_8_GOTOFF + -- : BFD_RELOC_64_PLT_PCREL + -- : BFD_RELOC_32_PLT_PCREL + -- : BFD_RELOC_24_PLT_PCREL + -- : BFD_RELOC_16_PLT_PCREL + -- : BFD_RELOC_8_PLT_PCREL + -- : BFD_RELOC_64_PLTOFF + -- : BFD_RELOC_32_PLTOFF + -- : BFD_RELOC_16_PLTOFF + -- : BFD_RELOC_LO16_PLTOFF + -- : BFD_RELOC_HI16_PLTOFF + -- : BFD_RELOC_HI16_S_PLTOFF + -- : BFD_RELOC_8_PLTOFF + For ELF. + -- : BFD_RELOC_SIZE32 + -- : BFD_RELOC_SIZE64 + Size relocations. + -- : BFD_RELOC_68K_GLOB_DAT + -- : BFD_RELOC_68K_JMP_SLOT + -- : BFD_RELOC_68K_RELATIVE + -- : BFD_RELOC_68K_TLS_GD32 + -- : BFD_RELOC_68K_TLS_GD16 + -- : BFD_RELOC_68K_TLS_GD8 + -- : BFD_RELOC_68K_TLS_LDM32 + -- : BFD_RELOC_68K_TLS_LDM16 + -- : BFD_RELOC_68K_TLS_LDM8 + -- : BFD_RELOC_68K_TLS_LDO32 + -- : BFD_RELOC_68K_TLS_LDO16 + -- : BFD_RELOC_68K_TLS_LDO8 + -- : BFD_RELOC_68K_TLS_IE32 + -- : BFD_RELOC_68K_TLS_IE16 + -- : BFD_RELOC_68K_TLS_IE8 + -- : BFD_RELOC_68K_TLS_LE32 + -- : BFD_RELOC_68K_TLS_LE16 + -- : BFD_RELOC_68K_TLS_LE8 + Relocations used by 68K ELF. + -- : BFD_RELOC_32_BASEREL + -- : BFD_RELOC_16_BASEREL + -- : BFD_RELOC_LO16_BASEREL + -- : BFD_RELOC_HI16_BASEREL + -- : BFD_RELOC_HI16_S_BASEREL + -- : BFD_RELOC_8_BASEREL + -- : BFD_RELOC_RVA + Linkage-table relative. + -- : BFD_RELOC_8_FFnn + Absolute 8-bit relocation, but used to form an address like 0xFFnn. + -- : BFD_RELOC_32_PCREL_S2 + -- : BFD_RELOC_16_PCREL_S2 + -- : BFD_RELOC_23_PCREL_S2 + These PC-relative relocations are stored as word displacements - + i.e., byte displacements shifted right two bits. The 30-bit word + displacement (<<32_PCREL_S2>> - 32 bits, shifted 2) is used on the + SPARC. (SPARC tools generally refer to this as <>.) The + signed 16-bit displacement is used on the MIPS, and the 23-bit + displacement is used on the Alpha. + -- : BFD_RELOC_HI22 + -- : BFD_RELOC_LO10 + High 22 bits and low 10 bits of 32-bit value, placed into lower + bits of the target word. These are used on the SPARC. + -- : BFD_RELOC_GPREL16 + -- : BFD_RELOC_GPREL32 + For systems that allocate a Global Pointer register, these are + displacements off that register. These relocation types are + handled specially, because the value the register will have is + decided relatively late. + -- : BFD_RELOC_NONE + -- : BFD_RELOC_SPARC_WDISP22 + -- : BFD_RELOC_SPARC22 + -- : BFD_RELOC_SPARC13 + -- : BFD_RELOC_SPARC_GOT10 + -- : BFD_RELOC_SPARC_GOT13 + -- : BFD_RELOC_SPARC_GOT22 + -- : BFD_RELOC_SPARC_PC10 + -- : BFD_RELOC_SPARC_PC22 + -- : BFD_RELOC_SPARC_WPLT30 + -- : BFD_RELOC_SPARC_COPY + -- : BFD_RELOC_SPARC_GLOB_DAT + -- : BFD_RELOC_SPARC_JMP_SLOT + -- : BFD_RELOC_SPARC_RELATIVE + -- : BFD_RELOC_SPARC_UA16 + -- : BFD_RELOC_SPARC_UA32 + -- : BFD_RELOC_SPARC_UA64 + -- : BFD_RELOC_SPARC_GOTDATA_HIX22 + -- : BFD_RELOC_SPARC_GOTDATA_LOX10 + -- : BFD_RELOC_SPARC_GOTDATA_OP_HIX22 + -- : BFD_RELOC_SPARC_GOTDATA_OP_LOX10 + -- : BFD_RELOC_SPARC_GOTDATA_OP + -- : BFD_RELOC_SPARC_JMP_IREL + -- : BFD_RELOC_SPARC_IRELATIVE + SPARC ELF relocations. There is probably some overlap with other + relocation types already defined. + -- : BFD_RELOC_SPARC_BASE13 + -- : BFD_RELOC_SPARC_BASE22 + I think these are specific to SPARC a.out (e.g., Sun 4). + -- : BFD_RELOC_SPARC_64 + -- : BFD_RELOC_SPARC_10 + -- : BFD_RELOC_SPARC_11 + -- : BFD_RELOC_SPARC_OLO10 + -- : BFD_RELOC_SPARC_HH22 + -- : BFD_RELOC_SPARC_HM10 + -- : BFD_RELOC_SPARC_LM22 + -- : BFD_RELOC_SPARC_PC_HH22 + -- : BFD_RELOC_SPARC_PC_HM10 + -- : BFD_RELOC_SPARC_PC_LM22 + -- : BFD_RELOC_SPARC_WDISP16 + -- : BFD_RELOC_SPARC_WDISP19 + -- : BFD_RELOC_SPARC_7 + -- : BFD_RELOC_SPARC_6 + -- : BFD_RELOC_SPARC_5 + -- : BFD_RELOC_SPARC_DISP64 + -- : BFD_RELOC_SPARC_PLT32 + -- : BFD_RELOC_SPARC_PLT64 + -- : BFD_RELOC_SPARC_HIX22 + -- : BFD_RELOC_SPARC_LOX10 + -- : BFD_RELOC_SPARC_H44 + -- : BFD_RELOC_SPARC_M44 + -- : BFD_RELOC_SPARC_L44 + -- : BFD_RELOC_SPARC_REGISTER + -- : BFD_RELOC_SPARC_H34 + -- : BFD_RELOC_SPARC_SIZE32 + -- : BFD_RELOC_SPARC_SIZE64 + -- : BFD_RELOC_SPARC_WDISP10 + SPARC64 relocations. + -- : BFD_RELOC_SPARC_REV32 + SPARC little endian relocation. + -- : BFD_RELOC_SPARC_TLS_GD_HI22 + -- : BFD_RELOC_SPARC_TLS_GD_LO10 + -- : BFD_RELOC_SPARC_TLS_GD_ADD + -- : BFD_RELOC_SPARC_TLS_GD_CALL + -- : BFD_RELOC_SPARC_TLS_LDM_HI22 + -- : BFD_RELOC_SPARC_TLS_LDM_LO10 + -- : BFD_RELOC_SPARC_TLS_LDM_ADD + -- : BFD_RELOC_SPARC_TLS_LDM_CALL + -- : BFD_RELOC_SPARC_TLS_LDO_HIX22 + -- : BFD_RELOC_SPARC_TLS_LDO_LOX10 + -- : BFD_RELOC_SPARC_TLS_LDO_ADD + -- : BFD_RELOC_SPARC_TLS_IE_HI22 + -- : BFD_RELOC_SPARC_TLS_IE_LO10 + -- : BFD_RELOC_SPARC_TLS_IE_LD + -- : BFD_RELOC_SPARC_TLS_IE_LDX + -- : BFD_RELOC_SPARC_TLS_IE_ADD + -- : BFD_RELOC_SPARC_TLS_LE_HIX22 + -- : BFD_RELOC_SPARC_TLS_LE_LOX10 + -- : BFD_RELOC_SPARC_TLS_DTPMOD32 + -- : BFD_RELOC_SPARC_TLS_DTPMOD64 + -- : BFD_RELOC_SPARC_TLS_DTPOFF32 + -- : BFD_RELOC_SPARC_TLS_DTPOFF64 + -- : BFD_RELOC_SPARC_TLS_TPOFF32 + -- : BFD_RELOC_SPARC_TLS_TPOFF64 + SPARC TLS relocations. + -- : BFD_RELOC_SPU_IMM7 + -- : BFD_RELOC_SPU_IMM8 + -- : BFD_RELOC_SPU_IMM10 + -- : BFD_RELOC_SPU_IMM10W + -- : BFD_RELOC_SPU_IMM16 + -- : BFD_RELOC_SPU_IMM16W + -- : BFD_RELOC_SPU_IMM18 + -- : BFD_RELOC_SPU_PCREL9a + -- : BFD_RELOC_SPU_PCREL9b + -- : BFD_RELOC_SPU_PCREL16 + -- : BFD_RELOC_SPU_LO16 + -- : BFD_RELOC_SPU_HI16 + -- : BFD_RELOC_SPU_PPU32 + -- : BFD_RELOC_SPU_PPU64 + -- : BFD_RELOC_SPU_ADD_PIC + SPU Relocations. + -- : BFD_RELOC_ALPHA_GPDISP_HI16 + Alpha ECOFF and ELF relocations. Some of these treat the symbol or + "addend" in some special way. For GPDISP_HI16 ("gpdisp") + relocations, the symbol is ignored when writing; when reading, it + will be the absolute section symbol. The addend is the + displacement in bytes of the "lda" instruction from the "ldah" + instruction (which is at the address of this reloc). + -- : BFD_RELOC_ALPHA_GPDISP_LO16 + For GPDISP_LO16 ("ignore") relocations, the symbol is handled as + with GPDISP_HI16 relocs. The addend is ignored when writing the + relocations out, and is filled in with the file's GP value on + reading, for convenience. + -- : BFD_RELOC_ALPHA_GPDISP + The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 + relocation except that there is no accompanying GPDISP_LO16 + relocation. + -- : BFD_RELOC_ALPHA_LITERAL + -- : BFD_RELOC_ALPHA_ELF_LITERAL + -- : BFD_RELOC_ALPHA_LITUSE + The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; + the assembler turns it into a LDQ instruction to load the address + of the symbol, and then fills in a register in the real + instruction. + + The LITERAL reloc, at the LDQ instruction, refers to the .lita + section symbol. The addend is ignored when writing, but is filled + in with the file's GP value on reading, for convenience, as with + the GPDISP_LO16 reloc. + + The ELF_LITERAL reloc is somewhere between 16_GOTOFF and + GPDISP_LO16. It should refer to the symbol to be referenced, as + with 16_GOTOFF, but it generates output not based on the position + within the .got section, but relative to the GP value chosen for + the file during the final link stage. + + The LITUSE reloc, on the instruction using the loaded address, + gives information to the linker that it might be able to use to + optimize away some literal section references. The symbol is + ignored (read as the absolute section symbol), and the "addend" + indicates the type of instruction using the register: 1 - "memory" + fmt insn 2 - byte-manipulation (byte offset reg) 3 - jsr (target of + branch) + -- : BFD_RELOC_ALPHA_HINT + The HINT relocation indicates a value that should be filled into + the "hint" field of a jmp/jsr/ret instruction, for possible branch- + prediction logic which may be provided on some processors. + -- : BFD_RELOC_ALPHA_LINKAGE + The LINKAGE relocation outputs a linkage pair in the object file, + which is filled by the linker. + -- : BFD_RELOC_ALPHA_CODEADDR + The CODEADDR relocation outputs a STO_CA in the object file, which + is filled by the linker. + -- : BFD_RELOC_ALPHA_GPREL_HI16 + -- : BFD_RELOC_ALPHA_GPREL_LO16 + The GPREL_HI/LO relocations together form a 32-bit offset from the + GP register. + -- : BFD_RELOC_ALPHA_BRSGP + Like BFD_RELOC_23_PCREL_S2, except that the source and target must + share a common GP, and the target address is adjusted for + STO_ALPHA_STD_GPLOAD. + -- : BFD_RELOC_ALPHA_NOP + The NOP relocation outputs a NOP if the longword displacement + between two procedure entry points is < 2^21. + -- : BFD_RELOC_ALPHA_BSR + The BSR relocation outputs a BSR if the longword displacement + between two procedure entry points is < 2^21. + -- : BFD_RELOC_ALPHA_LDA + The LDA relocation outputs a LDA if the longword displacement + between two procedure entry points is < 2^16. + -- : BFD_RELOC_ALPHA_BOH + The BOH relocation outputs a BSR if the longword displacement + between two procedure entry points is < 2^21, or else a hint. + -- : BFD_RELOC_ALPHA_TLSGD + -- : BFD_RELOC_ALPHA_TLSLDM + -- : BFD_RELOC_ALPHA_DTPMOD64 + -- : BFD_RELOC_ALPHA_GOTDTPREL16 + -- : BFD_RELOC_ALPHA_DTPREL64 + -- : BFD_RELOC_ALPHA_DTPREL_HI16 + -- : BFD_RELOC_ALPHA_DTPREL_LO16 + -- : BFD_RELOC_ALPHA_DTPREL16 + -- : BFD_RELOC_ALPHA_GOTTPREL16 + -- : BFD_RELOC_ALPHA_TPREL64 + -- : BFD_RELOC_ALPHA_TPREL_HI16 + -- : BFD_RELOC_ALPHA_TPREL_LO16 + -- : BFD_RELOC_ALPHA_TPREL16 + Alpha thread-local storage relocations. + -- : BFD_RELOC_MIPS_JMP + -- : BFD_RELOC_MICROMIPS_JMP + The MIPS jump instruction. + -- : BFD_RELOC_MIPS16_JMP + The MIPS16 jump instruction. + -- : BFD_RELOC_MIPS16_GPREL + MIPS16 GP relative reloc. + -- : BFD_RELOC_HI16 + High 16 bits of 32-bit value; simple reloc. + -- : BFD_RELOC_HI16_S + High 16 bits of 32-bit value but the low 16 bits will be sign + extended and added to form the final result. If the low 16 bits + form a negative number, we need to add one to the high value to + compensate for the borrow when the low bits are added. + -- : BFD_RELOC_LO16 + Low 16 bits. + -- : BFD_RELOC_HI16_PCREL + High 16 bits of 32-bit pc-relative value. + -- : BFD_RELOC_HI16_S_PCREL + High 16 bits of 32-bit pc-relative value, adjusted. + -- : BFD_RELOC_LO16_PCREL + Low 16 bits of pc-relative value. + -- : BFD_RELOC_MIPS16_GOT16 + -- : BFD_RELOC_MIPS16_CALL16 + Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of + 16-bit immediate fields. + -- : BFD_RELOC_MIPS16_HI16 + MIPS16 high 16 bits of 32-bit value. + -- : BFD_RELOC_MIPS16_HI16_S + MIPS16 high 16 bits of 32-bit value but the low 16 bits will be + sign extended and added to form the final result. If the low 16 + bits form a negative number, we need to add one to the high value + to compensate for the borrow when the low bits are added. + -- : BFD_RELOC_MIPS16_LO16 + MIPS16 low 16 bits. + -- : BFD_RELOC_MIPS16_TLS_GD + -- : BFD_RELOC_MIPS16_TLS_LDM + -- : BFD_RELOC_MIPS16_TLS_DTPREL_HI16 + -- : BFD_RELOC_MIPS16_TLS_DTPREL_LO16 + -- : BFD_RELOC_MIPS16_TLS_GOTTPREL + -- : BFD_RELOC_MIPS16_TLS_TPREL_HI16 + -- : BFD_RELOC_MIPS16_TLS_TPREL_LO16 + MIPS16 TLS relocations. + -- : BFD_RELOC_MIPS_LITERAL + -- : BFD_RELOC_MICROMIPS_LITERAL + Relocation against a MIPS literal section. + -- : BFD_RELOC_MICROMIPS_7_PCREL_S1 + -- : BFD_RELOC_MICROMIPS_10_PCREL_S1 + -- : BFD_RELOC_MICROMIPS_16_PCREL_S1 + microMIPS PC-relative relocations. + -- : BFD_RELOC_MIPS16_16_PCREL_S1 + MIPS16 PC-relative relocation. + -- : BFD_RELOC_MIPS_21_PCREL_S2 + -- : BFD_RELOC_MIPS_26_PCREL_S2 + -- : BFD_RELOC_MIPS_18_PCREL_S3 + -- : BFD_RELOC_MIPS_19_PCREL_S2 + MIPS PC-relative relocations. + -- : BFD_RELOC_MICROMIPS_GPREL16 + -- : BFD_RELOC_MICROMIPS_HI16 + -- : BFD_RELOC_MICROMIPS_HI16_S + -- : BFD_RELOC_MICROMIPS_LO16 + microMIPS versions of generic BFD relocs. + -- : BFD_RELOC_MIPS_GOT16 + -- : BFD_RELOC_MICROMIPS_GOT16 + -- : BFD_RELOC_MIPS_CALL16 + -- : BFD_RELOC_MICROMIPS_CALL16 + -- : BFD_RELOC_MIPS_GOT_HI16 + -- : BFD_RELOC_MICROMIPS_GOT_HI16 + -- : BFD_RELOC_MIPS_GOT_LO16 + -- : BFD_RELOC_MICROMIPS_GOT_LO16 + -- : BFD_RELOC_MIPS_CALL_HI16 + -- : BFD_RELOC_MICROMIPS_CALL_HI16 + -- : BFD_RELOC_MIPS_CALL_LO16 + -- : BFD_RELOC_MICROMIPS_CALL_LO16 + -- : BFD_RELOC_MIPS_SUB + -- : BFD_RELOC_MICROMIPS_SUB + -- : BFD_RELOC_MIPS_GOT_PAGE + -- : BFD_RELOC_MICROMIPS_GOT_PAGE + -- : BFD_RELOC_MIPS_GOT_OFST + -- : BFD_RELOC_MICROMIPS_GOT_OFST + -- : BFD_RELOC_MIPS_GOT_DISP + -- : BFD_RELOC_MICROMIPS_GOT_DISP + -- : BFD_RELOC_MIPS_SHIFT5 + -- : BFD_RELOC_MIPS_SHIFT6 + -- : BFD_RELOC_MIPS_INSERT_A + -- : BFD_RELOC_MIPS_INSERT_B + -- : BFD_RELOC_MIPS_DELETE + -- : BFD_RELOC_MIPS_HIGHEST + -- : BFD_RELOC_MICROMIPS_HIGHEST + -- : BFD_RELOC_MIPS_HIGHER + -- : BFD_RELOC_MICROMIPS_HIGHER + -- : BFD_RELOC_MIPS_SCN_DISP + -- : BFD_RELOC_MICROMIPS_SCN_DISP + -- : BFD_RELOC_MIPS_16 + -- : BFD_RELOC_MIPS_RELGOT + -- : BFD_RELOC_MIPS_JALR + -- : BFD_RELOC_MICROMIPS_JALR + -- : BFD_RELOC_MIPS_TLS_DTPMOD32 + -- : BFD_RELOC_MIPS_TLS_DTPREL32 + -- : BFD_RELOC_MIPS_TLS_DTPMOD64 + -- : BFD_RELOC_MIPS_TLS_DTPREL64 + -- : BFD_RELOC_MIPS_TLS_GD + -- : BFD_RELOC_MICROMIPS_TLS_GD + -- : BFD_RELOC_MIPS_TLS_LDM + -- : BFD_RELOC_MICROMIPS_TLS_LDM + -- : BFD_RELOC_MIPS_TLS_DTPREL_HI16 + -- : BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16 + -- : BFD_RELOC_MIPS_TLS_DTPREL_LO16 + -- : BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16 + -- : BFD_RELOC_MIPS_TLS_GOTTPREL + -- : BFD_RELOC_MICROMIPS_TLS_GOTTPREL + -- : BFD_RELOC_MIPS_TLS_TPREL32 + -- : BFD_RELOC_MIPS_TLS_TPREL64 + -- : BFD_RELOC_MIPS_TLS_TPREL_HI16 + -- : BFD_RELOC_MICROMIPS_TLS_TPREL_HI16 + -- : BFD_RELOC_MIPS_TLS_TPREL_LO16 + -- : BFD_RELOC_MICROMIPS_TLS_TPREL_LO16 + -- : BFD_RELOC_MIPS_EH + MIPS ELF relocations. + -- : BFD_RELOC_MIPS_COPY + -- : BFD_RELOC_MIPS_JUMP_SLOT + MIPS ELF relocations (VxWorks and PLT extensions). + -- : BFD_RELOC_MOXIE_10_PCREL + Moxie ELF relocations. + -- : BFD_RELOC_FT32_10 + -- : BFD_RELOC_FT32_20 + -- : BFD_RELOC_FT32_17 + -- : BFD_RELOC_FT32_18 + -- : BFD_RELOC_FT32_RELAX + -- : BFD_RELOC_FT32_SC0 + -- : BFD_RELOC_FT32_SC1 + -- : BFD_RELOC_FT32_15 + -- : BFD_RELOC_FT32_DIFF32 + FT32 ELF relocations. + -- : BFD_RELOC_FRV_LABEL16 + -- : BFD_RELOC_FRV_LABEL24 + -- : BFD_RELOC_FRV_LO16 + -- : BFD_RELOC_FRV_HI16 + -- : BFD_RELOC_FRV_GPREL12 + -- : BFD_RELOC_FRV_GPRELU12 + -- : BFD_RELOC_FRV_GPREL32 + -- : BFD_RELOC_FRV_GPRELHI + -- : BFD_RELOC_FRV_GPRELLO + -- : BFD_RELOC_FRV_GOT12 + -- : BFD_RELOC_FRV_GOTHI + -- : BFD_RELOC_FRV_GOTLO + -- : BFD_RELOC_FRV_FUNCDESC + -- : BFD_RELOC_FRV_FUNCDESC_GOT12 + -- : BFD_RELOC_FRV_FUNCDESC_GOTHI + -- : BFD_RELOC_FRV_FUNCDESC_GOTLO + -- : BFD_RELOC_FRV_FUNCDESC_VALUE + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFF12 + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFHI + -- : BFD_RELOC_FRV_FUNCDESC_GOTOFFLO + -- : BFD_RELOC_FRV_GOTOFF12 + -- : BFD_RELOC_FRV_GOTOFFHI + -- : BFD_RELOC_FRV_GOTOFFLO + -- : BFD_RELOC_FRV_GETTLSOFF + -- : BFD_RELOC_FRV_TLSDESC_VALUE + -- : BFD_RELOC_FRV_GOTTLSDESC12 + -- : BFD_RELOC_FRV_GOTTLSDESCHI + -- : BFD_RELOC_FRV_GOTTLSDESCLO + -- : BFD_RELOC_FRV_TLSMOFF12 + -- : BFD_RELOC_FRV_TLSMOFFHI + -- : BFD_RELOC_FRV_TLSMOFFLO + -- : BFD_RELOC_FRV_GOTTLSOFF12 + -- : BFD_RELOC_FRV_GOTTLSOFFHI + -- : BFD_RELOC_FRV_GOTTLSOFFLO + -- : BFD_RELOC_FRV_TLSOFF + -- : BFD_RELOC_FRV_TLSDESC_RELAX + -- : BFD_RELOC_FRV_GETTLSOFF_RELAX + -- : BFD_RELOC_FRV_TLSOFF_RELAX + -- : BFD_RELOC_FRV_TLSMOFF + Fujitsu Frv Relocations. + -- : BFD_RELOC_MN10300_GOTOFF24 + This is a 24bit GOT-relative reloc for the mn10300. + -- : BFD_RELOC_MN10300_GOT32 + This is a 32bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_GOT24 + This is a 24bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_GOT16 + This is a 16bit GOT-relative reloc for the mn10300, offset by two + bytes in the instruction. + -- : BFD_RELOC_MN10300_COPY + Copy symbol at runtime. + -- : BFD_RELOC_MN10300_GLOB_DAT + Create GOT entry. + -- : BFD_RELOC_MN10300_JMP_SLOT + Create PLT entry. + -- : BFD_RELOC_MN10300_RELATIVE + Adjust by program base. + -- : BFD_RELOC_MN10300_SYM_DIFF + Together with another reloc targeted at the same location, allows + for a value that is the difference of two symbols in the same + section. + -- : BFD_RELOC_MN10300_ALIGN + The addend of this reloc is an alignment power that must be + honoured at the offset's location, regardless of linker relaxation. + -- : BFD_RELOC_MN10300_TLS_GD + -- : BFD_RELOC_MN10300_TLS_LD + -- : BFD_RELOC_MN10300_TLS_LDO + -- : BFD_RELOC_MN10300_TLS_GOTIE + -- : BFD_RELOC_MN10300_TLS_IE + -- : BFD_RELOC_MN10300_TLS_LE + -- : BFD_RELOC_MN10300_TLS_DTPMOD + -- : BFD_RELOC_MN10300_TLS_DTPOFF + -- : BFD_RELOC_MN10300_TLS_TPOFF + Various TLS-related relocations. + -- : BFD_RELOC_MN10300_32_PCREL + This is a 32bit pcrel reloc for the mn10300, offset by two bytes in + the instruction. + -- : BFD_RELOC_MN10300_16_PCREL + This is a 16bit pcrel reloc for the mn10300, offset by two bytes in + the instruction. + -- : BFD_RELOC_386_GOT32 + -- : BFD_RELOC_386_PLT32 + -- : BFD_RELOC_386_COPY + -- : BFD_RELOC_386_GLOB_DAT + -- : BFD_RELOC_386_JUMP_SLOT + -- : BFD_RELOC_386_RELATIVE + -- : BFD_RELOC_386_GOTOFF + -- : BFD_RELOC_386_GOTPC + -- : BFD_RELOC_386_TLS_TPOFF + -- : BFD_RELOC_386_TLS_IE + -- : BFD_RELOC_386_TLS_GOTIE + -- : BFD_RELOC_386_TLS_LE + -- : BFD_RELOC_386_TLS_GD + -- : BFD_RELOC_386_TLS_LDM + -- : BFD_RELOC_386_TLS_LDO_32 + -- : BFD_RELOC_386_TLS_IE_32 + -- : BFD_RELOC_386_TLS_LE_32 + -- : BFD_RELOC_386_TLS_DTPMOD32 + -- : BFD_RELOC_386_TLS_DTPOFF32 + -- : BFD_RELOC_386_TLS_TPOFF32 + -- : BFD_RELOC_386_TLS_GOTDESC + -- : BFD_RELOC_386_TLS_DESC_CALL + -- : BFD_RELOC_386_TLS_DESC + -- : BFD_RELOC_386_IRELATIVE + -- : BFD_RELOC_386_GOT32X + i386/elf relocations. + -- : BFD_RELOC_X86_64_GOT32 + -- : BFD_RELOC_X86_64_PLT32 + -- : BFD_RELOC_X86_64_COPY + -- : BFD_RELOC_X86_64_GLOB_DAT + -- : BFD_RELOC_X86_64_JUMP_SLOT + -- : BFD_RELOC_X86_64_RELATIVE + -- : BFD_RELOC_X86_64_GOTPCREL + -- : BFD_RELOC_X86_64_32S + -- : BFD_RELOC_X86_64_DTPMOD64 + -- : BFD_RELOC_X86_64_DTPOFF64 + -- : BFD_RELOC_X86_64_TPOFF64 + -- : BFD_RELOC_X86_64_TLSGD + -- : BFD_RELOC_X86_64_TLSLD + -- : BFD_RELOC_X86_64_DTPOFF32 + -- : BFD_RELOC_X86_64_GOTTPOFF + -- : BFD_RELOC_X86_64_TPOFF32 + -- : BFD_RELOC_X86_64_GOTOFF64 + -- : BFD_RELOC_X86_64_GOTPC32 + -- : BFD_RELOC_X86_64_GOT64 + -- : BFD_RELOC_X86_64_GOTPCREL64 + -- : BFD_RELOC_X86_64_GOTPC64 + -- : BFD_RELOC_X86_64_GOTPLT64 + -- : BFD_RELOC_X86_64_PLTOFF64 + -- : BFD_RELOC_X86_64_GOTPC32_TLSDESC + -- : BFD_RELOC_X86_64_TLSDESC_CALL + -- : BFD_RELOC_X86_64_TLSDESC + -- : BFD_RELOC_X86_64_IRELATIVE + -- : BFD_RELOC_X86_64_PC32_BND + -- : BFD_RELOC_X86_64_PLT32_BND + -- : BFD_RELOC_X86_64_GOTPCRELX + -- : BFD_RELOC_X86_64_REX_GOTPCRELX + -- : BFD_RELOC_X86_64_CODE_4_GOTPCRELX + -- : BFD_RELOC_X86_64_CODE_4_GOTTPOFF + -- : BFD_RELOC_X86_64_CODE_4_GOTPC32_TLSDESC + -- : BFD_RELOC_X86_64_CODE_5_GOTPCRELX + -- : BFD_RELOC_X86_64_CODE_5_GOTTPOFF + -- : BFD_RELOC_X86_64_CODE_5_GOTPC32_TLSDESC + -- : BFD_RELOC_X86_64_CODE_6_GOTPCRELX + -- : BFD_RELOC_X86_64_CODE_6_GOTTPOFF + -- : BFD_RELOC_X86_64_CODE_6_GOTPC32_TLSDESC + x86-64/elf relocations. + -- : BFD_RELOC_NS32K_IMM_8 + -- : BFD_RELOC_NS32K_IMM_16 + -- : BFD_RELOC_NS32K_IMM_32 + -- : BFD_RELOC_NS32K_IMM_8_PCREL + -- : BFD_RELOC_NS32K_IMM_16_PCREL + -- : BFD_RELOC_NS32K_IMM_32_PCREL + -- : BFD_RELOC_NS32K_DISP_8 + -- : BFD_RELOC_NS32K_DISP_16 + -- : BFD_RELOC_NS32K_DISP_32 + -- : BFD_RELOC_NS32K_DISP_8_PCREL + -- : BFD_RELOC_NS32K_DISP_16_PCREL + -- : BFD_RELOC_NS32K_DISP_32_PCREL + ns32k relocations. + -- : BFD_RELOC_PDP11_DISP_8_PCREL + -- : BFD_RELOC_PDP11_DISP_6_PCREL + PDP11 relocations. + -- : BFD_RELOC_PJ_CODE_HI16 + -- : BFD_RELOC_PJ_CODE_LO16 + -- : BFD_RELOC_PJ_CODE_DIR16 + -- : BFD_RELOC_PJ_CODE_DIR32 + -- : BFD_RELOC_PJ_CODE_REL16 + -- : BFD_RELOC_PJ_CODE_REL32 + Picojava relocs. Not all of these appear in object files. + -- : BFD_RELOC_PPC_B26 + -- : BFD_RELOC_PPC_BA26 + -- : BFD_RELOC_PPC_TOC16 + -- : BFD_RELOC_PPC_TOC16_LO + -- : BFD_RELOC_PPC_TOC16_HI + -- : BFD_RELOC_PPC_B16 + -- : BFD_RELOC_PPC_B16_BRTAKEN + -- : BFD_RELOC_PPC_B16_BRNTAKEN + -- : BFD_RELOC_PPC_BA16 + -- : BFD_RELOC_PPC_BA16_BRTAKEN + -- : BFD_RELOC_PPC_BA16_BRNTAKEN + -- : BFD_RELOC_PPC_COPY + -- : BFD_RELOC_PPC_GLOB_DAT + -- : BFD_RELOC_PPC_JMP_SLOT + -- : BFD_RELOC_PPC_RELATIVE + -- : BFD_RELOC_PPC_LOCAL24PC + -- : BFD_RELOC_PPC_EMB_NADDR32 + -- : BFD_RELOC_PPC_EMB_NADDR16 + -- : BFD_RELOC_PPC_EMB_NADDR16_LO + -- : BFD_RELOC_PPC_EMB_NADDR16_HI + -- : BFD_RELOC_PPC_EMB_NADDR16_HA + -- : BFD_RELOC_PPC_EMB_SDAI16 + -- : BFD_RELOC_PPC_EMB_SDA2I16 + -- : BFD_RELOC_PPC_EMB_SDA2REL + -- : BFD_RELOC_PPC_EMB_SDA21 + -- : BFD_RELOC_PPC_EMB_MRKREF + -- : BFD_RELOC_PPC_EMB_RELSEC16 + -- : BFD_RELOC_PPC_EMB_RELST_LO + -- : BFD_RELOC_PPC_EMB_RELST_HI + -- : BFD_RELOC_PPC_EMB_RELST_HA + -- : BFD_RELOC_PPC_EMB_BIT_FLD + -- : BFD_RELOC_PPC_EMB_RELSDA + -- : BFD_RELOC_PPC_VLE_REL8 + -- : BFD_RELOC_PPC_VLE_REL15 + -- : BFD_RELOC_PPC_VLE_REL24 + -- : BFD_RELOC_PPC_VLE_LO16A + -- : BFD_RELOC_PPC_VLE_LO16D + -- : BFD_RELOC_PPC_VLE_HI16A + -- : BFD_RELOC_PPC_VLE_HI16D + -- : BFD_RELOC_PPC_VLE_HA16A + -- : BFD_RELOC_PPC_VLE_HA16D + -- : BFD_RELOC_PPC_VLE_SDA21 + -- : BFD_RELOC_PPC_VLE_SDA21_LO + -- : BFD_RELOC_PPC_VLE_SDAREL_LO16A + -- : BFD_RELOC_PPC_VLE_SDAREL_LO16D + -- : BFD_RELOC_PPC_VLE_SDAREL_HI16A + -- : BFD_RELOC_PPC_VLE_SDAREL_HI16D + -- : BFD_RELOC_PPC_VLE_SDAREL_HA16A + -- : BFD_RELOC_PPC_VLE_SDAREL_HA16D + -- : BFD_RELOC_PPC_16DX_HA + -- : BFD_RELOC_PPC_REL16DX_HA + -- : BFD_RELOC_PPC_NEG + -- : BFD_RELOC_PPC64_HIGHER + -- : BFD_RELOC_PPC64_HIGHER_S + -- : BFD_RELOC_PPC64_HIGHEST + -- : BFD_RELOC_PPC64_HIGHEST_S + -- : BFD_RELOC_PPC64_TOC16_LO + -- : BFD_RELOC_PPC64_TOC16_HI + -- : BFD_RELOC_PPC64_TOC16_HA + -- : BFD_RELOC_PPC64_TOC + -- : BFD_RELOC_PPC64_PLTGOT16 + -- : BFD_RELOC_PPC64_PLTGOT16_LO + -- : BFD_RELOC_PPC64_PLTGOT16_HI + -- : BFD_RELOC_PPC64_PLTGOT16_HA + -- : BFD_RELOC_PPC64_ADDR16_DS + -- : BFD_RELOC_PPC64_ADDR16_LO_DS + -- : BFD_RELOC_PPC64_GOT16_DS + -- : BFD_RELOC_PPC64_GOT16_LO_DS + -- : BFD_RELOC_PPC64_PLT16_LO_DS + -- : BFD_RELOC_PPC64_SECTOFF_DS + -- : BFD_RELOC_PPC64_SECTOFF_LO_DS + -- : BFD_RELOC_PPC64_TOC16_DS + -- : BFD_RELOC_PPC64_TOC16_LO_DS + -- : BFD_RELOC_PPC64_PLTGOT16_DS + -- : BFD_RELOC_PPC64_PLTGOT16_LO_DS + -- : BFD_RELOC_PPC64_ADDR16_HIGH + -- : BFD_RELOC_PPC64_ADDR16_HIGHA + -- : BFD_RELOC_PPC64_REL16_HIGH + -- : BFD_RELOC_PPC64_REL16_HIGHA + -- : BFD_RELOC_PPC64_REL16_HIGHER + -- : BFD_RELOC_PPC64_REL16_HIGHERA + -- : BFD_RELOC_PPC64_REL16_HIGHEST + -- : BFD_RELOC_PPC64_REL16_HIGHESTA + -- : BFD_RELOC_PPC64_ADDR64_LOCAL + -- : BFD_RELOC_PPC64_ENTRY + -- : BFD_RELOC_PPC64_REL24_NOTOC + -- : BFD_RELOC_PPC64_REL24_P9NOTOC + -- : BFD_RELOC_PPC64_D34 + -- : BFD_RELOC_PPC64_D34_LO + -- : BFD_RELOC_PPC64_D34_HI30 + -- : BFD_RELOC_PPC64_D34_HA30 + -- : BFD_RELOC_PPC64_PCREL34 + -- : BFD_RELOC_PPC64_GOT_PCREL34 + -- : BFD_RELOC_PPC64_PLT_PCREL34 + -- : BFD_RELOC_PPC64_ADDR16_HIGHER34 + -- : BFD_RELOC_PPC64_ADDR16_HIGHERA34 + -- : BFD_RELOC_PPC64_ADDR16_HIGHEST34 + -- : BFD_RELOC_PPC64_ADDR16_HIGHESTA34 + -- : BFD_RELOC_PPC64_REL16_HIGHER34 + -- : BFD_RELOC_PPC64_REL16_HIGHERA34 + -- : BFD_RELOC_PPC64_REL16_HIGHEST34 + -- : BFD_RELOC_PPC64_REL16_HIGHESTA34 + -- : BFD_RELOC_PPC64_D28 + -- : BFD_RELOC_PPC64_PCREL28 + Power(rs6000) and PowerPC relocations. + -- : BFD_RELOC_PPC_TLS + -- : BFD_RELOC_PPC_TLSGD + -- : BFD_RELOC_PPC_TLSLD + -- : BFD_RELOC_PPC_TLSLE + -- : BFD_RELOC_PPC_TLSIE + -- : BFD_RELOC_PPC_TLSM + -- : BFD_RELOC_PPC_TLSML + -- : BFD_RELOC_PPC_DTPMOD + -- : BFD_RELOC_PPC_TPREL16 + -- : BFD_RELOC_PPC_TPREL16_LO + -- : BFD_RELOC_PPC_TPREL16_HI + -- : BFD_RELOC_PPC_TPREL16_HA + -- : BFD_RELOC_PPC_TPREL + -- : BFD_RELOC_PPC_DTPREL16 + -- : BFD_RELOC_PPC_DTPREL16_LO + -- : BFD_RELOC_PPC_DTPREL16_HI + -- : BFD_RELOC_PPC_DTPREL16_HA + -- : BFD_RELOC_PPC_DTPREL + -- : BFD_RELOC_PPC_GOT_TLSGD16 + -- : BFD_RELOC_PPC_GOT_TLSGD16_LO + -- : BFD_RELOC_PPC_GOT_TLSGD16_HI + -- : BFD_RELOC_PPC_GOT_TLSGD16_HA + -- : BFD_RELOC_PPC_GOT_TLSLD16 + -- : BFD_RELOC_PPC_GOT_TLSLD16_LO + -- : BFD_RELOC_PPC_GOT_TLSLD16_HI + -- : BFD_RELOC_PPC_GOT_TLSLD16_HA + -- : BFD_RELOC_PPC_GOT_TPREL16 + -- : BFD_RELOC_PPC_GOT_TPREL16_LO + -- : BFD_RELOC_PPC_GOT_TPREL16_HI + -- : BFD_RELOC_PPC_GOT_TPREL16_HA + -- : BFD_RELOC_PPC_GOT_DTPREL16 + -- : BFD_RELOC_PPC_GOT_DTPREL16_LO + -- : BFD_RELOC_PPC_GOT_DTPREL16_HI + -- : BFD_RELOC_PPC_GOT_DTPREL16_HA + -- : BFD_RELOC_PPC64_TLSGD + -- : BFD_RELOC_PPC64_TLSLD + -- : BFD_RELOC_PPC64_TLSLE + -- : BFD_RELOC_PPC64_TLSIE + -- : BFD_RELOC_PPC64_TLSM + -- : BFD_RELOC_PPC64_TLSML + -- : BFD_RELOC_PPC64_TPREL16_DS + -- : BFD_RELOC_PPC64_TPREL16_LO_DS + -- : BFD_RELOC_PPC64_TPREL16_HIGH + -- : BFD_RELOC_PPC64_TPREL16_HIGHA + -- : BFD_RELOC_PPC64_TPREL16_HIGHER + -- : BFD_RELOC_PPC64_TPREL16_HIGHERA + -- : BFD_RELOC_PPC64_TPREL16_HIGHEST + -- : BFD_RELOC_PPC64_TPREL16_HIGHESTA + -- : BFD_RELOC_PPC64_DTPREL16_DS + -- : BFD_RELOC_PPC64_DTPREL16_LO_DS + -- : BFD_RELOC_PPC64_DTPREL16_HIGH + -- : BFD_RELOC_PPC64_DTPREL16_HIGHA + -- : BFD_RELOC_PPC64_DTPREL16_HIGHER + -- : BFD_RELOC_PPC64_DTPREL16_HIGHERA + -- : BFD_RELOC_PPC64_DTPREL16_HIGHEST + -- : BFD_RELOC_PPC64_DTPREL16_HIGHESTA + -- : BFD_RELOC_PPC64_TPREL34 + -- : BFD_RELOC_PPC64_DTPREL34 + -- : BFD_RELOC_PPC64_GOT_TLSGD_PCREL34 + -- : BFD_RELOC_PPC64_GOT_TLSLD_PCREL34 + -- : BFD_RELOC_PPC64_GOT_TPREL_PCREL34 + -- : BFD_RELOC_PPC64_GOT_DTPREL_PCREL34 + -- : BFD_RELOC_PPC64_TLS_PCREL + PowerPC and PowerPC64 thread-local storage relocations. + -- : BFD_RELOC_I370_D12 + IBM 370/390 relocations. + -- : BFD_RELOC_CTOR + The type of reloc used to build a constructor table - at the moment + probably a 32 bit wide absolute relocation, but the target can + choose. It generally does map to one of the other relocation + types. + -- : BFD_RELOC_ARM_PCREL_BRANCH + ARM 26 bit pc-relative branch. The lowest two bits must be zero + and are not stored in the instruction. + -- : BFD_RELOC_ARM_PCREL_BLX + ARM 26 bit pc-relative branch. The lowest bit must be zero and is + not stored in the instruction. The 2nd lowest bit comes from a 1 + bit field in the instruction. + -- : BFD_RELOC_THUMB_PCREL_BLX + Thumb 22 bit pc-relative branch. The lowest bit must be zero and + is not stored in the instruction. The 2nd lowest bit comes from a + 1 bit field in the instruction. + -- : BFD_RELOC_ARM_PCREL_CALL + ARM 26-bit pc-relative branch for an unconditional BL or BLX + instruction. + -- : BFD_RELOC_ARM_PCREL_JUMP + ARM 26-bit pc-relative branch for B or conditional BL instruction. + -- : BFD_RELOC_THUMB_PCREL_BRANCH5 + ARM 5-bit pc-relative branch for Branch Future instructions. + -- : BFD_RELOC_THUMB_PCREL_BFCSEL + ARM 6-bit pc-relative branch for BFCSEL instruction. + -- : BFD_RELOC_ARM_THUMB_BF17 + ARM 17-bit pc-relative branch for Branch Future instructions. + -- : BFD_RELOC_ARM_THUMB_BF13 + ARM 13-bit pc-relative branch for BFCSEL instruction. + -- : BFD_RELOC_ARM_THUMB_BF19 + ARM 19-bit pc-relative branch for Branch Future Link instruction. + -- : BFD_RELOC_ARM_THUMB_LOOP12 + ARM 12-bit pc-relative branch for Low Overhead Loop instructions. + -- : BFD_RELOC_THUMB_PCREL_BRANCH7 + -- : BFD_RELOC_THUMB_PCREL_BRANCH9 + -- : BFD_RELOC_THUMB_PCREL_BRANCH12 + -- : BFD_RELOC_THUMB_PCREL_BRANCH20 + -- : BFD_RELOC_THUMB_PCREL_BRANCH23 + -- : BFD_RELOC_THUMB_PCREL_BRANCH25 + Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. The + lowest bit must be zero and is not stored in the instruction. Note + that the corresponding ELF R_ARM_THM_JUMPnn constant has an "nn" + one smaller in all cases. Note further that BRANCH23 corresponds + to R_ARM_THM_CALL. + -- : BFD_RELOC_ARM_OFFSET_IMM + 12-bit immediate offset, used in ARM-format ldr and str + instructions. + -- : BFD_RELOC_ARM_THUMB_OFFSET + 5-bit immediate offset, used in Thumb-format ldr and str + instructions. + -- : BFD_RELOC_ARM_TARGET1 + Pc-relative or absolute relocation depending on target. Used for + entries in .init_array sections. + -- : BFD_RELOC_ARM_ROSEGREL32 + Read-only segment base relative address. + -- : BFD_RELOC_ARM_SBREL32 + Data segment base relative address. + -- : BFD_RELOC_ARM_TARGET2 + This reloc is used for references to RTTI data from exception + handling tables. The actual definition depends on the target. It + may be a pc-relative or some form of GOT-indirect relocation. + -- : BFD_RELOC_ARM_PREL31 + 31-bit PC relative address. + -- : BFD_RELOC_ARM_MOVW + -- : BFD_RELOC_ARM_MOVT + -- : BFD_RELOC_ARM_MOVW_PCREL + -- : BFD_RELOC_ARM_MOVT_PCREL + -- : BFD_RELOC_ARM_THUMB_MOVW + -- : BFD_RELOC_ARM_THUMB_MOVT + -- : BFD_RELOC_ARM_THUMB_MOVW_PCREL + -- : BFD_RELOC_ARM_THUMB_MOVT_PCREL + Low and High halfword relocations for MOVW and MOVT instructions. + -- : BFD_RELOC_ARM_GOTFUNCDESC + -- : BFD_RELOC_ARM_GOTOFFFUNCDESC + -- : BFD_RELOC_ARM_FUNCDESC + -- : BFD_RELOC_ARM_FUNCDESC_VALUE + -- : BFD_RELOC_ARM_TLS_GD32_FDPIC + -- : BFD_RELOC_ARM_TLS_LDM32_FDPIC + -- : BFD_RELOC_ARM_TLS_IE32_FDPIC + ARM FDPIC specific relocations. + -- : BFD_RELOC_ARM_JUMP_SLOT + -- : BFD_RELOC_ARM_GLOB_DAT + -- : BFD_RELOC_ARM_GOT32 + -- : BFD_RELOC_ARM_PLT32 + -- : BFD_RELOC_ARM_RELATIVE + -- : BFD_RELOC_ARM_GOTOFF + -- : BFD_RELOC_ARM_GOTPC + -- : BFD_RELOC_ARM_GOT_PREL + Relocations for setting up GOTs and PLTs for shared libraries. + -- : BFD_RELOC_ARM_TLS_GD32 + -- : BFD_RELOC_ARM_TLS_LDO32 + -- : BFD_RELOC_ARM_TLS_LDM32 + -- : BFD_RELOC_ARM_TLS_DTPOFF32 + -- : BFD_RELOC_ARM_TLS_DTPMOD32 + -- : BFD_RELOC_ARM_TLS_TPOFF32 + -- : BFD_RELOC_ARM_TLS_IE32 + -- : BFD_RELOC_ARM_TLS_LE32 + -- : BFD_RELOC_ARM_TLS_GOTDESC + -- : BFD_RELOC_ARM_TLS_CALL + -- : BFD_RELOC_ARM_THM_TLS_CALL + -- : BFD_RELOC_ARM_TLS_DESCSEQ + -- : BFD_RELOC_ARM_THM_TLS_DESCSEQ + -- : BFD_RELOC_ARM_TLS_DESC + ARM thread-local storage relocations. + -- : BFD_RELOC_ARM_ALU_PC_G0_NC + -- : BFD_RELOC_ARM_ALU_PC_G0 + -- : BFD_RELOC_ARM_ALU_PC_G1_NC + -- : BFD_RELOC_ARM_ALU_PC_G1 + -- : BFD_RELOC_ARM_ALU_PC_G2 + -- : BFD_RELOC_ARM_LDR_PC_G0 + -- : BFD_RELOC_ARM_LDR_PC_G1 + -- : BFD_RELOC_ARM_LDR_PC_G2 + -- : BFD_RELOC_ARM_LDRS_PC_G0 + -- : BFD_RELOC_ARM_LDRS_PC_G1 + -- : BFD_RELOC_ARM_LDRS_PC_G2 + -- : BFD_RELOC_ARM_LDC_PC_G0 + -- : BFD_RELOC_ARM_LDC_PC_G1 + -- : BFD_RELOC_ARM_LDC_PC_G2 + -- : BFD_RELOC_ARM_ALU_SB_G0_NC + -- : BFD_RELOC_ARM_ALU_SB_G0 + -- : BFD_RELOC_ARM_ALU_SB_G1_NC + -- : BFD_RELOC_ARM_ALU_SB_G1 + -- : BFD_RELOC_ARM_ALU_SB_G2 + -- : BFD_RELOC_ARM_LDR_SB_G0 + -- : BFD_RELOC_ARM_LDR_SB_G1 + -- : BFD_RELOC_ARM_LDR_SB_G2 + -- : BFD_RELOC_ARM_LDRS_SB_G0 + -- : BFD_RELOC_ARM_LDRS_SB_G1 + -- : BFD_RELOC_ARM_LDRS_SB_G2 + -- : BFD_RELOC_ARM_LDC_SB_G0 + -- : BFD_RELOC_ARM_LDC_SB_G1 + -- : BFD_RELOC_ARM_LDC_SB_G2 + ARM group relocations. + -- : BFD_RELOC_ARM_V4BX + Annotation of BX instructions. + -- : BFD_RELOC_ARM_IRELATIVE + ARM support for STT_GNU_IFUNC. + -- : BFD_RELOC_ARM_THUMB_ALU_ABS_G0_NC + -- : BFD_RELOC_ARM_THUMB_ALU_ABS_G1_NC + -- : BFD_RELOC_ARM_THUMB_ALU_ABS_G2_NC + -- : BFD_RELOC_ARM_THUMB_ALU_ABS_G3_NC + Thumb1 relocations to support execute-only code. + -- : BFD_RELOC_ARM_IMMEDIATE + -- : BFD_RELOC_ARM_ADRL_IMMEDIATE + -- : BFD_RELOC_ARM_T32_IMMEDIATE + -- : BFD_RELOC_ARM_T32_ADD_IMM + -- : BFD_RELOC_ARM_T32_IMM12 + -- : BFD_RELOC_ARM_T32_ADD_PC12 + -- : BFD_RELOC_ARM_SHIFT_IMM + -- : BFD_RELOC_ARM_SMC + -- : BFD_RELOC_ARM_HVC + -- : BFD_RELOC_ARM_SWI + -- : BFD_RELOC_ARM_MULTI + -- : BFD_RELOC_ARM_CP_OFF_IMM + -- : BFD_RELOC_ARM_CP_OFF_IMM_S2 + -- : BFD_RELOC_ARM_T32_CP_OFF_IMM + -- : BFD_RELOC_ARM_T32_CP_OFF_IMM_S2 + -- : BFD_RELOC_ARM_T32_VLDR_VSTR_OFF_IMM + -- : BFD_RELOC_ARM_ADR_IMM + -- : BFD_RELOC_ARM_LDR_IMM + -- : BFD_RELOC_ARM_LITERAL + -- : BFD_RELOC_ARM_IN_POOL + -- : BFD_RELOC_ARM_OFFSET_IMM8 + -- : BFD_RELOC_ARM_T32_OFFSET_U8 + -- : BFD_RELOC_ARM_T32_OFFSET_IMM + -- : BFD_RELOC_ARM_HWLITERAL + -- : BFD_RELOC_ARM_THUMB_ADD + -- : BFD_RELOC_ARM_THUMB_IMM + -- : BFD_RELOC_ARM_THUMB_SHIFT + These relocs are only used within the ARM assembler. They are not + (at present) written to any object files. + -- : BFD_RELOC_SH_PCDISP8BY2 + -- : BFD_RELOC_SH_PCDISP12BY2 + -- : BFD_RELOC_SH_IMM3 + -- : BFD_RELOC_SH_IMM3U + -- : BFD_RELOC_SH_DISP12 + -- : BFD_RELOC_SH_DISP12BY2 + -- : BFD_RELOC_SH_DISP12BY4 + -- : BFD_RELOC_SH_DISP12BY8 + -- : BFD_RELOC_SH_DISP20 + -- : BFD_RELOC_SH_DISP20BY8 + -- : BFD_RELOC_SH_IMM4 + -- : BFD_RELOC_SH_IMM4BY2 + -- : BFD_RELOC_SH_IMM4BY4 + -- : BFD_RELOC_SH_IMM8 + -- : BFD_RELOC_SH_IMM8BY2 + -- : BFD_RELOC_SH_IMM8BY4 + -- : BFD_RELOC_SH_PCRELIMM8BY2 + -- : BFD_RELOC_SH_PCRELIMM8BY4 + -- : BFD_RELOC_SH_SWITCH16 + -- : BFD_RELOC_SH_SWITCH32 + -- : BFD_RELOC_SH_USES + -- : BFD_RELOC_SH_COUNT + -- : BFD_RELOC_SH_ALIGN + -- : BFD_RELOC_SH_CODE + -- : BFD_RELOC_SH_DATA + -- : BFD_RELOC_SH_LABEL + -- : BFD_RELOC_SH_LOOP_START + -- : BFD_RELOC_SH_LOOP_END + -- : BFD_RELOC_SH_COPY + -- : BFD_RELOC_SH_GLOB_DAT + -- : BFD_RELOC_SH_JMP_SLOT + -- : BFD_RELOC_SH_RELATIVE + -- : BFD_RELOC_SH_GOTPC + -- : BFD_RELOC_SH_GOT_LOW16 + -- : BFD_RELOC_SH_GOT_MEDLOW16 + -- : BFD_RELOC_SH_GOT_MEDHI16 + -- : BFD_RELOC_SH_GOT_HI16 + -- : BFD_RELOC_SH_GOTPLT_LOW16 + -- : BFD_RELOC_SH_GOTPLT_MEDLOW16 + -- : BFD_RELOC_SH_GOTPLT_MEDHI16 + -- : BFD_RELOC_SH_GOTPLT_HI16 + -- : BFD_RELOC_SH_PLT_LOW16 + -- : BFD_RELOC_SH_PLT_MEDLOW16 + -- : BFD_RELOC_SH_PLT_MEDHI16 + -- : BFD_RELOC_SH_PLT_HI16 + -- : BFD_RELOC_SH_GOTOFF_LOW16 + -- : BFD_RELOC_SH_GOTOFF_MEDLOW16 + -- : BFD_RELOC_SH_GOTOFF_MEDHI16 + -- : BFD_RELOC_SH_GOTOFF_HI16 + -- : BFD_RELOC_SH_GOTPC_LOW16 + -- : BFD_RELOC_SH_GOTPC_MEDLOW16 + -- : BFD_RELOC_SH_GOTPC_MEDHI16 + -- : BFD_RELOC_SH_GOTPC_HI16 + -- : BFD_RELOC_SH_COPY64 + -- : BFD_RELOC_SH_GLOB_DAT64 + -- : BFD_RELOC_SH_JMP_SLOT64 + -- : BFD_RELOC_SH_RELATIVE64 + -- : BFD_RELOC_SH_GOT10BY4 + -- : BFD_RELOC_SH_GOT10BY8 + -- : BFD_RELOC_SH_GOTPLT10BY4 + -- : BFD_RELOC_SH_GOTPLT10BY8 + -- : BFD_RELOC_SH_GOTPLT32 + -- : BFD_RELOC_SH_SHMEDIA_CODE + -- : BFD_RELOC_SH_IMMU5 + -- : BFD_RELOC_SH_IMMS6 + -- : BFD_RELOC_SH_IMMS6BY32 + -- : BFD_RELOC_SH_IMMU6 + -- : BFD_RELOC_SH_IMMS10 + -- : BFD_RELOC_SH_IMMS10BY2 + -- : BFD_RELOC_SH_IMMS10BY4 + -- : BFD_RELOC_SH_IMMS10BY8 + -- : BFD_RELOC_SH_IMMS16 + -- : BFD_RELOC_SH_IMMU16 + -- : BFD_RELOC_SH_IMM_LOW16 + -- : BFD_RELOC_SH_IMM_LOW16_PCREL + -- : BFD_RELOC_SH_IMM_MEDLOW16 + -- : BFD_RELOC_SH_IMM_MEDLOW16_PCREL + -- : BFD_RELOC_SH_IMM_MEDHI16 + -- : BFD_RELOC_SH_IMM_MEDHI16_PCREL + -- : BFD_RELOC_SH_IMM_HI16 + -- : BFD_RELOC_SH_IMM_HI16_PCREL + -- : BFD_RELOC_SH_PT_16 + -- : BFD_RELOC_SH_TLS_GD_32 + -- : BFD_RELOC_SH_TLS_LD_32 + -- : BFD_RELOC_SH_TLS_LDO_32 + -- : BFD_RELOC_SH_TLS_IE_32 + -- : BFD_RELOC_SH_TLS_LE_32 + -- : BFD_RELOC_SH_TLS_DTPMOD32 + -- : BFD_RELOC_SH_TLS_DTPOFF32 + -- : BFD_RELOC_SH_TLS_TPOFF32 + -- : BFD_RELOC_SH_GOT20 + -- : BFD_RELOC_SH_GOTOFF20 + -- : BFD_RELOC_SH_GOTFUNCDESC + -- : BFD_RELOC_SH_GOTFUNCDESC20 + -- : BFD_RELOC_SH_GOTOFFFUNCDESC + -- : BFD_RELOC_SH_GOTOFFFUNCDESC20 + -- : BFD_RELOC_SH_FUNCDESC + Renesas / SuperH SH relocs. Not all of these appear in object + files. + -- : BFD_RELOC_ARC_NONE + -- : BFD_RELOC_ARC_8 + -- : BFD_RELOC_ARC_16 + -- : BFD_RELOC_ARC_24 + -- : BFD_RELOC_ARC_32 + -- : BFD_RELOC_ARC_N8 + -- : BFD_RELOC_ARC_N16 + -- : BFD_RELOC_ARC_N24 + -- : BFD_RELOC_ARC_N32 + -- : BFD_RELOC_ARC_SDA + -- : BFD_RELOC_ARC_SECTOFF + -- : BFD_RELOC_ARC_S21H_PCREL + -- : BFD_RELOC_ARC_S21W_PCREL + -- : BFD_RELOC_ARC_S25H_PCREL + -- : BFD_RELOC_ARC_S25W_PCREL + -- : BFD_RELOC_ARC_SDA32 + -- : BFD_RELOC_ARC_SDA_LDST + -- : BFD_RELOC_ARC_SDA_LDST1 + -- : BFD_RELOC_ARC_SDA_LDST2 + -- : BFD_RELOC_ARC_SDA16_LD + -- : BFD_RELOC_ARC_SDA16_LD1 + -- : BFD_RELOC_ARC_SDA16_LD2 + -- : BFD_RELOC_ARC_S13_PCREL + -- : BFD_RELOC_ARC_W + -- : BFD_RELOC_ARC_32_ME + -- : BFD_RELOC_ARC_32_ME_S + -- : BFD_RELOC_ARC_N32_ME + -- : BFD_RELOC_ARC_SECTOFF_ME + -- : BFD_RELOC_ARC_SDA32_ME + -- : BFD_RELOC_ARC_W_ME + -- : BFD_RELOC_AC_SECTOFF_U8 + -- : BFD_RELOC_AC_SECTOFF_U8_1 + -- : BFD_RELOC_AC_SECTOFF_U8_2 + -- : BFD_RELOC_AC_SECTOFF_S9 + -- : BFD_RELOC_AC_SECTOFF_S9_1 + -- : BFD_RELOC_AC_SECTOFF_S9_2 + -- : BFD_RELOC_ARC_SECTOFF_ME_1 + -- : BFD_RELOC_ARC_SECTOFF_ME_2 + -- : BFD_RELOC_ARC_SECTOFF_1 + -- : BFD_RELOC_ARC_SECTOFF_2 + -- : BFD_RELOC_ARC_SDA_12 + -- : BFD_RELOC_ARC_SDA16_ST2 + -- : BFD_RELOC_ARC_32_PCREL + -- : BFD_RELOC_ARC_PC32 + -- : BFD_RELOC_ARC_GOT32 + -- : BFD_RELOC_ARC_GOTPC32 + -- : BFD_RELOC_ARC_PLT32 + -- : BFD_RELOC_ARC_COPY + -- : BFD_RELOC_ARC_GLOB_DAT + -- : BFD_RELOC_ARC_JMP_SLOT + -- : BFD_RELOC_ARC_RELATIVE + -- : BFD_RELOC_ARC_GOTOFF + -- : BFD_RELOC_ARC_GOTPC + -- : BFD_RELOC_ARC_S21W_PCREL_PLT + -- : BFD_RELOC_ARC_S25H_PCREL_PLT + -- : BFD_RELOC_ARC_TLS_DTPMOD + -- : BFD_RELOC_ARC_TLS_TPOFF + -- : BFD_RELOC_ARC_TLS_GD_GOT + -- : BFD_RELOC_ARC_TLS_GD_LD + -- : BFD_RELOC_ARC_TLS_GD_CALL + -- : BFD_RELOC_ARC_TLS_IE_GOT + -- : BFD_RELOC_ARC_TLS_DTPOFF + -- : BFD_RELOC_ARC_TLS_DTPOFF_S9 + -- : BFD_RELOC_ARC_TLS_LE_S9 + -- : BFD_RELOC_ARC_TLS_LE_32 + -- : BFD_RELOC_ARC_S25W_PCREL_PLT + -- : BFD_RELOC_ARC_S21H_PCREL_PLT + -- : BFD_RELOC_ARC_NPS_CMEM16 + -- : BFD_RELOC_ARC_JLI_SECTOFF + ARC relocs. + -- : BFD_RELOC_BFIN_16_IMM + ADI Blackfin 16 bit immediate absolute reloc. + -- : BFD_RELOC_BFIN_16_HIGH + ADI Blackfin 16 bit immediate absolute reloc higher 16 bits. + -- : BFD_RELOC_BFIN_4_PCREL + ADI Blackfin 'a' part of LSETUP. + -- : BFD_RELOC_BFIN_5_PCREL + ADI Blackfin. + -- : BFD_RELOC_BFIN_16_LOW + ADI Blackfin 16 bit immediate absolute reloc lower 16 bits. + -- : BFD_RELOC_BFIN_10_PCREL + ADI Blackfin. + -- : BFD_RELOC_BFIN_11_PCREL + ADI Blackfin 'b' part of LSETUP. + -- : BFD_RELOC_BFIN_12_PCREL_JUMP + ADI Blackfin. + -- : BFD_RELOC_BFIN_12_PCREL_JUMP_S + ADI Blackfin Short jump, pcrel. + -- : BFD_RELOC_BFIN_24_PCREL_CALL_X + ADI Blackfin Call.x not implemented. + -- : BFD_RELOC_BFIN_24_PCREL_JUMP_L + ADI Blackfin Long Jump pcrel. + -- : BFD_RELOC_BFIN_GOT17M4 + -- : BFD_RELOC_BFIN_GOTHI + -- : BFD_RELOC_BFIN_GOTLO + -- : BFD_RELOC_BFIN_FUNCDESC + -- : BFD_RELOC_BFIN_FUNCDESC_GOT17M4 + -- : BFD_RELOC_BFIN_FUNCDESC_GOTHI + -- : BFD_RELOC_BFIN_FUNCDESC_GOTLO + -- : BFD_RELOC_BFIN_FUNCDESC_VALUE + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4 + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI + -- : BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO + -- : BFD_RELOC_BFIN_GOTOFF17M4 + -- : BFD_RELOC_BFIN_GOTOFFHI + -- : BFD_RELOC_BFIN_GOTOFFLO + ADI Blackfin FD-PIC relocations. + -- : BFD_RELOC_BFIN_GOT + ADI Blackfin GOT relocation. + -- : BFD_RELOC_BFIN_PLTPC + ADI Blackfin PLTPC relocation. + -- : BFD_ARELOC_BFIN_PUSH + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_CONST + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_ADD + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_SUB + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_MULT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_DIV + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_MOD + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LSHIFT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_RSHIFT + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_AND + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_OR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_XOR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LAND + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LOR + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_LEN + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_NEG + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_COMP + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_PAGE + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_HWPAGE + ADI Blackfin arithmetic relocation. + -- : BFD_ARELOC_BFIN_ADDR + ADI Blackfin arithmetic relocation. + -- : BFD_RELOC_D10V_10_PCREL_R + Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 + bits assumed to be 0. + -- : BFD_RELOC_D10V_10_PCREL_L + Mitsubishi D10V relocs. This is a 10-bit reloc with the right 2 + bits assumed to be 0. This is the same as the previous reloc + except it is in the left container, i.e., shifted left 15 bits. + -- : BFD_RELOC_D10V_18 + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_D10V_18_PCREL + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_D30V_6 + Mitsubishi D30V relocs. This is a 6-bit absolute reloc. + -- : BFD_RELOC_D30V_9_PCREL + This is a 6-bit pc-relative reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_9_PCREL_R + This is a 6-bit pc-relative reloc with the right 3 bits assumed to + be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_15 + This is a 12-bit absolute reloc with the right 3 bitsassumed to be + 0. + -- : BFD_RELOC_D30V_15_PCREL + This is a 12-bit pc-relative reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_15_PCREL_R + This is a 12-bit pc-relative reloc with the right 3 bits assumed to + be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_21 + This is an 18-bit absolute reloc with the right 3 bits assumed to + be 0. + -- : BFD_RELOC_D30V_21_PCREL + This is an 18-bit pc-relative reloc with the right 3 bits assumed + to be 0. + -- : BFD_RELOC_D30V_21_PCREL_R + This is an 18-bit pc-relative reloc with the right 3 bits assumed + to be 0. Same as the previous reloc but on the right side of the + container. + -- : BFD_RELOC_D30V_32 + This is a 32-bit absolute reloc. + -- : BFD_RELOC_D30V_32_PCREL + This is a 32-bit pc-relative reloc. + -- : BFD_RELOC_DLX_HI16_S + -- : BFD_RELOC_DLX_LO16 + -- : BFD_RELOC_DLX_JMP26 + DLX relocs. + -- : BFD_RELOC_M32C_HI8 + -- : BFD_RELOC_M32C_RL_JUMP + -- : BFD_RELOC_M32C_RL_1ADDR + -- : BFD_RELOC_M32C_RL_2ADDR + Renesas M16C/M32C Relocations. + -- : BFD_RELOC_M32R_24 + Renesas M32R (formerly Mitsubishi M32R) relocs. This is a 24 bit + absolute address. + -- : BFD_RELOC_M32R_10_PCREL + This is a 10-bit pc-relative reloc with the right 2 bits assumed to + be 0. + -- : BFD_RELOC_M32R_18_PCREL + This is an 18-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_M32R_26_PCREL + This is a 26-bit reloc with the right 2 bits assumed to be 0. + -- : BFD_RELOC_M32R_HI16_ULO + This is a 16-bit reloc containing the high 16 bits of an address + used when the lower 16 bits are treated as unsigned. + -- : BFD_RELOC_M32R_HI16_SLO + This is a 16-bit reloc containing the high 16 bits of an address + used when the lower 16 bits are treated as signed. + -- : BFD_RELOC_M32R_LO16 + This is a 16-bit reloc containing the lower 16 bits of an address. + -- : BFD_RELOC_M32R_SDA16 + This is a 16-bit reloc containing the small data area offset for + use in add3, load, and store instructions. + -- : BFD_RELOC_M32R_GOT24 + -- : BFD_RELOC_M32R_26_PLTREL + -- : BFD_RELOC_M32R_COPY + -- : BFD_RELOC_M32R_GLOB_DAT + -- : BFD_RELOC_M32R_JMP_SLOT + -- : BFD_RELOC_M32R_RELATIVE + -- : BFD_RELOC_M32R_GOTOFF + -- : BFD_RELOC_M32R_GOTOFF_HI_ULO + -- : BFD_RELOC_M32R_GOTOFF_HI_SLO + -- : BFD_RELOC_M32R_GOTOFF_LO + -- : BFD_RELOC_M32R_GOTPC24 + -- : BFD_RELOC_M32R_GOT16_HI_ULO + -- : BFD_RELOC_M32R_GOT16_HI_SLO + -- : BFD_RELOC_M32R_GOT16_LO + -- : BFD_RELOC_M32R_GOTPC_HI_ULO + -- : BFD_RELOC_M32R_GOTPC_HI_SLO + -- : BFD_RELOC_M32R_GOTPC_LO + For PIC. + -- : BFD_RELOC_NDS32_20 + NDS32 relocs. This is a 20 bit absolute address. + -- : BFD_RELOC_NDS32_9_PCREL + This is a 9-bit pc-relative reloc with the right 1 bit assumed to + be 0. + -- : BFD_RELOC_NDS32_WORD_9_PCREL + This is a 9-bit pc-relative reloc with the right 1 bit assumed to + be 0. + -- : BFD_RELOC_NDS32_15_PCREL + This is an 15-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_17_PCREL + This is an 17-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_25_PCREL + This is a 25-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_NDS32_HI20 + This is a 20-bit reloc containing the high 20 bits of an address + used with the lower 12 bits. + -- : BFD_RELOC_NDS32_LO12S3 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift right by 3. This is used with ldi,sdi. + -- : BFD_RELOC_NDS32_LO12S2 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 2. This is used with lwi,swi. + -- : BFD_RELOC_NDS32_LO12S1 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 1. This is used with lhi,shi. + -- : BFD_RELOC_NDS32_LO12S0 + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 0. This is used with lbisbi. + -- : BFD_RELOC_NDS32_LO12S0_ORI + This is a 12-bit reloc containing the lower 12 bits of an address + then shift left by 0. This is only used with branch relaxations. + -- : BFD_RELOC_NDS32_SDA15S3 + This is a 15-bit reloc containing the small data area 18-bit signed + offset and shift left by 3 for use in ldi, sdi. + -- : BFD_RELOC_NDS32_SDA15S2 + This is a 15-bit reloc containing the small data area 17-bit signed + offset and shift left by 2 for use in lwi, swi. + -- : BFD_RELOC_NDS32_SDA15S1 + This is a 15-bit reloc containing the small data area 16-bit signed + offset and shift left by 1 for use in lhi, shi. + -- : BFD_RELOC_NDS32_SDA15S0 + This is a 15-bit reloc containing the small data area 15-bit signed + offset and shift left by 0 for use in lbi, sbi. + -- : BFD_RELOC_NDS32_SDA16S3 + This is a 16-bit reloc containing the small data area 16-bit signed + offset and shift left by 3. + -- : BFD_RELOC_NDS32_SDA17S2 + This is a 17-bit reloc containing the small data area 17-bit signed + offset and shift left by 2 for use in lwi.gp, swi.gp. + -- : BFD_RELOC_NDS32_SDA18S1 + This is a 18-bit reloc containing the small data area 18-bit signed + offset and shift left by 1 for use in lhi.gp, shi.gp. + -- : BFD_RELOC_NDS32_SDA19S0 + This is a 19-bit reloc containing the small data area 19-bit signed + offset and shift left by 0 for use in lbi.gp, sbi.gp. + -- : BFD_RELOC_NDS32_GOT20 + -- : BFD_RELOC_NDS32_9_PLTREL + -- : BFD_RELOC_NDS32_25_PLTREL + -- : BFD_RELOC_NDS32_COPY + -- : BFD_RELOC_NDS32_GLOB_DAT + -- : BFD_RELOC_NDS32_JMP_SLOT + -- : BFD_RELOC_NDS32_RELATIVE + -- : BFD_RELOC_NDS32_GOTOFF + -- : BFD_RELOC_NDS32_GOTOFF_HI20 + -- : BFD_RELOC_NDS32_GOTOFF_LO12 + -- : BFD_RELOC_NDS32_GOTPC20 + -- : BFD_RELOC_NDS32_GOT_HI20 + -- : BFD_RELOC_NDS32_GOT_LO12 + -- : BFD_RELOC_NDS32_GOTPC_HI20 + -- : BFD_RELOC_NDS32_GOTPC_LO12 + For PIC. + -- : BFD_RELOC_NDS32_INSN16 + -- : BFD_RELOC_NDS32_LABEL + -- : BFD_RELOC_NDS32_LONGCALL1 + -- : BFD_RELOC_NDS32_LONGCALL2 + -- : BFD_RELOC_NDS32_LONGCALL3 + -- : BFD_RELOC_NDS32_LONGJUMP1 + -- : BFD_RELOC_NDS32_LONGJUMP2 + -- : BFD_RELOC_NDS32_LONGJUMP3 + -- : BFD_RELOC_NDS32_LOADSTORE + -- : BFD_RELOC_NDS32_9_FIXED + -- : BFD_RELOC_NDS32_15_FIXED + -- : BFD_RELOC_NDS32_17_FIXED + -- : BFD_RELOC_NDS32_25_FIXED + -- : BFD_RELOC_NDS32_LONGCALL4 + -- : BFD_RELOC_NDS32_LONGCALL5 + -- : BFD_RELOC_NDS32_LONGCALL6 + -- : BFD_RELOC_NDS32_LONGJUMP4 + -- : BFD_RELOC_NDS32_LONGJUMP5 + -- : BFD_RELOC_NDS32_LONGJUMP6 + -- : BFD_RELOC_NDS32_LONGJUMP7 + For relax. + -- : BFD_RELOC_NDS32_PLTREL_HI20 + -- : BFD_RELOC_NDS32_PLTREL_LO12 + -- : BFD_RELOC_NDS32_PLT_GOTREL_HI20 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO12 + For PIC. + -- : BFD_RELOC_NDS32_SDA12S2_DP + -- : BFD_RELOC_NDS32_SDA12S2_SP + -- : BFD_RELOC_NDS32_LO12S2_DP + -- : BFD_RELOC_NDS32_LO12S2_SP + For floating point. + -- : BFD_RELOC_NDS32_DWARF2_OP1 + -- : BFD_RELOC_NDS32_DWARF2_OP2 + -- : BFD_RELOC_NDS32_DWARF2_LEB + For dwarf2 debug_line. + -- : BFD_RELOC_NDS32_UPDATE_TA + For eliminating 16-bit instructions. + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO20 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO15 + -- : BFD_RELOC_NDS32_PLT_GOTREL_LO19 + -- : BFD_RELOC_NDS32_GOT_LO15 + -- : BFD_RELOC_NDS32_GOT_LO19 + -- : BFD_RELOC_NDS32_GOTOFF_LO15 + -- : BFD_RELOC_NDS32_GOTOFF_LO19 + -- : BFD_RELOC_NDS32_GOT15S2 + -- : BFD_RELOC_NDS32_GOT17S2 + For PIC object relaxation. + -- : BFD_RELOC_NDS32_5 + NDS32 relocs. This is a 5 bit absolute address. + -- : BFD_RELOC_NDS32_10_UPCREL + This is a 10-bit unsigned pc-relative reloc with the right 1 bit + assumed to be 0. + -- : BFD_RELOC_NDS32_SDA_FP7U2_RELA + If fp were omitted, fp can used as another gp. + -- : BFD_RELOC_NDS32_RELAX_ENTRY + -- : BFD_RELOC_NDS32_GOT_SUFF + -- : BFD_RELOC_NDS32_GOTOFF_SUFF + -- : BFD_RELOC_NDS32_PLT_GOT_SUFF + -- : BFD_RELOC_NDS32_MULCALL_SUFF + -- : BFD_RELOC_NDS32_PTR + -- : BFD_RELOC_NDS32_PTR_COUNT + -- : BFD_RELOC_NDS32_PTR_RESOLVED + -- : BFD_RELOC_NDS32_PLTBLOCK + -- : BFD_RELOC_NDS32_RELAX_REGION_BEGIN + -- : BFD_RELOC_NDS32_RELAX_REGION_END + -- : BFD_RELOC_NDS32_MINUEND + -- : BFD_RELOC_NDS32_SUBTRAHEND + -- : BFD_RELOC_NDS32_DIFF8 + -- : BFD_RELOC_NDS32_DIFF16 + -- : BFD_RELOC_NDS32_DIFF32 + -- : BFD_RELOC_NDS32_DIFF_ULEB128 + -- : BFD_RELOC_NDS32_EMPTY + Relaxation relative relocation types. + -- : BFD_RELOC_NDS32_25_ABS + This is a 25 bit absolute address. + -- : BFD_RELOC_NDS32_DATA + -- : BFD_RELOC_NDS32_TRAN + -- : BFD_RELOC_NDS32_17IFC_PCREL + -- : BFD_RELOC_NDS32_10IFCU_PCREL + For ex9 and ifc using. + -- : BFD_RELOC_NDS32_TPOFF + -- : BFD_RELOC_NDS32_GOTTPOFF + -- : BFD_RELOC_NDS32_TLS_LE_HI20 + -- : BFD_RELOC_NDS32_TLS_LE_LO12 + -- : BFD_RELOC_NDS32_TLS_LE_20 + -- : BFD_RELOC_NDS32_TLS_LE_15S0 + -- : BFD_RELOC_NDS32_TLS_LE_15S1 + -- : BFD_RELOC_NDS32_TLS_LE_15S2 + -- : BFD_RELOC_NDS32_TLS_LE_ADD + -- : BFD_RELOC_NDS32_TLS_LE_LS + -- : BFD_RELOC_NDS32_TLS_IE_HI20 + -- : BFD_RELOC_NDS32_TLS_IE_LO12 + -- : BFD_RELOC_NDS32_TLS_IE_LO12S2 + -- : BFD_RELOC_NDS32_TLS_IEGP_HI20 + -- : BFD_RELOC_NDS32_TLS_IEGP_LO12 + -- : BFD_RELOC_NDS32_TLS_IEGP_LO12S2 + -- : BFD_RELOC_NDS32_TLS_IEGP_LW + -- : BFD_RELOC_NDS32_TLS_DESC + -- : BFD_RELOC_NDS32_TLS_DESC_HI20 + -- : BFD_RELOC_NDS32_TLS_DESC_LO12 + -- : BFD_RELOC_NDS32_TLS_DESC_20 + -- : BFD_RELOC_NDS32_TLS_DESC_SDA17S2 + -- : BFD_RELOC_NDS32_TLS_DESC_ADD + -- : BFD_RELOC_NDS32_TLS_DESC_FUNC + -- : BFD_RELOC_NDS32_TLS_DESC_CALL + -- : BFD_RELOC_NDS32_TLS_DESC_MEM + -- : BFD_RELOC_NDS32_REMOVE + -- : BFD_RELOC_NDS32_GROUP + For TLS. + -- : BFD_RELOC_NDS32_LSI + For floating load store relaxation. + -- : BFD_RELOC_V850_9_PCREL + This is a 9-bit reloc. + -- : BFD_RELOC_V850_22_PCREL + This is a 22-bit reloc. + -- : BFD_RELOC_V850_SDA_16_16_OFFSET + This is a 16 bit offset from the short data area pointer. + -- : BFD_RELOC_V850_SDA_15_16_OFFSET + This is a 16 bit offset (of which only 15 bits are used) from the + short data area pointer. + -- : BFD_RELOC_V850_ZDA_16_16_OFFSET + This is a 16 bit offset from the zero data area pointer. + -- : BFD_RELOC_V850_ZDA_15_16_OFFSET + This is a 16 bit offset (of which only 15 bits are used) from the + zero data area pointer. + -- : BFD_RELOC_V850_TDA_6_8_OFFSET + This is an 8 bit offset (of which only 6 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_7_8_OFFSET + This is an 8bit offset (of which only 7 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_7_7_OFFSET + This is a 7 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_TDA_16_16_OFFSET + This is a 16 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_TDA_4_5_OFFSET + This is a 5 bit offset (of which only 4 bits are used) from the + tiny data area pointer. + -- : BFD_RELOC_V850_TDA_4_4_OFFSET + This is a 4 bit offset from the tiny data area pointer. + -- : BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET + This is a 16 bit offset from the short data area pointer, with the + bits placed non-contiguously in the instruction. + -- : BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET + This is a 16 bit offset from the zero data area pointer, with the + bits placed non-contiguously in the instruction. + -- : BFD_RELOC_V850_CALLT_6_7_OFFSET + This is a 6 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_CALLT_16_16_OFFSET + This is a 16 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_LONGCALL + Used for relaxing indirect function calls. + -- : BFD_RELOC_V850_LONGJUMP + Used for relaxing indirect jumps. + -- : BFD_RELOC_V850_ALIGN + Used to maintain alignment whilst relaxing. + -- : BFD_RELOC_V850_LO16_SPLIT_OFFSET + This is a variation of BFD_RELOC_LO16 that can be used in v850e + ld.bu instructions. + -- : BFD_RELOC_V850_16_PCREL + This is a 16-bit reloc. + -- : BFD_RELOC_V850_17_PCREL + This is a 17-bit reloc. + -- : BFD_RELOC_V850_23 + This is a 23-bit reloc. + -- : BFD_RELOC_V850_32_PCREL + This is a 32-bit reloc. + -- : BFD_RELOC_V850_32_ABS + This is a 32-bit reloc. + -- : BFD_RELOC_V850_16_SPLIT_OFFSET + This is a 16-bit reloc. + -- : BFD_RELOC_V850_16_S1 + This is a 16-bit reloc. + -- : BFD_RELOC_V850_LO16_S1 + Low 16 bits. 16 bit shifted by 1. + -- : BFD_RELOC_V850_CALLT_15_16_OFFSET + This is a 16 bit offset from the call table base pointer. + -- : BFD_RELOC_V850_32_GOTPCREL + -- : BFD_RELOC_V850_16_GOT + -- : BFD_RELOC_V850_32_GOT + -- : BFD_RELOC_V850_22_PLT_PCREL + -- : BFD_RELOC_V850_32_PLT_PCREL + -- : BFD_RELOC_V850_COPY + -- : BFD_RELOC_V850_GLOB_DAT + -- : BFD_RELOC_V850_JMP_SLOT + -- : BFD_RELOC_V850_RELATIVE + -- : BFD_RELOC_V850_16_GOTOFF + -- : BFD_RELOC_V850_32_GOTOFF + DSO relocations. + -- : BFD_RELOC_V850_CODE + Start code. + -- : BFD_RELOC_V850_DATA + Start data in text. + -- : BFD_RELOC_TIC30_LDP + This is a 8bit DP reloc for the tms320c30, where the most + significant 8 bits of a 24 bit word are placed into the least + significant 8 bits of the opcode. + -- : BFD_RELOC_TIC54X_PARTLS7 + This is a 7bit reloc for the tms320c54x, where the least + significant 7 bits of a 16 bit word are placed into the least + significant 7 bits of the opcode. + -- : BFD_RELOC_TIC54X_PARTMS9 + This is a 9bit DP reloc for the tms320c54x, where the most + significant 9 bits of a 16 bit word are placed into the least + significant 9 bits of the opcode. + -- : BFD_RELOC_TIC54X_23 + This is an extended address 23-bit reloc for the tms320c54x. + -- : BFD_RELOC_TIC54X_16_OF_23 + This is a 16-bit reloc for the tms320c54x, where the least + significant 16 bits of a 23-bit extended address are placed into + the opcode. + -- : BFD_RELOC_TIC54X_MS7_OF_23 + This is a reloc for the tms320c54x, where the most significant 7 + bits of a 23-bit extended address are placed into the opcode. + -- : BFD_RELOC_C6000_PCR_S21 + -- : BFD_RELOC_C6000_PCR_S12 + -- : BFD_RELOC_C6000_PCR_S10 + -- : BFD_RELOC_C6000_PCR_S7 + -- : BFD_RELOC_C6000_ABS_S16 + -- : BFD_RELOC_C6000_ABS_L16 + -- : BFD_RELOC_C6000_ABS_H16 + -- : BFD_RELOC_C6000_SBR_U15_B + -- : BFD_RELOC_C6000_SBR_U15_H + -- : BFD_RELOC_C6000_SBR_U15_W + -- : BFD_RELOC_C6000_SBR_S16 + -- : BFD_RELOC_C6000_SBR_L16_B + -- : BFD_RELOC_C6000_SBR_L16_H + -- : BFD_RELOC_C6000_SBR_L16_W + -- : BFD_RELOC_C6000_SBR_H16_B + -- : BFD_RELOC_C6000_SBR_H16_H + -- : BFD_RELOC_C6000_SBR_H16_W + -- : BFD_RELOC_C6000_SBR_GOT_U15_W + -- : BFD_RELOC_C6000_SBR_GOT_L16_W + -- : BFD_RELOC_C6000_SBR_GOT_H16_W + -- : BFD_RELOC_C6000_DSBT_INDEX + -- : BFD_RELOC_C6000_PREL31 + -- : BFD_RELOC_C6000_COPY + -- : BFD_RELOC_C6000_JUMP_SLOT + -- : BFD_RELOC_C6000_EHTYPE + -- : BFD_RELOC_C6000_PCR_H16 + -- : BFD_RELOC_C6000_PCR_L16 + -- : BFD_RELOC_C6000_ALIGN + -- : BFD_RELOC_C6000_FPHEAD + -- : BFD_RELOC_C6000_NOCMP + TMS320C6000 relocations. + -- : BFD_RELOC_FR30_48 + This is a 48 bit reloc for the FR30 that stores 32 bits. + -- : BFD_RELOC_FR30_20 + This is a 32 bit reloc for the FR30 that stores 20 bits split up + into two sections. + -- : BFD_RELOC_FR30_6_IN_4 + This is a 16 bit reloc for the FR30 that stores a 6 bit word offset + in 4 bits. + -- : BFD_RELOC_FR30_8_IN_8 + This is a 16 bit reloc for the FR30 that stores an 8 bit byte + offset into 8 bits. + -- : BFD_RELOC_FR30_9_IN_8 + This is a 16 bit reloc for the FR30 that stores a 9 bit short + offset into 8 bits. + -- : BFD_RELOC_FR30_10_IN_8 + This is a 16 bit reloc for the FR30 that stores a 10 bit word + offset into 8 bits. + -- : BFD_RELOC_FR30_9_PCREL + This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative + short offset into 8 bits. + -- : BFD_RELOC_FR30_12_PCREL + This is a 16 bit reloc for the FR30 that stores a 12 bit pc + relative short offset into 11 bits. + -- : BFD_RELOC_MCORE_PCREL_IMM8BY4 + -- : BFD_RELOC_MCORE_PCREL_IMM11BY2 + -- : BFD_RELOC_MCORE_PCREL_IMM4BY2 + -- : BFD_RELOC_MCORE_PCREL_32 + -- : BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2 + -- : BFD_RELOC_MCORE_RVA + Motorola Mcore relocations. + -- : BFD_RELOC_MEP_8 + -- : BFD_RELOC_MEP_16 + -- : BFD_RELOC_MEP_32 + -- : BFD_RELOC_MEP_PCREL8A2 + -- : BFD_RELOC_MEP_PCREL12A2 + -- : BFD_RELOC_MEP_PCREL17A2 + -- : BFD_RELOC_MEP_PCREL24A2 + -- : BFD_RELOC_MEP_PCABS24A2 + -- : BFD_RELOC_MEP_LOW16 + -- : BFD_RELOC_MEP_HI16U + -- : BFD_RELOC_MEP_HI16S + -- : BFD_RELOC_MEP_GPREL + -- : BFD_RELOC_MEP_TPREL + -- : BFD_RELOC_MEP_TPREL7 + -- : BFD_RELOC_MEP_TPREL7A2 + -- : BFD_RELOC_MEP_TPREL7A4 + -- : BFD_RELOC_MEP_UIMM24 + -- : BFD_RELOC_MEP_ADDR24A4 + -- : BFD_RELOC_MEP_GNU_VTINHERIT + -- : BFD_RELOC_MEP_GNU_VTENTRY + Toshiba Media Processor Relocations. + -- : BFD_RELOC_METAG_HIADDR16 + -- : BFD_RELOC_METAG_LOADDR16 + -- : BFD_RELOC_METAG_RELBRANCH + -- : BFD_RELOC_METAG_GETSETOFF + -- : BFD_RELOC_METAG_HIOG + -- : BFD_RELOC_METAG_LOOG + -- : BFD_RELOC_METAG_REL8 + -- : BFD_RELOC_METAG_REL16 + -- : BFD_RELOC_METAG_HI16_GOTOFF + -- : BFD_RELOC_METAG_LO16_GOTOFF + -- : BFD_RELOC_METAG_GETSET_GOTOFF + -- : BFD_RELOC_METAG_GETSET_GOT + -- : BFD_RELOC_METAG_HI16_GOTPC + -- : BFD_RELOC_METAG_LO16_GOTPC + -- : BFD_RELOC_METAG_HI16_PLT + -- : BFD_RELOC_METAG_LO16_PLT + -- : BFD_RELOC_METAG_RELBRANCH_PLT + -- : BFD_RELOC_METAG_GOTOFF + -- : BFD_RELOC_METAG_PLT + -- : BFD_RELOC_METAG_COPY + -- : BFD_RELOC_METAG_JMP_SLOT + -- : BFD_RELOC_METAG_RELATIVE + -- : BFD_RELOC_METAG_GLOB_DAT + -- : BFD_RELOC_METAG_TLS_GD + -- : BFD_RELOC_METAG_TLS_LDM + -- : BFD_RELOC_METAG_TLS_LDO_HI16 + -- : BFD_RELOC_METAG_TLS_LDO_LO16 + -- : BFD_RELOC_METAG_TLS_LDO + -- : BFD_RELOC_METAG_TLS_IE + -- : BFD_RELOC_METAG_TLS_IENONPIC + -- : BFD_RELOC_METAG_TLS_IENONPIC_HI16 + -- : BFD_RELOC_METAG_TLS_IENONPIC_LO16 + -- : BFD_RELOC_METAG_TLS_TPOFF + -- : BFD_RELOC_METAG_TLS_DTPMOD + -- : BFD_RELOC_METAG_TLS_DTPOFF + -- : BFD_RELOC_METAG_TLS_LE + -- : BFD_RELOC_METAG_TLS_LE_HI16 + -- : BFD_RELOC_METAG_TLS_LE_LO16 + Imagination Technologies Meta relocations. + -- : BFD_RELOC_MMIX_GETA + -- : BFD_RELOC_MMIX_GETA_1 + -- : BFD_RELOC_MMIX_GETA_2 + -- : BFD_RELOC_MMIX_GETA_3 + These are relocations for the GETA instruction. + -- : BFD_RELOC_MMIX_CBRANCH + -- : BFD_RELOC_MMIX_CBRANCH_J + -- : BFD_RELOC_MMIX_CBRANCH_1 + -- : BFD_RELOC_MMIX_CBRANCH_2 + -- : BFD_RELOC_MMIX_CBRANCH_3 + These are relocations for a conditional branch instruction. + -- : BFD_RELOC_MMIX_PUSHJ + -- : BFD_RELOC_MMIX_PUSHJ_1 + -- : BFD_RELOC_MMIX_PUSHJ_2 + -- : BFD_RELOC_MMIX_PUSHJ_3 + -- : BFD_RELOC_MMIX_PUSHJ_STUBBABLE + These are relocations for the PUSHJ instruction. + -- : BFD_RELOC_MMIX_JMP + -- : BFD_RELOC_MMIX_JMP_1 + -- : BFD_RELOC_MMIX_JMP_2 + -- : BFD_RELOC_MMIX_JMP_3 + These are relocations for the JMP instruction. + -- : BFD_RELOC_MMIX_ADDR19 + This is a relocation for a relative address as in a GETA + instruction or a branch. + -- : BFD_RELOC_MMIX_ADDR27 + This is a relocation for a relative address as in a JMP + instruction. + -- : BFD_RELOC_MMIX_REG_OR_BYTE + This is a relocation for an instruction field that may be a general + register or a value 0..255. + -- : BFD_RELOC_MMIX_REG + This is a relocation for an instruction field that may be a general + register. + -- : BFD_RELOC_MMIX_BASE_PLUS_OFFSET + This is a relocation for two instruction fields holding a register + and an offset, the equivalent of the relocation. + -- : BFD_RELOC_MMIX_LOCAL + This relocation is an assertion that the expression is not + allocated as a global register. It does not modify contents. + -- : BFD_RELOC_AVR_7_PCREL + This is a 16 bit reloc for the AVR that stores 8 bit pc relative + short offset into 7 bits. + -- : BFD_RELOC_AVR_13_PCREL + This is a 16 bit reloc for the AVR that stores 13 bit pc relative + short offset into 12 bits. + -- : BFD_RELOC_AVR_16_PM + This is a 16 bit reloc for the AVR that stores 17 bit value + (usually program memory address) into 16 bits. + -- : BFD_RELOC_AVR_LO8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (usually + data memory address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HI8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of data memory address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HH8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of program memory address) into 8 bit immediate value of + LDI insn. + -- : BFD_RELOC_AVR_MS8_LDI + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of 32 bit value) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (usually data memory address) into 8 bit immediate value of SUBI + insn. + -- : BFD_RELOC_AVR_HI8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 8 bit of data memory address) into 8 bit immediate value of + SUBI insn. + -- : BFD_RELOC_AVR_HH8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (most high 8 bit of program memory address) into 8 bit immediate + value of LDI or SUBI insn. + -- : BFD_RELOC_AVR_MS8_LDI_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (msb of 32 bit value) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (usually + command address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_LO8_LDI_GS + This is a 16 bit reloc for the AVR that stores 8 bit value (command + address) into 8 bit immediate value of LDI insn. If the address is + beyond the 128k boundary, the linker inserts a jump stub for this + reloc in the lower 128k. + -- : BFD_RELOC_AVR_HI8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of command address) into 8 bit immediate value of LDI insn. + -- : BFD_RELOC_AVR_HI8_LDI_GS + This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 + bit of command address) into 8 bit immediate value of LDI insn. If + the address is beyond the 128k boundary, the linker inserts a jump + stub for this reloc below 128k. + -- : BFD_RELOC_AVR_HH8_LDI_PM + This is a 16 bit reloc for the AVR that stores 8 bit value (most + high 8 bit of command address) into 8 bit immediate value of LDI + insn. + -- : BFD_RELOC_AVR_LO8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (usually command address) into 8 bit immediate value of SUBI insn. + -- : BFD_RELOC_AVR_HI8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 8 bit of 16 bit command address) into 8 bit immediate value + of SUBI insn. + -- : BFD_RELOC_AVR_HH8_LDI_PM_NEG + This is a 16 bit reloc for the AVR that stores negated 8 bit value + (high 6 bit of 22 bit command address) into 8 bit immediate value + of SUBI insn. + -- : BFD_RELOC_AVR_CALL + This is a 32 bit reloc for the AVR that stores 23 bit value into 22 + bits. + -- : BFD_RELOC_AVR_LDI + This is a 16 bit reloc for the AVR that stores all needed bits for + absolute addressing with ldi with overflow check to linktime. + -- : BFD_RELOC_AVR_6 + This is a 6 bit reloc for the AVR that stores offset for ldd/std + instructions. + -- : BFD_RELOC_AVR_6_ADIW + This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw + instructions. + -- : BFD_RELOC_AVR_8_LO + This is a 8 bit reloc for the AVR that stores bits 0..7 of a symbol + in .byte lo8(symbol). + -- : BFD_RELOC_AVR_8_HI + This is a 8 bit reloc for the AVR that stores bits 8..15 of a + symbol in .byte hi8(symbol). + -- : BFD_RELOC_AVR_8_HLO + This is a 8 bit reloc for the AVR that stores bits 16..23 of a + symbol in .byte hlo8(symbol). + -- : BFD_RELOC_AVR_DIFF8 + -- : BFD_RELOC_AVR_DIFF16 + -- : BFD_RELOC_AVR_DIFF32 + AVR relocations to mark the difference of two local symbols. These + are only needed to support linker relaxation and can be ignored + when not relaxing. The field is set to the value of the difference + assuming no relaxation. The relocation encodes the position of the + second symbol so the linker can determine whether to adjust the + field value. + -- : BFD_RELOC_AVR_LDS_STS_16 + This is a 7 bit reloc for the AVR that stores SRAM address for + 16bit lds and sts instructions supported only tiny core. + -- : BFD_RELOC_AVR_PORT6 + This is a 6 bit reloc for the AVR that stores an I/O register + number for the IN and OUT instructions. + -- : BFD_RELOC_AVR_PORT5 + This is a 5 bit reloc for the AVR that stores an I/O register + number for the SBIC, SBIS, SBI and CBI instructions. + -- : BFD_RELOC_RISCV_HI20 + -- : BFD_RELOC_RISCV_PCREL_HI20 + -- : BFD_RELOC_RISCV_PCREL_LO12_I + -- : BFD_RELOC_RISCV_PCREL_LO12_S + -- : BFD_RELOC_RISCV_LO12_I + -- : BFD_RELOC_RISCV_LO12_S + -- : BFD_RELOC_RISCV_GPREL12_I + -- : BFD_RELOC_RISCV_GPREL12_S + -- : BFD_RELOC_RISCV_TPREL_HI20 + -- : BFD_RELOC_RISCV_TPREL_LO12_I + -- : BFD_RELOC_RISCV_TPREL_LO12_S + -- : BFD_RELOC_RISCV_TPREL_ADD + -- : BFD_RELOC_RISCV_CALL + -- : BFD_RELOC_RISCV_CALL_PLT + -- : BFD_RELOC_RISCV_ADD8 + -- : BFD_RELOC_RISCV_ADD16 + -- : BFD_RELOC_RISCV_ADD32 + -- : BFD_RELOC_RISCV_ADD64 + -- : BFD_RELOC_RISCV_SUB8 + -- : BFD_RELOC_RISCV_SUB16 + -- : BFD_RELOC_RISCV_SUB32 + -- : BFD_RELOC_RISCV_SUB64 + -- : BFD_RELOC_RISCV_GOT_HI20 + -- : BFD_RELOC_RISCV_TLS_GOT_HI20 + -- : BFD_RELOC_RISCV_TLS_GD_HI20 + -- : BFD_RELOC_RISCV_JMP + -- : BFD_RELOC_RISCV_TLS_DTPMOD32 + -- : BFD_RELOC_RISCV_TLS_DTPREL32 + -- : BFD_RELOC_RISCV_TLS_DTPMOD64 + -- : BFD_RELOC_RISCV_TLS_DTPREL64 + -- : BFD_RELOC_RISCV_TLS_TPREL32 + -- : BFD_RELOC_RISCV_TLS_TPREL64 + -- : BFD_RELOC_RISCV_TLSDESC_HI20 + -- : BFD_RELOC_RISCV_TLSDESC_LOAD_LO12 + -- : BFD_RELOC_RISCV_TLSDESC_ADD_LO12 + -- : BFD_RELOC_RISCV_TLSDESC_CALL + -- : BFD_RELOC_RISCV_ALIGN + -- : BFD_RELOC_RISCV_RVC_BRANCH + -- : BFD_RELOC_RISCV_RVC_JUMP + -- : BFD_RELOC_RISCV_RELAX + -- : BFD_RELOC_RISCV_CFA + -- : BFD_RELOC_RISCV_SUB6 + -- : BFD_RELOC_RISCV_SET6 + -- : BFD_RELOC_RISCV_SET8 + -- : BFD_RELOC_RISCV_SET16 + -- : BFD_RELOC_RISCV_SET32 + -- : BFD_RELOC_RISCV_32_PCREL + -- : BFD_RELOC_RISCV_SET_ULEB128 + -- : BFD_RELOC_RISCV_SUB_ULEB128 + RISC-V relocations. + -- : BFD_RELOC_RL78_NEG8 + -- : BFD_RELOC_RL78_NEG16 + -- : BFD_RELOC_RL78_NEG24 + -- : BFD_RELOC_RL78_NEG32 + -- : BFD_RELOC_RL78_16_OP + -- : BFD_RELOC_RL78_24_OP + -- : BFD_RELOC_RL78_32_OP + -- : BFD_RELOC_RL78_8U + -- : BFD_RELOC_RL78_16U + -- : BFD_RELOC_RL78_24U + -- : BFD_RELOC_RL78_DIR3U_PCREL + -- : BFD_RELOC_RL78_DIFF + -- : BFD_RELOC_RL78_GPRELB + -- : BFD_RELOC_RL78_GPRELW + -- : BFD_RELOC_RL78_GPRELL + -- : BFD_RELOC_RL78_SYM + -- : BFD_RELOC_RL78_OP_SUBTRACT + -- : BFD_RELOC_RL78_OP_NEG + -- : BFD_RELOC_RL78_OP_AND + -- : BFD_RELOC_RL78_OP_SHRA + -- : BFD_RELOC_RL78_ABS8 + -- : BFD_RELOC_RL78_ABS16 + -- : BFD_RELOC_RL78_ABS16_REV + -- : BFD_RELOC_RL78_ABS32 + -- : BFD_RELOC_RL78_ABS32_REV + -- : BFD_RELOC_RL78_ABS16U + -- : BFD_RELOC_RL78_ABS16UW + -- : BFD_RELOC_RL78_ABS16UL + -- : BFD_RELOC_RL78_RELAX + -- : BFD_RELOC_RL78_HI16 + -- : BFD_RELOC_RL78_HI8 + -- : BFD_RELOC_RL78_LO16 + -- : BFD_RELOC_RL78_CODE + -- : BFD_RELOC_RL78_SADDR + Renesas RL78 Relocations. + -- : BFD_RELOC_RX_NEG8 + -- : BFD_RELOC_RX_NEG16 + -- : BFD_RELOC_RX_NEG24 + -- : BFD_RELOC_RX_NEG32 + -- : BFD_RELOC_RX_16_OP + -- : BFD_RELOC_RX_24_OP + -- : BFD_RELOC_RX_32_OP + -- : BFD_RELOC_RX_8U + -- : BFD_RELOC_RX_16U + -- : BFD_RELOC_RX_24U + -- : BFD_RELOC_RX_DIR3U_PCREL + -- : BFD_RELOC_RX_DIFF + -- : BFD_RELOC_RX_GPRELB + -- : BFD_RELOC_RX_GPRELW + -- : BFD_RELOC_RX_GPRELL + -- : BFD_RELOC_RX_SYM + -- : BFD_RELOC_RX_OP_SUBTRACT + -- : BFD_RELOC_RX_OP_NEG + -- : BFD_RELOC_RX_ABS8 + -- : BFD_RELOC_RX_ABS16 + -- : BFD_RELOC_RX_ABS16_REV + -- : BFD_RELOC_RX_ABS32 + -- : BFD_RELOC_RX_ABS32_REV + -- : BFD_RELOC_RX_ABS16U + -- : BFD_RELOC_RX_ABS16UW + -- : BFD_RELOC_RX_ABS16UL + -- : BFD_RELOC_RX_RELAX + Renesas RX Relocations. + -- : BFD_RELOC_390_12 + Direct 12 bit. + -- : BFD_RELOC_390_GOT12 + 12 bit GOT offset. + -- : BFD_RELOC_390_PLT32 + 32 bit PC relative PLT address. + -- : BFD_RELOC_390_COPY + Copy symbol at runtime. + -- : BFD_RELOC_390_GLOB_DAT + Create GOT entry. + -- : BFD_RELOC_390_JMP_SLOT + Create PLT entry. + -- : BFD_RELOC_390_RELATIVE + Adjust by program base. + -- : BFD_RELOC_390_GOTPC + 32 bit PC relative offset to GOT. + -- : BFD_RELOC_390_GOT16 + 16 bit GOT offset. + -- : BFD_RELOC_390_PC12DBL + PC relative 12 bit shifted by 1. + -- : BFD_RELOC_390_PLT12DBL + 12 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC16DBL + PC relative 16 bit shifted by 1. + -- : BFD_RELOC_390_PLT16DBL + 16 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC24DBL + PC relative 24 bit shifted by 1. + -- : BFD_RELOC_390_PLT24DBL + 24 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_PC32DBL + PC relative 32 bit shifted by 1. + -- : BFD_RELOC_390_PLT32DBL + 32 bit PC rel. PLT shifted by 1. + -- : BFD_RELOC_390_GOTPCDBL + 32 bit PC rel. GOT shifted by 1. + -- : BFD_RELOC_390_GOT64 + 64 bit GOT offset. + -- : BFD_RELOC_390_PLT64 + 64 bit PC relative PLT address. + -- : BFD_RELOC_390_GOTENT + 32 bit rel. offset to GOT entry. + -- : BFD_RELOC_390_GOTOFF64 + 64 bit offset to GOT. + -- : BFD_RELOC_390_GOTPLT12 + 12-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT16 + 16-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT32 + 32-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLT64 + 64-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_GOTPLTENT + 32-bit rel. offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_390_PLTOFF16 + 16-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_PLTOFF32 + 32-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_PLTOFF64 + 64-bit rel. offset from the GOT to a PLT entry. + -- : BFD_RELOC_390_TLS_LOAD + -- : BFD_RELOC_390_TLS_GDCALL + -- : BFD_RELOC_390_TLS_LDCALL + -- : BFD_RELOC_390_TLS_GD32 + -- : BFD_RELOC_390_TLS_GD64 + -- : BFD_RELOC_390_TLS_GOTIE12 + -- : BFD_RELOC_390_TLS_GOTIE32 + -- : BFD_RELOC_390_TLS_GOTIE64 + -- : BFD_RELOC_390_TLS_LDM32 + -- : BFD_RELOC_390_TLS_LDM64 + -- : BFD_RELOC_390_TLS_IE32 + -- : BFD_RELOC_390_TLS_IE64 + -- : BFD_RELOC_390_TLS_IEENT + -- : BFD_RELOC_390_TLS_LE32 + -- : BFD_RELOC_390_TLS_LE64 + -- : BFD_RELOC_390_TLS_LDO32 + -- : BFD_RELOC_390_TLS_LDO64 + -- : BFD_RELOC_390_TLS_DTPMOD + -- : BFD_RELOC_390_TLS_DTPOFF + -- : BFD_RELOC_390_TLS_TPOFF + s390 tls relocations. + -- : BFD_RELOC_390_20 + -- : BFD_RELOC_390_GOT20 + -- : BFD_RELOC_390_GOTPLT20 + -- : BFD_RELOC_390_TLS_GOTIE20 + Long displacement extension. + -- : BFD_RELOC_390_IRELATIVE + STT_GNU_IFUNC relocation. + -- : BFD_RELOC_SCORE_GPREL15 + Score relocations. Low 16 bit for load/store. + -- : BFD_RELOC_SCORE_DUMMY2 + -- : BFD_RELOC_SCORE_JMP + This is a 24-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_SCORE_BRANCH + This is a 19-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_SCORE_IMM30 + This is a 32-bit reloc for 48-bit instructions. + -- : BFD_RELOC_SCORE_IMM32 + This is a 32-bit reloc for 48-bit instructions. + -- : BFD_RELOC_SCORE16_JMP + This is a 11-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_SCORE16_BRANCH + This is a 8-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_SCORE_BCMP + This is a 9-bit reloc with the right 1 bit assumed to be 0. + -- : BFD_RELOC_SCORE_GOT15 + -- : BFD_RELOC_SCORE_GOT_LO16 + -- : BFD_RELOC_SCORE_CALL15 + -- : BFD_RELOC_SCORE_DUMMY_HI16 + Undocumented Score relocs. + -- : BFD_RELOC_IP2K_FR9 + Scenix IP2K - 9-bit register number / data address. + -- : BFD_RELOC_IP2K_BANK + Scenix IP2K - 4-bit register/data bank number. + -- : BFD_RELOC_IP2K_ADDR16CJP + Scenix IP2K - low 13 bits of instruction word address. + -- : BFD_RELOC_IP2K_PAGE3 + Scenix IP2K - high 3 bits of instruction word address. + -- : BFD_RELOC_IP2K_LO8DATA + -- : BFD_RELOC_IP2K_HI8DATA + -- : BFD_RELOC_IP2K_EX8DATA + Scenix IP2K - ext/low/high 8 bits of data address. + -- : BFD_RELOC_IP2K_LO8INSN + -- : BFD_RELOC_IP2K_HI8INSN + Scenix IP2K - low/high 8 bits of instruction word address. + -- : BFD_RELOC_IP2K_PC_SKIP + Scenix IP2K - even/odd PC modifier to modify snb pcl.0. + -- : BFD_RELOC_IP2K_TEXT + Scenix IP2K - 16 bit word address in text section. + -- : BFD_RELOC_IP2K_FR_OFFSET + Scenix IP2K - 7-bit sp or dp offset. + -- : BFD_RELOC_VPE4KMATH_DATA + -- : BFD_RELOC_VPE4KMATH_INSN + Scenix VPE4K coprocessor - data/insn-space addressing. + -- : BFD_RELOC_VTABLE_INHERIT + -- : BFD_RELOC_VTABLE_ENTRY + These two relocations are used by the linker to determine which of + the entries in a C++ virtual function table are actually used. + When the -gc-sections option is given, the linker will zero out the + entries that are not used, so that the code for those functions + need not be included in the output. + + VTABLE_INHERIT is a zero-space relocation used to describe to the + linker the inheritance tree of a C++ virtual function table. The + relocation's symbol should be the parent class' vtable, and the + relocation should be located at the child vtable. + + VTABLE_ENTRY is a zero-space relocation that describes the use of a + virtual function table entry. The reloc's symbol should refer to + the table of the class mentioned in the code. Off of that base, an + offset describes the entry that is being used. For Rela hosts, + this offset is stored in the reloc's addend. For Rel hosts, we are + forced to put this offset in the reloc's section offset. + -- : BFD_RELOC_IA64_IMM14 + -- : BFD_RELOC_IA64_IMM22 + -- : BFD_RELOC_IA64_IMM64 + -- : BFD_RELOC_IA64_DIR32MSB + -- : BFD_RELOC_IA64_DIR32LSB + -- : BFD_RELOC_IA64_DIR64MSB + -- : BFD_RELOC_IA64_DIR64LSB + -- : BFD_RELOC_IA64_GPREL22 + -- : BFD_RELOC_IA64_GPREL64I + -- : BFD_RELOC_IA64_GPREL32MSB + -- : BFD_RELOC_IA64_GPREL32LSB + -- : BFD_RELOC_IA64_GPREL64MSB + -- : BFD_RELOC_IA64_GPREL64LSB + -- : BFD_RELOC_IA64_LTOFF22 + -- : BFD_RELOC_IA64_LTOFF64I + -- : BFD_RELOC_IA64_PLTOFF22 + -- : BFD_RELOC_IA64_PLTOFF64I + -- : BFD_RELOC_IA64_PLTOFF64MSB + -- : BFD_RELOC_IA64_PLTOFF64LSB + -- : BFD_RELOC_IA64_FPTR64I + -- : BFD_RELOC_IA64_FPTR32MSB + -- : BFD_RELOC_IA64_FPTR32LSB + -- : BFD_RELOC_IA64_FPTR64MSB + -- : BFD_RELOC_IA64_FPTR64LSB + -- : BFD_RELOC_IA64_PCREL21B + -- : BFD_RELOC_IA64_PCREL21BI + -- : BFD_RELOC_IA64_PCREL21M + -- : BFD_RELOC_IA64_PCREL21F + -- : BFD_RELOC_IA64_PCREL22 + -- : BFD_RELOC_IA64_PCREL60B + -- : BFD_RELOC_IA64_PCREL64I + -- : BFD_RELOC_IA64_PCREL32MSB + -- : BFD_RELOC_IA64_PCREL32LSB + -- : BFD_RELOC_IA64_PCREL64MSB + -- : BFD_RELOC_IA64_PCREL64LSB + -- : BFD_RELOC_IA64_LTOFF_FPTR22 + -- : BFD_RELOC_IA64_LTOFF_FPTR64I + -- : BFD_RELOC_IA64_LTOFF_FPTR32MSB + -- : BFD_RELOC_IA64_LTOFF_FPTR32LSB + -- : BFD_RELOC_IA64_LTOFF_FPTR64MSB + -- : BFD_RELOC_IA64_LTOFF_FPTR64LSB + -- : BFD_RELOC_IA64_SEGREL32MSB + -- : BFD_RELOC_IA64_SEGREL32LSB + -- : BFD_RELOC_IA64_SEGREL64MSB + -- : BFD_RELOC_IA64_SEGREL64LSB + -- : BFD_RELOC_IA64_SECREL32MSB + -- : BFD_RELOC_IA64_SECREL32LSB + -- : BFD_RELOC_IA64_SECREL64MSB + -- : BFD_RELOC_IA64_SECREL64LSB + -- : BFD_RELOC_IA64_REL32MSB + -- : BFD_RELOC_IA64_REL32LSB + -- : BFD_RELOC_IA64_REL64MSB + -- : BFD_RELOC_IA64_REL64LSB + -- : BFD_RELOC_IA64_LTV32MSB + -- : BFD_RELOC_IA64_LTV32LSB + -- : BFD_RELOC_IA64_LTV64MSB + -- : BFD_RELOC_IA64_LTV64LSB + -- : BFD_RELOC_IA64_IPLTMSB + -- : BFD_RELOC_IA64_IPLTLSB + -- : BFD_RELOC_IA64_COPY + -- : BFD_RELOC_IA64_LTOFF22X + -- : BFD_RELOC_IA64_LDXMOV + -- : BFD_RELOC_IA64_TPREL14 + -- : BFD_RELOC_IA64_TPREL22 + -- : BFD_RELOC_IA64_TPREL64I + -- : BFD_RELOC_IA64_TPREL64MSB + -- : BFD_RELOC_IA64_TPREL64LSB + -- : BFD_RELOC_IA64_LTOFF_TPREL22 + -- : BFD_RELOC_IA64_DTPMOD64MSB + -- : BFD_RELOC_IA64_DTPMOD64LSB + -- : BFD_RELOC_IA64_LTOFF_DTPMOD22 + -- : BFD_RELOC_IA64_DTPREL14 + -- : BFD_RELOC_IA64_DTPREL22 + -- : BFD_RELOC_IA64_DTPREL64I + -- : BFD_RELOC_IA64_DTPREL32MSB + -- : BFD_RELOC_IA64_DTPREL32LSB + -- : BFD_RELOC_IA64_DTPREL64MSB + -- : BFD_RELOC_IA64_DTPREL64LSB + -- : BFD_RELOC_IA64_LTOFF_DTPREL22 + Intel IA64 Relocations. + -- : BFD_RELOC_M68HC11_HI8 + Motorola 68HC11 reloc. This is the 8 bit high part of an absolute + address. + -- : BFD_RELOC_M68HC11_LO8 + Motorola 68HC11 reloc. This is the 8 bit low part of an absolute + address. + -- : BFD_RELOC_M68HC11_3B + Motorola 68HC11 reloc. This is the 3 bit of a value. + -- : BFD_RELOC_M68HC11_RL_JUMP + Motorola 68HC11 reloc. This reloc marks the beginning of a + jump/call instruction. It is used for linker relaxation to + correctly identify beginning of instruction and change some + branches to use PC-relative addressing mode. + -- : BFD_RELOC_M68HC11_RL_GROUP + Motorola 68HC11 reloc. This reloc marks a group of several + instructions that gcc generates and for which the linker relaxation + pass can modify and/or remove some of them. + -- : BFD_RELOC_M68HC11_LO16 + Motorola 68HC11 reloc. This is the 16-bit lower part of an + address. It is used for 'call' instruction to specify the symbol + address without any special transformation (due to memory bank + window). + -- : BFD_RELOC_M68HC11_PAGE + Motorola 68HC11 reloc. This is a 8-bit reloc that specifies the + page number of an address. It is used by 'call' instruction to + specify the page number of the symbol. + -- : BFD_RELOC_M68HC11_24 + Motorola 68HC11 reloc. This is a 24-bit reloc that represents the + address with a 16-bit value and a 8-bit page number. The symbol + address is transformed to follow the 16K memory bank of 68HC12 + (seen as mapped in the window). + -- : BFD_RELOC_M68HC12_5B + Motorola 68HC12 reloc. This is the 5 bits of a value. + -- : BFD_RELOC_XGATE_RL_JUMP + Freescale XGATE reloc. This reloc marks the beginning of a bra/jal + instruction. + -- : BFD_RELOC_XGATE_RL_GROUP + Freescale XGATE reloc. This reloc marks a group of several + instructions that gcc generates and for which the linker relaxation + pass can modify and/or remove some of them. + -- : BFD_RELOC_XGATE_LO16 + Freescale XGATE reloc. This is the 16-bit lower part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_GPAGE + Freescale XGATE reloc. + -- : BFD_RELOC_XGATE_24 + Freescale XGATE reloc. + -- : BFD_RELOC_XGATE_PCREL_9 + Freescale XGATE reloc. This is a 9-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_PCREL_10 + Freescale XGATE reloc. This is a 10-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM8_LO + Freescale XGATE reloc. This is the 16-bit lower part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_IMM8_HI + Freescale XGATE reloc. This is the 16-bit higher part of an + address. It is used for the '16-bit' instructions. + -- : BFD_RELOC_XGATE_IMM3 + Freescale XGATE reloc. This is a 3-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM4 + Freescale XGATE reloc. This is a 4-bit pc-relative reloc. + -- : BFD_RELOC_XGATE_IMM5 + Freescale XGATE reloc. This is a 5-bit pc-relative reloc. + -- : BFD_RELOC_M68HC12_9B + Motorola 68HC12 reloc. This is the 9 bits of a value. + -- : BFD_RELOC_M68HC12_16B + Motorola 68HC12 reloc. This is the 16 bits of a value. + -- : BFD_RELOC_M68HC12_9_PCREL + Motorola 68HC12/XGATE reloc. This is a PCREL9 branch. + -- : BFD_RELOC_M68HC12_10_PCREL + Motorola 68HC12/XGATE reloc. This is a PCREL10 branch. + -- : BFD_RELOC_M68HC12_LO8XG + Motorola 68HC12/XGATE reloc. This is the 8 bit low part of an + absolute address and immediately precedes a matching HI8XG part. + -- : BFD_RELOC_M68HC12_HI8XG + Motorola 68HC12/XGATE reloc. This is the 8 bit high part of an + absolute address and immediately follows a matching LO8XG part. + -- : BFD_RELOC_S12Z_15_PCREL + Freescale S12Z reloc. This is a 15 bit relative address. If the + most significant bits are all zero then it may be truncated to 8 + bits. + -- : BFD_RELOC_CR16_NUM8 + -- : BFD_RELOC_CR16_NUM16 + -- : BFD_RELOC_CR16_NUM32 + -- : BFD_RELOC_CR16_NUM32a + -- : BFD_RELOC_CR16_REGREL0 + -- : BFD_RELOC_CR16_REGREL4 + -- : BFD_RELOC_CR16_REGREL4a + -- : BFD_RELOC_CR16_REGREL14 + -- : BFD_RELOC_CR16_REGREL14a + -- : BFD_RELOC_CR16_REGREL16 + -- : BFD_RELOC_CR16_REGREL20 + -- : BFD_RELOC_CR16_REGREL20a + -- : BFD_RELOC_CR16_ABS20 + -- : BFD_RELOC_CR16_ABS24 + -- : BFD_RELOC_CR16_IMM4 + -- : BFD_RELOC_CR16_IMM8 + -- : BFD_RELOC_CR16_IMM16 + -- : BFD_RELOC_CR16_IMM20 + -- : BFD_RELOC_CR16_IMM24 + -- : BFD_RELOC_CR16_IMM32 + -- : BFD_RELOC_CR16_IMM32a + -- : BFD_RELOC_CR16_DISP4 + -- : BFD_RELOC_CR16_DISP8 + -- : BFD_RELOC_CR16_DISP16 + -- : BFD_RELOC_CR16_DISP20 + -- : BFD_RELOC_CR16_DISP24 + -- : BFD_RELOC_CR16_DISP24a + -- : BFD_RELOC_CR16_SWITCH8 + -- : BFD_RELOC_CR16_SWITCH16 + -- : BFD_RELOC_CR16_SWITCH32 + -- : BFD_RELOC_CR16_GOT_REGREL20 + -- : BFD_RELOC_CR16_GOTC_REGREL20 + -- : BFD_RELOC_CR16_GLOB_DAT + NS CR16 Relocations. + -- : BFD_RELOC_CRX_REL4 + -- : BFD_RELOC_CRX_REL8 + -- : BFD_RELOC_CRX_REL8_CMP + -- : BFD_RELOC_CRX_REL16 + -- : BFD_RELOC_CRX_REL24 + -- : BFD_RELOC_CRX_REL32 + -- : BFD_RELOC_CRX_REGREL12 + -- : BFD_RELOC_CRX_REGREL22 + -- : BFD_RELOC_CRX_REGREL28 + -- : BFD_RELOC_CRX_REGREL32 + -- : BFD_RELOC_CRX_ABS16 + -- : BFD_RELOC_CRX_ABS32 + -- : BFD_RELOC_CRX_NUM8 + -- : BFD_RELOC_CRX_NUM16 + -- : BFD_RELOC_CRX_NUM32 + -- : BFD_RELOC_CRX_IMM16 + -- : BFD_RELOC_CRX_IMM32 + -- : BFD_RELOC_CRX_SWITCH8 + -- : BFD_RELOC_CRX_SWITCH16 + -- : BFD_RELOC_CRX_SWITCH32 + NS CRX Relocations. + -- : BFD_RELOC_CRIS_BDISP8 + -- : BFD_RELOC_CRIS_UNSIGNED_5 + -- : BFD_RELOC_CRIS_SIGNED_6 + -- : BFD_RELOC_CRIS_UNSIGNED_6 + -- : BFD_RELOC_CRIS_SIGNED_8 + -- : BFD_RELOC_CRIS_UNSIGNED_8 + -- : BFD_RELOC_CRIS_SIGNED_16 + -- : BFD_RELOC_CRIS_UNSIGNED_16 + -- : BFD_RELOC_CRIS_LAPCQ_OFFSET + -- : BFD_RELOC_CRIS_UNSIGNED_4 + These relocs are only used within the CRIS assembler. They are not + (at present) written to any object files. + -- : BFD_RELOC_CRIS_COPY + -- : BFD_RELOC_CRIS_GLOB_DAT + -- : BFD_RELOC_CRIS_JUMP_SLOT + -- : BFD_RELOC_CRIS_RELATIVE + Relocs used in ELF shared libraries for CRIS. + -- : BFD_RELOC_CRIS_32_GOT + 32-bit offset to symbol-entry within GOT. + -- : BFD_RELOC_CRIS_16_GOT + 16-bit offset to symbol-entry within GOT. + -- : BFD_RELOC_CRIS_32_GOTPLT + 32-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_CRIS_16_GOTPLT + 16-bit offset to symbol-entry within GOT, with PLT handling. + -- : BFD_RELOC_CRIS_32_GOTREL + 32-bit offset to symbol, relative to GOT. + -- : BFD_RELOC_CRIS_32_PLT_GOTREL + 32-bit offset to symbol with PLT entry, relative to GOT. + -- : BFD_RELOC_CRIS_32_PLT_PCREL + 32-bit offset to symbol with PLT entry, relative to this + relocation. + -- : BFD_RELOC_CRIS_32_GOT_GD + -- : BFD_RELOC_CRIS_16_GOT_GD + -- : BFD_RELOC_CRIS_32_GD + -- : BFD_RELOC_CRIS_DTP + -- : BFD_RELOC_CRIS_32_DTPREL + -- : BFD_RELOC_CRIS_16_DTPREL + -- : BFD_RELOC_CRIS_32_GOT_TPREL + -- : BFD_RELOC_CRIS_16_GOT_TPREL + -- : BFD_RELOC_CRIS_32_TPREL + -- : BFD_RELOC_CRIS_16_TPREL + -- : BFD_RELOC_CRIS_DTPMOD + -- : BFD_RELOC_CRIS_32_IE + Relocs used in TLS code for CRIS. + -- : BFD_RELOC_OR1K_REL_26 + -- : BFD_RELOC_OR1K_SLO16 + -- : BFD_RELOC_OR1K_PCREL_PG21 + -- : BFD_RELOC_OR1K_LO13 + -- : BFD_RELOC_OR1K_SLO13 + -- : BFD_RELOC_OR1K_GOTPC_HI16 + -- : BFD_RELOC_OR1K_GOTPC_LO16 + -- : BFD_RELOC_OR1K_GOT_AHI16 + -- : BFD_RELOC_OR1K_GOT16 + -- : BFD_RELOC_OR1K_GOT_PG21 + -- : BFD_RELOC_OR1K_GOT_LO13 + -- : BFD_RELOC_OR1K_PLT26 + -- : BFD_RELOC_OR1K_PLTA26 + -- : BFD_RELOC_OR1K_GOTOFF_SLO16 + -- : BFD_RELOC_OR1K_COPY + -- : BFD_RELOC_OR1K_GLOB_DAT + -- : BFD_RELOC_OR1K_JMP_SLOT + -- : BFD_RELOC_OR1K_RELATIVE + -- : BFD_RELOC_OR1K_TLS_GD_HI16 + -- : BFD_RELOC_OR1K_TLS_GD_LO16 + -- : BFD_RELOC_OR1K_TLS_GD_PG21 + -- : BFD_RELOC_OR1K_TLS_GD_LO13 + -- : BFD_RELOC_OR1K_TLS_LDM_HI16 + -- : BFD_RELOC_OR1K_TLS_LDM_LO16 + -- : BFD_RELOC_OR1K_TLS_LDM_PG21 + -- : BFD_RELOC_OR1K_TLS_LDM_LO13 + -- : BFD_RELOC_OR1K_TLS_LDO_HI16 + -- : BFD_RELOC_OR1K_TLS_LDO_LO16 + -- : BFD_RELOC_OR1K_TLS_IE_HI16 + -- : BFD_RELOC_OR1K_TLS_IE_AHI16 + -- : BFD_RELOC_OR1K_TLS_IE_LO16 + -- : BFD_RELOC_OR1K_TLS_IE_PG21 + -- : BFD_RELOC_OR1K_TLS_IE_LO13 + -- : BFD_RELOC_OR1K_TLS_LE_HI16 + -- : BFD_RELOC_OR1K_TLS_LE_AHI16 + -- : BFD_RELOC_OR1K_TLS_LE_LO16 + -- : BFD_RELOC_OR1K_TLS_LE_SLO16 + -- : BFD_RELOC_OR1K_TLS_TPOFF + -- : BFD_RELOC_OR1K_TLS_DTPOFF + -- : BFD_RELOC_OR1K_TLS_DTPMOD + OpenRISC 1000 Relocations. + -- : BFD_RELOC_H8_DIR16A8 + -- : BFD_RELOC_H8_DIR16R8 + -- : BFD_RELOC_H8_DIR24A8 + -- : BFD_RELOC_H8_DIR24R8 + -- : BFD_RELOC_H8_DIR32A16 + -- : BFD_RELOC_H8_DISP32A16 + H8 elf Relocations. + -- : BFD_RELOC_XSTORMY16_REL_12 + -- : BFD_RELOC_XSTORMY16_12 + -- : BFD_RELOC_XSTORMY16_24 + -- : BFD_RELOC_XSTORMY16_FPTR16 + Sony Xstormy16 Relocations. + -- : BFD_RELOC_RELC + Self-describing complex relocations. + -- : BFD_RELOC_VAX_GLOB_DAT + -- : BFD_RELOC_VAX_JMP_SLOT + -- : BFD_RELOC_VAX_RELATIVE + Relocations used by VAX ELF. + -- : BFD_RELOC_MT_PC16 + Morpho MT - 16 bit immediate relocation. + -- : BFD_RELOC_MT_HI16 + Morpho MT - Hi 16 bits of an address. + -- : BFD_RELOC_MT_LO16 + Morpho MT - Low 16 bits of an address. + -- : BFD_RELOC_MT_GNU_VTINHERIT + Morpho MT - Used to tell the linker which vtable entries are used. + -- : BFD_RELOC_MT_GNU_VTENTRY + Morpho MT - Used to tell the linker which vtable entries are used. + -- : BFD_RELOC_MT_PCINSN8 + Morpho MT - 8 bit immediate relocation. + -- : BFD_RELOC_MSP430_10_PCREL + -- : BFD_RELOC_MSP430_16_PCREL + -- : BFD_RELOC_MSP430_16 + -- : BFD_RELOC_MSP430_16_PCREL_BYTE + -- : BFD_RELOC_MSP430_16_BYTE + -- : BFD_RELOC_MSP430_2X_PCREL + -- : BFD_RELOC_MSP430_RL_PCREL + -- : BFD_RELOC_MSP430_ABS8 + -- : BFD_RELOC_MSP430X_PCR20_EXT_SRC + -- : BFD_RELOC_MSP430X_PCR20_EXT_DST + -- : BFD_RELOC_MSP430X_PCR20_EXT_ODST + -- : BFD_RELOC_MSP430X_ABS20_EXT_SRC + -- : BFD_RELOC_MSP430X_ABS20_EXT_DST + -- : BFD_RELOC_MSP430X_ABS20_EXT_ODST + -- : BFD_RELOC_MSP430X_ABS20_ADR_SRC + -- : BFD_RELOC_MSP430X_ABS20_ADR_DST + -- : BFD_RELOC_MSP430X_PCR16 + -- : BFD_RELOC_MSP430X_PCR20_CALL + -- : BFD_RELOC_MSP430X_ABS16 + -- : BFD_RELOC_MSP430_ABS_HI16 + -- : BFD_RELOC_MSP430_PREL31 + -- : BFD_RELOC_MSP430_SYM_DIFF + -- : BFD_RELOC_MSP430_SET_ULEB128 + -- : BFD_RELOC_MSP430_SUB_ULEB128 + msp430 specific relocation codes. + -- : BFD_RELOC_PRU_U16 + PRU LDI 16-bit unsigned data-memory relocation. + -- : BFD_RELOC_PRU_U16_PMEMIMM + PRU LDI 16-bit unsigned instruction-memory relocation. + -- : BFD_RELOC_PRU_LDI32 + PRU relocation for two consecutive LDI load instructions that load + a 32 bit value into a register. If the higher bits are all zero, + then the second instruction may be relaxed. + -- : BFD_RELOC_PRU_S10_PCREL + PRU QBBx 10-bit signed PC-relative relocation. + -- : BFD_RELOC_PRU_U8_PCREL + PRU 8-bit unsigned relocation used for the LOOP instruction. + -- : BFD_RELOC_PRU_32_PMEM + -- : BFD_RELOC_PRU_16_PMEM + PRU Program Memory relocations. Used to convert from byte + addressing to 32-bit word addressing. + -- : BFD_RELOC_PRU_GNU_DIFF8 + -- : BFD_RELOC_PRU_GNU_DIFF16 + -- : BFD_RELOC_PRU_GNU_DIFF32 + -- : BFD_RELOC_PRU_GNU_DIFF16_PMEM + -- : BFD_RELOC_PRU_GNU_DIFF32_PMEM + PRU relocations to mark the difference of two local symbols. These + are only needed to support linker relaxation and can be ignored + when not relaxing. The field is set to the value of the difference + assuming no relaxation. The relocation encodes the position of the + second symbol so the linker can determine whether to adjust the + field value. The PMEM variants encode the word difference, instead + of byte difference between symbols. + -- : BFD_RELOC_IQ2000_OFFSET_16 + -- : BFD_RELOC_IQ2000_OFFSET_21 + -- : BFD_RELOC_IQ2000_UHI16 + IQ2000 Relocations. + -- : BFD_RELOC_XTENSA_RTLD + Special Xtensa relocation used only by PLT entries in ELF shared + objects to indicate that the runtime linker should set the value to + one of its own internal functions or data structures. + -- : BFD_RELOC_XTENSA_GLOB_DAT + -- : BFD_RELOC_XTENSA_JMP_SLOT + -- : BFD_RELOC_XTENSA_RELATIVE + Xtensa relocations for ELF shared objects. + -- : BFD_RELOC_XTENSA_PLT + Xtensa relocation used in ELF object files for symbols that may + require PLT entries. Otherwise, this is just a generic 32-bit + relocation. + -- : BFD_RELOC_XTENSA_DIFF8 + -- : BFD_RELOC_XTENSA_DIFF16 + -- : BFD_RELOC_XTENSA_DIFF32 + Xtensa relocations for backward compatibility. These have been + replaced by BFD_RELOC_XTENSA_PDIFF and BFD_RELOC_XTENSA_NDIFF. + Xtensa relocations to mark the difference of two local symbols. + These are only needed to support linker relaxation and can be + ignored when not relaxing. The field is set to the value of the + difference assuming no relaxation. The relocation encodes the + position of the first symbol so the linker can determine whether to + adjust the field value. + -- : BFD_RELOC_XTENSA_SLOT0_OP + -- : BFD_RELOC_XTENSA_SLOT1_OP + -- : BFD_RELOC_XTENSA_SLOT2_OP + -- : BFD_RELOC_XTENSA_SLOT3_OP + -- : BFD_RELOC_XTENSA_SLOT4_OP + -- : BFD_RELOC_XTENSA_SLOT5_OP + -- : BFD_RELOC_XTENSA_SLOT6_OP + -- : BFD_RELOC_XTENSA_SLOT7_OP + -- : BFD_RELOC_XTENSA_SLOT8_OP + -- : BFD_RELOC_XTENSA_SLOT9_OP + -- : BFD_RELOC_XTENSA_SLOT10_OP + -- : BFD_RELOC_XTENSA_SLOT11_OP + -- : BFD_RELOC_XTENSA_SLOT12_OP + -- : BFD_RELOC_XTENSA_SLOT13_OP + -- : BFD_RELOC_XTENSA_SLOT14_OP + Generic Xtensa relocations for instruction operands. Only the slot + number is encoded in the relocation. The relocation applies to the + last PC-relative immediate operand, or if there are no PC-relative + immediates, to the last immediate operand. + -- : BFD_RELOC_XTENSA_SLOT0_ALT + -- : BFD_RELOC_XTENSA_SLOT1_ALT + -- : BFD_RELOC_XTENSA_SLOT2_ALT + -- : BFD_RELOC_XTENSA_SLOT3_ALT + -- : BFD_RELOC_XTENSA_SLOT4_ALT + -- : BFD_RELOC_XTENSA_SLOT5_ALT + -- : BFD_RELOC_XTENSA_SLOT6_ALT + -- : BFD_RELOC_XTENSA_SLOT7_ALT + -- : BFD_RELOC_XTENSA_SLOT8_ALT + -- : BFD_RELOC_XTENSA_SLOT9_ALT + -- : BFD_RELOC_XTENSA_SLOT10_ALT + -- : BFD_RELOC_XTENSA_SLOT11_ALT + -- : BFD_RELOC_XTENSA_SLOT12_ALT + -- : BFD_RELOC_XTENSA_SLOT13_ALT + -- : BFD_RELOC_XTENSA_SLOT14_ALT + Alternate Xtensa relocations. Only the slot is encoded in the + relocation. The meaning of these relocations is opcode-specific. + -- : BFD_RELOC_XTENSA_OP0 + -- : BFD_RELOC_XTENSA_OP1 + -- : BFD_RELOC_XTENSA_OP2 + Xtensa relocations for backward compatibility. These have all been + replaced by BFD_RELOC_XTENSA_SLOT0_OP. + -- : BFD_RELOC_XTENSA_ASM_EXPAND + Xtensa relocation to mark that the assembler expanded the + instructions from an original target. The expansion size is + encoded in the reloc size. + -- : BFD_RELOC_XTENSA_ASM_SIMPLIFY + Xtensa relocation to mark that the linker should simplify + assembler-expanded instructions. This is commonly used internally + by the linker after analysis of a BFD_RELOC_XTENSA_ASM_EXPAND. + -- : BFD_RELOC_XTENSA_TLSDESC_FN + -- : BFD_RELOC_XTENSA_TLSDESC_ARG + -- : BFD_RELOC_XTENSA_TLS_DTPOFF + -- : BFD_RELOC_XTENSA_TLS_TPOFF + -- : BFD_RELOC_XTENSA_TLS_FUNC + -- : BFD_RELOC_XTENSA_TLS_ARG + -- : BFD_RELOC_XTENSA_TLS_CALL + Xtensa TLS relocations. + -- : BFD_RELOC_XTENSA_PDIFF8 + -- : BFD_RELOC_XTENSA_PDIFF16 + -- : BFD_RELOC_XTENSA_PDIFF32 + -- : BFD_RELOC_XTENSA_NDIFF8 + -- : BFD_RELOC_XTENSA_NDIFF16 + -- : BFD_RELOC_XTENSA_NDIFF32 + Xtensa relocations to mark the difference of two local symbols. + These are only needed to support linker relaxation and can be + ignored when not relaxing. The field is set to the value of the + difference assuming no relaxation. The relocation encodes the + position of the subtracted symbol so the linker can determine + whether to adjust the field value. PDIFF relocations are used for + positive differences, NDIFF relocations are used for negative + differences. The difference value is treated as unsigned with + these relocation types, giving full 8/16 value ranges. + -- : BFD_RELOC_Z80_DISP8 + 8 bit signed offset in (ix+d) or (iy+d). + -- : BFD_RELOC_Z80_BYTE0 + First 8 bits of multibyte (32, 24 or 16 bit) value. + -- : BFD_RELOC_Z80_BYTE1 + Second 8 bits of multibyte (32, 24 or 16 bit) value. + -- : BFD_RELOC_Z80_BYTE2 + Third 8 bits of multibyte (32 or 24 bit) value. + -- : BFD_RELOC_Z80_BYTE3 + Fourth 8 bits of multibyte (32 bit) value. + -- : BFD_RELOC_Z80_WORD0 + Lowest 16 bits of multibyte (32 or 24 bit) value. + -- : BFD_RELOC_Z80_WORD1 + Highest 16 bits of multibyte (32 or 24 bit) value. + -- : BFD_RELOC_Z80_16_BE + Like BFD_RELOC_16 but big-endian. + -- : BFD_RELOC_Z8K_DISP7 + DJNZ offset. + -- : BFD_RELOC_Z8K_CALLR + CALR offset. + -- : BFD_RELOC_Z8K_IMM4L + 4 bit value. + -- : BFD_RELOC_LM32_CALL + -- : BFD_RELOC_LM32_BRANCH + -- : BFD_RELOC_LM32_16_GOT + -- : BFD_RELOC_LM32_GOTOFF_HI16 + -- : BFD_RELOC_LM32_GOTOFF_LO16 + -- : BFD_RELOC_LM32_COPY + -- : BFD_RELOC_LM32_GLOB_DAT + -- : BFD_RELOC_LM32_JMP_SLOT + -- : BFD_RELOC_LM32_RELATIVE + Lattice Mico32 relocations. + -- : BFD_RELOC_MACH_O_SECTDIFF + Difference between two section addreses. Must be followed by a + BFD_RELOC_MACH_O_PAIR. + -- : BFD_RELOC_MACH_O_LOCAL_SECTDIFF + Like BFD_RELOC_MACH_O_SECTDIFF but with a local symbol. + -- : BFD_RELOC_MACH_O_PAIR + Pair of relocation. Contains the first symbol. + -- : BFD_RELOC_MACH_O_SUBTRACTOR32 + Symbol will be substracted. Must be followed by a BFD_RELOC_32. + -- : BFD_RELOC_MACH_O_SUBTRACTOR64 + Symbol will be substracted. Must be followed by a BFD_RELOC_64. + -- : BFD_RELOC_MACH_O_X86_64_BRANCH32 + -- : BFD_RELOC_MACH_O_X86_64_BRANCH8 + PCREL relocations. They are marked as branch to create PLT entry + if required. + -- : BFD_RELOC_MACH_O_X86_64_GOT + Used when referencing a GOT entry. + -- : BFD_RELOC_MACH_O_X86_64_GOT_LOAD + Used when loading a GOT entry with movq. It is specially marked so + that the linker could optimize the movq to a leaq if possible. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_1 + Same as BFD_RELOC_32_PCREL but with an implicit -1 addend. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_2 + Same as BFD_RELOC_32_PCREL but with an implicit -2 addend. + -- : BFD_RELOC_MACH_O_X86_64_PCREL32_4 + Same as BFD_RELOC_32_PCREL but with an implicit -4 addend. + -- : BFD_RELOC_MACH_O_X86_64_TLV + Used when referencing a TLV entry. + -- : BFD_RELOC_MACH_O_ARM64_ADDEND + Addend for PAGE or PAGEOFF. + -- : BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGE21 + Relative offset to page of GOT slot. + -- : BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGEOFF12 + Relative offset within page of GOT slot. + -- : BFD_RELOC_MACH_O_ARM64_POINTER_TO_GOT + Address of a GOT entry. + -- : BFD_RELOC_MICROBLAZE_32_LO + This is a 32 bit reloc for the microblaze that stores the low 16 + bits of a value. + -- : BFD_RELOC_MICROBLAZE_32_LO_PCREL + This is a 32 bit pc-relative reloc for the microblaze that stores + the low 16 bits of a value. + -- : BFD_RELOC_MICROBLAZE_32_ROSDA + This is a 32 bit reloc for the microblaze that stores a value + relative to the read-only small data area anchor. + -- : BFD_RELOC_MICROBLAZE_32_RWSDA + This is a 32 bit reloc for the microblaze that stores a value + relative to the read-write small data area anchor. + -- : BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM + This is a 32 bit reloc for the microblaze to handle expressions of + the form "Symbol Op Symbol". + -- : BFD_RELOC_MICROBLAZE_32_NONE + This is a 32 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing. + -- : BFD_RELOC_MICROBLAZE_64_NONE + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). No relocation is done here - + only used for relaxing. + -- : BFD_RELOC_MICROBLAZE_64_GOTPC + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is PC-relative + GOT offset. + -- : BFD_RELOC_MICROBLAZE_64_GOT + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is GOT offset. + -- : BFD_RELOC_MICROBLAZE_64_PLT + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is PC-relative + offset into PLT. + -- : BFD_RELOC_MICROBLAZE_64_GOTOFF + This is a 64 bit reloc that stores the 32 bit GOT relative value in + two words (with an imm instruction). The relocation is relative + offset from _GLOBAL_OFFSET_TABLE_. + -- : BFD_RELOC_MICROBLAZE_32_GOTOFF + This is a 32 bit reloc that stores the 32 bit GOT relative value in + a word. The relocation is relative offset from + _GLOBAL_OFFSET_TABLE_. + -- : BFD_RELOC_MICROBLAZE_COPY + This is used to tell the dynamic linker to copy the value out of + the dynamic object into the runtime process image. + -- : BFD_RELOC_MICROBLAZE_64_TLS + Unused Reloc. + -- : BFD_RELOC_MICROBLAZE_64_TLSGD + This is a 64 bit reloc that stores the 32 bit GOT relative value of + the GOT TLS GD info entry in two words (with an imm instruction). + The relocation is GOT offset. + -- : BFD_RELOC_MICROBLAZE_64_TLSLD + This is a 64 bit reloc that stores the 32 bit GOT relative value of + the GOT TLS LD info entry in two words (with an imm instruction). + The relocation is GOT offset. + -- : BFD_RELOC_MICROBLAZE_32_TLSDTPMOD + This is a 32 bit reloc that stores the Module ID to GOT(n). + -- : BFD_RELOC_MICROBLAZE_32_TLSDTPREL + This is a 32 bit reloc that stores TLS offset to GOT(n+1). + -- : BFD_RELOC_MICROBLAZE_64_TLSDTPREL + This is a 32 bit reloc for storing TLS offset to two words (uses + imm instruction). + -- : BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL + This is a 64 bit reloc that stores 32-bit thread pointer relative + offset to two words (uses imm instruction). + -- : BFD_RELOC_MICROBLAZE_64_TLSTPREL + This is a 64 bit reloc that stores 32-bit thread pointer relative + offset to two words (uses imm instruction). + -- : BFD_RELOC_MICROBLAZE_64_TEXTPCREL + This is a 64 bit reloc that stores the 32 bit pc relative value in + two words (with an imm instruction). The relocation is PC-relative + offset from start of TEXT. + -- : BFD_RELOC_MICROBLAZE_64_TEXTREL + This is a 64 bit reloc that stores the 32 bit offset value in two + words (with an imm instruction). The relocation is relative offset + from start of TEXT. + -- : BFD_RELOC_KVX_RELOC_START + KVX pseudo relocation code to mark the start of the KVX relocation + enumerators. N.B. the order of the enumerators is important as + several tables in the KVX bfd backend are indexed by these + enumerators; make sure they are all synced. + -- : BFD_RELOC_KVX_NONE + KVX null relocation code. + -- : BFD_RELOC_KVX_16 + -- : BFD_RELOC_KVX_32 + -- : BFD_RELOC_KVX_64 + -- : BFD_RELOC_KVX_S16_PCREL + -- : BFD_RELOC_KVX_PCREL17 + -- : BFD_RELOC_KVX_PCREL27 + -- : BFD_RELOC_KVX_32_PCREL + -- : BFD_RELOC_KVX_S37_PCREL_LO10 + -- : BFD_RELOC_KVX_S37_PCREL_UP27 + -- : BFD_RELOC_KVX_S43_PCREL_LO10 + -- : BFD_RELOC_KVX_S43_PCREL_UP27 + -- : BFD_RELOC_KVX_S43_PCREL_EX6 + -- : BFD_RELOC_KVX_S64_PCREL_LO10 + -- : BFD_RELOC_KVX_S64_PCREL_UP27 + -- : BFD_RELOC_KVX_S64_PCREL_EX27 + -- : BFD_RELOC_KVX_64_PCREL + -- : BFD_RELOC_KVX_S16 + -- : BFD_RELOC_KVX_S32_LO5 + -- : BFD_RELOC_KVX_S32_UP27 + -- : BFD_RELOC_KVX_S37_LO10 + -- : BFD_RELOC_KVX_S37_UP27 + -- : BFD_RELOC_KVX_S37_GOTOFF_LO10 + -- : BFD_RELOC_KVX_S37_GOTOFF_UP27 + -- : BFD_RELOC_KVX_S43_GOTOFF_LO10 + -- : BFD_RELOC_KVX_S43_GOTOFF_UP27 + -- : BFD_RELOC_KVX_S43_GOTOFF_EX6 + -- : BFD_RELOC_KVX_32_GOTOFF + -- : BFD_RELOC_KVX_64_GOTOFF + -- : BFD_RELOC_KVX_32_GOT + -- : BFD_RELOC_KVX_S37_GOT_LO10 + -- : BFD_RELOC_KVX_S37_GOT_UP27 + -- : BFD_RELOC_KVX_S43_GOT_LO10 + -- : BFD_RELOC_KVX_S43_GOT_UP27 + -- : BFD_RELOC_KVX_S43_GOT_EX6 + -- : BFD_RELOC_KVX_64_GOT + -- : BFD_RELOC_KVX_GLOB_DAT + -- : BFD_RELOC_KVX_COPY + -- : BFD_RELOC_KVX_JMP_SLOT + -- : BFD_RELOC_KVX_RELATIVE + -- : BFD_RELOC_KVX_S43_LO10 + -- : BFD_RELOC_KVX_S43_UP27 + -- : BFD_RELOC_KVX_S43_EX6 + -- : BFD_RELOC_KVX_S64_LO10 + -- : BFD_RELOC_KVX_S64_UP27 + -- : BFD_RELOC_KVX_S64_EX27 + -- : BFD_RELOC_KVX_S37_GOTADDR_LO10 + -- : BFD_RELOC_KVX_S37_GOTADDR_UP27 + -- : BFD_RELOC_KVX_S43_GOTADDR_LO10 + -- : BFD_RELOC_KVX_S43_GOTADDR_UP27 + -- : BFD_RELOC_KVX_S43_GOTADDR_EX6 + -- : BFD_RELOC_KVX_S64_GOTADDR_LO10 + -- : BFD_RELOC_KVX_S64_GOTADDR_UP27 + -- : BFD_RELOC_KVX_S64_GOTADDR_EX27 + -- : BFD_RELOC_KVX_64_DTPMOD + -- : BFD_RELOC_KVX_64_DTPOFF + -- : BFD_RELOC_KVX_S37_TLS_DTPOFF_LO10 + -- : BFD_RELOC_KVX_S37_TLS_DTPOFF_UP27 + -- : BFD_RELOC_KVX_S43_TLS_DTPOFF_LO10 + -- : BFD_RELOC_KVX_S43_TLS_DTPOFF_UP27 + -- : BFD_RELOC_KVX_S43_TLS_DTPOFF_EX6 + -- : BFD_RELOC_KVX_S37_TLS_GD_LO10 + -- : BFD_RELOC_KVX_S37_TLS_GD_UP27 + -- : BFD_RELOC_KVX_S43_TLS_GD_LO10 + -- : BFD_RELOC_KVX_S43_TLS_GD_UP27 + -- : BFD_RELOC_KVX_S43_TLS_GD_EX6 + -- : BFD_RELOC_KVX_S37_TLS_LD_LO10 + -- : BFD_RELOC_KVX_S37_TLS_LD_UP27 + -- : BFD_RELOC_KVX_S43_TLS_LD_LO10 + -- : BFD_RELOC_KVX_S43_TLS_LD_UP27 + -- : BFD_RELOC_KVX_S43_TLS_LD_EX6 + -- : BFD_RELOC_KVX_64_TPOFF + -- : BFD_RELOC_KVX_S37_TLS_IE_LO10 + -- : BFD_RELOC_KVX_S37_TLS_IE_UP27 + -- : BFD_RELOC_KVX_S43_TLS_IE_LO10 + -- : BFD_RELOC_KVX_S43_TLS_IE_UP27 + -- : BFD_RELOC_KVX_S43_TLS_IE_EX6 + -- : BFD_RELOC_KVX_S37_TLS_LE_LO10 + -- : BFD_RELOC_KVX_S37_TLS_LE_UP27 + -- : BFD_RELOC_KVX_S43_TLS_LE_LO10 + -- : BFD_RELOC_KVX_S43_TLS_LE_UP27 + -- : BFD_RELOC_KVX_S43_TLS_LE_EX6 + -- : BFD_RELOC_KVX_8 + KVX Relocations. + -- : BFD_RELOC_KVX_RELOC_END + KVX pseudo relocation code to mark the end of the KVX relocation + enumerators that have direct mapping to ELF reloc codes. There are + a few more enumerators after this one; those are mainly used by the + KVX assembler for the internal fixup or to select one of the above + enumerators. + -- : BFD_RELOC_AARCH64_RELOC_START + AArch64 pseudo relocation code to mark the start of the AArch64 + relocation enumerators. N.B. the order of the enumerators is + important as several tables in the AArch64 bfd backend are indexed + by these enumerators; make sure they are all synced. + -- : BFD_RELOC_AARCH64_NULL + Deprecated AArch64 null relocation code. + -- : BFD_RELOC_AARCH64_NONE + AArch64 null relocation code. + -- : BFD_RELOC_AARCH64_64 + -- : BFD_RELOC_AARCH64_32 + -- : BFD_RELOC_AARCH64_16 + Basic absolute relocations of N bits. These are equivalent to + BFD_RELOC_N and they were added to assist the indexing of the howto + table. + -- : BFD_RELOC_AARCH64_64_PCREL + -- : BFD_RELOC_AARCH64_32_PCREL + -- : BFD_RELOC_AARCH64_16_PCREL + PC-relative relocations. These are equivalent to BFD_RELOC_N_PCREL + and they were added to assist the indexing of the howto table. + -- : BFD_RELOC_AARCH64_MOVW_G0 + AArch64 MOV[NZK] instruction with most significant bits 0 to 15 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G0_NC + AArch64 MOV[NZK] instruction with less significant bits 0 to 15 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G1 + AArch64 MOV[NZK] instruction with most significant bits 16 to 31 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G1_NC + AArch64 MOV[NZK] instruction with less significant bits 16 to 31 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G2 + AArch64 MOV[NZK] instruction with most significant bits 32 to 47 of + an unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G2_NC + AArch64 MOV[NZK] instruction with less significant bits 32 to 47 of + an address/value. No overflow checking. + -- : BFD_RELOC_AARCH64_MOVW_G3 + AArch64 MOV[NZK] instruction with most signficant bits 48 to 64 of + a signed or unsigned address/value. + -- : BFD_RELOC_AARCH64_MOVW_G0_S + AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a + signed value. Changes instruction to MOVZ or MOVN depending on the + value's sign. + -- : BFD_RELOC_AARCH64_MOVW_G1_S + AArch64 MOV[NZ] instruction with most significant bits 16 to 31 of + a signed value. Changes instruction to MOVZ or MOVN depending on + the value's sign. + -- : BFD_RELOC_AARCH64_MOVW_G2_S + AArch64 MOV[NZ] instruction with most significant bits 32 to 47 of + a signed value. Changes instruction to MOVZ or MOVN depending on + the value's sign. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G0 + AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a + signed value. Changes instruction to MOVZ or MOVN depending on the + value's sign. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G0_NC + AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a + signed value. Changes instruction to MOVZ or MOVN depending on the + value's sign. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G1 + AArch64 MOVK instruction with most significant bits 16 to 31 of a + signed value. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G1_NC + AArch64 MOVK instruction with most significant bits 16 to 31 of a + signed value. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G2 + AArch64 MOVK instruction with most significant bits 32 to 47 of a + signed value. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G2_NC + AArch64 MOVK instruction with most significant bits 32 to 47 of a + signed value. + -- : BFD_RELOC_AARCH64_MOVW_PREL_G3 + AArch64 MOVK instruction with most significant bits 47 to 63 of a + signed value. + -- : BFD_RELOC_AARCH64_LD_LO19_PCREL + AArch64 Load Literal instruction, holding a 19 bit pc-relative word + offset. The lowest two bits must be zero and are not stored in the + instruction, giving a 21 bit signed byte offset. + -- : BFD_RELOC_AARCH64_ADR_LO21_PCREL + AArch64 ADR instruction, holding a simple 21 bit pc-relative byte + offset. + -- : BFD_RELOC_AARCH64_ADR_HI21_PCREL + AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page + offset, giving a 4KB aligned page base address. + -- : BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL + AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page + offset, giving a 4KB aligned page base address, but with no + overflow checking. + -- : BFD_RELOC_AARCH64_ADD_LO12 + AArch64 ADD immediate instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST8_LO12 + AArch64 8-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_TSTBR14 + AArch64 14 bit pc-relative test bit and branch. The lowest two + bits must be zero and are not stored in the instruction, giving a + 16 bit signed byte offset. + -- : BFD_RELOC_AARCH64_BRANCH19 + AArch64 19 bit pc-relative conditional branch and compare & branch. + The lowest two bits must be zero and are not stored in the + instruction, giving a 21 bit signed byte offset. + -- : BFD_RELOC_AARCH64_JUMP26 + AArch64 26 bit pc-relative unconditional branch. The lowest two + bits must be zero and are not stored in the instruction, giving a + 28 bit signed byte offset. + -- : BFD_RELOC_AARCH64_CALL26 + AArch64 26 bit pc-relative unconditional branch and link. The + lowest two bits must be zero and are not stored in the instruction, + giving a 28 bit signed byte offset. + -- : BFD_RELOC_AARCH64_LDST16_LO12 + AArch64 16-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST32_LO12 + AArch64 32-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST64_LO12 + AArch64 64-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_LDST128_LO12 + AArch64 128-bit load/store instruction, holding bits 0 to 11 of the + address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_GOT_LD_PREL19 + AArch64 Load Literal instruction, holding a 19 bit PC relative word + offset of the global offset table entry for a symbol. The lowest + two bits must be zero and are not stored in the instruction, giving + a 21 bit signed byte offset. This relocation type requires signed + overflow checking. + -- : BFD_RELOC_AARCH64_ADR_GOT_PAGE + Get to the page base of the global offset table entry for a symbol + as part of an ADRP instruction using a 21 bit PC relative value. + Used in conjunction with BFD_RELOC_AARCH64_LD64_GOT_LO12_NC. + -- : BFD_RELOC_AARCH64_LD64_GOT_LO12_NC + Unsigned 12 bit byte offset for 64 bit load/store from the page of + the GOT entry for this symbol. Used in conjunction with + BFD_RELOC_AARCH64_ADR_GOT_PAGE. Valid in LP64 ABI only. + -- : BFD_RELOC_AARCH64_LD32_GOT_LO12_NC + Unsigned 12 bit byte offset for 32 bit load/store from the page of + the GOT entry for this symbol. Used in conjunction with + BFD_RELOC_AARCH64_ADR_GOT_PAGE. Valid in ILP32 ABI only. + -- : BFD_RELOC_AARCH64_MOVW_GOTOFF_G0_NC + Unsigned 16 bit byte offset for 64 bit load/store from the GOT + entry for this symbol. Valid in LP64 ABI only. + -- : BFD_RELOC_AARCH64_MOVW_GOTOFF_G1 + Unsigned 16 bit byte higher offset for 64 bit load/store from the + GOT entry for this symbol. Valid in LP64 ABI only. + -- : BFD_RELOC_AARCH64_LD64_GOTOFF_LO15 + Unsigned 15 bit byte offset for 64 bit load/store from the page of + the GOT entry for this symbol. Valid in LP64 ABI only. + -- : BFD_RELOC_AARCH64_LD32_GOTPAGE_LO14 + Scaled 14 bit byte offset to the page base of the global offset + table. + -- : BFD_RELOC_AARCH64_LD64_GOTPAGE_LO15 + Scaled 15 bit byte offset to the page base of the global offset + table. + -- : BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21 + Get to the page base of the global offset table entry for a symbols + tls_index structure as part of an adrp instruction using a 21 bit + PC relative value. Used in conjunction with + BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC. + -- : BFD_RELOC_AARCH64_TLSGD_ADR_PREL21 + AArch64 TLS General Dynamic. + -- : BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC + Unsigned 12 bit byte offset to global offset table entry for a + symbol's tls_index structure. Used in conjunction with + BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21. + -- : BFD_RELOC_AARCH64_TLSGD_MOVW_G0_NC + AArch64 TLS General Dynamic relocation. + -- : BFD_RELOC_AARCH64_TLSGD_MOVW_G1 + AArch64 TLS General Dynamic relocation. + -- : BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1 + AArch64 TLS INITIAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_HI12 + bit[23:12] of byte offset to module TLS base address. + -- : BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12 + Unsigned 12 bit byte offset to module TLS base address. + -- : BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12_NC + No overflow check version of + BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12. + -- : BFD_RELOC_AARCH64_TLSLD_ADD_LO12_NC + Unsigned 12 bit byte offset to global offset table entry for a + symbol's tls_index structure. Used in conjunction with + BFD_RELOC_AARCH64_TLSLD_ADR_PAGE21. + -- : BFD_RELOC_AARCH64_TLSLD_ADR_PAGE21 + GOT entry page address for AArch64 TLS Local Dynamic, used with + ADRP instruction. + -- : BFD_RELOC_AARCH64_TLSLD_ADR_PREL21 + GOT entry address for AArch64 TLS Local Dynamic, used with ADR + instruction. + -- : BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12 + bit[11:1] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12 + bit[11:2] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12 + bit[11:3] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12 + bit[11:0] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0 + bit[15:0] of byte offset to module TLS base address. + -- : BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0_NC + No overflow check version of + BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0. + -- : BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1 + bit[31:16] of byte offset to module TLS base address. + -- : BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1_NC + No overflow check version of + BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1. + -- : BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G2 + bit[47:32] of byte offset to module TLS base address. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12 + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC + AArch64 TLS LOCAL EXEC relocation. + -- : BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12 + bit[11:1] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12 + bit[11:2] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12 + bit[11:3] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12 + bit[11:0] of byte offset to module TLS base address, encoded in + ldst instructions. + -- : BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSDESC_LD_PREL19 + -- : BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21 + -- : BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21 + -- : BFD_RELOC_AARCH64_TLSDESC_LD64_LO12 + -- : BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC + -- : BFD_RELOC_AARCH64_TLSDESC_ADD_LO12 + -- : BFD_RELOC_AARCH64_TLSDESC_OFF_G1 + -- : BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC + -- : BFD_RELOC_AARCH64_TLSDESC_LDR + -- : BFD_RELOC_AARCH64_TLSDESC_ADD + -- : BFD_RELOC_AARCH64_TLSDESC_CALL + AArch64 TLS DESC relocations. + -- : BFD_RELOC_AARCH64_COPY + -- : BFD_RELOC_AARCH64_GLOB_DAT + -- : BFD_RELOC_AARCH64_JUMP_SLOT + -- : BFD_RELOC_AARCH64_RELATIVE + AArch64 DSO relocations. + -- : BFD_RELOC_AARCH64_TLS_DTPMOD + -- : BFD_RELOC_AARCH64_TLS_DTPREL + -- : BFD_RELOC_AARCH64_TLS_TPREL + -- : BFD_RELOC_AARCH64_TLSDESC + AArch64 TLS relocations. + -- : BFD_RELOC_AARCH64_IRELATIVE + AArch64 support for STT_GNU_IFUNC. + -- : BFD_RELOC_AARCH64_RELOC_END + AArch64 pseudo relocation code to mark the end of the AArch64 + relocation enumerators that have direct mapping to ELF reloc codes. + There are a few more enumerators after this one; those are mainly + used by the AArch64 assembler for the internal fixup or to select + one of the above enumerators. + -- : BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_LDST_LO12 + AArch64 unspecified load/store instruction, holding bits 0 to 11 of + the address. Used in conjunction with + BFD_RELOC_AARCH64_ADR_HI21_PCREL. + -- : BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12 + AArch64 pseudo relocation code for TLS local dynamic mode. It's to + be used internally by the AArch64 assembler and not (currently) + written to any object files. + -- : BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12, but no + overflow check. + -- : BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12 + AArch64 pseudo relocation code for TLS local exec mode. It's to be + used internally by the AArch64 assembler and not (currently) + written to any object files. + -- : BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12_NC + Similar to BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12, but no overflow + check. + -- : BFD_RELOC_AARCH64_LD_GOT_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC + AArch64 pseudo relocation code to be used internally by the AArch64 + assembler and not (currently) written to any object files. + -- : BFD_RELOC_TILEPRO_COPY + -- : BFD_RELOC_TILEPRO_GLOB_DAT + -- : BFD_RELOC_TILEPRO_JMP_SLOT + -- : BFD_RELOC_TILEPRO_RELATIVE + -- : BFD_RELOC_TILEPRO_BROFF_X1 + -- : BFD_RELOC_TILEPRO_JOFFLONG_X1 + -- : BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT + -- : BFD_RELOC_TILEPRO_IMM8_X0 + -- : BFD_RELOC_TILEPRO_IMM8_Y0 + -- : BFD_RELOC_TILEPRO_IMM8_X1 + -- : BFD_RELOC_TILEPRO_IMM8_Y1 + -- : BFD_RELOC_TILEPRO_DEST_IMM8_X1 + -- : BFD_RELOC_TILEPRO_MT_IMM15_X1 + -- : BFD_RELOC_TILEPRO_MF_IMM15_X1 + -- : BFD_RELOC_TILEPRO_IMM16_X0 + -- : BFD_RELOC_TILEPRO_IMM16_X1 + -- : BFD_RELOC_TILEPRO_IMM16_X0_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_HA + -- : BFD_RELOC_TILEPRO_IMM16_X0_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA + -- : BFD_RELOC_TILEPRO_MMSTART_X0 + -- : BFD_RELOC_TILEPRO_MMEND_X0 + -- : BFD_RELOC_TILEPRO_MMSTART_X1 + -- : BFD_RELOC_TILEPRO_MMEND_X1 + -- : BFD_RELOC_TILEPRO_SHAMT_X0 + -- : BFD_RELOC_TILEPRO_SHAMT_X1 + -- : BFD_RELOC_TILEPRO_SHAMT_Y0 + -- : BFD_RELOC_TILEPRO_SHAMT_Y1 + -- : BFD_RELOC_TILEPRO_TLS_GD_CALL + -- : BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD + -- : BFD_RELOC_TILEPRO_TLS_IE_LOAD + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA + -- : BFD_RELOC_TILEPRO_TLS_DTPMOD32 + -- : BFD_RELOC_TILEPRO_TLS_DTPOFF32 + -- : BFD_RELOC_TILEPRO_TLS_TPOFF32 + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI + -- : BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA + -- : BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA + Tilera TILEPro Relocations. + -- : BFD_RELOC_TILEGX_HW0 + -- : BFD_RELOC_TILEGX_HW1 + -- : BFD_RELOC_TILEGX_HW2 + -- : BFD_RELOC_TILEGX_HW3 + -- : BFD_RELOC_TILEGX_HW0_LAST + -- : BFD_RELOC_TILEGX_HW1_LAST + -- : BFD_RELOC_TILEGX_HW2_LAST + -- : BFD_RELOC_TILEGX_COPY + -- : BFD_RELOC_TILEGX_GLOB_DAT + -- : BFD_RELOC_TILEGX_JMP_SLOT + -- : BFD_RELOC_TILEGX_RELATIVE + -- : BFD_RELOC_TILEGX_BROFF_X1 + -- : BFD_RELOC_TILEGX_JUMPOFF_X1 + -- : BFD_RELOC_TILEGX_JUMPOFF_X1_PLT + -- : BFD_RELOC_TILEGX_IMM8_X0 + -- : BFD_RELOC_TILEGX_IMM8_Y0 + -- : BFD_RELOC_TILEGX_IMM8_X1 + -- : BFD_RELOC_TILEGX_IMM8_Y1 + -- : BFD_RELOC_TILEGX_DEST_IMM8_X1 + -- : BFD_RELOC_TILEGX_MT_IMM14_X1 + -- : BFD_RELOC_TILEGX_MF_IMM14_X1 + -- : BFD_RELOC_TILEGX_MMSTART_X0 + -- : BFD_RELOC_TILEGX_MMEND_X0 + -- : BFD_RELOC_TILEGX_SHAMT_X0 + -- : BFD_RELOC_TILEGX_SHAMT_X1 + -- : BFD_RELOC_TILEGX_SHAMT_Y0 + -- : BFD_RELOC_TILEGX_SHAMT_Y1 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3 + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3 + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT + -- : BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL + -- : BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE + -- : BFD_RELOC_TILEGX_TLS_DTPMOD64 + -- : BFD_RELOC_TILEGX_TLS_DTPOFF64 + -- : BFD_RELOC_TILEGX_TLS_TPOFF64 + -- : BFD_RELOC_TILEGX_TLS_DTPMOD32 + -- : BFD_RELOC_TILEGX_TLS_DTPOFF32 + -- : BFD_RELOC_TILEGX_TLS_TPOFF32 + -- : BFD_RELOC_TILEGX_TLS_GD_CALL + -- : BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD + -- : BFD_RELOC_TILEGX_TLS_IE_LOAD + -- : BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD + -- : BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD + Tilera TILE-Gx Relocations. + -- : BFD_RELOC_BPF_64 + -- : BFD_RELOC_BPF_DISP32 + -- : BFD_RELOC_BPF_DISPCALL32 + -- : BFD_RELOC_BPF_DISP16 + Linux eBPF relocations. + -- : BFD_RELOC_EPIPHANY_SIMM8 + Adapteva EPIPHANY - 8 bit signed pc-relative displacement. + -- : BFD_RELOC_EPIPHANY_SIMM24 + Adapteva EPIPHANY - 24 bit signed pc-relative displacement. + -- : BFD_RELOC_EPIPHANY_HIGH + Adapteva EPIPHANY - 16 most-significant bits of absolute address. + -- : BFD_RELOC_EPIPHANY_LOW + Adapteva EPIPHANY - 16 least-significant bits of absolute address. + -- : BFD_RELOC_EPIPHANY_SIMM11 + Adapteva EPIPHANY - 11 bit signed number - add/sub immediate. + -- : BFD_RELOC_EPIPHANY_IMM11 + Adapteva EPIPHANY - 11 bit sign-magnitude number (ld/st + displacement). + -- : BFD_RELOC_EPIPHANY_IMM8 + Adapteva EPIPHANY - 8 bit immediate for 16 bit mov instruction. + -- : BFD_RELOC_VISIUM_HI16 + -- : BFD_RELOC_VISIUM_LO16 + -- : BFD_RELOC_VISIUM_IM16 + -- : BFD_RELOC_VISIUM_REL16 + -- : BFD_RELOC_VISIUM_HI16_PCREL + -- : BFD_RELOC_VISIUM_LO16_PCREL + -- : BFD_RELOC_VISIUM_IM16_PCREL + Visium Relocations. + -- : BFD_RELOC_WASM32_LEB128 + -- : BFD_RELOC_WASM32_LEB128_GOT + -- : BFD_RELOC_WASM32_LEB128_GOT_CODE + -- : BFD_RELOC_WASM32_LEB128_PLT + -- : BFD_RELOC_WASM32_PLT_INDEX + -- : BFD_RELOC_WASM32_ABS32_CODE + -- : BFD_RELOC_WASM32_COPY + -- : BFD_RELOC_WASM32_CODE_POINTER + -- : BFD_RELOC_WASM32_INDEX + -- : BFD_RELOC_WASM32_PLT_SIG + WebAssembly relocations. + -- : BFD_RELOC_CKCORE_NONE + -- : BFD_RELOC_CKCORE_ADDR32 + -- : BFD_RELOC_CKCORE_PCREL_IMM8BY4 + -- : BFD_RELOC_CKCORE_PCREL_IMM11BY2 + -- : BFD_RELOC_CKCORE_PCREL_IMM4BY2 + -- : BFD_RELOC_CKCORE_PCREL32 + -- : BFD_RELOC_CKCORE_PCREL_JSR_IMM11BY2 + -- : BFD_RELOC_CKCORE_GNU_VTINHERIT + -- : BFD_RELOC_CKCORE_GNU_VTENTRY + -- : BFD_RELOC_CKCORE_RELATIVE + -- : BFD_RELOC_CKCORE_COPY + -- : BFD_RELOC_CKCORE_GLOB_DAT + -- : BFD_RELOC_CKCORE_JUMP_SLOT + -- : BFD_RELOC_CKCORE_GOTOFF + -- : BFD_RELOC_CKCORE_GOTPC + -- : BFD_RELOC_CKCORE_GOT32 + -- : BFD_RELOC_CKCORE_PLT32 + -- : BFD_RELOC_CKCORE_ADDRGOT + -- : BFD_RELOC_CKCORE_ADDRPLT + -- : BFD_RELOC_CKCORE_PCREL_IMM26BY2 + -- : BFD_RELOC_CKCORE_PCREL_IMM16BY2 + -- : BFD_RELOC_CKCORE_PCREL_IMM16BY4 + -- : BFD_RELOC_CKCORE_PCREL_IMM10BY2 + -- : BFD_RELOC_CKCORE_PCREL_IMM10BY4 + -- : BFD_RELOC_CKCORE_ADDR_HI16 + -- : BFD_RELOC_CKCORE_ADDR_LO16 + -- : BFD_RELOC_CKCORE_GOTPC_HI16 + -- : BFD_RELOC_CKCORE_GOTPC_LO16 + -- : BFD_RELOC_CKCORE_GOTOFF_HI16 + -- : BFD_RELOC_CKCORE_GOTOFF_LO16 + -- : BFD_RELOC_CKCORE_GOT12 + -- : BFD_RELOC_CKCORE_GOT_HI16 + -- : BFD_RELOC_CKCORE_GOT_LO16 + -- : BFD_RELOC_CKCORE_PLT12 + -- : BFD_RELOC_CKCORE_PLT_HI16 + -- : BFD_RELOC_CKCORE_PLT_LO16 + -- : BFD_RELOC_CKCORE_ADDRGOT_HI16 + -- : BFD_RELOC_CKCORE_ADDRGOT_LO16 + -- : BFD_RELOC_CKCORE_ADDRPLT_HI16 + -- : BFD_RELOC_CKCORE_ADDRPLT_LO16 + -- : BFD_RELOC_CKCORE_PCREL_JSR_IMM26BY2 + -- : BFD_RELOC_CKCORE_TOFFSET_LO16 + -- : BFD_RELOC_CKCORE_DOFFSET_LO16 + -- : BFD_RELOC_CKCORE_PCREL_IMM18BY2 + -- : BFD_RELOC_CKCORE_DOFFSET_IMM18 + -- : BFD_RELOC_CKCORE_DOFFSET_IMM18BY2 + -- : BFD_RELOC_CKCORE_DOFFSET_IMM18BY4 + -- : BFD_RELOC_CKCORE_GOTOFF_IMM18 + -- : BFD_RELOC_CKCORE_GOT_IMM18BY4 + -- : BFD_RELOC_CKCORE_PLT_IMM18BY4 + -- : BFD_RELOC_CKCORE_PCREL_IMM7BY4 + -- : BFD_RELOC_CKCORE_TLS_LE32 + -- : BFD_RELOC_CKCORE_TLS_IE32 + -- : BFD_RELOC_CKCORE_TLS_GD32 + -- : BFD_RELOC_CKCORE_TLS_LDM32 + -- : BFD_RELOC_CKCORE_TLS_LDO32 + -- : BFD_RELOC_CKCORE_TLS_DTPMOD32 + -- : BFD_RELOC_CKCORE_TLS_DTPOFF32 + -- : BFD_RELOC_CKCORE_TLS_TPOFF32 + -- : BFD_RELOC_CKCORE_PCREL_FLRW_IMM8BY4 + -- : BFD_RELOC_CKCORE_NOJSRI + -- : BFD_RELOC_CKCORE_CALLGRAPH + -- : BFD_RELOC_CKCORE_IRELATIVE + -- : BFD_RELOC_CKCORE_PCREL_BLOOP_IMM4BY4 + -- : BFD_RELOC_CKCORE_PCREL_BLOOP_IMM12BY4 + C-SKY relocations. + -- : BFD_RELOC_S12Z_OPR + S12Z relocations. + -- : BFD_RELOC_LARCH_TLS_DTPMOD32 + -- : BFD_RELOC_LARCH_TLS_DTPREL32 + -- : BFD_RELOC_LARCH_TLS_DTPMOD64 + -- : BFD_RELOC_LARCH_TLS_DTPREL64 + -- : BFD_RELOC_LARCH_TLS_TPREL32 + -- : BFD_RELOC_LARCH_TLS_TPREL64 + -- : BFD_RELOC_LARCH_TLS_DESC32 + -- : BFD_RELOC_LARCH_TLS_DESC64 + -- : BFD_RELOC_LARCH_MARK_LA + -- : BFD_RELOC_LARCH_MARK_PCREL + -- : BFD_RELOC_LARCH_SOP_PUSH_PCREL + -- : BFD_RELOC_LARCH_SOP_PUSH_ABSOLUTE + -- : BFD_RELOC_LARCH_SOP_PUSH_DUP + -- : BFD_RELOC_LARCH_SOP_PUSH_GPREL + -- : BFD_RELOC_LARCH_SOP_PUSH_TLS_TPREL + -- : BFD_RELOC_LARCH_SOP_PUSH_TLS_GOT + -- : BFD_RELOC_LARCH_SOP_PUSH_TLS_GD + -- : BFD_RELOC_LARCH_SOP_PUSH_PLT_PCREL + -- : BFD_RELOC_LARCH_SOP_ASSERT + -- : BFD_RELOC_LARCH_SOP_NOT + -- : BFD_RELOC_LARCH_SOP_SUB + -- : BFD_RELOC_LARCH_SOP_SL + -- : BFD_RELOC_LARCH_SOP_SR + -- : BFD_RELOC_LARCH_SOP_ADD + -- : BFD_RELOC_LARCH_SOP_AND + -- : BFD_RELOC_LARCH_SOP_IF_ELSE + -- : BFD_RELOC_LARCH_SOP_POP_32_S_10_5 + -- : BFD_RELOC_LARCH_SOP_POP_32_U_10_12 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_10_12 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_10_16 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_10_16_S2 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_5_20 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_0_5_10_16_S2 + -- : BFD_RELOC_LARCH_SOP_POP_32_S_0_10_10_16_S2 + -- : BFD_RELOC_LARCH_SOP_POP_32_U + -- : BFD_RELOC_LARCH_ADD8 + -- : BFD_RELOC_LARCH_ADD16 + -- : BFD_RELOC_LARCH_ADD24 + -- : BFD_RELOC_LARCH_ADD32 + -- : BFD_RELOC_LARCH_ADD64 + -- : BFD_RELOC_LARCH_SUB8 + -- : BFD_RELOC_LARCH_SUB16 + -- : BFD_RELOC_LARCH_SUB24 + -- : BFD_RELOC_LARCH_SUB32 + -- : BFD_RELOC_LARCH_SUB64 + -- : BFD_RELOC_LARCH_B16 + -- : BFD_RELOC_LARCH_B21 + -- : BFD_RELOC_LARCH_B26 + -- : BFD_RELOC_LARCH_ABS_HI20 + -- : BFD_RELOC_LARCH_ABS_LO12 + -- : BFD_RELOC_LARCH_ABS64_LO20 + -- : BFD_RELOC_LARCH_ABS64_HI12 + -- : BFD_RELOC_LARCH_PCALA_HI20 + -- : BFD_RELOC_LARCH_PCALA_LO12 + -- : BFD_RELOC_LARCH_PCALA64_LO20 + -- : BFD_RELOC_LARCH_PCALA64_HI12 + -- : BFD_RELOC_LARCH_GOT_PC_HI20 + -- : BFD_RELOC_LARCH_GOT_PC_LO12 + -- : BFD_RELOC_LARCH_GOT64_PC_LO20 + -- : BFD_RELOC_LARCH_GOT64_PC_HI12 + -- : BFD_RELOC_LARCH_GOT_HI20 + -- : BFD_RELOC_LARCH_GOT_LO12 + -- : BFD_RELOC_LARCH_GOT64_LO20 + -- : BFD_RELOC_LARCH_GOT64_HI12 + -- : BFD_RELOC_LARCH_TLS_LE_HI20 + -- : BFD_RELOC_LARCH_TLS_LE_LO12 + -- : BFD_RELOC_LARCH_TLS_LE64_LO20 + -- : BFD_RELOC_LARCH_TLS_LE64_HI12 + -- : BFD_RELOC_LARCH_TLS_IE_PC_HI20 + -- : BFD_RELOC_LARCH_TLS_IE_PC_LO12 + -- : BFD_RELOC_LARCH_TLS_IE64_PC_LO20 + -- : BFD_RELOC_LARCH_TLS_IE64_PC_HI12 + -- : BFD_RELOC_LARCH_TLS_IE_HI20 + -- : BFD_RELOC_LARCH_TLS_IE_LO12 + -- : BFD_RELOC_LARCH_TLS_IE64_LO20 + -- : BFD_RELOC_LARCH_TLS_IE64_HI12 + -- : BFD_RELOC_LARCH_TLS_LD_PC_HI20 + -- : BFD_RELOC_LARCH_TLS_LD_HI20 + -- : BFD_RELOC_LARCH_TLS_GD_PC_HI20 + -- : BFD_RELOC_LARCH_TLS_GD_HI20 + -- : BFD_RELOC_LARCH_32_PCREL + -- : BFD_RELOC_LARCH_RELAX + -- : BFD_RELOC_LARCH_DELETE + -- : BFD_RELOC_LARCH_ALIGN + -- : BFD_RELOC_LARCH_PCREL20_S2 + -- : BFD_RELOC_LARCH_CFA + -- : BFD_RELOC_LARCH_ADD6 + -- : BFD_RELOC_LARCH_SUB6 + -- : BFD_RELOC_LARCH_ADD_ULEB128 + -- : BFD_RELOC_LARCH_SUB_ULEB128 + -- : BFD_RELOC_LARCH_64_PCREL + -- : BFD_RELOC_LARCH_CALL36 + -- : BFD_RELOC_LARCH_TLS_DESC_PC_HI20 + -- : BFD_RELOC_LARCH_TLS_DESC_PC_LO12 + -- : BFD_RELOC_LARCH_TLS_DESC64_PC_LO20 + -- : BFD_RELOC_LARCH_TLS_DESC64_PC_HI12 + -- : BFD_RELOC_LARCH_TLS_DESC_HI20 + -- : BFD_RELOC_LARCH_TLS_DESC_LO12 + -- : BFD_RELOC_LARCH_TLS_DESC64_LO20 + -- : BFD_RELOC_LARCH_TLS_DESC64_HI12 + -- : BFD_RELOC_LARCH_TLS_DESC_LD + -- : BFD_RELOC_LARCH_TLS_DESC_CALL + -- : BFD_RELOC_LARCH_TLS_LE_HI20_R + -- : BFD_RELOC_LARCH_TLS_LE_ADD_R + -- : BFD_RELOC_LARCH_TLS_LE_LO12_R + -- : BFD_RELOC_LARCH_TLS_LD_PCREL20_S2 + -- : BFD_RELOC_LARCH_TLS_GD_PCREL20_S2 + -- : BFD_RELOC_LARCH_TLS_DESC_PCREL20_S2 + LARCH relocations. + + typedef enum bfd_reloc_code_real bfd_reloc_code_real_type; + + +2.10.2.2 'bfd_reloc_type_lookup' +................................ + + -- Function: reloc_howto_type *bfd_reloc_type_lookup (bfd *abfd, + bfd_reloc_code_real_type code); reloc_howto_type + *bfd_reloc_name_lookup (bfd *abfd, const char *reloc_name); + Return a pointer to a howto structure which, when invoked, will + perform the relocation CODE on data from the architecture noted. + +2.10.2.3 'bfd_default_reloc_type_lookup' +........................................ + + -- Function: reloc_howto_type *bfd_default_reloc_type_lookup (bfd + *abfd, bfd_reloc_code_real_type code); + Provides a default relocation lookup routine for any architecture. + +2.10.2.4 'bfd_get_reloc_code_name' +.................................. + + -- Function: const char *bfd_get_reloc_code_name + (bfd_reloc_code_real_type code); + Provides a printable name for the supplied relocation code. Useful + mainly for printing error messages. + +2.10.2.5 'bfd_generic_relax_section' +.................................... + + -- Function: bool bfd_generic_relax_section (bfd *abfd, asection + *section, struct bfd_link_info *, bool *); + Provides default handling for relaxing for back ends which don't do + relaxing. + +2.10.2.6 'bfd_generic_gc_sections' +.................................. + + -- Function: bool bfd_generic_gc_sections (bfd *, struct bfd_link_info + *); + Provides default handling for relaxing for back ends which don't do + section gc - i.e., does nothing. + +2.10.2.7 'bfd_generic_lookup_section_flags' +........................................... + + -- Function: bool bfd_generic_lookup_section_flags (struct + bfd_link_info *, struct flag_info *, asection *); + Provides default handling for section flags lookup - i.e., does + nothing. Returns FALSE if the section should be omitted, otherwise + TRUE. + +2.10.2.8 'bfd_generic_merge_sections' +..................................... + + -- Function: bool bfd_generic_merge_sections (bfd *, struct + bfd_link_info *); + Provides default handling for SEC_MERGE section merging for back + ends which don't have SEC_MERGE support - i.e., does nothing. + +2.10.2.9 'bfd_generic_get_relocated_section_contents' +..................................................... + + -- Function: bfd_byte *bfd_generic_get_relocated_section_contents (bfd + *abfd, struct bfd_link_info *link_info, struct bfd_link_order + *link_order, bfd_byte *data, bool relocatable, asymbol + **symbols); + Provides default handling of relocation effort for back ends which + can't be bothered to do it efficiently. + +2.10.2.10 '_bfd_generic_set_reloc' +.................................. + + -- Function: void _bfd_generic_set_reloc (bfd *abfd, sec_ptr section, + arelent **relptr, unsigned int count); + Installs a new set of internal relocations in SECTION. + +2.10.2.11 '_bfd_unrecognized_reloc' +................................... + + -- Function: bool _bfd_unrecognized_reloc (bfd * abfd, sec_ptr section, + unsigned int r_type); + Reports an unrecognized reloc. Written as a function in order to + reduce code duplication. Returns FALSE so that it can be called + from a return statement. + + +File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end + +2.11 Core files +=============== + +2.11.1 Core file functions +-------------------------- + +These are functions pertaining to core files. + +2.11.1.1 'bfd_core_file_failing_command' +........................................ + + -- Function: const char *bfd_core_file_failing_command (bfd *abfd); + Return a read-only string explaining which program was running when + it failed and produced the core file ABFD. + +2.11.1.2 'bfd_core_file_failing_signal' +....................................... + + -- Function: int bfd_core_file_failing_signal (bfd *abfd); + Returns the signal number which caused the core dump which + generated the file the BFD ABFD is attached to. + +2.11.1.3 'bfd_core_file_pid' +............................ + + -- Function: int bfd_core_file_pid (bfd *abfd); + Returns the PID of the process the core dump the BFD ABFD is + attached to was generated from. + +2.11.1.4 'core_file_matches_executable_p' +......................................... + + -- Function: bool core_file_matches_executable_p (bfd *core_bfd, bfd + *exec_bfd); + Return 'TRUE' if the core file attached to CORE_BFD was generated + by a run of the executable file attached to EXEC_BFD, 'FALSE' + otherwise. + +2.11.1.5 'generic_core_file_matches_executable_p' +................................................. + + -- Function: bool generic_core_file_matches_executable_p (bfd + *core_bfd, bfd *exec_bfd); + Return TRUE if the core file attached to CORE_BFD was generated by + a run of the executable file attached to EXEC_BFD. The match is + based on executable basenames only. + + Note: When not able to determine the core file failing command or + the executable name, we still return TRUE even though we're not + sure that core file and executable match. This is to avoid + generating a false warning in situations where we really don't know + whether they match or not. + + +File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end + +2.12 Targets +============ + +Each port of BFD to a different machine requires the creation of a +target back end. All the back end provides to the root part of BFD is a +structure containing pointers to functions which perform certain low +level operations on files. BFD translates the applications's requests +through a pointer into calls to the back end routines. + + When a file is opened with 'bfd_openr', its format and target are +unknown. BFD uses various mechanisms to determine how to interpret the +file. The operations performed are: + + * Create a BFD by calling the internal routine '_bfd_new_bfd', then + call 'bfd_find_target' with the target string supplied to + 'bfd_openr' and the new BFD pointer. + + * If a null target string was provided to 'bfd_find_target', look up + the environment variable 'GNUTARGET' and use that as the target + string. + + * If the target string is still 'NULL', or the target string is + 'default', then use the first item in the target vector as the + target type, and set 'target_defaulted' in the BFD to cause + 'bfd_check_format' to loop through all the targets. *Note + bfd_target::. *Note Formats::. + + * Otherwise, inspect the elements in the target vector one by one, + until a match on target name is found. When found, use it. + + * Otherwise return the error 'bfd_error_invalid_target' to + 'bfd_openr'. + + * 'bfd_openr' attempts to open the file using 'bfd_open_file', and + returns the BFD. + Once the BFD has been opened and the target selected, the file format +may be determined. This is done by calling 'bfd_check_format' on the +BFD with a suggested format. If 'target_defaulted' has been set, each +possible target type is tried to see if it recognizes the specified +format. 'bfd_check_format' returns 'TRUE' when the caller guesses +right. +* Menu: + +* bfd_target:: + + +File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets + +2.12.1 bfd_target +----------------- + +This structure contains everything that BFD knows about a target. It +includes things like its byte order, name, and which routines to call to +do various operations. + + Every BFD points to a target structure with its 'xvec' member. + + The macros below are used to dispatch to functions through the +'bfd_target' vector. They are used in a number of macros further down +in 'bfd.h', and are also used when calling various routines by hand +inside the BFD implementation. The ARGLIST argument must be +parenthesized; it contains all the arguments to the called function. + + They make the documentation (more) unpleasant to read, so if someone +wants to fix this and not break the above, please do. + #define BFD_SEND(bfd, message, arglist) \ + ((*((bfd)->xvec->message)) arglist) + + #ifdef DEBUG_BFD_SEND + #undef BFD_SEND + #define BFD_SEND(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + ((*((bfd)->xvec->message)) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) + #endif + For operations which index on the BFD format: + #define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) + + #ifdef DEBUG_BFD_SEND + #undef BFD_SEND_FMT + #define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) + #endif + + /* Defined to TRUE if unused section symbol should be kept. */ + #ifndef TARGET_KEEP_UNUSED_SECTION_SYMBOLS + #define TARGET_KEEP_UNUSED_SECTION_SYMBOLS true + #endif + + This is the structure which defines the type of BFD this is. The +'xvec' member of the struct 'bfd' itself points here. Each module that +implements access to a different target under BFD, defines one of these. + + FIXME, these names should be rationalised with the names of the entry +points which call them. Too bad we can't have one macro to define them +both! + + typedef struct bfd_target + { + /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ + const char *name; + + /* The "flavour" of a back end is a general indication about + the contents of a file. */ + enum bfd_flavour flavour; + + /* The order of bytes within the data area of a file. */ + enum bfd_endian byteorder; + + /* The order of bytes within the header parts of a file. */ + enum bfd_endian header_byteorder; + + /* A mask of all the flags which an executable may have set - + from the set BFD_NO_FLAGS, HAS_RELOC, ...D_PAGED. */ + flagword object_flags; + + /* A mask of all the flags which a section may have set - from + the set SEC_NO_FLAGS, SEC_ALLOC, ...SET_NEVER_LOAD. */ + flagword section_flags; + + /* The character normally found at the front of a symbol. + (if any), perhaps `_'. */ + char symbol_leading_char; + + /* The pad character for file names within an archive header. */ + char ar_pad_char; + + /* The maximum number of characters in an archive header. */ + unsigned char ar_max_namelen; + + /* How well this target matches, used to select between various + possible targets when more than one target matches. */ + unsigned char match_priority; + + /* TRUE if unused section symbols should be kept. */ + bool keep_unused_section_symbols; + + /* Entries for byte swapping for data. These are different from the + other entry points, since they don't take a BFD as the first argument. + Certain other handlers could do the same. */ + uint64_t (*bfd_getx64) (const void *); + int64_t (*bfd_getx_signed_64) (const void *); + void (*bfd_putx64) (uint64_t, void *); + bfd_vma (*bfd_getx32) (const void *); + bfd_signed_vma (*bfd_getx_signed_32) (const void *); + void (*bfd_putx32) (bfd_vma, void *); + bfd_vma (*bfd_getx16) (const void *); + bfd_signed_vma (*bfd_getx_signed_16) (const void *); + void (*bfd_putx16) (bfd_vma, void *); + + /* Byte swapping for the headers. */ + uint64_t (*bfd_h_getx64) (const void *); + int64_t (*bfd_h_getx_signed_64) (const void *); + void (*bfd_h_putx64) (uint64_t, void *); + bfd_vma (*bfd_h_getx32) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); + void (*bfd_h_putx32) (bfd_vma, void *); + bfd_vma (*bfd_h_getx16) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); + void (*bfd_h_putx16) (bfd_vma, void *); + + /* Format dependent routines: these are vectors of entry points + within the target vector structure, one for each format to check. */ + + /* Check the format of a file being read. Return a bfd_cleanup on + success or zero on failure. */ + bfd_cleanup (*_bfd_check_format[bfd_type_end]) (bfd *); + + /* Set the format of a file being written. */ + bool (*_bfd_set_format[bfd_type_end]) (bfd *); + + /* Write cached information into a file being written, at bfd_close. */ + bool (*_bfd_write_contents[bfd_type_end]) (bfd *); + + The general target vector. These vectors are initialized using the +BFD_JUMP_TABLE macros. + /* Generic entry points. */ + #define BFD_JUMP_TABLE_GENERIC(NAME) \ + NAME##_close_and_cleanup, \ + NAME##_bfd_free_cached_info, \ + NAME##_new_section_hook, \ + NAME##_get_section_contents + + /* Called when the BFD is being closed to do any necessary cleanup. */ + bool (*_close_and_cleanup) (bfd *); + /* Ask the BFD to free all cached information. */ + bool (*_bfd_free_cached_info) (bfd *); + /* Called when a new section is created. */ + bool (*_new_section_hook) (bfd *, sec_ptr); + /* Read the contents of a section. */ + bool (*_bfd_get_section_contents) (bfd *, sec_ptr, void *, file_ptr, + bfd_size_type); + + /* Entry points to copy private data. */ + #define BFD_JUMP_TABLE_COPY(NAME) \ + NAME##_bfd_copy_private_bfd_data, \ + NAME##_bfd_merge_private_bfd_data, \ + NAME##_init_private_section_data, \ + NAME##_bfd_copy_private_section_data, \ + NAME##_bfd_copy_private_symbol_data, \ + NAME##_bfd_copy_private_header_data, \ + NAME##_bfd_set_private_flags, \ + NAME##_bfd_print_private_bfd_data + + /* Called to copy BFD general private data from one object file + to another. */ + bool (*_bfd_copy_private_bfd_data) (bfd *, bfd *); + /* Called to merge BFD general private data from one object file + to a common output file when linking. */ + bool (*_bfd_merge_private_bfd_data) (bfd *, struct bfd_link_info *); + /* Called to initialize BFD private section data from one object file + to another. */ + #define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \ + BFD_SEND (obfd, _bfd_init_private_section_data, \ + (ibfd, isec, obfd, osec, link_info)) + bool (*_bfd_init_private_section_data) (bfd *, sec_ptr, bfd *, sec_ptr, + struct bfd_link_info *); + /* Called to copy BFD private section data from one object file + to another. */ + bool (*_bfd_copy_private_section_data) (bfd *, sec_ptr, bfd *, sec_ptr); + /* Called to copy BFD private symbol data from one symbol + to another. */ + bool (*_bfd_copy_private_symbol_data) (bfd *, asymbol *, + bfd *, asymbol *); + /* Called to copy BFD private header data from one object file + to another. */ + bool (*_bfd_copy_private_header_data) (bfd *, bfd *); + /* Called to set private backend flags. */ + bool (*_bfd_set_private_flags) (bfd *, flagword); + + /* Called to print private BFD data. */ + bool (*_bfd_print_private_bfd_data) (bfd *, void *); + + /* Core file entry points. */ + #define BFD_JUMP_TABLE_CORE(NAME) \ + NAME##_core_file_failing_command, \ + NAME##_core_file_failing_signal, \ + NAME##_core_file_matches_executable_p, \ + NAME##_core_file_pid + + char *(*_core_file_failing_command) (bfd *); + int (*_core_file_failing_signal) (bfd *); + bool (*_core_file_matches_executable_p) (bfd *, bfd *); + int (*_core_file_pid) (bfd *); + + /* Archive entry points. */ + #define BFD_JUMP_TABLE_ARCHIVE(NAME) \ + NAME##_slurp_armap, \ + NAME##_slurp_extended_name_table, \ + NAME##_construct_extended_name_table, \ + NAME##_truncate_arname, \ + NAME##_write_armap, \ + NAME##_read_ar_hdr, \ + NAME##_write_ar_hdr, \ + NAME##_openr_next_archived_file, \ + NAME##_get_elt_at_index, \ + NAME##_generic_stat_arch_elt, \ + NAME##_update_armap_timestamp + + bool (*_bfd_slurp_armap) (bfd *); + bool (*_bfd_slurp_extended_name_table) (bfd *); + bool (*_bfd_construct_extended_name_table) (bfd *, char **, + bfd_size_type *, + const char **); + void (*_bfd_truncate_arname) (bfd *, const char *, char *); + bool (*write_armap) (bfd *, unsigned, struct orl *, unsigned, int); + void *(*_bfd_read_ar_hdr_fn) (bfd *); + bool (*_bfd_write_ar_hdr_fn) (bfd *, bfd *); + bfd *(*openr_next_archived_file) (bfd *, bfd *); + #define bfd_get_elt_at_index(b,i) \ + BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) + bfd *(*_bfd_get_elt_at_index) (bfd *, symindex); + int (*_bfd_stat_arch_elt) (bfd *, struct stat *); + bool (*_bfd_update_armap_timestamp) (bfd *); + + /* Entry points used for symbols. */ + #define BFD_JUMP_TABLE_SYMBOLS(NAME) \ + NAME##_get_symtab_upper_bound, \ + NAME##_canonicalize_symtab, \ + NAME##_make_empty_symbol, \ + NAME##_print_symbol, \ + NAME##_get_symbol_info, \ + NAME##_get_symbol_version_string, \ + NAME##_bfd_is_local_label_name, \ + NAME##_bfd_is_target_special_symbol, \ + NAME##_get_lineno, \ + NAME##_find_nearest_line, \ + NAME##_find_nearest_line_with_alt, \ + NAME##_find_line, \ + NAME##_find_inliner_info, \ + NAME##_bfd_make_debug_symbol, \ + NAME##_read_minisymbols, \ + NAME##_minisymbol_to_symbol + + long (*_bfd_get_symtab_upper_bound) (bfd *); + long (*_bfd_canonicalize_symtab) (bfd *, struct bfd_symbol **); + struct bfd_symbol * + (*_bfd_make_empty_symbol) (bfd *); + void (*_bfd_print_symbol) (bfd *, void *, struct bfd_symbol *, + bfd_print_symbol_type); + #define bfd_print_symbol(b,p,s,e) \ + BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) + void (*_bfd_get_symbol_info) (bfd *, struct bfd_symbol *, symbol_info *); + #define bfd_get_symbol_info(b,p,e) \ + BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) + const char * + (*_bfd_get_symbol_version_string) (bfd *, struct bfd_symbol *, + bool, bool *); + #define bfd_get_symbol_version_string(b,s,p,h) \ + BFD_SEND (b, _bfd_get_symbol_version_string, (b,s,p,h)) + bool (*_bfd_is_local_label_name) (bfd *, const char *); + bool (*_bfd_is_target_special_symbol) (bfd *, asymbol *); + alent * + (*_get_lineno) (bfd *, struct bfd_symbol *); + bool (*_bfd_find_nearest_line) (bfd *, struct bfd_symbol **, + struct bfd_section *, bfd_vma, + const char **, const char **, + unsigned int *, unsigned int *); + bool (*_bfd_find_nearest_line_with_alt) (bfd *, const char *, + struct bfd_symbol **, + struct bfd_section *, bfd_vma, + const char **, const char **, + unsigned int *, unsigned int *); + bool (*_bfd_find_line) (bfd *, struct bfd_symbol **, + struct bfd_symbol *, const char **, + unsigned int *); + bool (*_bfd_find_inliner_info) + (bfd *, const char **, const char **, unsigned int *); + /* Back-door to allow format-aware applications to create debug symbols + while using BFD for everything else. Currently used by the assembler + when creating COFF files. */ + asymbol * + (*_bfd_make_debug_symbol) (bfd *); + #define bfd_read_minisymbols(b, d, m, s) \ + BFD_SEND (b, _read_minisymbols, (b, d, m, s)) + long (*_read_minisymbols) (bfd *, bool, void **, unsigned int *); + #define bfd_minisymbol_to_symbol(b, d, m, f) \ + BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) + asymbol * + (*_minisymbol_to_symbol) (bfd *, bool, const void *, asymbol *); + + /* Routines for relocs. */ + #define BFD_JUMP_TABLE_RELOCS(NAME) \ + NAME##_get_reloc_upper_bound, \ + NAME##_canonicalize_reloc, \ + NAME##_set_reloc, \ + NAME##_bfd_reloc_type_lookup, \ + NAME##_bfd_reloc_name_lookup + + long (*_get_reloc_upper_bound) (bfd *, sec_ptr); + long (*_bfd_canonicalize_reloc) (bfd *, sec_ptr, arelent **, + struct bfd_symbol **); + void (*_bfd_set_reloc) (bfd *, sec_ptr, arelent **, unsigned int); + /* See documentation on reloc types. */ + reloc_howto_type * + (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); + reloc_howto_type * + (*reloc_name_lookup) (bfd *, const char *); + + /* Routines used when writing an object file. */ + #define BFD_JUMP_TABLE_WRITE(NAME) \ + NAME##_set_arch_mach, \ + NAME##_set_section_contents + + bool (*_bfd_set_arch_mach) (bfd *, enum bfd_architecture, + unsigned long); + bool (*_bfd_set_section_contents) (bfd *, sec_ptr, const void *, + file_ptr, bfd_size_type); + + /* Routines used by the linker. */ + #define BFD_JUMP_TABLE_LINK(NAME) \ + NAME##_sizeof_headers, \ + NAME##_bfd_get_relocated_section_contents, \ + NAME##_bfd_relax_section, \ + NAME##_bfd_link_hash_table_create, \ + NAME##_bfd_link_add_symbols, \ + NAME##_bfd_link_just_syms, \ + NAME##_bfd_copy_link_hash_symbol_type, \ + NAME##_bfd_final_link, \ + NAME##_bfd_link_split_section, \ + NAME##_bfd_link_check_relocs, \ + NAME##_bfd_gc_sections, \ + NAME##_bfd_lookup_section_flags, \ + NAME##_bfd_merge_sections, \ + NAME##_bfd_is_group_section, \ + NAME##_bfd_group_name, \ + NAME##_bfd_discard_group, \ + NAME##_section_already_linked, \ + NAME##_bfd_define_common_symbol, \ + NAME##_bfd_link_hide_symbol, \ + NAME##_bfd_define_start_stop + + int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *); + bfd_byte * + (*_bfd_get_relocated_section_contents) (bfd *, + struct bfd_link_info *, + struct bfd_link_order *, + bfd_byte *, bool, + struct bfd_symbol **); + + bool (*_bfd_relax_section) (bfd *, struct bfd_section *, + struct bfd_link_info *, bool *); + + /* Create a hash table for the linker. Different backends store + different information in this table. */ + struct bfd_link_hash_table * + (*_bfd_link_hash_table_create) (bfd *); + + /* Add symbols from this object file into the hash table. */ + bool (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); + + /* Indicate that we are only retrieving symbol values from this section. */ + void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); + + /* Copy the symbol type and other attributes for a linker script + assignment of one symbol to another. */ + #define bfd_copy_link_hash_symbol_type(b, t, f) \ + BFD_SEND (b, _bfd_copy_link_hash_symbol_type, (b, t, f)) + void (*_bfd_copy_link_hash_symbol_type) (bfd *, + struct bfd_link_hash_entry *, + struct bfd_link_hash_entry *); + + /* Do a link based on the link_order structures attached to each + section of the BFD. */ + bool (*_bfd_final_link) (bfd *, struct bfd_link_info *); + + /* Should this section be split up into smaller pieces during linking. */ + bool (*_bfd_link_split_section) (bfd *, struct bfd_section *); + + /* Check the relocations in the bfd for validity. */ + bool (* _bfd_link_check_relocs)(bfd *, struct bfd_link_info *); + + /* Remove sections that are not referenced from the output. */ + bool (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); + + /* Sets the bitmask of allowed and disallowed section flags. */ + bool (*_bfd_lookup_section_flags) (struct bfd_link_info *, + struct flag_info *, asection *); + + /* Attempt to merge SEC_MERGE sections. */ + bool (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); + + /* Is this section a member of a group? */ + bool (*_bfd_is_group_section) (bfd *, const struct bfd_section *); + + /* The group name, if section is a member of a group. */ + const char *(*_bfd_group_name) (bfd *, const struct bfd_section *); + + /* Discard members of a group. */ + bool (*_bfd_discard_group) (bfd *, struct bfd_section *); + + /* Check if SEC has been already linked during a reloceatable or + final link. */ + bool (*_section_already_linked) (bfd *, asection *, + struct bfd_link_info *); + + /* Define a common symbol. */ + bool (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Hide a symbol. */ + void (*_bfd_link_hide_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Define a __start, __stop, .startof. or .sizeof. symbol. */ + struct bfd_link_hash_entry * + (*_bfd_define_start_stop) (struct bfd_link_info *, const char *, + asection *); + + /* Routines to handle dynamic symbols and relocs. */ + #define BFD_JUMP_TABLE_DYNAMIC(NAME) \ + NAME##_get_dynamic_symtab_upper_bound, \ + NAME##_canonicalize_dynamic_symtab, \ + NAME##_get_synthetic_symtab, \ + NAME##_get_dynamic_reloc_upper_bound, \ + NAME##_canonicalize_dynamic_reloc + + /* Get the amount of memory required to hold the dynamic symbols. */ + long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); + /* Read in the dynamic symbols. */ + long (*_bfd_canonicalize_dynamic_symtab) (bfd *, struct bfd_symbol **); + /* Create synthetized symbols. */ + long (*_bfd_get_synthetic_symtab) (bfd *, long, struct bfd_symbol **, + long, struct bfd_symbol **, + struct bfd_symbol **); + /* Get the amount of memory required to hold the dynamic relocs. */ + long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); + /* Read in the dynamic relocs. */ + long (*_bfd_canonicalize_dynamic_reloc) (bfd *, arelent **, + struct bfd_symbol **); + + A pointer to an alternative bfd_target in case the current one is not +satisfactory. This can happen when the target cpu supports both big and +little endian code, and target chosen by the linker has the wrong +endianness. The function open_output() in ld/ldlang.c uses this field +to find an alternative output format that is suitable. + /* Opposite endian version of this target. */ + const struct bfd_target *alternative_target; + + /* Data for use by back-end routines, which isn't + generic enough to belong in this structure. */ + const void *backend_data; + + } bfd_target; + + static inline const char * + bfd_get_target (const bfd *abfd) + { + return abfd->xvec->name; + } + + static inline enum bfd_flavour + bfd_get_flavour (const bfd *abfd) + { + return abfd->xvec->flavour; + } + + static inline flagword + bfd_applicable_file_flags (const bfd *abfd) + { + return abfd->xvec->object_flags; + } + + static inline bool + bfd_family_coff (const bfd *abfd) + { + return (bfd_get_flavour (abfd) == bfd_target_coff_flavour + || bfd_get_flavour (abfd) == bfd_target_xcoff_flavour); + } + + static inline bool + bfd_big_endian (const bfd *abfd) + { + return abfd->xvec->byteorder == BFD_ENDIAN_BIG; + } + static inline bool + bfd_little_endian (const bfd *abfd) + { + return abfd->xvec->byteorder == BFD_ENDIAN_LITTLE; + } + + static inline bool + bfd_header_big_endian (const bfd *abfd) + { + return abfd->xvec->header_byteorder == BFD_ENDIAN_BIG; + } + + static inline bool + bfd_header_little_endian (const bfd *abfd) + { + return abfd->xvec->header_byteorder == BFD_ENDIAN_LITTLE; + } + + static inline flagword + bfd_applicable_section_flags (const bfd *abfd) + { + return abfd->xvec->section_flags; + } + + static inline char + bfd_get_symbol_leading_char (const bfd *abfd) + { + return abfd->xvec->symbol_leading_char; + } + + static inline enum bfd_flavour + bfd_asymbol_flavour (const asymbol *sy) + { + if ((sy->flags & BSF_SYNTHETIC) != 0) + return bfd_target_unknown_flavour; + return sy->the_bfd->xvec->flavour; + } + + static inline bool + bfd_keep_unused_section_symbols (const bfd *abfd) + { + return abfd->xvec->keep_unused_section_symbols; + } + + +2.12.1.1 'bfd_set_default_target' +................................. + + -- Function: bool bfd_set_default_target (const char *name); + Set the default target vector to use when recognizing a BFD. This + takes the name of the target, which may be a BFD target name or a + configuration triplet. + +2.12.1.2 'bfd_find_target' +.......................... + + -- Function: const bfd_target *bfd_find_target (const char + *target_name, bfd *abfd); + Return a pointer to the transfer vector for the object target named + TARGET_NAME. If TARGET_NAME is 'NULL', choose the one in the + environment variable 'GNUTARGET'; if that is null or not defined, + then choose the first entry in the target list. Passing in the + string "default" or setting the environment variable to "default" + will cause the first entry in the target list to be returned, and + "target_defaulted" will be set in the BFD if ABFD isn't 'NULL'. + This causes 'bfd_check_format' to loop over all the targets to find + the one that matches the file being read. + +2.12.1.3 'bfd_get_target_info' +.............................. + + -- Function: const bfd_target *bfd_get_target_info (const char + *target_name, bfd *abfd, bool *is_bigendian, int + *underscoring, const char **def_target_arch); + Return a pointer to the transfer vector for the object target named + TARGET_NAME. If TARGET_NAME is 'NULL', choose the one in the + environment variable 'GNUTARGET'; if that is null or not defined, + then choose the first entry in the target list. Passing in the + string "default" or setting the environment variable to "default" + will cause the first entry in the target list to be returned, and + "target_defaulted" will be set in the BFD if ABFD isn't 'NULL'. + This causes 'bfd_check_format' to loop over all the targets to find + the one that matches the file being read. If IS_BIGENDIAN is not + 'NULL', then set this value to target's endian mode. True for + big-endian, FALSE for little-endian or for invalid target. If + UNDERSCORING is not 'NULL', then set this value to target's + underscoring mode. Zero for none-underscoring, -1 for invalid + target, else the value of target vector's symbol underscoring. If + DEF_TARGET_ARCH is not 'NULL', then set it to the architecture + string specified by the target_name. + +2.12.1.4 'bfd_target_list' +.......................... + + -- Function: const char ** bfd_target_list (void); + Return a freshly malloced NULL-terminated vector of the names of + all the valid BFD targets. Do not modify the names. + +2.12.1.5 'bfd_iterate_over_targets' +................................... + + -- Function: const bfd_target *bfd_iterate_over_targets (int (*func) + (const bfd_target *, void *), void *data); + Call FUNC for each target in the list of BFD target vectors, + passing DATA to FUNC. Stop iterating if FUNC returns a non-zero + result, and return that target vector. Return NULL if FUNC always + returns zero. + +2.12.1.6 'bfd_flavour_name' +........................... + + -- Function: const char *bfd_flavour_name (enum bfd_flavour flavour); + Return the string form of FLAVOUR. + + +File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end + +2.13 Architectures +================== + +BFD keeps one atom in a BFD describing the architecture of the data +attached to the BFD: a pointer to a 'bfd_arch_info_type'. + + Pointers to structures can be requested independently of a BFD so +that an architecture's information can be interrogated without access to +an open BFD. + + The architecture information is provided by each architecture +package. The set of default architectures is selected by the macro +'SELECT_ARCHITECTURES'. This is normally set up in the +'config/TARGET.mt' file of your choice. If the name is not defined, +then all the architectures supported are included. + + When BFD starts up, all the architectures are called with an +initialize method. It is up to the architecture back end to insert as +many items into the list of architectures as it wants to; generally this +would be one for each machine and one for the default case (an item with +a machine field of 0). + + BFD's idea of an architecture is implemented in 'archures.c'. + +2.13.1 bfd_architecture +----------------------- + +This enum gives the object file's CPU architecture, in a global +sense--i.e., what processor family does it belong to? Another field +indicates which processor within the family is in use. The machine +gives a number which distinguishes different versions of the +architecture, containing, for example, 68020 for Motorola 68020. + enum bfd_architecture + { + bfd_arch_unknown, /* File arch not known. */ + bfd_arch_obscure, /* Arch known, not one of these. */ + bfd_arch_m68k, /* Motorola 68xxx. */ + #define bfd_mach_m68000 1 + #define bfd_mach_m68008 2 + #define bfd_mach_m68010 3 + #define bfd_mach_m68020 4 + #define bfd_mach_m68030 5 + #define bfd_mach_m68040 6 + #define bfd_mach_m68060 7 + #define bfd_mach_cpu32 8 + #define bfd_mach_fido 9 + #define bfd_mach_mcf_isa_a_nodiv 10 + #define bfd_mach_mcf_isa_a 11 + #define bfd_mach_mcf_isa_a_mac 12 + #define bfd_mach_mcf_isa_a_emac 13 + #define bfd_mach_mcf_isa_aplus 14 + #define bfd_mach_mcf_isa_aplus_mac 15 + #define bfd_mach_mcf_isa_aplus_emac 16 + #define bfd_mach_mcf_isa_b_nousp 17 + #define bfd_mach_mcf_isa_b_nousp_mac 18 + #define bfd_mach_mcf_isa_b_nousp_emac 19 + #define bfd_mach_mcf_isa_b 20 + #define bfd_mach_mcf_isa_b_mac 21 + #define bfd_mach_mcf_isa_b_emac 22 + #define bfd_mach_mcf_isa_b_float 23 + #define bfd_mach_mcf_isa_b_float_mac 24 + #define bfd_mach_mcf_isa_b_float_emac 25 + #define bfd_mach_mcf_isa_c 26 + #define bfd_mach_mcf_isa_c_mac 27 + #define bfd_mach_mcf_isa_c_emac 28 + #define bfd_mach_mcf_isa_c_nodiv 29 + #define bfd_mach_mcf_isa_c_nodiv_mac 30 + #define bfd_mach_mcf_isa_c_nodiv_emac 31 + bfd_arch_vax, /* DEC Vax. */ + + bfd_arch_or1k, /* OpenRISC 1000. */ + #define bfd_mach_or1k 1 + #define bfd_mach_or1knd 2 + + bfd_arch_sparc, /* SPARC. */ + #define bfd_mach_sparc 1 + /* The difference between v8plus and v9 is that v9 is a true 64 bit env. */ + #define bfd_mach_sparc_sparclet 2 + #define bfd_mach_sparc_sparclite 3 + #define bfd_mach_sparc_v8plus 4 + #define bfd_mach_sparc_v8plusa 5 /* with ultrasparc add'ns. */ + #define bfd_mach_sparc_sparclite_le 6 + #define bfd_mach_sparc_v9 7 + #define bfd_mach_sparc_v9a 8 /* with ultrasparc add'ns. */ + #define bfd_mach_sparc_v8plusb 9 /* with cheetah add'ns. */ + #define bfd_mach_sparc_v9b 10 /* with cheetah add'ns. */ + #define bfd_mach_sparc_v8plusc 11 /* with UA2005 and T1 add'ns. */ + #define bfd_mach_sparc_v9c 12 /* with UA2005 and T1 add'ns. */ + #define bfd_mach_sparc_v8plusd 13 /* with UA2007 and T3 add'ns. */ + #define bfd_mach_sparc_v9d 14 /* with UA2007 and T3 add'ns. */ + #define bfd_mach_sparc_v8pluse 15 /* with OSA2001 and T4 add'ns (no IMA). */ + #define bfd_mach_sparc_v9e 16 /* with OSA2001 and T4 add'ns (no IMA). */ + #define bfd_mach_sparc_v8plusv 17 /* with OSA2011 and T4 and IMA and FJMAU add'ns. */ + #define bfd_mach_sparc_v9v 18 /* with OSA2011 and T4 and IMA and FJMAU add'ns. */ + #define bfd_mach_sparc_v8plusm 19 /* with OSA2015 and M7 add'ns. */ + #define bfd_mach_sparc_v9m 20 /* with OSA2015 and M7 add'ns. */ + #define bfd_mach_sparc_v8plusm8 21 /* with OSA2017 and M8 add'ns. */ + #define bfd_mach_sparc_v9m8 22 /* with OSA2017 and M8 add'ns. */ + /* Nonzero if MACH has the v9 instruction set. */ + #define bfd_mach_sparc_v9_p(mach) \ + ((mach) >= bfd_mach_sparc_v8plus && (mach) <= bfd_mach_sparc_v9m8 \ + && (mach) != bfd_mach_sparc_sparclite_le) + /* Nonzero if MACH is a 64 bit sparc architecture. */ + #define bfd_mach_sparc_64bit_p(mach) \ + ((mach) >= bfd_mach_sparc_v9 \ + && (mach) != bfd_mach_sparc_v8plusb \ + && (mach) != bfd_mach_sparc_v8plusc \ + && (mach) != bfd_mach_sparc_v8plusd \ + && (mach) != bfd_mach_sparc_v8pluse \ + && (mach) != bfd_mach_sparc_v8plusv \ + && (mach) != bfd_mach_sparc_v8plusm \ + && (mach) != bfd_mach_sparc_v8plusm8) + bfd_arch_spu, /* PowerPC SPU. */ + #define bfd_mach_spu 256 + bfd_arch_mips, /* MIPS Rxxxx. */ + #define bfd_mach_mips3000 3000 + #define bfd_mach_mips3900 3900 + #define bfd_mach_mips4000 4000 + #define bfd_mach_mips4010 4010 + #define bfd_mach_mips4100 4100 + #define bfd_mach_mips4111 4111 + #define bfd_mach_mips4120 4120 + #define bfd_mach_mips4300 4300 + #define bfd_mach_mips4400 4400 + #define bfd_mach_mips4600 4600 + #define bfd_mach_mips4650 4650 + #define bfd_mach_mips5000 5000 + #define bfd_mach_mips5400 5400 + #define bfd_mach_mips5500 5500 + #define bfd_mach_mips5900 5900 + #define bfd_mach_mips6000 6000 + #define bfd_mach_mips7000 7000 + #define bfd_mach_mips8000 8000 + #define bfd_mach_mips9000 9000 + #define bfd_mach_mips10000 10000 + #define bfd_mach_mips12000 12000 + #define bfd_mach_mips14000 14000 + #define bfd_mach_mips16000 16000 + #define bfd_mach_mips16 16 + #define bfd_mach_mips5 5 + #define bfd_mach_mips_allegrex 10111431 /* octal 'AL', 31. */ + #define bfd_mach_mips_loongson_2e 3001 + #define bfd_mach_mips_loongson_2f 3002 + #define bfd_mach_mips_gs464 3003 + #define bfd_mach_mips_gs464e 3004 + #define bfd_mach_mips_gs264e 3005 + #define bfd_mach_mips_sb1 12310201 /* octal 'SB', 01. */ + #define bfd_mach_mips_octeon 6501 + #define bfd_mach_mips_octeonp 6601 + #define bfd_mach_mips_octeon2 6502 + #define bfd_mach_mips_octeon3 6503 + #define bfd_mach_mips_xlr 887682 /* decimal 'XLR'. */ + #define bfd_mach_mips_interaptiv_mr2 736550 /* decimal 'IA2'. */ + #define bfd_mach_mipsisa32 32 + #define bfd_mach_mipsisa32r2 33 + #define bfd_mach_mipsisa32r3 34 + #define bfd_mach_mipsisa32r5 36 + #define bfd_mach_mipsisa32r6 37 + #define bfd_mach_mipsisa64 64 + #define bfd_mach_mipsisa64r2 65 + #define bfd_mach_mipsisa64r3 66 + #define bfd_mach_mipsisa64r5 68 + #define bfd_mach_mipsisa64r6 69 + #define bfd_mach_mips_micromips 96 + bfd_arch_i386, /* Intel 386. */ + #define bfd_mach_i386_intel_syntax (1 << 0) + #define bfd_mach_i386_i8086 (1 << 1) + #define bfd_mach_i386_i386 (1 << 2) + #define bfd_mach_x86_64 (1 << 3) + #define bfd_mach_x64_32 (1 << 4) + #define bfd_mach_i386_i386_intel_syntax (bfd_mach_i386_i386 | bfd_mach_i386_intel_syntax) + #define bfd_mach_x86_64_intel_syntax (bfd_mach_x86_64 | bfd_mach_i386_intel_syntax) + #define bfd_mach_x64_32_intel_syntax (bfd_mach_x64_32 | bfd_mach_i386_intel_syntax) + bfd_arch_iamcu, /* Intel MCU. */ + #define bfd_mach_iamcu (1 << 8) + #define bfd_mach_i386_iamcu (bfd_mach_i386_i386 | bfd_mach_iamcu) + #define bfd_mach_i386_iamcu_intel_syntax (bfd_mach_i386_iamcu | bfd_mach_i386_intel_syntax) + bfd_arch_romp, /* IBM ROMP PC/RT. */ + bfd_arch_convex, /* Convex. */ + bfd_arch_m98k, /* Motorola 98xxx. */ + bfd_arch_pyramid, /* Pyramid Technology. */ + bfd_arch_h8300, /* Renesas H8/300 (formerly Hitachi H8/300). */ + #define bfd_mach_h8300 1 + #define bfd_mach_h8300h 2 + #define bfd_mach_h8300s 3 + #define bfd_mach_h8300hn 4 + #define bfd_mach_h8300sn 5 + #define bfd_mach_h8300sx 6 + #define bfd_mach_h8300sxn 7 + bfd_arch_pdp11, /* DEC PDP-11. */ + bfd_arch_powerpc, /* PowerPC. */ + #define bfd_mach_ppc 32 + #define bfd_mach_ppc64 64 + #define bfd_mach_ppc_403 403 + #define bfd_mach_ppc_403gc 4030 + #define bfd_mach_ppc_405 405 + #define bfd_mach_ppc_505 505 + #define bfd_mach_ppc_601 601 + #define bfd_mach_ppc_602 602 + #define bfd_mach_ppc_603 603 + #define bfd_mach_ppc_ec603e 6031 + #define bfd_mach_ppc_604 604 + #define bfd_mach_ppc_620 620 + #define bfd_mach_ppc_630 630 + #define bfd_mach_ppc_750 750 + #define bfd_mach_ppc_860 860 + #define bfd_mach_ppc_a35 35 + #define bfd_mach_ppc_rs64ii 642 + #define bfd_mach_ppc_rs64iii 643 + #define bfd_mach_ppc_7400 7400 + #define bfd_mach_ppc_e500 500 + #define bfd_mach_ppc_e500mc 5001 + #define bfd_mach_ppc_e500mc64 5005 + #define bfd_mach_ppc_e5500 5006 + #define bfd_mach_ppc_e6500 5007 + #define bfd_mach_ppc_titan 83 + #define bfd_mach_ppc_vle 84 + bfd_arch_rs6000, /* IBM RS/6000. */ + #define bfd_mach_rs6k 6000 + #define bfd_mach_rs6k_rs1 6001 + #define bfd_mach_rs6k_rsc 6003 + #define bfd_mach_rs6k_rs2 6002 + bfd_arch_hppa, /* HP PA RISC. */ + #define bfd_mach_hppa10 10 + #define bfd_mach_hppa11 11 + #define bfd_mach_hppa20 20 + #define bfd_mach_hppa20w 25 + bfd_arch_d10v, /* Mitsubishi D10V. */ + #define bfd_mach_d10v 1 + #define bfd_mach_d10v_ts2 2 + #define bfd_mach_d10v_ts3 3 + bfd_arch_d30v, /* Mitsubishi D30V. */ + bfd_arch_dlx, /* DLX. */ + bfd_arch_m68hc11, /* Motorola 68HC11. */ + bfd_arch_m68hc12, /* Motorola 68HC12. */ + #define bfd_mach_m6812_default 0 + #define bfd_mach_m6812 1 + #define bfd_mach_m6812s 2 + bfd_arch_m9s12x, /* Freescale S12X. */ + bfd_arch_m9s12xg, /* Freescale XGATE. */ + bfd_arch_s12z, /* Freescale S12Z. */ + #define bfd_mach_s12z_default 0 + bfd_arch_z8k, /* Zilog Z8000. */ + #define bfd_mach_z8001 1 + #define bfd_mach_z8002 2 + bfd_arch_sh, /* Renesas / SuperH SH (formerly Hitachi SH). */ + #define bfd_mach_sh 1 + #define bfd_mach_sh2 0x20 + #define bfd_mach_sh_dsp 0x2d + #define bfd_mach_sh2a 0x2a + #define bfd_mach_sh2a_nofpu 0x2b + #define bfd_mach_sh2a_nofpu_or_sh4_nommu_nofpu 0x2a1 + #define bfd_mach_sh2a_nofpu_or_sh3_nommu 0x2a2 + #define bfd_mach_sh2a_or_sh4 0x2a3 + #define bfd_mach_sh2a_or_sh3e 0x2a4 + #define bfd_mach_sh2e 0x2e + #define bfd_mach_sh3 0x30 + #define bfd_mach_sh3_nommu 0x31 + #define bfd_mach_sh3_dsp 0x3d + #define bfd_mach_sh3e 0x3e + #define bfd_mach_sh4 0x40 + #define bfd_mach_sh4_nofpu 0x41 + #define bfd_mach_sh4_nommu_nofpu 0x42 + #define bfd_mach_sh4a 0x4a + #define bfd_mach_sh4a_nofpu 0x4b + #define bfd_mach_sh4al_dsp 0x4d + bfd_arch_alpha, /* Dec Alpha. */ + #define bfd_mach_alpha_ev4 0x10 + #define bfd_mach_alpha_ev5 0x20 + #define bfd_mach_alpha_ev6 0x30 + bfd_arch_arm, /* Advanced Risc Machines ARM. */ + #define bfd_mach_arm_unknown 0 + #define bfd_mach_arm_2 1 + #define bfd_mach_arm_2a 2 + #define bfd_mach_arm_3 3 + #define bfd_mach_arm_3M 4 + #define bfd_mach_arm_4 5 + #define bfd_mach_arm_4T 6 + #define bfd_mach_arm_5 7 + #define bfd_mach_arm_5T 8 + #define bfd_mach_arm_5TE 9 + #define bfd_mach_arm_XScale 10 + #define bfd_mach_arm_ep9312 11 + #define bfd_mach_arm_iWMMXt 12 + #define bfd_mach_arm_iWMMXt2 13 + #define bfd_mach_arm_5TEJ 14 + #define bfd_mach_arm_6 15 + #define bfd_mach_arm_6KZ 16 + #define bfd_mach_arm_6T2 17 + #define bfd_mach_arm_6K 18 + #define bfd_mach_arm_7 19 + #define bfd_mach_arm_6M 20 + #define bfd_mach_arm_6SM 21 + #define bfd_mach_arm_7EM 22 + #define bfd_mach_arm_8 23 + #define bfd_mach_arm_8R 24 + #define bfd_mach_arm_8M_BASE 25 + #define bfd_mach_arm_8M_MAIN 26 + #define bfd_mach_arm_8_1M_MAIN 27 + #define bfd_mach_arm_9 28 + bfd_arch_nds32, /* Andes NDS32. */ + #define bfd_mach_n1 1 + #define bfd_mach_n1h 2 + #define bfd_mach_n1h_v2 3 + #define bfd_mach_n1h_v3 4 + #define bfd_mach_n1h_v3m 5 + bfd_arch_ns32k, /* National Semiconductors ns32000. */ + bfd_arch_tic30, /* Texas Instruments TMS320C30. */ + bfd_arch_tic4x, /* Texas Instruments TMS320C3X/4X. */ + #define bfd_mach_tic3x 30 + #define bfd_mach_tic4x 40 + bfd_arch_tic54x, /* Texas Instruments TMS320C54X. */ + bfd_arch_tic6x, /* Texas Instruments TMS320C6X. */ + bfd_arch_v850, /* NEC V850. */ + bfd_arch_v850_rh850,/* NEC V850 (using RH850 ABI). */ + #define bfd_mach_v850 1 + #define bfd_mach_v850e 'E' + #define bfd_mach_v850e1 '1' + #define bfd_mach_v850e2 0x4532 + #define bfd_mach_v850e2v3 0x45325633 + #define bfd_mach_v850e3v5 0x45335635 /* ('E'|'3'|'V'|'5'). */ + bfd_arch_arc, /* ARC Cores. */ + #define bfd_mach_arc_a4 0 + #define bfd_mach_arc_a5 1 + #define bfd_mach_arc_arc600 2 + #define bfd_mach_arc_arc601 4 + #define bfd_mach_arc_arc700 3 + #define bfd_mach_arc_arcv2 5 + bfd_arch_m32c, /* Renesas M16C/M32C. */ + #define bfd_mach_m16c 0x75 + #define bfd_mach_m32c 0x78 + bfd_arch_m32r, /* Renesas M32R (formerly Mitsubishi M32R/D). */ + #define bfd_mach_m32r 1 /* For backwards compatibility. */ + #define bfd_mach_m32rx 'x' + #define bfd_mach_m32r2 '2' + bfd_arch_mn10200, /* Matsushita MN10200. */ + bfd_arch_mn10300, /* Matsushita MN10300. */ + #define bfd_mach_mn10300 300 + #define bfd_mach_am33 330 + #define bfd_mach_am33_2 332 + bfd_arch_fr30, + #define bfd_mach_fr30 0x46523330 + bfd_arch_frv, + #define bfd_mach_frv 1 + #define bfd_mach_frvsimple 2 + #define bfd_mach_fr300 300 + #define bfd_mach_fr400 400 + #define bfd_mach_fr450 450 + #define bfd_mach_frvtomcat 499 /* fr500 prototype. */ + #define bfd_mach_fr500 500 + #define bfd_mach_fr550 550 + bfd_arch_moxie, /* The moxie processor. */ + #define bfd_mach_moxie 1 + bfd_arch_ft32, /* The ft32 processor. */ + #define bfd_mach_ft32 1 + #define bfd_mach_ft32b 2 + bfd_arch_mcore, + bfd_arch_mep, + #define bfd_mach_mep 1 + #define bfd_mach_mep_h1 0x6831 + #define bfd_mach_mep_c5 0x6335 + bfd_arch_metag, + #define bfd_mach_metag 1 + bfd_arch_ia64, /* HP/Intel ia64. */ + #define bfd_mach_ia64_elf64 64 + #define bfd_mach_ia64_elf32 32 + bfd_arch_ip2k, /* Ubicom IP2K microcontrollers. */ + #define bfd_mach_ip2022 1 + #define bfd_mach_ip2022ext 2 + bfd_arch_iq2000, /* Vitesse IQ2000. */ + #define bfd_mach_iq2000 1 + #define bfd_mach_iq10 2 + bfd_arch_bpf, /* Linux eBPF. */ + #define bfd_mach_bpf 1 + #define bfd_mach_xbpf 2 + bfd_arch_epiphany, /* Adapteva EPIPHANY. */ + #define bfd_mach_epiphany16 1 + #define bfd_mach_epiphany32 2 + bfd_arch_mt, + #define bfd_mach_ms1 1 + #define bfd_mach_mrisc2 2 + #define bfd_mach_ms2 3 + bfd_arch_pj, + bfd_arch_avr, /* Atmel AVR microcontrollers. */ + #define bfd_mach_avr1 1 + #define bfd_mach_avr2 2 + #define bfd_mach_avr25 25 + #define bfd_mach_avr3 3 + #define bfd_mach_avr31 31 + #define bfd_mach_avr35 35 + #define bfd_mach_avr4 4 + #define bfd_mach_avr5 5 + #define bfd_mach_avr51 51 + #define bfd_mach_avr6 6 + #define bfd_mach_avrtiny 100 + #define bfd_mach_avrxmega1 101 + #define bfd_mach_avrxmega2 102 + #define bfd_mach_avrxmega3 103 + #define bfd_mach_avrxmega4 104 + #define bfd_mach_avrxmega5 105 + #define bfd_mach_avrxmega6 106 + #define bfd_mach_avrxmega7 107 + bfd_arch_bfin, /* ADI Blackfin. */ + #define bfd_mach_bfin 1 + bfd_arch_cr16, /* National Semiconductor CompactRISC (ie CR16). */ + #define bfd_mach_cr16 1 + bfd_arch_crx, /* National Semiconductor CRX. */ + #define bfd_mach_crx 1 + bfd_arch_cris, /* Axis CRIS. */ + #define bfd_mach_cris_v0_v10 255 + #define bfd_mach_cris_v32 32 + #define bfd_mach_cris_v10_v32 1032 + bfd_arch_riscv, + #define bfd_mach_riscv32 132 + #define bfd_mach_riscv64 164 + bfd_arch_rl78, + #define bfd_mach_rl78 0x75 + bfd_arch_rx, /* Renesas RX. */ + #define bfd_mach_rx 0x75 + #define bfd_mach_rx_v2 0x76 + #define bfd_mach_rx_v3 0x77 + bfd_arch_s390, /* IBM s390. */ + #define bfd_mach_s390_31 31 + #define bfd_mach_s390_64 64 + bfd_arch_score, /* Sunplus score. */ + #define bfd_mach_score3 3 + #define bfd_mach_score7 7 + bfd_arch_mmix, /* Donald Knuth's educational processor. */ + bfd_arch_xstormy16, + #define bfd_mach_xstormy16 1 + bfd_arch_msp430, /* Texas Instruments MSP430 architecture. */ + #define bfd_mach_msp11 11 + #define bfd_mach_msp110 110 + #define bfd_mach_msp12 12 + #define bfd_mach_msp13 13 + #define bfd_mach_msp14 14 + #define bfd_mach_msp15 15 + #define bfd_mach_msp16 16 + #define bfd_mach_msp20 20 + #define bfd_mach_msp21 21 + #define bfd_mach_msp22 22 + #define bfd_mach_msp23 23 + #define bfd_mach_msp24 24 + #define bfd_mach_msp26 26 + #define bfd_mach_msp31 31 + #define bfd_mach_msp32 32 + #define bfd_mach_msp33 33 + #define bfd_mach_msp41 41 + #define bfd_mach_msp42 42 + #define bfd_mach_msp43 43 + #define bfd_mach_msp44 44 + #define bfd_mach_msp430x 45 + #define bfd_mach_msp46 46 + #define bfd_mach_msp47 47 + #define bfd_mach_msp54 54 + bfd_arch_xgate, /* Freescale XGATE. */ + #define bfd_mach_xgate 1 + bfd_arch_xtensa, /* Tensilica's Xtensa cores. */ + #define bfd_mach_xtensa 1 + bfd_arch_z80, + /* Zilog Z80 without undocumented opcodes. */ + #define bfd_mach_z80strict 1 + /* Zilog Z180: successor with additional instructions, but without + halves of ix and iy. */ + #define bfd_mach_z180 2 + /* Zilog Z80 with ixl, ixh, iyl, and iyh. */ + #define bfd_mach_z80 3 + /* Zilog eZ80 (successor of Z80 & Z180) in Z80 (16-bit address) mode. */ + #define bfd_mach_ez80_z80 4 + /* Zilog eZ80 (successor of Z80 & Z180) in ADL (24-bit address) mode. */ + #define bfd_mach_ez80_adl 5 + /* Z80N */ + #define bfd_mach_z80n 6 + /* Zilog Z80 with all undocumented instructions. */ + #define bfd_mach_z80full 7 + /* GameBoy Z80 (reduced instruction set). */ + #define bfd_mach_gbz80 8 + /* ASCII R800: successor with multiplication. */ + #define bfd_mach_r800 11 + bfd_arch_lm32, /* Lattice Mico32. */ + #define bfd_mach_lm32 1 + bfd_arch_microblaze,/* Xilinx MicroBlaze. */ + bfd_arch_kvx, /* Kalray VLIW core of the MPPA processor family */ + #define bfd_mach_kv3_unknown 0 + #define bfd_mach_kv3_1 1 + #define bfd_mach_kv3_1_64 2 + #define bfd_mach_kv3_1_usr 3 + #define bfd_mach_kv3_2 4 + #define bfd_mach_kv3_2_64 5 + #define bfd_mach_kv3_2_usr 6 + #define bfd_mach_kv4_1 7 + #define bfd_mach_kv4_1_64 8 + #define bfd_mach_kv4_1_usr 9 + bfd_arch_tilepro, /* Tilera TILEPro. */ + bfd_arch_tilegx, /* Tilera TILE-Gx. */ + #define bfd_mach_tilepro 1 + #define bfd_mach_tilegx 1 + #define bfd_mach_tilegx32 2 + bfd_arch_aarch64, /* AArch64. */ + #define bfd_mach_aarch64 0 + #define bfd_mach_aarch64_8R 1 + #define bfd_mach_aarch64_ilp32 32 + #define bfd_mach_aarch64_llp64 64 + bfd_arch_visium, /* Visium. */ + #define bfd_mach_visium 1 + bfd_arch_wasm32, /* WebAssembly. */ + #define bfd_mach_wasm32 1 + bfd_arch_pru, /* PRU. */ + #define bfd_mach_pru 0 + bfd_arch_nfp, /* Netronome Flow Processor */ + #define bfd_mach_nfp3200 0x3200 + #define bfd_mach_nfp6000 0x6000 + bfd_arch_csky, /* C-SKY. */ + #define bfd_mach_ck_unknown 0 + #define bfd_mach_ck510 1 + #define bfd_mach_ck610 2 + #define bfd_mach_ck801 3 + #define bfd_mach_ck802 4 + #define bfd_mach_ck803 5 + #define bfd_mach_ck807 6 + #define bfd_mach_ck810 7 + #define bfd_mach_ck860 8 + bfd_arch_loongarch, /* LoongArch */ + #define bfd_mach_loongarch32 1 + #define bfd_mach_loongarch64 2 + bfd_arch_amdgcn, /* AMDGCN */ + #define bfd_mach_amdgcn_unknown 0x000 + #define bfd_mach_amdgcn_gfx900 0x02c + #define bfd_mach_amdgcn_gfx904 0x02e + #define bfd_mach_amdgcn_gfx906 0x02f + #define bfd_mach_amdgcn_gfx908 0x030 + #define bfd_mach_amdgcn_gfx90a 0x03f + #define bfd_mach_amdgcn_gfx1010 0x033 + #define bfd_mach_amdgcn_gfx1011 0x034 + #define bfd_mach_amdgcn_gfx1012 0x035 + #define bfd_mach_amdgcn_gfx1030 0x036 + #define bfd_mach_amdgcn_gfx1031 0x037 + #define bfd_mach_amdgcn_gfx1032 0x038 + #define bfd_mach_amdgcn_gfx1100 0x041 + #define bfd_mach_amdgcn_gfx1101 0x046 + #define bfd_mach_amdgcn_gfx1102 0x047 + bfd_arch_last + }; + +2.13.2 bfd_arch_info +-------------------- + +This structure contains information on architectures for use within BFD. + + typedef struct bfd_arch_info + { + int bits_per_word; + int bits_per_address; + int bits_per_byte; + enum bfd_architecture arch; + unsigned long mach; + const char *arch_name; + const char *printable_name; + unsigned int section_align_power; + /* TRUE if this is the default machine for the architecture. + The default arch should be the first entry for an arch so that + all the entries for that arch can be accessed via next. */ + bool the_default; + const struct bfd_arch_info * (*compatible) (const struct bfd_arch_info *, + const struct bfd_arch_info *); + + bool (*scan) (const struct bfd_arch_info *, const char *); + + /* Allocate via bfd_malloc and return a fill buffer of size COUNT. If + IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is + TRUE, the buffer contains code. */ + void *(*fill) (bfd_size_type count, bool is_bigendian, bool code); + + const struct bfd_arch_info *next; + + /* On some architectures the offset for a relocation can point into + the middle of an instruction. This field specifies the maximum + offset such a relocation can have (in octets). This affects the + behaviour of the disassembler, since a value greater than zero + means that it may need to disassemble an instruction twice, once + to get its length and then a second time to display it. If the + value is negative then this has to be done for every single + instruction, regardless of the offset of the reloc. */ + signed int max_reloc_offset_into_insn; + } + bfd_arch_info_type; + + +2.13.2.1 'bfd_printable_name' +............................. + + -- Function: const char *bfd_printable_name (bfd *abfd); + Return a printable string representing the architecture and machine + from the pointer to the architecture info structure. + +2.13.2.2 'bfd_scan_arch' +........................ + + -- Function: const bfd_arch_info_type *bfd_scan_arch (const char + *string); + Figure out if BFD supports any cpu which could be described with + the name STRING. Return a pointer to an 'arch_info' structure if a + machine is found, otherwise NULL. + +2.13.2.3 'bfd_arch_list' +........................ + + -- Function: const char **bfd_arch_list (void); + Return a freshly malloced NULL-terminated vector of the names of + all the valid BFD architectures. Do not modify the names. + +2.13.2.4 'bfd_arch_get_compatible' +.................................. + + -- Function: const bfd_arch_info_type *bfd_arch_get_compatible (const + bfd *abfd, const bfd *bbfd, bool accept_unknowns); + Determine whether two BFDs' architectures and machine types are + compatible. Calculates the lowest common denominator between the + two architectures and machine types implied by the BFDs and returns + a pointer to an 'arch_info' structure describing the compatible + machine. + +2.13.2.5 'bfd_default_arch_struct' +.................................. + +The 'bfd_default_arch_struct' is an item of 'bfd_arch_info_type' which +has been initialized to a fairly generic state. A BFD starts life by +pointing to this structure, until the correct back end has determined +the real architecture of the file. + extern const bfd_arch_info_type bfd_default_arch_struct; + + +2.13.2.6 'bfd_set_arch_info' +............................ + + -- Function: void bfd_set_arch_info (bfd *abfd, const + bfd_arch_info_type *arg); + Set the architecture info of ABFD to ARG. + +2.13.2.7 'bfd_default_set_arch_mach' +.................................... + + -- Function: bool bfd_default_set_arch_mach (bfd *abfd, enum + bfd_architecture arch, unsigned long mach); + Set the architecture and machine type in BFD ABFD to ARCH and MACH. + Find the correct pointer to a structure and insert it into the + 'arch_info' pointer. + +2.13.2.8 'bfd_get_arch' +....................... + + -- Function: enum bfd_architecture bfd_get_arch (const bfd *abfd); + Return the enumerated type which describes the BFD ABFD's + architecture. + +2.13.2.9 'bfd_get_mach' +....................... + + -- Function: unsigned long bfd_get_mach (const bfd *abfd); + Return the long type which describes the BFD ABFD's machine. + +2.13.2.10 'bfd_arch_bits_per_byte' +.................................. + + -- Function: unsigned int bfd_arch_bits_per_byte (const bfd *abfd); + Return the number of bits in one of the BFD ABFD's architecture's + bytes. + +2.13.2.11 'bfd_arch_bits_per_address' +..................................... + + -- Function: unsigned int bfd_arch_bits_per_address (const bfd *abfd); + Return the number of bits in one of the BFD ABFD's architecture's + addresses. + +2.13.2.12 'bfd_default_compatible' +.................................. + + -- Function: const bfd_arch_info_type *bfd_default_compatible (const + bfd_arch_info_type *a, const bfd_arch_info_type *b); + The default function for testing for compatibility. + +2.13.2.13 'bfd_default_scan' +............................ + + -- Function: bool bfd_default_scan (const struct bfd_arch_info *info, + const char *string); + The default function for working out whether this is an + architecture hit and a machine hit. + +2.13.2.14 'bfd_get_arch_info' +............................. + + -- Function: const bfd_arch_info_type *bfd_get_arch_info (bfd *abfd); + Return the architecture info struct in ABFD. + +2.13.2.15 'bfd_lookup_arch' +........................... + + -- Function: const bfd_arch_info_type *bfd_lookup_arch (enum + bfd_architecture arch, unsigned long machine); + Look for the architecture info structure which matches the + arguments ARCH and MACHINE. A machine of 0 matches the + machine/architecture structure which marks itself as the default. + +2.13.2.16 'bfd_printable_arch_mach' +................................... + + -- Function: const char *bfd_printable_arch_mach (enum bfd_architecture + arch, unsigned long machine); + Return a printable string representing the architecture and machine + type. + + This routine is depreciated. + +2.13.2.17 'bfd_octets_per_byte' +............................... + + -- Function: unsigned int bfd_octets_per_byte (const bfd *abfd, const + asection *sec); + Return the number of octets (8-bit quantities) per target byte + (minimum addressable unit). In most cases, this will be one, but + some DSP targets have 16, 32, or even 48 bits per byte. + +2.13.2.18 'bfd_arch_mach_octets_per_byte' +......................................... + + -- Function: unsigned int bfd_arch_mach_octets_per_byte (enum + bfd_architecture arch, unsigned long machine); + See bfd_octets_per_byte. + + This routine is provided for those cases where a bfd * is not + available + +2.13.2.19 'bfd_arch_default_fill' +................................. + + -- Function: void *bfd_arch_default_fill (bfd_size_type count, bool + is_bigendian, bool code); + Allocate via bfd_malloc and return a fill buffer of size COUNT. If + IS_BIGENDIAN is TRUE, the order of bytes is big endian. If CODE is + TRUE, the buffer contains code. + + +File: bfd.info, Node: Opening and Closing, Next: Internal, Prev: Architectures, Up: BFD front end + +2.14 Opening and closing BFDs +============================= + +2.14.1 Functions for opening and closing +---------------------------------------- + +2.14.1.1 '_bfd_new_bfd' +....................... + + -- Function: bfd *_bfd_new_bfd (void); + Return a new BFD. All BFD's are allocated through this routine. + +2.14.1.2 '_bfd_new_bfd_contained_in' +.................................... + + -- Function: bfd *_bfd_new_bfd_contained_in (bfd *); + Allocate a new BFD as a member of archive OBFD. + +2.14.1.3 '_bfd_free_cached_info' +................................ + + -- Function: bool _bfd_free_cached_info (bfd *); + Free objalloc memory. + +2.14.1.4 'bfd_fopen' +.................... + + -- Function: bfd *bfd_fopen (const char *filename, const char *target, + const char *mode, int fd); + Open the file FILENAME with the target TARGET. Return a pointer to + the created BFD. If FD is not -1, then 'fdopen' is used to open the + file; otherwise, 'fopen' is used. MODE is passed directly to + 'fopen' or 'fdopen'. + + Calls 'bfd_find_target', so TARGET is interpreted as by that + function. + + The new BFD is marked as cacheable iff FD is -1. + + If 'NULL' is returned then an error has occured. Possible errors + are 'bfd_error_no_memory', 'bfd_error_invalid_target' or + 'system_call' error. + + On error, FD is always closed. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.5 'bfd_openr' +.................... + + -- Function: bfd *bfd_openr (const char *filename, const char *target); + Open the file FILENAME (using 'fopen') with the target TARGET. + Return a pointer to the created BFD. + + Calls 'bfd_find_target', so TARGET is interpreted as by that + function. + + If 'NULL' is returned then an error has occured. Possible errors + are 'bfd_error_no_memory', 'bfd_error_invalid_target' or + 'system_call' error. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.6 'bfd_fdopenr' +...................... + + -- Function: bfd *bfd_fdopenr (const char *filename, const char + *target, int fd); + 'bfd_fdopenr' is to 'bfd_fopenr' much like 'fdopen' is to 'fopen'. + It opens a BFD on a file already described by the FD supplied. + + When the file is later 'bfd_close'd, the file descriptor will be + closed. If the caller desires that this file descriptor be cached + by BFD (opened as needed, closed as needed to free descriptors for + other opens), with the supplied FD used as an initial file + descriptor (but subject to closure at any time), call + bfd_set_cacheable(bfd, 1) on the returned BFD. The default is to + assume no caching; the file descriptor will remain open until + 'bfd_close', and will not be affected by BFD operations on other + files. + + Possible errors are 'bfd_error_no_memory', + 'bfd_error_invalid_target' and 'bfd_error_system_call'. + + On error, FD is closed. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.7 'bfd_fdopenw' +...................... + + -- Function: bfd *bfd_fdopenw (const char *filename, const char + *target, int fd); + 'bfd_fdopenw' is exactly like 'bfd_fdopenr' with the exception that + the resulting BFD is suitable for output. + +2.14.1.8 'bfd_openstreamr' +.......................... + + -- Function: bfd *bfd_openstreamr (const char * filename, const char * + target, void * stream); + Open a BFD for read access on an existing stdio stream. When the + BFD is passed to 'bfd_close', the stream will be closed. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.9 'bfd_openr_iovec' +.......................... + + -- Function: bfd *bfd_openr_iovec (const char *filename, const char + *target, void *(*open_func) (struct bfd *nbfd, void + *open_closure), void *open_closure, file_ptr (*pread_func) + (struct bfd *nbfd, void *stream, void *buf, file_ptr nbytes, + file_ptr offset), int (*close_func) (struct bfd *nbfd, void + *stream), int (*stat_func) (struct bfd *abfd, void *stream, + struct stat *sb)); + Create and return a BFD backed by a read-only STREAM. The STREAM + is created using OPEN_FUNC, accessed using PREAD_FUNC and destroyed + using CLOSE_FUNC. + + Calls 'bfd_find_target', so TARGET is interpreted as by that + function. + + Calls OPEN_FUNC (which can call 'bfd_zalloc' and + 'bfd_get_filename') to obtain the read-only stream backing the BFD. + OPEN_FUNC either succeeds returning the non-'NULL' STREAM, or fails + returning 'NULL' (setting 'bfd_error'). + + Calls PREAD_FUNC to request NBYTES of data from STREAM starting at + OFFSET (e.g., via a call to 'bfd_read'). PREAD_FUNC either + succeeds returning the number of bytes read (which can be less than + NBYTES when end-of-file), or fails returning -1 (setting + 'bfd_error'). + + Calls CLOSE_FUNC when the BFD is later closed using 'bfd_close'. + CLOSE_FUNC either succeeds returning 0, or fails returning -1 + (setting 'bfd_error'). + + Calls STAT_FUNC to fill in a stat structure for bfd_stat, + bfd_get_size, and bfd_get_mtime calls. STAT_FUNC returns 0 on + success, or returns -1 on failure (setting 'bfd_error'). + + If 'bfd_openr_iovec' returns 'NULL' then an error has occurred. + Possible errors are 'bfd_error_no_memory', + 'bfd_error_invalid_target' and 'bfd_error_system_call'. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.10 'bfd_openw' +..................... + + -- Function: bfd *bfd_openw (const char *filename, const char *target); + Create a BFD, associated with file FILENAME, using the file format + TARGET, and return a pointer to it. + + Possible errors are 'bfd_error_system_call', 'bfd_error_no_memory', + 'bfd_error_invalid_target'. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.11 'bfd_elf_bfd_from_remote_memory' +.......................................... + + -- Function: bfd *bfd_elf_bfd_from_remote_memory (bfd *templ, bfd_vma + ehdr_vma, bfd_size_type size, bfd_vma *loadbasep, int + (*target_read_memory) (bfd_vma vma, bfd_byte *myaddr, + bfd_size_type len)); + Create a new BFD as if by bfd_openr. Rather than opening a file, + reconstruct an ELF file by reading the segments out of remote + memory based on the ELF file header at EHDR_VMA and the ELF program + headers it points to. If non-zero, SIZE is the known extent of the + object. If not null, *LOADBASEP is filled in with the difference + between the VMAs from which the segments were read, and the VMAs + the file headers (and hence BFD's idea of each section's VMA) put + them at. + + The function TARGET_READ_MEMORY is called to copy LEN bytes from + the remote memory at target address VMA into the local buffer at + MYADDR; it should return zero on success or an errno code on + failure. TEMPL must be a BFD for an ELF target with the word size + and byte order found in the remote memory. + +2.14.1.12 'bfd_close' +..................... + + -- Function: bool bfd_close (bfd *abfd); + Close a BFD. If the BFD was open for writing, then pending + operations are completed and the file written out and closed. If + the created file is executable, then 'chmod' is called to mark it + as such. + + All memory attached to the BFD is released. + + The file descriptor associated with the BFD is closed (even if it + was passed in to BFD by 'bfd_fdopenr'). + + 'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.13 'bfd_close_all_done' +.............................. + + -- Function: bool bfd_close_all_done (bfd *); + Close a BFD. Differs from 'bfd_close' since it does not complete + any pending operations. This routine would be used if the + application had just used BFD for swapping and didn't want to use + any of the writing code. + + If the created file is executable, then 'chmod' is called to mark + it as such. + + All memory attached to the BFD is released. + + 'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.14 'bfd_create' +...................... + + -- Function: bfd *bfd_create (const char *filename, bfd *templ); + Create a new BFD in the manner of 'bfd_openw', but without opening + a file. The new BFD takes the target from the target used by + TEMPL. The format is always set to 'bfd_object'. + + A copy of the FILENAME argument is stored in the newly created BFD. + It can be accessed via the bfd_get_filename() macro. + +2.14.1.15 'bfd_make_writable' +............................. + + -- Function: bool bfd_make_writable (bfd *abfd); + Takes a BFD as created by 'bfd_create' and converts it into one + like as returned by 'bfd_openw'. It does this by converting the + BFD to BFD_IN_MEMORY. It's assumed that you will call + 'bfd_make_readable' on this bfd later. + + 'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.16 'bfd_make_readable' +............................. + + -- Function: bool bfd_make_readable (bfd *abfd); + Takes a BFD as created by 'bfd_create' and 'bfd_make_writable' and + converts it into one like as returned by 'bfd_openr'. It does this + by writing the contents out to the memory buffer, then reversing + the direction. + + 'TRUE' is returned if all is ok, otherwise 'FALSE'. + +2.14.1.17 'bfd_calc_gnu_debuglink_crc32' +........................................ + + -- Function: uint32_t bfd_calc_gnu_debuglink_crc32 (uint32_t crc, const + bfd_byte *buf, bfd_size_type len); + Computes a CRC value as used in the .gnu_debuglink section. + Advances the previously computed CRC value by computing and adding + in the crc32 for LEN bytes of BUF. + + Return the updated CRC32 value. + +2.14.1.18 'bfd_get_debug_link_info' +................................... + + -- Function: char *bfd_get_debug_link_info (bfd *abfd, uint32_t + *crc32_out); + Extracts the filename and CRC32 value for any separate debug + information file associated with ABFD. + + Returns the filename of the associated debug information file, or + NULL if there is no such file. If the filename was found then the + contents of CRC32_OUT are updated to hold the corresponding CRC32 + value for the file. + + The returned filename is allocated with 'malloc'; freeing it is the + responsibility of the caller. + +2.14.1.19 'bfd_get_alt_debug_link_info' +....................................... + + -- Function: char *bfd_get_alt_debug_link_info (bfd * abfd, + bfd_size_type *buildid_len, bfd_byte **buildid_out); + Fetch the filename and BuildID value for any alternate debuginfo + associated with ABFD. Return NULL if no such info found, otherwise + return filename and update BUILDID_LEN and BUILDID_OUT. The + returned filename and build_id are allocated with 'malloc'; freeing + them is the responsibility of the caller. + +2.14.1.20 'bfd_follow_gnu_debuglink' +.................................... + + -- Function: char *bfd_follow_gnu_debuglink (bfd *abfd, const char + *dir); + Takes a BFD and searches it for a .gnu_debuglink section. If this + section is found, it examines the section for the name and checksum + of a '.debug' file containing auxiliary debugging information. It + then searches the filesystem for this .debug file in some standard + locations, including the directory tree rooted at DIR, and if found + returns the full filename. + + If DIR is NULL, the search will take place starting at the current + directory. + + Returns 'NULL' on any errors or failure to locate the .debug file, + otherwise a pointer to a heap-allocated string containing the + filename. The caller is responsible for freeing this string. + +2.14.1.21 'bfd_follow_gnu_debugaltlink' +....................................... + + -- Function: char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char + *dir); + Takes a BFD and searches it for a .gnu_debugaltlink section. If + this section is found, it examines the section for the name of a + file containing auxiliary debugging information. It then searches + the filesystem for this file in a set of standard locations, + including the directory tree rooted at DIR, and if found returns + the full filename. + + If DIR is NULL, the search will take place starting at the current + directory. + + Returns 'NULL' on any errors or failure to locate the debug file, + otherwise a pointer to a heap-allocated string containing the + filename. The caller is responsible for freeing this string. + +2.14.1.22 'bfd_create_gnu_debuglink_section' +............................................ + + -- Function: struct bfd_section *bfd_create_gnu_debuglink_section (bfd + *abfd, const char *filename); + Takes a BFD and adds a .gnu_debuglink section to it. The section + is sized to be big enough to contain a link to the specified + FILENAME. + + A pointer to the new section is returned if all is ok. Otherwise + 'NULL' is returned and bfd_error is set. + +2.14.1.23 'bfd_fill_in_gnu_debuglink_section' +............................................. + + -- Function: bool bfd_fill_in_gnu_debuglink_section (bfd *abfd, struct + bfd_section *sect, const char *filename); + Takes a BFD and containing a .gnu_debuglink section SECT and fills + in the contents of the section to contain a link to the specified + FILENAME. The filename should be absolute or relative to the + current directory. + + 'TRUE' is returned if all is ok. Otherwise 'FALSE' is returned and + bfd_error is set. + +2.14.1.24 'bfd_follow_build_id_debuglink' +......................................... + + -- Function: char *bfd_follow_build_id_debuglink (bfd *abfd, const char + *dir); + Takes ABFD and searches it for a .note.gnu.build-id section. If + this section is found, it extracts the value of the NT_GNU_BUILD_ID + note, which should be a hexadecimal value NNNN+NN (for 32+ hex + digits). It then searches the filesystem for a file named + .BUILD-ID/NN/NN+NN.DEBUG in a set of standard locations, including + the directory tree rooted at DIR. The filename of the first + matching file to be found is returned. A matching file should + contain a .note.gnu.build-id section with the same NNNN+NN note as + ABFD, although this check is currently not implemented. + + If DIR is NULL, the search will take place starting at the current + directory. + + Returns 'NULL' on any errors or failure to locate the debug file, + otherwise a pointer to a heap-allocated string containing the + filename. The caller is responsible for freeing this string. + +2.14.1.25 'bfd_set_filename' +............................ + + -- Function: const char *bfd_set_filename (bfd *abfd, const char + *filename); + Set the filename of ABFD, copying the FILENAME parameter to + bfd_alloc'd memory owned by ABFD. Returns a pointer the newly + allocated name, or NULL if the allocation failed. + + +File: bfd.info, Node: Internal, Next: File Caching, Prev: Opening and Closing, Up: BFD front end + +2.15 Implementation details +=========================== + +2.15.1 Internal functions +------------------------- + +These routines are used within BFD. They are not intended for export, +but are documented here for completeness. + +2.15.1.1 'bfd_malloc' +..................... + + -- Function: void *bfd_malloc (bfd_size_type *size*); + Returns a pointer to an allocated block of memory that is at least + SIZE bytes long. If SIZE is 0 then it will be treated as if it + were 1. If SIZE is too big then NULL will be returned. Returns + NULL upon error and sets bfd_error. + +2.15.1.2 'bfd_realloc' +...................... + + -- Function: void *bfd_realloc (void **mem*, bfd_size_type *size*); + Returns a pointer to an allocated block of memory that is at least + SIZE bytes long. If SIZE is 0 then it will be treated as if it + were 1. If SIZE is too big then NULL will be returned. If MEM is + not NULL then it must point to an allocated block of memory. If + this block is large enough then MEM may be used as the return value + for this function, but this is not guaranteed. + + If MEM is not returned then the first N bytes in the returned block + will be identical to the first N bytes in region pointed to by MEM, + where N is the lessor of SIZE and the length of the region of + memory currently addressed by MEM. + + Returns NULL upon error and sets bfd_error. + +2.15.1.3 'bfd_realloc_or_free' +.............................. + + -- Function: void *bfd_realloc_or_free (void **mem*, bfd_size_type + *size*); + Returns a pointer to an allocated block of memory that is at least + SIZE bytes long. If SIZE is 0 then no memory will be allocated, + MEM will be freed, and NULL will be returned. This will not cause + bfd_error to be set. + + If SIZE is too big then NULL will be returned and bfd_error will be + set. If MEM is not NULL then it must point to an allocated block + of memory. If this block is large enough then MEM may be used as + the return value for this function, but this is not guaranteed. + + If MEM is not returned then the first N bytes in the returned block + will be identical to the first N bytes in region pointed to by MEM, + where N is the lessor of SIZE and the length of the region of + memory currently addressed by MEM. + +2.15.1.4 'bfd_zmalloc' +...................... + + -- Function: void *bfd_zmalloc (bfd_size_type *size*); + Returns a pointer to an allocated block of memory that is at least + SIZE bytes long. If SIZE is 0 then it will be treated as if it + were 1. If SIZE is too big then NULL will be returned. Returns + NULL upon error and sets bfd_error. + + If NULL is not returned then the allocated block of memory will + have been cleared. + +2.15.1.5 'bfd_alloc' +.................... + + -- Function: void *bfd_alloc (bfd *abfd, bfd_size_type wanted); + Allocate a block of WANTED bytes of memory attached to 'abfd' and + return a pointer to it. + +2.15.1.6 'bfd_zalloc' +..................... + + -- Function: void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); + Allocate a block of WANTED bytes of zeroed memory attached to + 'abfd' and return a pointer to it. + +2.15.1.7 'bfd_release' +...................... + + -- Function: void bfd_release (bfd *, void *); + Free a block allocated for a BFD. Note: Also frees all more + recently allocated blocks! + +2.15.1.8 'bfd_write_bigendian_4byte_int' +........................................ + + -- Function: bool bfd_write_bigendian_4byte_int (bfd *, unsigned int); + Write a 4 byte integer I to the output BFD ABFD, in big endian + order regardless of what else is going on. This is useful in + archives. + +2.15.1.9 'bfd_put_size' +....................... + +2.15.1.10 'bfd_get_size' +........................ + +These macros as used for reading and writing raw data in sections; each +access (except for bytes) is vectored through the target format of the +BFD and mangled accordingly. The mangling performs any necessary endian +translations and removes alignment restrictions. Note that types +accepted and returned by these macros are identical so they can be +swapped around in macros--for example, 'libaout.h' defines 'GET_WORD' to +either 'bfd_get_32' or 'bfd_get_64'. + + In the put routines, VAL must be a 'bfd_vma'. If we are on a system +without prototypes, the caller is responsible for making sure that is +true, with a cast if necessary. We don't cast them in the macro +definitions because that would prevent 'lint' or 'gcc -Wall' from +detecting sins such as passing a pointer. To detect calling these with +less than a 'bfd_vma', use 'gcc -Wconversion' on a host with 64 bit +'bfd_vma''s. + + /* Byte swapping macros for user section data. */ + + #define bfd_put_8(abfd, val, ptr) \ + ((void) (*((bfd_byte *) (ptr)) = (val) & 0xff)) + #define bfd_put_signed_8 \ + bfd_put_8 + #define bfd_get_8(abfd, ptr) \ + ((bfd_vma) *(const bfd_byte *) (ptr) & 0xff) + #define bfd_get_signed_8(abfd, ptr) \ + ((((bfd_signed_vma) *(const bfd_byte *) (ptr) & 0xff) ^ 0x80) - 0x80) + + #define bfd_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) + #define bfd_put_signed_16 \ + bfd_put_16 + #define bfd_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx16, (ptr)) + #define bfd_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) + + #define bfd_put_24(abfd, val, ptr) \ + do \ + if (bfd_big_endian (abfd)) \ + bfd_putb24 ((val), (ptr)); \ + else \ + bfd_putl24 ((val), (ptr)); \ + while (0) + + bfd_vma bfd_getb24 (const void *p); + bfd_vma bfd_getl24 (const void *p); + + #define bfd_get_24(abfd, ptr) \ + (bfd_big_endian (abfd) ? bfd_getb24 (ptr) : bfd_getl24 (ptr)) + + #define bfd_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) + #define bfd_put_signed_32 \ + bfd_put_32 + #define bfd_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx32, (ptr)) + #define bfd_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) + + #define bfd_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) + #define bfd_put_signed_64 \ + bfd_put_64 + #define bfd_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx64, (ptr)) + #define bfd_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) + + #define bfd_get(bits, abfd, ptr) \ + ((bits) == 8 ? bfd_get_8 (abfd, ptr) \ + : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ + : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ + : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ + : (abort (), (bfd_vma) - 1)) + + #define bfd_put(bits, abfd, val, ptr) \ + ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ + : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ + : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ + : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ + : (abort (), (void) 0)) + + +2.15.1.11 'bfd_h_put_size' +.......................... + +These macros have the same function as their 'bfd_get_x' brethren, +except that they are used for removing information for the header +records of object files. Believe it or not, some object files keep +their header records in big endian order and their data in little endian +order. + + /* Byte swapping macros for file header data. */ + + #define bfd_h_put_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) + #define bfd_h_put_signed_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) + #define bfd_h_get_8(abfd, ptr) \ + bfd_get_8 (abfd, ptr) + #define bfd_h_get_signed_8(abfd, ptr) \ + bfd_get_signed_8 (abfd, ptr) + + #define bfd_h_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) + #define bfd_h_put_signed_16 \ + bfd_h_put_16 + #define bfd_h_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx16, (ptr)) + #define bfd_h_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) + + #define bfd_h_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) + #define bfd_h_put_signed_32 \ + bfd_h_put_32 + #define bfd_h_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx32, (ptr)) + #define bfd_h_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) + + #define bfd_h_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) + #define bfd_h_put_signed_64 \ + bfd_h_put_64 + #define bfd_h_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx64, (ptr)) + #define bfd_h_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) + + /* Aliases for the above, which should eventually go away. */ + + #define H_PUT_64 bfd_h_put_64 + #define H_PUT_32 bfd_h_put_32 + #define H_PUT_16 bfd_h_put_16 + #define H_PUT_8 bfd_h_put_8 + #define H_PUT_S64 bfd_h_put_signed_64 + #define H_PUT_S32 bfd_h_put_signed_32 + #define H_PUT_S16 bfd_h_put_signed_16 + #define H_PUT_S8 bfd_h_put_signed_8 + #define H_GET_64 bfd_h_get_64 + #define H_GET_32 bfd_h_get_32 + #define H_GET_16 bfd_h_get_16 + #define H_GET_8 bfd_h_get_8 + #define H_GET_S64 bfd_h_get_signed_64 + #define H_GET_S32 bfd_h_get_signed_32 + #define H_GET_S16 bfd_h_get_signed_16 + #define H_GET_S8 bfd_h_get_signed_8 + + + +2.15.1.12 'Byte swapping routines.' +................................... + + -- Function: uint64_t bfd_getb64 (const void *); uint64_t bfd_getl64 + (const void *); int64_t bfd_getb_signed_64 (const void *); + int64_t bfd_getl_signed_64 (const void *); bfd_vma bfd_getb32 + (const void *); bfd_vma bfd_getl32 (const void *); + bfd_signed_vma bfd_getb_signed_32 (const void *); + bfd_signed_vma bfd_getl_signed_32 (const void *); bfd_vma + bfd_getb16 (const void *); bfd_vma bfd_getl16 (const void *); + bfd_signed_vma bfd_getb_signed_16 (const void *); + bfd_signed_vma bfd_getl_signed_16 (const void *); void + bfd_putb64 (uint64_t, void *); void bfd_putl64 (uint64_t, void + *); void bfd_putb32 (bfd_vma, void *); void bfd_putl32 + (bfd_vma, void *); void bfd_putb24 (bfd_vma, void *); void + bfd_putl24 (bfd_vma, void *); void bfd_putb16 (bfd_vma, void + *); void bfd_putl16 (bfd_vma, void *); uint64_t bfd_get_bits + (const void *, int, bool); void bfd_put_bits (uint64_t, void + *, int, bool); + Read and write integers in a particular endian order. getb and + putb functions handle big-endian, getl and putl handle + little-endian. bfd_get_bits and bfd_put_bits specify big-endian by + passing TRUE in the last parameter, little-endian by passing FALSE. + +2.15.1.13 'bfd_log2' +.................... + + -- Function: unsigned int bfd_log2 (bfd_vma x); + Return the log base 2 of the value supplied, rounded up. E.g., an + X of 1025 returns 11. A X of 0 returns 0. + + +File: bfd.info, Node: File Caching, Next: Linker Functions, Prev: Internal, Up: BFD front end + +2.16 File caching +================= + +The file caching mechanism is embedded within BFD and allows the +application to open as many BFDs as it wants without regard to the +underlying operating system's file descriptor limit (often as low as 20 +open files). The module in 'cache.c' maintains a least recently used +list of 'bfd_cache_max_open' files, and exports the name +'bfd_cache_lookup', which runs around and makes sure that the required +BFD is open. If not, then it chooses a file to close, closes it and +opens the one wanted, returning its file handle. + +2.16.1 Caching functions +------------------------ + +2.16.1.1 'bfd_cache_init' +......................... + + -- Function: bool bfd_cache_init (bfd *abfd); + Add a newly opened BFD to the cache. + +2.16.1.2 'bfd_cache_close' +.......................... + + -- Function: bool bfd_cache_close (bfd *abfd); + Remove the BFD ABFD from the cache. If the attached file is open, + then close it too. + + 'FALSE' is returned if closing the file fails, 'TRUE' is returned + if all is well. + +2.16.1.3 'bfd_cache_close_all' +.............................. + + -- Function: bool bfd_cache_close_all (void); + Remove all BFDs from the cache. If the attached file is open, then + close it too. Note - despite its name this function will close a + BFD even if it is not marked as being cacheable, ie even if + bfd_get_cacheable() returns false. + + 'FALSE' is returned if closing one of the file fails, 'TRUE' is + returned if all is well. + +2.16.1.4 'bfd_cache_set_uncloseable' +.................................... + + -- Function: bool bfd_cache_set_uncloseable (bfd *abfd, bool value, + bool *old); + Internal function to mark ABFD as either closeable or not. This is + used by bfd_check_format_matches to avoid races where + bfd_cache_close_all is called in another thread. VALUE is true to + mark the BFD as temporarily uncloseable by the cache; false to mark + it as closeable once again. OLD, if non-NULL, is set to the + previous value of the flag. Returns false on error, true on + success. + +2.16.1.5 'bfd_cache_size' +......................... + + -- Function: unsigned bfd_cache_size (void); + Return the number of open files in the cache. + +2.16.1.6 'bfd_open_file' +........................ + + -- Function: FILE* bfd_open_file (bfd *abfd); + Call the OS to open a file for ABFD. Return the 'FILE *' (possibly + 'NULL') that results from this operation. Set up the BFD so that + future accesses know the file is open. If the 'FILE *' returned is + 'NULL', then it won't have been put in the cache, so it won't have + to be removed from it. + + +File: bfd.info, Node: Linker Functions, Next: Hash Tables, Prev: File Caching, Up: BFD front end + +2.17 Linker Functions +===================== + +The linker uses three special entry points in the BFD target vector. It +is not necessary to write special routines for these entry points when +creating a new BFD back end, since generic versions are provided. +However, writing them can speed up linking and make it use significantly +less runtime memory. + + The first routine creates a hash table used by the other routines. +The second routine adds the symbols from an object file to the hash +table. The third routine takes all the object files and links them +together to create the output file. These routines are designed so that +the linker proper does not need to know anything about the symbols in +the object files that it is linking. The linker merely arranges the +sections as directed by the linker script and lets BFD handle the +details of symbols and relocs. + + The second routine and third routines are passed a pointer to a +'struct bfd_link_info' structure (defined in 'bfdlink.h') which holds +information relevant to the link, including the linker hash table (which +was created by the first routine) and a set of callback functions to the +linker proper. + + The generic linker routines are in 'linker.c', and use the header +file 'genlink.h'. As of this writing, the only back ends which have +implemented versions of these routines are a.out (in 'aoutx.h') and +ECOFF (in 'ecoff.c'). The a.out routines are used as examples +throughout this section. + +* Menu: + +* Creating a Linker Hash Table:: +* Adding Symbols to the Hash Table:: +* Performing the Final Link:: + + +File: bfd.info, Node: Creating a Linker Hash Table, Next: Adding Symbols to the Hash Table, Prev: Linker Functions, Up: Linker Functions + +2.17.1 Creating a linker hash table +----------------------------------- + +The linker routines must create a hash table, which must be derived from +'struct bfd_link_hash_table' described in 'bfdlink.c'. *Note Hash +Tables::, for information on how to create a derived hash table. This +entry point is called using the target vector of the linker output file. + + The '_bfd_link_hash_table_create' entry point must allocate and +initialize an instance of the desired hash table. If the back end does +not require any additional information to be stored with the entries in +the hash table, the entry point may simply create a 'struct +bfd_link_hash_table'. Most likely, however, some additional information +will be needed. + + For example, with each entry in the hash table the a.out linker keeps +the index the symbol has in the final output file (this index number is +used so that when doing a relocatable link the symbol index used in the +output file can be quickly filled in when copying over a reloc). The +a.out linker code defines the required structures and functions for a +hash table derived from 'struct bfd_link_hash_table'. The a.out linker +hash table is created by the function +'NAME(aout,link_hash_table_create)'; it simply allocates space for the +hash table, initializes it, and returns a pointer to it. + + When writing the linker routines for a new back end, you will +generally not know exactly which fields will be required until you have +finished. You should simply create a new hash table which defines no +additional fields, and then simply add fields as they become necessary. + + +File: bfd.info, Node: Adding Symbols to the Hash Table, Next: Performing the Final Link, Prev: Creating a Linker Hash Table, Up: Linker Functions + +2.17.2 Adding symbols to the hash table +--------------------------------------- + +The linker proper will call the '_bfd_link_add_symbols' entry point for +each object file or archive which is to be linked (typically these are +the files named on the command line, but some may also come from the +linker script). The entry point is responsible for examining the file. +For an object file, BFD must add any relevant symbol information to the +hash table. For an archive, BFD must determine which elements of the +archive should be used and adding them to the link. + + The a.out version of this entry point is +'NAME(aout,link_add_symbols)'. + +* Menu: + +* Differing file formats:: +* Adding symbols from an object file:: +* Adding symbols from an archive:: + + +File: bfd.info, Node: Differing file formats, Next: Adding symbols from an object file, Prev: Adding Symbols to the Hash Table, Up: Adding Symbols to the Hash Table + +2.17.2.1 Differing file formats +............................... + +Normally all the files involved in a link will be of the same format, +but it is also possible to link together different format object files, +and the back end must support that. The '_bfd_link_add_symbols' entry +point is called via the target vector of the file to be added. This has +an important consequence: the function may not assume that the hash +table is the type created by the corresponding +'_bfd_link_hash_table_create' vector. All the '_bfd_link_add_symbols' +function can assume about the hash table is that it is derived from +'struct bfd_link_hash_table'. + + Sometimes the '_bfd_link_add_symbols' function must store some +information in the hash table entry to be used by the '_bfd_final_link' +function. In such a case the output bfd xvec must be checked to make +sure that the hash table was created by an object file of the same +format. + + The '_bfd_final_link' routine must be prepared to handle a hash entry +without any extra information added by the '_bfd_link_add_symbols' +function. A hash entry without extra information will also occur when +the linker script directs the linker to create a symbol. Note that, +regardless of how a hash table entry is added, all the fields will be +initialized to some sort of null value by the hash table entry +initialization function. + + See 'ecoff_link_add_externals' for an example of how to check the +output bfd before saving information (in this case, the ECOFF external +symbol debugging information) in a hash table entry. + + +File: bfd.info, Node: Adding symbols from an object file, Next: Adding symbols from an archive, Prev: Differing file formats, Up: Adding Symbols to the Hash Table + +2.17.2.2 Adding symbols from an object file +........................................... + +When the '_bfd_link_add_symbols' routine is passed an object file, it +must add all externally visible symbols in that object file to the hash +table. The actual work of adding the symbol to the hash table is +normally handled by the function '_bfd_generic_link_add_one_symbol'. +The '_bfd_link_add_symbols' routine is responsible for reading all the +symbols from the object file and passing the correct information to +'_bfd_generic_link_add_one_symbol'. + + The '_bfd_link_add_symbols' routine should not use +'bfd_canonicalize_symtab' to read the symbols. The point of providing +this routine is to avoid the overhead of converting the symbols into +generic 'asymbol' structures. + + '_bfd_generic_link_add_one_symbol' handles the details of combining +common symbols, warning about multiple definitions, and so forth. It +takes arguments which describe the symbol to add, notably symbol flags, +a section, and an offset. The symbol flags include such things as +'BSF_WEAK' or 'BSF_INDIRECT'. The section is a section in the object +file, or something like 'bfd_und_section_ptr' for an undefined symbol or +'bfd_com_section_ptr' for a common symbol. + + If the '_bfd_final_link' routine is also going to need to read the +symbol information, the '_bfd_link_add_symbols' routine should save it +somewhere attached to the object file BFD. However, the information +should only be saved if the 'keep_memory' field of the 'info' argument +is TRUE, so that the '-no-keep-memory' linker switch is effective. + + The a.out function which adds symbols from an object file is +'aout_link_add_object_symbols', and most of the interesting work is in +'aout_link_add_symbols'. The latter saves pointers to the hash tables +entries created by '_bfd_generic_link_add_one_symbol' indexed by symbol +number, so that the '_bfd_final_link' routine does not have to call the +hash table lookup routine to locate the entry. + + +File: bfd.info, Node: Adding symbols from an archive, Prev: Adding symbols from an object file, Up: Adding Symbols to the Hash Table + +2.17.2.3 Adding symbols from an archive +....................................... + +When the '_bfd_link_add_symbols' routine is passed an archive, it must +look through the symbols defined by the archive and decide which +elements of the archive should be included in the link. For each such +element it must call the 'add_archive_element' linker callback, and it +must add the symbols from the object file to the linker hash table. +(The callback may in fact indicate that a replacement BFD should be +used, in which case the symbols from that BFD should be added to the +linker hash table instead.) + + In most cases the work of looking through the symbols in the archive +should be done by the '_bfd_generic_link_add_archive_symbols' function. +'_bfd_generic_link_add_archive_symbols' is passed a function to call to +make the final decision about adding an archive element to the link and +to do the actual work of adding the symbols to the linker hash table. +If the element is to be included, the 'add_archive_element' linker +callback routine must be called with the element as an argument, and the +element's symbols must be added to the linker hash table just as though +the element had itself been passed to the '_bfd_link_add_symbols' +function. + + When the a.out '_bfd_link_add_symbols' function receives an archive, +it calls '_bfd_generic_link_add_archive_symbols' passing +'aout_link_check_archive_element' as the function argument. +'aout_link_check_archive_element' calls 'aout_link_check_ar_symbols'. +If the latter decides to add the element (an element is only added if it +provides a real, non-common, definition for a previously undefined or +common symbol) it calls the 'add_archive_element' callback and then +'aout_link_check_archive_element' calls 'aout_link_add_symbols' to +actually add the symbols to the linker hash table - possibly those of a +substitute BFD, if the 'add_archive_element' callback avails itself of +that option. + + The ECOFF back end is unusual in that it does not normally call +'_bfd_generic_link_add_archive_symbols', because ECOFF archives already +contain a hash table of symbols. The ECOFF back end searches the +archive itself to avoid the overhead of creating a new hash table. + + +File: bfd.info, Node: Performing the Final Link, Prev: Adding Symbols to the Hash Table, Up: Linker Functions + +2.17.3 Performing the final link +-------------------------------- + +When all the input files have been processed, the linker calls the +'_bfd_final_link' entry point of the output BFD. This routine is +responsible for producing the final output file, which has several +aspects. It must relocate the contents of the input sections and copy +the data into the output sections. It must build an output symbol table +including any local symbols from the input files and the global symbols +from the hash table. When producing relocatable output, it must modify +the input relocs and write them into the output file. There may also be +object format dependent work to be done. + + The linker will also call the 'write_object_contents' entry point +when the BFD is closed. The two entry points must work together in +order to produce the correct output file. + + The details of how this works are inevitably dependent upon the +specific object file format. The a.out '_bfd_final_link' routine is +'NAME(aout,final_link)'. + +* Menu: + +* Information provided by the linker:: +* Relocating the section contents:: +* Writing the symbol table:: + + +File: bfd.info, Node: Information provided by the linker, Next: Relocating the section contents, Prev: Performing the Final Link, Up: Performing the Final Link + +2.17.3.1 Information provided by the linker +........................................... + +Before the linker calls the '_bfd_final_link' entry point, it sets up +some data structures for the function to use. + + The 'input_bfds' field of the 'bfd_link_info' structure will point to +a list of all the input files included in the link. These files are +linked through the 'link.next' field of the 'bfd' structure. + + Each section in the output file will have a list of 'link_order' +structures attached to the 'map_head.link_order' field (the 'link_order' +structure is defined in 'bfdlink.h'). These structures describe how to +create the contents of the output section in terms of the contents of +various input sections, fill constants, and, eventually, other types of +information. They also describe relocs that must be created by the BFD +backend, but do not correspond to any input file; this is used to +support -Ur, which builds constructors while generating a relocatable +object file. + + +File: bfd.info, Node: Relocating the section contents, Next: Writing the symbol table, Prev: Information provided by the linker, Up: Performing the Final Link + +2.17.3.2 Relocating the section contents +........................................ + +The '_bfd_final_link' function should look through the 'link_order' +structures attached to each section of the output file. Each +'link_order' structure should either be handled specially, or it should +be passed to the function '_bfd_default_link_order' which will do the +right thing ('_bfd_default_link_order' is defined in 'linker.c'). + + For efficiency, a 'link_order' of type 'bfd_indirect_link_order' +whose associated section belongs to a BFD of the same format as the +output BFD must be handled specially. This type of 'link_order' +describes part of an output section in terms of a section belonging to +one of the input files. The '_bfd_final_link' function should read the +contents of the section and any associated relocs, apply the relocs to +the section contents, and write out the modified section contents. If +performing a relocatable link, the relocs themselves must also be +modified and written out. + + The functions '_bfd_relocate_contents' and '_bfd_final_link_relocate' +provide some general support for performing the actual relocations, +notably overflow checking. Their arguments include information about +the symbol the relocation is against and a 'reloc_howto_type' argument +which describes the relocation to perform. These functions are defined +in 'reloc.c'. + + The a.out function which handles reading, relocating, and writing +section contents is 'aout_link_input_section'. The actual relocation is +done in 'aout_link_input_section_std' and 'aout_link_input_section_ext'. + + +File: bfd.info, Node: Writing the symbol table, Prev: Relocating the section contents, Up: Performing the Final Link + +2.17.3.3 Writing the symbol table +................................. + +The '_bfd_final_link' function must gather all the symbols in the input +files and write them out. It must also write out all the symbols in the +global hash table. This must be controlled by the 'strip' and 'discard' +fields of the 'bfd_link_info' structure. + + The local symbols of the input files will not have been entered into +the linker hash table. The '_bfd_final_link' routine must consider each +input file and include the symbols in the output file. It may be +convenient to do this when looking through the 'link_order' structures, +or it may be done by stepping through the 'input_bfds' list. + + The '_bfd_final_link' routine must also traverse the global hash +table to gather all the externally visible symbols. It is possible that +most of the externally visible symbols may be written out when +considering the symbols of each input file, but it is still necessary to +traverse the hash table since the linker script may have defined some +symbols that are not in any of the input files. + + The 'strip' field of the 'bfd_link_info' structure controls which +symbols are written out. The possible values are listed in 'bfdlink.h'. +If the value is 'strip_some', then the 'keep_hash' field of the +'bfd_link_info' structure is a hash table of symbols to keep; each +symbol should be looked up in this hash table, and only symbols which +are present should be included in the output file. + + If the 'strip' field of the 'bfd_link_info' structure permits local +symbols to be written out, the 'discard' field is used to further +controls which local symbols are included in the output file. If the +value is 'discard_l', then all local symbols which begin with a certain +prefix are discarded; this is controlled by the +'bfd_is_local_label_name' entry point. + + The a.out backend handles symbols by calling +'aout_link_write_symbols' on each input BFD and then traversing the +global hash table with the function 'aout_link_write_other_symbol'. It +builds a string table while writing out the symbols, which is written to +the output file at the end of 'NAME(aout,final_link)'. + +2.17.3.4 'bfd_link_split_section' +................................. + + -- Function: bool bfd_link_split_section (bfd *abfd, asection *sec); + Return nonzero if SEC should be split during a reloceatable or + final link. + #define bfd_link_split_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) + + +2.17.3.5 'bfd_section_already_linked' +..................................... + + -- Function: bool bfd_section_already_linked (bfd *abfd, asection *sec, + struct bfd_link_info *info); + Check if DATA has been already linked during a reloceatable or + final link. Return TRUE if it has. + #define bfd_section_already_linked(abfd, sec, info) \ + BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) + + +2.17.3.6 'bfd_generic_define_common_symbol' +........................................... + + -- Function: bool bfd_generic_define_common_symbol (bfd *output_bfd, + struct bfd_link_info *info, struct bfd_link_hash_entry *h); + Convert common symbol H into a defined symbol. Return TRUE on + success and FALSE on failure. + #define bfd_define_common_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) + + +2.17.3.7 '_bfd_generic_link_hide_symbol' +........................................ + + -- Function: void _bfd_generic_link_hide_symbol (bfd *output_bfd, + struct bfd_link_info *info, struct bfd_link_hash_entry *h); + Hide symbol H. This is an internal function. It should not be + called from outside the BFD library. + #define bfd_link_hide_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_link_hide_symbol, (output_bfd, info, h)) + + +2.17.3.8 'bfd_generic_define_start_stop' +........................................ + + -- Function: struct bfd_link_hash_entry *bfd_generic_define_start_stop + (struct bfd_link_info *info, const char *symbol, asection + *sec); + Define a __start, __stop, .startof. or .sizeof. symbol. Return + the symbol or NULL if no such undefined symbol exists. + #define bfd_define_start_stop(output_bfd, info, symbol, sec) \ + BFD_SEND (output_bfd, _bfd_define_start_stop, (info, symbol, sec)) + + +2.17.3.9 'bfd_find_version_for_sym' +................................... + + -- Function: struct bfd_elf_version_tree * bfd_find_version_for_sym + (struct bfd_elf_version_tree *verdefs, const char *sym_name, + bool *hide); + Search an elf version script tree for symbol versioning info and + export / don't-export status for a given symbol. Return non-NULL + on success and NULL on failure; also sets the output 'hide' boolean + parameter. + +2.17.3.10 'bfd_hide_sym_by_version' +................................... + + -- Function: bool bfd_hide_sym_by_version (struct bfd_elf_version_tree + *verdefs, const char *sym_name); + Search an elf version script tree for symbol versioning info for a + given symbol. Return TRUE if the symbol is hidden. + +2.17.3.11 'bfd_link_check_relocs' +................................. + + -- Function: bool bfd_link_check_relocs (bfd *abfd, struct + bfd_link_info *info); + Checks the relocs in ABFD for validity. Does not execute the + relocs. Return TRUE if everything is OK, FALSE otherwise. This is + the external entry point to this code. + +2.17.3.12 '_bfd_generic_link_check_relocs' +.......................................... + + -- Function: bool _bfd_generic_link_check_relocs (bfd *abfd, struct + bfd_link_info *info); + Stub function for targets that do not implement reloc checking. + Return TRUE. This is an internal function. It should not be called + from outside the BFD library. + +2.17.3.13 'bfd_merge_private_bfd_data' +...................................... + + -- Function: bool bfd_merge_private_bfd_data (bfd *ibfd, struct + bfd_link_info *info); + Merge private BFD information from the BFD IBFD to the the output + file BFD when linking. Return 'TRUE' on success, 'FALSE' on error. + Possible error returns are: + + * 'bfd_error_no_memory' - Not enough memory exists to create + private data for OBFD. + #define bfd_merge_private_bfd_data(ibfd, info) \ + BFD_SEND ((info)->output_bfd, _bfd_merge_private_bfd_data, \ + (ibfd, info)) + + +2.17.3.14 '_bfd_generic_verify_endian_match' +............................................ + + -- Function: bool _bfd_generic_verify_endian_match (bfd *ibfd, struct + bfd_link_info *info); + Can be used from / for bfd_merge_private_bfd_data to check that + endianness matches between input and output file. Returns TRUE for + a match, otherwise returns FALSE and emits an error. + + +File: bfd.info, Node: Hash Tables, Prev: Linker Functions, Up: BFD front end + +2.18 Hash Tables +================ + +BFD provides a simple set of hash table functions. Routines are +provided to initialize a hash table, to free a hash table, to look up a +string in a hash table and optionally create an entry for it, and to +traverse a hash table. There is currently no routine to delete an +string from a hash table. + + The basic hash table does not permit any data to be stored with a +string. However, a hash table is designed to present a base class from +which other types of hash tables may be derived. These derived types +may store additional information with the string. Hash tables were +implemented in this way, rather than simply providing a data pointer in +a hash table entry, because they were designed for use by the linker +back ends. The linker may create thousands of hash table entries, and +the overhead of allocating private data and storing and following +pointers becomes noticeable. + + The basic hash table code is in 'hash.c'. + +* Menu: + +* Creating and Freeing a Hash Table:: +* Looking Up or Entering a String:: +* Traversing a Hash Table:: +* Deriving a New Hash Table Type:: + + +File: bfd.info, Node: Creating and Freeing a Hash Table, Next: Looking Up or Entering a String, Prev: Hash Tables, Up: Hash Tables + +2.18.1 Creating and freeing a hash table +---------------------------------------- + +To create a hash table, create an instance of a 'struct bfd_hash_table' +(defined in 'bfd.h') and call 'bfd_hash_table_init' (if you know +approximately how many entries you will need, the function +'bfd_hash_table_init_n', which takes a SIZE argument, may be used). +'bfd_hash_table_init' returns 'FALSE' if some sort of error occurs. + + The function 'bfd_hash_table_init' take as an argument a function to +use to create new entries. For a basic hash table, use the function +'bfd_hash_newfunc'. *Note Deriving a New Hash Table Type::, for why you +would want to use a different value for this argument. + + 'bfd_hash_table_init' will create an objalloc which will be used to +allocate new entries. You may allocate memory on this objalloc using +'bfd_hash_allocate'. + + Use 'bfd_hash_table_free' to free up all the memory that has been +allocated for a hash table. This will not free up the 'struct +bfd_hash_table' itself, which you must provide. + + Use 'bfd_hash_set_default_size' to set the default size of hash table +to use. + + +File: bfd.info, Node: Looking Up or Entering a String, Next: Traversing a Hash Table, Prev: Creating and Freeing a Hash Table, Up: Hash Tables + +2.18.2 Looking up or entering a string +-------------------------------------- + +The function 'bfd_hash_lookup' is used both to look up a string in the +hash table and to create a new entry. + + If the CREATE argument is 'FALSE', 'bfd_hash_lookup' will look up a +string. If the string is found, it will returns a pointer to a 'struct +bfd_hash_entry'. If the string is not found in the table +'bfd_hash_lookup' will return 'NULL'. You should not modify any of the +fields in the returns 'struct bfd_hash_entry'. + + If the CREATE argument is 'TRUE', the string will be entered into the +hash table if it is not already there. Either way a pointer to a +'struct bfd_hash_entry' will be returned, either to the existing +structure or to a newly created one. In this case, a 'NULL' return +means that an error occurred. + + If the CREATE argument is 'TRUE', and a new entry is created, the +COPY argument is used to decide whether to copy the string onto the hash +table objalloc or not. If COPY is passed as 'FALSE', you must be +careful not to deallocate or modify the string as long as the hash table +exists. + + +File: bfd.info, Node: Traversing a Hash Table, Next: Deriving a New Hash Table Type, Prev: Looking Up or Entering a String, Up: Hash Tables + +2.18.3 Traversing a hash table +------------------------------ + +The function 'bfd_hash_traverse' may be used to traverse a hash table, +calling a function on each element. The traversal is done in a random +order. + + 'bfd_hash_traverse' takes as arguments a function and a generic 'void +*' pointer. The function is called with a hash table entry (a 'struct +bfd_hash_entry *') and the generic pointer passed to +'bfd_hash_traverse'. The function must return a 'boolean' value, which +indicates whether to continue traversing the hash table. If the +function returns 'FALSE', 'bfd_hash_traverse' will stop the traversal +and return immediately. + + +File: bfd.info, Node: Deriving a New Hash Table Type, Prev: Traversing a Hash Table, Up: Hash Tables + +2.18.4 Deriving a new hash table type +------------------------------------- + +Many uses of hash tables want to store additional information which each +entry in the hash table. Some also find it convenient to store +additional information with the hash table itself. This may be done +using a derived hash table. + + Since C is not an object oriented language, creating a derived hash +table requires sticking together some boilerplate routines with a few +differences specific to the type of hash table you want to create. + + An example of a derived hash table is the linker hash table. The +structures for this are defined in 'bfdlink.h'. The functions are in +'linker.c'. + + You may also derive a hash table from an already derived hash table. +For example, the a.out linker backend code uses a hash table derived +from the linker hash table. + +* Menu: + +* Define the Derived Structures:: +* Write the Derived Creation Routine:: +* Write Other Derived Routines:: + + +File: bfd.info, Node: Define the Derived Structures, Next: Write the Derived Creation Routine, Prev: Deriving a New Hash Table Type, Up: Deriving a New Hash Table Type + +2.18.4.1 Define the derived structures +...................................... + +You must define a structure for an entry in the hash table, and a +structure for the hash table itself. + + The first field in the structure for an entry in the hash table must +be of the type used for an entry in the hash table you are deriving +from. If you are deriving from a basic hash table this is 'struct +bfd_hash_entry', which is defined in 'bfd.h'. The first field in the +structure for the hash table itself must be of the type of the hash +table you are deriving from itself. If you are deriving from a basic +hash table, this is 'struct bfd_hash_table'. + + For example, the linker hash table defines 'struct +bfd_link_hash_entry' (in 'bfdlink.h'). The first field, 'root', is of +type 'struct bfd_hash_entry'. Similarly, the first field in 'struct +bfd_link_hash_table', 'table', is of type 'struct bfd_hash_table'. + + +File: bfd.info, Node: Write the Derived Creation Routine, Next: Write Other Derived Routines, Prev: Define the Derived Structures, Up: Deriving a New Hash Table Type + +2.18.4.2 Write the derived creation routine +........................................... + +You must write a routine which will create and initialize an entry in +the hash table. This routine is passed as the function argument to +'bfd_hash_table_init'. + + In order to permit other hash tables to be derived from the hash +table you are creating, this routine must be written in a standard way. + + The first argument to the creation routine is a pointer to a hash +table entry. This may be 'NULL', in which case the routine should +allocate the right amount of space. Otherwise the space has already +been allocated by a hash table type derived from this one. + + After allocating space, the creation routine must call the creation +routine of the hash table type it is derived from, passing in a pointer +to the space it just allocated. This will initialize any fields used by +the base hash table. + + Finally the creation routine must initialize any local fields for the +new hash table type. + + Here is a boilerplate example of a creation routine. FUNCTION_NAME +is the name of the routine. ENTRY_TYPE is the type of an entry in the +hash table you are creating. BASE_NEWFUNC is the name of the creation +routine of the hash table type your hash table is derived from. + + struct bfd_hash_entry * + FUNCTION_NAME (struct bfd_hash_entry *entry, + struct bfd_hash_table *table, + const char *string) + { + struct ENTRY_TYPE *ret = (ENTRY_TYPE *) entry; + + /* Allocate the structure if it has not already been allocated by a + derived class. */ + if (ret == NULL) + { + ret = bfd_hash_allocate (table, sizeof (* ret)); + if (ret == NULL) + return NULL; + } + + /* Call the allocation method of the base class. */ + ret = ((ENTRY_TYPE *) + BASE_NEWFUNC ((struct bfd_hash_entry *) ret, table, string)); + + /* Initialize the local fields here. */ + + return (struct bfd_hash_entry *) ret; + } + The creation routine for the linker hash table, which is in +'linker.c', looks just like this example. FUNCTION_NAME is +'_bfd_link_hash_newfunc'. ENTRY_TYPE is 'struct bfd_link_hash_entry'. +BASE_NEWFUNC is 'bfd_hash_newfunc', the creation routine for a basic +hash table. + + '_bfd_link_hash_newfunc' also initializes the local fields in a +linker hash table entry: 'type', 'written' and 'next'. + + +File: bfd.info, Node: Write Other Derived Routines, Prev: Write the Derived Creation Routine, Up: Deriving a New Hash Table Type + +2.18.4.3 Write other derived routines +..................................... + +You will want to write other routines for your new hash table, as well. + + You will want an initialization routine which calls the +initialization routine of the hash table you are deriving from and +initializes any other local fields. For the linker hash table, this is +'_bfd_link_hash_table_init' in 'linker.c'. + + You will want a lookup routine which calls the lookup routine of the +hash table you are deriving from and casts the result. The linker hash +table uses 'bfd_link_hash_lookup' in 'linker.c' (this actually takes an +additional argument which it uses to decide how to return the looked up +value). + + You may want a traversal routine. This should just call the +traversal routine of the hash table you are deriving from with +appropriate casts. The linker hash table uses 'bfd_link_hash_traverse' +in 'linker.c'. + + These routines may simply be defined as macros. For example, the +a.out backend linker hash table, which is derived from the linker hash +table, uses macros for the lookup and traversal routines. These are +'aout_link_hash_lookup' and 'aout_link_hash_traverse' in aoutx.h. + +2.18.4.4 'bfd_hash_table_init_n' +................................ + + -- Function: bool bfd_hash_table_init_n (struct bfd_hash_table *, + struct bfd_hash_entry *(* *newfunc*) (struct bfd_hash_entry *, + struct bfd_hash_table *, const char *), unsigned int + *entsize*, unsigned int *size*); + Create a new hash table, given a number of entries. + +2.18.4.5 'bfd_hash_table_init' +.............................. + + -- Function: bool bfd_hash_table_init (struct bfd_hash_table *, struct + bfd_hash_entry *(* *newfunc*) (struct bfd_hash_entry *, struct + bfd_hash_table *, const char *), unsigned int *entsize*); + Create a new hash table with the default number of entries. + +2.18.4.6 'bfd_hash_table_free' +.............................. + + -- Function: void bfd_hash_table_free (struct bfd_hash_table *); + Free a hash table. + +2.18.4.7 'bfd_hash_lookup' +.......................... + + -- Function: struct bfd_hash_entry *bfd_hash_lookup (struct + bfd_hash_table *, const char *, bool *create*, bool *copy*); + Look up a string in a hash table. + +2.18.4.8 'bfd_hash_insert' +.......................... + + -- Function: struct bfd_hash_entry *bfd_hash_insert (struct + bfd_hash_table *, const char *, unsigned long *hash*); + Insert an entry in a hash table. + +2.18.4.9 'bfd_hash_rename' +.......................... + + -- Function: void bfd_hash_rename (struct bfd_hash_table *, const char + *, struct bfd_hash_entry *); + Rename an entry in a hash table. + +2.18.4.10 'bfd_hash_replace' +............................ + + -- Function: void bfd_hash_replace (struct bfd_hash_table *, struct + bfd_hash_entry * *old*, struct bfd_hash_entry * *new*); + Replace an entry in a hash table. + +2.18.4.11 'bfd_hash_allocate' +............................. + + -- Function: void *bfd_hash_allocate (struct bfd_hash_table *, unsigned + int *size*); + Allocate space in a hash table. + +2.18.4.12 'bfd_hash_newfunc' +............................ + + -- Function: struct bfd_hash_entry *bfd_hash_newfunc (struct + bfd_hash_entry *, struct bfd_hash_table *, const char *); + Base method for creating a new hash table entry. + +2.18.4.13 'bfd_hash_traverse' +............................. + + -- Function: void bfd_hash_traverse (struct bfd_hash_table *, bool (*) + (struct bfd_hash_entry *, void *), void *); + Traverse a hash table. + +2.18.4.14 'bfd_hash_set_default_size' +..................................... + + -- Function: unsigned int bfd_hash_set_default_size (unsigned int); + Set hash table default size. + +2.18.4.15 '_bfd_stringtab_init' +............................... + + -- Function: struct bfd_strtab_hash *_bfd_stringtab_init (void); + Create a new strtab. + +2.18.4.16 '_bfd_xcoff_stringtab_init' +..................................... + + -- Function: struct bfd_strtab_hash *_bfd_xcoff_stringtab_init (bool + *isxcoff64*); + Create a new strtab in which the strings are output in the format + used in the XCOFF .debug section: a two byte length precedes each + string. + +2.18.4.17 '_bfd_stringtab_free' +............................... + + -- Function: void _bfd_stringtab_free (struct bfd_strtab_hash *); + Free a strtab. + +2.18.4.18 '_bfd_stringtab_add' +.............................. + + -- Function: bfd_size_type _bfd_stringtab_add (struct bfd_strtab_hash + *, const char *, bool *hash*, bool *copy*); + Get the index of a string in a strtab, adding it if it is not + already present. If HASH is FALSE, we don't really use the hash + table, and we don't eliminate duplicate strings. If COPY is true + then store a copy of STR if creating a new entry. + +2.18.4.19 '_bfd_stringtab_size' +............................... + + -- Function: bfd_size_type _bfd_stringtab_size (struct bfd_strtab_hash + *); + Get the number of bytes in a strtab. + +2.18.4.20 '_bfd_stringtab_emit' +............................... + + -- Function: bool _bfd_stringtab_emit (bfd *, struct bfd_strtab_hash + *); + Write out a strtab. ABFD must already be at the right location in + the file. + + +File: bfd.info, Node: BFD back ends, Next: GNU Free Documentation License, Prev: BFD front end, Up: Top + +3 BFD back ends +*************** + +* Menu: + +* What to Put Where:: +* aout :: a.out backends +* coff :: coff backends +* elf :: elf backends +* mmo :: mmo backend + + +File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back ends, Up: BFD back ends + +3.1 What to Put Where +===================== + +All of BFD lives in one directory. + + +File: bfd.info, Node: aout, Next: coff, Prev: What to Put Where, Up: BFD back ends + +3.2 a.out backends +================== + +BFD supports a number of different flavours of a.out format, though the +major differences are only the sizes of the structures on disk, and the +shape of the relocation information. + + The support is split into a basic support file 'aoutx.h' and other +files which derive functions from the base. One derivation file is +'aoutf1.h' (for a.out flavour 1), and adds to the basic a.out functions +support for sun3, sun4, and 386 a.out files, to create a target jump +vector for a specific target. + + This information is further split out into more specific files for +each machine, including 'sunos.c' for sun3 and sun4, and 'demo64.c' for +a demonstration of a 64 bit a.out format. + + The base file 'aoutx.h' defines general mechanisms for reading and +writing records to and from disk and various other methods which BFD +requires. It is included by 'aout32.c' and 'aout64.c' to form the names +'aout_32_swap_exec_header_in', 'aout_64_swap_exec_header_in', etc. + + As an example, this is what goes on to make the back end for a sun4, +from 'aout32.c': + + #define ARCH_SIZE 32 + #include "aoutx.h" + + Which exports names: + + ... + aout_32_canonicalize_reloc + aout_32_find_nearest_line + aout_32_get_lineno + aout_32_get_reloc_upper_bound + ... + + from 'sunos.c': + + #define TARGET_NAME "a.out-sunos-big" + #define VECNAME sparc_aout_sunos_be_vec + #include "aoutf1.h" + + requires all the names from 'aout32.c', and produces the jump vector + + sparc_aout_sunos_be_vec + + The file 'host-aout.c' is a special case. It is for a large set of +hosts that use "more or less standard" a.out files, and for which +cross-debugging is not interesting. It uses the standard 32-bit a.out +support routines, but determines the file offsets and addresses of the +text, data, and BSS sections, the machine architecture and machine type, +and the entry point address, in a host-dependent manner. Once these +values have been determined, generic code is used to handle the object +file. + + When porting it to run on a new system, you must supply: + + HOST_PAGE_SIZE + HOST_SEGMENT_SIZE + HOST_MACHINE_ARCH (optional) + HOST_MACHINE_MACHINE (optional) + HOST_TEXT_START_ADDR + HOST_STACK_END_ADDR + + in the file '../include/sys/h-XXX.h' (for your host). These values, +plus the structures and macros defined in 'a.out.h' on your host system, +will produce a BFD target that will access ordinary a.out files on your +host. To configure a new machine to use 'host-aout.c', specify: + + TDEFAULTS = -DDEFAULT_VECTOR=host_aout_big_vec + TDEPFILES= host-aout.o trad-core.o + + in the 'config/XXX.mt' file, and modify 'configure.ac' to use the +'XXX.mt' file (by setting "'bfd_target=XXX'") when your configuration is +selected. + +3.2.1 Relocations +----------------- + +The file 'aoutx.h' provides for both the _standard_ and _extended_ forms +of a.out relocation records. + + The standard records contain only an address, a symbol index, and a +type field. The extended records also have a full integer for an +addend. + +3.2.2 Internal entry points +--------------------------- + +'aoutx.h' exports several routines for accessing the contents of an +a.out file, which are gathered and exported in turn by various format +specific files (eg sunos.c). + +3.2.2.1 'aout_SIZE_swap_exec_header_in' +....................................... + + -- Function: void aout_SIZE_swap_exec_header_in, (bfd *abfd, struct + external_exec *bytes, struct internal_exec *execp); + Swap the information in an executable header RAW_BYTES taken from a + raw byte stream memory image into the internal exec header + structure EXECP. + +3.2.2.2 'aout_SIZE_swap_exec_header_out' +........................................ + + -- Function: bool aout_SIZE_swap_exec_header_out (bfd *abfd, struct + internal_exec *execp, struct external_exec *raw_bytes); + Swap the information in an internal exec header structure EXECP + into the buffer RAW_BYTES ready for writing to disk. + +3.2.2.3 'aout_SIZE_some_aout_object_p' +...................................... + + -- Function: bfd_cleanup aout_SIZE_some_aout_object_p (bfd *abfd, + struct internal_exec *execp, bfd_cleanup + (*callback_to_real_object_p) (bfd *)); + Some a.out variant thinks that the file open in ABFD checking is an + a.out file. Do some more checking, and set up for access if it + really is. Call back to the calling environment's "finish up" + function just before returning, to handle any last-minute setup. + +3.2.2.4 'aout_SIZE_mkobject' +............................ + + -- Function: bool aout_SIZE_mkobject, (bfd *abfd); + Initialize BFD ABFD for use with a.out files. + +3.2.2.5 'aout_SIZE_machine_type' +................................ + + -- Function: enum machine_type aout_SIZE_machine_type (enum + bfd_architecture arch, unsigned long machine, bool *unknown); + Keep track of machine architecture and machine type for a.out's. + Return the 'machine_type' for a particular architecture and + machine, or 'M_UNKNOWN' if that exact architecture and machine + can't be represented in a.out format. + + If the architecture is understood, machine type 0 (default) is + always understood. + +3.2.2.6 'aout_SIZE_set_arch_mach' +................................. + + -- Function: bool aout_SIZE_set_arch_mach, (bfd *, enum + bfd_architecture arch, unsigned long machine); + Set the architecture and the machine of the BFD ABFD to the values + ARCH and MACHINE. Verify that ABFD's format can support the + architecture required. + +3.2.2.7 'aout_SIZE_new_section_hook' +.................................... + + -- Function: bool aout_SIZE_new_section_hook, (bfd *abfd, asection + *newsect); + Called by the BFD in response to a 'bfd_make_section' request. + + +File: bfd.info, Node: coff, Next: elf, Prev: aout, Up: BFD back ends + +3.3 coff backends +================= + +BFD supports a number of different flavours of coff format. The major +differences between formats are the sizes and alignments of fields in +structures on disk, and the occasional extra field. + + Coff in all its varieties is implemented with a few common files and +a number of implementation specific files. For example, the i386 coff +format is implemented in the file 'coff-i386.c'. This file '#include's +'coff/i386.h' which defines the external structure of the coff format +for the i386, and 'coff/internal.h' which defines the internal +structure. 'coff-i386.c' also defines the relocations used by the i386 +coff format *Note Relocations::. + +3.3.1 Porting to a new version of coff +-------------------------------------- + +The recommended method is to select from the existing implementations +the version of coff which is most like the one you want to use. For +example, we'll say that i386 coff is the one you select, and that your +coff flavour is called foo. Copy 'i386coff.c' to 'foocoff.c', copy +'../include/coff/i386.h' to '../include/coff/foo.h', and add the lines +to 'targets.c' and 'Makefile.in' so that your new back end is used. +Alter the shapes of the structures in '../include/coff/foo.h' so that +they match what you need. You will probably also have to add '#ifdef's +to the code in 'coff/internal.h' and 'coffcode.h' if your version of +coff is too wild. + + You can verify that your new BFD backend works quite simply by +building 'objdump' from the 'binutils' directory, and making sure that +its version of what's going on and your host system's idea (assuming it +has the pretty standard coff dump utility, usually called 'att-dump' or +just 'dump') are the same. Then clean up your code, and send what +you've done to Cygnus. Then your stuff will be in the next release, and +you won't have to keep integrating it. + +3.3.2 How the coff backend works +-------------------------------- + +3.3.2.1 File layout +................... + +The Coff backend is split into generic routines that are applicable to +any Coff target and routines that are specific to a particular target. +The target-specific routines are further split into ones which are +basically the same for all Coff targets except that they use the +external symbol format or use different values for certain constants. + + The generic routines are in 'coffgen.c'. These routines work for any +Coff target. They use some hooks into the target specific code; the +hooks are in a 'bfd_coff_backend_data' structure, one of which exists +for each target. + + The essentially similar target-specific routines are in 'coffcode.h'. +This header file includes executable C code. The various Coff targets +first include the appropriate Coff header file, make any special defines +that are needed, and then include 'coffcode.h'. + + Some of the Coff targets then also have additional routines in the +target source file itself. + +3.3.2.2 Coff long section names +............................... + +In the standard Coff object format, section names are limited to the +eight bytes available in the 's_name' field of the 'SCNHDR' section +header structure. The format requires the field to be NUL-padded, but +not necessarily NUL-terminated, so the longest section names permitted +are a full eight characters. + + The Microsoft PE variants of the Coff object file format add an +extension to support the use of long section names. This extension is +defined in section 4 of the Microsoft PE/COFF specification (rev 8.1). +If a section name is too long to fit into the section header's 's_name' +field, it is instead placed into the string table, and the 's_name' +field is filled with a slash ("/") followed by the ASCII decimal +representation of the offset of the full name relative to the string +table base. + + Note that this implies that the extension can only be used in object +files, as executables do not contain a string table. The standard +specifies that long section names from objects emitted into executable +images are to be truncated. + + However, as a GNU extension, BFD can generate executable images that +contain a string table and long section names. This would appear to be +technically valid, as the standard only says that Coff debugging +information is deprecated, not forbidden, and in practice it works, +although some tools that parse PE files expecting the MS standard format +may become confused; 'PEview' is one known example. + + The functionality is supported in BFD by code implemented under the +control of the macro 'COFF_LONG_SECTION_NAMES'. If not defined, the +format does not support long section names in any way. If defined, it +is used to initialise a flag, '_bfd_coff_long_section_names', and a hook +function pointer, '_bfd_coff_set_long_section_names', in the Coff +backend data structure. The flag controls the generation of long +section names in output BFDs at runtime; if it is false, as it will be +by default when generating an executable image, long section names are +truncated; if true, the long section names extension is employed. The +hook points to a function that allows the value of a copy of the flag in +coff object tdata to be altered at runtime, on formats that support long +section names at all; on other formats it points to a stub that returns +an error indication. + + With input BFDs, the flag is set according to whether any long +section names are detected while reading the section headers. For a +completely new BFD, the flag is set to the default for the target +format. This information can be used by a client of the BFD library +when deciding what output format to generate, and means that a BFD that +is opened for read and subsequently converted to a writeable BFD and +modified in-place will retain whatever format it had on input. + + If 'COFF_LONG_SECTION_NAMES' is simply defined (blank), or is defined +to the value "1", then long section names are enabled by default; if it +is defined to the value zero, they are disabled by default (but still +accepted in input BFDs). The header 'coffcode.h' defines a macro, +'COFF_DEFAULT_LONG_SECTION_NAMES', which is used in the backends to +initialise the backend data structure fields appropriately; see the +comments for further detail. + +3.3.2.3 Bit twiddling +..................... + +Each flavour of coff supported in BFD has its own header file describing +the external layout of the structures. There is also an internal +description of the coff layout, in 'coff/internal.h'. A major function +of the coff backend is swapping the bytes and twiddling the bits to +translate the external form of the structures into the normal internal +form. This is all performed in the 'bfd_swap'_thing_direction routines. +Some elements are different sizes between different versions of coff; it +is the duty of the coff version specific include file to override the +definitions of various packing routines in 'coffcode.h'. E.g., the size +of line number entry in coff is sometimes 16 bits, and sometimes 32 +bits. '#define'ing 'PUT_LNSZ_LNNO' and 'GET_LNSZ_LNNO' will select the +correct one. No doubt, some day someone will find a version of coff +which has a varying field size not catered to at the moment. To port +BFD, that person will have to add more '#defines'. Three of the bit +twiddling routines are exported to 'gdb'; 'coff_swap_aux_in', +'coff_swap_sym_in' and 'coff_swap_lineno_in'. 'GDB' reads the symbol +table on its own, but uses BFD to fix things up. More of the bit +twiddlers are exported for 'gas'; 'coff_swap_aux_out', +'coff_swap_sym_out', 'coff_swap_lineno_out', 'coff_swap_reloc_out', +'coff_swap_filehdr_out', 'coff_swap_aouthdr_out', +'coff_swap_scnhdr_out'. 'Gas' currently keeps track of all the symbol +table and reloc drudgery itself, thereby saving the internal BFD +overhead, but uses BFD to swap things on the way out, making cross ports +much safer. Doing so also allows BFD (and thus the linker) to use the +same header files as 'gas', which makes one avenue to disaster +disappear. + +3.3.2.4 Symbol reading +...................... + +The simple canonical form for symbols used by BFD is not rich enough to +keep all the information available in a coff symbol table. The back end +gets around this problem by keeping the original symbol table around, +"behind the scenes". + + When a symbol table is requested (through a call to +'bfd_canonicalize_symtab'), a request gets through to +'coff_get_normalized_symtab'. This reads the symbol table from the coff +file and swaps all the structures inside into the internal form. It +also fixes up all the pointers in the table (represented in the file by +offsets from the first symbol in the table) into physical pointers to +elements in the new internal table. This involves some work since the +meanings of fields change depending upon context: a field that is a +pointer to another structure in the symbol table at one moment may be +the size in bytes of a structure at the next. Another pass is made over +the table. All symbols which mark file names ('C_FILE' symbols) are +modified so that the internal string points to the value in the auxent +(the real filename) rather than the normal text associated with the +symbol ('".file"'). + + At this time the symbol names are moved around. Coff stores all +symbols less than nine characters long physically within the symbol +table; longer strings are kept at the end of the file in the string +table. This pass moves all strings into memory and replaces them with +pointers to the strings. + + The symbol table is massaged once again, this time to create the +canonical table used by the BFD application. Each symbol is inspected +in turn, and a decision made (using the 'sclass' field) about the +various flags to set in the 'asymbol'. *Note Symbols::. The generated +canonical table shares strings with the hidden internal symbol table. + + Any linenumbers are read from the coff file too, and attached to the +symbols which own the functions the linenumbers belong to. + +3.3.2.5 Symbol writing +...................... + +Writing a symbol to a coff file which didn't come from a coff file will +lose any debugging information. The 'asymbol' structure remembers the +BFD from which the symbol was taken, and on output the back end makes +sure that the same destination target as source target is present. + + When the symbols have come from a coff file then all the debugging +information is preserved. + + Symbol tables are provided for writing to the back end in a vector of +pointers to pointers. This allows applications like the linker to +accumulate and output large symbol tables without having to do too much +byte copying. + + This function runs through the provided symbol table and patches each +symbol marked as a file place holder ('C_FILE') to point to the next +file place holder in the list. It also marks each 'offset' field in the +list with the offset from the first symbol of the current symbol. + + Another function of this procedure is to turn the canonical value +form of BFD into the form used by coff. Internally, BFD expects symbol +values to be offsets from a section base; so a symbol physically at +0x120, but in a section starting at 0x100, would have the value 0x20. +Coff expects symbols to contain their final value, so symbols have their +values changed at this point to reflect their sum with their owning +section. This transformation uses the 'output_section' field of the +'asymbol''s 'asection' *Note Sections::. + + * 'coff_mangle_symbols' + This routine runs though the provided symbol table and uses the +offsets generated by the previous pass and the pointers generated when +the symbol table was read in to create the structured hierarchy required +by coff. It changes each pointer to a symbol into the index into the +symbol table of the asymbol. + + * 'coff_write_symbols' + This routine runs through the symbol table and patches up the symbols +from their internal form into the coff way, calls the bit twiddlers, and +writes out the table to the file. + +3.3.2.6 'coff_symbol_type' +.......................... + +The hidden information for an 'asymbol' is described in a +'combined_entry_type': + + typedef struct coff_ptr_struct + { + /* Remembers the offset from the first symbol in the file for + this symbol. Generated by coff_renumber_symbols. */ + unsigned int offset; + + /* Selects between the elements of the union below. */ + unsigned int is_sym : 1; + + /* Selects between the elements of the x_sym.x_tagndx union. If set, + p is valid and the field will be renumbered. */ + unsigned int fix_tag : 1; + + /* Selects between the elements of the x_sym.x_fcnary.x_fcn.x_endndx + union. If set, p is valid and the field will be renumbered. */ + unsigned int fix_end : 1; + + /* Selects between the elements of the x_csect.x_scnlen union. If set, + p is valid and the field will be renumbered. */ + unsigned int fix_scnlen : 1; + + /* If set, u.syment.n_value contains a pointer to a symbol. The final + value will be the offset field. Used for XCOFF C_BSTAT symbols. */ + unsigned int fix_value : 1; + + /* If set, u.syment.n_value is an index into the line number entries. + Used for XCOFF C_BINCL/C_EINCL symbols. */ + unsigned int fix_line : 1; + + /* The container for the symbol structure as read and translated + from the file. */ + union + { + union internal_auxent auxent; + struct internal_syment syment; + } u; + + /* An extra pointer which can used by format based on COFF (like XCOFF) + to provide extra information to their backend. */ + void *extrap; + } combined_entry_type; + + /* Each canonical asymbol really looks like this: */ + + typedef struct coff_symbol_struct + { + /* The actual symbol which the rest of BFD works with */ + asymbol symbol; + + /* A pointer to the hidden information for this symbol */ + combined_entry_type *native; + + /* A pointer to the linenumber information for this symbol */ + struct lineno_cache_entry *lineno; + + /* Have the line numbers been relocated yet ? */ + bool done_lineno; + } coff_symbol_type; + + +3.3.2.7 'bfd_coff_backend_data' +............................... + + typedef struct + { + void (*_bfd_coff_swap_aux_in) + (bfd *, void *, int, int, int, int, void *); + + void (*_bfd_coff_swap_sym_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_lineno_in) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aux_out) + (bfd *, void *, int, int, int, int, void *); + + unsigned int (*_bfd_coff_swap_sym_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_lineno_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_reloc_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_filehdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aouthdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_scnhdr_out) + (bfd *, void *, void *); + + unsigned int _bfd_filhsz; + unsigned int _bfd_aoutsz; + unsigned int _bfd_scnhsz; + unsigned int _bfd_symesz; + unsigned int _bfd_auxesz; + unsigned int _bfd_relsz; + unsigned int _bfd_linesz; + unsigned int _bfd_filnmlen; + bool _bfd_coff_long_filenames; + + bool _bfd_coff_long_section_names; + bool (*_bfd_coff_set_long_section_names) + (bfd *, int); + + unsigned int _bfd_coff_default_section_alignment_power; + bool _bfd_coff_force_symnames_in_strings; + unsigned int _bfd_coff_debug_string_prefix_length; + unsigned int _bfd_coff_max_nscns; + + void (*_bfd_coff_swap_filehdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_aouthdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_scnhdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_reloc_in) + (bfd *abfd, void *, void *); + + bool (*_bfd_coff_bad_format_hook) + (bfd *, void *); + + bool (*_bfd_coff_set_arch_mach_hook) + (bfd *, void *); + + void * (*_bfd_coff_mkobject_hook) + (bfd *, void *, void *); + + bool (*_bfd_styp_to_sec_flags_hook) + (bfd *, void *, const char *, asection *, flagword *); + + void (*_bfd_set_alignment_hook) + (bfd *, asection *, void *); + + bool (*_bfd_coff_slurp_symbol_table) + (bfd *); + + bool (*_bfd_coff_symname_in_debug) + (bfd *, struct internal_syment *); + + bool (*_bfd_coff_pointerize_aux_hook) + (bfd *, combined_entry_type *, combined_entry_type *, + unsigned int, combined_entry_type *); + + bool (*_bfd_coff_print_aux) + (bfd *, FILE *, combined_entry_type *, combined_entry_type *, + combined_entry_type *, unsigned int); + + bool (*_bfd_coff_reloc16_extra_cases) + (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *, + bfd_byte *, size_t *, size_t *); + + int (*_bfd_coff_reloc16_estimate) + (bfd *, asection *, arelent *, unsigned int, + struct bfd_link_info *); + + enum coff_symbol_classification (*_bfd_coff_classify_symbol) + (bfd *, struct internal_syment *); + + bool (*_bfd_coff_compute_section_file_positions) + (bfd *); + + bool (*_bfd_coff_start_final_link) + (bfd *, struct bfd_link_info *); + + bool (*_bfd_coff_relocate_section) + (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *, + struct internal_reloc *, struct internal_syment *, asection **); + + reloc_howto_type *(*_bfd_coff_rtype_to_howto) + (bfd *, asection *, struct internal_reloc *, + struct coff_link_hash_entry *, struct internal_syment *, bfd_vma *); + + bool (*_bfd_coff_adjust_symndx) + (bfd *, struct bfd_link_info *, bfd *, asection *, + struct internal_reloc *, bool *); + + bool (*_bfd_coff_link_add_one_symbol) + (struct bfd_link_info *, bfd *, const char *, flagword, + asection *, bfd_vma, const char *, bool, bool, + struct bfd_link_hash_entry **); + + bool (*_bfd_coff_link_output_has_begun) + (bfd *, struct coff_final_link_info *); + + bool (*_bfd_coff_final_link_postscript) + (bfd *, struct coff_final_link_info *); + + bool (*_bfd_coff_print_pdata) + (bfd *, void *); + + } bfd_coff_backend_data; + + +3.3.2.8 Writing relocations +........................... + +To write relocations, the back end steps though the canonical relocation +table and create an 'internal_reloc'. The symbol index to use is +removed from the 'offset' field in the symbol table supplied. The +address comes directly from the sum of the section base address and the +relocation offset; the type is dug directly from the howto field. Then +the 'internal_reloc' is swapped into the shape of an 'external_reloc' +and written out to disk. + +3.3.2.9 Reading linenumbers +........................... + +Creating the linenumber table is done by reading in the entire coff +linenumber table, and creating another table for internal use. + + A coff linenumber table is structured so that each function is marked +as having a line number of 0. Each line within the function is an +offset from the first line in the function. The base of the line number +information for the table is stored in the symbol associated with the +function. + + Note: The PE format uses line number 0 for a flag indicating a new +source file. + + The information is copied from the external to the internal table, +and each symbol which marks a function is marked by pointing its... + + How does this work ? + +3.3.2.10 Reading relocations +............................ + +Coff relocations are easily transformed into the internal BFD form +('arelent'). + + Reading a coff relocation table is done in the following stages: + + * Read the entire coff relocation table into memory. + + * Process each relocation in turn; first swap it from the external to + the internal form. + + * Turn the symbol referenced in the relocation's symbol index into a + pointer into the canonical symbol table. This table is the same as + the one returned by a call to 'bfd_canonicalize_symtab'. The back + end will call that routine and save the result if a + canonicalization hasn't been done. + + * The reloc index is turned into a pointer to a howto structure, in a + back end specific way. For instance, the 386 uses the 'r_type' to + directly produce an index into a howto table vector. + + * Note that 'arelent.addend' for COFF is often not what most people + understand as a relocation addend, but rather an adjustment to the + relocation addend stored in section contents of relocatable object + files. The value found in section contents may also be confusing, + depending on both symbol value and addend somewhat similar to the + field value for a final-linked object. See 'CALC_ADDEND'. + + +File: bfd.info, Node: elf, Next: mmo, Prev: coff, Up: BFD back ends + +3.4 ELF backends +================ + +BFD support for ELF formats is being worked on. Currently, the best +supported back ends are for sparc and i386 (running svr4 or Solaris 2). + + Documentation of the internals of the support code still needs to be +written. The code is changing quickly enough that we haven't bothered +yet. + + +File: bfd.info, Node: mmo, Prev: elf, Up: BFD back ends + +3.5 mmo backend +=============== + +The mmo object format is used exclusively together with Professor Donald +E. Knuth's educational 64-bit processor MMIX. The simulator 'mmix' which +is available at understands this +format. That package also includes a combined assembler and linker +called 'mmixal'. The mmo format has no advantages feature-wise compared +to e.g. ELF. It is a simple non-relocatable object format with no +support for archives or debugging information, except for symbol value +information and line numbers (which is not yet implemented in BFD). See + for more information about MMIX. The ELF format +is used for intermediate object files in the BFD implementation. + +* Menu: + +* File layout:: +* Symbol-table:: +* mmo section mapping:: + + +File: bfd.info, Node: File layout, Next: Symbol-table, Prev: mmo, Up: mmo + +3.5.1 File layout +----------------- + +The mmo file contents is not partitioned into named sections as with +e.g. ELF. Memory areas is formed by specifying the location of the data +that follows. Only the memory area '0x0000...00' to '0x01ff...ff' is +executable, so it is used for code (and constants) and the area +'0x2000...00' to '0x20ff...ff' is used for writable data. *Note mmo +section mapping::. + + There is provision for specifying "special data" of 65536 different +types. We use type 80 (decimal), arbitrarily chosen the same as the ELF +'e_machine' number for MMIX, filling it with section information +normally found in ELF objects. *Note mmo section mapping::. + + Contents is entered as 32-bit words, xor:ed over previous contents, +always zero-initialized. A word that starts with the byte '0x98' forms +a command called a 'lopcode', where the next byte distinguished between +the thirteen lopcodes. The two remaining bytes, called the 'Y' and 'Z' +fields, or the 'YZ' field (a 16-bit big-endian number), are used for +various purposes different for each lopcode. As documented in +, the lopcodes are: + +'lop_quote' + 0x98000001. The next word is contents, regardless of whether it + starts with 0x98 or not. + +'lop_loc' + 0x9801YYZZ, where 'Z' is 1 or 2. This is a location directive, + setting the location for the next data to the next 32-bit word (for + Z = 1) or 64-bit word (for Z = 2), plus Y * 2^56. Normally 'Y' is + 0 for the text segment and 2 for the data segment. Beware that the + low bits of non- tetrabyte-aligned values are silently discarded + when being automatically incremented and when storing contents (in + contrast to e.g. its use as current location when followed by + lop_fixo et al before the next possibly-quoted tetrabyte contents). + +'lop_skip' + 0x9802YYZZ. Increase the current location by 'YZ' bytes. + +'lop_fixo' + 0x9803YYZZ, where 'Z' is 1 or 2. Store the current location as 64 + bits into the location pointed to by the next 32-bit (Z = 1) or + 64-bit (Z = 2) word, plus Y * 2^56. + +'lop_fixr' + 0x9804YYZZ. 'YZ' is stored into the current location plus 2 - 4 * + YZ. + +'lop_fixrx' + 0x980500ZZ. 'Z' is 16 or 24. A value 'L' derived from the + following 32-bit word are used in a manner similar to 'YZ' in + lop_fixr: it is xor:ed into the current location minus 4 * L. The + first byte of the word is 0 or 1. If it is 1, then L = (LOWEST 24 + BITS OF WORD) - 2^Z, if 0, then L = (LOWEST 24 BITS OF WORD). + +'lop_file' + 0x9806YYZZ. 'Y' is the file number, 'Z' is count of 32-bit words. + Set the file number to 'Y' and the line counter to 0. The next Z * + 4 bytes contain the file name, padded with zeros if the count is + not a multiple of four. The same 'Y' may occur multiple times, but + 'Z' must be 0 for all but the first occurrence. + +'lop_line' + 0x9807YYZZ. 'YZ' is the line number. Together with lop_file, it + forms the source location for the next 32-bit word. Note that for + each non-lopcode 32-bit word, line numbers are assumed incremented + by one. + +'lop_spec' + 0x9808YYZZ. 'YZ' is the type number. Data until the next lopcode + other than lop_quote forms special data of type 'YZ'. *Note mmo + section mapping::. + + Other types than 80, (or type 80 with a content that does not + parse) is stored in sections named '.MMIX.spec_data.N' where N is + the 'YZ'-type. The flags for such a sections say not to allocate + or load the data. The vma is 0. Contents of multiple occurrences + of special data N is concatenated to the data of the previous + lop_spec Ns. The location in data or code at which the lop_spec + occurred is lost. + +'lop_pre' + 0x980901ZZ. The first lopcode in a file. The 'Z' field forms the + length of header information in 32-bit words, where the first word + tells the time in seconds since '00:00:00 GMT Jan 1 1970'. + +'lop_post' + 0x980a00ZZ. Z > 32. This lopcode follows after all + content-generating lopcodes in a program. The 'Z' field denotes + the value of 'rG' at the beginning of the program. The following + 256 - Z big-endian 64-bit words are loaded into global registers + '$G' ... '$255'. + +'lop_stab' + 0x980b0000. The next-to-last lopcode in a program. Must follow + immediately after the lop_post lopcode and its data. After this + lopcode follows all symbols in a compressed format (*note + Symbol-table::). + +'lop_end' + 0x980cYYZZ. The last lopcode in a program. It must follow the + lop_stab lopcode and its data. The 'YZ' field contains the number + of 32-bit words of symbol table information after the preceding + lop_stab lopcode. + + Note that the lopcode "fixups"; 'lop_fixr', 'lop_fixrx' and +'lop_fixo' are not generated by BFD, but are handled. They are +generated by 'mmixal'. + + This trivial one-label, one-instruction file: + + :Main TRAP 1,2,3 + + can be represented this way in mmo: + + 0x98090101 - lop_pre, one 32-bit word with timestamp. + + 0x98010002 - lop_loc, text segment, using a 64-bit address. + Note that mmixal does not emit this for the file above. + 0x00000000 - Address, high 32 bits. + 0x00000000 - Address, low 32 bits. + 0x98060002 - lop_file, 2 32-bit words for file-name. + 0x74657374 - "test" + 0x2e730000 - ".s\0\0" + 0x98070001 - lop_line, line 1. + 0x00010203 - TRAP 1,2,3 + 0x980a00ff - lop_post, setting $255 to 0. + 0x00000000 + 0x00000000 + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 *Note Symbol-table::. + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 + 0x980c0005 - lop_end; symbol table contained five 32-bit words. + + +File: bfd.info, Node: Symbol-table, Next: mmo section mapping, Prev: File layout, Up: mmo + +3.5.2 Symbol table format +------------------------- + +From mmixal.w (or really, the generated mmixal.tex) in the MMIXware +package which also contains the 'mmix' simulator: "Symbols are stored +and retrieved by means of a 'ternary search trie', following ideas of +Bentley and Sedgewick. (See ACM-SIAM Symp. on Discrete Algorithms '8' +(1997), 360-369; R.Sedgewick, 'Algorithms in C' (Reading, Mass. +Addison-Wesley, 1998), '15.4'.) Each trie node stores a character, and +there are branches to subtries for the cases where a given character is +less than, equal to, or greater than the character in the trie. There +also is a pointer to a symbol table entry if a symbol ends at the +current node." + + So it's a tree encoded as a stream of bytes. The stream of bytes +acts on a single virtual global symbol, adding and removing characters +and signalling complete symbol points. Here, we read the stream and +create symbols at the completion points. + + First, there's a control byte 'm'. If any of the listed bits in 'm' +is nonzero, we execute what stands at the right, in the listed order: + + (MMO3_LEFT) + 0x40 - Traverse left trie. + (Read a new command byte and recurse.) + + (MMO3_SYMBITS) + 0x2f - Read the next byte as a character and store it in the + current character position; increment character position. + Test the bits of m: + + (MMO3_WCHAR) + 0x80 - The character is 16-bit (so read another byte, + merge into current character. + + (MMO3_TYPEBITS) + 0xf - We have a complete symbol; parse the type, value + and serial number and do what should be done + with a symbol. The type and length information + is in j = (m & 0xf). + + (MMO3_REGQUAL_BITS) + j == 0xf: A register variable. The following + byte tells which register. + j <= 8: An absolute symbol. Read j bytes as the + big-endian number the symbol equals. + A j = 2 with two zero bytes denotes an + unknown symbol. + j > 8: As with j <= 8, but add (0x20 << 56) + to the value in the following j - 8 + bytes. + + Then comes the serial number, as a variant of + uleb128, but better named ubeb128: + Read bytes and shift the previous value left 7 + (multiply by 128). Add in the new byte, repeat + until a byte has bit 7 set. The serial number + is the computed value minus 128. + + (MMO3_MIDDLE) + 0x20 - Traverse middle trie. (Read a new command byte + and recurse.) Decrement character position. + + (MMO3_RIGHT) + 0x10 - Traverse right trie. (Read a new command byte and + recurse.) + + Let's look again at the 'lop_stab' for the trivial file (*note File +layout::). + + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 + + This forms the trivial trie (note that the path between ":" and "M" +is redundant): + + 203a ":" + 40 / + 40 / + 10 \ + 40 / + 40 / + 204d "M" + 2061 "a" + 2069 "i" + 016e "n" is the last character in a full symbol, and + with a value represented in one byte. + 00 The value is 0. + 81 The serial number is 1. + + +File: bfd.info, Node: mmo section mapping, Prev: Symbol-table, Up: mmo + +3.5.3 mmo section mapping +------------------------- + +The implementation in BFD uses special data type 80 (decimal) to +encapsulate and describe named sections, containing e.g. debug +information. If needed, any datum in the encapsulation will be quoted +using lop_quote. First comes a 32-bit word holding the number of 32-bit +words containing the zero-terminated zero-padded segment name. After +the name there's a 32-bit word holding flags describing the section +type. Then comes a 64-bit big-endian word with the section length (in +bytes), then another with the section start address. Depending on the +type of section, the contents might follow, zero-padded to 32-bit +boundary. For a loadable section (such as data or code), the contents +might follow at some later point, not necessarily immediately, as a +lop_loc with the same start address as in the section description, +followed by the contents. This in effect forms a descriptor that must +be emitted before the actual contents. Sections described this way must +not overlap. + + For areas that don't have such descriptors, synthetic sections are +formed by BFD. Consecutive contents in the two memory areas +'0x0000...00' to '0x01ff...ff' and '0x2000...00' to '0x20ff...ff' are +entered in sections named '.text' and '.data' respectively. If an area +is not otherwise described, but would together with a neighboring lower +area be less than '0x40000000' bytes long, it is joined with the lower +area and the gap is zero-filled. For other cases, a new section is +formed, named '.MMIX.sec.N'. Here, N is a number, a running count +through the mmo file, starting at 0. + + A loadable section specified as: + + .section secname,"ax" + TETRA 1,2,3,4,-1,-2009 + BYTE 80 + + and linked to address '0x4', is represented by the sequence: + + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "secn" + 0x616d6500 - "ame\0" + 0x00000033 - flags CODE, READONLY, LOAD, ALLOC + 0x00000000 - high 32 bits of section length + 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits + 0x00000000 - high 32 bits of section address + 0x00000004 - section address is 4 + 0x98010002 - 64 bits with address of following data + 0x00000000 - high 32 bits of address + 0x00000004 - low 32 bits: data starts at address 4 + 0x00000001 - 1 + 0x00000002 - 2 + 0x00000003 - 3 + 0x00000004 - 4 + 0xffffffff - -1 + 0xfffff827 - -2009 + 0x50000000 - 80 as a byte, padded with zeros. + + Note that the lop_spec wrapping does not include the section +contents. Compare this to a non-loaded section specified as: + + .section thirdsec + TETRA 200001,100002 + BYTE 38,40 + + This, when linked to address '0x200000000000001c', is represented by: + + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "thir" + 0x616d6500 - "dsec" + 0x00000010 - flag READONLY + 0x00000000 - high 32 bits of section length + 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits + 0x20000000 - high 32 bits of address + 0x0000001c - low 32 bits of address 0x200000000000001c + 0x00030d41 - 200001 + 0x000186a2 - 100002 + 0x26280000 - 38, 40 as bytes, padded with zeros + + For the latter example, the section contents must not be loaded in +memory, and is therefore specified as part of the special data. The +address is usually unimportant but might provide information for e.g. +the DWARF 2 debugging format. + + +File: bfd.info, Node: GNU Free Documentation License, Next: BFD Index, Prev: BFD back ends, Up: Top + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: bfd.info, Node: BFD Index, Prev: GNU Free Documentation License, Up: Top + +BFD Index +********* + +[index] +* Menu: + +* *bfd_alloc: Internal. (line 74) +* *bfd_arch_default_fill: Architectures. (line 740) +* *bfd_asprintf: Error reporting. (line 102) +* *bfd_create: Opening and Closing. + (line 226) +* *bfd_default_reloc_type_lookup: howto manager. (line 3604) +* *bfd_demangle: Miscellaneous. (line 321) +* *bfd_elf_bfd_from_remote_memory: Opening and Closing. + (line 172) +* *bfd_fdopenr: Opening and Closing. + (line 71) +* *bfd_fdopenw: Opening and Closing. + (line 97) +* *bfd_follow_build_id_debuglink: Opening and Closing. + (line 360) +* *bfd_follow_gnu_debugaltlink: Opening and Closing. + (line 316) +* *bfd_follow_gnu_debuglink: Opening and Closing. + (line 297) +* *bfd_fopen: Opening and Closing. + (line 30) +* *bfd_generic_get_relocated_section_contents: howto manager. + (line 3652) +* *bfd_get_alt_debug_link_info: Opening and Closing. + (line 286) +* *bfd_get_debug_link_info: Opening and Closing. + (line 270) +* *bfd_get_linker_section: section prototypes. (line 37) +* *bfd_get_next_section_by_name: section prototypes. (line 26) +* *bfd_get_relocated_section_contents: Miscellaneous. (line 273) +* *bfd_get_section_by_name: section prototypes. (line 18) +* *bfd_get_section_by_name_if: section prototypes. (line 45) +* *bfd_get_unique_section_name: section prototypes. (line 60) +* *bfd_hash_allocate: Write Other Derived Routines. + (line 83) +* *bfd_make_section: section prototypes. (line 132) +* *bfd_make_section_anyway: section prototypes. (line 106) +* *bfd_make_section_anyway_with_flags: section prototypes. (line 90) +* *bfd_make_section_old_way: section prototypes. (line 71) +* *bfd_make_section_with_flags: section prototypes. (line 121) +* *bfd_malloc: Internal. (line 15) +* *bfd_mmap: Miscellaneous. (line 459) +* *bfd_openr: Opening and Closing. + (line 54) +* *bfd_openr_iovec: Opening and Closing. + (line 116) +* *bfd_openr_next_archived_file: Archives. (line 83) +* *bfd_openstreamr: Opening and Closing. + (line 105) +* *bfd_openw: Opening and Closing. + (line 159) +* *bfd_realloc: Internal. (line 24) +* *bfd_realloc_or_free: Internal. (line 42) +* *bfd_reloc_type_lookup: howto manager. (line 3595) +* *bfd_sections_find_if: section prototypes. (line 178) +* *bfd_zalloc: Internal. (line 81) +* *bfd_zmalloc: Internal. (line 62) +* *_bfd_generic_make_empty_symbol: symbol handling functions. + (line 91) +* *_bfd_new_bfd: Opening and Closing. + (line 12) +* *_bfd_new_bfd_contained_in: Opening and Closing. + (line 18) +* _bfd_clear_error_data: Error reporting. (line 92) +* _bfd_clear_error_data <1>: Error reporting. (line 96) +* _bfd_error_handler: Error reporting. (line 135) +* _bfd_error_handler <1>: Error reporting. (line 139) +* _bfd_final_link_relocate: Relocating the section contents. + (line 22) +* _bfd_free_cached_info: Opening and Closing. + (line 20) +* _bfd_free_cached_info <1>: Opening and Closing. + (line 24) +* _bfd_generic_link_add_archive_symbols: Adding symbols from an archive. + (line 15) +* _bfd_generic_link_add_one_symbol: Adding symbols from an object file. + (line 19) +* _bfd_generic_link_check_relocs: Writing the symbol table. + (line 126) +* _bfd_generic_link_check_relocs <1>: Writing the symbol table. + (line 130) +* _bfd_generic_link_hide_symbol: Writing the symbol table. + (line 75) +* _bfd_generic_link_hide_symbol <1>: Writing the symbol table. + (line 79) +* _bfd_generic_make_empty_symbol: symbol handling functions. + (line 87) +* _bfd_generic_set_reloc: howto manager. (line 3658) +* _bfd_generic_set_reloc <1>: howto manager. (line 3662) +* _bfd_generic_verify_endian_match: Writing the symbol table. + (line 151) +* _bfd_generic_verify_endian_match <1>: Writing the symbol table. + (line 155) +* _bfd_get_error_program_name: Error reporting. (line 183) +* _bfd_link_add_symbols in target vector: Adding Symbols to the Hash Table. + (line 6) +* _bfd_link_final_link in target vector: Performing the Final Link. + (line 6) +* _bfd_link_hash_table_create in target vector: Creating a Linker Hash Table. + (line 6) +* _bfd_new_bfd: Opening and Closing. + (line 8) +* _bfd_new_bfd_contained_in: Opening and Closing. + (line 14) +* _bfd_relocate_contents: Relocating the section contents. + (line 22) +* _bfd_restore_error_handler_caching: Error reporting. (line 168) +* _bfd_restore_error_handler_caching <1>: Error reporting. (line 172) +* _bfd_set_error_handler_caching: Error reporting. (line 157) +* _bfd_stringtab_add: Write Other Derived Routines. + (line 127) +* _bfd_stringtab_add <1>: Write Other Derived Routines. + (line 131) +* _bfd_stringtab_emit: Write Other Derived Routines. + (line 144) +* _bfd_stringtab_emit <1>: Write Other Derived Routines. + (line 148) +* _bfd_stringtab_free: Write Other Derived Routines. + (line 121) +* _bfd_stringtab_free <1>: Write Other Derived Routines. + (line 125) +* _bfd_stringtab_init: Write Other Derived Routines. + (line 106) +* _bfd_stringtab_size: Write Other Derived Routines. + (line 137) +* _bfd_stringtab_size <1>: Write Other Derived Routines. + (line 141) +* _bfd_threading_enabled: Threading. (line 15) +* _bfd_threading_enabled <1>: Threading. (line 20) +* _bfd_unrecognized_reloc: howto manager. (line 3665) +* _bfd_unrecognized_reloc <1>: howto manager. (line 3669) +* _bfd_xcoff_stringtab_init: Write Other Derived Routines. + (line 112) +* aout_SIZE_machine_type: aout. (line 130) +* aout_SIZE_mkobject: aout. (line 124) +* aout_SIZE_mkobject,: aout. (line 128) +* aout_SIZE_new_section_hook: aout. (line 152) +* aout_SIZE_new_section_hook,: aout. (line 156) +* aout_SIZE_set_arch_mach: aout. (line 143) +* aout_SIZE_set_arch_mach,: aout. (line 147) +* aout_SIZE_some_aout_object_p: aout. (line 113) +* aout_SIZE_some_aout_object_p <1>: aout. (line 117) +* aout_SIZE_swap_exec_header_in: aout. (line 96) +* aout_SIZE_swap_exec_header_in,: aout. (line 100) +* aout_SIZE_swap_exec_header_out: aout. (line 105) +* aout_SIZE_swap_exec_header_out <1>: aout. (line 109) +* arelent_chain: typedef arelent. (line 280) +* BFD: Overview. (line 6) +* BFD canonical format: Canonical format. (line 11) +* bfd_alloc: Internal. (line 70) +* bfd_alt_mach_code: Miscellaneous. (line 295) +* bfd_alt_mach_code <1>: Miscellaneous. (line 299) +* bfd_architecture: Architectures. (line 654) +* bfd_arch_bits_per_address: Architectures. (line 670) +* bfd_arch_bits_per_byte: Architectures. (line 663) +* bfd_arch_default_fill: Architectures. (line 736) +* bfd_arch_get_compatible: Architectures. (line 613) +* bfd_arch_info_type: Architectures. (line 601) +* bfd_arch_info_type <1>: Architectures. (line 617) +* bfd_arch_info_type <2>: Architectures. (line 681) +* bfd_arch_info_type <3>: Architectures. (line 696) +* bfd_arch_info_type <4>: Architectures. (line 702) +* bfd_arch_list: Architectures. (line 606) +* bfd_arch_mach_octets_per_byte: Architectures. (line 726) +* BFD_ARELOC_BFIN_ADD: howto manager. (line 1167) +* BFD_ARELOC_BFIN_ADDR: howto manager. (line 1201) +* BFD_ARELOC_BFIN_AND: howto manager. (line 1181) +* BFD_ARELOC_BFIN_COMP: howto manager. (line 1195) +* BFD_ARELOC_BFIN_CONST: howto manager. (line 1165) +* BFD_ARELOC_BFIN_DIV: howto manager. (line 1173) +* BFD_ARELOC_BFIN_HWPAGE: howto manager. (line 1199) +* BFD_ARELOC_BFIN_LAND: howto manager. (line 1187) +* BFD_ARELOC_BFIN_LEN: howto manager. (line 1191) +* BFD_ARELOC_BFIN_LOR: howto manager. (line 1189) +* BFD_ARELOC_BFIN_LSHIFT: howto manager. (line 1177) +* BFD_ARELOC_BFIN_MOD: howto manager. (line 1175) +* BFD_ARELOC_BFIN_MULT: howto manager. (line 1171) +* BFD_ARELOC_BFIN_NEG: howto manager. (line 1193) +* BFD_ARELOC_BFIN_OR: howto manager. (line 1183) +* BFD_ARELOC_BFIN_PAGE: howto manager. (line 1197) +* BFD_ARELOC_BFIN_PUSH: howto manager. (line 1163) +* BFD_ARELOC_BFIN_RSHIFT: howto manager. (line 1179) +* BFD_ARELOC_BFIN_SUB: howto manager. (line 1169) +* BFD_ARELOC_BFIN_XOR: howto manager. (line 1185) +* bfd_asprintf: Error reporting. (line 98) +* bfd_cache_close: File Caching. (line 23) +* bfd_cache_close <1>: File Caching. (line 27) +* bfd_cache_close_all: File Caching. (line 33) +* bfd_cache_close_all <1>: File Caching. (line 37) +* bfd_cache_init: File Caching. (line 17) +* bfd_cache_init <1>: File Caching. (line 21) +* bfd_cache_set_uncloseable: File Caching. (line 45) +* bfd_cache_set_uncloseable <1>: File Caching. (line 49) +* bfd_cache_size: File Caching. (line 58) +* bfd_cache_size <1>: File Caching. (line 62) +* bfd_calc_gnu_debuglink_crc32: Opening and Closing. + (line 255) +* bfd_calc_gnu_debuglink_crc32 <1>: Opening and Closing. + (line 259) +* bfd_canonicalize_reloc: Miscellaneous. (line 17) +* bfd_canonicalize_reloc <1>: Miscellaneous. (line 21) +* bfd_canonicalize_symtab: symbol handling functions. + (line 47) +* bfd_check_format: Formats. (line 20) +* bfd_check_format <1>: Formats. (line 24) +* bfd_check_format_matches: Formats. (line 55) +* bfd_check_format_matches <1>: Formats. (line 59) +* bfd_check_overflow: typedef arelent. (line 292) +* bfd_check_overflow <1>: typedef arelent. (line 296) +* bfd_close: Opening and Closing. + (line 190) +* bfd_close <1>: Opening and Closing. + (line 194) +* bfd_close_all_done: Opening and Closing. + (line 206) +* bfd_close_all_done <1>: Opening and Closing. + (line 210) +* bfd_coff_backend_data: coff. (line 299) +* bfd_copy_private_bfd_data: Miscellaneous. (line 139) +* bfd_copy_private_bfd_data <1>: Miscellaneous. (line 143) +* bfd_copy_private_header_data: Miscellaneous. (line 124) +* bfd_copy_private_header_data <1>: Miscellaneous. (line 128) +* bfd_copy_private_section_data: section prototypes. (line 247) +* bfd_copy_private_section_data <1>: section prototypes. (line 251) +* bfd_copy_private_symbol_data: symbol handling functions. + (line 126) +* bfd_copy_private_symbol_data <1>: symbol handling functions. + (line 130) +* bfd_core_file_failing_command: Core Files. (line 10) +* bfd_core_file_failing_signal: Core Files. (line 17) +* bfd_core_file_failing_signal <1>: Core Files. (line 21) +* bfd_core_file_pid: Core Files. (line 24) +* bfd_core_file_pid <1>: Core Files. (line 28) +* bfd_create: Opening and Closing. + (line 222) +* bfd_create_gnu_debuglink_section: Opening and Closing. + (line 331) +* bfd_decode_symclass: symbol handling functions. + (line 104) +* bfd_decode_symclass <1>: symbol handling functions. + (line 108) +* bfd_default_arch_struct: Architectures. (line 624) +* bfd_default_compatible: Architectures. (line 677) +* bfd_default_reloc_type_lookup: howto manager. (line 3600) +* bfd_default_scan: Architectures. (line 684) +* bfd_default_scan <1>: Architectures. (line 688) +* bfd_default_set_arch_mach: Architectures. (line 641) +* bfd_default_set_arch_mach <1>: Architectures. (line 645) +* bfd_demangle: Miscellaneous. (line 317) +* bfd_elf_bfd_from_remote_memory: Opening and Closing. + (line 168) +* bfd_elf_version_tree: Writing the symbol table. + (line 102) +* bfd_emul_get_commonpagesize: Miscellaneous. (line 311) +* bfd_emul_get_commonpagesize <1>: Miscellaneous. (line 315) +* bfd_emul_get_maxpagesize: Miscellaneous. (line 304) +* bfd_emul_get_maxpagesize <1>: Miscellaneous. (line 308) +* bfd_errmsg: Error reporting. (line 75) +* bfd_fdopenr: Opening and Closing. + (line 67) +* bfd_fdopenw: Opening and Closing. + (line 93) +* bfd_fill_in_gnu_debuglink_section: Opening and Closing. + (line 343) +* bfd_fill_in_gnu_debuglink_section <1>: Opening and Closing. + (line 347) +* bfd_find_target: bfd_target. (line 545) +* bfd_find_version_for_sym: Writing the symbol table. + (line 98) +* bfd_flavour_name: bfd_target. (line 600) +* bfd_flush: Miscellaneous. (line 388) +* bfd_flush <1>: Miscellaneous. (line 392) +* bfd_follow_build_id_debuglink: Opening and Closing. + (line 356) +* bfd_follow_gnu_debugaltlink: Opening and Closing. + (line 312) +* bfd_follow_gnu_debuglink: Opening and Closing. + (line 293) +* bfd_fopen: Opening and Closing. + (line 26) +* bfd_format_string: Formats. (line 79) +* bfd_generic_define_common_symbol: Writing the symbol table. + (line 64) +* bfd_generic_define_common_symbol <1>: Writing the symbol table. + (line 68) +* bfd_generic_define_start_stop: Writing the symbol table. + (line 86) +* bfd_generic_discard_group: section prototypes. (line 276) +* bfd_generic_discard_group <1>: section prototypes. (line 280) +* bfd_generic_gc_sections: howto manager. (line 3623) +* bfd_generic_gc_sections <1>: howto manager. (line 3627) +* bfd_generic_get_relocated_section_contents: howto manager. (line 3648) +* bfd_generic_group_name: section prototypes. (line 269) +* bfd_generic_is_group_section: section prototypes. (line 262) +* bfd_generic_is_group_section <1>: section prototypes. (line 266) +* bfd_generic_lookup_section_flags: howto manager. (line 3631) +* bfd_generic_lookup_section_flags <1>: howto manager. (line 3635) +* bfd_generic_merge_sections: howto manager. (line 3640) +* bfd_generic_merge_sections <1>: howto manager. (line 3644) +* bfd_generic_relax_section: howto manager. (line 3615) +* bfd_generic_relax_section <1>: howto manager. (line 3619) +* bfd_getb64: Internal. (line 260) +* bfd_get_alt_debug_link_info: Opening and Closing. + (line 282) +* bfd_get_arch: Architectures. (line 650) +* bfd_get_arch_info: Architectures. (line 692) +* bfd_get_arch_size: Miscellaneous. (line 58) +* bfd_get_arch_size <1>: Miscellaneous. (line 62) +* bfd_get_current_time: Miscellaneous. (line 465) +* bfd_get_current_time <1>: Miscellaneous. (line 469) +* bfd_get_debug_link_info: Opening and Closing. + (line 266) +* bfd_get_error: Error reporting. (line 50) +* bfd_get_error <1>: Error reporting. (line 55) +* bfd_get_file_size: Miscellaneous. (line 447) +* bfd_get_file_size <1>: Miscellaneous. (line 451) +* bfd_get_gp_size: Miscellaneous. (line 92) +* bfd_get_linker_section: section prototypes. (line 33) +* bfd_get_mach: Architectures. (line 657) +* bfd_get_mtime: Miscellaneous. (line 410) +* bfd_get_mtime <1>: Miscellaneous. (line 414) +* bfd_get_next_mapent: Archives. (line 56) +* bfd_get_next_mapent <1>: Archives. (line 60) +* bfd_get_next_section_by_name: section prototypes. (line 22) +* bfd_get_relocated_section_contents: Miscellaneous. (line 269) +* bfd_get_reloc_code_name: howto manager. (line 3607) +* bfd_get_reloc_upper_bound: Miscellaneous. (line 8) +* bfd_get_reloc_upper_bound <1>: Miscellaneous. (line 12) +* bfd_get_section_by_name: section prototypes. (line 14) +* bfd_get_section_by_name_if: section prototypes. (line 41) +* bfd_get_section_contents: section prototypes. (line 223) +* bfd_get_section_contents <1>: section prototypes. (line 227) +* bfd_get_sign_extend_vma: Miscellaneous. (line 70) +* bfd_get_sign_extend_vma <1>: Miscellaneous. (line 74) +* bfd_get_size: Miscellaneous. (line 417) +* bfd_get_size <1>: Miscellaneous. (line 421) +* bfd_get_size <2>: Internal. (line 102) +* bfd_get_symtab_upper_bound: symbol handling functions. + (line 5) +* bfd_get_target_info: bfd_target. (line 560) +* bfd_get_unique_section_name: section prototypes. (line 56) +* bfd_hash_allocate: Creating and Freeing a Hash Table. + (line 17) +* bfd_hash_allocate <1>: Write Other Derived Routines. + (line 79) +* bfd_hash_entry: Write Other Derived Routines. + (line 55) +* bfd_hash_entry <1>: Write Other Derived Routines. + (line 62) +* bfd_hash_entry <2>: Write Other Derived Routines. + (line 90) +* bfd_hash_insert: Write Other Derived Routines. + (line 58) +* bfd_hash_lookup: Looking Up or Entering a String. + (line 6) +* bfd_hash_lookup <1>: Write Other Derived Routines. + (line 51) +* bfd_hash_newfunc: Creating and Freeing a Hash Table. + (line 12) +* bfd_hash_newfunc <1>: Write Other Derived Routines. + (line 86) +* bfd_hash_rename: Write Other Derived Routines. + (line 65) +* bfd_hash_rename <1>: Write Other Derived Routines. + (line 69) +* bfd_hash_replace: Write Other Derived Routines. + (line 72) +* bfd_hash_replace <1>: Write Other Derived Routines. + (line 76) +* bfd_hash_set_default_size: Creating and Freeing a Hash Table. + (line 25) +* bfd_hash_set_default_size <1>: Write Other Derived Routines. + (line 100) +* bfd_hash_table_free: Creating and Freeing a Hash Table. + (line 21) +* bfd_hash_table_free <1>: Write Other Derived Routines. + (line 45) +* bfd_hash_table_free <2>: Write Other Derived Routines. + (line 49) +* bfd_hash_table_init: Creating and Freeing a Hash Table. + (line 6) +* bfd_hash_table_init <1>: Write Other Derived Routines. + (line 37) +* bfd_hash_table_init <2>: Write Other Derived Routines. + (line 41) +* bfd_hash_table_init_n: Creating and Freeing a Hash Table. + (line 6) +* bfd_hash_table_init_n <1>: Write Other Derived Routines. + (line 28) +* bfd_hash_table_init_n <2>: Write Other Derived Routines. + (line 32) +* bfd_hash_traverse: Traversing a Hash Table. + (line 6) +* bfd_hash_traverse <1>: Write Other Derived Routines. + (line 93) +* bfd_hash_traverse <2>: Write Other Derived Routines. + (line 97) +* bfd_hide_sym_by_version: Writing the symbol table. + (line 109) +* bfd_hide_sym_by_version <1>: Writing the symbol table. + (line 113) +* bfd_h_put_size: Internal. (line 188) +* bfd_init: Initialization. (line 3) +* bfd_install_relocation: typedef arelent. (line 331) +* bfd_install_relocation <1>: typedef arelent. (line 335) +* bfd_is_local_label: symbol handling functions. + (line 16) +* bfd_is_local_label <1>: symbol handling functions. + (line 20) +* bfd_is_local_label_name: symbol handling functions. + (line 23) +* bfd_is_local_label_name <1>: symbol handling functions. + (line 27) +* bfd_is_target_special_symbol: symbol handling functions. + (line 35) +* bfd_is_target_special_symbol <1>: symbol handling functions. + (line 39) +* bfd_is_undefined_symclass: symbol handling functions. + (line 111) +* bfd_is_undefined_symclass <1>: symbol handling functions. + (line 115) +* bfd_iterate_over_targets: bfd_target. (line 590) +* bfd_link_check_relocs: Writing the symbol table. + (line 117) +* bfd_link_check_relocs <1>: Writing the symbol table. + (line 121) +* bfd_link_hash_entry: Writing the symbol table. + (line 90) +* bfd_link_split_section: Writing the symbol table. + (line 43) +* bfd_link_split_section <1>: Writing the symbol table. + (line 47) +* bfd_lock: Threading. (line 45) +* bfd_lock <1>: Threading. (line 49) +* bfd_log2: Internal. (line 280) +* bfd_lookup_arch: Architectures. (line 698) +* bfd_make_debug_symbol: symbol handling functions. + (line 95) +* bfd_make_empty_symbol: symbol handling functions. + (line 73) +* bfd_make_readable: Opening and Closing. + (line 244) +* bfd_make_readable <1>: Opening and Closing. + (line 248) +* bfd_make_section: section prototypes. (line 128) +* bfd_make_section_anyway: section prototypes. (line 102) +* bfd_make_section_anyway_with_flags: section prototypes. (line 86) +* bfd_make_section_old_way: section prototypes. (line 67) +* bfd_make_section_with_flags: section prototypes. (line 117) +* bfd_make_writable: Opening and Closing. + (line 233) +* bfd_make_writable <1>: Opening and Closing. + (line 237) +* bfd_malloc: Internal. (line 11) +* bfd_malloc_and_get_section: section prototypes. (line 238) +* bfd_malloc_and_get_section <1>: section prototypes. (line 242) +* bfd_map_over_sections: section prototypes. (line 156) +* bfd_map_over_sections <1>: section prototypes. (line 160) +* bfd_merge_private_bfd_data: Writing the symbol table. + (line 135) +* bfd_merge_private_bfd_data <1>: Writing the symbol table. + (line 139) +* bfd_mmap: Miscellaneous. (line 455) +* bfd_octets_per_byte: Architectures. (line 717) +* bfd_openr: Opening and Closing. + (line 50) +* bfd_openr_iovec: Opening and Closing. + (line 112) +* bfd_openr_next_archived_file: Archives. (line 79) +* bfd_openstreamr: Opening and Closing. + (line 101) +* bfd_openw: Opening and Closing. + (line 155) +* bfd_open_file: File Caching. (line 64) +* bfd_open_file <1>: File Caching. (line 68) +* bfd_perform_relocation: typedef arelent. (line 311) +* bfd_perform_relocation <1>: typedef arelent. (line 315) +* bfd_perror: Error reporting. (line 82) +* bfd_perror <1>: Error reporting. (line 86) +* bfd_printable_arch_mach: Architectures. (line 707) +* bfd_printable_name: Architectures. (line 590) +* bfd_print_error: Error reporting. (line 122) +* bfd_print_error <1>: Error reporting. (line 127) +* bfd_print_symbol_vandf: symbol handling functions. + (line 65) +* bfd_print_symbol_vandf <1>: symbol handling functions. + (line 69) +* bfd_put_size: Internal. (line 99) +* bfd_read: Miscellaneous. (line 366) +* bfd_read <1>: Miscellaneous. (line 370) +* bfd_realloc: Internal. (line 20) +* bfd_realloc_or_free: Internal. (line 38) +* bfd_record_phdr: Miscellaneous. (line 279) +* bfd_record_phdr <1>: Miscellaneous. (line 283) +* bfd_release: Internal. (line 84) +* bfd_release <1>: Internal. (line 88) +* BFD_RELOC_12_PCREL: howto manager. (line 36) +* BFD_RELOC_14: howto manager. (line 29) +* BFD_RELOC_16: howto manager. (line 28) +* BFD_RELOC_16_BASEREL: howto manager. (line 90) +* BFD_RELOC_16_GOTOFF: howto manager. (line 49) +* BFD_RELOC_16_GOT_PCREL: howto manager. (line 46) +* BFD_RELOC_16_PCREL: howto manager. (line 35) +* BFD_RELOC_16_PCREL_S2: howto manager. (line 100) +* BFD_RELOC_16_PLTOFF: howto manager. (line 61) +* BFD_RELOC_16_PLT_PCREL: howto manager. (line 57) +* BFD_RELOC_16_SECIDX: howto manager. (line 43) +* BFD_RELOC_23_PCREL_S2: howto manager. (line 101) +* BFD_RELOC_24: howto manager. (line 27) +* BFD_RELOC_24_PCREL: howto manager. (line 34) +* BFD_RELOC_24_PLT_PCREL: howto manager. (line 56) +* BFD_RELOC_26: howto manager. (line 26) +* BFD_RELOC_32: howto manager. (line 25) +* BFD_RELOC_32_BASEREL: howto manager. (line 89) +* BFD_RELOC_32_GOTOFF: howto manager. (line 48) +* BFD_RELOC_32_GOT_PCREL: howto manager. (line 45) +* BFD_RELOC_32_PCREL: howto manager. (line 33) +* BFD_RELOC_32_PCREL_S2: howto manager. (line 99) +* BFD_RELOC_32_PLTOFF: howto manager. (line 60) +* BFD_RELOC_32_PLT_PCREL: howto manager. (line 55) +* BFD_RELOC_32_SECREL: howto manager. (line 42) +* BFD_RELOC_386_COPY: howto manager. (line 523) +* BFD_RELOC_386_GLOB_DAT: howto manager. (line 524) +* BFD_RELOC_386_GOT32: howto manager. (line 521) +* BFD_RELOC_386_GOT32X: howto manager. (line 545) +* BFD_RELOC_386_GOTOFF: howto manager. (line 527) +* BFD_RELOC_386_GOTPC: howto manager. (line 528) +* BFD_RELOC_386_IRELATIVE: howto manager. (line 544) +* BFD_RELOC_386_JUMP_SLOT: howto manager. (line 525) +* BFD_RELOC_386_PLT32: howto manager. (line 522) +* BFD_RELOC_386_RELATIVE: howto manager. (line 526) +* BFD_RELOC_386_TLS_DESC: howto manager. (line 543) +* BFD_RELOC_386_TLS_DESC_CALL: howto manager. (line 542) +* BFD_RELOC_386_TLS_DTPMOD32: howto manager. (line 538) +* BFD_RELOC_386_TLS_DTPOFF32: howto manager. (line 539) +* BFD_RELOC_386_TLS_GD: howto manager. (line 533) +* BFD_RELOC_386_TLS_GOTDESC: howto manager. (line 541) +* BFD_RELOC_386_TLS_GOTIE: howto manager. (line 531) +* BFD_RELOC_386_TLS_IE: howto manager. (line 530) +* BFD_RELOC_386_TLS_IE_32: howto manager. (line 536) +* BFD_RELOC_386_TLS_LDM: howto manager. (line 534) +* BFD_RELOC_386_TLS_LDO_32: howto manager. (line 535) +* BFD_RELOC_386_TLS_LE: howto manager. (line 532) +* BFD_RELOC_386_TLS_LE_32: howto manager. (line 537) +* BFD_RELOC_386_TLS_TPOFF: howto manager. (line 529) +* BFD_RELOC_386_TLS_TPOFF32: howto manager. (line 540) +* BFD_RELOC_390_12: howto manager. (line 1962) +* BFD_RELOC_390_20: howto manager. (line 2043) +* BFD_RELOC_390_COPY: howto manager. (line 1968) +* BFD_RELOC_390_GLOB_DAT: howto manager. (line 1970) +* BFD_RELOC_390_GOT12: howto manager. (line 1964) +* BFD_RELOC_390_GOT16: howto manager. (line 1978) +* BFD_RELOC_390_GOT20: howto manager. (line 2044) +* BFD_RELOC_390_GOT64: howto manager. (line 1998) +* BFD_RELOC_390_GOTENT: howto manager. (line 2002) +* BFD_RELOC_390_GOTOFF64: howto manager. (line 2004) +* BFD_RELOC_390_GOTPC: howto manager. (line 1976) +* BFD_RELOC_390_GOTPCDBL: howto manager. (line 1996) +* BFD_RELOC_390_GOTPLT12: howto manager. (line 2006) +* BFD_RELOC_390_GOTPLT16: howto manager. (line 2008) +* BFD_RELOC_390_GOTPLT20: howto manager. (line 2045) +* BFD_RELOC_390_GOTPLT32: howto manager. (line 2010) +* BFD_RELOC_390_GOTPLT64: howto manager. (line 2012) +* BFD_RELOC_390_GOTPLTENT: howto manager. (line 2014) +* BFD_RELOC_390_IRELATIVE: howto manager. (line 2048) +* BFD_RELOC_390_JMP_SLOT: howto manager. (line 1972) +* BFD_RELOC_390_PC12DBL: howto manager. (line 1980) +* BFD_RELOC_390_PC16DBL: howto manager. (line 1984) +* BFD_RELOC_390_PC24DBL: howto manager. (line 1988) +* BFD_RELOC_390_PC32DBL: howto manager. (line 1992) +* BFD_RELOC_390_PLT12DBL: howto manager. (line 1982) +* BFD_RELOC_390_PLT16DBL: howto manager. (line 1986) +* BFD_RELOC_390_PLT24DBL: howto manager. (line 1990) +* BFD_RELOC_390_PLT32: howto manager. (line 1966) +* BFD_RELOC_390_PLT32DBL: howto manager. (line 1994) +* BFD_RELOC_390_PLT64: howto manager. (line 2000) +* BFD_RELOC_390_PLTOFF16: howto manager. (line 2016) +* BFD_RELOC_390_PLTOFF32: howto manager. (line 2018) +* BFD_RELOC_390_PLTOFF64: howto manager. (line 2020) +* BFD_RELOC_390_RELATIVE: howto manager. (line 1974) +* BFD_RELOC_390_TLS_DTPMOD: howto manager. (line 2039) +* BFD_RELOC_390_TLS_DTPOFF: howto manager. (line 2040) +* BFD_RELOC_390_TLS_GD32: howto manager. (line 2025) +* BFD_RELOC_390_TLS_GD64: howto manager. (line 2026) +* BFD_RELOC_390_TLS_GDCALL: howto manager. (line 2023) +* BFD_RELOC_390_TLS_GOTIE12: howto manager. (line 2027) +* BFD_RELOC_390_TLS_GOTIE20: howto manager. (line 2046) +* BFD_RELOC_390_TLS_GOTIE32: howto manager. (line 2028) +* BFD_RELOC_390_TLS_GOTIE64: howto manager. (line 2029) +* BFD_RELOC_390_TLS_IE32: howto manager. (line 2032) +* BFD_RELOC_390_TLS_IE64: howto manager. (line 2033) +* BFD_RELOC_390_TLS_IEENT: howto manager. (line 2034) +* BFD_RELOC_390_TLS_LDCALL: howto manager. (line 2024) +* BFD_RELOC_390_TLS_LDM32: howto manager. (line 2030) +* BFD_RELOC_390_TLS_LDM64: howto manager. (line 2031) +* BFD_RELOC_390_TLS_LDO32: howto manager. (line 2037) +* BFD_RELOC_390_TLS_LDO64: howto manager. (line 2038) +* BFD_RELOC_390_TLS_LE32: howto manager. (line 2035) +* BFD_RELOC_390_TLS_LE64: howto manager. (line 2036) +* BFD_RELOC_390_TLS_LOAD: howto manager. (line 2022) +* BFD_RELOC_390_TLS_TPOFF: howto manager. (line 2041) +* BFD_RELOC_64: howto manager. (line 24) +* BFD_RELOC_64_PCREL: howto manager. (line 32) +* BFD_RELOC_64_PLTOFF: howto manager. (line 59) +* BFD_RELOC_64_PLT_PCREL: howto manager. (line 54) +* BFD_RELOC_68K_GLOB_DAT: howto manager. (line 70) +* BFD_RELOC_68K_JMP_SLOT: howto manager. (line 71) +* BFD_RELOC_68K_RELATIVE: howto manager. (line 72) +* BFD_RELOC_68K_TLS_GD16: howto manager. (line 74) +* BFD_RELOC_68K_TLS_GD32: howto manager. (line 73) +* BFD_RELOC_68K_TLS_GD8: howto manager. (line 75) +* BFD_RELOC_68K_TLS_IE16: howto manager. (line 83) +* BFD_RELOC_68K_TLS_IE32: howto manager. (line 82) +* BFD_RELOC_68K_TLS_IE8: howto manager. (line 84) +* BFD_RELOC_68K_TLS_LDM16: howto manager. (line 77) +* BFD_RELOC_68K_TLS_LDM32: howto manager. (line 76) +* BFD_RELOC_68K_TLS_LDM8: howto manager. (line 78) +* BFD_RELOC_68K_TLS_LDO16: howto manager. (line 80) +* BFD_RELOC_68K_TLS_LDO32: howto manager. (line 79) +* BFD_RELOC_68K_TLS_LDO8: howto manager. (line 81) +* BFD_RELOC_68K_TLS_LE16: howto manager. (line 86) +* BFD_RELOC_68K_TLS_LE32: howto manager. (line 85) +* BFD_RELOC_68K_TLS_LE8: howto manager. (line 87) +* BFD_RELOC_8: howto manager. (line 30) +* BFD_RELOC_8_BASEREL: howto manager. (line 94) +* BFD_RELOC_8_FFnn: howto manager. (line 97) +* BFD_RELOC_8_GOTOFF: howto manager. (line 53) +* BFD_RELOC_8_GOT_PCREL: howto manager. (line 47) +* BFD_RELOC_8_PCREL: howto manager. (line 37) +* BFD_RELOC_8_PLTOFF: howto manager. (line 65) +* BFD_RELOC_8_PLT_PCREL: howto manager. (line 58) +* BFD_RELOC_AARCH64_16: howto manager. (line 2850) +* BFD_RELOC_AARCH64_16_PCREL: howto manager. (line 2856) +* BFD_RELOC_AARCH64_32: howto manager. (line 2849) +* BFD_RELOC_AARCH64_32_PCREL: howto manager. (line 2855) +* BFD_RELOC_AARCH64_64: howto manager. (line 2848) +* BFD_RELOC_AARCH64_64_PCREL: howto manager. (line 2854) +* BFD_RELOC_AARCH64_ADD_LO12: howto manager. (line 2929) +* BFD_RELOC_AARCH64_ADR_GOT_PAGE: howto manager. (line 2975) +* BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL: howto manager. (line 2925) +* BFD_RELOC_AARCH64_ADR_HI21_PCREL: howto manager. (line 2922) +* BFD_RELOC_AARCH64_ADR_LO21_PCREL: howto manager. (line 2919) +* BFD_RELOC_AARCH64_BRANCH19: howto manager. (line 2941) +* BFD_RELOC_AARCH64_CALL26: howto manager. (line 2949) +* BFD_RELOC_AARCH64_COPY: howto manager. (line 3134) +* BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP: howto manager. (line 3152) +* BFD_RELOC_AARCH64_GLOB_DAT: howto manager. (line 3135) +* BFD_RELOC_AARCH64_GOT_LD_PREL19: howto manager. (line 2969) +* BFD_RELOC_AARCH64_IRELATIVE: howto manager. (line 3144) +* BFD_RELOC_AARCH64_JUMP26: howto manager. (line 2945) +* BFD_RELOC_AARCH64_JUMP_SLOT: howto manager. (line 3136) +* BFD_RELOC_AARCH64_LD32_GOTPAGE_LO14: howto manager. (line 2996) +* BFD_RELOC_AARCH64_LD32_GOT_LO12_NC: howto manager. (line 2983) +* BFD_RELOC_AARCH64_LD64_GOTOFF_LO15: howto manager. (line 2993) +* BFD_RELOC_AARCH64_LD64_GOTPAGE_LO15: howto manager. (line 2999) +* BFD_RELOC_AARCH64_LD64_GOT_LO12_NC: howto manager. (line 2979) +* BFD_RELOC_AARCH64_LDST128_LO12: howto manager. (line 2965) +* BFD_RELOC_AARCH64_LDST16_LO12: howto manager. (line 2953) +* BFD_RELOC_AARCH64_LDST32_LO12: howto manager. (line 2957) +* BFD_RELOC_AARCH64_LDST64_LO12: howto manager. (line 2961) +* BFD_RELOC_AARCH64_LDST8_LO12: howto manager. (line 2933) +* BFD_RELOC_AARCH64_LDST_LO12: howto manager. (line 3155) +* BFD_RELOC_AARCH64_LD_GOT_LO12_NC: howto manager. (line 3173) +* BFD_RELOC_AARCH64_LD_LO19_PCREL: howto manager. (line 2915) +* BFD_RELOC_AARCH64_MOVW_G0: howto manager. (line 2859) +* BFD_RELOC_AARCH64_MOVW_G0_NC: howto manager. (line 2862) +* BFD_RELOC_AARCH64_MOVW_G0_S: howto manager. (line 2880) +* BFD_RELOC_AARCH64_MOVW_G1: howto manager. (line 2865) +* BFD_RELOC_AARCH64_MOVW_G1_NC: howto manager. (line 2868) +* BFD_RELOC_AARCH64_MOVW_G1_S: howto manager. (line 2884) +* BFD_RELOC_AARCH64_MOVW_G2: howto manager. (line 2871) +* BFD_RELOC_AARCH64_MOVW_G2_NC: howto manager. (line 2874) +* BFD_RELOC_AARCH64_MOVW_G2_S: howto manager. (line 2888) +* BFD_RELOC_AARCH64_MOVW_G3: howto manager. (line 2877) +* BFD_RELOC_AARCH64_MOVW_GOTOFF_G0_NC: howto manager. (line 2987) +* BFD_RELOC_AARCH64_MOVW_GOTOFF_G1: howto manager. (line 2990) +* BFD_RELOC_AARCH64_MOVW_PREL_G0: howto manager. (line 2892) +* BFD_RELOC_AARCH64_MOVW_PREL_G0_NC: howto manager. (line 2896) +* BFD_RELOC_AARCH64_MOVW_PREL_G1: howto manager. (line 2900) +* BFD_RELOC_AARCH64_MOVW_PREL_G1_NC: howto manager. (line 2903) +* BFD_RELOC_AARCH64_MOVW_PREL_G2: howto manager. (line 2906) +* BFD_RELOC_AARCH64_MOVW_PREL_G2_NC: howto manager. (line 2909) +* BFD_RELOC_AARCH64_MOVW_PREL_G3: howto manager. (line 2912) +* BFD_RELOC_AARCH64_NONE: howto manager. (line 2846) +* BFD_RELOC_AARCH64_NULL: howto manager. (line 2844) +* BFD_RELOC_AARCH64_RELATIVE: howto manager. (line 3137) +* BFD_RELOC_AARCH64_RELOC_END: howto manager. (line 3146) +* BFD_RELOC_AARCH64_RELOC_START: howto manager. (line 2839) +* BFD_RELOC_AARCH64_TLSDESC: howto manager. (line 3142) +* BFD_RELOC_AARCH64_TLSDESC_ADD: howto manager. (line 3131) +* BFD_RELOC_AARCH64_TLSDESC_ADD_LO12: howto manager. (line 3127) +* BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21: howto manager. (line 3124) +* BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21: howto manager. (line 3123) +* BFD_RELOC_AARCH64_TLSDESC_CALL: howto manager. (line 3132) +* BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC: howto manager. (line 3126) +* BFD_RELOC_AARCH64_TLSDESC_LD64_LO12: howto manager. (line 3125) +* BFD_RELOC_AARCH64_TLSDESC_LDR: howto manager. (line 3130) +* BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC: howto manager. (line 3179) +* BFD_RELOC_AARCH64_TLSDESC_LD_PREL19: howto manager. (line 3122) +* BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC: howto manager. (line 3129) +* BFD_RELOC_AARCH64_TLSDESC_OFF_G1: howto manager. (line 3128) +* BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC: howto manager. (line 3009) +* BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21: howto manager. (line 3002) +* BFD_RELOC_AARCH64_TLSGD_ADR_PREL21: howto manager. (line 3007) +* BFD_RELOC_AARCH64_TLSGD_MOVW_G0_NC: howto manager. (line 3013) +* BFD_RELOC_AARCH64_TLSGD_MOVW_G1: howto manager. (line 3015) +* BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21: howto manager. + (line 3017) +* BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC: howto manager. + (line 3021) +* BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC: howto manager. + (line 3019) +* BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC: howto manager. + (line 3176) +* BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19: howto manager. (line 3023) +* BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC: howto manager. + (line 3025) +* BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1: howto manager. (line 3027) +* BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_HI12: howto manager. (line 3029) +* BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12: howto manager. (line 3031) +* BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12_NC: howto manager. (line 3033) +* BFD_RELOC_AARCH64_TLSLD_ADD_LO12_NC: howto manager. (line 3036) +* BFD_RELOC_AARCH64_TLSLD_ADR_PAGE21: howto manager. (line 3040) +* BFD_RELOC_AARCH64_TLSLD_ADR_PREL21: howto manager. (line 3043) +* BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12: howto manager. (line 3046) +* BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12_NC: howto manager. + (line 3049) +* BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12: howto manager. (line 3052) +* BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12_NC: howto manager. + (line 3055) +* BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12: howto manager. (line 3058) +* BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12_NC: howto manager. + (line 3061) +* BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12: howto manager. (line 3064) +* BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12_NC: howto manager. + (line 3067) +* BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12: howto manager. (line 3159) +* BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12_NC: howto manager. + (line 3163) +* BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0: howto manager. (line 3070) +* BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0_NC: howto manager. (line 3072) +* BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1: howto manager. (line 3075) +* BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1_NC: howto manager. (line 3077) +* BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G2: howto manager. (line 3080) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12: howto manager. (line 3092) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12: howto manager. (line 3094) +* BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC: howto manager. (line 3096) +* BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12: howto manager. (line 3098) +* BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12_NC: howto manager. + (line 3101) +* BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12: howto manager. (line 3104) +* BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12_NC: howto manager. + (line 3107) +* BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12: howto manager. (line 3110) +* BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12_NC: howto manager. + (line 3113) +* BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12: howto manager. (line 3116) +* BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12_NC: howto manager. + (line 3119) +* BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12: howto manager. (line 3166) +* BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12_NC: howto manager. (line 3170) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0: howto manager. (line 3088) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC: howto manager. (line 3090) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1: howto manager. (line 3084) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC: howto manager. (line 3086) +* BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2: howto manager. (line 3082) +* BFD_RELOC_AARCH64_TLS_DTPMOD: howto manager. (line 3139) +* BFD_RELOC_AARCH64_TLS_DTPREL: howto manager. (line 3140) +* BFD_RELOC_AARCH64_TLS_TPREL: howto manager. (line 3141) +* BFD_RELOC_AARCH64_TSTBR14: howto manager. (line 2937) +* BFD_RELOC_AC_SECTOFF_S9: howto manager. (line 1085) +* BFD_RELOC_AC_SECTOFF_S9_1: howto manager. (line 1086) +* BFD_RELOC_AC_SECTOFF_S9_2: howto manager. (line 1087) +* BFD_RELOC_AC_SECTOFF_U8: howto manager. (line 1082) +* BFD_RELOC_AC_SECTOFF_U8_1: howto manager. (line 1083) +* BFD_RELOC_AC_SECTOFF_U8_2: howto manager. (line 1084) +* BFD_RELOC_ALPHA_BOH: howto manager. (line 288) +* BFD_RELOC_ALPHA_BRSGP: howto manager. (line 275) +* BFD_RELOC_ALPHA_BSR: howto manager. (line 282) +* BFD_RELOC_ALPHA_CODEADDR: howto manager. (line 268) +* BFD_RELOC_ALPHA_DTPMOD64: howto manager. (line 293) +* BFD_RELOC_ALPHA_DTPREL16: howto manager. (line 298) +* BFD_RELOC_ALPHA_DTPREL64: howto manager. (line 295) +* BFD_RELOC_ALPHA_DTPREL_HI16: howto manager. (line 296) +* BFD_RELOC_ALPHA_DTPREL_LO16: howto manager. (line 297) +* BFD_RELOC_ALPHA_ELF_LITERAL: howto manager. (line 236) +* BFD_RELOC_ALPHA_GOTDTPREL16: howto manager. (line 294) +* BFD_RELOC_ALPHA_GOTTPREL16: howto manager. (line 299) +* BFD_RELOC_ALPHA_GPDISP: howto manager. (line 231) +* BFD_RELOC_ALPHA_GPDISP_HI16: howto manager. (line 219) +* BFD_RELOC_ALPHA_GPDISP_LO16: howto manager. (line 226) +* BFD_RELOC_ALPHA_GPREL_HI16: howto manager. (line 271) +* BFD_RELOC_ALPHA_GPREL_LO16: howto manager. (line 272) +* BFD_RELOC_ALPHA_HINT: howto manager. (line 261) +* BFD_RELOC_ALPHA_LDA: howto manager. (line 285) +* BFD_RELOC_ALPHA_LINKAGE: howto manager. (line 265) +* BFD_RELOC_ALPHA_LITERAL: howto manager. (line 235) +* BFD_RELOC_ALPHA_LITUSE: howto manager. (line 237) +* BFD_RELOC_ALPHA_NOP: howto manager. (line 279) +* BFD_RELOC_ALPHA_TLSGD: howto manager. (line 291) +* BFD_RELOC_ALPHA_TLSLDM: howto manager. (line 292) +* BFD_RELOC_ALPHA_TPREL16: howto manager. (line 303) +* BFD_RELOC_ALPHA_TPREL64: howto manager. (line 300) +* BFD_RELOC_ALPHA_TPREL_HI16: howto manager. (line 301) +* BFD_RELOC_ALPHA_TPREL_LO16: howto manager. (line 302) +* BFD_RELOC_ARC_16: howto manager. (line 1054) +* BFD_RELOC_ARC_24: howto manager. (line 1055) +* BFD_RELOC_ARC_32: howto manager. (line 1056) +* BFD_RELOC_ARC_32_ME: howto manager. (line 1076) +* BFD_RELOC_ARC_32_ME_S: howto manager. (line 1077) +* BFD_RELOC_ARC_32_PCREL: howto manager. (line 1094) +* BFD_RELOC_ARC_8: howto manager. (line 1053) +* BFD_RELOC_ARC_COPY: howto manager. (line 1099) +* BFD_RELOC_ARC_GLOB_DAT: howto manager. (line 1100) +* BFD_RELOC_ARC_GOT32: howto manager. (line 1096) +* BFD_RELOC_ARC_GOTOFF: howto manager. (line 1103) +* BFD_RELOC_ARC_GOTPC: howto manager. (line 1104) +* BFD_RELOC_ARC_GOTPC32: howto manager. (line 1097) +* BFD_RELOC_ARC_JLI_SECTOFF: howto manager. (line 1120) +* BFD_RELOC_ARC_JMP_SLOT: howto manager. (line 1101) +* BFD_RELOC_ARC_N16: howto manager. (line 1058) +* BFD_RELOC_ARC_N24: howto manager. (line 1059) +* BFD_RELOC_ARC_N32: howto manager. (line 1060) +* BFD_RELOC_ARC_N32_ME: howto manager. (line 1078) +* BFD_RELOC_ARC_N8: howto manager. (line 1057) +* BFD_RELOC_ARC_NONE: howto manager. (line 1052) +* BFD_RELOC_ARC_NPS_CMEM16: howto manager. (line 1119) +* BFD_RELOC_ARC_PC32: howto manager. (line 1095) +* BFD_RELOC_ARC_PLT32: howto manager. (line 1098) +* BFD_RELOC_ARC_RELATIVE: howto manager. (line 1102) +* BFD_RELOC_ARC_S13_PCREL: howto manager. (line 1074) +* BFD_RELOC_ARC_S21H_PCREL: howto manager. (line 1063) +* BFD_RELOC_ARC_S21H_PCREL_PLT: howto manager. (line 1118) +* BFD_RELOC_ARC_S21W_PCREL: howto manager. (line 1064) +* BFD_RELOC_ARC_S21W_PCREL_PLT: howto manager. (line 1105) +* BFD_RELOC_ARC_S25H_PCREL: howto manager. (line 1065) +* BFD_RELOC_ARC_S25H_PCREL_PLT: howto manager. (line 1106) +* BFD_RELOC_ARC_S25W_PCREL: howto manager. (line 1066) +* BFD_RELOC_ARC_S25W_PCREL_PLT: howto manager. (line 1117) +* BFD_RELOC_ARC_SDA: howto manager. (line 1061) +* BFD_RELOC_ARC_SDA16_LD: howto manager. (line 1071) +* BFD_RELOC_ARC_SDA16_LD1: howto manager. (line 1072) +* BFD_RELOC_ARC_SDA16_LD2: howto manager. (line 1073) +* BFD_RELOC_ARC_SDA16_ST2: howto manager. (line 1093) +* BFD_RELOC_ARC_SDA32: howto manager. (line 1067) +* BFD_RELOC_ARC_SDA32_ME: howto manager. (line 1080) +* BFD_RELOC_ARC_SDA_12: howto manager. (line 1092) +* BFD_RELOC_ARC_SDA_LDST: howto manager. (line 1068) +* BFD_RELOC_ARC_SDA_LDST1: howto manager. (line 1069) +* BFD_RELOC_ARC_SDA_LDST2: howto manager. (line 1070) +* BFD_RELOC_ARC_SECTOFF: howto manager. (line 1062) +* BFD_RELOC_ARC_SECTOFF_1: howto manager. (line 1090) +* BFD_RELOC_ARC_SECTOFF_2: howto manager. (line 1091) +* BFD_RELOC_ARC_SECTOFF_ME: howto manager. (line 1079) +* BFD_RELOC_ARC_SECTOFF_ME_1: howto manager. (line 1088) +* BFD_RELOC_ARC_SECTOFF_ME_2: howto manager. (line 1089) +* BFD_RELOC_ARC_TLS_DTPMOD: howto manager. (line 1107) +* BFD_RELOC_ARC_TLS_DTPOFF: howto manager. (line 1113) +* BFD_RELOC_ARC_TLS_DTPOFF_S9: howto manager. (line 1114) +* BFD_RELOC_ARC_TLS_GD_CALL: howto manager. (line 1111) +* BFD_RELOC_ARC_TLS_GD_GOT: howto manager. (line 1109) +* BFD_RELOC_ARC_TLS_GD_LD: howto manager. (line 1110) +* BFD_RELOC_ARC_TLS_IE_GOT: howto manager. (line 1112) +* BFD_RELOC_ARC_TLS_LE_32: howto manager. (line 1116) +* BFD_RELOC_ARC_TLS_LE_S9: howto manager. (line 1115) +* BFD_RELOC_ARC_TLS_TPOFF: howto manager. (line 1108) +* BFD_RELOC_ARC_W: howto manager. (line 1075) +* BFD_RELOC_ARC_W_ME: howto manager. (line 1081) +* BFD_RELOC_ARM_ADRL_IMMEDIATE: howto manager. (line 925) +* BFD_RELOC_ARM_ADR_IMM: howto manager. (line 940) +* BFD_RELOC_ARM_ALU_PC_G0: howto manager. (line 887) +* BFD_RELOC_ARM_ALU_PC_G0_NC: howto manager. (line 886) +* BFD_RELOC_ARM_ALU_PC_G1: howto manager. (line 889) +* BFD_RELOC_ARM_ALU_PC_G1_NC: howto manager. (line 888) +* BFD_RELOC_ARM_ALU_PC_G2: howto manager. (line 890) +* BFD_RELOC_ARM_ALU_SB_G0: howto manager. (line 901) +* BFD_RELOC_ARM_ALU_SB_G0_NC: howto manager. (line 900) +* BFD_RELOC_ARM_ALU_SB_G1: howto manager. (line 903) +* BFD_RELOC_ARM_ALU_SB_G1_NC: howto manager. (line 902) +* BFD_RELOC_ARM_ALU_SB_G2: howto manager. (line 904) +* BFD_RELOC_ARM_CP_OFF_IMM: howto manager. (line 935) +* BFD_RELOC_ARM_CP_OFF_IMM_S2: howto manager. (line 936) +* BFD_RELOC_ARM_FUNCDESC: howto manager. (line 856) +* BFD_RELOC_ARM_FUNCDESC_VALUE: howto manager. (line 857) +* BFD_RELOC_ARM_GLOB_DAT: howto manager. (line 863) +* BFD_RELOC_ARM_GOT32: howto manager. (line 864) +* BFD_RELOC_ARM_GOTFUNCDESC: howto manager. (line 854) +* BFD_RELOC_ARM_GOTOFF: howto manager. (line 867) +* BFD_RELOC_ARM_GOTOFFFUNCDESC: howto manager. (line 855) +* BFD_RELOC_ARM_GOTPC: howto manager. (line 868) +* BFD_RELOC_ARM_GOT_PREL: howto manager. (line 869) +* BFD_RELOC_ARM_HVC: howto manager. (line 932) +* BFD_RELOC_ARM_HWLITERAL: howto manager. (line 947) +* BFD_RELOC_ARM_IMMEDIATE: howto manager. (line 924) +* BFD_RELOC_ARM_IN_POOL: howto manager. (line 943) +* BFD_RELOC_ARM_IRELATIVE: howto manager. (line 917) +* BFD_RELOC_ARM_JUMP_SLOT: howto manager. (line 862) +* BFD_RELOC_ARM_LDC_PC_G0: howto manager. (line 897) +* BFD_RELOC_ARM_LDC_PC_G1: howto manager. (line 898) +* BFD_RELOC_ARM_LDC_PC_G2: howto manager. (line 899) +* BFD_RELOC_ARM_LDC_SB_G0: howto manager. (line 911) +* BFD_RELOC_ARM_LDC_SB_G1: howto manager. (line 912) +* BFD_RELOC_ARM_LDC_SB_G2: howto manager. (line 913) +* BFD_RELOC_ARM_LDRS_PC_G0: howto manager. (line 894) +* BFD_RELOC_ARM_LDRS_PC_G1: howto manager. (line 895) +* BFD_RELOC_ARM_LDRS_PC_G2: howto manager. (line 896) +* BFD_RELOC_ARM_LDRS_SB_G0: howto manager. (line 908) +* BFD_RELOC_ARM_LDRS_SB_G1: howto manager. (line 909) +* BFD_RELOC_ARM_LDRS_SB_G2: howto manager. (line 910) +* BFD_RELOC_ARM_LDR_IMM: howto manager. (line 941) +* BFD_RELOC_ARM_LDR_PC_G0: howto manager. (line 891) +* BFD_RELOC_ARM_LDR_PC_G1: howto manager. (line 892) +* BFD_RELOC_ARM_LDR_PC_G2: howto manager. (line 893) +* BFD_RELOC_ARM_LDR_SB_G0: howto manager. (line 905) +* BFD_RELOC_ARM_LDR_SB_G1: howto manager. (line 906) +* BFD_RELOC_ARM_LDR_SB_G2: howto manager. (line 907) +* BFD_RELOC_ARM_LITERAL: howto manager. (line 942) +* BFD_RELOC_ARM_MOVT: howto manager. (line 846) +* BFD_RELOC_ARM_MOVT_PCREL: howto manager. (line 848) +* BFD_RELOC_ARM_MOVW: howto manager. (line 845) +* BFD_RELOC_ARM_MOVW_PCREL: howto manager. (line 847) +* BFD_RELOC_ARM_MULTI: howto manager. (line 934) +* BFD_RELOC_ARM_OFFSET_IMM: howto manager. (line 826) +* BFD_RELOC_ARM_OFFSET_IMM8: howto manager. (line 944) +* BFD_RELOC_ARM_PCREL_BLX: howto manager. (line 790) +* BFD_RELOC_ARM_PCREL_BRANCH: howto manager. (line 787) +* BFD_RELOC_ARM_PCREL_CALL: howto manager. (line 798) +* BFD_RELOC_ARM_PCREL_JUMP: howto manager. (line 801) +* BFD_RELOC_ARM_PLT32: howto manager. (line 865) +* BFD_RELOC_ARM_PREL31: howto manager. (line 843) +* BFD_RELOC_ARM_RELATIVE: howto manager. (line 866) +* BFD_RELOC_ARM_ROSEGREL32: howto manager. (line 835) +* BFD_RELOC_ARM_SBREL32: howto manager. (line 837) +* BFD_RELOC_ARM_SHIFT_IMM: howto manager. (line 930) +* BFD_RELOC_ARM_SMC: howto manager. (line 931) +* BFD_RELOC_ARM_SWI: howto manager. (line 933) +* BFD_RELOC_ARM_T32_ADD_IMM: howto manager. (line 927) +* BFD_RELOC_ARM_T32_ADD_PC12: howto manager. (line 929) +* BFD_RELOC_ARM_T32_CP_OFF_IMM: howto manager. (line 937) +* BFD_RELOC_ARM_T32_CP_OFF_IMM_S2: howto manager. (line 938) +* BFD_RELOC_ARM_T32_IMM12: howto manager. (line 928) +* BFD_RELOC_ARM_T32_IMMEDIATE: howto manager. (line 926) +* BFD_RELOC_ARM_T32_OFFSET_IMM: howto manager. (line 946) +* BFD_RELOC_ARM_T32_OFFSET_U8: howto manager. (line 945) +* BFD_RELOC_ARM_T32_VLDR_VSTR_OFF_IMM: howto manager. (line 939) +* BFD_RELOC_ARM_TARGET1: howto manager. (line 832) +* BFD_RELOC_ARM_TARGET2: howto manager. (line 839) +* BFD_RELOC_ARM_THM_TLS_CALL: howto manager. (line 881) +* BFD_RELOC_ARM_THM_TLS_DESCSEQ: howto manager. (line 883) +* BFD_RELOC_ARM_THUMB_ADD: howto manager. (line 948) +* BFD_RELOC_ARM_THUMB_ALU_ABS_G0_NC: howto manager. (line 919) +* BFD_RELOC_ARM_THUMB_ALU_ABS_G1_NC: howto manager. (line 920) +* BFD_RELOC_ARM_THUMB_ALU_ABS_G2_NC: howto manager. (line 921) +* BFD_RELOC_ARM_THUMB_ALU_ABS_G3_NC: howto manager. (line 922) +* BFD_RELOC_ARM_THUMB_BF13: howto manager. (line 809) +* BFD_RELOC_ARM_THUMB_BF17: howto manager. (line 807) +* BFD_RELOC_ARM_THUMB_BF19: howto manager. (line 811) +* BFD_RELOC_ARM_THUMB_IMM: howto manager. (line 949) +* BFD_RELOC_ARM_THUMB_LOOP12: howto manager. (line 813) +* BFD_RELOC_ARM_THUMB_MOVT: howto manager. (line 850) +* BFD_RELOC_ARM_THUMB_MOVT_PCREL: howto manager. (line 852) +* BFD_RELOC_ARM_THUMB_MOVW: howto manager. (line 849) +* BFD_RELOC_ARM_THUMB_MOVW_PCREL: howto manager. (line 851) +* BFD_RELOC_ARM_THUMB_OFFSET: howto manager. (line 829) +* BFD_RELOC_ARM_THUMB_SHIFT: howto manager. (line 950) +* BFD_RELOC_ARM_TLS_CALL: howto manager. (line 880) +* BFD_RELOC_ARM_TLS_DESC: howto manager. (line 884) +* BFD_RELOC_ARM_TLS_DESCSEQ: howto manager. (line 882) +* BFD_RELOC_ARM_TLS_DTPMOD32: howto manager. (line 875) +* BFD_RELOC_ARM_TLS_DTPOFF32: howto manager. (line 874) +* BFD_RELOC_ARM_TLS_GD32: howto manager. (line 871) +* BFD_RELOC_ARM_TLS_GD32_FDPIC: howto manager. (line 858) +* BFD_RELOC_ARM_TLS_GOTDESC: howto manager. (line 879) +* BFD_RELOC_ARM_TLS_IE32: howto manager. (line 877) +* BFD_RELOC_ARM_TLS_IE32_FDPIC: howto manager. (line 860) +* BFD_RELOC_ARM_TLS_LDM32: howto manager. (line 873) +* BFD_RELOC_ARM_TLS_LDM32_FDPIC: howto manager. (line 859) +* BFD_RELOC_ARM_TLS_LDO32: howto manager. (line 872) +* BFD_RELOC_ARM_TLS_LE32: howto manager. (line 878) +* BFD_RELOC_ARM_TLS_TPOFF32: howto manager. (line 876) +* BFD_RELOC_ARM_V4BX: howto manager. (line 915) +* BFD_RELOC_AVR_13_PCREL: howto manager. (line 1745) +* BFD_RELOC_AVR_16_PM: howto manager. (line 1748) +* BFD_RELOC_AVR_6: howto manager. (line 1816) +* BFD_RELOC_AVR_6_ADIW: howto manager. (line 1819) +* BFD_RELOC_AVR_7_PCREL: howto manager. (line 1742) +* BFD_RELOC_AVR_8_HI: howto manager. (line 1825) +* BFD_RELOC_AVR_8_HLO: howto manager. (line 1828) +* BFD_RELOC_AVR_8_LO: howto manager. (line 1822) +* BFD_RELOC_AVR_CALL: howto manager. (line 1810) +* BFD_RELOC_AVR_DIFF16: howto manager. (line 1832) +* BFD_RELOC_AVR_DIFF32: howto manager. (line 1833) +* BFD_RELOC_AVR_DIFF8: howto manager. (line 1831) +* BFD_RELOC_AVR_HH8_LDI: howto manager. (line 1757) +* BFD_RELOC_AVR_HH8_LDI_NEG: howto manager. (line 1772) +* BFD_RELOC_AVR_HH8_LDI_PM: howto manager. (line 1795) +* BFD_RELOC_AVR_HH8_LDI_PM_NEG: howto manager. (line 1806) +* BFD_RELOC_AVR_HI8_LDI: howto manager. (line 1754) +* BFD_RELOC_AVR_HI8_LDI_GS: howto manager. (line 1790) +* BFD_RELOC_AVR_HI8_LDI_NEG: howto manager. (line 1768) +* BFD_RELOC_AVR_HI8_LDI_PM: howto manager. (line 1787) +* BFD_RELOC_AVR_HI8_LDI_PM_NEG: howto manager. (line 1802) +* BFD_RELOC_AVR_LDI: howto manager. (line 1813) +* BFD_RELOC_AVR_LDS_STS_16: howto manager. (line 1840) +* BFD_RELOC_AVR_LO8_LDI: howto manager. (line 1751) +* BFD_RELOC_AVR_LO8_LDI_GS: howto manager. (line 1782) +* BFD_RELOC_AVR_LO8_LDI_NEG: howto manager. (line 1764) +* BFD_RELOC_AVR_LO8_LDI_PM: howto manager. (line 1779) +* BFD_RELOC_AVR_LO8_LDI_PM_NEG: howto manager. (line 1799) +* BFD_RELOC_AVR_MS8_LDI: howto manager. (line 1761) +* BFD_RELOC_AVR_MS8_LDI_NEG: howto manager. (line 1776) +* BFD_RELOC_AVR_PORT5: howto manager. (line 1846) +* BFD_RELOC_AVR_PORT6: howto manager. (line 1843) +* BFD_RELOC_BFIN_10_PCREL: howto manager. (line 1132) +* BFD_RELOC_BFIN_11_PCREL: howto manager. (line 1134) +* BFD_RELOC_BFIN_12_PCREL_JUMP: howto manager. (line 1136) +* BFD_RELOC_BFIN_12_PCREL_JUMP_S: howto manager. (line 1138) +* BFD_RELOC_BFIN_16_HIGH: howto manager. (line 1124) +* BFD_RELOC_BFIN_16_IMM: howto manager. (line 1122) +* BFD_RELOC_BFIN_16_LOW: howto manager. (line 1130) +* BFD_RELOC_BFIN_24_PCREL_CALL_X: howto manager. (line 1140) +* BFD_RELOC_BFIN_24_PCREL_JUMP_L: howto manager. (line 1142) +* BFD_RELOC_BFIN_4_PCREL: howto manager. (line 1126) +* BFD_RELOC_BFIN_5_PCREL: howto manager. (line 1128) +* BFD_RELOC_BFIN_FUNCDESC: howto manager. (line 1147) +* BFD_RELOC_BFIN_FUNCDESC_GOT17M4: howto manager. (line 1148) +* BFD_RELOC_BFIN_FUNCDESC_GOTHI: howto manager. (line 1149) +* BFD_RELOC_BFIN_FUNCDESC_GOTLO: howto manager. (line 1150) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4: howto manager. (line 1152) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI: howto manager. (line 1153) +* BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO: howto manager. (line 1154) +* BFD_RELOC_BFIN_FUNCDESC_VALUE: howto manager. (line 1151) +* BFD_RELOC_BFIN_GOT: howto manager. (line 1159) +* BFD_RELOC_BFIN_GOT17M4: howto manager. (line 1144) +* BFD_RELOC_BFIN_GOTHI: howto manager. (line 1145) +* BFD_RELOC_BFIN_GOTLO: howto manager. (line 1146) +* BFD_RELOC_BFIN_GOTOFF17M4: howto manager. (line 1155) +* BFD_RELOC_BFIN_GOTOFFHI: howto manager. (line 1156) +* BFD_RELOC_BFIN_GOTOFFLO: howto manager. (line 1157) +* BFD_RELOC_BFIN_PLTPC: howto manager. (line 1161) +* BFD_RELOC_BPF_64: howto manager. (line 3372) +* BFD_RELOC_BPF_DISP16: howto manager. (line 3375) +* BFD_RELOC_BPF_DISP32: howto manager. (line 3373) +* BFD_RELOC_BPF_DISPCALL32: howto manager. (line 3374) +* BFD_RELOC_C6000_ABS_H16: howto manager. (line 1587) +* BFD_RELOC_C6000_ABS_L16: howto manager. (line 1586) +* BFD_RELOC_C6000_ABS_S16: howto manager. (line 1585) +* BFD_RELOC_C6000_ALIGN: howto manager. (line 1608) +* BFD_RELOC_C6000_COPY: howto manager. (line 1603) +* BFD_RELOC_C6000_DSBT_INDEX: howto manager. (line 1601) +* BFD_RELOC_C6000_EHTYPE: howto manager. (line 1605) +* BFD_RELOC_C6000_FPHEAD: howto manager. (line 1609) +* BFD_RELOC_C6000_JUMP_SLOT: howto manager. (line 1604) +* BFD_RELOC_C6000_NOCMP: howto manager. (line 1610) +* BFD_RELOC_C6000_PCR_H16: howto manager. (line 1606) +* BFD_RELOC_C6000_PCR_L16: howto manager. (line 1607) +* BFD_RELOC_C6000_PCR_S10: howto manager. (line 1583) +* BFD_RELOC_C6000_PCR_S12: howto manager. (line 1582) +* BFD_RELOC_C6000_PCR_S21: howto manager. (line 1581) +* BFD_RELOC_C6000_PCR_S7: howto manager. (line 1584) +* BFD_RELOC_C6000_PREL31: howto manager. (line 1602) +* BFD_RELOC_C6000_SBR_GOT_H16_W: howto manager. (line 1600) +* BFD_RELOC_C6000_SBR_GOT_L16_W: howto manager. (line 1599) +* BFD_RELOC_C6000_SBR_GOT_U15_W: howto manager. (line 1598) +* BFD_RELOC_C6000_SBR_H16_B: howto manager. (line 1595) +* BFD_RELOC_C6000_SBR_H16_H: howto manager. (line 1596) +* BFD_RELOC_C6000_SBR_H16_W: howto manager. (line 1597) +* BFD_RELOC_C6000_SBR_L16_B: howto manager. (line 1592) +* BFD_RELOC_C6000_SBR_L16_H: howto manager. (line 1593) +* BFD_RELOC_C6000_SBR_L16_W: howto manager. (line 1594) +* BFD_RELOC_C6000_SBR_S16: howto manager. (line 1591) +* BFD_RELOC_C6000_SBR_U15_B: howto manager. (line 1588) +* BFD_RELOC_C6000_SBR_U15_H: howto manager. (line 1589) +* BFD_RELOC_C6000_SBR_U15_W: howto manager. (line 1590) +* BFD_RELOC_CKCORE_ADDR32: howto manager. (line 3412) +* BFD_RELOC_CKCORE_ADDRGOT: howto manager. (line 3428) +* BFD_RELOC_CKCORE_ADDRGOT_HI16: howto manager. (line 3447) +* BFD_RELOC_CKCORE_ADDRGOT_LO16: howto manager. (line 3448) +* BFD_RELOC_CKCORE_ADDRPLT: howto manager. (line 3429) +* BFD_RELOC_CKCORE_ADDRPLT_HI16: howto manager. (line 3449) +* BFD_RELOC_CKCORE_ADDRPLT_LO16: howto manager. (line 3450) +* BFD_RELOC_CKCORE_ADDR_HI16: howto manager. (line 3435) +* BFD_RELOC_CKCORE_ADDR_LO16: howto manager. (line 3436) +* BFD_RELOC_CKCORE_CALLGRAPH: howto manager. (line 3472) +* BFD_RELOC_CKCORE_COPY: howto manager. (line 3421) +* BFD_RELOC_CKCORE_DOFFSET_IMM18: howto manager. (line 3455) +* BFD_RELOC_CKCORE_DOFFSET_IMM18BY2: howto manager. (line 3456) +* BFD_RELOC_CKCORE_DOFFSET_IMM18BY4: howto manager. (line 3457) +* BFD_RELOC_CKCORE_DOFFSET_LO16: howto manager. (line 3453) +* BFD_RELOC_CKCORE_GLOB_DAT: howto manager. (line 3422) +* BFD_RELOC_CKCORE_GNU_VTENTRY: howto manager. (line 3419) +* BFD_RELOC_CKCORE_GNU_VTINHERIT: howto manager. (line 3418) +* BFD_RELOC_CKCORE_GOT12: howto manager. (line 3441) +* BFD_RELOC_CKCORE_GOT32: howto manager. (line 3426) +* BFD_RELOC_CKCORE_GOTOFF: howto manager. (line 3424) +* BFD_RELOC_CKCORE_GOTOFF_HI16: howto manager. (line 3439) +* BFD_RELOC_CKCORE_GOTOFF_IMM18: howto manager. (line 3458) +* BFD_RELOC_CKCORE_GOTOFF_LO16: howto manager. (line 3440) +* BFD_RELOC_CKCORE_GOTPC: howto manager. (line 3425) +* BFD_RELOC_CKCORE_GOTPC_HI16: howto manager. (line 3437) +* BFD_RELOC_CKCORE_GOTPC_LO16: howto manager. (line 3438) +* BFD_RELOC_CKCORE_GOT_HI16: howto manager. (line 3442) +* BFD_RELOC_CKCORE_GOT_IMM18BY4: howto manager. (line 3459) +* BFD_RELOC_CKCORE_GOT_LO16: howto manager. (line 3443) +* BFD_RELOC_CKCORE_IRELATIVE: howto manager. (line 3473) +* BFD_RELOC_CKCORE_JUMP_SLOT: howto manager. (line 3423) +* BFD_RELOC_CKCORE_NOJSRI: howto manager. (line 3471) +* BFD_RELOC_CKCORE_NONE: howto manager. (line 3411) +* BFD_RELOC_CKCORE_PCREL32: howto manager. (line 3416) +* BFD_RELOC_CKCORE_PCREL_BLOOP_IMM12BY4: howto manager. (line 3475) +* BFD_RELOC_CKCORE_PCREL_BLOOP_IMM4BY4: howto manager. (line 3474) +* BFD_RELOC_CKCORE_PCREL_FLRW_IMM8BY4: howto manager. (line 3470) +* BFD_RELOC_CKCORE_PCREL_IMM10BY2: howto manager. (line 3433) +* BFD_RELOC_CKCORE_PCREL_IMM10BY4: howto manager. (line 3434) +* BFD_RELOC_CKCORE_PCREL_IMM11BY2: howto manager. (line 3414) +* BFD_RELOC_CKCORE_PCREL_IMM16BY2: howto manager. (line 3431) +* BFD_RELOC_CKCORE_PCREL_IMM16BY4: howto manager. (line 3432) +* BFD_RELOC_CKCORE_PCREL_IMM18BY2: howto manager. (line 3454) +* BFD_RELOC_CKCORE_PCREL_IMM26BY2: howto manager. (line 3430) +* BFD_RELOC_CKCORE_PCREL_IMM4BY2: howto manager. (line 3415) +* BFD_RELOC_CKCORE_PCREL_IMM7BY4: howto manager. (line 3461) +* BFD_RELOC_CKCORE_PCREL_IMM8BY4: howto manager. (line 3413) +* BFD_RELOC_CKCORE_PCREL_JSR_IMM11BY2: howto manager. (line 3417) +* BFD_RELOC_CKCORE_PCREL_JSR_IMM26BY2: howto manager. (line 3451) +* BFD_RELOC_CKCORE_PLT12: howto manager. (line 3444) +* BFD_RELOC_CKCORE_PLT32: howto manager. (line 3427) +* BFD_RELOC_CKCORE_PLT_HI16: howto manager. (line 3445) +* BFD_RELOC_CKCORE_PLT_IMM18BY4: howto manager. (line 3460) +* BFD_RELOC_CKCORE_PLT_LO16: howto manager. (line 3446) +* BFD_RELOC_CKCORE_RELATIVE: howto manager. (line 3420) +* BFD_RELOC_CKCORE_TLS_DTPMOD32: howto manager. (line 3467) +* BFD_RELOC_CKCORE_TLS_DTPOFF32: howto manager. (line 3468) +* BFD_RELOC_CKCORE_TLS_GD32: howto manager. (line 3464) +* BFD_RELOC_CKCORE_TLS_IE32: howto manager. (line 3463) +* BFD_RELOC_CKCORE_TLS_LDM32: howto manager. (line 3465) +* BFD_RELOC_CKCORE_TLS_LDO32: howto manager. (line 3466) +* BFD_RELOC_CKCORE_TLS_LE32: howto manager. (line 3462) +* BFD_RELOC_CKCORE_TLS_TPOFF32: howto manager. (line 3469) +* BFD_RELOC_CKCORE_TOFFSET_LO16: howto manager. (line 3452) +* bfd_reloc_code_real_type: howto manager. (line 9) +* BFD_RELOC_CR16_ABS20: howto manager. (line 2288) +* BFD_RELOC_CR16_ABS24: howto manager. (line 2289) +* BFD_RELOC_CR16_DISP16: howto manager. (line 2299) +* BFD_RELOC_CR16_DISP20: howto manager. (line 2300) +* BFD_RELOC_CR16_DISP24: howto manager. (line 2301) +* BFD_RELOC_CR16_DISP24a: howto manager. (line 2302) +* BFD_RELOC_CR16_DISP4: howto manager. (line 2297) +* BFD_RELOC_CR16_DISP8: howto manager. (line 2298) +* BFD_RELOC_CR16_GLOB_DAT: howto manager. (line 2308) +* BFD_RELOC_CR16_GOTC_REGREL20: howto manager. (line 2307) +* BFD_RELOC_CR16_GOT_REGREL20: howto manager. (line 2306) +* BFD_RELOC_CR16_IMM16: howto manager. (line 2292) +* BFD_RELOC_CR16_IMM20: howto manager. (line 2293) +* BFD_RELOC_CR16_IMM24: howto manager. (line 2294) +* BFD_RELOC_CR16_IMM32: howto manager. (line 2295) +* BFD_RELOC_CR16_IMM32a: howto manager. (line 2296) +* BFD_RELOC_CR16_IMM4: howto manager. (line 2290) +* BFD_RELOC_CR16_IMM8: howto manager. (line 2291) +* BFD_RELOC_CR16_NUM16: howto manager. (line 2277) +* BFD_RELOC_CR16_NUM32: howto manager. (line 2278) +* BFD_RELOC_CR16_NUM32a: howto manager. (line 2279) +* BFD_RELOC_CR16_NUM8: howto manager. (line 2276) +* BFD_RELOC_CR16_REGREL0: howto manager. (line 2280) +* BFD_RELOC_CR16_REGREL14: howto manager. (line 2283) +* BFD_RELOC_CR16_REGREL14a: howto manager. (line 2284) +* BFD_RELOC_CR16_REGREL16: howto manager. (line 2285) +* BFD_RELOC_CR16_REGREL20: howto manager. (line 2286) +* BFD_RELOC_CR16_REGREL20a: howto manager. (line 2287) +* BFD_RELOC_CR16_REGREL4: howto manager. (line 2281) +* BFD_RELOC_CR16_REGREL4a: howto manager. (line 2282) +* BFD_RELOC_CR16_SWITCH16: howto manager. (line 2304) +* BFD_RELOC_CR16_SWITCH32: howto manager. (line 2305) +* BFD_RELOC_CR16_SWITCH8: howto manager. (line 2303) +* BFD_RELOC_CRIS_16_DTPREL: howto manager. (line 2368) +* BFD_RELOC_CRIS_16_GOT: howto manager. (line 2350) +* BFD_RELOC_CRIS_16_GOTPLT: howto manager. (line 2354) +* BFD_RELOC_CRIS_16_GOT_GD: howto manager. (line 2364) +* BFD_RELOC_CRIS_16_GOT_TPREL: howto manager. (line 2370) +* BFD_RELOC_CRIS_16_TPREL: howto manager. (line 2372) +* BFD_RELOC_CRIS_32_DTPREL: howto manager. (line 2367) +* BFD_RELOC_CRIS_32_GD: howto manager. (line 2365) +* BFD_RELOC_CRIS_32_GOT: howto manager. (line 2348) +* BFD_RELOC_CRIS_32_GOTPLT: howto manager. (line 2352) +* BFD_RELOC_CRIS_32_GOTREL: howto manager. (line 2356) +* BFD_RELOC_CRIS_32_GOT_GD: howto manager. (line 2363) +* BFD_RELOC_CRIS_32_GOT_TPREL: howto manager. (line 2369) +* BFD_RELOC_CRIS_32_IE: howto manager. (line 2374) +* BFD_RELOC_CRIS_32_PLT_GOTREL: howto manager. (line 2358) +* BFD_RELOC_CRIS_32_PLT_PCREL: howto manager. (line 2360) +* BFD_RELOC_CRIS_32_TPREL: howto manager. (line 2371) +* BFD_RELOC_CRIS_BDISP8: howto manager. (line 2331) +* BFD_RELOC_CRIS_COPY: howto manager. (line 2343) +* BFD_RELOC_CRIS_DTP: howto manager. (line 2366) +* BFD_RELOC_CRIS_DTPMOD: howto manager. (line 2373) +* BFD_RELOC_CRIS_GLOB_DAT: howto manager. (line 2344) +* BFD_RELOC_CRIS_JUMP_SLOT: howto manager. (line 2345) +* BFD_RELOC_CRIS_LAPCQ_OFFSET: howto manager. (line 2339) +* BFD_RELOC_CRIS_RELATIVE: howto manager. (line 2346) +* BFD_RELOC_CRIS_SIGNED_16: howto manager. (line 2337) +* BFD_RELOC_CRIS_SIGNED_6: howto manager. (line 2333) +* BFD_RELOC_CRIS_SIGNED_8: howto manager. (line 2335) +* BFD_RELOC_CRIS_UNSIGNED_16: howto manager. (line 2338) +* BFD_RELOC_CRIS_UNSIGNED_4: howto manager. (line 2340) +* BFD_RELOC_CRIS_UNSIGNED_5: howto manager. (line 2332) +* BFD_RELOC_CRIS_UNSIGNED_6: howto manager. (line 2334) +* BFD_RELOC_CRIS_UNSIGNED_8: howto manager. (line 2336) +* BFD_RELOC_CRX_ABS16: howto manager. (line 2320) +* BFD_RELOC_CRX_ABS32: howto manager. (line 2321) +* BFD_RELOC_CRX_IMM16: howto manager. (line 2325) +* BFD_RELOC_CRX_IMM32: howto manager. (line 2326) +* BFD_RELOC_CRX_NUM16: howto manager. (line 2323) +* BFD_RELOC_CRX_NUM32: howto manager. (line 2324) +* BFD_RELOC_CRX_NUM8: howto manager. (line 2322) +* BFD_RELOC_CRX_REGREL12: howto manager. (line 2316) +* BFD_RELOC_CRX_REGREL22: howto manager. (line 2317) +* BFD_RELOC_CRX_REGREL28: howto manager. (line 2318) +* BFD_RELOC_CRX_REGREL32: howto manager. (line 2319) +* BFD_RELOC_CRX_REL16: howto manager. (line 2313) +* BFD_RELOC_CRX_REL24: howto manager. (line 2314) +* BFD_RELOC_CRX_REL32: howto manager. (line 2315) +* BFD_RELOC_CRX_REL4: howto manager. (line 2310) +* BFD_RELOC_CRX_REL8: howto manager. (line 2311) +* BFD_RELOC_CRX_REL8_CMP: howto manager. (line 2312) +* BFD_RELOC_CRX_SWITCH16: howto manager. (line 2328) +* BFD_RELOC_CRX_SWITCH32: howto manager. (line 2329) +* BFD_RELOC_CRX_SWITCH8: howto manager. (line 2327) +* BFD_RELOC_CTOR: howto manager. (line 782) +* BFD_RELOC_D10V_10_PCREL_L: howto manager. (line 1206) +* BFD_RELOC_D10V_10_PCREL_R: howto manager. (line 1203) +* BFD_RELOC_D10V_18: howto manager. (line 1210) +* BFD_RELOC_D10V_18_PCREL: howto manager. (line 1212) +* BFD_RELOC_D30V_15: howto manager. (line 1223) +* BFD_RELOC_D30V_15_PCREL: howto manager. (line 1226) +* BFD_RELOC_D30V_15_PCREL_R: howto manager. (line 1229) +* BFD_RELOC_D30V_21: howto manager. (line 1233) +* BFD_RELOC_D30V_21_PCREL: howto manager. (line 1236) +* BFD_RELOC_D30V_21_PCREL_R: howto manager. (line 1239) +* BFD_RELOC_D30V_32: howto manager. (line 1243) +* BFD_RELOC_D30V_32_PCREL: howto manager. (line 1245) +* BFD_RELOC_D30V_6: howto manager. (line 1214) +* BFD_RELOC_D30V_9_PCREL: howto manager. (line 1216) +* BFD_RELOC_D30V_9_PCREL_R: howto manager. (line 1219) +* BFD_RELOC_DLX_HI16_S: howto manager. (line 1247) +* BFD_RELOC_DLX_JMP26: howto manager. (line 1249) +* BFD_RELOC_DLX_LO16: howto manager. (line 1248) +* BFD_RELOC_EPIPHANY_HIGH: howto manager. (line 3381) +* BFD_RELOC_EPIPHANY_IMM11: howto manager. (line 3387) +* BFD_RELOC_EPIPHANY_IMM8: howto manager. (line 3390) +* BFD_RELOC_EPIPHANY_LOW: howto manager. (line 3383) +* BFD_RELOC_EPIPHANY_SIMM11: howto manager. (line 3385) +* BFD_RELOC_EPIPHANY_SIMM24: howto manager. (line 3379) +* BFD_RELOC_EPIPHANY_SIMM8: howto manager. (line 3377) +* BFD_RELOC_FR30_10_IN_8: howto manager. (line 1626) +* BFD_RELOC_FR30_12_PCREL: howto manager. (line 1632) +* BFD_RELOC_FR30_20: howto manager. (line 1614) +* BFD_RELOC_FR30_48: howto manager. (line 1612) +* BFD_RELOC_FR30_6_IN_4: howto manager. (line 1617) +* BFD_RELOC_FR30_8_IN_8: howto manager. (line 1620) +* BFD_RELOC_FR30_9_IN_8: howto manager. (line 1623) +* BFD_RELOC_FR30_9_PCREL: howto manager. (line 1629) +* BFD_RELOC_FRV_FUNCDESC: howto manager. (line 451) +* BFD_RELOC_FRV_FUNCDESC_GOT12: howto manager. (line 452) +* BFD_RELOC_FRV_FUNCDESC_GOTHI: howto manager. (line 453) +* BFD_RELOC_FRV_FUNCDESC_GOTLO: howto manager. (line 454) +* BFD_RELOC_FRV_FUNCDESC_GOTOFF12: howto manager. (line 456) +* BFD_RELOC_FRV_FUNCDESC_GOTOFFHI: howto manager. (line 457) +* BFD_RELOC_FRV_FUNCDESC_GOTOFFLO: howto manager. (line 458) +* BFD_RELOC_FRV_FUNCDESC_VALUE: howto manager. (line 455) +* BFD_RELOC_FRV_GETTLSOFF: howto manager. (line 462) +* BFD_RELOC_FRV_GETTLSOFF_RELAX: howto manager. (line 475) +* BFD_RELOC_FRV_GOT12: howto manager. (line 448) +* BFD_RELOC_FRV_GOTHI: howto manager. (line 449) +* BFD_RELOC_FRV_GOTLO: howto manager. (line 450) +* BFD_RELOC_FRV_GOTOFF12: howto manager. (line 459) +* BFD_RELOC_FRV_GOTOFFHI: howto manager. (line 460) +* BFD_RELOC_FRV_GOTOFFLO: howto manager. (line 461) +* BFD_RELOC_FRV_GOTTLSDESC12: howto manager. (line 464) +* BFD_RELOC_FRV_GOTTLSDESCHI: howto manager. (line 465) +* BFD_RELOC_FRV_GOTTLSDESCLO: howto manager. (line 466) +* BFD_RELOC_FRV_GOTTLSOFF12: howto manager. (line 470) +* BFD_RELOC_FRV_GOTTLSOFFHI: howto manager. (line 471) +* BFD_RELOC_FRV_GOTTLSOFFLO: howto manager. (line 472) +* BFD_RELOC_FRV_GPREL12: howto manager. (line 443) +* BFD_RELOC_FRV_GPREL32: howto manager. (line 445) +* BFD_RELOC_FRV_GPRELHI: howto manager. (line 446) +* BFD_RELOC_FRV_GPRELLO: howto manager. (line 447) +* BFD_RELOC_FRV_GPRELU12: howto manager. (line 444) +* BFD_RELOC_FRV_HI16: howto manager. (line 442) +* BFD_RELOC_FRV_LABEL16: howto manager. (line 439) +* BFD_RELOC_FRV_LABEL24: howto manager. (line 440) +* BFD_RELOC_FRV_LO16: howto manager. (line 441) +* BFD_RELOC_FRV_TLSDESC_RELAX: howto manager. (line 474) +* BFD_RELOC_FRV_TLSDESC_VALUE: howto manager. (line 463) +* BFD_RELOC_FRV_TLSMOFF: howto manager. (line 477) +* BFD_RELOC_FRV_TLSMOFF12: howto manager. (line 467) +* BFD_RELOC_FRV_TLSMOFFHI: howto manager. (line 468) +* BFD_RELOC_FRV_TLSMOFFLO: howto manager. (line 469) +* BFD_RELOC_FRV_TLSOFF: howto manager. (line 473) +* BFD_RELOC_FRV_TLSOFF_RELAX: howto manager. (line 476) +* BFD_RELOC_FT32_10: howto manager. (line 429) +* BFD_RELOC_FT32_15: howto manager. (line 436) +* BFD_RELOC_FT32_17: howto manager. (line 431) +* BFD_RELOC_FT32_18: howto manager. (line 432) +* BFD_RELOC_FT32_20: howto manager. (line 430) +* BFD_RELOC_FT32_DIFF32: howto manager. (line 437) +* BFD_RELOC_FT32_RELAX: howto manager. (line 433) +* BFD_RELOC_FT32_SC0: howto manager. (line 434) +* BFD_RELOC_FT32_SC1: howto manager. (line 435) +* BFD_RELOC_GPREL16: howto manager. (line 112) +* BFD_RELOC_GPREL32: howto manager. (line 113) +* BFD_RELOC_H8_DIR16A8: howto manager. (line 2417) +* BFD_RELOC_H8_DIR16R8: howto manager. (line 2418) +* BFD_RELOC_H8_DIR24A8: howto manager. (line 2419) +* BFD_RELOC_H8_DIR24R8: howto manager. (line 2420) +* BFD_RELOC_H8_DIR32A16: howto manager. (line 2421) +* BFD_RELOC_H8_DISP32A16: howto manager. (line 2422) +* BFD_RELOC_HI16: howto manager. (line 312) +* BFD_RELOC_HI16_BASEREL: howto manager. (line 92) +* BFD_RELOC_HI16_GOTOFF: howto manager. (line 51) +* BFD_RELOC_HI16_PCREL: howto manager. (line 321) +* BFD_RELOC_HI16_PLTOFF: howto manager. (line 63) +* BFD_RELOC_HI16_S: howto manager. (line 314) +* BFD_RELOC_HI16_S_BASEREL: howto manager. (line 93) +* BFD_RELOC_HI16_S_GOTOFF: howto manager. (line 52) +* BFD_RELOC_HI16_S_PCREL: howto manager. (line 323) +* BFD_RELOC_HI16_S_PLTOFF: howto manager. (line 64) +* BFD_RELOC_HI22: howto manager. (line 108) +* BFD_RELOC_I370_D12: howto manager. (line 780) +* BFD_RELOC_IA64_COPY: howto manager. (line 2174) +* BFD_RELOC_IA64_DIR32LSB: howto manager. (line 2119) +* BFD_RELOC_IA64_DIR32MSB: howto manager. (line 2118) +* BFD_RELOC_IA64_DIR64LSB: howto manager. (line 2121) +* BFD_RELOC_IA64_DIR64MSB: howto manager. (line 2120) +* BFD_RELOC_IA64_DTPMOD64LSB: howto manager. (line 2184) +* BFD_RELOC_IA64_DTPMOD64MSB: howto manager. (line 2183) +* BFD_RELOC_IA64_DTPREL14: howto manager. (line 2186) +* BFD_RELOC_IA64_DTPREL22: howto manager. (line 2187) +* BFD_RELOC_IA64_DTPREL32LSB: howto manager. (line 2190) +* BFD_RELOC_IA64_DTPREL32MSB: howto manager. (line 2189) +* BFD_RELOC_IA64_DTPREL64I: howto manager. (line 2188) +* BFD_RELOC_IA64_DTPREL64LSB: howto manager. (line 2192) +* BFD_RELOC_IA64_DTPREL64MSB: howto manager. (line 2191) +* BFD_RELOC_IA64_FPTR32LSB: howto manager. (line 2136) +* BFD_RELOC_IA64_FPTR32MSB: howto manager. (line 2135) +* BFD_RELOC_IA64_FPTR64I: howto manager. (line 2134) +* BFD_RELOC_IA64_FPTR64LSB: howto manager. (line 2138) +* BFD_RELOC_IA64_FPTR64MSB: howto manager. (line 2137) +* BFD_RELOC_IA64_GPREL22: howto manager. (line 2122) +* BFD_RELOC_IA64_GPREL32LSB: howto manager. (line 2125) +* BFD_RELOC_IA64_GPREL32MSB: howto manager. (line 2124) +* BFD_RELOC_IA64_GPREL64I: howto manager. (line 2123) +* BFD_RELOC_IA64_GPREL64LSB: howto manager. (line 2127) +* BFD_RELOC_IA64_GPREL64MSB: howto manager. (line 2126) +* BFD_RELOC_IA64_IMM14: howto manager. (line 2115) +* BFD_RELOC_IA64_IMM22: howto manager. (line 2116) +* BFD_RELOC_IA64_IMM64: howto manager. (line 2117) +* BFD_RELOC_IA64_IPLTLSB: howto manager. (line 2173) +* BFD_RELOC_IA64_IPLTMSB: howto manager. (line 2172) +* BFD_RELOC_IA64_LDXMOV: howto manager. (line 2176) +* BFD_RELOC_IA64_LTOFF22: howto manager. (line 2128) +* BFD_RELOC_IA64_LTOFF22X: howto manager. (line 2175) +* BFD_RELOC_IA64_LTOFF64I: howto manager. (line 2129) +* BFD_RELOC_IA64_LTOFF_DTPMOD22: howto manager. (line 2185) +* BFD_RELOC_IA64_LTOFF_DTPREL22: howto manager. (line 2193) +* BFD_RELOC_IA64_LTOFF_FPTR22: howto manager. (line 2150) +* BFD_RELOC_IA64_LTOFF_FPTR32LSB: howto manager. (line 2153) +* BFD_RELOC_IA64_LTOFF_FPTR32MSB: howto manager. (line 2152) +* BFD_RELOC_IA64_LTOFF_FPTR64I: howto manager. (line 2151) +* BFD_RELOC_IA64_LTOFF_FPTR64LSB: howto manager. (line 2155) +* BFD_RELOC_IA64_LTOFF_FPTR64MSB: howto manager. (line 2154) +* BFD_RELOC_IA64_LTOFF_TPREL22: howto manager. (line 2182) +* BFD_RELOC_IA64_LTV32LSB: howto manager. (line 2169) +* BFD_RELOC_IA64_LTV32MSB: howto manager. (line 2168) +* BFD_RELOC_IA64_LTV64LSB: howto manager. (line 2171) +* BFD_RELOC_IA64_LTV64MSB: howto manager. (line 2170) +* BFD_RELOC_IA64_PCREL21B: howto manager. (line 2139) +* BFD_RELOC_IA64_PCREL21BI: howto manager. (line 2140) +* BFD_RELOC_IA64_PCREL21F: howto manager. (line 2142) +* BFD_RELOC_IA64_PCREL21M: howto manager. (line 2141) +* BFD_RELOC_IA64_PCREL22: howto manager. (line 2143) +* BFD_RELOC_IA64_PCREL32LSB: howto manager. (line 2147) +* BFD_RELOC_IA64_PCREL32MSB: howto manager. (line 2146) +* BFD_RELOC_IA64_PCREL60B: howto manager. (line 2144) +* BFD_RELOC_IA64_PCREL64I: howto manager. (line 2145) +* BFD_RELOC_IA64_PCREL64LSB: howto manager. (line 2149) +* BFD_RELOC_IA64_PCREL64MSB: howto manager. (line 2148) +* BFD_RELOC_IA64_PLTOFF22: howto manager. (line 2130) +* BFD_RELOC_IA64_PLTOFF64I: howto manager. (line 2131) +* BFD_RELOC_IA64_PLTOFF64LSB: howto manager. (line 2133) +* BFD_RELOC_IA64_PLTOFF64MSB: howto manager. (line 2132) +* BFD_RELOC_IA64_REL32LSB: howto manager. (line 2165) +* BFD_RELOC_IA64_REL32MSB: howto manager. (line 2164) +* BFD_RELOC_IA64_REL64LSB: howto manager. (line 2167) +* BFD_RELOC_IA64_REL64MSB: howto manager. (line 2166) +* BFD_RELOC_IA64_SECREL32LSB: howto manager. (line 2161) +* BFD_RELOC_IA64_SECREL32MSB: howto manager. (line 2160) +* BFD_RELOC_IA64_SECREL64LSB: howto manager. (line 2163) +* BFD_RELOC_IA64_SECREL64MSB: howto manager. (line 2162) +* BFD_RELOC_IA64_SEGREL32LSB: howto manager. (line 2157) +* BFD_RELOC_IA64_SEGREL32MSB: howto manager. (line 2156) +* BFD_RELOC_IA64_SEGREL64LSB: howto manager. (line 2159) +* BFD_RELOC_IA64_SEGREL64MSB: howto manager. (line 2158) +* BFD_RELOC_IA64_TPREL14: howto manager. (line 2177) +* BFD_RELOC_IA64_TPREL22: howto manager. (line 2178) +* BFD_RELOC_IA64_TPREL64I: howto manager. (line 2179) +* BFD_RELOC_IA64_TPREL64LSB: howto manager. (line 2181) +* BFD_RELOC_IA64_TPREL64MSB: howto manager. (line 2180) +* BFD_RELOC_IP2K_ADDR16CJP: howto manager. (line 2076) +* BFD_RELOC_IP2K_BANK: howto manager. (line 2074) +* BFD_RELOC_IP2K_EX8DATA: howto manager. (line 2082) +* BFD_RELOC_IP2K_FR9: howto manager. (line 2072) +* BFD_RELOC_IP2K_FR_OFFSET: howto manager. (line 2091) +* BFD_RELOC_IP2K_HI8DATA: howto manager. (line 2081) +* BFD_RELOC_IP2K_HI8INSN: howto manager. (line 2085) +* BFD_RELOC_IP2K_LO8DATA: howto manager. (line 2080) +* BFD_RELOC_IP2K_LO8INSN: howto manager. (line 2084) +* BFD_RELOC_IP2K_PAGE3: howto manager. (line 2078) +* BFD_RELOC_IP2K_PC_SKIP: howto manager. (line 2087) +* BFD_RELOC_IP2K_TEXT: howto manager. (line 2089) +* BFD_RELOC_IQ2000_OFFSET_16: howto manager. (line 2500) +* BFD_RELOC_IQ2000_OFFSET_21: howto manager. (line 2501) +* BFD_RELOC_IQ2000_UHI16: howto manager. (line 2502) +* BFD_RELOC_KVX_16: howto manager. (line 2750) +* BFD_RELOC_KVX_32: howto manager. (line 2751) +* BFD_RELOC_KVX_32_GOT: howto manager. (line 2778) +* BFD_RELOC_KVX_32_GOTOFF: howto manager. (line 2776) +* BFD_RELOC_KVX_32_PCREL: howto manager. (line 2756) +* BFD_RELOC_KVX_64: howto manager. (line 2752) +* BFD_RELOC_KVX_64_DTPMOD: howto manager. (line 2803) +* BFD_RELOC_KVX_64_DTPOFF: howto manager. (line 2804) +* BFD_RELOC_KVX_64_GOT: howto manager. (line 2784) +* BFD_RELOC_KVX_64_GOTOFF: howto manager. (line 2777) +* BFD_RELOC_KVX_64_PCREL: howto manager. (line 2765) +* BFD_RELOC_KVX_64_TPOFF: howto manager. (line 2820) +* BFD_RELOC_KVX_8: howto manager. (line 2831) +* BFD_RELOC_KVX_COPY: howto manager. (line 2786) +* BFD_RELOC_KVX_GLOB_DAT: howto manager. (line 2785) +* BFD_RELOC_KVX_JMP_SLOT: howto manager. (line 2787) +* BFD_RELOC_KVX_NONE: howto manager. (line 2748) +* BFD_RELOC_KVX_PCREL17: howto manager. (line 2754) +* BFD_RELOC_KVX_PCREL27: howto manager. (line 2755) +* BFD_RELOC_KVX_RELATIVE: howto manager. (line 2788) +* BFD_RELOC_KVX_RELOC_END: howto manager. (line 2833) +* BFD_RELOC_KVX_RELOC_START: howto manager. (line 2743) +* BFD_RELOC_KVX_S16: howto manager. (line 2766) +* BFD_RELOC_KVX_S16_PCREL: howto manager. (line 2753) +* BFD_RELOC_KVX_S32_LO5: howto manager. (line 2767) +* BFD_RELOC_KVX_S32_UP27: howto manager. (line 2768) +* BFD_RELOC_KVX_S37_GOTADDR_LO10: howto manager. (line 2795) +* BFD_RELOC_KVX_S37_GOTADDR_UP27: howto manager. (line 2796) +* BFD_RELOC_KVX_S37_GOTOFF_LO10: howto manager. (line 2771) +* BFD_RELOC_KVX_S37_GOTOFF_UP27: howto manager. (line 2772) +* BFD_RELOC_KVX_S37_GOT_LO10: howto manager. (line 2779) +* BFD_RELOC_KVX_S37_GOT_UP27: howto manager. (line 2780) +* BFD_RELOC_KVX_S37_LO10: howto manager. (line 2769) +* BFD_RELOC_KVX_S37_PCREL_LO10: howto manager. (line 2757) +* BFD_RELOC_KVX_S37_PCREL_UP27: howto manager. (line 2758) +* BFD_RELOC_KVX_S37_TLS_DTPOFF_LO10: howto manager. (line 2805) +* BFD_RELOC_KVX_S37_TLS_DTPOFF_UP27: howto manager. (line 2806) +* BFD_RELOC_KVX_S37_TLS_GD_LO10: howto manager. (line 2810) +* BFD_RELOC_KVX_S37_TLS_GD_UP27: howto manager. (line 2811) +* BFD_RELOC_KVX_S37_TLS_IE_LO10: howto manager. (line 2821) +* BFD_RELOC_KVX_S37_TLS_IE_UP27: howto manager. (line 2822) +* BFD_RELOC_KVX_S37_TLS_LD_LO10: howto manager. (line 2815) +* BFD_RELOC_KVX_S37_TLS_LD_UP27: howto manager. (line 2816) +* BFD_RELOC_KVX_S37_TLS_LE_LO10: howto manager. (line 2826) +* BFD_RELOC_KVX_S37_TLS_LE_UP27: howto manager. (line 2827) +* BFD_RELOC_KVX_S37_UP27: howto manager. (line 2770) +* BFD_RELOC_KVX_S43_EX6: howto manager. (line 2791) +* BFD_RELOC_KVX_S43_GOTADDR_EX6: howto manager. (line 2799) +* BFD_RELOC_KVX_S43_GOTADDR_LO10: howto manager. (line 2797) +* BFD_RELOC_KVX_S43_GOTADDR_UP27: howto manager. (line 2798) +* BFD_RELOC_KVX_S43_GOTOFF_EX6: howto manager. (line 2775) +* BFD_RELOC_KVX_S43_GOTOFF_LO10: howto manager. (line 2773) +* BFD_RELOC_KVX_S43_GOTOFF_UP27: howto manager. (line 2774) +* BFD_RELOC_KVX_S43_GOT_EX6: howto manager. (line 2783) +* BFD_RELOC_KVX_S43_GOT_LO10: howto manager. (line 2781) +* BFD_RELOC_KVX_S43_GOT_UP27: howto manager. (line 2782) +* BFD_RELOC_KVX_S43_LO10: howto manager. (line 2789) +* BFD_RELOC_KVX_S43_PCREL_EX6: howto manager. (line 2761) +* BFD_RELOC_KVX_S43_PCREL_LO10: howto manager. (line 2759) +* BFD_RELOC_KVX_S43_PCREL_UP27: howto manager. (line 2760) +* BFD_RELOC_KVX_S43_TLS_DTPOFF_EX6: howto manager. (line 2809) +* BFD_RELOC_KVX_S43_TLS_DTPOFF_LO10: howto manager. (line 2807) +* BFD_RELOC_KVX_S43_TLS_DTPOFF_UP27: howto manager. (line 2808) +* BFD_RELOC_KVX_S43_TLS_GD_EX6: howto manager. (line 2814) +* BFD_RELOC_KVX_S43_TLS_GD_LO10: howto manager. (line 2812) +* BFD_RELOC_KVX_S43_TLS_GD_UP27: howto manager. (line 2813) +* BFD_RELOC_KVX_S43_TLS_IE_EX6: howto manager. (line 2825) +* BFD_RELOC_KVX_S43_TLS_IE_LO10: howto manager. (line 2823) +* BFD_RELOC_KVX_S43_TLS_IE_UP27: howto manager. (line 2824) +* BFD_RELOC_KVX_S43_TLS_LD_EX6: howto manager. (line 2819) +* BFD_RELOC_KVX_S43_TLS_LD_LO10: howto manager. (line 2817) +* BFD_RELOC_KVX_S43_TLS_LD_UP27: howto manager. (line 2818) +* BFD_RELOC_KVX_S43_TLS_LE_EX6: howto manager. (line 2830) +* BFD_RELOC_KVX_S43_TLS_LE_LO10: howto manager. (line 2828) +* BFD_RELOC_KVX_S43_TLS_LE_UP27: howto manager. (line 2829) +* BFD_RELOC_KVX_S43_UP27: howto manager. (line 2790) +* BFD_RELOC_KVX_S64_EX27: howto manager. (line 2794) +* BFD_RELOC_KVX_S64_GOTADDR_EX27: howto manager. (line 2802) +* BFD_RELOC_KVX_S64_GOTADDR_LO10: howto manager. (line 2800) +* BFD_RELOC_KVX_S64_GOTADDR_UP27: howto manager. (line 2801) +* BFD_RELOC_KVX_S64_LO10: howto manager. (line 2792) +* BFD_RELOC_KVX_S64_PCREL_EX27: howto manager. (line 2764) +* BFD_RELOC_KVX_S64_PCREL_LO10: howto manager. (line 2762) +* BFD_RELOC_KVX_S64_PCREL_UP27: howto manager. (line 2763) +* BFD_RELOC_KVX_S64_UP27: howto manager. (line 2793) +* BFD_RELOC_LARCH_32_PCREL: howto manager. (line 3559) +* BFD_RELOC_LARCH_64_PCREL: howto manager. (line 3569) +* BFD_RELOC_LARCH_ABS64_HI12: howto manager. (line 3530) +* BFD_RELOC_LARCH_ABS64_LO20: howto manager. (line 3529) +* BFD_RELOC_LARCH_ABS_HI20: howto manager. (line 3527) +* BFD_RELOC_LARCH_ABS_LO12: howto manager. (line 3528) +* BFD_RELOC_LARCH_ADD16: howto manager. (line 3515) +* BFD_RELOC_LARCH_ADD24: howto manager. (line 3516) +* BFD_RELOC_LARCH_ADD32: howto manager. (line 3517) +* BFD_RELOC_LARCH_ADD6: howto manager. (line 3565) +* BFD_RELOC_LARCH_ADD64: howto manager. (line 3518) +* BFD_RELOC_LARCH_ADD8: howto manager. (line 3514) +* BFD_RELOC_LARCH_ADD_ULEB128: howto manager. (line 3567) +* BFD_RELOC_LARCH_ALIGN: howto manager. (line 3562) +* BFD_RELOC_LARCH_B16: howto manager. (line 3524) +* BFD_RELOC_LARCH_B21: howto manager. (line 3525) +* BFD_RELOC_LARCH_B26: howto manager. (line 3526) +* BFD_RELOC_LARCH_CALL36: howto manager. (line 3570) +* BFD_RELOC_LARCH_CFA: howto manager. (line 3564) +* BFD_RELOC_LARCH_DELETE: howto manager. (line 3561) +* BFD_RELOC_LARCH_GOT64_HI12: howto manager. (line 3542) +* BFD_RELOC_LARCH_GOT64_LO20: howto manager. (line 3541) +* BFD_RELOC_LARCH_GOT64_PC_HI12: howto manager. (line 3538) +* BFD_RELOC_LARCH_GOT64_PC_LO20: howto manager. (line 3537) +* BFD_RELOC_LARCH_GOT_HI20: howto manager. (line 3539) +* BFD_RELOC_LARCH_GOT_LO12: howto manager. (line 3540) +* BFD_RELOC_LARCH_GOT_PC_HI20: howto manager. (line 3535) +* BFD_RELOC_LARCH_GOT_PC_LO12: howto manager. (line 3536) +* BFD_RELOC_LARCH_MARK_LA: howto manager. (line 3487) +* BFD_RELOC_LARCH_MARK_PCREL: howto manager. (line 3488) +* BFD_RELOC_LARCH_PCALA64_HI12: howto manager. (line 3534) +* BFD_RELOC_LARCH_PCALA64_LO20: howto manager. (line 3533) +* BFD_RELOC_LARCH_PCALA_HI20: howto manager. (line 3531) +* BFD_RELOC_LARCH_PCALA_LO12: howto manager. (line 3532) +* BFD_RELOC_LARCH_PCREL20_S2: howto manager. (line 3563) +* BFD_RELOC_LARCH_RELAX: howto manager. (line 3560) +* BFD_RELOC_LARCH_SOP_ADD: howto manager. (line 3502) +* BFD_RELOC_LARCH_SOP_AND: howto manager. (line 3503) +* BFD_RELOC_LARCH_SOP_ASSERT: howto manager. (line 3497) +* BFD_RELOC_LARCH_SOP_IF_ELSE: howto manager. (line 3504) +* BFD_RELOC_LARCH_SOP_NOT: howto manager. (line 3498) +* BFD_RELOC_LARCH_SOP_POP_32_S_0_10_10_16_S2: howto manager. (line 3512) +* BFD_RELOC_LARCH_SOP_POP_32_S_0_5_10_16_S2: howto manager. (line 3511) +* BFD_RELOC_LARCH_SOP_POP_32_S_10_12: howto manager. (line 3507) +* BFD_RELOC_LARCH_SOP_POP_32_S_10_16: howto manager. (line 3508) +* BFD_RELOC_LARCH_SOP_POP_32_S_10_16_S2: howto manager. (line 3509) +* BFD_RELOC_LARCH_SOP_POP_32_S_10_5: howto manager. (line 3505) +* BFD_RELOC_LARCH_SOP_POP_32_S_5_20: howto manager. (line 3510) +* BFD_RELOC_LARCH_SOP_POP_32_U: howto manager. (line 3513) +* BFD_RELOC_LARCH_SOP_POP_32_U_10_12: howto manager. (line 3506) +* BFD_RELOC_LARCH_SOP_PUSH_ABSOLUTE: howto manager. (line 3490) +* BFD_RELOC_LARCH_SOP_PUSH_DUP: howto manager. (line 3491) +* BFD_RELOC_LARCH_SOP_PUSH_GPREL: howto manager. (line 3492) +* BFD_RELOC_LARCH_SOP_PUSH_PCREL: howto manager. (line 3489) +* BFD_RELOC_LARCH_SOP_PUSH_PLT_PCREL: howto manager. (line 3496) +* BFD_RELOC_LARCH_SOP_PUSH_TLS_GD: howto manager. (line 3495) +* BFD_RELOC_LARCH_SOP_PUSH_TLS_GOT: howto manager. (line 3494) +* BFD_RELOC_LARCH_SOP_PUSH_TLS_TPREL: howto manager. (line 3493) +* BFD_RELOC_LARCH_SOP_SL: howto manager. (line 3500) +* BFD_RELOC_LARCH_SOP_SR: howto manager. (line 3501) +* BFD_RELOC_LARCH_SOP_SUB: howto manager. (line 3499) +* BFD_RELOC_LARCH_SUB16: howto manager. (line 3520) +* BFD_RELOC_LARCH_SUB24: howto manager. (line 3521) +* BFD_RELOC_LARCH_SUB32: howto manager. (line 3522) +* BFD_RELOC_LARCH_SUB6: howto manager. (line 3566) +* BFD_RELOC_LARCH_SUB64: howto manager. (line 3523) +* BFD_RELOC_LARCH_SUB8: howto manager. (line 3519) +* BFD_RELOC_LARCH_SUB_ULEB128: howto manager. (line 3568) +* BFD_RELOC_LARCH_TLS_DESC32: howto manager. (line 3485) +* BFD_RELOC_LARCH_TLS_DESC64: howto manager. (line 3486) +* BFD_RELOC_LARCH_TLS_DESC64_HI12: howto manager. (line 3578) +* BFD_RELOC_LARCH_TLS_DESC64_LO20: howto manager. (line 3577) +* BFD_RELOC_LARCH_TLS_DESC64_PC_HI12: howto manager. (line 3574) +* BFD_RELOC_LARCH_TLS_DESC64_PC_LO20: howto manager. (line 3573) +* BFD_RELOC_LARCH_TLS_DESC_CALL: howto manager. (line 3580) +* BFD_RELOC_LARCH_TLS_DESC_HI20: howto manager. (line 3575) +* BFD_RELOC_LARCH_TLS_DESC_LD: howto manager. (line 3579) +* BFD_RELOC_LARCH_TLS_DESC_LO12: howto manager. (line 3576) +* BFD_RELOC_LARCH_TLS_DESC_PCREL20_S2: howto manager. (line 3586) +* BFD_RELOC_LARCH_TLS_DESC_PC_HI20: howto manager. (line 3571) +* BFD_RELOC_LARCH_TLS_DESC_PC_LO12: howto manager. (line 3572) +* BFD_RELOC_LARCH_TLS_DTPMOD32: howto manager. (line 3479) +* BFD_RELOC_LARCH_TLS_DTPMOD64: howto manager. (line 3481) +* BFD_RELOC_LARCH_TLS_DTPREL32: howto manager. (line 3480) +* BFD_RELOC_LARCH_TLS_DTPREL64: howto manager. (line 3482) +* BFD_RELOC_LARCH_TLS_GD_HI20: howto manager. (line 3558) +* BFD_RELOC_LARCH_TLS_GD_PCREL20_S2: howto manager. (line 3585) +* BFD_RELOC_LARCH_TLS_GD_PC_HI20: howto manager. (line 3557) +* BFD_RELOC_LARCH_TLS_IE64_HI12: howto manager. (line 3554) +* BFD_RELOC_LARCH_TLS_IE64_LO20: howto manager. (line 3553) +* BFD_RELOC_LARCH_TLS_IE64_PC_HI12: howto manager. (line 3550) +* BFD_RELOC_LARCH_TLS_IE64_PC_LO20: howto manager. (line 3549) +* BFD_RELOC_LARCH_TLS_IE_HI20: howto manager. (line 3551) +* BFD_RELOC_LARCH_TLS_IE_LO12: howto manager. (line 3552) +* BFD_RELOC_LARCH_TLS_IE_PC_HI20: howto manager. (line 3547) +* BFD_RELOC_LARCH_TLS_IE_PC_LO12: howto manager. (line 3548) +* BFD_RELOC_LARCH_TLS_LD_HI20: howto manager. (line 3556) +* BFD_RELOC_LARCH_TLS_LD_PCREL20_S2: howto manager. (line 3584) +* BFD_RELOC_LARCH_TLS_LD_PC_HI20: howto manager. (line 3555) +* BFD_RELOC_LARCH_TLS_LE64_HI12: howto manager. (line 3546) +* BFD_RELOC_LARCH_TLS_LE64_LO20: howto manager. (line 3545) +* BFD_RELOC_LARCH_TLS_LE_ADD_R: howto manager. (line 3582) +* BFD_RELOC_LARCH_TLS_LE_HI20: howto manager. (line 3543) +* BFD_RELOC_LARCH_TLS_LE_HI20_R: howto manager. (line 3581) +* BFD_RELOC_LARCH_TLS_LE_LO12: howto manager. (line 3544) +* BFD_RELOC_LARCH_TLS_LE_LO12_R: howto manager. (line 3583) +* BFD_RELOC_LARCH_TLS_TPREL32: howto manager. (line 3483) +* BFD_RELOC_LARCH_TLS_TPREL64: howto manager. (line 3484) +* BFD_RELOC_LM32_16_GOT: howto manager. (line 2623) +* BFD_RELOC_LM32_BRANCH: howto manager. (line 2622) +* BFD_RELOC_LM32_CALL: howto manager. (line 2621) +* BFD_RELOC_LM32_COPY: howto manager. (line 2626) +* BFD_RELOC_LM32_GLOB_DAT: howto manager. (line 2627) +* BFD_RELOC_LM32_GOTOFF_HI16: howto manager. (line 2624) +* BFD_RELOC_LM32_GOTOFF_LO16: howto manager. (line 2625) +* BFD_RELOC_LM32_JMP_SLOT: howto manager. (line 2628) +* BFD_RELOC_LM32_RELATIVE: howto manager. (line 2629) +* BFD_RELOC_LO10: howto manager. (line 109) +* BFD_RELOC_LO16: howto manager. (line 319) +* BFD_RELOC_LO16_BASEREL: howto manager. (line 91) +* BFD_RELOC_LO16_GOTOFF: howto manager. (line 50) +* BFD_RELOC_LO16_PCREL: howto manager. (line 325) +* BFD_RELOC_LO16_PLTOFF: howto manager. (line 62) +* BFD_RELOC_M32C_HI8: howto manager. (line 1251) +* BFD_RELOC_M32C_RL_1ADDR: howto manager. (line 1253) +* BFD_RELOC_M32C_RL_2ADDR: howto manager. (line 1254) +* BFD_RELOC_M32C_RL_JUMP: howto manager. (line 1252) +* BFD_RELOC_M32R_10_PCREL: howto manager. (line 1259) +* BFD_RELOC_M32R_18_PCREL: howto manager. (line 1262) +* BFD_RELOC_M32R_24: howto manager. (line 1256) +* BFD_RELOC_M32R_26_PCREL: howto manager. (line 1264) +* BFD_RELOC_M32R_26_PLTREL: howto manager. (line 1278) +* BFD_RELOC_M32R_COPY: howto manager. (line 1279) +* BFD_RELOC_M32R_GLOB_DAT: howto manager. (line 1280) +* BFD_RELOC_M32R_GOT16_HI_SLO: howto manager. (line 1289) +* BFD_RELOC_M32R_GOT16_HI_ULO: howto manager. (line 1288) +* BFD_RELOC_M32R_GOT16_LO: howto manager. (line 1290) +* BFD_RELOC_M32R_GOT24: howto manager. (line 1277) +* BFD_RELOC_M32R_GOTOFF: howto manager. (line 1283) +* BFD_RELOC_M32R_GOTOFF_HI_SLO: howto manager. (line 1285) +* BFD_RELOC_M32R_GOTOFF_HI_ULO: howto manager. (line 1284) +* BFD_RELOC_M32R_GOTOFF_LO: howto manager. (line 1286) +* BFD_RELOC_M32R_GOTPC24: howto manager. (line 1287) +* BFD_RELOC_M32R_GOTPC_HI_SLO: howto manager. (line 1292) +* BFD_RELOC_M32R_GOTPC_HI_ULO: howto manager. (line 1291) +* BFD_RELOC_M32R_GOTPC_LO: howto manager. (line 1293) +* BFD_RELOC_M32R_HI16_SLO: howto manager. (line 1269) +* BFD_RELOC_M32R_HI16_ULO: howto manager. (line 1266) +* BFD_RELOC_M32R_JMP_SLOT: howto manager. (line 1281) +* BFD_RELOC_M32R_LO16: howto manager. (line 1272) +* BFD_RELOC_M32R_RELATIVE: howto manager. (line 1282) +* BFD_RELOC_M32R_SDA16: howto manager. (line 1274) +* BFD_RELOC_M68HC11_24: howto manager. (line 2221) +* BFD_RELOC_M68HC11_3B: howto manager. (line 2201) +* BFD_RELOC_M68HC11_HI8: howto manager. (line 2195) +* BFD_RELOC_M68HC11_LO16: howto manager. (line 2212) +* BFD_RELOC_M68HC11_LO8: howto manager. (line 2198) +* BFD_RELOC_M68HC11_PAGE: howto manager. (line 2217) +* BFD_RELOC_M68HC11_RL_GROUP: howto manager. (line 2208) +* BFD_RELOC_M68HC11_RL_JUMP: howto manager. (line 2203) +* BFD_RELOC_M68HC12_10_PCREL: howto manager. (line 2264) +* BFD_RELOC_M68HC12_16B: howto manager. (line 2260) +* BFD_RELOC_M68HC12_5B: howto manager. (line 2226) +* BFD_RELOC_M68HC12_9B: howto manager. (line 2258) +* BFD_RELOC_M68HC12_9_PCREL: howto manager. (line 2262) +* BFD_RELOC_M68HC12_HI8XG: howto manager. (line 2269) +* BFD_RELOC_M68HC12_LO8XG: howto manager. (line 2266) +* BFD_RELOC_MACH_O_ARM64_ADDEND: howto manager. (line 2659) +* BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGE21: howto manager. (line 2661) +* BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGEOFF12: howto manager. (line 2663) +* BFD_RELOC_MACH_O_ARM64_POINTER_TO_GOT: howto manager. (line 2665) +* BFD_RELOC_MACH_O_LOCAL_SECTDIFF: howto manager. (line 2634) +* BFD_RELOC_MACH_O_PAIR: howto manager. (line 2636) +* BFD_RELOC_MACH_O_SECTDIFF: howto manager. (line 2631) +* BFD_RELOC_MACH_O_SUBTRACTOR32: howto manager. (line 2638) +* BFD_RELOC_MACH_O_SUBTRACTOR64: howto manager. (line 2640) +* BFD_RELOC_MACH_O_X86_64_BRANCH32: howto manager. (line 2642) +* BFD_RELOC_MACH_O_X86_64_BRANCH8: howto manager. (line 2643) +* BFD_RELOC_MACH_O_X86_64_GOT: howto manager. (line 2646) +* BFD_RELOC_MACH_O_X86_64_GOT_LOAD: howto manager. (line 2648) +* BFD_RELOC_MACH_O_X86_64_PCREL32_1: howto manager. (line 2651) +* BFD_RELOC_MACH_O_X86_64_PCREL32_2: howto manager. (line 2653) +* BFD_RELOC_MACH_O_X86_64_PCREL32_4: howto manager. (line 2655) +* BFD_RELOC_MACH_O_X86_64_TLV: howto manager. (line 2657) +* BFD_RELOC_MCORE_PCREL_32: howto manager. (line 1638) +* BFD_RELOC_MCORE_PCREL_IMM11BY2: howto manager. (line 1636) +* BFD_RELOC_MCORE_PCREL_IMM4BY2: howto manager. (line 1637) +* BFD_RELOC_MCORE_PCREL_IMM8BY4: howto manager. (line 1635) +* BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2: howto manager. (line 1639) +* BFD_RELOC_MCORE_RVA: howto manager. (line 1640) +* BFD_RELOC_MEP_16: howto manager. (line 1643) +* BFD_RELOC_MEP_32: howto manager. (line 1644) +* BFD_RELOC_MEP_8: howto manager. (line 1642) +* BFD_RELOC_MEP_ADDR24A4: howto manager. (line 1659) +* BFD_RELOC_MEP_GNU_VTENTRY: howto manager. (line 1661) +* BFD_RELOC_MEP_GNU_VTINHERIT: howto manager. (line 1660) +* BFD_RELOC_MEP_GPREL: howto manager. (line 1653) +* BFD_RELOC_MEP_HI16S: howto manager. (line 1652) +* BFD_RELOC_MEP_HI16U: howto manager. (line 1651) +* BFD_RELOC_MEP_LOW16: howto manager. (line 1650) +* BFD_RELOC_MEP_PCABS24A2: howto manager. (line 1649) +* BFD_RELOC_MEP_PCREL12A2: howto manager. (line 1646) +* BFD_RELOC_MEP_PCREL17A2: howto manager. (line 1647) +* BFD_RELOC_MEP_PCREL24A2: howto manager. (line 1648) +* BFD_RELOC_MEP_PCREL8A2: howto manager. (line 1645) +* BFD_RELOC_MEP_TPREL: howto manager. (line 1654) +* BFD_RELOC_MEP_TPREL7: howto manager. (line 1655) +* BFD_RELOC_MEP_TPREL7A2: howto manager. (line 1656) +* BFD_RELOC_MEP_TPREL7A4: howto manager. (line 1657) +* BFD_RELOC_MEP_UIMM24: howto manager. (line 1658) +* BFD_RELOC_METAG_COPY: howto manager. (line 1682) +* BFD_RELOC_METAG_GETSETOFF: howto manager. (line 1666) +* BFD_RELOC_METAG_GETSET_GOT: howto manager. (line 1674) +* BFD_RELOC_METAG_GETSET_GOTOFF: howto manager. (line 1673) +* BFD_RELOC_METAG_GLOB_DAT: howto manager. (line 1685) +* BFD_RELOC_METAG_GOTOFF: howto manager. (line 1680) +* BFD_RELOC_METAG_HI16_GOTOFF: howto manager. (line 1671) +* BFD_RELOC_METAG_HI16_GOTPC: howto manager. (line 1675) +* BFD_RELOC_METAG_HI16_PLT: howto manager. (line 1677) +* BFD_RELOC_METAG_HIADDR16: howto manager. (line 1663) +* BFD_RELOC_METAG_HIOG: howto manager. (line 1667) +* BFD_RELOC_METAG_JMP_SLOT: howto manager. (line 1683) +* BFD_RELOC_METAG_LO16_GOTOFF: howto manager. (line 1672) +* BFD_RELOC_METAG_LO16_GOTPC: howto manager. (line 1676) +* BFD_RELOC_METAG_LO16_PLT: howto manager. (line 1678) +* BFD_RELOC_METAG_LOADDR16: howto manager. (line 1664) +* BFD_RELOC_METAG_LOOG: howto manager. (line 1668) +* BFD_RELOC_METAG_PLT: howto manager. (line 1681) +* BFD_RELOC_METAG_REL16: howto manager. (line 1670) +* BFD_RELOC_METAG_REL8: howto manager. (line 1669) +* BFD_RELOC_METAG_RELATIVE: howto manager. (line 1684) +* BFD_RELOC_METAG_RELBRANCH: howto manager. (line 1665) +* BFD_RELOC_METAG_RELBRANCH_PLT: howto manager. (line 1679) +* BFD_RELOC_METAG_TLS_DTPMOD: howto manager. (line 1696) +* BFD_RELOC_METAG_TLS_DTPOFF: howto manager. (line 1697) +* BFD_RELOC_METAG_TLS_GD: howto manager. (line 1686) +* BFD_RELOC_METAG_TLS_IE: howto manager. (line 1691) +* BFD_RELOC_METAG_TLS_IENONPIC: howto manager. (line 1692) +* BFD_RELOC_METAG_TLS_IENONPIC_HI16: howto manager. (line 1693) +* BFD_RELOC_METAG_TLS_IENONPIC_LO16: howto manager. (line 1694) +* BFD_RELOC_METAG_TLS_LDM: howto manager. (line 1687) +* BFD_RELOC_METAG_TLS_LDO: howto manager. (line 1690) +* BFD_RELOC_METAG_TLS_LDO_HI16: howto manager. (line 1688) +* BFD_RELOC_METAG_TLS_LDO_LO16: howto manager. (line 1689) +* BFD_RELOC_METAG_TLS_LE: howto manager. (line 1698) +* BFD_RELOC_METAG_TLS_LE_HI16: howto manager. (line 1699) +* BFD_RELOC_METAG_TLS_LE_LO16: howto manager. (line 1700) +* BFD_RELOC_METAG_TLS_TPOFF: howto manager. (line 1695) +* BFD_RELOC_MICROBLAZE_32_GOTOFF: howto manager. (line 2705) +* BFD_RELOC_MICROBLAZE_32_LO: howto manager. (line 2667) +* BFD_RELOC_MICROBLAZE_32_LO_PCREL: howto manager. (line 2670) +* BFD_RELOC_MICROBLAZE_32_NONE: howto manager. (line 2682) +* BFD_RELOC_MICROBLAZE_32_ROSDA: howto manager. (line 2673) +* BFD_RELOC_MICROBLAZE_32_RWSDA: howto manager. (line 2676) +* BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM: howto manager. (line 2679) +* BFD_RELOC_MICROBLAZE_32_TLSDTPMOD: howto manager. (line 2722) +* BFD_RELOC_MICROBLAZE_32_TLSDTPREL: howto manager. (line 2724) +* BFD_RELOC_MICROBLAZE_64_GOT: howto manager. (line 2694) +* BFD_RELOC_MICROBLAZE_64_GOTOFF: howto manager. (line 2701) +* BFD_RELOC_MICROBLAZE_64_GOTPC: howto manager. (line 2690) +* BFD_RELOC_MICROBLAZE_64_NONE: howto manager. (line 2686) +* BFD_RELOC_MICROBLAZE_64_PLT: howto manager. (line 2697) +* BFD_RELOC_MICROBLAZE_64_TEXTPCREL: howto manager. (line 2735) +* BFD_RELOC_MICROBLAZE_64_TEXTREL: howto manager. (line 2739) +* BFD_RELOC_MICROBLAZE_64_TLS: howto manager. (line 2712) +* BFD_RELOC_MICROBLAZE_64_TLSDTPREL: howto manager. (line 2726) +* BFD_RELOC_MICROBLAZE_64_TLSGD: howto manager. (line 2714) +* BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL: howto manager. (line 2729) +* BFD_RELOC_MICROBLAZE_64_TLSLD: howto manager. (line 2718) +* BFD_RELOC_MICROBLAZE_64_TLSTPREL: howto manager. (line 2732) +* BFD_RELOC_MICROBLAZE_COPY: howto manager. (line 2709) +* BFD_RELOC_MICROMIPS_10_PCREL_S1: howto manager. (line 352) +* BFD_RELOC_MICROMIPS_16_PCREL_S1: howto manager. (line 353) +* BFD_RELOC_MICROMIPS_7_PCREL_S1: howto manager. (line 351) +* BFD_RELOC_MICROMIPS_CALL16: howto manager. (line 370) +* BFD_RELOC_MICROMIPS_CALL_HI16: howto manager. (line 376) +* BFD_RELOC_MICROMIPS_CALL_LO16: howto manager. (line 378) +* BFD_RELOC_MICROMIPS_GOT16: howto manager. (line 368) +* BFD_RELOC_MICROMIPS_GOT_DISP: howto manager. (line 386) +* BFD_RELOC_MICROMIPS_GOT_HI16: howto manager. (line 372) +* BFD_RELOC_MICROMIPS_GOT_LO16: howto manager. (line 374) +* BFD_RELOC_MICROMIPS_GOT_OFST: howto manager. (line 384) +* BFD_RELOC_MICROMIPS_GOT_PAGE: howto manager. (line 382) +* BFD_RELOC_MICROMIPS_GPREL16: howto manager. (line 362) +* BFD_RELOC_MICROMIPS_HI16: howto manager. (line 363) +* BFD_RELOC_MICROMIPS_HI16_S: howto manager. (line 364) +* BFD_RELOC_MICROMIPS_HIGHER: howto manager. (line 395) +* BFD_RELOC_MICROMIPS_HIGHEST: howto manager. (line 393) +* BFD_RELOC_MICROMIPS_JALR: howto manager. (line 401) +* BFD_RELOC_MICROMIPS_JMP: howto manager. (line 306) +* BFD_RELOC_MICROMIPS_LITERAL: howto manager. (line 349) +* BFD_RELOC_MICROMIPS_LO16: howto manager. (line 365) +* BFD_RELOC_MICROMIPS_SCN_DISP: howto manager. (line 397) +* BFD_RELOC_MICROMIPS_SUB: howto manager. (line 380) +* BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16: howto manager. (line 411) +* BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16: howto manager. (line 413) +* BFD_RELOC_MICROMIPS_TLS_GD: howto manager. (line 407) +* BFD_RELOC_MICROMIPS_TLS_GOTTPREL: howto manager. (line 415) +* BFD_RELOC_MICROMIPS_TLS_LDM: howto manager. (line 409) +* BFD_RELOC_MICROMIPS_TLS_TPREL_HI16: howto manager. (line 419) +* BFD_RELOC_MICROMIPS_TLS_TPREL_LO16: howto manager. (line 421) +* BFD_RELOC_MIPS16_16_PCREL_S1: howto manager. (line 355) +* BFD_RELOC_MIPS16_CALL16: howto manager. (line 328) +* BFD_RELOC_MIPS16_GOT16: howto manager. (line 327) +* BFD_RELOC_MIPS16_GPREL: howto manager. (line 310) +* BFD_RELOC_MIPS16_HI16: howto manager. (line 331) +* BFD_RELOC_MIPS16_HI16_S: howto manager. (line 333) +* BFD_RELOC_MIPS16_JMP: howto manager. (line 308) +* BFD_RELOC_MIPS16_LO16: howto manager. (line 338) +* BFD_RELOC_MIPS16_TLS_DTPREL_HI16: howto manager. (line 342) +* BFD_RELOC_MIPS16_TLS_DTPREL_LO16: howto manager. (line 343) +* BFD_RELOC_MIPS16_TLS_GD: howto manager. (line 340) +* BFD_RELOC_MIPS16_TLS_GOTTPREL: howto manager. (line 344) +* BFD_RELOC_MIPS16_TLS_LDM: howto manager. (line 341) +* BFD_RELOC_MIPS16_TLS_TPREL_HI16: howto manager. (line 345) +* BFD_RELOC_MIPS16_TLS_TPREL_LO16: howto manager. (line 346) +* BFD_RELOC_MIPS_16: howto manager. (line 398) +* BFD_RELOC_MIPS_18_PCREL_S3: howto manager. (line 359) +* BFD_RELOC_MIPS_19_PCREL_S2: howto manager. (line 360) +* BFD_RELOC_MIPS_21_PCREL_S2: howto manager. (line 357) +* BFD_RELOC_MIPS_26_PCREL_S2: howto manager. (line 358) +* BFD_RELOC_MIPS_CALL16: howto manager. (line 369) +* BFD_RELOC_MIPS_CALL_HI16: howto manager. (line 375) +* BFD_RELOC_MIPS_CALL_LO16: howto manager. (line 377) +* BFD_RELOC_MIPS_COPY: howto manager. (line 424) +* BFD_RELOC_MIPS_DELETE: howto manager. (line 391) +* BFD_RELOC_MIPS_EH: howto manager. (line 422) +* BFD_RELOC_MIPS_GOT16: howto manager. (line 367) +* BFD_RELOC_MIPS_GOT_DISP: howto manager. (line 385) +* BFD_RELOC_MIPS_GOT_HI16: howto manager. (line 371) +* BFD_RELOC_MIPS_GOT_LO16: howto manager. (line 373) +* BFD_RELOC_MIPS_GOT_OFST: howto manager. (line 383) +* BFD_RELOC_MIPS_GOT_PAGE: howto manager. (line 381) +* BFD_RELOC_MIPS_HIGHER: howto manager. (line 394) +* BFD_RELOC_MIPS_HIGHEST: howto manager. (line 392) +* BFD_RELOC_MIPS_INSERT_A: howto manager. (line 389) +* BFD_RELOC_MIPS_INSERT_B: howto manager. (line 390) +* BFD_RELOC_MIPS_JALR: howto manager. (line 400) +* BFD_RELOC_MIPS_JMP: howto manager. (line 305) +* BFD_RELOC_MIPS_JUMP_SLOT: howto manager. (line 425) +* BFD_RELOC_MIPS_LITERAL: howto manager. (line 348) +* BFD_RELOC_MIPS_RELGOT: howto manager. (line 399) +* BFD_RELOC_MIPS_SCN_DISP: howto manager. (line 396) +* BFD_RELOC_MIPS_SHIFT5: howto manager. (line 387) +* BFD_RELOC_MIPS_SHIFT6: howto manager. (line 388) +* BFD_RELOC_MIPS_SUB: howto manager. (line 379) +* BFD_RELOC_MIPS_TLS_DTPMOD32: howto manager. (line 402) +* BFD_RELOC_MIPS_TLS_DTPMOD64: howto manager. (line 404) +* BFD_RELOC_MIPS_TLS_DTPREL32: howto manager. (line 403) +* BFD_RELOC_MIPS_TLS_DTPREL64: howto manager. (line 405) +* BFD_RELOC_MIPS_TLS_DTPREL_HI16: howto manager. (line 410) +* BFD_RELOC_MIPS_TLS_DTPREL_LO16: howto manager. (line 412) +* BFD_RELOC_MIPS_TLS_GD: howto manager. (line 406) +* BFD_RELOC_MIPS_TLS_GOTTPREL: howto manager. (line 414) +* BFD_RELOC_MIPS_TLS_LDM: howto manager. (line 408) +* BFD_RELOC_MIPS_TLS_TPREL32: howto manager. (line 416) +* BFD_RELOC_MIPS_TLS_TPREL64: howto manager. (line 417) +* BFD_RELOC_MIPS_TLS_TPREL_HI16: howto manager. (line 418) +* BFD_RELOC_MIPS_TLS_TPREL_LO16: howto manager. (line 420) +* BFD_RELOC_MMIX_ADDR19: howto manager. (line 1724) +* BFD_RELOC_MMIX_ADDR27: howto manager. (line 1727) +* BFD_RELOC_MMIX_BASE_PLUS_OFFSET: howto manager. (line 1736) +* BFD_RELOC_MMIX_CBRANCH: howto manager. (line 1707) +* BFD_RELOC_MMIX_CBRANCH_1: howto manager. (line 1709) +* BFD_RELOC_MMIX_CBRANCH_2: howto manager. (line 1710) +* BFD_RELOC_MMIX_CBRANCH_3: howto manager. (line 1711) +* BFD_RELOC_MMIX_CBRANCH_J: howto manager. (line 1708) +* BFD_RELOC_MMIX_GETA: howto manager. (line 1702) +* BFD_RELOC_MMIX_GETA_1: howto manager. (line 1703) +* BFD_RELOC_MMIX_GETA_2: howto manager. (line 1704) +* BFD_RELOC_MMIX_GETA_3: howto manager. (line 1705) +* BFD_RELOC_MMIX_JMP: howto manager. (line 1719) +* BFD_RELOC_MMIX_JMP_1: howto manager. (line 1720) +* BFD_RELOC_MMIX_JMP_2: howto manager. (line 1721) +* BFD_RELOC_MMIX_JMP_3: howto manager. (line 1722) +* BFD_RELOC_MMIX_LOCAL: howto manager. (line 1739) +* BFD_RELOC_MMIX_PUSHJ: howto manager. (line 1713) +* BFD_RELOC_MMIX_PUSHJ_1: howto manager. (line 1714) +* BFD_RELOC_MMIX_PUSHJ_2: howto manager. (line 1715) +* BFD_RELOC_MMIX_PUSHJ_3: howto manager. (line 1716) +* BFD_RELOC_MMIX_PUSHJ_STUBBABLE: howto manager. (line 1717) +* BFD_RELOC_MMIX_REG: howto manager. (line 1733) +* BFD_RELOC_MMIX_REG_OR_BYTE: howto manager. (line 1730) +* BFD_RELOC_MN10300_16_PCREL: howto manager. (line 518) +* BFD_RELOC_MN10300_32_PCREL: howto manager. (line 515) +* BFD_RELOC_MN10300_ALIGN: howto manager. (line 502) +* BFD_RELOC_MN10300_COPY: howto manager. (line 490) +* BFD_RELOC_MN10300_GLOB_DAT: howto manager. (line 492) +* BFD_RELOC_MN10300_GOT16: howto manager. (line 487) +* BFD_RELOC_MN10300_GOT24: howto manager. (line 484) +* BFD_RELOC_MN10300_GOT32: howto manager. (line 481) +* BFD_RELOC_MN10300_GOTOFF24: howto manager. (line 479) +* BFD_RELOC_MN10300_JMP_SLOT: howto manager. (line 494) +* BFD_RELOC_MN10300_RELATIVE: howto manager. (line 496) +* BFD_RELOC_MN10300_SYM_DIFF: howto manager. (line 498) +* BFD_RELOC_MN10300_TLS_DTPMOD: howto manager. (line 511) +* BFD_RELOC_MN10300_TLS_DTPOFF: howto manager. (line 512) +* BFD_RELOC_MN10300_TLS_GD: howto manager. (line 505) +* BFD_RELOC_MN10300_TLS_GOTIE: howto manager. (line 508) +* BFD_RELOC_MN10300_TLS_IE: howto manager. (line 509) +* BFD_RELOC_MN10300_TLS_LD: howto manager. (line 506) +* BFD_RELOC_MN10300_TLS_LDO: howto manager. (line 507) +* BFD_RELOC_MN10300_TLS_LE: howto manager. (line 510) +* BFD_RELOC_MN10300_TLS_TPOFF: howto manager. (line 513) +* BFD_RELOC_MOXIE_10_PCREL: howto manager. (line 427) +* BFD_RELOC_MSP430X_ABS16: howto manager. (line 2465) +* BFD_RELOC_MSP430X_ABS20_ADR_DST: howto manager. (line 2462) +* BFD_RELOC_MSP430X_ABS20_ADR_SRC: howto manager. (line 2461) +* BFD_RELOC_MSP430X_ABS20_EXT_DST: howto manager. (line 2459) +* BFD_RELOC_MSP430X_ABS20_EXT_ODST: howto manager. (line 2460) +* BFD_RELOC_MSP430X_ABS20_EXT_SRC: howto manager. (line 2458) +* BFD_RELOC_MSP430X_PCR16: howto manager. (line 2463) +* BFD_RELOC_MSP430X_PCR20_CALL: howto manager. (line 2464) +* BFD_RELOC_MSP430X_PCR20_EXT_DST: howto manager. (line 2456) +* BFD_RELOC_MSP430X_PCR20_EXT_ODST: howto manager. (line 2457) +* BFD_RELOC_MSP430X_PCR20_EXT_SRC: howto manager. (line 2455) +* BFD_RELOC_MSP430_10_PCREL: howto manager. (line 2447) +* BFD_RELOC_MSP430_16: howto manager. (line 2449) +* BFD_RELOC_MSP430_16_BYTE: howto manager. (line 2451) +* BFD_RELOC_MSP430_16_PCREL: howto manager. (line 2448) +* BFD_RELOC_MSP430_16_PCREL_BYTE: howto manager. (line 2450) +* BFD_RELOC_MSP430_2X_PCREL: howto manager. (line 2452) +* BFD_RELOC_MSP430_ABS8: howto manager. (line 2454) +* BFD_RELOC_MSP430_ABS_HI16: howto manager. (line 2466) +* BFD_RELOC_MSP430_PREL31: howto manager. (line 2467) +* BFD_RELOC_MSP430_RL_PCREL: howto manager. (line 2453) +* BFD_RELOC_MSP430_SET_ULEB128: howto manager. (line 2469) +* BFD_RELOC_MSP430_SUB_ULEB128: howto manager. (line 2470) +* BFD_RELOC_MSP430_SYM_DIFF: howto manager. (line 2468) +* BFD_RELOC_MT_GNU_VTENTRY: howto manager. (line 2443) +* BFD_RELOC_MT_GNU_VTINHERIT: howto manager. (line 2441) +* BFD_RELOC_MT_HI16: howto manager. (line 2437) +* BFD_RELOC_MT_LO16: howto manager. (line 2439) +* BFD_RELOC_MT_PC16: howto manager. (line 2435) +* BFD_RELOC_MT_PCINSN8: howto manager. (line 2445) +* BFD_RELOC_NDS32_10IFCU_PCREL: howto manager. (line 1445) +* BFD_RELOC_NDS32_10_UPCREL: howto manager. (line 1416) +* BFD_RELOC_NDS32_15_FIXED: howto manager. (line 1377) +* BFD_RELOC_NDS32_15_PCREL: howto manager. (line 1303) +* BFD_RELOC_NDS32_17IFC_PCREL: howto manager. (line 1444) +* BFD_RELOC_NDS32_17_FIXED: howto manager. (line 1378) +* BFD_RELOC_NDS32_17_PCREL: howto manager. (line 1305) +* BFD_RELOC_NDS32_20: howto manager. (line 1295) +* BFD_RELOC_NDS32_25_ABS: howto manager. (line 1440) +* BFD_RELOC_NDS32_25_FIXED: howto manager. (line 1379) +* BFD_RELOC_NDS32_25_PCREL: howto manager. (line 1307) +* BFD_RELOC_NDS32_25_PLTREL: howto manager. (line 1353) +* BFD_RELOC_NDS32_5: howto manager. (line 1414) +* BFD_RELOC_NDS32_9_FIXED: howto manager. (line 1376) +* BFD_RELOC_NDS32_9_PCREL: howto manager. (line 1297) +* BFD_RELOC_NDS32_9_PLTREL: howto manager. (line 1352) +* BFD_RELOC_NDS32_COPY: howto manager. (line 1354) +* BFD_RELOC_NDS32_DATA: howto manager. (line 1442) +* BFD_RELOC_NDS32_DIFF16: howto manager. (line 1435) +* BFD_RELOC_NDS32_DIFF32: howto manager. (line 1436) +* BFD_RELOC_NDS32_DIFF8: howto manager. (line 1434) +* BFD_RELOC_NDS32_DIFF_ULEB128: howto manager. (line 1437) +* BFD_RELOC_NDS32_DWARF2_LEB: howto manager. (line 1400) +* BFD_RELOC_NDS32_DWARF2_OP1: howto manager. (line 1398) +* BFD_RELOC_NDS32_DWARF2_OP2: howto manager. (line 1399) +* BFD_RELOC_NDS32_EMPTY: howto manager. (line 1438) +* BFD_RELOC_NDS32_GLOB_DAT: howto manager. (line 1355) +* BFD_RELOC_NDS32_GOT15S2: howto manager. (line 1411) +* BFD_RELOC_NDS32_GOT17S2: howto manager. (line 1412) +* BFD_RELOC_NDS32_GOT20: howto manager. (line 1351) +* BFD_RELOC_NDS32_GOTOFF: howto manager. (line 1358) +* BFD_RELOC_NDS32_GOTOFF_HI20: howto manager. (line 1359) +* BFD_RELOC_NDS32_GOTOFF_LO12: howto manager. (line 1360) +* BFD_RELOC_NDS32_GOTOFF_LO15: howto manager. (line 1409) +* BFD_RELOC_NDS32_GOTOFF_LO19: howto manager. (line 1410) +* BFD_RELOC_NDS32_GOTOFF_SUFF: howto manager. (line 1423) +* BFD_RELOC_NDS32_GOTPC20: howto manager. (line 1361) +* BFD_RELOC_NDS32_GOTPC_HI20: howto manager. (line 1364) +* BFD_RELOC_NDS32_GOTPC_LO12: howto manager. (line 1365) +* BFD_RELOC_NDS32_GOTTPOFF: howto manager. (line 1448) +* BFD_RELOC_NDS32_GOT_HI20: howto manager. (line 1362) +* BFD_RELOC_NDS32_GOT_LO12: howto manager. (line 1363) +* BFD_RELOC_NDS32_GOT_LO15: howto manager. (line 1407) +* BFD_RELOC_NDS32_GOT_LO19: howto manager. (line 1408) +* BFD_RELOC_NDS32_GOT_SUFF: howto manager. (line 1422) +* BFD_RELOC_NDS32_GROUP: howto manager. (line 1474) +* BFD_RELOC_NDS32_HI20: howto manager. (line 1309) +* BFD_RELOC_NDS32_INSN16: howto manager. (line 1367) +* BFD_RELOC_NDS32_JMP_SLOT: howto manager. (line 1356) +* BFD_RELOC_NDS32_LABEL: howto manager. (line 1368) +* BFD_RELOC_NDS32_LO12S0: howto manager. (line 1321) +* BFD_RELOC_NDS32_LO12S0_ORI: howto manager. (line 1324) +* BFD_RELOC_NDS32_LO12S1: howto manager. (line 1318) +* BFD_RELOC_NDS32_LO12S2: howto manager. (line 1315) +* BFD_RELOC_NDS32_LO12S2_DP: howto manager. (line 1395) +* BFD_RELOC_NDS32_LO12S2_SP: howto manager. (line 1396) +* BFD_RELOC_NDS32_LO12S3: howto manager. (line 1312) +* BFD_RELOC_NDS32_LOADSTORE: howto manager. (line 1375) +* BFD_RELOC_NDS32_LONGCALL1: howto manager. (line 1369) +* BFD_RELOC_NDS32_LONGCALL2: howto manager. (line 1370) +* BFD_RELOC_NDS32_LONGCALL3: howto manager. (line 1371) +* BFD_RELOC_NDS32_LONGCALL4: howto manager. (line 1380) +* BFD_RELOC_NDS32_LONGCALL5: howto manager. (line 1381) +* BFD_RELOC_NDS32_LONGCALL6: howto manager. (line 1382) +* BFD_RELOC_NDS32_LONGJUMP1: howto manager. (line 1372) +* BFD_RELOC_NDS32_LONGJUMP2: howto manager. (line 1373) +* BFD_RELOC_NDS32_LONGJUMP3: howto manager. (line 1374) +* BFD_RELOC_NDS32_LONGJUMP4: howto manager. (line 1383) +* BFD_RELOC_NDS32_LONGJUMP5: howto manager. (line 1384) +* BFD_RELOC_NDS32_LONGJUMP6: howto manager. (line 1385) +* BFD_RELOC_NDS32_LONGJUMP7: howto manager. (line 1386) +* BFD_RELOC_NDS32_LSI: howto manager. (line 1476) +* BFD_RELOC_NDS32_MINUEND: howto manager. (line 1432) +* BFD_RELOC_NDS32_MULCALL_SUFF: howto manager. (line 1425) +* BFD_RELOC_NDS32_PLTBLOCK: howto manager. (line 1429) +* BFD_RELOC_NDS32_PLTREL_HI20: howto manager. (line 1388) +* BFD_RELOC_NDS32_PLTREL_LO12: howto manager. (line 1389) +* BFD_RELOC_NDS32_PLT_GOTREL_HI20: howto manager. (line 1390) +* BFD_RELOC_NDS32_PLT_GOTREL_LO12: howto manager. (line 1391) +* BFD_RELOC_NDS32_PLT_GOTREL_LO15: howto manager. (line 1405) +* BFD_RELOC_NDS32_PLT_GOTREL_LO19: howto manager. (line 1406) +* BFD_RELOC_NDS32_PLT_GOTREL_LO20: howto manager. (line 1404) +* BFD_RELOC_NDS32_PLT_GOT_SUFF: howto manager. (line 1424) +* BFD_RELOC_NDS32_PTR: howto manager. (line 1426) +* BFD_RELOC_NDS32_PTR_COUNT: howto manager. (line 1427) +* BFD_RELOC_NDS32_PTR_RESOLVED: howto manager. (line 1428) +* BFD_RELOC_NDS32_RELATIVE: howto manager. (line 1357) +* BFD_RELOC_NDS32_RELAX_ENTRY: howto manager. (line 1421) +* BFD_RELOC_NDS32_RELAX_REGION_BEGIN: howto manager. (line 1430) +* BFD_RELOC_NDS32_RELAX_REGION_END: howto manager. (line 1431) +* BFD_RELOC_NDS32_REMOVE: howto manager. (line 1473) +* BFD_RELOC_NDS32_SDA12S2_DP: howto manager. (line 1393) +* BFD_RELOC_NDS32_SDA12S2_SP: howto manager. (line 1394) +* BFD_RELOC_NDS32_SDA15S0: howto manager. (line 1336) +* BFD_RELOC_NDS32_SDA15S1: howto manager. (line 1333) +* BFD_RELOC_NDS32_SDA15S2: howto manager. (line 1330) +* BFD_RELOC_NDS32_SDA15S3: howto manager. (line 1327) +* BFD_RELOC_NDS32_SDA16S3: howto manager. (line 1339) +* BFD_RELOC_NDS32_SDA17S2: howto manager. (line 1342) +* BFD_RELOC_NDS32_SDA18S1: howto manager. (line 1345) +* BFD_RELOC_NDS32_SDA19S0: howto manager. (line 1348) +* BFD_RELOC_NDS32_SDA_FP7U2_RELA: howto manager. (line 1419) +* BFD_RELOC_NDS32_SUBTRAHEND: howto manager. (line 1433) +* BFD_RELOC_NDS32_TLS_DESC: howto manager. (line 1464) +* BFD_RELOC_NDS32_TLS_DESC_20: howto manager. (line 1467) +* BFD_RELOC_NDS32_TLS_DESC_ADD: howto manager. (line 1469) +* BFD_RELOC_NDS32_TLS_DESC_CALL: howto manager. (line 1471) +* BFD_RELOC_NDS32_TLS_DESC_FUNC: howto manager. (line 1470) +* BFD_RELOC_NDS32_TLS_DESC_HI20: howto manager. (line 1465) +* BFD_RELOC_NDS32_TLS_DESC_LO12: howto manager. (line 1466) +* BFD_RELOC_NDS32_TLS_DESC_MEM: howto manager. (line 1472) +* BFD_RELOC_NDS32_TLS_DESC_SDA17S2: howto manager. (line 1468) +* BFD_RELOC_NDS32_TLS_IEGP_HI20: howto manager. (line 1460) +* BFD_RELOC_NDS32_TLS_IEGP_LO12: howto manager. (line 1461) +* BFD_RELOC_NDS32_TLS_IEGP_LO12S2: howto manager. (line 1462) +* BFD_RELOC_NDS32_TLS_IEGP_LW: howto manager. (line 1463) +* BFD_RELOC_NDS32_TLS_IE_HI20: howto manager. (line 1457) +* BFD_RELOC_NDS32_TLS_IE_LO12: howto manager. (line 1458) +* BFD_RELOC_NDS32_TLS_IE_LO12S2: howto manager. (line 1459) +* BFD_RELOC_NDS32_TLS_LE_15S0: howto manager. (line 1452) +* BFD_RELOC_NDS32_TLS_LE_15S1: howto manager. (line 1453) +* BFD_RELOC_NDS32_TLS_LE_15S2: howto manager. (line 1454) +* BFD_RELOC_NDS32_TLS_LE_20: howto manager. (line 1451) +* BFD_RELOC_NDS32_TLS_LE_ADD: howto manager. (line 1455) +* BFD_RELOC_NDS32_TLS_LE_HI20: howto manager. (line 1449) +* BFD_RELOC_NDS32_TLS_LE_LO12: howto manager. (line 1450) +* BFD_RELOC_NDS32_TLS_LE_LS: howto manager. (line 1456) +* BFD_RELOC_NDS32_TPOFF: howto manager. (line 1447) +* BFD_RELOC_NDS32_TRAN: howto manager. (line 1443) +* BFD_RELOC_NDS32_UPDATE_TA: howto manager. (line 1402) +* BFD_RELOC_NDS32_WORD_9_PCREL: howto manager. (line 1300) +* BFD_RELOC_NONE: howto manager. (line 118) +* BFD_RELOC_NS32K_DISP_16: howto manager. (line 595) +* BFD_RELOC_NS32K_DISP_16_PCREL: howto manager. (line 598) +* BFD_RELOC_NS32K_DISP_32: howto manager. (line 596) +* BFD_RELOC_NS32K_DISP_32_PCREL: howto manager. (line 599) +* BFD_RELOC_NS32K_DISP_8: howto manager. (line 594) +* BFD_RELOC_NS32K_DISP_8_PCREL: howto manager. (line 597) +* BFD_RELOC_NS32K_IMM_16: howto manager. (line 589) +* BFD_RELOC_NS32K_IMM_16_PCREL: howto manager. (line 592) +* BFD_RELOC_NS32K_IMM_32: howto manager. (line 590) +* BFD_RELOC_NS32K_IMM_32_PCREL: howto manager. (line 593) +* BFD_RELOC_NS32K_IMM_8: howto manager. (line 588) +* BFD_RELOC_NS32K_IMM_8_PCREL: howto manager. (line 591) +* bfd_reloc_offset_in_range: typedef arelent. (line 303) +* bfd_reloc_offset_in_range <1>: typedef arelent. (line 307) +* BFD_RELOC_OR1K_COPY: howto manager. (line 2390) +* BFD_RELOC_OR1K_GLOB_DAT: howto manager. (line 2391) +* BFD_RELOC_OR1K_GOT16: howto manager. (line 2384) +* BFD_RELOC_OR1K_GOTOFF_SLO16: howto manager. (line 2389) +* BFD_RELOC_OR1K_GOTPC_HI16: howto manager. (line 2381) +* BFD_RELOC_OR1K_GOTPC_LO16: howto manager. (line 2382) +* BFD_RELOC_OR1K_GOT_AHI16: howto manager. (line 2383) +* BFD_RELOC_OR1K_GOT_LO13: howto manager. (line 2386) +* BFD_RELOC_OR1K_GOT_PG21: howto manager. (line 2385) +* BFD_RELOC_OR1K_JMP_SLOT: howto manager. (line 2392) +* BFD_RELOC_OR1K_LO13: howto manager. (line 2379) +* BFD_RELOC_OR1K_PCREL_PG21: howto manager. (line 2378) +* BFD_RELOC_OR1K_PLT26: howto manager. (line 2387) +* BFD_RELOC_OR1K_PLTA26: howto manager. (line 2388) +* BFD_RELOC_OR1K_RELATIVE: howto manager. (line 2393) +* BFD_RELOC_OR1K_REL_26: howto manager. (line 2376) +* BFD_RELOC_OR1K_SLO13: howto manager. (line 2380) +* BFD_RELOC_OR1K_SLO16: howto manager. (line 2377) +* BFD_RELOC_OR1K_TLS_DTPMOD: howto manager. (line 2415) +* BFD_RELOC_OR1K_TLS_DTPOFF: howto manager. (line 2414) +* BFD_RELOC_OR1K_TLS_GD_HI16: howto manager. (line 2394) +* BFD_RELOC_OR1K_TLS_GD_LO13: howto manager. (line 2397) +* BFD_RELOC_OR1K_TLS_GD_LO16: howto manager. (line 2395) +* BFD_RELOC_OR1K_TLS_GD_PG21: howto manager. (line 2396) +* BFD_RELOC_OR1K_TLS_IE_AHI16: howto manager. (line 2405) +* BFD_RELOC_OR1K_TLS_IE_HI16: howto manager. (line 2404) +* BFD_RELOC_OR1K_TLS_IE_LO13: howto manager. (line 2408) +* BFD_RELOC_OR1K_TLS_IE_LO16: howto manager. (line 2406) +* BFD_RELOC_OR1K_TLS_IE_PG21: howto manager. (line 2407) +* BFD_RELOC_OR1K_TLS_LDM_HI16: howto manager. (line 2398) +* BFD_RELOC_OR1K_TLS_LDM_LO13: howto manager. (line 2401) +* BFD_RELOC_OR1K_TLS_LDM_LO16: howto manager. (line 2399) +* BFD_RELOC_OR1K_TLS_LDM_PG21: howto manager. (line 2400) +* BFD_RELOC_OR1K_TLS_LDO_HI16: howto manager. (line 2402) +* BFD_RELOC_OR1K_TLS_LDO_LO16: howto manager. (line 2403) +* BFD_RELOC_OR1K_TLS_LE_AHI16: howto manager. (line 2410) +* BFD_RELOC_OR1K_TLS_LE_HI16: howto manager. (line 2409) +* BFD_RELOC_OR1K_TLS_LE_LO16: howto manager. (line 2411) +* BFD_RELOC_OR1K_TLS_LE_SLO16: howto manager. (line 2412) +* BFD_RELOC_OR1K_TLS_TPOFF: howto manager. (line 2413) +* BFD_RELOC_PDP11_DISP_6_PCREL: howto manager. (line 602) +* BFD_RELOC_PDP11_DISP_8_PCREL: howto manager. (line 601) +* BFD_RELOC_PJ_CODE_DIR16: howto manager. (line 606) +* BFD_RELOC_PJ_CODE_DIR32: howto manager. (line 607) +* BFD_RELOC_PJ_CODE_HI16: howto manager. (line 604) +* BFD_RELOC_PJ_CODE_LO16: howto manager. (line 605) +* BFD_RELOC_PJ_CODE_REL16: howto manager. (line 608) +* BFD_RELOC_PJ_CODE_REL32: howto manager. (line 609) +* BFD_RELOC_PPC64_ADDR16_DS: howto manager. (line 675) +* BFD_RELOC_PPC64_ADDR16_HIGH: howto manager. (line 686) +* BFD_RELOC_PPC64_ADDR16_HIGHA: howto manager. (line 687) +* BFD_RELOC_PPC64_ADDR16_HIGHER34: howto manager. (line 705) +* BFD_RELOC_PPC64_ADDR16_HIGHERA34: howto manager. (line 706) +* BFD_RELOC_PPC64_ADDR16_HIGHEST34: howto manager. (line 707) +* BFD_RELOC_PPC64_ADDR16_HIGHESTA34: howto manager. (line 708) +* BFD_RELOC_PPC64_ADDR16_LO_DS: howto manager. (line 676) +* BFD_RELOC_PPC64_ADDR64_LOCAL: howto manager. (line 694) +* BFD_RELOC_PPC64_D28: howto manager. (line 713) +* BFD_RELOC_PPC64_D34: howto manager. (line 698) +* BFD_RELOC_PPC64_D34_HA30: howto manager. (line 701) +* BFD_RELOC_PPC64_D34_HI30: howto manager. (line 700) +* BFD_RELOC_PPC64_D34_LO: howto manager. (line 699) +* BFD_RELOC_PPC64_DTPREL16_DS: howto manager. (line 764) +* BFD_RELOC_PPC64_DTPREL16_HIGH: howto manager. (line 766) +* BFD_RELOC_PPC64_DTPREL16_HIGHA: howto manager. (line 767) +* BFD_RELOC_PPC64_DTPREL16_HIGHER: howto manager. (line 768) +* BFD_RELOC_PPC64_DTPREL16_HIGHERA: howto manager. (line 769) +* BFD_RELOC_PPC64_DTPREL16_HIGHEST: howto manager. (line 770) +* BFD_RELOC_PPC64_DTPREL16_HIGHESTA: howto manager. (line 771) +* BFD_RELOC_PPC64_DTPREL16_LO_DS: howto manager. (line 765) +* BFD_RELOC_PPC64_DTPREL34: howto manager. (line 773) +* BFD_RELOC_PPC64_ENTRY: howto manager. (line 695) +* BFD_RELOC_PPC64_GOT16_DS: howto manager. (line 677) +* BFD_RELOC_PPC64_GOT16_LO_DS: howto manager. (line 678) +* BFD_RELOC_PPC64_GOT_DTPREL_PCREL34: howto manager. (line 777) +* BFD_RELOC_PPC64_GOT_PCREL34: howto manager. (line 703) +* BFD_RELOC_PPC64_GOT_TLSGD_PCREL34: howto manager. (line 774) +* BFD_RELOC_PPC64_GOT_TLSLD_PCREL34: howto manager. (line 775) +* BFD_RELOC_PPC64_GOT_TPREL_PCREL34: howto manager. (line 776) +* BFD_RELOC_PPC64_HIGHER: howto manager. (line 663) +* BFD_RELOC_PPC64_HIGHER_S: howto manager. (line 664) +* BFD_RELOC_PPC64_HIGHEST: howto manager. (line 665) +* BFD_RELOC_PPC64_HIGHEST_S: howto manager. (line 666) +* BFD_RELOC_PPC64_PCREL28: howto manager. (line 714) +* BFD_RELOC_PPC64_PCREL34: howto manager. (line 702) +* BFD_RELOC_PPC64_PLT16_LO_DS: howto manager. (line 679) +* BFD_RELOC_PPC64_PLTGOT16: howto manager. (line 671) +* BFD_RELOC_PPC64_PLTGOT16_DS: howto manager. (line 684) +* BFD_RELOC_PPC64_PLTGOT16_HA: howto manager. (line 674) +* BFD_RELOC_PPC64_PLTGOT16_HI: howto manager. (line 673) +* BFD_RELOC_PPC64_PLTGOT16_LO: howto manager. (line 672) +* BFD_RELOC_PPC64_PLTGOT16_LO_DS: howto manager. (line 685) +* BFD_RELOC_PPC64_PLT_PCREL34: howto manager. (line 704) +* BFD_RELOC_PPC64_REL16_HIGH: howto manager. (line 688) +* BFD_RELOC_PPC64_REL16_HIGHA: howto manager. (line 689) +* BFD_RELOC_PPC64_REL16_HIGHER: howto manager. (line 690) +* BFD_RELOC_PPC64_REL16_HIGHER34: howto manager. (line 709) +* BFD_RELOC_PPC64_REL16_HIGHERA: howto manager. (line 691) +* BFD_RELOC_PPC64_REL16_HIGHERA34: howto manager. (line 710) +* BFD_RELOC_PPC64_REL16_HIGHEST: howto manager. (line 692) +* BFD_RELOC_PPC64_REL16_HIGHEST34: howto manager. (line 711) +* BFD_RELOC_PPC64_REL16_HIGHESTA: howto manager. (line 693) +* BFD_RELOC_PPC64_REL16_HIGHESTA34: howto manager. (line 712) +* BFD_RELOC_PPC64_REL24_NOTOC: howto manager. (line 696) +* BFD_RELOC_PPC64_REL24_P9NOTOC: howto manager. (line 697) +* BFD_RELOC_PPC64_SECTOFF_DS: howto manager. (line 680) +* BFD_RELOC_PPC64_SECTOFF_LO_DS: howto manager. (line 681) +* BFD_RELOC_PPC64_TLSGD: howto manager. (line 750) +* BFD_RELOC_PPC64_TLSIE: howto manager. (line 753) +* BFD_RELOC_PPC64_TLSLD: howto manager. (line 751) +* BFD_RELOC_PPC64_TLSLE: howto manager. (line 752) +* BFD_RELOC_PPC64_TLSM: howto manager. (line 754) +* BFD_RELOC_PPC64_TLSML: howto manager. (line 755) +* BFD_RELOC_PPC64_TLS_PCREL: howto manager. (line 778) +* BFD_RELOC_PPC64_TOC: howto manager. (line 670) +* BFD_RELOC_PPC64_TOC16_DS: howto manager. (line 682) +* BFD_RELOC_PPC64_TOC16_HA: howto manager. (line 669) +* BFD_RELOC_PPC64_TOC16_HI: howto manager. (line 668) +* BFD_RELOC_PPC64_TOC16_LO: howto manager. (line 667) +* BFD_RELOC_PPC64_TOC16_LO_DS: howto manager. (line 683) +* BFD_RELOC_PPC64_TPREL16_DS: howto manager. (line 756) +* BFD_RELOC_PPC64_TPREL16_HIGH: howto manager. (line 758) +* BFD_RELOC_PPC64_TPREL16_HIGHA: howto manager. (line 759) +* BFD_RELOC_PPC64_TPREL16_HIGHER: howto manager. (line 760) +* BFD_RELOC_PPC64_TPREL16_HIGHERA: howto manager. (line 761) +* BFD_RELOC_PPC64_TPREL16_HIGHEST: howto manager. (line 762) +* BFD_RELOC_PPC64_TPREL16_HIGHESTA: howto manager. (line 763) +* BFD_RELOC_PPC64_TPREL16_LO_DS: howto manager. (line 757) +* BFD_RELOC_PPC64_TPREL34: howto manager. (line 772) +* BFD_RELOC_PPC_16DX_HA: howto manager. (line 660) +* BFD_RELOC_PPC_B16: howto manager. (line 616) +* BFD_RELOC_PPC_B16_BRNTAKEN: howto manager. (line 618) +* BFD_RELOC_PPC_B16_BRTAKEN: howto manager. (line 617) +* BFD_RELOC_PPC_B26: howto manager. (line 611) +* BFD_RELOC_PPC_BA16: howto manager. (line 619) +* BFD_RELOC_PPC_BA16_BRNTAKEN: howto manager. (line 621) +* BFD_RELOC_PPC_BA16_BRTAKEN: howto manager. (line 620) +* BFD_RELOC_PPC_BA26: howto manager. (line 612) +* BFD_RELOC_PPC_COPY: howto manager. (line 622) +* BFD_RELOC_PPC_DTPMOD: howto manager. (line 723) +* BFD_RELOC_PPC_DTPREL: howto manager. (line 733) +* BFD_RELOC_PPC_DTPREL16: howto manager. (line 729) +* BFD_RELOC_PPC_DTPREL16_HA: howto manager. (line 732) +* BFD_RELOC_PPC_DTPREL16_HI: howto manager. (line 731) +* BFD_RELOC_PPC_DTPREL16_LO: howto manager. (line 730) +* BFD_RELOC_PPC_EMB_BIT_FLD: howto manager. (line 641) +* BFD_RELOC_PPC_EMB_MRKREF: howto manager. (line 636) +* BFD_RELOC_PPC_EMB_NADDR16: howto manager. (line 628) +* BFD_RELOC_PPC_EMB_NADDR16_HA: howto manager. (line 631) +* BFD_RELOC_PPC_EMB_NADDR16_HI: howto manager. (line 630) +* BFD_RELOC_PPC_EMB_NADDR16_LO: howto manager. (line 629) +* BFD_RELOC_PPC_EMB_NADDR32: howto manager. (line 627) +* BFD_RELOC_PPC_EMB_RELSDA: howto manager. (line 642) +* BFD_RELOC_PPC_EMB_RELSEC16: howto manager. (line 637) +* BFD_RELOC_PPC_EMB_RELST_HA: howto manager. (line 640) +* BFD_RELOC_PPC_EMB_RELST_HI: howto manager. (line 639) +* BFD_RELOC_PPC_EMB_RELST_LO: howto manager. (line 638) +* BFD_RELOC_PPC_EMB_SDA21: howto manager. (line 635) +* BFD_RELOC_PPC_EMB_SDA2I16: howto manager. (line 633) +* BFD_RELOC_PPC_EMB_SDA2REL: howto manager. (line 634) +* BFD_RELOC_PPC_EMB_SDAI16: howto manager. (line 632) +* BFD_RELOC_PPC_GLOB_DAT: howto manager. (line 623) +* BFD_RELOC_PPC_GOT_DTPREL16: howto manager. (line 746) +* BFD_RELOC_PPC_GOT_DTPREL16_HA: howto manager. (line 749) +* BFD_RELOC_PPC_GOT_DTPREL16_HI: howto manager. (line 748) +* BFD_RELOC_PPC_GOT_DTPREL16_LO: howto manager. (line 747) +* BFD_RELOC_PPC_GOT_TLSGD16: howto manager. (line 734) +* BFD_RELOC_PPC_GOT_TLSGD16_HA: howto manager. (line 737) +* BFD_RELOC_PPC_GOT_TLSGD16_HI: howto manager. (line 736) +* BFD_RELOC_PPC_GOT_TLSGD16_LO: howto manager. (line 735) +* BFD_RELOC_PPC_GOT_TLSLD16: howto manager. (line 738) +* BFD_RELOC_PPC_GOT_TLSLD16_HA: howto manager. (line 741) +* BFD_RELOC_PPC_GOT_TLSLD16_HI: howto manager. (line 740) +* BFD_RELOC_PPC_GOT_TLSLD16_LO: howto manager. (line 739) +* BFD_RELOC_PPC_GOT_TPREL16: howto manager. (line 742) +* BFD_RELOC_PPC_GOT_TPREL16_HA: howto manager. (line 745) +* BFD_RELOC_PPC_GOT_TPREL16_HI: howto manager. (line 744) +* BFD_RELOC_PPC_GOT_TPREL16_LO: howto manager. (line 743) +* BFD_RELOC_PPC_JMP_SLOT: howto manager. (line 624) +* BFD_RELOC_PPC_LOCAL24PC: howto manager. (line 626) +* BFD_RELOC_PPC_NEG: howto manager. (line 662) +* BFD_RELOC_PPC_REL16DX_HA: howto manager. (line 661) +* BFD_RELOC_PPC_RELATIVE: howto manager. (line 625) +* BFD_RELOC_PPC_TLS: howto manager. (line 716) +* BFD_RELOC_PPC_TLSGD: howto manager. (line 717) +* BFD_RELOC_PPC_TLSIE: howto manager. (line 720) +* BFD_RELOC_PPC_TLSLD: howto manager. (line 718) +* BFD_RELOC_PPC_TLSLE: howto manager. (line 719) +* BFD_RELOC_PPC_TLSM: howto manager. (line 721) +* BFD_RELOC_PPC_TLSML: howto manager. (line 722) +* BFD_RELOC_PPC_TOC16: howto manager. (line 613) +* BFD_RELOC_PPC_TOC16_HI: howto manager. (line 615) +* BFD_RELOC_PPC_TOC16_LO: howto manager. (line 614) +* BFD_RELOC_PPC_TPREL: howto manager. (line 728) +* BFD_RELOC_PPC_TPREL16: howto manager. (line 724) +* BFD_RELOC_PPC_TPREL16_HA: howto manager. (line 727) +* BFD_RELOC_PPC_TPREL16_HI: howto manager. (line 726) +* BFD_RELOC_PPC_TPREL16_LO: howto manager. (line 725) +* BFD_RELOC_PPC_VLE_HA16A: howto manager. (line 650) +* BFD_RELOC_PPC_VLE_HA16D: howto manager. (line 651) +* BFD_RELOC_PPC_VLE_HI16A: howto manager. (line 648) +* BFD_RELOC_PPC_VLE_HI16D: howto manager. (line 649) +* BFD_RELOC_PPC_VLE_LO16A: howto manager. (line 646) +* BFD_RELOC_PPC_VLE_LO16D: howto manager. (line 647) +* BFD_RELOC_PPC_VLE_REL15: howto manager. (line 644) +* BFD_RELOC_PPC_VLE_REL24: howto manager. (line 645) +* BFD_RELOC_PPC_VLE_REL8: howto manager. (line 643) +* BFD_RELOC_PPC_VLE_SDA21: howto manager. (line 652) +* BFD_RELOC_PPC_VLE_SDA21_LO: howto manager. (line 653) +* BFD_RELOC_PPC_VLE_SDAREL_HA16A: howto manager. (line 658) +* BFD_RELOC_PPC_VLE_SDAREL_HA16D: howto manager. (line 659) +* BFD_RELOC_PPC_VLE_SDAREL_HI16A: howto manager. (line 656) +* BFD_RELOC_PPC_VLE_SDAREL_HI16D: howto manager. (line 657) +* BFD_RELOC_PPC_VLE_SDAREL_LO16A: howto manager. (line 654) +* BFD_RELOC_PPC_VLE_SDAREL_LO16D: howto manager. (line 655) +* BFD_RELOC_PRU_16_PMEM: howto manager. (line 2485) +* BFD_RELOC_PRU_32_PMEM: howto manager. (line 2484) +* BFD_RELOC_PRU_GNU_DIFF16: howto manager. (line 2489) +* BFD_RELOC_PRU_GNU_DIFF16_PMEM: howto manager. (line 2491) +* BFD_RELOC_PRU_GNU_DIFF32: howto manager. (line 2490) +* BFD_RELOC_PRU_GNU_DIFF32_PMEM: howto manager. (line 2492) +* BFD_RELOC_PRU_GNU_DIFF8: howto manager. (line 2488) +* BFD_RELOC_PRU_LDI32: howto manager. (line 2476) +* BFD_RELOC_PRU_S10_PCREL: howto manager. (line 2480) +* BFD_RELOC_PRU_U16: howto manager. (line 2472) +* BFD_RELOC_PRU_U16_PMEMIMM: howto manager. (line 2474) +* BFD_RELOC_PRU_U8_PCREL: howto manager. (line 2482) +* BFD_RELOC_RELC: howto manager. (line 2429) +* BFD_RELOC_RISCV_32_PCREL: howto manager. (line 1895) +* BFD_RELOC_RISCV_ADD16: howto manager. (line 1864) +* BFD_RELOC_RISCV_ADD32: howto manager. (line 1865) +* BFD_RELOC_RISCV_ADD64: howto manager. (line 1866) +* BFD_RELOC_RISCV_ADD8: howto manager. (line 1863) +* BFD_RELOC_RISCV_ALIGN: howto manager. (line 1885) +* BFD_RELOC_RISCV_CALL: howto manager. (line 1861) +* BFD_RELOC_RISCV_CALL_PLT: howto manager. (line 1862) +* BFD_RELOC_RISCV_CFA: howto manager. (line 1889) +* BFD_RELOC_RISCV_GOT_HI20: howto manager. (line 1871) +* BFD_RELOC_RISCV_GPREL12_I: howto manager. (line 1855) +* BFD_RELOC_RISCV_GPREL12_S: howto manager. (line 1856) +* BFD_RELOC_RISCV_HI20: howto manager. (line 1849) +* BFD_RELOC_RISCV_JMP: howto manager. (line 1874) +* BFD_RELOC_RISCV_LO12_I: howto manager. (line 1853) +* BFD_RELOC_RISCV_LO12_S: howto manager. (line 1854) +* BFD_RELOC_RISCV_PCREL_HI20: howto manager. (line 1850) +* BFD_RELOC_RISCV_PCREL_LO12_I: howto manager. (line 1851) +* BFD_RELOC_RISCV_PCREL_LO12_S: howto manager. (line 1852) +* BFD_RELOC_RISCV_RELAX: howto manager. (line 1888) +* BFD_RELOC_RISCV_RVC_BRANCH: howto manager. (line 1886) +* BFD_RELOC_RISCV_RVC_JUMP: howto manager. (line 1887) +* BFD_RELOC_RISCV_SET16: howto manager. (line 1893) +* BFD_RELOC_RISCV_SET32: howto manager. (line 1894) +* BFD_RELOC_RISCV_SET6: howto manager. (line 1891) +* BFD_RELOC_RISCV_SET8: howto manager. (line 1892) +* BFD_RELOC_RISCV_SET_ULEB128: howto manager. (line 1896) +* BFD_RELOC_RISCV_SUB16: howto manager. (line 1868) +* BFD_RELOC_RISCV_SUB32: howto manager. (line 1869) +* BFD_RELOC_RISCV_SUB6: howto manager. (line 1890) +* BFD_RELOC_RISCV_SUB64: howto manager. (line 1870) +* BFD_RELOC_RISCV_SUB8: howto manager. (line 1867) +* BFD_RELOC_RISCV_SUB_ULEB128: howto manager. (line 1897) +* BFD_RELOC_RISCV_TLSDESC_ADD_LO12: howto manager. (line 1883) +* BFD_RELOC_RISCV_TLSDESC_CALL: howto manager. (line 1884) +* BFD_RELOC_RISCV_TLSDESC_HI20: howto manager. (line 1881) +* BFD_RELOC_RISCV_TLSDESC_LOAD_LO12: howto manager. (line 1882) +* BFD_RELOC_RISCV_TLS_DTPMOD32: howto manager. (line 1875) +* BFD_RELOC_RISCV_TLS_DTPMOD64: howto manager. (line 1877) +* BFD_RELOC_RISCV_TLS_DTPREL32: howto manager. (line 1876) +* BFD_RELOC_RISCV_TLS_DTPREL64: howto manager. (line 1878) +* BFD_RELOC_RISCV_TLS_GD_HI20: howto manager. (line 1873) +* BFD_RELOC_RISCV_TLS_GOT_HI20: howto manager. (line 1872) +* BFD_RELOC_RISCV_TLS_TPREL32: howto manager. (line 1879) +* BFD_RELOC_RISCV_TLS_TPREL64: howto manager. (line 1880) +* BFD_RELOC_RISCV_TPREL_ADD: howto manager. (line 1860) +* BFD_RELOC_RISCV_TPREL_HI20: howto manager. (line 1857) +* BFD_RELOC_RISCV_TPREL_LO12_I: howto manager. (line 1858) +* BFD_RELOC_RISCV_TPREL_LO12_S: howto manager. (line 1859) +* BFD_RELOC_RL78_16U: howto manager. (line 1907) +* BFD_RELOC_RL78_16_OP: howto manager. (line 1903) +* BFD_RELOC_RL78_24U: howto manager. (line 1908) +* BFD_RELOC_RL78_24_OP: howto manager. (line 1904) +* BFD_RELOC_RL78_32_OP: howto manager. (line 1905) +* BFD_RELOC_RL78_8U: howto manager. (line 1906) +* BFD_RELOC_RL78_ABS16: howto manager. (line 1920) +* BFD_RELOC_RL78_ABS16U: howto manager. (line 1924) +* BFD_RELOC_RL78_ABS16UL: howto manager. (line 1926) +* BFD_RELOC_RL78_ABS16UW: howto manager. (line 1925) +* BFD_RELOC_RL78_ABS16_REV: howto manager. (line 1921) +* BFD_RELOC_RL78_ABS32: howto manager. (line 1922) +* BFD_RELOC_RL78_ABS32_REV: howto manager. (line 1923) +* BFD_RELOC_RL78_ABS8: howto manager. (line 1919) +* BFD_RELOC_RL78_CODE: howto manager. (line 1931) +* BFD_RELOC_RL78_DIFF: howto manager. (line 1910) +* BFD_RELOC_RL78_DIR3U_PCREL: howto manager. (line 1909) +* BFD_RELOC_RL78_GPRELB: howto manager. (line 1911) +* BFD_RELOC_RL78_GPRELL: howto manager. (line 1913) +* BFD_RELOC_RL78_GPRELW: howto manager. (line 1912) +* BFD_RELOC_RL78_HI16: howto manager. (line 1928) +* BFD_RELOC_RL78_HI8: howto manager. (line 1929) +* BFD_RELOC_RL78_LO16: howto manager. (line 1930) +* BFD_RELOC_RL78_NEG16: howto manager. (line 1900) +* BFD_RELOC_RL78_NEG24: howto manager. (line 1901) +* BFD_RELOC_RL78_NEG32: howto manager. (line 1902) +* BFD_RELOC_RL78_NEG8: howto manager. (line 1899) +* BFD_RELOC_RL78_OP_AND: howto manager. (line 1917) +* BFD_RELOC_RL78_OP_NEG: howto manager. (line 1916) +* BFD_RELOC_RL78_OP_SHRA: howto manager. (line 1918) +* BFD_RELOC_RL78_OP_SUBTRACT: howto manager. (line 1915) +* BFD_RELOC_RL78_RELAX: howto manager. (line 1927) +* BFD_RELOC_RL78_SADDR: howto manager. (line 1932) +* BFD_RELOC_RL78_SYM: howto manager. (line 1914) +* BFD_RELOC_RVA: howto manager. (line 95) +* BFD_RELOC_RX_16U: howto manager. (line 1942) +* BFD_RELOC_RX_16_OP: howto manager. (line 1938) +* BFD_RELOC_RX_24U: howto manager. (line 1943) +* BFD_RELOC_RX_24_OP: howto manager. (line 1939) +* BFD_RELOC_RX_32_OP: howto manager. (line 1940) +* BFD_RELOC_RX_8U: howto manager. (line 1941) +* BFD_RELOC_RX_ABS16: howto manager. (line 1953) +* BFD_RELOC_RX_ABS16U: howto manager. (line 1957) +* BFD_RELOC_RX_ABS16UL: howto manager. (line 1959) +* BFD_RELOC_RX_ABS16UW: howto manager. (line 1958) +* BFD_RELOC_RX_ABS16_REV: howto manager. (line 1954) +* BFD_RELOC_RX_ABS32: howto manager. (line 1955) +* BFD_RELOC_RX_ABS32_REV: howto manager. (line 1956) +* BFD_RELOC_RX_ABS8: howto manager. (line 1952) +* BFD_RELOC_RX_DIFF: howto manager. (line 1945) +* BFD_RELOC_RX_DIR3U_PCREL: howto manager. (line 1944) +* BFD_RELOC_RX_GPRELB: howto manager. (line 1946) +* BFD_RELOC_RX_GPRELL: howto manager. (line 1948) +* BFD_RELOC_RX_GPRELW: howto manager. (line 1947) +* BFD_RELOC_RX_NEG16: howto manager. (line 1935) +* BFD_RELOC_RX_NEG24: howto manager. (line 1936) +* BFD_RELOC_RX_NEG32: howto manager. (line 1937) +* BFD_RELOC_RX_NEG8: howto manager. (line 1934) +* BFD_RELOC_RX_OP_NEG: howto manager. (line 1951) +* BFD_RELOC_RX_OP_SUBTRACT: howto manager. (line 1950) +* BFD_RELOC_RX_RELAX: howto manager. (line 1960) +* BFD_RELOC_RX_SYM: howto manager. (line 1949) +* BFD_RELOC_S12Z_15_PCREL: howto manager. (line 2272) +* BFD_RELOC_S12Z_OPR: howto manager. (line 3477) +* BFD_RELOC_SCORE16_BRANCH: howto manager. (line 2063) +* BFD_RELOC_SCORE16_JMP: howto manager. (line 2061) +* BFD_RELOC_SCORE_BCMP: howto manager. (line 2065) +* BFD_RELOC_SCORE_BRANCH: howto manager. (line 2055) +* BFD_RELOC_SCORE_CALL15: howto manager. (line 2069) +* BFD_RELOC_SCORE_DUMMY2: howto manager. (line 2052) +* BFD_RELOC_SCORE_DUMMY_HI16: howto manager. (line 2070) +* BFD_RELOC_SCORE_GOT15: howto manager. (line 2067) +* BFD_RELOC_SCORE_GOT_LO16: howto manager. (line 2068) +* BFD_RELOC_SCORE_GPREL15: howto manager. (line 2050) +* BFD_RELOC_SCORE_IMM30: howto manager. (line 2057) +* BFD_RELOC_SCORE_IMM32: howto manager. (line 2059) +* BFD_RELOC_SCORE_JMP: howto manager. (line 2053) +* BFD_RELOC_SH_ALIGN: howto manager. (line 975) +* BFD_RELOC_SH_CODE: howto manager. (line 976) +* BFD_RELOC_SH_COPY: howto manager. (line 981) +* BFD_RELOC_SH_COPY64: howto manager. (line 1006) +* BFD_RELOC_SH_COUNT: howto manager. (line 974) +* BFD_RELOC_SH_DATA: howto manager. (line 977) +* BFD_RELOC_SH_DISP12: howto manager. (line 957) +* BFD_RELOC_SH_DISP12BY2: howto manager. (line 958) +* BFD_RELOC_SH_DISP12BY4: howto manager. (line 959) +* BFD_RELOC_SH_DISP12BY8: howto manager. (line 960) +* BFD_RELOC_SH_DISP20: howto manager. (line 961) +* BFD_RELOC_SH_DISP20BY8: howto manager. (line 962) +* BFD_RELOC_SH_FUNCDESC: howto manager. (line 1049) +* BFD_RELOC_SH_GLOB_DAT: howto manager. (line 982) +* BFD_RELOC_SH_GLOB_DAT64: howto manager. (line 1007) +* BFD_RELOC_SH_GOT10BY4: howto manager. (line 1010) +* BFD_RELOC_SH_GOT10BY8: howto manager. (line 1011) +* BFD_RELOC_SH_GOT20: howto manager. (line 1043) +* BFD_RELOC_SH_GOTFUNCDESC: howto manager. (line 1045) +* BFD_RELOC_SH_GOTFUNCDESC20: howto manager. (line 1046) +* BFD_RELOC_SH_GOTOFF20: howto manager. (line 1044) +* BFD_RELOC_SH_GOTOFFFUNCDESC: howto manager. (line 1047) +* BFD_RELOC_SH_GOTOFFFUNCDESC20: howto manager. (line 1048) +* BFD_RELOC_SH_GOTOFF_HI16: howto manager. (line 1001) +* BFD_RELOC_SH_GOTOFF_LOW16: howto manager. (line 998) +* BFD_RELOC_SH_GOTOFF_MEDHI16: howto manager. (line 1000) +* BFD_RELOC_SH_GOTOFF_MEDLOW16: howto manager. (line 999) +* BFD_RELOC_SH_GOTPC: howto manager. (line 985) +* BFD_RELOC_SH_GOTPC_HI16: howto manager. (line 1005) +* BFD_RELOC_SH_GOTPC_LOW16: howto manager. (line 1002) +* BFD_RELOC_SH_GOTPC_MEDHI16: howto manager. (line 1004) +* BFD_RELOC_SH_GOTPC_MEDLOW16: howto manager. (line 1003) +* BFD_RELOC_SH_GOTPLT10BY4: howto manager. (line 1012) +* BFD_RELOC_SH_GOTPLT10BY8: howto manager. (line 1013) +* BFD_RELOC_SH_GOTPLT32: howto manager. (line 1014) +* BFD_RELOC_SH_GOTPLT_HI16: howto manager. (line 993) +* BFD_RELOC_SH_GOTPLT_LOW16: howto manager. (line 990) +* BFD_RELOC_SH_GOTPLT_MEDHI16: howto manager. (line 992) +* BFD_RELOC_SH_GOTPLT_MEDLOW16: howto manager. (line 991) +* BFD_RELOC_SH_GOT_HI16: howto manager. (line 989) +* BFD_RELOC_SH_GOT_LOW16: howto manager. (line 986) +* BFD_RELOC_SH_GOT_MEDHI16: howto manager. (line 988) +* BFD_RELOC_SH_GOT_MEDLOW16: howto manager. (line 987) +* BFD_RELOC_SH_IMM3: howto manager. (line 955) +* BFD_RELOC_SH_IMM3U: howto manager. (line 956) +* BFD_RELOC_SH_IMM4: howto manager. (line 963) +* BFD_RELOC_SH_IMM4BY2: howto manager. (line 964) +* BFD_RELOC_SH_IMM4BY4: howto manager. (line 965) +* BFD_RELOC_SH_IMM8: howto manager. (line 966) +* BFD_RELOC_SH_IMM8BY2: howto manager. (line 967) +* BFD_RELOC_SH_IMM8BY4: howto manager. (line 968) +* BFD_RELOC_SH_IMMS10: howto manager. (line 1020) +* BFD_RELOC_SH_IMMS10BY2: howto manager. (line 1021) +* BFD_RELOC_SH_IMMS10BY4: howto manager. (line 1022) +* BFD_RELOC_SH_IMMS10BY8: howto manager. (line 1023) +* BFD_RELOC_SH_IMMS16: howto manager. (line 1024) +* BFD_RELOC_SH_IMMS6: howto manager. (line 1017) +* BFD_RELOC_SH_IMMS6BY32: howto manager. (line 1018) +* BFD_RELOC_SH_IMMU16: howto manager. (line 1025) +* BFD_RELOC_SH_IMMU5: howto manager. (line 1016) +* BFD_RELOC_SH_IMMU6: howto manager. (line 1019) +* BFD_RELOC_SH_IMM_HI16: howto manager. (line 1032) +* BFD_RELOC_SH_IMM_HI16_PCREL: howto manager. (line 1033) +* BFD_RELOC_SH_IMM_LOW16: howto manager. (line 1026) +* BFD_RELOC_SH_IMM_LOW16_PCREL: howto manager. (line 1027) +* BFD_RELOC_SH_IMM_MEDHI16: howto manager. (line 1030) +* BFD_RELOC_SH_IMM_MEDHI16_PCREL: howto manager. (line 1031) +* BFD_RELOC_SH_IMM_MEDLOW16: howto manager. (line 1028) +* BFD_RELOC_SH_IMM_MEDLOW16_PCREL: howto manager. (line 1029) +* BFD_RELOC_SH_JMP_SLOT: howto manager. (line 983) +* BFD_RELOC_SH_JMP_SLOT64: howto manager. (line 1008) +* BFD_RELOC_SH_LABEL: howto manager. (line 978) +* BFD_RELOC_SH_LOOP_END: howto manager. (line 980) +* BFD_RELOC_SH_LOOP_START: howto manager. (line 979) +* BFD_RELOC_SH_PCDISP12BY2: howto manager. (line 954) +* BFD_RELOC_SH_PCDISP8BY2: howto manager. (line 953) +* BFD_RELOC_SH_PCRELIMM8BY2: howto manager. (line 969) +* BFD_RELOC_SH_PCRELIMM8BY4: howto manager. (line 970) +* BFD_RELOC_SH_PLT_HI16: howto manager. (line 997) +* BFD_RELOC_SH_PLT_LOW16: howto manager. (line 994) +* BFD_RELOC_SH_PLT_MEDHI16: howto manager. (line 996) +* BFD_RELOC_SH_PLT_MEDLOW16: howto manager. (line 995) +* BFD_RELOC_SH_PT_16: howto manager. (line 1034) +* BFD_RELOC_SH_RELATIVE: howto manager. (line 984) +* BFD_RELOC_SH_RELATIVE64: howto manager. (line 1009) +* BFD_RELOC_SH_SHMEDIA_CODE: howto manager. (line 1015) +* BFD_RELOC_SH_SWITCH16: howto manager. (line 971) +* BFD_RELOC_SH_SWITCH32: howto manager. (line 972) +* BFD_RELOC_SH_TLS_DTPMOD32: howto manager. (line 1040) +* BFD_RELOC_SH_TLS_DTPOFF32: howto manager. (line 1041) +* BFD_RELOC_SH_TLS_GD_32: howto manager. (line 1035) +* BFD_RELOC_SH_TLS_IE_32: howto manager. (line 1038) +* BFD_RELOC_SH_TLS_LDO_32: howto manager. (line 1037) +* BFD_RELOC_SH_TLS_LD_32: howto manager. (line 1036) +* BFD_RELOC_SH_TLS_LE_32: howto manager. (line 1039) +* BFD_RELOC_SH_TLS_TPOFF32: howto manager. (line 1042) +* BFD_RELOC_SH_USES: howto manager. (line 973) +* BFD_RELOC_SIZE32: howto manager. (line 67) +* BFD_RELOC_SIZE64: howto manager. (line 68) +* BFD_RELOC_SPARC13: howto manager. (line 121) +* BFD_RELOC_SPARC22: howto manager. (line 120) +* BFD_RELOC_SPARC_10: howto manager. (line 148) +* BFD_RELOC_SPARC_11: howto manager. (line 149) +* BFD_RELOC_SPARC_5: howto manager. (line 161) +* BFD_RELOC_SPARC_6: howto manager. (line 160) +* BFD_RELOC_SPARC_64: howto manager. (line 147) +* BFD_RELOC_SPARC_7: howto manager. (line 159) +* BFD_RELOC_SPARC_BASE13: howto manager. (line 144) +* BFD_RELOC_SPARC_BASE22: howto manager. (line 145) +* BFD_RELOC_SPARC_COPY: howto manager. (line 128) +* BFD_RELOC_SPARC_DISP64: howto manager. (line 162) +* BFD_RELOC_SPARC_GLOB_DAT: howto manager. (line 129) +* BFD_RELOC_SPARC_GOT10: howto manager. (line 122) +* BFD_RELOC_SPARC_GOT13: howto manager. (line 123) +* BFD_RELOC_SPARC_GOT22: howto manager. (line 124) +* BFD_RELOC_SPARC_GOTDATA_HIX22: howto manager. (line 135) +* BFD_RELOC_SPARC_GOTDATA_LOX10: howto manager. (line 136) +* BFD_RELOC_SPARC_GOTDATA_OP: howto manager. (line 139) +* BFD_RELOC_SPARC_GOTDATA_OP_HIX22: howto manager. (line 137) +* BFD_RELOC_SPARC_GOTDATA_OP_LOX10: howto manager. (line 138) +* BFD_RELOC_SPARC_H34: howto manager. (line 171) +* BFD_RELOC_SPARC_H44: howto manager. (line 167) +* BFD_RELOC_SPARC_HH22: howto manager. (line 151) +* BFD_RELOC_SPARC_HIX22: howto manager. (line 165) +* BFD_RELOC_SPARC_HM10: howto manager. (line 152) +* BFD_RELOC_SPARC_IRELATIVE: howto manager. (line 141) +* BFD_RELOC_SPARC_JMP_IREL: howto manager. (line 140) +* BFD_RELOC_SPARC_JMP_SLOT: howto manager. (line 130) +* BFD_RELOC_SPARC_L44: howto manager. (line 169) +* BFD_RELOC_SPARC_LM22: howto manager. (line 153) +* BFD_RELOC_SPARC_LOX10: howto manager. (line 166) +* BFD_RELOC_SPARC_M44: howto manager. (line 168) +* BFD_RELOC_SPARC_OLO10: howto manager. (line 150) +* BFD_RELOC_SPARC_PC10: howto manager. (line 125) +* BFD_RELOC_SPARC_PC22: howto manager. (line 126) +* BFD_RELOC_SPARC_PC_HH22: howto manager. (line 154) +* BFD_RELOC_SPARC_PC_HM10: howto manager. (line 155) +* BFD_RELOC_SPARC_PC_LM22: howto manager. (line 156) +* BFD_RELOC_SPARC_PLT32: howto manager. (line 163) +* BFD_RELOC_SPARC_PLT64: howto manager. (line 164) +* BFD_RELOC_SPARC_REGISTER: howto manager. (line 170) +* BFD_RELOC_SPARC_RELATIVE: howto manager. (line 131) +* BFD_RELOC_SPARC_REV32: howto manager. (line 176) +* BFD_RELOC_SPARC_SIZE32: howto manager. (line 172) +* BFD_RELOC_SPARC_SIZE64: howto manager. (line 173) +* BFD_RELOC_SPARC_TLS_DTPMOD32: howto manager. (line 196) +* BFD_RELOC_SPARC_TLS_DTPMOD64: howto manager. (line 197) +* BFD_RELOC_SPARC_TLS_DTPOFF32: howto manager. (line 198) +* BFD_RELOC_SPARC_TLS_DTPOFF64: howto manager. (line 199) +* BFD_RELOC_SPARC_TLS_GD_ADD: howto manager. (line 180) +* BFD_RELOC_SPARC_TLS_GD_CALL: howto manager. (line 181) +* BFD_RELOC_SPARC_TLS_GD_HI22: howto manager. (line 178) +* BFD_RELOC_SPARC_TLS_GD_LO10: howto manager. (line 179) +* BFD_RELOC_SPARC_TLS_IE_ADD: howto manager. (line 193) +* BFD_RELOC_SPARC_TLS_IE_HI22: howto manager. (line 189) +* BFD_RELOC_SPARC_TLS_IE_LD: howto manager. (line 191) +* BFD_RELOC_SPARC_TLS_IE_LDX: howto manager. (line 192) +* BFD_RELOC_SPARC_TLS_IE_LO10: howto manager. (line 190) +* BFD_RELOC_SPARC_TLS_LDM_ADD: howto manager. (line 184) +* BFD_RELOC_SPARC_TLS_LDM_CALL: howto manager. (line 185) +* BFD_RELOC_SPARC_TLS_LDM_HI22: howto manager. (line 182) +* BFD_RELOC_SPARC_TLS_LDM_LO10: howto manager. (line 183) +* BFD_RELOC_SPARC_TLS_LDO_ADD: howto manager. (line 188) +* BFD_RELOC_SPARC_TLS_LDO_HIX22: howto manager. (line 186) +* BFD_RELOC_SPARC_TLS_LDO_LOX10: howto manager. (line 187) +* BFD_RELOC_SPARC_TLS_LE_HIX22: howto manager. (line 194) +* BFD_RELOC_SPARC_TLS_LE_LOX10: howto manager. (line 195) +* BFD_RELOC_SPARC_TLS_TPOFF32: howto manager. (line 200) +* BFD_RELOC_SPARC_TLS_TPOFF64: howto manager. (line 201) +* BFD_RELOC_SPARC_UA16: howto manager. (line 132) +* BFD_RELOC_SPARC_UA32: howto manager. (line 133) +* BFD_RELOC_SPARC_UA64: howto manager. (line 134) +* BFD_RELOC_SPARC_WDISP10: howto manager. (line 174) +* BFD_RELOC_SPARC_WDISP16: howto manager. (line 157) +* BFD_RELOC_SPARC_WDISP19: howto manager. (line 158) +* BFD_RELOC_SPARC_WDISP22: howto manager. (line 119) +* BFD_RELOC_SPARC_WPLT30: howto manager. (line 127) +* BFD_RELOC_SPU_ADD_PIC: howto manager. (line 217) +* BFD_RELOC_SPU_HI16: howto manager. (line 214) +* BFD_RELOC_SPU_IMM10: howto manager. (line 205) +* BFD_RELOC_SPU_IMM10W: howto manager. (line 206) +* BFD_RELOC_SPU_IMM16: howto manager. (line 207) +* BFD_RELOC_SPU_IMM16W: howto manager. (line 208) +* BFD_RELOC_SPU_IMM18: howto manager. (line 209) +* BFD_RELOC_SPU_IMM7: howto manager. (line 203) +* BFD_RELOC_SPU_IMM8: howto manager. (line 204) +* BFD_RELOC_SPU_LO16: howto manager. (line 213) +* BFD_RELOC_SPU_PCREL16: howto manager. (line 212) +* BFD_RELOC_SPU_PCREL9a: howto manager. (line 210) +* BFD_RELOC_SPU_PCREL9b: howto manager. (line 211) +* BFD_RELOC_SPU_PPU32: howto manager. (line 215) +* BFD_RELOC_SPU_PPU64: howto manager. (line 216) +* BFD_RELOC_THUMB_PCREL_BFCSEL: howto manager. (line 805) +* BFD_RELOC_THUMB_PCREL_BLX: howto manager. (line 794) +* BFD_RELOC_THUMB_PCREL_BRANCH12: howto manager. (line 817) +* BFD_RELOC_THUMB_PCREL_BRANCH20: howto manager. (line 818) +* BFD_RELOC_THUMB_PCREL_BRANCH23: howto manager. (line 819) +* BFD_RELOC_THUMB_PCREL_BRANCH25: howto manager. (line 820) +* BFD_RELOC_THUMB_PCREL_BRANCH5: howto manager. (line 803) +* BFD_RELOC_THUMB_PCREL_BRANCH7: howto manager. (line 815) +* BFD_RELOC_THUMB_PCREL_BRANCH9: howto manager. (line 816) +* BFD_RELOC_TIC30_LDP: howto manager. (line 1560) +* BFD_RELOC_TIC54X_16_OF_23: howto manager. (line 1574) +* BFD_RELOC_TIC54X_23: howto manager. (line 1572) +* BFD_RELOC_TIC54X_MS7_OF_23: howto manager. (line 1578) +* BFD_RELOC_TIC54X_PARTLS7: howto manager. (line 1564) +* BFD_RELOC_TIC54X_PARTMS9: howto manager. (line 1568) +* BFD_RELOC_TILEGX_BROFF_X1: howto manager. (line 3273) +* BFD_RELOC_TILEGX_COPY: howto manager. (line 3269) +* BFD_RELOC_TILEGX_DEST_IMM8_X1: howto manager. (line 3280) +* BFD_RELOC_TILEGX_GLOB_DAT: howto manager. (line 3270) +* BFD_RELOC_TILEGX_HW0: howto manager. (line 3262) +* BFD_RELOC_TILEGX_HW0_LAST: howto manager. (line 3266) +* BFD_RELOC_TILEGX_HW1: howto manager. (line 3263) +* BFD_RELOC_TILEGX_HW1_LAST: howto manager. (line 3267) +* BFD_RELOC_TILEGX_HW2: howto manager. (line 3264) +* BFD_RELOC_TILEGX_HW2_LAST: howto manager. (line 3268) +* BFD_RELOC_TILEGX_HW3: howto manager. (line 3265) +* BFD_RELOC_TILEGX_IMM16_X0_HW0: howto manager. (line 3289) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT: howto manager. (line 3317) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST: howto manager. (line 3297) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT: howto manager. (line 3325) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL: howto manager. (line 3311) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL: howto manager. + (line 3345) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD: howto manager. (line 3339) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE: howto manager. (line 3351) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE: howto manager. (line 3335) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL: howto manager. (line 3303) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL: howto manager. (line 3319) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD: howto manager. (line 3331) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE: howto manager. (line 3343) +* BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE: howto manager. (line 3333) +* BFD_RELOC_TILEGX_IMM16_X0_HW1: howto manager. (line 3291) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST: howto manager. (line 3299) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT: howto manager. (line 3327) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL: howto manager. (line 3313) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL: howto manager. + (line 3347) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD: howto manager. (line 3341) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE: howto manager. (line 3353) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE: howto manager. (line 3337) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL: howto manager. (line 3305) +* BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL: howto manager. (line 3321) +* BFD_RELOC_TILEGX_IMM16_X0_HW2: howto manager. (line 3293) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST: howto manager. (line 3301) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL: howto manager. (line 3315) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL: howto manager. + (line 3349) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL: howto manager. (line 3307) +* BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL: howto manager. (line 3323) +* BFD_RELOC_TILEGX_IMM16_X0_HW3: howto manager. (line 3295) +* BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL: howto manager. (line 3309) +* BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL: howto manager. (line 3329) +* BFD_RELOC_TILEGX_IMM16_X1_HW0: howto manager. (line 3290) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT: howto manager. (line 3318) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST: howto manager. (line 3298) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT: howto manager. (line 3326) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL: howto manager. (line 3312) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL: howto manager. + (line 3346) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD: howto manager. (line 3340) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE: howto manager. (line 3352) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE: howto manager. (line 3336) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL: howto manager. (line 3304) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL: howto manager. (line 3320) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD: howto manager. (line 3332) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE: howto manager. (line 3344) +* BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE: howto manager. (line 3334) +* BFD_RELOC_TILEGX_IMM16_X1_HW1: howto manager. (line 3292) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST: howto manager. (line 3300) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT: howto manager. (line 3328) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL: howto manager. (line 3314) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL: howto manager. + (line 3348) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD: howto manager. (line 3342) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE: howto manager. (line 3354) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE: howto manager. (line 3338) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL: howto manager. (line 3306) +* BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL: howto manager. (line 3322) +* BFD_RELOC_TILEGX_IMM16_X1_HW2: howto manager. (line 3294) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST: howto manager. (line 3302) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL: howto manager. (line 3316) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL: howto manager. + (line 3350) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL: howto manager. (line 3308) +* BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL: howto manager. (line 3324) +* BFD_RELOC_TILEGX_IMM16_X1_HW3: howto manager. (line 3296) +* BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL: howto manager. (line 3310) +* BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL: howto manager. (line 3330) +* BFD_RELOC_TILEGX_IMM8_X0: howto manager. (line 3276) +* BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD: howto manager. (line 3367) +* BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD: howto manager. (line 3362) +* BFD_RELOC_TILEGX_IMM8_X1: howto manager. (line 3278) +* BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD: howto manager. (line 3368) +* BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD: howto manager. (line 3363) +* BFD_RELOC_TILEGX_IMM8_Y0: howto manager. (line 3277) +* BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD: howto manager. (line 3369) +* BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD: howto manager. (line 3364) +* BFD_RELOC_TILEGX_IMM8_Y1: howto manager. (line 3279) +* BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD: howto manager. (line 3370) +* BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD: howto manager. (line 3365) +* BFD_RELOC_TILEGX_JMP_SLOT: howto manager. (line 3271) +* BFD_RELOC_TILEGX_JUMPOFF_X1: howto manager. (line 3274) +* BFD_RELOC_TILEGX_JUMPOFF_X1_PLT: howto manager. (line 3275) +* BFD_RELOC_TILEGX_MF_IMM14_X1: howto manager. (line 3282) +* BFD_RELOC_TILEGX_MMEND_X0: howto manager. (line 3284) +* BFD_RELOC_TILEGX_MMSTART_X0: howto manager. (line 3283) +* BFD_RELOC_TILEGX_MT_IMM14_X1: howto manager. (line 3281) +* BFD_RELOC_TILEGX_RELATIVE: howto manager. (line 3272) +* BFD_RELOC_TILEGX_SHAMT_X0: howto manager. (line 3285) +* BFD_RELOC_TILEGX_SHAMT_X1: howto manager. (line 3286) +* BFD_RELOC_TILEGX_SHAMT_Y0: howto manager. (line 3287) +* BFD_RELOC_TILEGX_SHAMT_Y1: howto manager. (line 3288) +* BFD_RELOC_TILEGX_TLS_DTPMOD32: howto manager. (line 3358) +* BFD_RELOC_TILEGX_TLS_DTPMOD64: howto manager. (line 3355) +* BFD_RELOC_TILEGX_TLS_DTPOFF32: howto manager. (line 3359) +* BFD_RELOC_TILEGX_TLS_DTPOFF64: howto manager. (line 3356) +* BFD_RELOC_TILEGX_TLS_GD_CALL: howto manager. (line 3361) +* BFD_RELOC_TILEGX_TLS_IE_LOAD: howto manager. (line 3366) +* BFD_RELOC_TILEGX_TLS_TPOFF32: howto manager. (line 3360) +* BFD_RELOC_TILEGX_TLS_TPOFF64: howto manager. (line 3357) +* BFD_RELOC_TILEPRO_BROFF_X1: howto manager. (line 3186) +* BFD_RELOC_TILEPRO_COPY: howto manager. (line 3182) +* BFD_RELOC_TILEPRO_DEST_IMM8_X1: howto manager. (line 3193) +* BFD_RELOC_TILEPRO_GLOB_DAT: howto manager. (line 3183) +* BFD_RELOC_TILEPRO_IMM16_X0: howto manager. (line 3196) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT: howto manager. (line 3212) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA: howto manager. (line 3218) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI: howto manager. (line 3216) +* BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO: howto manager. (line 3214) +* BFD_RELOC_TILEPRO_IMM16_X0_HA: howto manager. (line 3202) +* BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL: howto manager. (line 3210) +* BFD_RELOC_TILEPRO_IMM16_X0_HI: howto manager. (line 3200) +* BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL: howto manager. (line 3208) +* BFD_RELOC_TILEPRO_IMM16_X0_LO: howto manager. (line 3198) +* BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL: howto manager. (line 3206) +* BFD_RELOC_TILEPRO_IMM16_X0_PCREL: howto manager. (line 3204) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD: howto manager. (line 3234) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA: howto manager. (line 3240) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI: howto manager. (line 3238) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO: howto manager. (line 3236) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE: howto manager. (line 3242) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA: howto manager. (line 3248) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI: howto manager. (line 3246) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO: howto manager. (line 3244) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE: howto manager. (line 3253) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA: howto manager. (line 3259) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI: howto manager. (line 3257) +* BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO: howto manager. (line 3255) +* BFD_RELOC_TILEPRO_IMM16_X1: howto manager. (line 3197) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT: howto manager. (line 3213) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA: howto manager. (line 3219) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI: howto manager. (line 3217) +* BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO: howto manager. (line 3215) +* BFD_RELOC_TILEPRO_IMM16_X1_HA: howto manager. (line 3203) +* BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL: howto manager. (line 3211) +* BFD_RELOC_TILEPRO_IMM16_X1_HI: howto manager. (line 3201) +* BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL: howto manager. (line 3209) +* BFD_RELOC_TILEPRO_IMM16_X1_LO: howto manager. (line 3199) +* BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL: howto manager. (line 3207) +* BFD_RELOC_TILEPRO_IMM16_X1_PCREL: howto manager. (line 3205) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD: howto manager. (line 3235) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA: howto manager. (line 3241) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI: howto manager. (line 3239) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO: howto manager. (line 3237) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE: howto manager. (line 3243) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA: howto manager. (line 3249) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI: howto manager. (line 3247) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO: howto manager. (line 3245) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE: howto manager. (line 3254) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA: howto manager. (line 3260) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI: howto manager. (line 3258) +* BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO: howto manager. (line 3256) +* BFD_RELOC_TILEPRO_IMM8_X0: howto manager. (line 3189) +* BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD: howto manager. (line 3229) +* BFD_RELOC_TILEPRO_IMM8_X1: howto manager. (line 3191) +* BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD: howto manager. (line 3230) +* BFD_RELOC_TILEPRO_IMM8_Y0: howto manager. (line 3190) +* BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD: howto manager. (line 3231) +* BFD_RELOC_TILEPRO_IMM8_Y1: howto manager. (line 3192) +* BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD: howto manager. (line 3232) +* BFD_RELOC_TILEPRO_JMP_SLOT: howto manager. (line 3184) +* BFD_RELOC_TILEPRO_JOFFLONG_X1: howto manager. (line 3187) +* BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT: howto manager. (line 3188) +* BFD_RELOC_TILEPRO_MF_IMM15_X1: howto manager. (line 3195) +* BFD_RELOC_TILEPRO_MMEND_X0: howto manager. (line 3221) +* BFD_RELOC_TILEPRO_MMEND_X1: howto manager. (line 3223) +* BFD_RELOC_TILEPRO_MMSTART_X0: howto manager. (line 3220) +* BFD_RELOC_TILEPRO_MMSTART_X1: howto manager. (line 3222) +* BFD_RELOC_TILEPRO_MT_IMM15_X1: howto manager. (line 3194) +* BFD_RELOC_TILEPRO_RELATIVE: howto manager. (line 3185) +* BFD_RELOC_TILEPRO_SHAMT_X0: howto manager. (line 3224) +* BFD_RELOC_TILEPRO_SHAMT_X1: howto manager. (line 3225) +* BFD_RELOC_TILEPRO_SHAMT_Y0: howto manager. (line 3226) +* BFD_RELOC_TILEPRO_SHAMT_Y1: howto manager. (line 3227) +* BFD_RELOC_TILEPRO_TLS_DTPMOD32: howto manager. (line 3250) +* BFD_RELOC_TILEPRO_TLS_DTPOFF32: howto manager. (line 3251) +* BFD_RELOC_TILEPRO_TLS_GD_CALL: howto manager. (line 3228) +* BFD_RELOC_TILEPRO_TLS_IE_LOAD: howto manager. (line 3233) +* BFD_RELOC_TILEPRO_TLS_TPOFF32: howto manager. (line 3252) +* bfd_reloc_type_lookup: howto manager. (line 3590) +* BFD_RELOC_V850_16_GOT: howto manager. (line 1545) +* BFD_RELOC_V850_16_GOTOFF: howto manager. (line 1553) +* BFD_RELOC_V850_16_PCREL: howto manager. (line 1526) +* BFD_RELOC_V850_16_S1: howto manager. (line 1538) +* BFD_RELOC_V850_16_SPLIT_OFFSET: howto manager. (line 1536) +* BFD_RELOC_V850_17_PCREL: howto manager. (line 1528) +* BFD_RELOC_V850_22_PCREL: howto manager. (line 1480) +* BFD_RELOC_V850_22_PLT_PCREL: howto manager. (line 1547) +* BFD_RELOC_V850_23: howto manager. (line 1530) +* BFD_RELOC_V850_32_ABS: howto manager. (line 1534) +* BFD_RELOC_V850_32_GOT: howto manager. (line 1546) +* BFD_RELOC_V850_32_GOTOFF: howto manager. (line 1554) +* BFD_RELOC_V850_32_GOTPCREL: howto manager. (line 1544) +* BFD_RELOC_V850_32_PCREL: howto manager. (line 1532) +* BFD_RELOC_V850_32_PLT_PCREL: howto manager. (line 1548) +* BFD_RELOC_V850_9_PCREL: howto manager. (line 1478) +* BFD_RELOC_V850_ALIGN: howto manager. (line 1521) +* BFD_RELOC_V850_CALLT_15_16_OFFSET: howto manager. (line 1542) +* BFD_RELOC_V850_CALLT_16_16_OFFSET: howto manager. (line 1515) +* BFD_RELOC_V850_CALLT_6_7_OFFSET: howto manager. (line 1513) +* BFD_RELOC_V850_CODE: howto manager. (line 1556) +* BFD_RELOC_V850_COPY: howto manager. (line 1549) +* BFD_RELOC_V850_DATA: howto manager. (line 1558) +* BFD_RELOC_V850_GLOB_DAT: howto manager. (line 1550) +* BFD_RELOC_V850_JMP_SLOT: howto manager. (line 1551) +* BFD_RELOC_V850_LO16_S1: howto manager. (line 1540) +* BFD_RELOC_V850_LO16_SPLIT_OFFSET: howto manager. (line 1523) +* BFD_RELOC_V850_LONGCALL: howto manager. (line 1517) +* BFD_RELOC_V850_LONGJUMP: howto manager. (line 1519) +* BFD_RELOC_V850_RELATIVE: howto manager. (line 1552) +* BFD_RELOC_V850_SDA_15_16_OFFSET: howto manager. (line 1484) +* BFD_RELOC_V850_SDA_16_16_OFFSET: howto manager. (line 1482) +* BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET: howto manager. (line 1507) +* BFD_RELOC_V850_TDA_16_16_OFFSET: howto manager. (line 1500) +* BFD_RELOC_V850_TDA_4_4_OFFSET: howto manager. (line 1505) +* BFD_RELOC_V850_TDA_4_5_OFFSET: howto manager. (line 1502) +* BFD_RELOC_V850_TDA_6_8_OFFSET: howto manager. (line 1492) +* BFD_RELOC_V850_TDA_7_7_OFFSET: howto manager. (line 1498) +* BFD_RELOC_V850_TDA_7_8_OFFSET: howto manager. (line 1495) +* BFD_RELOC_V850_ZDA_15_16_OFFSET: howto manager. (line 1489) +* BFD_RELOC_V850_ZDA_16_16_OFFSET: howto manager. (line 1487) +* BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET: howto manager. (line 1510) +* BFD_RELOC_VAX_GLOB_DAT: howto manager. (line 2431) +* BFD_RELOC_VAX_JMP_SLOT: howto manager. (line 2432) +* BFD_RELOC_VAX_RELATIVE: howto manager. (line 2433) +* BFD_RELOC_VISIUM_HI16: howto manager. (line 3392) +* BFD_RELOC_VISIUM_HI16_PCREL: howto manager. (line 3396) +* BFD_RELOC_VISIUM_IM16: howto manager. (line 3394) +* BFD_RELOC_VISIUM_IM16_PCREL: howto manager. (line 3398) +* BFD_RELOC_VISIUM_LO16: howto manager. (line 3393) +* BFD_RELOC_VISIUM_LO16_PCREL: howto manager. (line 3397) +* BFD_RELOC_VISIUM_REL16: howto manager. (line 3395) +* BFD_RELOC_VPE4KMATH_DATA: howto manager. (line 2093) +* BFD_RELOC_VPE4KMATH_INSN: howto manager. (line 2094) +* BFD_RELOC_VTABLE_ENTRY: howto manager. (line 2097) +* BFD_RELOC_VTABLE_INHERIT: howto manager. (line 2096) +* BFD_RELOC_WASM32_ABS32_CODE: howto manager. (line 3405) +* BFD_RELOC_WASM32_CODE_POINTER: howto manager. (line 3407) +* BFD_RELOC_WASM32_COPY: howto manager. (line 3406) +* BFD_RELOC_WASM32_INDEX: howto manager. (line 3408) +* BFD_RELOC_WASM32_LEB128: howto manager. (line 3400) +* BFD_RELOC_WASM32_LEB128_GOT: howto manager. (line 3401) +* BFD_RELOC_WASM32_LEB128_GOT_CODE: howto manager. (line 3402) +* BFD_RELOC_WASM32_LEB128_PLT: howto manager. (line 3403) +* BFD_RELOC_WASM32_PLT_INDEX: howto manager. (line 3404) +* BFD_RELOC_WASM32_PLT_SIG: howto manager. (line 3409) +* BFD_RELOC_X86_64_32S: howto manager. (line 554) +* BFD_RELOC_X86_64_CODE_4_GOTPC32_TLSDESC: howto manager. (line 580) +* BFD_RELOC_X86_64_CODE_4_GOTPCRELX: howto manager. (line 578) +* BFD_RELOC_X86_64_CODE_4_GOTTPOFF: howto manager. (line 579) +* BFD_RELOC_X86_64_CODE_5_GOTPC32_TLSDESC: howto manager. (line 583) +* BFD_RELOC_X86_64_CODE_5_GOTPCRELX: howto manager. (line 581) +* BFD_RELOC_X86_64_CODE_5_GOTTPOFF: howto manager. (line 582) +* BFD_RELOC_X86_64_CODE_6_GOTPC32_TLSDESC: howto manager. (line 586) +* BFD_RELOC_X86_64_CODE_6_GOTPCRELX: howto manager. (line 584) +* BFD_RELOC_X86_64_CODE_6_GOTTPOFF: howto manager. (line 585) +* BFD_RELOC_X86_64_COPY: howto manager. (line 549) +* BFD_RELOC_X86_64_DTPMOD64: howto manager. (line 555) +* BFD_RELOC_X86_64_DTPOFF32: howto manager. (line 560) +* BFD_RELOC_X86_64_DTPOFF64: howto manager. (line 556) +* BFD_RELOC_X86_64_GLOB_DAT: howto manager. (line 550) +* BFD_RELOC_X86_64_GOT32: howto manager. (line 547) +* BFD_RELOC_X86_64_GOT64: howto manager. (line 565) +* BFD_RELOC_X86_64_GOTOFF64: howto manager. (line 563) +* BFD_RELOC_X86_64_GOTPC32: howto manager. (line 564) +* BFD_RELOC_X86_64_GOTPC32_TLSDESC: howto manager. (line 570) +* BFD_RELOC_X86_64_GOTPC64: howto manager. (line 567) +* BFD_RELOC_X86_64_GOTPCREL: howto manager. (line 553) +* BFD_RELOC_X86_64_GOTPCREL64: howto manager. (line 566) +* BFD_RELOC_X86_64_GOTPCRELX: howto manager. (line 576) +* BFD_RELOC_X86_64_GOTPLT64: howto manager. (line 568) +* BFD_RELOC_X86_64_GOTTPOFF: howto manager. (line 561) +* BFD_RELOC_X86_64_IRELATIVE: howto manager. (line 573) +* BFD_RELOC_X86_64_JUMP_SLOT: howto manager. (line 551) +* BFD_RELOC_X86_64_PC32_BND: howto manager. (line 574) +* BFD_RELOC_X86_64_PLT32: howto manager. (line 548) +* BFD_RELOC_X86_64_PLT32_BND: howto manager. (line 575) +* BFD_RELOC_X86_64_PLTOFF64: howto manager. (line 569) +* BFD_RELOC_X86_64_RELATIVE: howto manager. (line 552) +* BFD_RELOC_X86_64_REX_GOTPCRELX: howto manager. (line 577) +* BFD_RELOC_X86_64_TLSDESC: howto manager. (line 572) +* BFD_RELOC_X86_64_TLSDESC_CALL: howto manager. (line 571) +* BFD_RELOC_X86_64_TLSGD: howto manager. (line 558) +* BFD_RELOC_X86_64_TLSLD: howto manager. (line 559) +* BFD_RELOC_X86_64_TPOFF32: howto manager. (line 562) +* BFD_RELOC_X86_64_TPOFF64: howto manager. (line 557) +* BFD_RELOC_XGATE_24: howto manager. (line 2240) +* BFD_RELOC_XGATE_GPAGE: howto manager. (line 2238) +* BFD_RELOC_XGATE_IMM3: howto manager. (line 2252) +* BFD_RELOC_XGATE_IMM4: howto manager. (line 2254) +* BFD_RELOC_XGATE_IMM5: howto manager. (line 2256) +* BFD_RELOC_XGATE_IMM8_HI: howto manager. (line 2249) +* BFD_RELOC_XGATE_IMM8_LO: howto manager. (line 2246) +* BFD_RELOC_XGATE_LO16: howto manager. (line 2235) +* BFD_RELOC_XGATE_PCREL_10: howto manager. (line 2244) +* BFD_RELOC_XGATE_PCREL_9: howto manager. (line 2242) +* BFD_RELOC_XGATE_RL_GROUP: howto manager. (line 2231) +* BFD_RELOC_XGATE_RL_JUMP: howto manager. (line 2228) +* BFD_RELOC_XSTORMY16_12: howto manager. (line 2425) +* BFD_RELOC_XSTORMY16_24: howto manager. (line 2426) +* BFD_RELOC_XSTORMY16_FPTR16: howto manager. (line 2427) +* BFD_RELOC_XSTORMY16_REL_12: howto manager. (line 2424) +* BFD_RELOC_XTENSA_ASM_EXPAND: howto manager. (line 2568) +* BFD_RELOC_XTENSA_ASM_SIMPLIFY: howto manager. (line 2572) +* BFD_RELOC_XTENSA_DIFF16: howto manager. (line 2517) +* BFD_RELOC_XTENSA_DIFF32: howto manager. (line 2518) +* BFD_RELOC_XTENSA_DIFF8: howto manager. (line 2516) +* BFD_RELOC_XTENSA_GLOB_DAT: howto manager. (line 2508) +* BFD_RELOC_XTENSA_JMP_SLOT: howto manager. (line 2509) +* BFD_RELOC_XTENSA_NDIFF16: howto manager. (line 2588) +* BFD_RELOC_XTENSA_NDIFF32: howto manager. (line 2589) +* BFD_RELOC_XTENSA_NDIFF8: howto manager. (line 2587) +* BFD_RELOC_XTENSA_OP0: howto manager. (line 2563) +* BFD_RELOC_XTENSA_OP1: howto manager. (line 2564) +* BFD_RELOC_XTENSA_OP2: howto manager. (line 2565) +* BFD_RELOC_XTENSA_PDIFF16: howto manager. (line 2585) +* BFD_RELOC_XTENSA_PDIFF32: howto manager. (line 2586) +* BFD_RELOC_XTENSA_PDIFF8: howto manager. (line 2584) +* BFD_RELOC_XTENSA_PLT: howto manager. (line 2512) +* BFD_RELOC_XTENSA_RELATIVE: howto manager. (line 2510) +* BFD_RELOC_XTENSA_RTLD: howto manager. (line 2504) +* BFD_RELOC_XTENSA_SLOT0_ALT: howto manager. (line 2546) +* BFD_RELOC_XTENSA_SLOT0_OP: howto manager. (line 2527) +* BFD_RELOC_XTENSA_SLOT10_ALT: howto manager. (line 2556) +* BFD_RELOC_XTENSA_SLOT10_OP: howto manager. (line 2537) +* BFD_RELOC_XTENSA_SLOT11_ALT: howto manager. (line 2557) +* BFD_RELOC_XTENSA_SLOT11_OP: howto manager. (line 2538) +* BFD_RELOC_XTENSA_SLOT12_ALT: howto manager. (line 2558) +* BFD_RELOC_XTENSA_SLOT12_OP: howto manager. (line 2539) +* BFD_RELOC_XTENSA_SLOT13_ALT: howto manager. (line 2559) +* BFD_RELOC_XTENSA_SLOT13_OP: howto manager. (line 2540) +* BFD_RELOC_XTENSA_SLOT14_ALT: howto manager. (line 2560) +* BFD_RELOC_XTENSA_SLOT14_OP: howto manager. (line 2541) +* BFD_RELOC_XTENSA_SLOT1_ALT: howto manager. (line 2547) +* BFD_RELOC_XTENSA_SLOT1_OP: howto manager. (line 2528) +* BFD_RELOC_XTENSA_SLOT2_ALT: howto manager. (line 2548) +* BFD_RELOC_XTENSA_SLOT2_OP: howto manager. (line 2529) +* BFD_RELOC_XTENSA_SLOT3_ALT: howto manager. (line 2549) +* BFD_RELOC_XTENSA_SLOT3_OP: howto manager. (line 2530) +* BFD_RELOC_XTENSA_SLOT4_ALT: howto manager. (line 2550) +* BFD_RELOC_XTENSA_SLOT4_OP: howto manager. (line 2531) +* BFD_RELOC_XTENSA_SLOT5_ALT: howto manager. (line 2551) +* BFD_RELOC_XTENSA_SLOT5_OP: howto manager. (line 2532) +* BFD_RELOC_XTENSA_SLOT6_ALT: howto manager. (line 2552) +* BFD_RELOC_XTENSA_SLOT6_OP: howto manager. (line 2533) +* BFD_RELOC_XTENSA_SLOT7_ALT: howto manager. (line 2553) +* BFD_RELOC_XTENSA_SLOT7_OP: howto manager. (line 2534) +* BFD_RELOC_XTENSA_SLOT8_ALT: howto manager. (line 2554) +* BFD_RELOC_XTENSA_SLOT8_OP: howto manager. (line 2535) +* BFD_RELOC_XTENSA_SLOT9_ALT: howto manager. (line 2555) +* BFD_RELOC_XTENSA_SLOT9_OP: howto manager. (line 2536) +* BFD_RELOC_XTENSA_TLSDESC_ARG: howto manager. (line 2577) +* BFD_RELOC_XTENSA_TLSDESC_FN: howto manager. (line 2576) +* BFD_RELOC_XTENSA_TLS_ARG: howto manager. (line 2581) +* BFD_RELOC_XTENSA_TLS_CALL: howto manager. (line 2582) +* BFD_RELOC_XTENSA_TLS_DTPOFF: howto manager. (line 2578) +* BFD_RELOC_XTENSA_TLS_FUNC: howto manager. (line 2580) +* BFD_RELOC_XTENSA_TLS_TPOFF: howto manager. (line 2579) +* BFD_RELOC_Z80_16_BE: howto manager. (line 2613) +* BFD_RELOC_Z80_BYTE0: howto manager. (line 2601) +* BFD_RELOC_Z80_BYTE1: howto manager. (line 2603) +* BFD_RELOC_Z80_BYTE2: howto manager. (line 2605) +* BFD_RELOC_Z80_BYTE3: howto manager. (line 2607) +* BFD_RELOC_Z80_DISP8: howto manager. (line 2599) +* BFD_RELOC_Z80_WORD0: howto manager. (line 2609) +* BFD_RELOC_Z80_WORD1: howto manager. (line 2611) +* BFD_RELOC_Z8K_CALLR: howto manager. (line 2617) +* BFD_RELOC_Z8K_DISP7: howto manager. (line 2615) +* BFD_RELOC_Z8K_IMM4L: howto manager. (line 2619) +* bfd_rename_section: section prototypes. (line 149) +* bfd_rename_section <1>: section prototypes. (line 153) +* bfd_scan_arch: Architectures. (line 597) +* bfd_scan_vma: Miscellaneous. (line 115) +* bfd_scan_vma <1>: Miscellaneous. (line 119) +* bfd_section: Opening and Closing. + (line 335) +* bfd_sections_find_if: section prototypes. (line 174) +* bfd_section_already_linked: Writing the symbol table. + (line 53) +* bfd_section_already_linked <1>: Writing the symbol table. + (line 57) +* bfd_section_list_clear: section prototypes. (line 7) +* bfd_section_list_clear <1>: section prototypes. (line 11) +* bfd_section_size_insane: section prototypes. (line 283) +* bfd_section_size_insane <1>: section prototypes. (line 287) +* bfd_seek: Miscellaneous. (line 402) +* bfd_seek <1>: Miscellaneous. (line 406) +* bfd_set_archive_head: Archives. (line 72) +* bfd_set_archive_head <1>: Archives. (line 76) +* bfd_set_arch_info: Architectures. (line 634) +* bfd_set_arch_info <1>: Architectures. (line 638) +* bfd_set_assert_handler: Error reporting. (line 204) +* bfd_set_assert_handler <1>: Error reporting. (line 209) +* bfd_set_default_target: bfd_target. (line 536) +* bfd_set_default_target <1>: bfd_target. (line 541) +* bfd_set_error: Error reporting. (line 57) +* bfd_set_error <1>: Error reporting. (line 61) +* bfd_set_error_handler: Error reporting. (line 150) +* bfd_set_error_handler <1>: Error reporting. (line 154) +* bfd_set_error_program_name: Error reporting. (line 175) +* bfd_set_error_program_name <1>: Error reporting. (line 179) +* bfd_set_filename: Opening and Closing. + (line 378) +* bfd_set_file_flags: Miscellaneous. (line 41) +* bfd_set_file_flags <1>: Miscellaneous. (line 45) +* bfd_set_format: Formats. (line 70) +* bfd_set_format <1>: Formats. (line 74) +* bfd_set_gp_size: Miscellaneous. (line 100) +* bfd_set_gp_size <1>: Miscellaneous. (line 104) +* bfd_set_gp_value: Miscellaneous. (line 108) +* bfd_set_gp_value <1>: Miscellaneous. (line 112) +* bfd_set_input_error: Error reporting. (line 66) +* bfd_set_input_error <1>: Error reporting. (line 70) +* bfd_set_private_flags: Miscellaneous. (line 153) +* bfd_set_private_flags <1>: Miscellaneous. (line 157) +* bfd_set_reloc: Miscellaneous. (line 31) +* bfd_set_reloc <1>: Miscellaneous. (line 35) +* bfd_set_section_contents: section prototypes. (line 201) +* bfd_set_section_contents <1>: section prototypes. (line 205) +* bfd_set_section_flags: section prototypes. (line 137) +* bfd_set_section_flags <1>: section prototypes. (line 141) +* bfd_set_section_size: section prototypes. (line 188) +* bfd_set_section_size <1>: section prototypes. (line 192) +* bfd_set_start_address: Miscellaneous. (line 84) +* bfd_set_start_address <1>: Miscellaneous. (line 88) +* bfd_set_symtab: symbol handling functions. + (line 57) +* bfd_set_symtab <1>: symbol handling functions. + (line 61) +* bfd_sprintf_vma: Miscellaneous. (line 287) +* bfd_sprintf_vma <1>: Miscellaneous. (line 291) +* bfd_stat: Miscellaneous. (line 394) +* bfd_stat <1>: Miscellaneous. (line 398) +* bfd_strtab_hash: Write Other Derived Routines. + (line 110) +* bfd_strtab_hash <1>: Write Other Derived Routines. + (line 116) +* bfd_symbol_info: symbol handling functions. + (line 119) +* bfd_symbol_info <1>: symbol handling functions. + (line 123) +* bfd_target: bfd_target. (line 549) +* bfd_target <1>: bfd_target. (line 564) +* bfd_target <2>: bfd_target. (line 594) +* bfd_target_list: bfd_target. (line 583) +* bfd_tell: Miscellaneous. (line 382) +* bfd_tell <1>: Miscellaneous. (line 386) +* bfd_thread_cleanup: Threading. (line 36) +* bfd_thread_cleanup <1>: Threading. (line 40) +* bfd_thread_init: Threading. (line 22) +* bfd_thread_init <1>: Threading. (line 26) +* bfd_unlock: Threading. (line 52) +* bfd_unlock <1>: Threading. (line 56) +* bfd_write: Miscellaneous. (line 374) +* bfd_write <1>: Miscellaneous. (line 378) +* bfd_write_bigendian_4byte_int: Internal. (line 91) +* bfd_write_bigendian_4byte_int <1>: Internal. (line 95) +* bfd_zalloc: Internal. (line 77) +* bfd_zmalloc: Internal. (line 58) +* Byte swapping routines.: Internal. (line 256) +* char: Error reporting. (line 79) +* char <1>: Error reporting. (line 187) +* char <2>: section prototypes. (line 273) +* char <3>: Formats. (line 83) +* char <4>: howto manager. (line 3611) +* char <5>: Core Files. (line 14) +* char <6>: bfd_target. (line 587) +* char <7>: bfd_target. (line 604) +* char <8>: Architectures. (line 594) +* char <9>: Architectures. (line 610) +* char <10>: Architectures. (line 711) +* char <11>: Opening and Closing. + (line 382) +* coff_symbol_type: coff. (line 234) +* core_file_matches_executable_p: Core Files. (line 31) +* core_file_matches_executable_p <1>: Core Files. (line 35) +* generic_core_file_matches_executable_p: Core Files. (line 40) +* generic_core_file_matches_executable_p <1>: Core Files. (line 44) +* Hash tables: Hash Tables. (line 6) +* int: Initialization. (line 6) +* int <1>: Miscellaneous. (line 96) +* int <2>: Architectures. (line 667) +* int <3>: Architectures. (line 674) +* int <4>: Architectures. (line 721) +* int <5>: Architectures. (line 730) +* int <6>: Internal. (line 284) +* int <7>: Write Other Derived Routines. + (line 104) +* internal object-file format: Canonical format. (line 11) +* Linker: Linker Functions. (line 6) +* long: Architectures. (line 661) +* machine_type: aout. (line 134) +* Other functions: Miscellaneous. (line 165) +* per_xvec_messages: Error reporting. (line 161) +* struct bfd_iovec: Miscellaneous. (line 327) +* target vector (_bfd_final_link): Performing the Final Link. + (line 6) +* target vector (_bfd_link_add_symbols): Adding Symbols to the Hash Table. + (line 6) +* target vector (_bfd_link_hash_table_create): Creating a Linker Hash Table. + (line 6) +* The HOWTO Macro: typedef arelent. (line 254) +* what is it?: Overview. (line 6) + + + +Tag Table: +Node: Top1051 +Node: Overview1387 +Node: History2445 +Node: How It Works3390 +Node: What BFD Version 2 Can Do4927 +Node: BFD information loss6244 +Node: Canonical format8785 +Node: BFD front end13128 +Node: typedef bfd13566 +Node: Error reporting27315 +Node: Initialization34811 +Node: Threading35342 +Node: Miscellaneous37539 +Node: Memory Usage56750 +Node: Sections57975 +Node: Section Input58456 +Node: Section Output59650 +Node: typedef asection62137 +Node: section prototypes79491 +Node: Symbols90761 +Node: Reading Symbols92364 +Node: Writing Symbols93472 +Node: Mini Symbols95216 +Node: typedef asymbol96190 +Node: symbol handling functions102396 +Node: Archives107611 +Node: Formats111759 +Node: Relocations115102 +Node: typedef arelent115829 +Node: howto manager129704 +Node: Core Files268894 +Node: Targets270895 +Node: bfd_target272856 +Node: Architectures298749 +Node: Opening and Closing331043 +Node: Internal346654 +Node: File Caching357989 +Node: Linker Functions360752 +Node: Creating a Linker Hash Table362426 +Node: Adding Symbols to the Hash Table364165 +Node: Differing file formats365065 +Node: Adding symbols from an object file366790 +Node: Adding symbols from an archive368940 +Node: Performing the Final Link371286 +Node: Information provided by the linker372527 +Node: Relocating the section contents373681 +Node: Writing the symbol table375433 +Node: Hash Tables382524 +Node: Creating and Freeing a Hash Table383722 +Node: Looking Up or Entering a String384972 +Node: Traversing a Hash Table386225 +Node: Deriving a New Hash Table Type387014 +Node: Define the Derived Structures388080 +Node: Write the Derived Creation Routine389161 +Node: Write Other Derived Routines391772 +Node: BFD back ends397197 +Node: What to Put Where397467 +Node: aout397647 +Node: coff403732 +Node: elf424875 +Node: mmo425276 +Node: File layout426146 +Node: Symbol-table432059 +Node: mmo section mapping435822 +Node: GNU Free Documentation License439476 +Node: BFD Index464540 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/bfd/doc/bfd.texi 16.3-5ubuntu1/bfd/doc/bfd.texi --- 16.3-5/bfd/doc/bfd.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfd.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,337 @@ +\input texinfo.tex +@setfilename bfd.info +@c Copyright (C) 1988-2024 Free Software Foundation, Inc. +@c +@synindex fn cp +@ifnottex +@dircategory Software development +@direntry +* Bfd: (bfd). The Binary File Descriptor library. +@end direntry +@end ifnottex + +@copying +This file documents the BFD library. + +Copyright @copyright{} 1991-2024 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@end copying +@iftex +@c@finalout +@setchapternewpage on +@c@setchapternewpage odd +@settitle LIB BFD, the Binary File Descriptor Library +@titlepage +@title{libbfd} +@subtitle{The Binary File Descriptor Library} +@sp 1 +@subtitle First Edition---BFD version < 3.0 % Since no product is stable before version 3.0 :-) +@subtitle Original Document Created: April 1991 +@author {Steve Chamberlain} +@author {Cygnus Support} +@page + +@tex +\def\$#1${{#1}} % Kluge: collect RCS revision info without $...$ +\xdef\manvers{1.5} % For use in headers, footers too +{\parskip=0pt +\hfill Free Software Foundation\par +\hfill sac\@www.gnu.org\par +\hfill {\it BFD}, \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +\global\parindent=0pt % Steve likes it this way +@end tex + +@vskip 0pt plus 1filll +Copyright @copyright{} 1991-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled ``GNU Free Documentation License''. + +@end titlepage +@end iftex +@contents + +@node Top, Overview, (dir), (dir) +@ifinfo +This file documents the binary file descriptor library libbfd. +@end ifinfo + +@menu +* Overview:: Overview of BFD +* BFD front end:: BFD front end +* BFD back ends:: BFD back ends +* GNU Free Documentation License:: GNU Free Documentation License +* BFD Index:: BFD Index +@end menu + +@node Overview, BFD front end, Top, Top +@chapter Introduction +@cindex BFD +@cindex what is it? +BFD is a package which allows applications to use the +same routines to operate on object files whatever the object file +format. A new object file format can be supported simply by +creating a new BFD back end and adding it to the library. + +BFD is split into two parts: the front end, and the back ends (one for +each object file format). +@itemize @bullet +@item The front end of BFD provides the interface to the user. It manages +memory and various canonical data structures. The front end also +decides which back end to use and when to call back end routines. +@item The back ends provide BFD its view of the real world. Each back +end provides a set of calls which the BFD front end can use to maintain +its canonical form. The back ends also may keep around information for +their own use, for greater efficiency. +@end itemize +@menu +* History:: History +* How It Works:: How It Works +* What BFD Version 2 Can Do:: What BFD Version 2 Can Do +@end menu + +@node History, How It Works, Overview, Overview +@section History + +One spur behind BFD was the desire, on the part of the GNU 960 team at +Intel Oregon, for interoperability of applications on their COFF and +b.out file formats. Cygnus was providing GNU support for the team, and +was contracted to provide the required functionality. + +The name came from a conversation David Wallace was having with Richard +Stallman about the library: RMS said that it would be quite hard---David +said ``BFD''. Stallman was right, but the name stuck. + +At the same time, Ready Systems wanted much the same thing, but for +different object file formats: IEEE-695, Oasys, Srecords, a.out and 68k +coff. + +BFD was first implemented by members of Cygnus Support; Steve +Chamberlain (@code{sac@@cygnus.com}), John Gilmore +(@code{gnu@@cygnus.com}), K. Richard Pixley (@code{rich@@cygnus.com}) +and David Henkel-Wallace (@code{gumby@@cygnus.com}). + + + +@node How It Works, What BFD Version 2 Can Do, History, Overview +@section How To Use BFD + +To use the library, include @file{bfd.h} and link with @file{libbfd.a}. + +BFD provides a common interface to the parts of an object file +for a calling application. + +When an application successfully opens a target file (object, archive, or +whatever), a pointer to an internal structure is returned. This pointer +points to a structure called @code{bfd}, described in +@file{bfd.h}. Our convention is to call this pointer a BFD, and +instances of it within code @code{abfd}. All operations on +the target object file are applied as methods to the BFD. The mapping is +defined within @code{bfd.h} in a set of macros, all beginning +with @samp{bfd_} to reduce namespace pollution. + +For example, this sequence does what you would probably expect: +return the number of sections in an object file attached to a BFD +@code{abfd}. + +@example +@c @cartouche +#include "bfd.h" + +unsigned int number_of_sections (abfd) +bfd *abfd; +@{ + return bfd_count_sections (abfd); +@} +@c @end cartouche +@end example + +The abstraction used within BFD is that an object file has: + +@itemize @bullet +@item +a header, +@item +a number of sections containing raw data (@pxref{Sections}), +@item +a set of relocations (@pxref{Relocations}), and +@item +some symbol information (@pxref{Symbols}). +@end itemize +@noindent +Also, BFDs opened for archives have the additional attribute of an index +and contain subordinate BFDs. This approach is fine for a.out and coff, +but loses efficiency when applied to formats such as S-records and +IEEE-695. + +@node What BFD Version 2 Can Do, , How It Works, Overview +@section What BFD Version 2 Can Do +@include bfdsumm.texi + +@node BFD front end, BFD back ends, Overview, Top +@chapter BFD Front End + +@menu +* typedef bfd:: +* Error reporting:: +* Initialization:: +* Threading:: +* Miscellaneous:: +* Memory Usage:: +* Sections:: +* Symbols:: +* Archives:: +* Formats:: +* Relocations:: +* Core Files:: +* Targets:: +* Architectures:: +* Opening and Closing:: +* Internal:: +* File Caching:: +* Linker Functions:: +* Hash Tables:: +@end menu + +@include bfdt.texi +@include bfdio.texi + +@node Memory Usage, Sections, Miscellaneous, BFD front end +@section Memory Usage +BFD keeps all of its internal structures in obstacks. There is one obstack +per open BFD file, into which the current state is stored. When a BFD is +closed, the obstack is deleted, and so everything which has been +allocated by BFD for the closing file is thrown away. + +BFD does not free anything created by an application, but pointers into +@code{bfd} structures become invalid on a @code{bfd_close}; for example, +after a @code{bfd_close} the vector passed to +@code{bfd_canonicalize_symtab} is still around, since it has been +allocated by the application, but the data that it pointed to are +lost. + +The general rule is to not close a BFD until all operations dependent +upon data from the BFD have been completed, or all the data from within +the file has been copied. To help with the management of memory, there +is a function (@code{bfd_alloc_size}) which returns the number of bytes +in obstacks associated with the supplied BFD. This could be used to +select the greediest open BFD, close it to reclaim the memory, perform +some operation and reopen the BFD again, to get a fresh copy of the data +structures. + +@node Sections, Symbols, Memory Usage, BFD front end +@include section.texi + +@node Symbols, Archives, Sections, BFD front end +@include syms.texi + +@node Archives, Formats, Symbols, BFD front end +@include archive.texi + +@node Formats, Relocations, Archives, BFD front end +@include format.texi + +@node Relocations, Core Files, Formats, BFD front end +@include reloc.texi + +@node Core Files, Targets, Relocations, BFD front end +@include corefile.texi + +@node Targets, Architectures, Core Files, BFD front end +@include targets.texi + +@node Architectures, Opening and Closing, Targets, BFD front end +@include archures.texi + +@node Opening and Closing, Internal, Architectures, BFD front end +@include opncls.texi + +@node Internal, File Caching, Opening and Closing, BFD front end +@include libbfd.texi + +@node File Caching, Linker Functions, Internal, BFD front end +@include cache.texi + +@node Linker Functions, Hash Tables, File Caching, BFD front end +@include linker.texi + +@node Hash Tables, , Linker Functions, BFD front end +@include hash.texi + +@node BFD back ends, GNU Free Documentation License, BFD front end, Top +@chapter BFD back ends +@menu +* What to Put Where:: +* aout :: a.out backends +* coff :: coff backends +* elf :: elf backends +* mmo :: mmo backend +@ignore +* srecord :: s-record backend +@end ignore +@end menu +@node What to Put Where, aout, BFD back ends, BFD back ends +@section What to Put Where +All of BFD lives in one directory. + +@node aout, coff, What to Put Where, BFD back ends +@include aoutx.texi + +@node coff, elf, aout, BFD back ends +@include coffcode.texi + +@node elf, mmo, coff, BFD back ends +@include elf.texi +@c Leave this out until the file has some actual contents... +@c @include elfcode.texi + +@node mmo, , elf, BFD back ends +@include mmo.texi + +@node GNU Free Documentation License, BFD Index, BFD back ends, Top +@include fdl.texi + +@node BFD Index, , GNU Free Documentation License, Top +@unnumbered BFD Index +@printindex cp + +@tex +% I think something like @@colophon should be in texinfo. In the +% meantime: +\long\def\colophon{\hbox to0pt{}\vfill +\centerline{The body of this manual is set in} +\centerline{\fontname\tenrm,} +\centerline{with headings in {\bf\fontname\tenbf}} +\centerline{and examples in {\tt\fontname\tentt}.} +\centerline{{\it\fontname\tenit\/} and} +\centerline{{\sl\fontname\tensl\/}} +\centerline{are used for emphasis.}\vfill} +\page\colophon +% Blame: doc@@cygnus.com, 28mar91. +@end tex + +@bye diff -pruN 16.3-5/bfd/doc/bfdint.texi 16.3-5ubuntu1/bfd/doc/bfdint.texi --- 16.3-5/bfd/doc/bfdint.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfdint.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,1851 @@ +\input texinfo +@c Copyright (C) 1988-2024 Free Software Foundation, Inc. +@setfilename bfdint.info +@settitle BFD Internals +@iftex +@titlepage +@title{BFD Internals} +@author{Ian Lance Taylor} +@author{Cygnus Solutions} +@page +@end iftex + +@copying +This file documents the internals of the BFD library. + +Copyright @copyright{} 1988-2024 Free Software Foundation, Inc. +Contributed by Cygnus Support. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.1 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``GNU General Public License'' and ``Funding +Free Software'', the Front-Cover texts being (a) (see below), and with +the Back-Cover Texts being (b) (see below). A copy of the license is +included in the section entitled ``GNU Free Documentation License''. + +(a) The FSF's Front-Cover Text is: + + A GNU Manual + +(b) The FSF's Back-Cover Text is: + + You have freedom to copy and modify this GNU Manual, like GNU + software. Copies published by the Free Software Foundation raise + funds for GNU development. +@end copying + +@node Top +@top BFD Internals +@raisesections +@cindex bfd internals + +This document describes some BFD internal information which may be +helpful when working on BFD. It is very incomplete. + +This document is not updated regularly, and may be out of date. + +The initial version of this document was written by Ian Lance Taylor +@email{ian@@cygnus.com}. + +@menu +* BFD overview:: BFD overview +* BFD guidelines:: BFD programming guidelines +* BFD target vector:: BFD target vector +* BFD generated files:: BFD generated files +* BFD multiple compilations:: Files compiled multiple times in BFD +* BFD relocation handling:: BFD relocation handling +* BFD ELF support:: BFD ELF support +* BFD glossary:: Glossary +* Index:: Index +@end menu + +@node BFD overview +@section BFD overview + +BFD is a library which provides a single interface to read and write +object files, executables, archive files, and core files in any format. + +@menu +* BFD library interfaces:: BFD library interfaces +* BFD library users:: BFD library users +* BFD view:: The BFD view of a file +* BFD blindness:: BFD loses information +@end menu + +@node BFD library interfaces +@subsection BFD library interfaces + +One way to look at the BFD library is to divide it into four parts by +type of interface. + +The first interface is the set of generic functions which programs using +the BFD library will call. These generic function normally translate +directly or indirectly into calls to routines which are specific to a +particular object file format. Many of these generic functions are +actually defined as macros in @file{bfd.h}. These functions comprise +the official BFD interface. + +The second interface is the set of functions which appear in the target +vectors. This is the bulk of the code in BFD. A target vector is a set +of function pointers specific to a particular object file format. The +target vector is used to implement the generic BFD functions. These +functions are always called through the target vector, and are never +called directly. The target vector is described in detail in @ref{BFD +target vector}. The set of functions which appear in a particular +target vector is often referred to as a BFD backend. + +The third interface is a set of oddball functions which are typically +specific to a particular object file format, are not generic functions, +and are called from outside of the BFD library. These are used as hooks +by the linker and the assembler when a particular object file format +requires some action which the BFD generic interface does not provide. +These functions are typically declared in @file{bfd.h}, but in many +cases they are only provided when BFD is configured with support for a +particular object file format. These functions live in a grey area, and +are not really part of the official BFD interface. + +The fourth interface is the set of BFD support functions which are +called by the other BFD functions. These manage issues like memory +allocation, error handling, file access, hash tables, swapping, and the +like. These functions are never called from outside of the BFD library. + +@node BFD library users +@subsection BFD library users + +Another way to look at the BFD library is to divide it into three parts +by the manner in which it is used. + +The first use is to read an object file. The object file readers are +programs like @samp{gdb}, @samp{nm}, @samp{objdump}, and @samp{objcopy}. +These programs use BFD to view an object file in a generic form. The +official BFD interface is normally fully adequate for these programs. + +The second use is to write an object file. The object file writers are +programs like @samp{gas} and @samp{objcopy}. These programs use BFD to +create an object file. The official BFD interface is normally adequate +for these programs, but for some object file formats the assembler needs +some additional hooks in order to set particular flags or other +information. The official BFD interface includes functions to copy +private information from one object file to another, and these functions +are used by @samp{objcopy} to avoid information loss. + +The third use is to link object files. There is only one object file +linker, @samp{ld}. Originally, @samp{ld} was an object file reader and +an object file writer, and it did the link operation using the generic +BFD structures. However, this turned out to be too slow and too memory +intensive. + +The official BFD linker functions were written to permit specific BFD +backends to perform the link without translating through the generic +structures, in the normal case where all the input files and output file +have the same object file format. Not all of the backends currently +implement the new interface, and there are default linking functions +within BFD which use the generic structures and which work with all +backends. + +For several object file formats the linker needs additional hooks which +are not provided by the official BFD interface, particularly for dynamic +linking support. These functions are typically called from the linker +emulation template. + +@node BFD view +@subsection The BFD view of a file + +BFD uses generic structures to manage information. It translates data +into the generic form when reading files, and out of the generic form +when writing files. + +BFD describes a file as a pointer to the @samp{bfd} type. A @samp{bfd} +is composed of the following elements. The BFD information can be +displayed using the @samp{objdump} program with various options. + +@table @asis +@item general information +The object file format, a few general flags, the start address. +@item architecture +The architecture, including both a general processor type (m68k, MIPS +etc.) and a specific machine number (m68000, R4000, etc.). +@item sections +A list of sections. +@item symbols +A symbol table. +@end table + +BFD represents a section as a pointer to the @samp{asection} type. Each +section has a name and a size. Most sections also have an associated +block of data, known as the section contents. Sections also have +associated flags, a virtual memory address, a load memory address, a +required alignment, a list of relocations, and other miscellaneous +information. + +BFD represents a relocation as a pointer to the @samp{arelent} type. A +relocation describes an action which the linker must take to modify the +section contents. Relocations have a symbol, an address, an addend, and +a pointer to a howto structure which describes how to perform the +relocation. For more information, see @ref{BFD relocation handling}. + +BFD represents a symbol as a pointer to the @samp{asymbol} type. A +symbol has a name, a pointer to a section, an offset within that +section, and some flags. + +Archive files do not have any sections or symbols. Instead, BFD +represents an archive file as a file which contains a list of +@samp{bfd}s. BFD also provides access to the archive symbol map, as a +list of symbol names. BFD provides a function to return the @samp{bfd} +within the archive which corresponds to a particular entry in the +archive symbol map. + +@node BFD blindness +@subsection BFD loses information + +Most object file formats have information which BFD can not represent in +its generic form, at least as currently defined. + +There is often explicit information which BFD can not represent. For +example, the COFF version stamp, or the ELF program segments. BFD +provides special hooks to handle this information when copying, +printing, or linking an object file. The BFD support for a particular +object file format will normally store this information in private data +and handle it using the special hooks. + +In some cases there is also implicit information which BFD can not +represent. For example, the MIPS processor distinguishes small and +large symbols, and requires that all small symbols be within 32K of the +GP register. This means that the MIPS assembler must be able to mark +variables as either small or large, and the MIPS linker must know to put +small symbols within range of the GP register. Since BFD can not +represent this information, this means that the assembler and linker +must have information that is specific to a particular object file +format which is outside of the BFD library. + +This loss of information indicates areas where the BFD paradigm breaks +down. It is not actually possible to represent the myriad differences +among object file formats using a single generic interface, at least not +in the manner which BFD does it today. + +Nevertheless, the BFD library does greatly simplify the task of dealing +with object files, and particular problems caused by information loss +can normally be solved using some sort of relatively constrained hook +into the library. + + + +@node BFD guidelines +@section BFD programming guidelines +@cindex bfd programming guidelines +@cindex programming guidelines for bfd +@cindex guidelines, bfd programming + +There is a lot of poorly written and confusing code in BFD. New BFD +code should be written to a higher standard. Merely because some BFD +code is written in a particular manner does not mean that you should +emulate it. + +Here are some general BFD programming guidelines: + +@itemize @bullet +@item +Follow the GNU coding standards. + +@item +Avoid global variables. We ideally want BFD to be fully reentrant, so +that it can be used in multiple threads. All uses of global or static +variables interfere with that. Initialized constant variables are OK, +and they should be explicitly marked with @samp{const}. Instead of global +variables, use data attached to a BFD or to a linker hash table. + +@item +All externally visible functions should have names which start with +@samp{bfd_}. All such functions should be declared in some header file, +typically @file{bfd.h}. See, for example, the various declarations near +the end of @file{bfd-in.h}, which mostly declare functions required by +specific linker emulations. + +@item +All functions which need to be visible from one file to another within +BFD, but should not be visible outside of BFD, should start with +@samp{_bfd_}. Although external names beginning with @samp{_} are +prohibited by the ANSI standard, in practice this usage will always +work, and it is required by the GNU coding standards. + +@item +Always remember that people can compile using @samp{--enable-targets} to +build several, or all, targets at once. It must be possible to link +together the files for all targets. + +@item +BFD code should compile with few or no warnings using @samp{gcc -Wall}. +Some warnings are OK, like the absence of certain function declarations +which may or may not be declared in system header files. Warnings about +ambiguous expressions and the like should always be fixed. +@end itemize + +@node BFD target vector +@section BFD target vector +@cindex bfd target vector +@cindex target vector in bfd + +BFD supports multiple object file formats by using the @dfn{target +vector}. This is simply a set of function pointers which implement +behaviour that is specific to a particular object file format. + +In this section I list all of the entries in the target vector and +describe what they do. + +@menu +* BFD target vector miscellaneous:: Miscellaneous constants +* BFD target vector swap:: Swapping functions +* BFD target vector format:: Format type dependent functions +* BFD_JUMP_TABLE macros:: BFD_JUMP_TABLE macros +* BFD target vector generic:: Generic functions +* BFD target vector copy:: Copy functions +* BFD target vector core:: Core file support functions +* BFD target vector archive:: Archive functions +* BFD target vector symbols:: Symbol table functions +* BFD target vector relocs:: Relocation support +* BFD target vector write:: Output functions +* BFD target vector link:: Linker functions +* BFD target vector dynamic:: Dynamic linking information functions +@end menu + +@node BFD target vector miscellaneous +@subsection Miscellaneous constants + +The target vector starts with a set of constants. + +@table @samp +@item name +The name of the target vector. This is an arbitrary string. This is +how the target vector is named in command-line options for tools which +use BFD, such as the @samp{--oformat} linker option. + +@item flavour +A general description of the type of target. The following flavours are +currently defined: + +@table @samp +@item bfd_target_unknown_flavour +Undefined or unknown. +@item bfd_target_aout_flavour +a.out. +@item bfd_target_coff_flavour +COFF. +@item bfd_target_ecoff_flavour +ECOFF. +@item bfd_target_elf_flavour +ELF. +@item bfd_target_tekhex_flavour +Tektronix hex format. +@item bfd_target_srec_flavour +Motorola S-record format. +@item bfd_target_ihex_flavour +Intel hex format. +@item bfd_target_som_flavour +SOM (used on HP/UX). +@item bfd_target_verilog_flavour +Verilog memory hex dump format. +@item bfd_target_msdos_flavour +MS-DOS. +@item bfd_target_evax_flavour +openVMS. +@item bfd_target_mmo_flavour +Donald Knuth's MMIXware object format. +@end table + +@item byteorder +The byte order of data in the object file. One of +@samp{BFD_ENDIAN_BIG}, @samp{BFD_ENDIAN_LITTLE}, or +@samp{BFD_ENDIAN_UNKNOWN}. The latter would be used for a format such +as S-records which do not record the architecture of the data. + +@item header_byteorder +The byte order of header information in the object file. Normally the +same as the @samp{byteorder} field, but there are certain cases where it +may be different. + +@item object_flags +Flags which may appear in the @samp{flags} field of a BFD with this +format. + +@item section_flags +Flags which may appear in the @samp{flags} field of a section within a +BFD with this format. + +@item symbol_leading_char +A character which the C compiler normally puts before a symbol. For +example, an a.out compiler will typically generate the symbol +@samp{_foo} for a function named @samp{foo} in the C source, in which +case this field would be @samp{_}. If there is no such character, this +field will be @samp{0}. + +@item ar_pad_char +The padding character to use at the end of an archive name. Normally +@samp{/}. + +@item ar_max_namelen +The maximum length of a short name in an archive. Normally @samp{14}. + +@item backend_data +A pointer to constant backend data. This is used by backends to store +whatever additional information they need to distinguish similar target +vectors which use the same sets of functions. +@end table + +@node BFD target vector swap +@subsection Swapping functions + +Every target vector has function pointers used for swapping information +in and out of the target representation. There are two sets of +functions: one for data information, and one for header information. +Each set has three sizes: 64-bit, 32-bit, and 16-bit. Each size has +three actual functions: put, get unsigned, and get signed. + +These 18 functions are used to convert data between the host and target +representations. + +@node BFD target vector format +@subsection Format type dependent functions + +Every target vector has three arrays of function pointers which are +indexed by the BFD format type. The BFD format types are as follows: + +@table @samp +@item bfd_unknown +Unknown format. Not used for anything useful. +@item bfd_object +Object file. +@item bfd_archive +Archive file. +@item bfd_core +Core file. +@end table + +The three arrays of function pointers are as follows: + +@table @samp +@item bfd_check_format +Check whether the BFD is of a particular format (object file, archive +file, or core file) corresponding to this target vector. This is called +by the @samp{bfd_check_format} function when examining an existing BFD. +If the BFD matches the desired format, this function will initialize any +format specific information such as the @samp{tdata} field of the BFD. +This function must be called before any other BFD target vector function +on a file opened for reading. + +@item bfd_set_format +Set the format of a BFD which was created for output. This is called by +the @samp{bfd_set_format} function after creating the BFD with a +function such as @samp{bfd_openw}. This function will initialize format +specific information required to write out an object file or whatever of +the given format. This function must be called before any other BFD +target vector function on a file opened for writing. + +@item bfd_write_contents +Write out the contents of the BFD in the given format. This is called +by @samp{bfd_close} function for a BFD opened for writing. This really +should not be an array selected by format type, as the +@samp{bfd_set_format} function provides all the required information. +In fact, BFD will fail if a different format is used when calling +through the @samp{bfd_set_format} and the @samp{bfd_write_contents} +arrays; fortunately, since @samp{bfd_close} gets it right, this is a +difficult error to make. +@end table + +@node BFD_JUMP_TABLE macros +@subsection @samp{BFD_JUMP_TABLE} macros +@cindex @samp{BFD_JUMP_TABLE} + +Most target vectors are defined using @samp{BFD_JUMP_TABLE} macros. +These macros take a single argument, which is a prefix applied to a set +of functions. The macros are then used to initialize the fields in the +target vector. + +For example, the @samp{BFD_JUMP_TABLE_RELOCS} macro defines three +functions: @samp{_get_reloc_upper_bound}, @samp{_canonicalize_reloc}, +and @samp{_bfd_reloc_type_lookup}. A reference like +@samp{BFD_JUMP_TABLE_RELOCS (foo)} will expand into three functions +prefixed with @samp{foo}: @samp{foo_get_reloc_upper_bound}, etc. The +@samp{BFD_JUMP_TABLE_RELOCS} macro will be placed such that those three +functions initialize the appropriate fields in the BFD target vector. + +This is done because it turns out that many different target vectors can +share certain classes of functions. For example, archives are similar +on most platforms, so most target vectors can use the same archive +functions. Those target vectors all use @samp{BFD_JUMP_TABLE_ARCHIVE} +with the same argument, calling a set of functions which is defined in +@file{archive.c}. + +Each of the @samp{BFD_JUMP_TABLE} macros is mentioned below along with +the description of the function pointers which it defines. The function +pointers will be described using the name without the prefix which the +@samp{BFD_JUMP_TABLE} macro defines. This name is normally the same as +the name of the field in the target vector structure. Any differences +will be noted. + +@node BFD target vector generic +@subsection Generic functions +@cindex @samp{BFD_JUMP_TABLE_GENERIC} + +The @samp{BFD_JUMP_TABLE_GENERIC} macro is used for some catch all +functions which don't easily fit into other categories. + +@table @samp +@item _close_and_cleanup +Free any target specific information associated with the BFD that +isn't freed by @samp{_bfd_free_cached_info}. This is called when any +BFD is closed (the @samp{bfd_write_contents} function mentioned +earlier is only called for a BFD opened for writing). This function +pointer is typically set to @samp{_bfd_generic_close_and_cleanup}, +which simply returns true. + +@item _bfd_free_cached_info +This function is designed for use by the generic archive routines, and +is also called by bfd_close. After creating the archive map archive +element bfds don't need symbols and other structures. Many targets +use @samp{bfd_alloc} to allocate target specific information and thus +do not need to do anything special for this entry point, and just set +it to @samp{_bfd_generic_free_cached_info} which throws away objalloc +memory for the bfd. Note that this means the bfd tdata and sections +are no longer available. Targets that malloc memory, attaching it to +the bfd tdata or to section used_by_bfd should implement a target +version of this function to free that memory before calling +@samp{_bfd_generic_free_cached_info}. + +@item _new_section_hook +This is called from @samp{bfd_make_section_anyway} whenever a new +section is created. Most targets use it to initialize section specific +information. This function is called whether or not the section +corresponds to an actual section in an actual BFD. + +@item _get_section_contents +Get the contents of a section. This is called from +@samp{bfd_get_section_contents}. Most targets set this to +@samp{_bfd_generic_get_section_contents}, which does a @samp{bfd_seek} +based on the section's @samp{filepos} field and a @samp{bfd_read}. The +corresponding field in the target vector is named +@samp{_bfd_get_section_contents}. + +@end table + +@node BFD target vector copy +@subsection Copy functions +@cindex @samp{BFD_JUMP_TABLE_COPY} + +The @samp{BFD_JUMP_TABLE_COPY} macro is used for functions which are +called when copying BFDs, and for a couple of functions which deal with +internal BFD information. + +@table @samp +@item _bfd_copy_private_bfd_data +This is called when copying a BFD, via @samp{bfd_copy_private_bfd_data}. +If the input and output BFDs have the same format, this will copy any +private information over. This is called after all the section contents +have been written to the output file. Only a few targets do anything in +this function. + +@item _bfd_merge_private_bfd_data +This is called when linking, via @samp{bfd_merge_private_bfd_data}. It +gives the backend linker code a chance to set any special flags in the +output file based on the contents of the input file. Only a few targets +do anything in this function. + +@item _bfd_copy_private_section_data +This is similar to @samp{_bfd_copy_private_bfd_data}, but it is called +for each section, via @samp{bfd_copy_private_section_data}. This +function is called before any section contents have been written. Only +a few targets do anything in this function. + +@item _bfd_copy_private_symbol_data +This is called via @samp{bfd_copy_private_symbol_data}, but I don't +think anything actually calls it. If it were defined, it could be used +to copy private symbol data from one BFD to another. However, most BFDs +store extra symbol information by allocating space which is larger than +the @samp{asymbol} structure and storing private information in the +extra space. Since @samp{objcopy} and other programs copy symbol +information by copying pointers to @samp{asymbol} structures, the +private symbol information is automatically copied as well. Most +targets do not do anything in this function. + +@item _bfd_set_private_flags +This is called via @samp{bfd_set_private_flags}. It is basically a hook +for the assembler to set magic information. For example, the PowerPC +ELF assembler uses it to set flags which appear in the e_flags field of +the ELF header. Most targets do not do anything in this function. + +@item _bfd_print_private_bfd_data +This is called by @samp{objdump} when the @samp{-p} option is used. It +is called via @samp{bfd_print_private_data}. It prints any interesting +information about the BFD which can not be otherwise represented by BFD +and thus can not be printed by @samp{objdump}. Most targets do not do +anything in this function. +@end table + +@node BFD target vector core +@subsection Core file support functions +@cindex @samp{BFD_JUMP_TABLE_CORE} + +The @samp{BFD_JUMP_TABLE_CORE} macro is used for functions which deal +with core files. Obviously, these functions only do something +interesting for targets which have core file support. + +@table @samp +@item _core_file_failing_command +Given a core file, this returns the command which was run to produce the +core file. + +@item _core_file_failing_signal +Given a core file, this returns the signal number which produced the +core file. + +@item _core_file_matches_executable_p +Given a core file and a BFD for an executable, this returns whether the +core file was generated by the executable. +@end table + +@node BFD target vector archive +@subsection Archive functions +@cindex @samp{BFD_JUMP_TABLE_ARCHIVE} + +The @samp{BFD_JUMP_TABLE_ARCHIVE} macro is used for functions which deal +with archive files. Most targets use COFF style archive files +(including ELF targets), and these use @samp{_bfd_archive_coff} as the +argument to @samp{BFD_JUMP_TABLE_ARCHIVE}. Some targets use BSD/a.out +style archives, and these use @samp{_bfd_archive_bsd}. (The main +difference between BSD and COFF archives is the format of the archive +symbol table). Targets with no archive support use +@samp{_bfd_noarchive}. Finally, a few targets have unusual archive +handling. + +@table @samp +@item _slurp_armap +Read in the archive symbol table, storing it in private BFD data. This +is normally called from the archive @samp{check_format} routine. The +corresponding field in the target vector is named +@samp{_bfd_slurp_armap}. + +@item _slurp_extended_name_table +Read in the extended name table from the archive, if there is one, +storing it in private BFD data. This is normally called from the +archive @samp{check_format} routine. The corresponding field in the +target vector is named @samp{_bfd_slurp_extended_name_table}. + +@item construct_extended_name_table +Build and return an extended name table if one is needed to write out +the archive. This also adjusts the archive headers to refer to the +extended name table appropriately. This is normally called from the +archive @samp{write_contents} routine. The corresponding field in the +target vector is named @samp{_bfd_construct_extended_name_table}. + +@item _truncate_arname +This copies a file name into an archive header, truncating it as +required. It is normally called from the archive @samp{write_contents} +routine. This function is more interesting in targets which do not +support extended name tables, but I think the GNU @samp{ar} program +always uses extended name tables anyhow. The corresponding field in the +target vector is named @samp{_bfd_truncate_arname}. + +@item _write_armap +Write out the archive symbol table using calls to @samp{bfd_write}. +This is normally called from the archive @samp{write_contents} routine. +The corresponding field in the target vector is named @samp{write_armap} +(no leading underscore). + +@item _read_ar_hdr +Read and parse an archive header. This handles expanding the archive +header name into the real file name using the extended name table. This +is called by routines which read the archive symbol table or the archive +itself. The corresponding field in the target vector is named +@samp{_bfd_read_ar_hdr_fn}. + +@item _openr_next_archived_file +Given an archive and a BFD representing a file stored within the +archive, return a BFD for the next file in the archive. This is called +via @samp{bfd_openr_next_archived_file}. The corresponding field in the +target vector is named @samp{openr_next_archived_file} (no leading +underscore). + +@item _get_elt_at_index +Given an archive and an index, return a BFD for the file in the archive +corresponding to that entry in the archive symbol table. This is called +via @samp{bfd_get_elt_at_index}. The corresponding field in the target +vector is named @samp{_bfd_get_elt_at_index}. + +@item _generic_stat_arch_elt +Do a stat on an element of an archive, returning information read from +the archive header (modification time, uid, gid, file mode, size). This +is called via @samp{bfd_stat_arch_elt}. The corresponding field in the +target vector is named @samp{_bfd_stat_arch_elt}. + +@item _update_armap_timestamp +After the entire contents of an archive have been written out, update +the timestamp of the archive symbol table to be newer than that of the +file. This is required for a.out style archives. This is normally +called by the archive @samp{write_contents} routine. The corresponding +field in the target vector is named @samp{_bfd_update_armap_timestamp}. +@end table + +@node BFD target vector symbols +@subsection Symbol table functions +@cindex @samp{BFD_JUMP_TABLE_SYMBOLS} + +The @samp{BFD_JUMP_TABLE_SYMBOLS} macro is used for functions which deal +with symbols. + +@table @samp +@item _get_symtab_upper_bound +Return a sensible upper bound on the amount of memory which will be +required to read the symbol table. In practice most targets return the +amount of memory required to hold @samp{asymbol} pointers for all the +symbols plus a trailing @samp{NULL} entry, and store the actual symbol +information in BFD private data. This is called via +@samp{bfd_get_symtab_upper_bound}. The corresponding field in the +target vector is named @samp{_bfd_get_symtab_upper_bound}. + +@item _canonicalize_symtab +Read in the symbol table. This is called via +@samp{bfd_canonicalize_symtab}. The corresponding field in the target +vector is named @samp{_bfd_canonicalize_symtab}. + +@item _make_empty_symbol +Create an empty symbol for the BFD. This is needed because most targets +store extra information with each symbol by allocating a structure +larger than an @samp{asymbol} and storing the extra information at the +end. This function will allocate the right amount of memory, and return +what looks like a pointer to an empty @samp{asymbol}. This is called +via @samp{bfd_make_empty_symbol}. The corresponding field in the target +vector is named @samp{_bfd_make_empty_symbol}. + +@item _print_symbol +Print information about the symbol. This is called via +@samp{bfd_print_symbol}. One of the arguments indicates what sort of +information should be printed: + +@table @samp +@item bfd_print_symbol_name +Just print the symbol name. +@item bfd_print_symbol_more +Print the symbol name and some interesting flags. I don't think +anything actually uses this. +@item bfd_print_symbol_all +Print all information about the symbol. This is used by @samp{objdump} +when run with the @samp{-t} option. +@end table +The corresponding field in the target vector is named +@samp{_bfd_print_symbol}. + +@item _get_symbol_info +Return a standard set of information about the symbol. This is called +via @samp{bfd_symbol_info}. The corresponding field in the target +vector is named @samp{_bfd_get_symbol_info}. + +@item _bfd_is_local_label_name +Return whether the given string would normally represent the name of a +local label. This is called via @samp{bfd_is_local_label} and +@samp{bfd_is_local_label_name}. Local labels are normally discarded by +the assembler. In the linker, this defines the difference between the +@samp{-x} and @samp{-X} options. + +@item _get_lineno +Return line number information for a symbol. This is only meaningful +for a COFF target. This is called when writing out COFF line numbers. + +@item _find_nearest_line +Given an address within a section, use the debugging information to find +the matching file name, function name, and line number, if any. This is +called via @samp{bfd_find_nearest_line}. The corresponding field in the +target vector is named @samp{_bfd_find_nearest_line}. + +@item _bfd_make_debug_symbol +Make a debugging symbol. This is only meaningful for a COFF target, +where it simply returns a symbol which will be placed in the +@samp{N_DEBUG} section when it is written out. This is called via +@samp{bfd_make_debug_symbol}. + +@item _read_minisymbols +Minisymbols are used to reduce the memory requirements of programs like +@samp{nm}. A minisymbol is a cookie pointing to internal symbol +information which the caller can use to extract complete symbol +information. This permits BFD to not convert all the symbols into +generic form, but to instead convert them one at a time. This is called +via @samp{bfd_read_minisymbols}. Most targets do not implement this, +and just use generic support which is based on using standard +@samp{asymbol} structures. + +@item _minisymbol_to_symbol +Convert a minisymbol to a standard @samp{asymbol}. This is called via +@samp{bfd_minisymbol_to_symbol}. +@end table + +@node BFD target vector relocs +@subsection Relocation support +@cindex @samp{BFD_JUMP_TABLE_RELOCS} + +The @samp{BFD_JUMP_TABLE_RELOCS} macro is used for functions which deal +with relocations. + +@table @samp +@item _get_reloc_upper_bound +Return a sensible upper bound on the amount of memory which will be +required to read the relocations for a section. In practice most +targets return the amount of memory required to hold @samp{arelent} +pointers for all the relocations plus a trailing @samp{NULL} entry, and +store the actual relocation information in BFD private data. This is +called via @samp{bfd_get_reloc_upper_bound}. + +@item _canonicalize_reloc +Return the relocation information for a section. This is called via +@samp{bfd_canonicalize_reloc}. The corresponding field in the target +vector is named @samp{_bfd_canonicalize_reloc}. + +@item _bfd_reloc_type_lookup +Given a relocation code, return the corresponding howto structure +(@pxref{BFD relocation codes}). This is called via +@samp{bfd_reloc_type_lookup}. The corresponding field in the target +vector is named @samp{reloc_type_lookup}. +@end table + +@node BFD target vector write +@subsection Output functions +@cindex @samp{BFD_JUMP_TABLE_WRITE} + +The @samp{BFD_JUMP_TABLE_WRITE} macro is used for functions which deal +with writing out a BFD. + +@table @samp +@item _set_arch_mach +Set the architecture and machine number for a BFD. This is called via +@samp{bfd_set_arch_mach}. Most targets implement this by calling +@samp{bfd_default_set_arch_mach}. The corresponding field in the target +vector is named @samp{_bfd_set_arch_mach}. + +@item _set_section_contents +Write out the contents of a section. This is called via +@samp{bfd_set_section_contents}. The corresponding field in the target +vector is named @samp{_bfd_set_section_contents}. +@end table + +@node BFD target vector link +@subsection Linker functions +@cindex @samp{BFD_JUMP_TABLE_LINK} + +The @samp{BFD_JUMP_TABLE_LINK} macro is used for functions called by the +linker. + +@table @samp +@item _sizeof_headers +Return the size of the header information required for a BFD. This is +used to implement the @samp{SIZEOF_HEADERS} linker script function. It +is normally used to align the first section at an efficient position on +the page. This is called via @samp{bfd_sizeof_headers}. The +corresponding field in the target vector is named +@samp{_bfd_sizeof_headers}. + +@item _bfd_get_relocated_section_contents +Read the contents of a section and apply the relocation information. +This handles both a final link and a relocatable link; in the latter +case, it adjust the relocation information as well. This is called via +@samp{bfd_get_relocated_section_contents}. Most targets implement it by +calling @samp{bfd_generic_get_relocated_section_contents}. + +@item _bfd_relax_section +Try to use relaxation to shrink the size of a section. This is called +by the linker when the @samp{-relax} option is used. This is called via +@samp{bfd_relax_section}. Most targets do not support any sort of +relaxation. + +@item _bfd_link_hash_table_create +Create the symbol hash table to use for the linker. This linker hook +permits the backend to control the size and information of the elements +in the linker symbol hash table. This is called via +@samp{bfd_link_hash_table_create}. + +@item _bfd_link_add_symbols +Given an object file or an archive, add all symbols into the linker +symbol hash table. Use callbacks to the linker to include archive +elements in the link. This is called via @samp{bfd_link_add_symbols}. + +@item _bfd_final_link +Finish the linking process. The linker calls this hook after all of the +input files have been read, when it is ready to finish the link and +generate the output file. This is called via @samp{bfd_final_link}. + +@item _bfd_link_split_section +I don't know what this is for. Nothing seems to call it. The only +non-trivial definition is in @file{som.c}. +@end table + +@node BFD target vector dynamic +@subsection Dynamic linking information functions +@cindex @samp{BFD_JUMP_TABLE_DYNAMIC} + +The @samp{BFD_JUMP_TABLE_DYNAMIC} macro is used for functions which read +dynamic linking information. + +@table @samp +@item _get_dynamic_symtab_upper_bound +Return a sensible upper bound on the amount of memory which will be +required to read the dynamic symbol table. In practice most targets +return the amount of memory required to hold @samp{asymbol} pointers for +all the symbols plus a trailing @samp{NULL} entry, and store the actual +symbol information in BFD private data. This is called via +@samp{bfd_get_dynamic_symtab_upper_bound}. The corresponding field in +the target vector is named @samp{_bfd_get_dynamic_symtab_upper_bound}. + +@item _canonicalize_dynamic_symtab +Read the dynamic symbol table. This is called via +@samp{bfd_canonicalize_dynamic_symtab}. The corresponding field in the +target vector is named @samp{_bfd_canonicalize_dynamic_symtab}. + +@item _get_dynamic_reloc_upper_bound +Return a sensible upper bound on the amount of memory which will be +required to read the dynamic relocations. In practice most targets +return the amount of memory required to hold @samp{arelent} pointers for +all the relocations plus a trailing @samp{NULL} entry, and store the +actual relocation information in BFD private data. This is called via +@samp{bfd_get_dynamic_reloc_upper_bound}. The corresponding field in +the target vector is named @samp{_bfd_get_dynamic_reloc_upper_bound}. + +@item _canonicalize_dynamic_reloc +Read the dynamic relocations. This is called via +@samp{bfd_canonicalize_dynamic_reloc}. The corresponding field in the +target vector is named @samp{_bfd_canonicalize_dynamic_reloc}. +@end table + +@node BFD generated files +@section BFD generated files +@cindex generated files in bfd +@cindex bfd generated files + +BFD contains several automatically generated files. This section +describes them. Some files are created at configure time, when you +configure BFD. Some files are created at make time, when you build +BFD. Some files are automatically rebuilt at make time, but only if +you configure with the @samp{--enable-maintainer-mode} option. Some +files live in the object directory---the directory from which you run +configure---and some live in the source directory. All files that live +in the source directory are checked into the git repository. + +@table @file +@item bfd.h +@cindex @file{bfd.h} +@cindex @file{bfd-in3.h} +Lives in the object directory. Created at make time from +@file{bfd-in2.h} via @file{bfd-in3.h}. @file{bfd-in3.h} is created at +configure time from @file{bfd-in2.h}. There are automatic dependencies +to rebuild @file{bfd-in3.h} and hence @file{bfd.h} if @file{bfd-in2.h} +changes, so you can normally ignore @file{bfd-in3.h}, and just think +about @file{bfd-in2.h} and @file{bfd.h}. + +@file{bfd.h} is built by replacing a few strings in @file{bfd-in2.h}. +To see them, search for @samp{@@} in @file{bfd-in2.h}. They mainly +control whether BFD is built for a 32 bit target or a 64 bit target. + +@item bfd-in2.h +@cindex @file{bfd-in2.h} +Lives in the source directory. Created from @file{bfd-in.h} and several +other BFD source files. If you configure with the +@samp{--enable-maintainer-mode} option, @file{bfd-in2.h} is rebuilt +automatically when a source file changes. + +@item elf32-target.h +@itemx elf64-target.h +@cindex @file{elf32-target.h} +@cindex @file{elf64-target.h} +Live in the object directory. Created from @file{elfxx-target.h}. +These files are versions of @file{elfxx-target.h} customized for either +a 32 bit ELF target or a 64 bit ELF target. + +@item libbfd.h +@cindex @file{libbfd.h} +Lives in the source directory. Created from @file{libbfd-in.h} and +several other BFD source files. If you configure with the +@samp{--enable-maintainer-mode} option, @file{libbfd.h} is rebuilt +automatically when a source file changes. + +@item libcoff.h +@cindex @file{libcoff.h} +Lives in the source directory. Created from @file{libcoff-in.h} and +@file{coffcode.h}. If you configure with the +@samp{--enable-maintainer-mode} option, @file{libcoff.h} is rebuilt +automatically when a source file changes. + +@item targmatch.h +@cindex @file{targmatch.h} +Lives in the object directory. Created at make time from +@file{config.bfd}. This file is used to map configuration triplets into +BFD target vector variable names at run time. +@end table + +@node BFD multiple compilations +@section Files compiled multiple times in BFD +Several files in BFD are compiled multiple times. By this I mean that +there are header files which contain function definitions. These header +files are included by other files, and thus the functions are compiled +once per file which includes them. + +Preprocessor macros are used to control the compilation, so that each +time the files are compiled the resulting functions are slightly +different. Naturally, if they weren't different, there would be no +reason to compile them multiple times. + +This is a not a particularly good programming technique, and future BFD +work should avoid it. + +@itemize @bullet +@item +Since this technique is rarely used, even experienced C programmers find +it confusing. + +@item +It is difficult to debug programs which use BFD, since there is no way +to describe which version of a particular function you are looking at. + +@item +Programs which use BFD wind up incorporating two or more slightly +different versions of the same function, which wastes space in the +executable. + +@item +This technique is never required nor is it especially efficient. It is +always possible to use statically initialized structures holding +function pointers and magic constants instead. +@end itemize + +The following is a list of the files which are compiled multiple times. + +@table @file +@item aout-target.h +@cindex @file{aout-target.h} +Describes a few functions and the target vector for a.out targets. This +is used by individual a.out targets with different definitions of +@samp{N_TXTADDR} and similar a.out macros. + +@item aoutf1.h +@cindex @file{aoutf1.h} +Implements standard SunOS a.out files. In principle it supports 64 bit +a.out targets based on the preprocessor macro @samp{ARCH_SIZE}, but +since all known a.out targets are 32 bits, this code may or may not +work. This file is only included by a few other files, and it is +difficult to justify its existence. + +@item aoutx.h +@cindex @file{aoutx.h} +Implements basic a.out support routines. This file can be compiled for +either 32 or 64 bit support. Since all known a.out targets are 32 bits, +the 64 bit support may or may not work. I believe the original +intention was that this file would only be included by @samp{aout32.c} +and @samp{aout64.c}, and that other a.out targets would simply refer to +the functions it defined. Unfortunately, some other a.out targets +started including it directly, leading to a somewhat confused state of +affairs. + +@item coffcode.h +@cindex @file{coffcode.h} +Implements basic COFF support routines. This file is included by every +COFF target. It implements code which handles COFF magic numbers as +well as various hook functions called by the generic COFF functions in +@file{coffgen.c}. This file is controlled by a number of different +macros, and more are added regularly. + +@item coffswap.h +@cindex @file{coffswap.h} +Implements COFF swapping routines. This file is included by +@file{coffcode.h}, and thus by every COFF target. It implements the +routines which swap COFF structures between internal and external +format. The main control for this file is the external structure +definitions in the files in the @file{include/coff} directory. A COFF +target file will include one of those files before including +@file{coffcode.h} and thus @file{coffswap.h}. There are a few other +macros which affect @file{coffswap.h} as well, mostly describing whether +certain fields are present in the external structures. + +@item ecoffswap.h +@cindex @file{ecoffswap.h} +Implements ECOFF swapping routines. This is like @file{coffswap.h}, but +for ECOFF. It is included by the ECOFF target files (of which there are +only two). The control is the preprocessor macro @samp{ECOFF_32} or +@samp{ECOFF_64}. + +@item elfcode.h +@cindex @file{elfcode.h} +Implements ELF functions that use external structure definitions. This +file is included by two other files: @file{elf32.c} and @file{elf64.c}. +It is controlled by the @samp{ARCH_SIZE} macro which is defined to be +@samp{32} or @samp{64} before including it. The @samp{NAME} macro is +used internally to give the functions different names for the two target +sizes. + +@item elfcore.h +@cindex @file{elfcore.h} +Like @file{elfcode.h}, but for functions that are specific to ELF core +files. This is included only by @file{elfcode.h}. + +@item elfxx-target.h +@cindex @file{elfxx-target.h} +This file is the source for the generated files @file{elf32-target.h} +and @file{elf64-target.h}, one of which is included by every ELF target. +It defines the ELF target vector. + +@item netbsd.h +@cindex @file{netbsd.h} +Used by all netbsd aout targets. Several other files include it. + +@item peicode.h +@cindex @file{peicode.h} +Provides swapping routines and other hooks for PE targets. +@file{coffcode.h} will include this rather than @file{coffswap.h} for a +PE target. This defines PE specific versions of the COFF swapping +routines, and also defines some macros which control @file{coffcode.h} +itself. +@end table + +@node BFD relocation handling +@section BFD relocation handling +@cindex bfd relocation handling +@cindex relocations in bfd + +The handling of relocations is one of the more confusing aspects of BFD. +Relocation handling has been implemented in various different ways, all +somewhat incompatible, none perfect. + +@menu +* BFD relocation concepts:: BFD relocation concepts +* BFD relocation functions:: BFD relocation functions +* BFD relocation codes:: BFD relocation codes +* BFD relocation future:: BFD relocation future +@end menu + +@node BFD relocation concepts +@subsection BFD relocation concepts + +A relocation is an action which the linker must take when linking. It +describes a change to the contents of a section. The change is normally +based on the final value of one or more symbols. Relocations are +created by the assembler when it creates an object file. + +Most relocations are simple. A typical simple relocation is to set 32 +bits at a given offset in a section to the value of a symbol. This type +of relocation would be generated for code like @code{int *p = &i;} where +@samp{p} and @samp{i} are global variables. A relocation for the symbol +@samp{i} would be generated such that the linker would initialize the +area of memory which holds the value of @samp{p} to the value of the +symbol @samp{i}. + +Slightly more complex relocations may include an addend, which is a +constant to add to the symbol value before using it. In some cases a +relocation will require adding the symbol value to the existing contents +of the section in the object file. In others the relocation will simply +replace the contents of the section with the symbol value. Some +relocations are PC relative, so that the value to be stored in the +section is the difference between the value of a symbol and the final +address of the section contents. + +In general, relocations can be arbitrarily complex. For example, +relocations used in dynamic linking systems often require the linker to +allocate space in a different section and use the offset within that +section as the value to store. + +When doing a relocatable link, the linker may or may not have to do +anything with a relocation, depending upon the definition of the +relocation. Simple relocations generally do not require any special +action. + +@node BFD relocation functions +@subsection BFD relocation functions + +In BFD, each section has an array of @samp{arelent} structures. Each +structure has a pointer to a symbol, an address within the section, an +addend, and a pointer to a @samp{reloc_howto_struct} structure. The +howto structure has a bunch of fields describing the reloc, including a +type field. The type field is specific to the object file format +backend; none of the generic code in BFD examines it. + +Originally, the function @samp{bfd_perform_relocation} was supposed to +handle all relocations. In theory, many relocations would be simple +enough to be described by the fields in the howto structure. For those +that weren't, the howto structure included a @samp{special_function} +field to use as an escape. + +While this seems plausible, a look at @samp{bfd_perform_relocation} +shows that it failed. The function has odd special cases. Some of the +fields in the howto structure, such as @samp{pcrel_offset}, were not +adequately documented. + +The linker uses @samp{bfd_perform_relocation} to do all relocations when +the input and output file have different formats (e.g., when generating +S-records). The generic linker code, which is used by all targets which +do not define their own special purpose linker, uses +@samp{bfd_get_relocated_section_contents}, which for most targets turns +into a call to @samp{bfd_generic_get_relocated_section_contents}, which +calls @samp{bfd_perform_relocation}. So @samp{bfd_perform_relocation} +is still widely used, which makes it difficult to change, since it is +difficult to test all possible cases. + +The assembler used @samp{bfd_perform_relocation} for a while. This +turned out to be the wrong thing to do, since +@samp{bfd_perform_relocation} was written to handle relocations on an +existing object file, while the assembler needed to create relocations +in a new object file. The assembler was changed to use the new function +@samp{bfd_install_relocation} instead, and @samp{bfd_install_relocation} +was created as a copy of @samp{bfd_perform_relocation}. + +Unfortunately, the work did not progress any farther, so +@samp{bfd_install_relocation} remains a simple copy of +@samp{bfd_perform_relocation}, with all the odd special cases and +confusing code. This again is difficult to change, because again any +change can affect any assembler target, and so is difficult to test. + +The new linker, when using the same object file format for all input +files and the output file, does not convert relocations into +@samp{arelent} structures, so it can not use +@samp{bfd_perform_relocation} at all. Instead, users of the new linker +are expected to write a @samp{relocate_section} function which will +handle relocations in a target specific fashion. + +There are two helper functions for target specific relocation: +@samp{_bfd_final_link_relocate} and @samp{_bfd_relocate_contents}. +These functions use a howto structure, but they @emph{do not} use the +@samp{special_function} field. Since the functions are normally called +from target specific code, the @samp{special_function} field adds +little; any relocations which require special handling can be handled +without calling those functions. + +So, if you want to add a new target, or add a new relocation to an +existing target, you need to do the following: + +@itemize @bullet +@item +Make sure you clearly understand what the contents of the section should +look like after assembly, after a relocatable link, and after a final +link. Make sure you clearly understand the operations the linker must +perform during a relocatable link and during a final link. + +@item +Write a howto structure for the relocation. The howto structure is +flexible enough to represent any relocation which should be handled by +setting a contiguous bitfield in the destination to the value of a +symbol, possibly with an addend, possibly adding the symbol value to the +value already present in the destination. + +@item +Change the assembler to generate your relocation. The assembler will +call @samp{bfd_install_relocation}, so your howto structure has to be +able to handle that. You may need to set the @samp{special_function} +field to handle assembly correctly. Be careful to ensure that any code +you write to handle the assembler will also work correctly when doing a +relocatable link. For example, see @samp{bfd_elf_generic_reloc}. + +@item +Test the assembler. Consider the cases of relocation against an +undefined symbol, a common symbol, a symbol defined in the object file +in the same section, and a symbol defined in the object file in a +different section. These cases may not all be applicable for your +reloc. + +@item +If your target uses the new linker, which is recommended, add any +required handling to the target specific relocation function. In simple +cases this will just involve a call to @samp{_bfd_final_link_relocate} +or @samp{_bfd_relocate_contents}, depending upon the definition of the +relocation and whether the link is relocatable or not. + +@item +Test the linker. Test the case of a final link. If the relocation can +overflow, use a linker script to force an overflow and make sure the +error is reported correctly. Test a relocatable link, whether the +symbol is defined or undefined in the relocatable output. For both the +final and relocatable link, test the case when the symbol is a common +symbol, when the symbol looked like a common symbol but became a defined +symbol, when the symbol is defined in a different object file, and when +the symbol is defined in the same object file. + +@item +In order for linking to another object file format, such as S-records, +to work correctly, @samp{bfd_perform_relocation} has to do the right +thing for the relocation. You may need to set the +@samp{special_function} field to handle this correctly. Test this by +doing a link in which the output object file format is S-records. + +@item +Using the linker to generate relocatable output in a different object +file format is impossible in the general case, so you generally don't +have to worry about that. The GNU linker makes sure to stop that from +happening when an input file in a different format has relocations. + +Linking input files of different object file formats together is quite +unusual, but if you're really dedicated you may want to consider testing +this case, both when the output object file format is the same as your +format, and when it is different. +@end itemize + +@node BFD relocation codes +@subsection BFD relocation codes + +BFD has another way of describing relocations besides the howto +structures described above: the enum @samp{bfd_reloc_code_real_type}. + +Every known relocation type can be described as a value in this +enumeration. The enumeration contains many target specific relocations, +but where two or more targets have the same relocation, a single code is +used. For example, the single value @samp{BFD_RELOC_32} is used for all +simple 32 bit relocation types. + +The main purpose of this relocation code is to give the assembler some +mechanism to create @samp{arelent} structures. In order for the +assembler to create an @samp{arelent} structure, it has to be able to +obtain a howto structure. The function @samp{bfd_reloc_type_lookup}, +which simply calls the target vector entry point +@samp{reloc_type_lookup}, takes a relocation code and returns a howto +structure. + +The function @samp{bfd_get_reloc_code_name} returns the name of a +relocation code. This is mainly used in error messages. + +Using both howto structures and relocation codes can be somewhat +confusing. There are many processor specific relocation codes. +However, the relocation is only fully defined by the howto structure. +The same relocation code will map to different howto structures in +different object file formats. For example, the addend handling may be +different. + +Most of the relocation codes are not really general. The assembler can +not use them without already understanding what sorts of relocations can +be used for a particular target. It might be possible to replace the +relocation codes with something simpler. + +@node BFD relocation future +@subsection BFD relocation future + +Clearly the current BFD relocation support is in bad shape. A +wholescale rewrite would be very difficult, because it would require +thorough testing of every BFD target. So some sort of incremental +change is required. + +My vague thoughts on this would involve defining a new, clearly defined, +howto structure. Some mechanism would be used to determine which type +of howto structure was being used by a particular format. + +The new howto structure would clearly define the relocation behaviour in +the case of an assembly, a relocatable link, and a final link. At +least one special function would be defined as an escape, and it might +make sense to define more. + +One or more generic functions similar to @samp{bfd_perform_relocation} +would be written to handle the new howto structure. + +This should make it possible to write a generic version of the relocate +section functions used by the new linker. The target specific code +would provide some mechanism (a function pointer or an initial +conversion) to convert target specific relocations into howto +structures. + +Ideally it would be possible to use this generic relocate section +function for the generic linker as well. That is, it would replace the +@samp{bfd_generic_get_relocated_section_contents} function which is +currently normally used. + +For the special case of ELF dynamic linking, more consideration needs to +be given to writing ELF specific but ELF target generic code to handle +special relocation types such as GOT and PLT. + +@node BFD ELF support +@section BFD ELF support +@cindex elf support in bfd +@cindex bfd elf support + +The ELF object file format is defined in two parts: a generic ABI and a +processor specific supplement. The ELF support in BFD is split in a +similar fashion. The processor specific support is largely kept within +a single file. The generic support is provided by several other files. +The processor specific support provides a set of function pointers and +constants used by the generic support. + +@menu +* BFD ELF sections and segments:: ELF sections and segments +* BFD ELF generic support:: BFD ELF generic support +* BFD ELF processor specific support:: BFD ELF processor specific support +* BFD ELF core files:: BFD ELF core files +* BFD ELF future:: BFD ELF future +@end menu + +@node BFD ELF sections and segments +@subsection ELF sections and segments + +The ELF ABI permits a file to have either sections or segments or both. +Relocatable object files conventionally have only sections. +Executables conventionally have both. Core files conventionally have +only program segments. + +ELF sections are similar to sections in other object file formats: they +have a name, a VMA, file contents, flags, and other miscellaneous +information. ELF relocations are stored in sections of a particular +type; BFD automatically converts these sections into internal relocation +information. + +ELF program segments are intended for fast interpretation by a system +loader. They have a type, a VMA, an LMA, file contents, and a couple of +other fields. When an ELF executable is run on a Unix system, the +system loader will examine the program segments to decide how to load +it. The loader will ignore the section information. Loadable program +segments (type @samp{PT_LOAD}) are directly loaded into memory. Other +program segments are interpreted by the loader, and generally provide +dynamic linking information. + +When an ELF file has both program segments and sections, an ELF program +segment may encompass one or more ELF sections, in the sense that the +portion of the file which corresponds to the program segment may include +the portions of the file corresponding to one or more sections. When +there is more than one section in a loadable program segment, the +relative positions of the section contents in the file must correspond +to the relative positions they should hold when the program segment is +loaded. This requirement should be obvious if you consider that the +system loader will load an entire program segment at a time. + +On a system which supports dynamic paging, such as any native Unix +system, the contents of a loadable program segment must be at the same +offset in the file as in memory, modulo the memory page size used on the +system. This is because the system loader will map the file into memory +starting at the start of a page. The system loader can easily remap +entire pages to the correct load address. However, if the contents of +the file were not correctly aligned within the page, the system loader +would have to shift the contents around within the page, which is too +expensive. For example, if the LMA of a loadable program segment is +@samp{0x40080} and the page size is @samp{0x1000}, then the position of +the segment contents within the file must equal @samp{0x80} modulo +@samp{0x1000}. + +BFD has only a single set of sections. It does not provide any generic +way to examine both sections and segments. When BFD is used to open an +object file or executable, the BFD sections will represent ELF sections. +When BFD is used to open a core file, the BFD sections will represent +ELF program segments. + +When BFD is used to examine an object file or executable, any program +segments will be read to set the LMA of the sections. This is because +ELF sections only have a VMA, while ELF program segments have both a VMA +and an LMA. Any program segments will be copied by the +@samp{copy_private} entry points. They will be printed by the +@samp{print_private} entry point. Otherwise, the program segments are +ignored. In particular, programs which use BFD currently have no direct +access to the program segments. + +When BFD is used to create an executable, the program segments will be +created automatically based on the section information. This is done in +the function @samp{assign_file_positions_for_segments} in @file{elf.c}. +This function has been tweaked many times, and probably still has +problems that arise in particular cases. + +There is a hook which may be used to explicitly define the program +segments when creating an executable: the @samp{bfd_record_phdr} +function in @file{bfd.c}. If this function is called, BFD will not +create program segments itself, but will only create the program +segments specified by the caller. The linker uses this function to +implement the @samp{PHDRS} linker script command. + +@node BFD ELF generic support +@subsection BFD ELF generic support + +In general, functions which do not read external data from the ELF file +are found in @file{elf.c}. They operate on the internal forms of the +ELF structures, which are defined in @file{include/elf/internal.h}. The +internal structures are defined in terms of @samp{bfd_vma}, and so may +be used for both 32 bit and 64 bit ELF targets. + +The file @file{elfcode.h} contains functions which operate on the +external data. @file{elfcode.h} is compiled twice, once via +@file{elf32.c} with @samp{ARCH_SIZE} defined as @samp{32}, and once via +@file{elf64.c} with @samp{ARCH_SIZE} defined as @samp{64}. +@file{elfcode.h} includes functions to swap the ELF structures in and +out of external form, as well as a few more complex functions. + +Linker support is found in @file{elflink.c}. The +linker support is only used if the processor specific file defines +@samp{elf_backend_relocate_section}, which is required to relocate the +section contents. If that macro is not defined, the generic linker code +is used, and relocations are handled via @samp{bfd_perform_relocation}. + +The core file support is in @file{elfcore.h}, which is compiled twice, +for both 32 and 64 bit support. The more interesting cases of core file +support only work on a native system which has the @file{sys/procfs.h} +header file. Without that file, the core file support does little more +than read the ELF program segments as BFD sections. + +The BFD internal header file @file{elf-bfd.h} is used for communication +among these files and the processor specific files. + +The default entries for the BFD ELF target vector are found mainly in +@file{elf.c}. Some functions are found in @file{elfcode.h}. + +The processor specific files may override particular entries in the +target vector, but most do not, with one exception: the +@samp{bfd_reloc_type_lookup} entry point is always processor specific. + +@node BFD ELF processor specific support +@subsection BFD ELF processor specific support + +By convention, the processor specific support for a particular processor +will be found in @file{elf@var{nn}-@var{cpu}.c}, where @var{nn} is +either 32 or 64, and @var{cpu} is the name of the processor. + +@menu +* BFD ELF processor required:: Required processor specific support +* BFD ELF processor linker:: Processor specific linker support +* BFD ELF processor other:: Other processor specific support options +@end menu + +@node BFD ELF processor required +@subsubsection Required processor specific support + +When writing a @file{elf@var{nn}-@var{cpu}.c} file, you must do the +following: + +@itemize @bullet +@item +Define either @samp{TARGET_BIG_SYM} or @samp{TARGET_LITTLE_SYM}, or +both, to a unique C name to use for the target vector. This name should +appear in the list of target vectors in @file{targets.c}, and will also +have to appear in @file{config.bfd} and @file{configure.ac}. Define +@samp{TARGET_BIG_SYM} for a big-endian processor, +@samp{TARGET_LITTLE_SYM} for a little-endian processor, and define both +for a bi-endian processor. +@item +Define either @samp{TARGET_BIG_NAME} or @samp{TARGET_LITTLE_NAME}, or +both, to a string used as the name of the target vector. This is the +name which a user of the BFD tool would use to specify the object file +format. It would normally appear in a linker emulation parameters +file. +@item +Define @samp{ELF_ARCH} to the BFD architecture (an element of the +@samp{bfd_architecture} enum, typically @samp{bfd_arch_@var{cpu}}). +@item +Define @samp{ELF_MACHINE_CODE} to the magic number which should appear +in the @samp{e_machine} field of the ELF header. As of this writing, +these magic numbers are assigned by Caldera; if you want to get a magic +number for a particular processor, try sending a note to +@email{registry@@caldera.com}. In the BFD sources, the magic numbers are +found in @file{include/elf/common.h}; they have names beginning with +@samp{EM_}. +@item +Define @samp{ELF_MAXPAGESIZE} to the maximum size of a virtual page in +memory. This can normally be found at the start of chapter 5 in the +processor specific supplement. For a processor which will only be used +in an embedded system, or which has no memory management hardware, this +can simply be @samp{1}. +@item +If the format should use @samp{Rel} rather than @samp{Rela} relocations, +define @samp{USE_REL}. This is normally defined in chapter 4 of the +processor specific supplement. + +In the absence of a supplement, it's easier to work with @samp{Rela} +relocations. @samp{Rela} relocations will require more space in object +files (but not in executables, except when using dynamic linking). +However, this is outweighed by the simplicity of addend handling when +using @samp{Rela} relocations. With @samp{Rel} relocations, the addend +must be stored in the section contents, which makes relocatable links +more complex. + +For example, consider C code like @code{i = a[1000];} where @samp{a} is +a global array. The instructions which load the value of @samp{a[1000]} +will most likely use a relocation which refers to the symbol +representing @samp{a}, with an addend that gives the offset from the +start of @samp{a} to element @samp{1000}. When using @samp{Rel} +relocations, that addend must be stored in the instructions themselves. +If you are adding support for a RISC chip which uses two or more +instructions to load an address, then the addend may not fit in a single +instruction, and will have to be somehow split among the instructions. +This makes linking awkward, particularly when doing a relocatable link +in which the addend may have to be updated. It can be done---the MIPS +ELF support does it---but it should be avoided when possible. + +It is possible, though somewhat awkward, to support both @samp{Rel} and +@samp{Rela} relocations for a single target; @file{elf64-mips.c} does it +by overriding the relocation reading and writing routines. +@item +Define howto structures for all the relocation types. +@item +Define a @samp{bfd_reloc_type_lookup} routine. This must be named +@samp{bfd_elf@var{nn}_bfd_reloc_type_lookup}, and may be either a +function or a macro. It must translate a BFD relocation code into a +howto structure. This is normally a table lookup or a simple switch. +@item +If using @samp{Rel} relocations, define @samp{elf_info_to_howto_rel}. +If using @samp{Rela} relocations, define @samp{elf_info_to_howto}. +Either way, this is a macro defined as the name of a function which +takes an @samp{arelent} and a @samp{Rel} or @samp{Rela} structure, and +sets the @samp{howto} field of the @samp{arelent} based on the +@samp{Rel} or @samp{Rela} structure. This is normally uses +@samp{ELF@var{nn}_R_TYPE} to get the ELF relocation type and uses it as +an index into a table of howto structures. +@end itemize + +You must also add the magic number for this processor to the +@samp{prep_headers} function in @file{elf.c}. + +You must also create a header file in the @file{include/elf} directory +called @file{@var{cpu}.h}. This file should define any target specific +information which may be needed outside of the BFD code. In particular +it should use the @samp{START_RELOC_NUMBERS}, @samp{RELOC_NUMBER}, +@samp{FAKE_RELOC}, @samp{EMPTY_RELOC} and @samp{END_RELOC_NUMBERS} +macros to create a table mapping the number used to identify a +relocation to a name describing that relocation. + +While not a BFD component, you probably also want to make the binutils +program @samp{readelf} parse your ELF objects. For this, you need to add +code for @code{EM_@var{cpu}} as appropriate in @file{binutils/readelf.c}. + +@node BFD ELF processor linker +@subsubsection Processor specific linker support + +The linker will be much more efficient if you define a relocate section +function. This will permit BFD to use the ELF specific linker support. + +If you do not define a relocate section function, BFD must use the +generic linker support, which requires converting all symbols and +relocations into BFD @samp{asymbol} and @samp{arelent} structures. In +this case, relocations will be handled by calling +@samp{bfd_perform_relocation}, which will use the howto structures you +have defined. @xref{BFD relocation handling}. + +In order to support linking into a different object file format, such as +S-records, @samp{bfd_perform_relocation} must work correctly with your +howto structures, so you can't skip that step. However, if you define +the relocate section function, then in the normal case of linking into +an ELF file the linker will not need to convert symbols and relocations, +and will be much more efficient. + +To use a relocation section function, define the macro +@samp{elf_backend_relocate_section} as the name of a function which will +take the contents of a section, as well as relocation, symbol, and other +information, and modify the section contents according to the relocation +information. In simple cases, this is little more than a loop over the +relocations which computes the value of each relocation and calls +@samp{_bfd_final_link_relocate}. The function must check for a +relocatable link, and in that case normally needs to do nothing other +than adjust the addend for relocations against a section symbol. + +The complex cases generally have to do with dynamic linker support. GOT +and PLT relocations must be handled specially, and the linker normally +arranges to set up the GOT and PLT sections while handling relocations. +When generating a shared library, random relocations must normally be +copied into the shared library, or converted to RELATIVE relocations +when possible. + +@node BFD ELF processor other +@subsubsection Other processor specific support options + +There are many other macros which may be defined in +@file{elf@var{nn}-@var{cpu}.c}. These macros may be found in +@file{elfxx-target.h}. + +Macros may be used to override some of the generic ELF target vector +functions. + +Several processor specific hook functions which may be defined as +macros. These functions are found as function pointers in the +@samp{elf_backend_data} structure defined in @file{elf-bfd.h}. In +general, a hook function is set by defining a macro +@samp{elf_backend_@var{name}}. + +There are a few processor specific constants which may also be defined. +These are again found in the @samp{elf_backend_data} structure. + +I will not define the various functions and constants here; see the +comments in @file{elf-bfd.h}. + +Normally any odd characteristic of a particular ELF processor is handled +via a hook function. For example, the special @samp{SHN_MIPS_SCOMMON} +section number found in MIPS ELF is handled via the hooks +@samp{section_from_bfd_section}, @samp{symbol_processing}, +@samp{add_symbol_hook}, and @samp{output_symbol_hook}. + +Dynamic linking support, which involves processor specific relocations +requiring special handling, is also implemented via hook functions. + +@node BFD ELF core files +@subsection BFD ELF core files +@cindex elf core files + +On native ELF Unix systems, core files are generated without any +sections. Instead, they only have program segments. + +When BFD is used to read an ELF core file, the BFD sections will +actually represent program segments. Since ELF program segments do not +have names, BFD will invent names like @samp{segment@var{n}} where +@var{n} is a number. + +A single ELF program segment may include both an initialized part and an +uninitialized part. The size of the initialized part is given by the +@samp{p_filesz} field. The total size of the segment is given by the +@samp{p_memsz} field. If @samp{p_memsz} is larger than @samp{p_filesz}, +then the extra space is uninitialized, or, more precisely, initialized +to zero. + +BFD will represent such a program segment as two different sections. +The first, named @samp{segment@var{n}a}, will represent the initialized +part of the program segment. The second, named @samp{segment@var{n}b}, +will represent the uninitialized part. + +ELF core files store special information such as register values in +program segments with the type @samp{PT_NOTE}. BFD will attempt to +interpret the information in these segments, and will create additional +sections holding the information. Some of this interpretation requires +information found in the host header file @file{sys/procfs.h}, and so +will only work when BFD is built on a native system. + +BFD does not currently provide any way to create an ELF core file. In +general, BFD does not provide a way to create core files. The way to +implement this would be to write @samp{bfd_set_format} and +@samp{bfd_write_contents} routines for the @samp{bfd_core} type; see +@ref{BFD target vector format}. + +@node BFD ELF future +@subsection BFD ELF future + +The current dynamic linking support has too much code duplication. +While each processor has particular differences, much of the dynamic +linking support is quite similar for each processor. The GOT and PLT +are handled in fairly similar ways, the details of -Bsymbolic linking +are generally similar, etc. This code should be reworked to use more +generic functions, eliminating the duplication. + +Similarly, the relocation handling has too much duplication. Many of +the @samp{reloc_type_lookup} and @samp{info_to_howto} functions are +quite similar. The relocate section functions are also often quite +similar, both in the standard linker handling and the dynamic linker +handling. Many of the COFF processor specific backends share a single +relocate section function (@samp{_bfd_coff_generic_relocate_section}), +and it should be possible to do something like this for the ELF targets +as well. + +The appearance of the processor specific magic number in +@samp{prep_headers} in @file{elf.c} is somewhat bogus. It should be +possible to add support for a new processor without changing the generic +support. + +The processor function hooks and constants are ad hoc and need better +documentation. + +@node BFD glossary +@section BFD glossary +@cindex glossary for bfd +@cindex bfd glossary + +This is a short glossary of some BFD terms. + +@table @asis +@item a.out +The a.out object file format. The original Unix object file format. +Still used on SunOS, though not Solaris. Supports only three sections. + +@item archive +A collection of object files produced and manipulated by the @samp{ar} +program. + +@item backend +The implementation within BFD of a particular object file format. The +set of functions which appear in a particular target vector. + +@item BFD +The BFD library itself. Also, each object file, archive, or executable +opened by the BFD library has the type @samp{bfd *}, and is sometimes +referred to as a bfd. + +@item COFF +The Common Object File Format. Used on Unix SVR3. Used by some +embedded targets, although ELF is normally better. + +@item DLL +A shared library on Windows. + +@item dynamic linker +When a program linked against a shared library is run, the dynamic +linker will locate the appropriate shared library and arrange to somehow +include it in the running image. + +@item dynamic object +Another name for an ELF shared library. + +@item ECOFF +The Extended Common Object File Format. Used on Alpha Digital Unix +(formerly OSF/1), as well as Ultrix and Irix 4. A variant of COFF. + +@item ELF +The Executable and Linking Format. The object file format used on most +modern Unix systems, including GNU/Linux, Solaris, Irix, and SVR4. Also +used on many embedded systems. + +@item executable +A program, with instructions and symbols, and perhaps dynamic linking +information. Normally produced by a linker. + +@item LMA +Load Memory Address. This is the address at which a section will be +loaded. Compare with VMA, below. + +@item object file +A binary file including machine instructions, symbols, and relocation +information. Normally produced by an assembler. + +@item object file format +The format of an object file. Typically object files and executables +for a particular system are in the same format, although executables +will not contain any relocation information. + +@item PE +The Portable Executable format. This is the object file format used for +Windows (specifically, Win32) object files. It is based closely on +COFF, but has a few significant differences. + +@item PEI +The Portable Executable Image format. This is the object file format +used for Windows (specifically, Win32) executables. It is very similar +to PE, but includes some additional header information. + +@item relocations +Information used by the linker to adjust section contents. Also called +relocs. + +@item section +Object files and executable are composed of sections. Sections have +optional data and optional relocation information. + +@item shared library +A library of functions which may be used by many executables without +actually being linked into each executable. There are several different +implementations of shared libraries, each having slightly different +features. + +@item symbol +Each object file and executable may have a list of symbols, often +referred to as the symbol table. A symbol is basically a name and an +address. There may also be some additional information like the type of +symbol, although the type of a symbol is normally something simple like +function or object, and should be confused with the more complex C +notion of type. Typically every global function and variable in a C +program will have an associated symbol. + +@item target vector +A set of functions which implement support for a particular object file +format. The @samp{bfd_target} structure. + +@item Win32 +The current Windows API, implemented by Windows 95 and later and Windows +NT 3.51 and later, but not by Windows 3.1. + +@item XCOFF +The eXtended Common Object File Format. Used on AIX. A variant of +COFF, with a completely different symbol table implementation. + +@item VMA +Virtual Memory Address. This is the address a section will have when +an executable is run. Compare with LMA, above. +@end table + +@node Index +@unnumberedsec Index +@printindex cp + +@contents +@bye diff -pruN 16.3-5/bfd/doc/bfdio.texi 16.3-5ubuntu1/bfd/doc/bfdio.texi --- 16.3-5/bfd/doc/bfdio.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfdio.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,146 @@ +@findex struct bfd_iovec +@subsubsection @code{struct bfd_iovec} +The @code{struct bfd_iovec} contains the internal file I/O class. +Each @code{BFD} has an instance of this class and all file I/O is +routed through it (it is assumed that the instance implements +all methods listed below). +@example +struct bfd_iovec +@{ + /* To avoid problems with macros, a "b" rather than "f" + prefix is prepended to each method name. */ + /* Attempt to read/write NBYTES on ABFD's IOSTREAM storing/fetching + bytes starting at PTR. Return the number of bytes actually + transfered (a read past end-of-file returns less than NBYTES), + or -1 (setting @code{bfd_error}) if an error occurs. */ + file_ptr (*bread) (struct bfd *abfd, void *ptr, file_ptr nbytes); + file_ptr (*bwrite) (struct bfd *abfd, const void *ptr, + file_ptr nbytes); + /* Return the current IOSTREAM file offset, or -1 (setting @code{bfd_error} + if an error occurs. */ + file_ptr (*btell) (struct bfd *abfd); + /* For the following, on successful completion a value of 0 is returned. + Otherwise, a value of -1 is returned (and @code{bfd_error} is set). */ + int (*bseek) (struct bfd *abfd, file_ptr offset, int whence); + int (*bclose) (struct bfd *abfd); + int (*bflush) (struct bfd *abfd); + int (*bstat) (struct bfd *abfd, struct stat *sb); + /* Mmap a part of the files. ADDR, LEN, PROT, FLAGS and OFFSET are the usual + mmap parameter, except that LEN and OFFSET do not need to be page + aligned. Returns (void *)-1 on failure, mmapped address on success. + Also write in MAP_ADDR the address of the page aligned buffer and in + MAP_LEN the size mapped (a page multiple). Use unmap with MAP_ADDR and + MAP_LEN to unmap. */ + void *(*bmmap) (struct bfd *abfd, void *addr, size_t len, + int prot, int flags, file_ptr offset, + void **map_addr, size_t *map_len); +@}; +extern const struct bfd_iovec _bfd_memory_iovec; +@end example + +@findex bfd_read +@subsubsection @code{bfd_read} +@deftypefn {Function} bfd_size_type bfd_read (void *, bfd_size_type, bfd *) ATTRIBUTE_WARN_UNUSED_RESULT; +Attempt to read SIZE bytes from ABFD's iostream to PTR. +Return the amount read. + +@end deftypefn +@findex bfd_write +@subsubsection @code{bfd_write} +@deftypefn {Function} bfd_size_type bfd_write (const void *, bfd_size_type, bfd *) ATTRIBUTE_WARN_UNUSED_RESULT; +Attempt to write SIZE bytes to ABFD's iostream from PTR. +Return the amount written. + +@end deftypefn +@findex bfd_tell +@subsubsection @code{bfd_tell} +@deftypefn {Function} file_ptr bfd_tell (bfd *) ATTRIBUTE_WARN_UNUSED_RESULT; +Return ABFD's iostream file position. + +@end deftypefn +@findex bfd_flush +@subsubsection @code{bfd_flush} +@deftypefn {Function} int bfd_flush (bfd *); +Flush ABFD's iostream pending IO. + +@end deftypefn +@findex bfd_stat +@subsubsection @code{bfd_stat} +@deftypefn {Function} int bfd_stat (bfd *, struct stat *) ATTRIBUTE_WARN_UNUSED_RESULT; +Call fstat on ABFD's iostream. Return 0 on success, and a +negative value on failure. + +@end deftypefn +@findex bfd_seek +@subsubsection @code{bfd_seek} +@deftypefn {Function} int bfd_seek (bfd *, file_ptr, int) ATTRIBUTE_WARN_UNUSED_RESULT; +Call fseek on ABFD's iostream. Return 0 on success, and a +negative value on failure. + +@end deftypefn +@findex bfd_get_mtime +@subsubsection @code{bfd_get_mtime} +@deftypefn {Function} long bfd_get_mtime (bfd *abfd); +Return the file modification time (as read from the file system, or +from the archive header for archive members). + +@end deftypefn +@findex bfd_get_size +@subsubsection @code{bfd_get_size} +@deftypefn {Function} ufile_ptr bfd_get_size (bfd *abfd); +Return the file size (as read from file system) for the file +associated with BFD @var{abfd}. + +The initial motivation for, and use of, this routine is not +so we can get the exact size of the object the BFD applies to, since +that might not be generally possible (archive members for example). +It would be ideal if someone could eventually modify +it so that such results were guaranteed. + +Instead, we want to ask questions like "is this NNN byte sized +object I'm about to try read from file offset YYY reasonable?" +As as example of where we might do this, some object formats +use string tables for which the first @code{sizeof (long)} bytes of the +table contain the size of the table itself, including the size bytes. +If an application tries to read what it thinks is one of these +string tables, without some way to validate the size, and for +some reason the size is wrong (byte swapping error, wrong location +for the string table, etc.), the only clue is likely to be a read +error when it tries to read the table, or a "virtual memory +exhausted" error when it tries to allocate 15 bazillon bytes +of space for the 15 bazillon byte table it is about to read. +This function at least allows us to answer the question, "is the +size reasonable?". + +A return value of zero indicates the file size is unknown. + +@end deftypefn +@findex bfd_get_file_size +@subsubsection @code{bfd_get_file_size} +@deftypefn {Function} ufile_ptr bfd_get_file_size (bfd *abfd); +Return the file size (as read from file system) for the file +associated with BFD @var{abfd}. It supports both normal files +and archive elements. + +@end deftypefn +@findex bfd_mmap +@subsubsection @code{bfd_mmap} +@deftypefn {Function} void *bfd_mmap (bfd *abfd, void *addr, size_t len, int prot, int flags, file_ptr offset, void **map_addr, size_t *map_len) ATTRIBUTE_WARN_UNUSED_RESULT; +Return mmap()ed region of the file, if possible and implemented. +LEN and OFFSET do not need to be page aligned. The page aligned +address and length are written to MAP_ADDR and MAP_LEN. + +@end deftypefn +@findex bfd_get_current_time +@subsubsection @code{bfd_get_current_time} +@deftypefn {Function} time_t bfd_get_current_time (time_t now); +Returns the current time. + +If the environment variable SOURCE_DATE_EPOCH is defined +then this is parsed and its value is returned. Otherwise +if the paramter NOW is non-zero, then that is returned. +Otherwise the result of the system call "time(NULL)" is +returned. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/bfdsumm.texi 16.3-5ubuntu1/bfd/doc/bfdsumm.texi --- 16.3-5/bfd/doc/bfdsumm.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfdsumm.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,150 @@ +@c This summary of BFD is shared by the BFD and LD docs. +@c Copyright (C) 2012-2024 Free Software Foundation, Inc. +When an object file is opened, BFD subroutines automatically determine +the format of the input object file. They then build a descriptor in +memory with pointers to routines that will be used to access elements of +the object file's data structures. + +As different information from the object files is required, +BFD reads from different sections of the file and processes them. +For example, a very common operation for the linker is processing symbol +tables. Each BFD back end provides a routine for converting +between the object file's representation of symbols and an internal +canonical format. When the linker asks for the symbol table of an object +file, it calls through a memory pointer to the routine from the +relevant BFD back end which reads and converts the table into a canonical +form. The linker then operates upon the canonical form. When the link is +finished and the linker writes the output file's symbol table, +another BFD back end routine is called to take the newly +created symbol table and convert it into the chosen output format. + +@menu +* BFD information loss:: Information Loss +* Canonical format:: The BFD canonical object-file format +@end menu + +@node BFD information loss +@subsection Information Loss + +@emph{Information can be lost during output.} The output formats +supported by BFD do not provide identical facilities, and +information which can be described in one form has nowhere to go in +another format. One example of this is alignment information in +@code{b.out}. There is nowhere in an @code{a.out} format file to store +alignment information on the contained data, so when a file is linked +from @code{b.out} and an @code{a.out} image is produced, alignment +information will not propagate to the output file. (The linker will +still use the alignment information internally, so the link is performed +correctly). + +Another example is COFF section names. COFF files may contain an +unlimited number of sections, each one with a textual section name. If +the target of the link is a format which does not have many sections (e.g., +@code{a.out}) or has sections without names (e.g., the Oasys format), the +link cannot be done simply. You can circumvent this problem by +describing the desired input-to-output section mapping with the linker command +language. + +@emph{Information can be lost during canonicalization.} The BFD +internal canonical form of the external formats is not exhaustive; there +are structures in input formats for which there is no direct +representation internally. This means that the BFD back ends +cannot maintain all possible data richness through the transformation +between external to internal and back to external formats. + +This limitation is only a problem when an application reads one +format and writes another. Each BFD back end is responsible for +maintaining as much data as possible, and the internal BFD +canonical form has structures which are opaque to the BFD core, +and exported only to the back ends. When a file is read in one format, +the canonical form is generated for BFD and the application. At the +same time, the back end saves away any information which may otherwise +be lost. If the data is then written back in the same format, the back +end routine will be able to use the canonical form provided by the +BFD core as well as the information it prepared earlier. Since +there is a great deal of commonality between back ends, +there is no information lost when +linking or copying big endian COFF to little endian COFF, or @code{a.out} to +@code{b.out}. When a mixture of formats is linked, the information is +only lost from the files whose format differs from the destination. + +@node Canonical format +@subsection The BFD canonical object-file format + +The greatest potential for loss of information occurs when there is the least +overlap between the information provided by the source format, that +stored by the canonical format, and that needed by the +destination format. A brief description of the canonical form may help +you understand which kinds of data you can count on preserving across +conversions. +@cindex BFD canonical format +@cindex internal object-file format + +@table @emph +@item files +Information stored on a per-file basis includes target machine +architecture, particular implementation format type, a demand pageable +bit, and a write protected bit. Information like Unix magic numbers is +not stored here---only the magic numbers' meaning, so a @code{ZMAGIC} +file would have both the demand pageable bit and the write protected +text bit set. The byte order of the target is stored on a per-file +basis, so that big- and little-endian object files may be used with one +another. + +@item sections +Each section in the input file contains the name of the section, the +section's original address in the object file, size and alignment +information, various flags, and pointers into other BFD data +structures. + +@item symbols +Each symbol contains a pointer to the information for the object file +which originally defined it, its name, its value, and various flag +bits. When a BFD back end reads in a symbol table, it relocates all +symbols to make them relative to the base of the section where they were +defined. Doing this ensures that each symbol points to its containing +section. Each symbol also has a varying amount of hidden private data +for the BFD back end. Since the symbol points to the original file, the +private data format for that symbol is accessible. @code{ld} can +operate on a collection of symbols of wildly different formats without +problems. + +Normal global and simple local symbols are maintained on output, so an +output file (no matter its format) will retain symbols pointing to +functions and to global, static, and common variables. Some symbol +information is not worth retaining; in @code{a.out}, type information is +stored in the symbol table as long symbol names. This information would +be useless to most COFF debuggers; the linker has command-line switches +to allow users to throw it away. + +There is one word of type information within the symbol, so if the +format supports symbol type information within symbols (for example, COFF, +Oasys) and the type is simple enough to fit within one word +(nearly everything but aggregates), the information will be preserved. + +@item relocation level +Each canonical BFD relocation record contains a pointer to the symbol to +relocate to, the offset of the data to relocate, the section the data +is in, and a pointer to a relocation type descriptor. Relocation is +performed by passing messages through the relocation type +descriptor and the symbol pointer. Therefore, relocations can be performed +on output data using a relocation method that is only available in one of the +input formats. For instance, Oasys provides a byte relocation format. +A relocation record requesting this relocation type would point +indirectly to a routine to perform this, so the relocation may be +performed on a byte being written to a 68k COFF file, even though 68k COFF +has no such relocation type. + +@item line numbers +Object formats can contain, for debugging purposes, some form of mapping +between symbols, source line numbers, and addresses in the output file. +These addresses have to be relocated along with the symbol information. +Each symbol with an associated list of line number records points to the +first record of the list. The head of a line number list consists of a +pointer to the symbol, which allows finding out the address of the +function whose line number is being described. The rest of the list is +made up of pairs: offsets into the section and line numbers. Any format +which can simply derive this information can pass it successfully +between formats. +@end table diff -pruN 16.3-5/bfd/doc/bfdt.texi 16.3-5ubuntu1/bfd/doc/bfdt.texi --- 16.3-5/bfd/doc/bfdt.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfdt.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,987 @@ +@node typedef bfd, Error reporting, BFD front end, BFD front end +@section @code{typedef bfd} +A BFD has type @code{bfd}; objects of this type are the +cornerstone of any application using BFD. Using BFD +consists of making references though the BFD and to data in the BFD. +Here is the structure that defines the type @code{bfd}. It +contains the major data about the file and pointers +to the rest of the data. + + +@example +struct bfd +@{ + /* The filename the application opened the BFD with. */ + const char *filename; + + /* A pointer to the target jump table. */ + const struct bfd_target *xvec; + + /* The IOSTREAM, and corresponding IO vector that provide access + to the file backing the BFD. */ + void *iostream; + const struct bfd_iovec *iovec; + + /* The caching routines use these to maintain a + least-recently-used list of BFDs. */ + struct bfd *lru_prev, *lru_next; + + /* Track current file position (or current buffer offset for + in-memory BFDs). When a file is closed by the caching routines, + BFD retains state information on the file here. */ + ufile_ptr where; + + /* File modified time, if mtime_set is TRUE. */ + long mtime; + + /* A unique identifier of the BFD */ + unsigned int id; + + /* Format_specific flags. */ + flagword flags; + + /* Values that may appear in the flags field of a BFD. These also + appear in the object_flags field of the bfd_target structure, where + they indicate the set of flags used by that backend (not all flags + are meaningful for all object file formats) (FIXME: at the moment, + the object_flags values have mostly just been copied from backend + to another, and are not necessarily correct). */ + +#define BFD_NO_FLAGS 0x0 + + /* BFD contains relocation entries. */ +#define HAS_RELOC 0x1 + + /* BFD is directly executable. */ +#define EXEC_P 0x2 + + /* BFD has line number information (basically used for F_LNNO in a + COFF header). */ +#define HAS_LINENO 0x4 + + /* BFD has debugging information. */ +#define HAS_DEBUG 0x08 + + /* BFD has symbols. */ +#define HAS_SYMS 0x10 + + /* BFD has local symbols (basically used for F_LSYMS in a COFF + header). */ +#define HAS_LOCALS 0x20 + + /* BFD is a dynamic object. */ +#define DYNAMIC 0x40 + + /* Text section is write protected (if D_PAGED is not set, this is + like an a.out NMAGIC file) (the linker sets this by default, but + clears it for -r or -N). */ +#define WP_TEXT 0x80 + + /* BFD is dynamically paged (this is like an a.out ZMAGIC file) (the + linker sets this by default, but clears it for -r or -n or -N). */ +#define D_PAGED 0x100 + + /* BFD is relaxable (this means that bfd_relax_section may be able to + do something) (sometimes bfd_relax_section can do something even if + this is not set). */ +#define BFD_IS_RELAXABLE 0x200 + + /* This may be set before writing out a BFD to request using a + traditional format. For example, this is used to request that when + writing out an a.out object the symbols not be hashed to eliminate + duplicates. */ +#define BFD_TRADITIONAL_FORMAT 0x400 + + /* This flag indicates that the BFD contents are actually cached + in memory. If this is set, iostream points to a malloc'd + bfd_in_memory struct. */ +#define BFD_IN_MEMORY 0x800 + + /* This BFD has been created by the linker and doesn't correspond + to any input file. */ +#define BFD_LINKER_CREATED 0x1000 + + /* This may be set before writing out a BFD to request that it + be written using values for UIDs, GIDs, timestamps, etc. that + will be consistent from run to run. */ +#define BFD_DETERMINISTIC_OUTPUT 0x2000 + + /* Compress sections in this BFD. */ +#define BFD_COMPRESS 0x4000 + + /* Decompress sections in this BFD. */ +#define BFD_DECOMPRESS 0x8000 + + /* BFD is a dummy, for plugins. */ +#define BFD_PLUGIN 0x10000 + + /* Compress sections in this BFD with SHF_COMPRESSED from gABI. */ +#define BFD_COMPRESS_GABI 0x20000 + + /* Convert ELF common symbol type to STT_COMMON or STT_OBJECT in this + BFD. */ +#define BFD_CONVERT_ELF_COMMON 0x40000 + + /* Use the ELF STT_COMMON type in this BFD. */ +#define BFD_USE_ELF_STT_COMMON 0x80000 + + /* Put pathnames into archives (non-POSIX). */ +#define BFD_ARCHIVE_FULL_PATH 0x100000 + +#define BFD_CLOSED_BY_CACHE 0x200000 + /* Compress sections in this BFD with SHF_COMPRESSED zstd. */ +#define BFD_COMPRESS_ZSTD 0x400000 + + /* Don't generate ELF section header. */ +#define BFD_NO_SECTION_HEADER 0x800000 + + /* Flags bits which are for BFD use only. */ +#define BFD_FLAGS_FOR_BFD_USE_MASK \ + (BFD_IN_MEMORY | BFD_COMPRESS | BFD_DECOMPRESS | BFD_LINKER_CREATED \ + | BFD_PLUGIN | BFD_TRADITIONAL_FORMAT | BFD_DETERMINISTIC_OUTPUT \ + | BFD_COMPRESS_GABI | BFD_CONVERT_ELF_COMMON | BFD_USE_ELF_STT_COMMON \ + | BFD_NO_SECTION_HEADER) + + /* The format which belongs to the BFD. (object, core, etc.) */ + ENUM_BITFIELD (bfd_format) format : 3; + + /* The direction with which the BFD was opened. */ + ENUM_BITFIELD (bfd_direction) direction : 2; + + /* POSIX.1-2017 (IEEE Std 1003.1) says of fopen : "When a file is + opened with update mode ('+' as the second or third character in + the mode argument), both input and output may be performed on + the associated stream. However, the application shall ensure + that output is not directly followed by input without an + intervening call to fflush() or to a file positioning function + (fseek(), fsetpos(), or rewind()), and input is not directly + followed by output without an intervening call to a file + positioning function, unless the input operation encounters + end-of-file." + This field tracks the last IO operation, so that bfd can insert + a seek when IO direction changes. */ + ENUM_BITFIELD (bfd_last_io) last_io : 2; + + /* Is the file descriptor being cached? That is, can it be closed as + needed, and re-opened when accessed later? */ + unsigned int cacheable : 1; + + /* Marks whether there was a default target specified when the + BFD was opened. This is used to select which matching algorithm + to use to choose the back end. */ + unsigned int target_defaulted : 1; + + /* ... and here: (``once'' means at least once). */ + unsigned int opened_once : 1; + + /* Set if we have a locally maintained mtime value, rather than + getting it from the file each time. */ + unsigned int mtime_set : 1; + + /* Flag set if symbols from this BFD should not be exported. */ + unsigned int no_export : 1; + + /* Remember when output has begun, to stop strange things + from happening. */ + unsigned int output_has_begun : 1; + + /* Have archive map. */ + unsigned int has_armap : 1; + + /* Set if this is a thin archive. */ + unsigned int is_thin_archive : 1; + + /* Set if this archive should not cache element positions. */ + unsigned int no_element_cache : 1; + + /* Set if only required symbols should be added in the link hash table for + this object. Used by VMS linkers. */ + unsigned int selective_search : 1; + + /* Set if this is the linker output BFD. */ + unsigned int is_linker_output : 1; + + /* Set if this is the linker input BFD. */ + unsigned int is_linker_input : 1; + + /* If this is an input for a compiler plug-in library. */ + ENUM_BITFIELD (bfd_plugin_format) plugin_format : 2; + + /* Set if this is a plugin output file. */ + unsigned int lto_output : 1; + + /* Do not attempt to modify this file. Set when detecting errors + that BFD is not prepared to handle for objcopy/strip. */ + unsigned int read_only : 1; + + /* LTO object type. */ + ENUM_BITFIELD (bfd_lto_object_type) lto_type : 2; + + /* Set if this BFD is currently being processed by + bfd_check_format_matches. This is checked by the cache to + avoid closing the BFD in this case. This should only be + examined or modified while the BFD lock is held. */ + unsigned int in_format_matches : 1; + + /* Set to dummy BFD created when claimed by a compiler plug-in + library. */ + bfd *plugin_dummy_bfd; + + /* The offset of this bfd in the file, typically 0 if it is not + contained in an archive. */ + ufile_ptr origin; + + /* The origin in the archive of the proxy entry. This will + normally be the same as origin, except for thin archives, + when it will contain the current offset of the proxy in the + thin archive rather than the offset of the bfd in its actual + container. */ + ufile_ptr proxy_origin; + + /* A hash table for section names. */ + struct bfd_hash_table section_htab; + + /* Pointer to linked list of sections. */ + struct bfd_section *sections; + + /* The last section on the section list. */ + struct bfd_section *section_last; + + /* The number of sections. */ + unsigned int section_count; + + /* The archive plugin file descriptor. */ + int archive_plugin_fd; + + /* The number of opens on the archive plugin file descriptor. */ + unsigned int archive_plugin_fd_open_count; + + /* A field used by _bfd_generic_link_add_archive_symbols. This will + be used only for archive elements. */ + int archive_pass; + + /* The total size of memory from bfd_alloc. */ + bfd_size_type alloc_size; + + /* Stuff only useful for object files: + The start address. */ + bfd_vma start_address; + + /* Symbol table for output BFD (with symcount entries). + Also used by the linker to cache input BFD symbols. */ + struct bfd_symbol **outsymbols; + + /* Used for input and output. */ + unsigned int symcount; + + /* Used for slurped dynamic symbol tables. */ + unsigned int dynsymcount; + + /* Pointer to structure which contains architecture information. */ + const struct bfd_arch_info *arch_info; + + /* Cached length of file for bfd_get_size. 0 until bfd_get_size is + called, 1 if stat returns an error or the file size is too large to + return in ufile_ptr. Both 0 and 1 should be treated as "unknown". */ + ufile_ptr size; + + /* Stuff only useful for archives. */ + void *arelt_data; + struct bfd *my_archive; /* The containing archive BFD. */ + struct bfd *archive_next; /* The next BFD in the archive. */ + struct bfd *archive_head; /* The first BFD in the archive. */ + struct bfd *nested_archives; /* List of nested archive in a flattened + thin archive. */ + + union @{ + /* For input BFDs, a chain of BFDs involved in a link. */ + struct bfd *next; + /* For output BFD, the linker hash table. */ + struct bfd_link_hash_table *hash; + @} link; + + /* Used by the back end to hold private data. */ + union + @{ + struct aout_data_struct *aout_data; + struct artdata *aout_ar_data; + struct coff_tdata *coff_obj_data; + struct pe_tdata *pe_obj_data; + struct xcoff_tdata *xcoff_obj_data; + struct ecoff_tdata *ecoff_obj_data; + struct srec_data_struct *srec_data; + struct verilog_data_struct *verilog_data; + struct ihex_data_struct *ihex_data; + struct tekhex_data_struct *tekhex_data; + struct elf_obj_tdata *elf_obj_data; + struct mmo_data_struct *mmo_data; + struct trad_core_struct *trad_core_data; + struct som_data_struct *som_data; + struct hpux_core_struct *hpux_core_data; + struct hppabsd_core_struct *hppabsd_core_data; + struct sgi_core_struct *sgi_core_data; + struct lynx_core_struct *lynx_core_data; + struct osf_core_struct *osf_core_data; + struct cisco_core_struct *cisco_core_data; + struct netbsd_core_struct *netbsd_core_data; + struct mach_o_data_struct *mach_o_data; + struct mach_o_fat_data_struct *mach_o_fat_data; + struct plugin_data_struct *plugin_data; + struct bfd_pef_data_struct *pef_data; + struct bfd_pef_xlib_data_struct *pef_xlib_data; + struct bfd_sym_data_struct *sym_data; + void *any; + @} + tdata; + + /* Used by the application to hold private data. */ + void *usrdata; + + /* Where all the allocated stuff under this BFD goes. This is a + struct objalloc *, but we use void * to avoid requiring the inclusion + of objalloc.h. */ + void *memory; + + /* For input BFDs, the build ID, if the object has one. */ + const struct bfd_build_id *build_id; + + /* For input BFDs, mmapped entries. */ + struct bfd_mmapped *mmapped; +@}; + +@end example +@node Error reporting, Initialization, typedef bfd, BFD front end +@section Error reporting +Most BFD functions return nonzero on success (check their +individual documentation for precise semantics). On an error, +they call @code{bfd_set_error} to set an error condition that callers +can check by calling @code{bfd_get_error}. +If that returns @code{bfd_error_system_call}, then check +@code{errno}. + +The easiest way to report a BFD error to the user is to +use @code{bfd_perror}. + +The BFD error is thread-local. + +@subsection Type @code{bfd_error_type} +The values returned by @code{bfd_get_error} are defined by the +enumerated type @code{bfd_error_type}. + + +@example +typedef enum bfd_error +@{ + bfd_error_no_error = 0, + bfd_error_system_call, + bfd_error_invalid_target, + bfd_error_wrong_format, + bfd_error_wrong_object_format, + bfd_error_invalid_operation, + bfd_error_no_memory, + bfd_error_no_symbols, + bfd_error_no_armap, + bfd_error_no_more_archived_files, + bfd_error_malformed_archive, + bfd_error_missing_dso, + bfd_error_file_not_recognized, + bfd_error_file_ambiguously_recognized, + bfd_error_no_contents, + bfd_error_nonrepresentable_section, + bfd_error_no_debug_section, + bfd_error_bad_value, + bfd_error_file_truncated, + bfd_error_file_too_big, + bfd_error_sorry, + bfd_error_on_input, + bfd_error_invalid_error_code +@} +bfd_error_type; + +@end example +@findex bfd_get_error +@subsubsection @code{bfd_get_error} +@deftypefn {Function} bfd_error_type bfd_get_error (void); +Return the current BFD error condition. + +@end deftypefn +@findex bfd_set_error +@subsubsection @code{bfd_set_error} +@deftypefn {Function} void bfd_set_error (bfd_error_type error_tag); +Set the BFD error condition to be @var{error_tag}. + +@var{error_tag} must not be bfd_error_on_input. Use +bfd_set_input_error for input errors instead. + +@end deftypefn +@findex bfd_set_input_error +@subsubsection @code{bfd_set_input_error} +@deftypefn {Function} void bfd_set_input_error (bfd *input, bfd_error_type error_tag); +Set the BFD error condition to be bfd_error_on_input. +@var{input} is the input bfd where the error occurred, and +@var{error_tag} the bfd_error_type error. + +@end deftypefn +@findex bfd_errmsg +@subsubsection @code{bfd_errmsg} +@deftypefn {Function} const char *bfd_errmsg (bfd_error_type error_tag); +Return a string describing the error @var{error_tag}, or +the system error if @var{error_tag} is @code{bfd_error_system_call}. + +@end deftypefn +@findex bfd_perror +@subsubsection @code{bfd_perror} +@deftypefn {Function} void bfd_perror (const char *message); +Print to the standard error stream a string describing the +last BFD error that occurred, or the last system error if +the last BFD error was a system call failure. If @var{message} +is non-NULL and non-empty, the error string printed is preceded +by @var{message}, a colon, and a space. It is followed by a newline. + +@end deftypefn +@findex _bfd_clear_error_data +@subsubsection @code{_bfd_clear_error_data} +@deftypefn {Function} void _bfd_clear_error_data (void); +Free any data associated with the BFD error. + +@end deftypefn +@findex bfd_asprintf +@subsubsection @code{bfd_asprintf} +@deftypefn {Function} char *bfd_asprintf (const char *fmt, ...); +Primarily for error reporting, this function is like +libiberty's xasprintf except that it can return NULL on no +memory and the returned string should not be freed. Uses a +thread-local malloc'd buffer managed by libbfd, _bfd_error_buf. +Be aware that a call to this function frees the result of any +previous call. bfd_errmsg (bfd_error_on_input) also calls +this function. + +@end deftypefn +@subsection BFD error handler +Some BFD functions want to print messages describing the +problem. They call a BFD error handler function. This +function may be overridden by the program. + +The BFD error handler acts like vprintf. + + +@example +typedef void (*bfd_error_handler_type) (const char *, va_list); + +@end example + +@example +typedef int (*bfd_print_callback) (void *, const char *, ...); +@end example +@findex bfd_print_error +@subsubsection @code{bfd_print_error} +@deftypefn {Function} void bfd_print_error (bfd_print_callback print_func, void *stream, const char *fmt, va_list ap); +This formats FMT and AP according to BFD "printf" rules, +sending the output to STREAM by repeated calls to PRINT_FUNC. +PRINT_FUNC is a printf-like function; it does not need to +implement the BFD printf format extensions. This can be used +in a callback that is set via bfd_set_error_handler to turn +the error into ordinary output. + +@end deftypefn +@findex _bfd_error_handler +@subsubsection @code{_bfd_error_handler} +@deftypefn {Function} void _bfd_error_handler (const char *fmt, ...) ATTRIBUTE_PRINTF_1; +This is the default routine to handle BFD error messages. +Like fprintf (stderr, ...), but also handles some extra format +specifiers. + +%pA section name from section. For group components, prints +group name too. +%pB file name from bfd. For archive components, prints +archive too. + +Beware: Only supports a maximum of 9 format arguments. + +@end deftypefn +@findex bfd_set_error_handler +@subsubsection @code{bfd_set_error_handler} +@deftypefn {Function} bfd_error_handler_type bfd_set_error_handler (bfd_error_handler_type); +Set the BFD error handler function. Returns the previous +function. + +@end deftypefn +@findex _bfd_set_error_handler_caching +@subsubsection @code{_bfd_set_error_handler_caching} +@deftypefn {Function} struct per_xvec_messages *_bfd_set_error_handler_caching (struct per_xvec_messages *); +Set the BFD error handler function to one that stores messages +to the per_xvec_messages object. Returns the previous object +to which messages are stored. Note that two sequential calls +to this with a non-NULL argument will cause output to be +dropped, rather than gathered. + +@end deftypefn +@findex _bfd_restore_error_handler_caching +@subsubsection @code{_bfd_restore_error_handler_caching} +@deftypefn {Function} void _bfd_restore_error_handler_caching (struct per_xvec_messages *); +Reset the BFD error handler object to an earlier value. + +@end deftypefn +@findex bfd_set_error_program_name +@subsubsection @code{bfd_set_error_program_name} +@deftypefn {Function} void bfd_set_error_program_name (const char *); +Set the program name to use when printing a BFD error. This +is printed before the error message followed by a colon and +space. The string must not be changed after it is passed to +this function. + +@end deftypefn +@findex _bfd_get_error_program_name +@subsubsection @code{_bfd_get_error_program_name} +@deftypefn {Function} const char *_bfd_get_error_program_name (void); +Get the program name used when printing a BFD error. + +@end deftypefn +@subsection BFD assert handler +If BFD finds an internal inconsistency, the bfd assert +handler is called with information on the BFD version, BFD +source file and line. If this happens, most programs linked +against BFD are expected to want to exit with an error, or mark +the current BFD operation as failed, so it is recommended to +override the default handler, which just calls +_bfd_error_handler and continues. + + +@example +typedef void (*bfd_assert_handler_type) (const char *bfd_formatmsg, + const char *bfd_version, + const char *bfd_file, + int bfd_line); + +@end example +@findex bfd_set_assert_handler +@subsubsection @code{bfd_set_assert_handler} +@deftypefn {Function} bfd_assert_handler_type bfd_set_assert_handler (bfd_assert_handler_type); +Set the BFD assert handler function. Returns the previous +function. + +@end deftypefn +@node Initialization, Threading, Error reporting, BFD front end +@findex bfd_init +@subsubsection @code{bfd_init} +@deftypefn {Function} unsigned int bfd_init (void); +This routine must be called before any other BFD function to +initialize magical internal data structures. +Returns a magic number, which may be used to check +that the bfd library is configured as expected by users. +@example +/* Value returned by bfd_init. */ +#define BFD_INIT_MAGIC (sizeof (struct bfd_section)) + +@end example + +@end deftypefn +@node Threading, Miscellaneous, Initialization, BFD front end +@section Threading +BFD has limited support for thread-safety. Most BFD globals +are protected by locks, while the error-related globals are +thread-local. A given BFD cannot safely be used from two +threads at the same time; it is up to the application to do +any needed locking. However, it is ok for different threads +to work on different BFD objects at the same time. + +@subsection Thread functions. + + + +@example +typedef bool (*bfd_lock_unlock_fn_type) (void *); +@end example +@findex _bfd_threading_enabled +@subsubsection @code{_bfd_threading_enabled} +@deftypefn {Function} bool _bfd_threading_enabled (void); +Return true if threading is enabled, false if not. + +@end deftypefn +@findex bfd_thread_init +@subsubsection @code{bfd_thread_init} +@deftypefn {Function} bool bfd_thread_init (bfd_lock_unlock_fn_type lock, bfd_lock_unlock_fn_type unlock, void *data); +Initialize BFD threading. The functions passed in will be +used to lock and unlock global data structures. This may only +be called a single time in a given process. Returns true on +success and false on error. DATA is passed verbatim to the +lock and unlock functions. The lock and unlock functions +should return true on success, or set the BFD error and return +false on failure. Note also that the lock must be a recursive +lock: BFD may attempt to acquire the lock when it is already +held by the current thread. + +@end deftypefn +@findex bfd_thread_cleanup +@subsubsection @code{bfd_thread_cleanup} +@deftypefn {Function} void bfd_thread_cleanup (void); +Clean up any thread-local state. This should be called by a +thread that uses any BFD functions, before the thread exits. +It is fine to call this multiple times, or to call it and then +later call BFD functions on the same thread again. + +@end deftypefn +@findex bfd_lock +@subsubsection @code{bfd_lock} +@deftypefn {Function} bool bfd_lock (void); +Acquire the global BFD lock, if needed. Returns true on +success, false on error. + +@end deftypefn +@findex bfd_unlock +@subsubsection @code{bfd_unlock} +@deftypefn {Function} bool bfd_unlock (void); +Release the global BFD lock, if needed. Returns true on +success, false on error. + +@end deftypefn +@node Miscellaneous, Memory Usage, Threading, BFD front end +@section Miscellaneous + + +@subsection Miscellaneous functions + + +@findex bfd_get_reloc_upper_bound +@subsubsection @code{bfd_get_reloc_upper_bound} +@deftypefn {Function} long bfd_get_reloc_upper_bound (bfd *abfd, asection *sect); +Return the number of bytes required to store the +relocation information associated with section @var{sect} +attached to bfd @var{abfd}. If an error occurs, return -1. + +@end deftypefn +@findex bfd_canonicalize_reloc +@subsubsection @code{bfd_canonicalize_reloc} +@deftypefn {Function} long bfd_canonicalize_reloc (bfd *abfd, asection *sec, arelent **loc, asymbol **syms); +Call the back end associated with the open BFD +@var{abfd} and translate the external form of the relocation +information attached to @var{sec} into the internal canonical +form. Place the table into memory at @var{loc}, which has +been preallocated, usually by a call to +@code{bfd_get_reloc_upper_bound}. Returns the number of relocs, or +-1 on error. + +The @var{syms} table is also needed for horrible internal magic +reasons. + +@end deftypefn +@findex bfd_set_reloc +@subsubsection @code{bfd_set_reloc} +@deftypefn {Function} void bfd_set_reloc (bfd *abfd, asection *sec, arelent **rel, unsigned int count); +Set the relocation pointer and count within +section @var{sec} to the values @var{rel} and @var{count}. +The argument @var{abfd} is ignored. +@example +#define bfd_set_reloc(abfd, asect, location, count) \ + BFD_SEND (abfd, _bfd_set_reloc, (abfd, asect, location, count)) +@end example + +@end deftypefn +@findex bfd_set_file_flags +@subsubsection @code{bfd_set_file_flags} +@deftypefn {Function} bool bfd_set_file_flags (bfd *abfd, flagword flags); +Set the flag word in the BFD @var{abfd} to the value @var{flags}. + +Possible errors are: +@itemize @bullet + +@item +@code{bfd_error_wrong_format} - The target bfd was not of object format. +@item +@code{bfd_error_invalid_operation} - The target bfd was open for reading. +@item +@code{bfd_error_invalid_operation} - +The flag word contained a bit which was not applicable to the +type of file. E.g., an attempt was made to set the @code{D_PAGED} bit +on a BFD format which does not support demand paging. +@end itemize + +@end deftypefn +@findex bfd_get_arch_size +@subsubsection @code{bfd_get_arch_size} +@deftypefn {Function} int bfd_get_arch_size (bfd *abfd); +Returns the normalized architecture address size, in bits, as +determined by the object file's format. By normalized, we mean +either 32 or 64. For ELF, this information is included in the +header. Use bfd_arch_bits_per_address for number of bits in +the architecture address. + +Returns the arch size in bits if known, @code{-1} otherwise. + +@end deftypefn +@findex bfd_get_sign_extend_vma +@subsubsection @code{bfd_get_sign_extend_vma} +@deftypefn {Function} int bfd_get_sign_extend_vma (bfd *abfd); +Indicates if the target architecture "naturally" sign extends +an address. Some architectures implicitly sign extend address +values when they are converted to types larger than the size +of an address. For instance, bfd_get_start_address() will +return an address sign extended to fill a bfd_vma when this is +the case. + +Returns @code{1} if the target architecture is known to sign +extend addresses, @code{0} if the target architecture is known to +not sign extend addresses, and @code{-1} otherwise. + +@end deftypefn +@findex bfd_set_start_address +@subsubsection @code{bfd_set_start_address} +@deftypefn {Function} bool bfd_set_start_address (bfd *abfd, bfd_vma vma); +Make @var{vma} the entry point of output BFD @var{abfd}. + +Returns @code{TRUE} on success, @code{FALSE} otherwise. + +@end deftypefn +@findex bfd_get_gp_size +@subsubsection @code{bfd_get_gp_size} +@deftypefn {Function} unsigned int bfd_get_gp_size (bfd *abfd); +Return the maximum size of objects to be optimized using the GP +register under MIPS ECOFF. This is typically set by the @code{-G} +argument to the compiler, assembler or linker. + +@end deftypefn +@findex bfd_set_gp_size +@subsubsection @code{bfd_set_gp_size} +@deftypefn {Function} void bfd_set_gp_size (bfd *abfd, unsigned int i); +Set the maximum size of objects to be optimized using the GP +register under ECOFF or MIPS ELF. This is typically set by +the @code{-G} argument to the compiler, assembler or linker. + +@end deftypefn +@findex bfd_set_gp_value +@subsubsection @code{bfd_set_gp_value} +@deftypefn {Function} void bfd_set_gp_value (bfd *abfd, bfd_vma v); +Allow external access to the fucntion to set the GP value. +This is specifically added for gdb-compile support. + +@end deftypefn +@findex bfd_scan_vma +@subsubsection @code{bfd_scan_vma} +@deftypefn {Function} bfd_vma bfd_scan_vma (const char *string, const char **end, int base); +Convert, like @code{strtoul} or @code{stdtoull}depending on the size +of a @code{bfd_vma}, a numerical expression @var{string} into a +@code{bfd_vma} integer, and return that integer. + +@end deftypefn +@findex bfd_copy_private_header_data +@subsubsection @code{bfd_copy_private_header_data} +@deftypefn {Function} bool bfd_copy_private_header_data (bfd *ibfd, bfd *obfd); +Copy private BFD header information from the BFD @var{ibfd} to the +the BFD @var{obfd}. This copies information that may require +sections to exist, but does not require symbol tables. Return +@code{true} on success, @code{false} on error. +Possible error returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{obfd}. +@end itemize +@example +#define bfd_copy_private_header_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_header_data, \ + (ibfd, obfd)) +@end example + +@end deftypefn +@findex bfd_copy_private_bfd_data +@subsubsection @code{bfd_copy_private_bfd_data} +@deftypefn {Function} bool bfd_copy_private_bfd_data (bfd *ibfd, bfd *obfd); +Copy private BFD information from the BFD @var{ibfd} to the +the BFD @var{obfd}. Return @code{TRUE} on success, @code{FALSE} on error. +Possible error returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{obfd}. +@end itemize +@example +#define bfd_copy_private_bfd_data(ibfd, obfd) \ + BFD_SEND (obfd, _bfd_copy_private_bfd_data, \ + (ibfd, obfd)) +@end example + +@end deftypefn +@findex bfd_set_private_flags +@subsubsection @code{bfd_set_private_flags} +@deftypefn {Function} bool bfd_set_private_flags (bfd *abfd, flagword flags); +Set private BFD flag information in the BFD @var{abfd}. +Return @code{TRUE} on success, @code{FALSE} on error. Possible error +returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{obfd}. +@end itemize +@example +#define bfd_set_private_flags(abfd, flags) \ + BFD_SEND (abfd, _bfd_set_private_flags, (abfd, flags)) +@end example + +@end deftypefn +@findex Other functions +@subsubsection @code{Other functions} +The following functions exist but have not yet been documented. +@example +#define bfd_sizeof_headers(abfd, info) \ + BFD_SEND (abfd, _bfd_sizeof_headers, (abfd, info)) + +#define bfd_find_nearest_line(abfd, sec, syms, off, file, func, line) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, syms, sec, off, file, func, line, NULL)) + +#define bfd_find_nearest_line_with_alt(abfd, alt_filename, sec, syms, off, \ + file, func, line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line_with_alt, \ + (abfd, alt_filename, syms, sec, off, file, func, line, disc)) + +#define bfd_find_nearest_line_discriminator(abfd, sec, syms, off, file, func, \ + line, disc) \ + BFD_SEND (abfd, _bfd_find_nearest_line, \ + (abfd, syms, sec, off, file, func, line, disc)) + +#define bfd_find_line(abfd, syms, sym, file, line) \ + BFD_SEND (abfd, _bfd_find_line, \ + (abfd, syms, sym, file, line)) + +#define bfd_find_inliner_info(abfd, file, func, line) \ + BFD_SEND (abfd, _bfd_find_inliner_info, \ + (abfd, file, func, line)) + +#define bfd_debug_info_start(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_start, (abfd)) + +#define bfd_debug_info_end(abfd) \ + BFD_SEND (abfd, _bfd_debug_info_end, (abfd)) + +#define bfd_debug_info_accumulate(abfd, section) \ + BFD_SEND (abfd, _bfd_debug_info_accumulate, (abfd, section)) + +#define bfd_stat_arch_elt(abfd, stat) \ + BFD_SEND (abfd->my_archive ? abfd->my_archive : abfd, \ + _bfd_stat_arch_elt, (abfd, stat)) + +#define bfd_update_armap_timestamp(abfd) \ + BFD_SEND (abfd, _bfd_update_armap_timestamp, (abfd)) + +#define bfd_set_arch_mach(abfd, arch, mach)\ + BFD_SEND ( abfd, _bfd_set_arch_mach, (abfd, arch, mach)) + +#define bfd_relax_section(abfd, section, link_info, again) \ + BFD_SEND (abfd, _bfd_relax_section, (abfd, section, link_info, again)) + +#define bfd_gc_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_gc_sections, (abfd, link_info)) + +#define bfd_lookup_section_flags(link_info, flag_info, section) \ + BFD_SEND (abfd, _bfd_lookup_section_flags, (link_info, flag_info, section)) + +#define bfd_merge_sections(abfd, link_info) \ + BFD_SEND (abfd, _bfd_merge_sections, (abfd, link_info)) + +#define bfd_is_group_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_is_group_section, (abfd, sec)) + +#define bfd_group_name(abfd, sec) \ + BFD_SEND (abfd, _bfd_group_name, (abfd, sec)) + +#define bfd_discard_group(abfd, sec) \ + BFD_SEND (abfd, _bfd_discard_group, (abfd, sec)) + +#define bfd_link_hash_table_create(abfd) \ + BFD_SEND (abfd, _bfd_link_hash_table_create, (abfd)) + +#define bfd_link_add_symbols(abfd, info) \ + BFD_SEND (abfd, _bfd_link_add_symbols, (abfd, info)) + +#define bfd_link_just_syms(abfd, sec, info) \ + BFD_SEND (abfd, _bfd_link_just_syms, (sec, info)) + +#define bfd_final_link(abfd, info) \ + BFD_SEND (abfd, _bfd_final_link, (abfd, info)) + +#define bfd_free_cached_info(abfd) \ + BFD_SEND (abfd, _bfd_free_cached_info, (abfd)) + +#define bfd_get_dynamic_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_symtab_upper_bound, (abfd)) + +#define bfd_print_private_bfd_data(abfd, file)\ + BFD_SEND (abfd, _bfd_print_private_bfd_data, (abfd, file)) + +#define bfd_canonicalize_dynamic_symtab(abfd, asymbols) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_symtab, (abfd, asymbols)) + +#define bfd_get_synthetic_symtab(abfd, count, syms, dyncount, dynsyms, ret) \ + BFD_SEND (abfd, _bfd_get_synthetic_symtab, (abfd, count, syms, \ + dyncount, dynsyms, ret)) + +#define bfd_get_dynamic_reloc_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_dynamic_reloc_upper_bound, (abfd)) + +#define bfd_canonicalize_dynamic_reloc(abfd, arels, asyms) \ + BFD_SEND (abfd, _bfd_canonicalize_dynamic_reloc, (abfd, arels, asyms)) + +@end example + +@findex bfd_get_relocated_section_contents +@subsubsection @code{bfd_get_relocated_section_contents} +@deftypefn {Function} bfd_byte *bfd_get_relocated_section_contents (bfd *, struct bfd_link_info *, struct bfd_link_order *, bfd_byte *, bool, asymbol **); +Read and relocate the indirect link_order section, into DATA +(if non-NULL) or to a malloc'd buffer. Return the buffer, or +NULL on errors. + +@end deftypefn +@findex bfd_record_phdr +@subsubsection @code{bfd_record_phdr} +@deftypefn {Function} bool bfd_record_phdr (bfd *, unsigned long, bool, flagword, bool, bfd_vma, bool, bool, unsigned int, struct bfd_section **); +Record information about an ELF program header. + +@end deftypefn +@findex bfd_sprintf_vma +@subsubsection @code{bfd_sprintf_vma} +@deftypefn {Function} void bfd_sprintf_vma (bfd *, char *, bfd_vma); void bfd_fprintf_vma (bfd *, void *, bfd_vma); +bfd_sprintf_vma and bfd_fprintf_vma display an address in the +target's address size. + +@end deftypefn +@findex bfd_alt_mach_code +@subsubsection @code{bfd_alt_mach_code} +@deftypefn {Function} bool bfd_alt_mach_code (bfd *abfd, int alternative); +When more than one machine code number is available for the +same machine type, this function can be used to switch between +the preferred one (alternative == 0) and any others. Currently, +only ELF supports this feature, with up to two alternate +machine codes. + +@end deftypefn +@findex bfd_emul_get_maxpagesize +@subsubsection @code{bfd_emul_get_maxpagesize} +@deftypefn {Function} bfd_vma bfd_emul_get_maxpagesize (const char *); +Returns the maximum page size, in bytes, as determined by +emulation. + +@end deftypefn +@findex bfd_emul_get_commonpagesize +@subsubsection @code{bfd_emul_get_commonpagesize} +@deftypefn {Function} bfd_vma bfd_emul_get_commonpagesize (const char *); +Returns the common page size, in bytes, as determined by +emulation. + +@end deftypefn +@findex bfd_demangle +@subsubsection @code{bfd_demangle} +@deftypefn {Function} char *bfd_demangle (bfd *, const char *, int); +Wrapper around cplus_demangle. Strips leading underscores and +other such chars that would otherwise confuse the demangler. +If passed a g++ v3 ABI mangled name, returns a buffer allocated +with malloc holding the demangled name. Returns NULL otherwise +and on memory alloc failure. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/bfdver.texi 16.3-5ubuntu1/bfd/doc/bfdver.texi --- 16.3-5/bfd/doc/bfdver.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/bfdver.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,4 @@ - +@set VERSION 2.43.50 +@set VERSION_PACKAGE (GNU Binutils) +@set UPDATED April 2025 +@set BUGURL @uref{https://sourceware.org/bugzilla/} diff -pruN 16.3-5/bfd/doc/cache.texi 16.3-5ubuntu1/bfd/doc/cache.texi --- 16.3-5/bfd/doc/cache.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/cache.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,71 @@ +@section File caching +The file caching mechanism is embedded within BFD and allows +the application to open as many BFDs as it wants without +regard to the underlying operating system's file descriptor +limit (often as low as 20 open files). The module in +@code{cache.c} maintains a least recently used list of +@code{bfd_cache_max_open} files, and exports the name +@code{bfd_cache_lookup}, which runs around and makes sure that +the required BFD is open. If not, then it chooses a file to +close, closes it and opens the one wanted, returning its file +handle. +@subsection Caching functions + + +@findex bfd_cache_init +@subsubsection @code{bfd_cache_init} +@deftypefn {Function} bool bfd_cache_init (bfd *abfd); +Add a newly opened BFD to the cache. + +@end deftypefn +@findex bfd_cache_close +@subsubsection @code{bfd_cache_close} +@deftypefn {Function} bool bfd_cache_close (bfd *abfd); +Remove the BFD @var{abfd} from the cache. If the attached file is open, +then close it too. + +@code{FALSE} is returned if closing the file fails, @code{TRUE} is +returned if all is well. + +@end deftypefn +@findex bfd_cache_close_all +@subsubsection @code{bfd_cache_close_all} +@deftypefn {Function} bool bfd_cache_close_all (void); +Remove all BFDs from the cache. If the attached file is open, +then close it too. Note - despite its name this function will +close a BFD even if it is not marked as being cacheable, ie +even if bfd_get_cacheable() returns false. + +@code{FALSE} is returned if closing one of the file fails, @code{TRUE} is +returned if all is well. + +@end deftypefn +@findex bfd_cache_set_uncloseable +@subsubsection @code{bfd_cache_set_uncloseable} +@deftypefn {Function} bool bfd_cache_set_uncloseable (bfd *abfd, bool value, bool *old); +Internal function to mark ABFD as either closeable or not. +This is used by bfd_check_format_matches to avoid races +where bfd_cache_close_all is called in another thread. +VALUE is true to mark the BFD as temporarily uncloseable +by the cache; false to mark it as closeable once again. +OLD, if non-NULL, is set to the previous value of the flag. +Returns false on error, true on success. + +@end deftypefn +@findex bfd_cache_size +@subsubsection @code{bfd_cache_size} +@deftypefn {Function} unsigned bfd_cache_size (void); +Return the number of open files in the cache. + +@end deftypefn +@findex bfd_open_file +@subsubsection @code{bfd_open_file} +@deftypefn {Function} FILE* bfd_open_file (bfd *abfd); +Call the OS to open a file for @var{abfd}. Return the @code{FILE *} +(possibly @code{NULL}) that results from this operation. Set up the +BFD so that future accesses know the file is open. If the @code{FILE *} +returned is @code{NULL}, then it won't have been put in the +cache, so it won't have to be removed from it. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/coffcode.texi 16.3-5ubuntu1/bfd/doc/coffcode.texi --- 16.3-5/bfd/doc/coffcode.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/coffcode.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,526 @@ +@section coff backends +BFD supports a number of different flavours of coff format. +The major differences between formats are the sizes and +alignments of fields in structures on disk, and the occasional +extra field. + +Coff in all its varieties is implemented with a few common +files and a number of implementation specific files. For +example, the i386 coff format is implemented in the file +@file{coff-i386.c}. This file @code{#include}s +@file{coff/i386.h} which defines the external structure of the +coff format for the i386, and @file{coff/internal.h} which +defines the internal structure. @file{coff-i386.c} also +defines the relocations used by the i386 coff format +@xref{Relocations}. + +@subsection Porting to a new version of coff +The recommended method is to select from the existing +implementations the version of coff which is most like the one +you want to use. For example, we'll say that i386 coff is +the one you select, and that your coff flavour is called foo. +Copy @file{i386coff.c} to @file{foocoff.c}, copy +@file{../include/coff/i386.h} to @file{../include/coff/foo.h}, +and add the lines to @file{targets.c} and @file{Makefile.in} +so that your new back end is used. Alter the shapes of the +structures in @file{../include/coff/foo.h} so that they match +what you need. You will probably also have to add +@code{#ifdef}s to the code in @file{coff/internal.h} and +@file{coffcode.h} if your version of coff is too wild. + +You can verify that your new BFD backend works quite simply by +building @file{objdump} from the @file{binutils} directory, +and making sure that its version of what's going on and your +host system's idea (assuming it has the pretty standard coff +dump utility, usually called @code{att-dump} or just +@code{dump}) are the same. Then clean up your code, and send +what you've done to Cygnus. Then your stuff will be in the +next release, and you won't have to keep integrating it. + +@subsection How the coff backend works + + +@subsubsection File layout +The Coff backend is split into generic routines that are +applicable to any Coff target and routines that are specific +to a particular target. The target-specific routines are +further split into ones which are basically the same for all +Coff targets except that they use the external symbol format +or use different values for certain constants. + +The generic routines are in @file{coffgen.c}. These routines +work for any Coff target. They use some hooks into the target +specific code; the hooks are in a @code{bfd_coff_backend_data} +structure, one of which exists for each target. + +The essentially similar target-specific routines are in +@file{coffcode.h}. This header file includes executable C code. +The various Coff targets first include the appropriate Coff +header file, make any special defines that are needed, and +then include @file{coffcode.h}. + +Some of the Coff targets then also have additional routines in +the target source file itself. + +@subsubsection Coff long section names +In the standard Coff object format, section names are limited to +the eight bytes available in the @code{s_name} field of the +@code{SCNHDR} section header structure. The format requires the +field to be NUL-padded, but not necessarily NUL-terminated, so +the longest section names permitted are a full eight characters. + +The Microsoft PE variants of the Coff object file format add +an extension to support the use of long section names. This +extension is defined in section 4 of the Microsoft PE/COFF +specification (rev 8.1). If a section name is too long to fit +into the section header's @code{s_name} field, it is instead +placed into the string table, and the @code{s_name} field is +filled with a slash ("/") followed by the ASCII decimal +representation of the offset of the full name relative to the +string table base. + +Note that this implies that the extension can only be used in object +files, as executables do not contain a string table. The standard +specifies that long section names from objects emitted into executable +images are to be truncated. + +However, as a GNU extension, BFD can generate executable images +that contain a string table and long section names. This +would appear to be technically valid, as the standard only says +that Coff debugging information is deprecated, not forbidden, +and in practice it works, although some tools that parse PE files +expecting the MS standard format may become confused; @file{PEview} is +one known example. + +The functionality is supported in BFD by code implemented under +the control of the macro @code{COFF_LONG_SECTION_NAMES}. If not +defined, the format does not support long section names in any way. +If defined, it is used to initialise a flag, +@code{_bfd_coff_long_section_names}, and a hook function pointer, +@code{_bfd_coff_set_long_section_names}, in the Coff backend data +structure. The flag controls the generation of long section names +in output BFDs at runtime; if it is false, as it will be by default +when generating an executable image, long section names are truncated; +if true, the long section names extension is employed. The hook +points to a function that allows the value of a copy of the flag +in coff object tdata to be altered at runtime, on formats that +support long section names at all; on other formats it points +to a stub that returns an error indication. + +With input BFDs, the flag is set according to whether any long section +names are detected while reading the section headers. For a completely +new BFD, the flag is set to the default for the target format. This +information can be used by a client of the BFD library when deciding +what output format to generate, and means that a BFD that is opened +for read and subsequently converted to a writeable BFD and modified +in-place will retain whatever format it had on input. + +If @code{COFF_LONG_SECTION_NAMES} is simply defined (blank), or is +defined to the value "1", then long section names are enabled by +default; if it is defined to the value zero, they are disabled by +default (but still accepted in input BFDs). The header @file{coffcode.h} +defines a macro, @code{COFF_DEFAULT_LONG_SECTION_NAMES}, which is +used in the backends to initialise the backend data structure fields +appropriately; see the comments for further detail. + +@subsubsection Bit twiddling +Each flavour of coff supported in BFD has its own header file +describing the external layout of the structures. There is also +an internal description of the coff layout, in +@file{coff/internal.h}. A major function of the +coff backend is swapping the bytes and twiddling the bits to +translate the external form of the structures into the normal +internal form. This is all performed in the +@code{bfd_swap}_@i{thing}_@i{direction} routines. Some +elements are different sizes between different versions of +coff; it is the duty of the coff version specific include file +to override the definitions of various packing routines in +@file{coffcode.h}. E.g., the size of line number entry in coff is +sometimes 16 bits, and sometimes 32 bits. @code{#define}ing +@code{PUT_LNSZ_LNNO} and @code{GET_LNSZ_LNNO} will select the +correct one. No doubt, some day someone will find a version of +coff which has a varying field size not catered to at the +moment. To port BFD, that person will have to add more @code{#defines}. +Three of the bit twiddling routines are exported to +@code{gdb}; @code{coff_swap_aux_in}, @code{coff_swap_sym_in} +and @code{coff_swap_lineno_in}. @code{GDB} reads the symbol +table on its own, but uses BFD to fix things up. More of the +bit twiddlers are exported for @code{gas}; +@code{coff_swap_aux_out}, @code{coff_swap_sym_out}, +@code{coff_swap_lineno_out}, @code{coff_swap_reloc_out}, +@code{coff_swap_filehdr_out}, @code{coff_swap_aouthdr_out}, +@code{coff_swap_scnhdr_out}. @code{Gas} currently keeps track +of all the symbol table and reloc drudgery itself, thereby +saving the internal BFD overhead, but uses BFD to swap things +on the way out, making cross ports much safer. Doing so also +allows BFD (and thus the linker) to use the same header files +as @code{gas}, which makes one avenue to disaster disappear. + +@subsubsection Symbol reading +The simple canonical form for symbols used by BFD is not rich +enough to keep all the information available in a coff symbol +table. The back end gets around this problem by keeping the original +symbol table around, "behind the scenes". + +When a symbol table is requested (through a call to +@code{bfd_canonicalize_symtab}), a request gets through to +@code{coff_get_normalized_symtab}. This reads the symbol table from +the coff file and swaps all the structures inside into the +internal form. It also fixes up all the pointers in the table +(represented in the file by offsets from the first symbol in +the table) into physical pointers to elements in the new +internal table. This involves some work since the meanings of +fields change depending upon context: a field that is a +pointer to another structure in the symbol table at one moment +may be the size in bytes of a structure at the next. Another +pass is made over the table. All symbols which mark file names +(@code{C_FILE} symbols) are modified so that the internal +string points to the value in the auxent (the real filename) +rather than the normal text associated with the symbol +(@code{".file"}). + +At this time the symbol names are moved around. Coff stores +all symbols less than nine characters long physically +within the symbol table; longer strings are kept at the end of +the file in the string table. This pass moves all strings +into memory and replaces them with pointers to the strings. + +The symbol table is massaged once again, this time to create +the canonical table used by the BFD application. Each symbol +is inspected in turn, and a decision made (using the +@code{sclass} field) about the various flags to set in the +@code{asymbol}. @xref{Symbols}. The generated canonical table +shares strings with the hidden internal symbol table. + +Any linenumbers are read from the coff file too, and attached +to the symbols which own the functions the linenumbers belong to. + +@subsubsection Symbol writing +Writing a symbol to a coff file which didn't come from a coff +file will lose any debugging information. The @code{asymbol} +structure remembers the BFD from which the symbol was taken, and on +output the back end makes sure that the same destination target as +source target is present. + +When the symbols have come from a coff file then all the +debugging information is preserved. + +Symbol tables are provided for writing to the back end in a +vector of pointers to pointers. This allows applications like +the linker to accumulate and output large symbol tables +without having to do too much byte copying. + +This function runs through the provided symbol table and +patches each symbol marked as a file place holder +(@code{C_FILE}) to point to the next file place holder in the +list. It also marks each @code{offset} field in the list with +the offset from the first symbol of the current symbol. + +Another function of this procedure is to turn the canonical +value form of BFD into the form used by coff. Internally, BFD +expects symbol values to be offsets from a section base; so a +symbol physically at 0x120, but in a section starting at +0x100, would have the value 0x20. Coff expects symbols to +contain their final value, so symbols have their values +changed at this point to reflect their sum with their owning +section. This transformation uses the +@code{output_section} field of the @code{asymbol}'s +@code{asection} @xref{Sections}. + +@itemize @bullet + +@item +@code{coff_mangle_symbols} +@end itemize +This routine runs though the provided symbol table and uses +the offsets generated by the previous pass and the pointers +generated when the symbol table was read in to create the +structured hierarchy required by coff. It changes each pointer +to a symbol into the index into the symbol table of the asymbol. + +@itemize @bullet + +@item +@code{coff_write_symbols} +@end itemize +This routine runs through the symbol table and patches up the +symbols from their internal form into the coff way, calls the +bit twiddlers, and writes out the table to the file. + +@findex coff_symbol_type +@subsubsection @code{coff_symbol_type} +The hidden information for an @code{asymbol} is described in a +@code{combined_entry_type}: + + +@example +typedef struct coff_ptr_struct +@{ + /* Remembers the offset from the first symbol in the file for + this symbol. Generated by coff_renumber_symbols. */ + unsigned int offset; + + /* Selects between the elements of the union below. */ + unsigned int is_sym : 1; + + /* Selects between the elements of the x_sym.x_tagndx union. If set, + p is valid and the field will be renumbered. */ + unsigned int fix_tag : 1; + + /* Selects between the elements of the x_sym.x_fcnary.x_fcn.x_endndx + union. If set, p is valid and the field will be renumbered. */ + unsigned int fix_end : 1; + + /* Selects between the elements of the x_csect.x_scnlen union. If set, + p is valid and the field will be renumbered. */ + unsigned int fix_scnlen : 1; + + /* If set, u.syment.n_value contains a pointer to a symbol. The final + value will be the offset field. Used for XCOFF C_BSTAT symbols. */ + unsigned int fix_value : 1; + + /* If set, u.syment.n_value is an index into the line number entries. + Used for XCOFF C_BINCL/C_EINCL symbols. */ + unsigned int fix_line : 1; + + /* The container for the symbol structure as read and translated + from the file. */ + union + @{ + union internal_auxent auxent; + struct internal_syment syment; + @} u; + + /* An extra pointer which can used by format based on COFF (like XCOFF) + to provide extra information to their backend. */ + void *extrap; +@} combined_entry_type; + +/* Each canonical asymbol really looks like this: */ + +typedef struct coff_symbol_struct +@{ + /* The actual symbol which the rest of BFD works with */ + asymbol symbol; + + /* A pointer to the hidden information for this symbol */ + combined_entry_type *native; + + /* A pointer to the linenumber information for this symbol */ + struct lineno_cache_entry *lineno; + + /* Have the line numbers been relocated yet ? */ + bool done_lineno; +@} coff_symbol_type; + +@end example +@findex bfd_coff_backend_data +@subsubsection @code{bfd_coff_backend_data} + +@example +typedef struct +@{ + void (*_bfd_coff_swap_aux_in) + (bfd *, void *, int, int, int, int, void *); + + void (*_bfd_coff_swap_sym_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_lineno_in) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aux_out) + (bfd *, void *, int, int, int, int, void *); + + unsigned int (*_bfd_coff_swap_sym_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_lineno_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_reloc_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_filehdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_aouthdr_out) + (bfd *, void *, void *); + + unsigned int (*_bfd_coff_swap_scnhdr_out) + (bfd *, void *, void *); + + unsigned int _bfd_filhsz; + unsigned int _bfd_aoutsz; + unsigned int _bfd_scnhsz; + unsigned int _bfd_symesz; + unsigned int _bfd_auxesz; + unsigned int _bfd_relsz; + unsigned int _bfd_linesz; + unsigned int _bfd_filnmlen; + bool _bfd_coff_long_filenames; + + bool _bfd_coff_long_section_names; + bool (*_bfd_coff_set_long_section_names) + (bfd *, int); + + unsigned int _bfd_coff_default_section_alignment_power; + bool _bfd_coff_force_symnames_in_strings; + unsigned int _bfd_coff_debug_string_prefix_length; + unsigned int _bfd_coff_max_nscns; + + void (*_bfd_coff_swap_filehdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_aouthdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_scnhdr_in) + (bfd *, void *, void *); + + void (*_bfd_coff_swap_reloc_in) + (bfd *abfd, void *, void *); + + bool (*_bfd_coff_bad_format_hook) + (bfd *, void *); + + bool (*_bfd_coff_set_arch_mach_hook) + (bfd *, void *); + + void * (*_bfd_coff_mkobject_hook) + (bfd *, void *, void *); + + bool (*_bfd_styp_to_sec_flags_hook) + (bfd *, void *, const char *, asection *, flagword *); + + void (*_bfd_set_alignment_hook) + (bfd *, asection *, void *); + + bool (*_bfd_coff_slurp_symbol_table) + (bfd *); + + bool (*_bfd_coff_symname_in_debug) + (bfd *, struct internal_syment *); + + bool (*_bfd_coff_pointerize_aux_hook) + (bfd *, combined_entry_type *, combined_entry_type *, + unsigned int, combined_entry_type *); + + bool (*_bfd_coff_print_aux) + (bfd *, FILE *, combined_entry_type *, combined_entry_type *, + combined_entry_type *, unsigned int); + + bool (*_bfd_coff_reloc16_extra_cases) + (bfd *, struct bfd_link_info *, struct bfd_link_order *, arelent *, + bfd_byte *, size_t *, size_t *); + + int (*_bfd_coff_reloc16_estimate) + (bfd *, asection *, arelent *, unsigned int, + struct bfd_link_info *); + + enum coff_symbol_classification (*_bfd_coff_classify_symbol) + (bfd *, struct internal_syment *); + + bool (*_bfd_coff_compute_section_file_positions) + (bfd *); + + bool (*_bfd_coff_start_final_link) + (bfd *, struct bfd_link_info *); + + bool (*_bfd_coff_relocate_section) + (bfd *, struct bfd_link_info *, bfd *, asection *, bfd_byte *, + struct internal_reloc *, struct internal_syment *, asection **); + + reloc_howto_type *(*_bfd_coff_rtype_to_howto) + (bfd *, asection *, struct internal_reloc *, + struct coff_link_hash_entry *, struct internal_syment *, bfd_vma *); + + bool (*_bfd_coff_adjust_symndx) + (bfd *, struct bfd_link_info *, bfd *, asection *, + struct internal_reloc *, bool *); + + bool (*_bfd_coff_link_add_one_symbol) + (struct bfd_link_info *, bfd *, const char *, flagword, + asection *, bfd_vma, const char *, bool, bool, + struct bfd_link_hash_entry **); + + bool (*_bfd_coff_link_output_has_begun) + (bfd *, struct coff_final_link_info *); + + bool (*_bfd_coff_final_link_postscript) + (bfd *, struct coff_final_link_info *); + + bool (*_bfd_coff_print_pdata) + (bfd *, void *); + +@} bfd_coff_backend_data; + +@end example +@subsubsection Writing relocations +To write relocations, the back end steps though the +canonical relocation table and create an +@code{internal_reloc}. The symbol index to use is removed from +the @code{offset} field in the symbol table supplied. The +address comes directly from the sum of the section base +address and the relocation offset; the type is dug directly +from the howto field. Then the @code{internal_reloc} is +swapped into the shape of an @code{external_reloc} and written +out to disk. + +@subsubsection Reading linenumbers +Creating the linenumber table is done by reading in the entire +coff linenumber table, and creating another table for internal use. + +A coff linenumber table is structured so that each function +is marked as having a line number of 0. Each line within the +function is an offset from the first line in the function. The +base of the line number information for the table is stored in +the symbol associated with the function. + +Note: The PE format uses line number 0 for a flag indicating a +new source file. + +The information is copied from the external to the internal +table, and each symbol which marks a function is marked by +pointing its... + +How does this work ? + +@subsubsection Reading relocations +Coff relocations are easily transformed into the internal BFD form +(@code{arelent}). + +Reading a coff relocation table is done in the following stages: + +@itemize @bullet + +@item +Read the entire coff relocation table into memory. + +@item +Process each relocation in turn; first swap it from the +external to the internal form. + +@item +Turn the symbol referenced in the relocation's symbol index +into a pointer into the canonical symbol table. +This table is the same as the one returned by a call to +@code{bfd_canonicalize_symtab}. The back end will call that +routine and save the result if a canonicalization hasn't been done. + +@item +The reloc index is turned into a pointer to a howto +structure, in a back end specific way. For instance, the 386 +uses the @code{r_type} to directly produce an index +into a howto table vector. + +@item +Note that @code{arelent.addend} for COFF is often not what +most people understand as a relocation addend, but rather an +adjustment to the relocation addend stored in section contents +of relocatable object files. The value found in section +contents may also be confusing, depending on both symbol value +and addend somewhat similar to the field value for a +final-linked object. See @code{CALC_ADDEND}. +@end itemize diff -pruN 16.3-5/bfd/doc/corefile.texi 16.3-5ubuntu1/bfd/doc/corefile.texi --- 16.3-5/bfd/doc/corefile.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/corefile.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,52 @@ +@section Core files + +@subsection Core file functions + + +These are functions pertaining to core files. + +@findex bfd_core_file_failing_command +@subsubsection @code{bfd_core_file_failing_command} +@deftypefn {Function} const char *bfd_core_file_failing_command (bfd *abfd); +Return a read-only string explaining which program was running +when it failed and produced the core file @var{abfd}. + +@end deftypefn +@findex bfd_core_file_failing_signal +@subsubsection @code{bfd_core_file_failing_signal} +@deftypefn {Function} int bfd_core_file_failing_signal (bfd *abfd); +Returns the signal number which caused the core dump which +generated the file the BFD @var{abfd} is attached to. + +@end deftypefn +@findex bfd_core_file_pid +@subsubsection @code{bfd_core_file_pid} +@deftypefn {Function} int bfd_core_file_pid (bfd *abfd); +Returns the PID of the process the core dump the BFD +@var{abfd} is attached to was generated from. + +@end deftypefn +@findex core_file_matches_executable_p +@subsubsection @code{core_file_matches_executable_p} +@deftypefn {Function} bool core_file_matches_executable_p (bfd *core_bfd, bfd *exec_bfd); +Return @code{TRUE} if the core file attached to @var{core_bfd} +was generated by a run of the executable file attached to +@var{exec_bfd}, @code{FALSE} otherwise. + +@end deftypefn +@findex generic_core_file_matches_executable_p +@subsubsection @code{generic_core_file_matches_executable_p} +@deftypefn {Function} bool generic_core_file_matches_executable_p (bfd *core_bfd, bfd *exec_bfd); +Return TRUE if the core file attached to @var{core_bfd} +was generated by a run of the executable file attached +to @var{exec_bfd}. The match is based on executable +basenames only. + +Note: When not able to determine the core file failing +command or the executable name, we still return TRUE even +though we're not sure that core file and executable match. +This is to avoid generating a false warning in situations +where we really don't know whether they match or not. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/elf.texi 16.3-5ubuntu1/bfd/doc/elf.texi --- 16.3-5/bfd/doc/elf.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/elf.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,9 @@ +@section ELF backends +BFD support for ELF formats is being worked on. +Currently, the best supported back ends are for sparc and i386 +(running svr4 or Solaris 2). + +Documentation of the internals of the support code still needs +to be written. The code is changing quickly enough that we +haven't bothered yet. diff -pruN 16.3-5/bfd/doc/elfcode.texi 16.3-5ubuntu1/bfd/doc/elfcode.texi --- 16.3-5/bfd/doc/elfcode.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/elfcode.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +0,0 @@ - diff -pruN 16.3-5/bfd/doc/fdl.texi 16.3-5ubuntu1/bfd/doc/fdl.texi --- 16.3-5/bfd/doc/fdl.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/fdl.texi 2024-12-29 02:50:06.000000000 +0000 @@ -1 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff -pruN 16.3-5/bfd/doc/format.texi 16.3-5ubuntu1/bfd/doc/format.texi --- 16.3-5/bfd/doc/format.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/format.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,105 @@ +@section File formats +A format is a BFD concept of high level file contents type. The +formats supported by BFD are: +@itemize @bullet + +@item +@code{bfd_object} +@end itemize +The BFD may contain data, symbols, relocations and debug info. + +@itemize @bullet + +@item +@code{bfd_archive} +@end itemize +The BFD contains other BFDs and an optional index. + +@itemize @bullet + +@item +@code{bfd_core} +@end itemize +The BFD contains the result of an executable core dump. + +@subsection File format functions + + +@findex bfd_check_format +@subsubsection @code{bfd_check_format} +@deftypefn {Function} bool bfd_check_format (bfd *abfd, bfd_format format); +Verify if the file attached to the BFD @var{abfd} is compatible +with the format @var{format} (i.e., one of @code{bfd_object}, +@code{bfd_archive} or @code{bfd_core}). + +If the BFD has been set to a specific target before the +call, only the named target and format combination is +checked. If the target has not been set, or has been set to +@code{default}, then all the known target backends is +interrogated to determine a match. If the default target +matches, it is used. If not, exactly one target must recognize +the file, or an error results. + +The function returns @code{TRUE} on success, otherwise @code{FALSE} +with one of the following error codes: + +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - +if @code{format} is not one of @code{bfd_object}, @code{bfd_archive} or +@code{bfd_core}. + +@item +@code{bfd_error_system_call} - +if an error occured during a read - even some file mismatches +can cause bfd_error_system_calls. + +@item +@code{file_not_recognised} - +none of the backends recognised the file format. + +@item +@code{bfd_error_file_ambiguously_recognized} - +more than one backend recognised the file format. +@end itemize +When calling bfd_check_format (or bfd_check_format_matches), +any underlying file descriptor will be kept open for the +duration of the call. This is done to avoid races when +another thread calls bfd_cache_close_all. In this scenario, +the thread calling bfd_check_format must call bfd_cache_close +itself. + +@end deftypefn +@findex bfd_check_format_matches +@subsubsection @code{bfd_check_format_matches} +@deftypefn {Function} bool bfd_check_format_matches (bfd *abfd, bfd_format format, char ***matching); +Like @code{bfd_check_format}, except when it returns FALSE with +@code{bfd_errno} set to @code{bfd_error_file_ambiguously_recognized}. In that +case, if @var{matching} is not NULL, it will be filled in with +a NULL-terminated list of the names of the formats that matched, +allocated with @code{malloc}. +Then the user may choose a format and try again. + +When done with the list that @var{matching} points to, the caller +should free it. + +@end deftypefn +@findex bfd_set_format +@subsubsection @code{bfd_set_format} +@deftypefn {Function} bool bfd_set_format (bfd *abfd, bfd_format format); +This function sets the file format of the BFD @var{abfd} to the +format @var{format}. If the target set in the BFD does not +support the format requested, the format is invalid, or the BFD +is not open for writing, then an error occurs. + +@end deftypefn +@findex bfd_format_string +@subsubsection @code{bfd_format_string} +@deftypefn {Function} const char *bfd_format_string (bfd_format format); +Return a pointer to a const string +@code{invalid}, @code{object}, @code{archive}, @code{core}, or @code{unknown}, +depending upon the value of @var{format}. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/hash.texi 16.3-5ubuntu1/bfd/doc/hash.texi --- 16.3-5/bfd/doc/hash.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/hash.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,354 @@ +@section Hash Tables +@cindex Hash tables +BFD provides a simple set of hash table functions. Routines +are provided to initialize a hash table, to free a hash table, +to look up a string in a hash table and optionally create an +entry for it, and to traverse a hash table. There is +currently no routine to delete an string from a hash table. +The basic hash table does not permit any data to be stored +with a string. However, a hash table is designed to present a +base class from which other types of hash tables may be +derived. These derived types may store additional information +with the string. Hash tables were implemented in this way, +rather than simply providing a data pointer in a hash table +entry, because they were designed for use by the linker back +ends. The linker may create thousands of hash table entries, +and the overhead of allocating private data and storing and +following pointers becomes noticeable. + +The basic hash table code is in @code{hash.c}. + +@menu +* Creating and Freeing a Hash Table:: +* Looking Up or Entering a String:: +* Traversing a Hash Table:: +* Deriving a New Hash Table Type:: +@end menu + +@node Creating and Freeing a Hash Table, Looking Up or Entering a String, Hash Tables, Hash Tables +@subsection Creating and freeing a hash table +@findex bfd_hash_table_init +@findex bfd_hash_table_init_n +To create a hash table, create an instance of a @code{struct +bfd_hash_table} (defined in @code{bfd.h}) and call +@code{bfd_hash_table_init} (if you know approximately how many +entries you will need, the function @code{bfd_hash_table_init_n}, +which takes a @var{size} argument, may be used). +@code{bfd_hash_table_init} returns @code{FALSE} if some sort of +error occurs. + +@findex bfd_hash_newfunc +The function @code{bfd_hash_table_init} take as an argument a +function to use to create new entries. For a basic hash +table, use the function @code{bfd_hash_newfunc}. @xref{Deriving +a New Hash Table Type}, for why you would want to use a +different value for this argument. + +@findex bfd_hash_allocate +@code{bfd_hash_table_init} will create an objalloc which will be +used to allocate new entries. You may allocate memory on this +objalloc using @code{bfd_hash_allocate}. + +@findex bfd_hash_table_free +Use @code{bfd_hash_table_free} to free up all the memory that has +been allocated for a hash table. This will not free up the +@code{struct bfd_hash_table} itself, which you must provide. + +@findex bfd_hash_set_default_size +Use @code{bfd_hash_set_default_size} to set the default size of +hash table to use. + +@node Looking Up or Entering a String, Traversing a Hash Table, Creating and Freeing a Hash Table, Hash Tables +@subsection Looking up or entering a string +@findex bfd_hash_lookup +The function @code{bfd_hash_lookup} is used both to look up a +string in the hash table and to create a new entry. + +If the @var{create} argument is @code{FALSE}, @code{bfd_hash_lookup} +will look up a string. If the string is found, it will +returns a pointer to a @code{struct bfd_hash_entry}. If the +string is not found in the table @code{bfd_hash_lookup} will +return @code{NULL}. You should not modify any of the fields in +the returns @code{struct bfd_hash_entry}. + +If the @var{create} argument is @code{TRUE}, the string will be +entered into the hash table if it is not already there. +Either way a pointer to a @code{struct bfd_hash_entry} will be +returned, either to the existing structure or to a newly +created one. In this case, a @code{NULL} return means that an +error occurred. + +If the @var{create} argument is @code{TRUE}, and a new entry is +created, the @var{copy} argument is used to decide whether to +copy the string onto the hash table objalloc or not. If +@var{copy} is passed as @code{FALSE}, you must be careful not to +deallocate or modify the string as long as the hash table +exists. + +@node Traversing a Hash Table, Deriving a New Hash Table Type, Looking Up or Entering a String, Hash Tables +@subsection Traversing a hash table +@findex bfd_hash_traverse +The function @code{bfd_hash_traverse} may be used to traverse a +hash table, calling a function on each element. The traversal +is done in a random order. + +@code{bfd_hash_traverse} takes as arguments a function and a +generic @code{void *} pointer. The function is called with a +hash table entry (a @code{struct bfd_hash_entry *}) and the +generic pointer passed to @code{bfd_hash_traverse}. The function +must return a @code{boolean} value, which indicates whether to +continue traversing the hash table. If the function returns +@code{FALSE}, @code{bfd_hash_traverse} will stop the traversal and +return immediately. + +@node Deriving a New Hash Table Type, , Traversing a Hash Table, Hash Tables +@subsection Deriving a new hash table type +Many uses of hash tables want to store additional information +which each entry in the hash table. Some also find it +convenient to store additional information with the hash table +itself. This may be done using a derived hash table. + +Since C is not an object oriented language, creating a derived +hash table requires sticking together some boilerplate +routines with a few differences specific to the type of hash +table you want to create. + +An example of a derived hash table is the linker hash table. +The structures for this are defined in @code{bfdlink.h}. The +functions are in @code{linker.c}. + +You may also derive a hash table from an already derived hash +table. For example, the a.out linker backend code uses a hash +table derived from the linker hash table. + +@menu +* Define the Derived Structures:: +* Write the Derived Creation Routine:: +* Write Other Derived Routines:: +@end menu + +@node Define the Derived Structures, Write the Derived Creation Routine, Deriving a New Hash Table Type, Deriving a New Hash Table Type +@subsubsection Define the derived structures +You must define a structure for an entry in the hash table, +and a structure for the hash table itself. + +The first field in the structure for an entry in the hash +table must be of the type used for an entry in the hash table +you are deriving from. If you are deriving from a basic hash +table this is @code{struct bfd_hash_entry}, which is defined in +@code{bfd.h}. The first field in the structure for the hash +table itself must be of the type of the hash table you are +deriving from itself. If you are deriving from a basic hash +table, this is @code{struct bfd_hash_table}. + +For example, the linker hash table defines @code{struct +bfd_link_hash_entry} (in @code{bfdlink.h}). The first field, +@code{root}, is of type @code{struct bfd_hash_entry}. Similarly, +the first field in @code{struct bfd_link_hash_table}, @code{table}, +is of type @code{struct bfd_hash_table}. + +@node Write the Derived Creation Routine, Write Other Derived Routines, Define the Derived Structures, Deriving a New Hash Table Type +@subsubsection Write the derived creation routine +You must write a routine which will create and initialize an +entry in the hash table. This routine is passed as the +function argument to @code{bfd_hash_table_init}. + +In order to permit other hash tables to be derived from the +hash table you are creating, this routine must be written in a +standard way. + +The first argument to the creation routine is a pointer to a +hash table entry. This may be @code{NULL}, in which case the +routine should allocate the right amount of space. Otherwise +the space has already been allocated by a hash table type +derived from this one. + +After allocating space, the creation routine must call the +creation routine of the hash table type it is derived from, +passing in a pointer to the space it just allocated. This +will initialize any fields used by the base hash table. + +Finally the creation routine must initialize any local fields +for the new hash table type. + +Here is a boilerplate example of a creation routine. +@var{function_name} is the name of the routine. +@var{entry_type} is the type of an entry in the hash table you +are creating. @var{base_newfunc} is the name of the creation +routine of the hash table type your hash table is derived +from. + + +@example +struct bfd_hash_entry * +@var{function_name} (struct bfd_hash_entry *entry, + struct bfd_hash_table *table, + const char *string) +@{ + struct @var{entry_type} *ret = (@var{entry_type} *) entry; + + /* Allocate the structure if it has not already been allocated by a + derived class. */ + if (ret == NULL) + @{ + ret = bfd_hash_allocate (table, sizeof (* ret)); + if (ret == NULL) + return NULL; + @} + + /* Call the allocation method of the base class. */ + ret = ((@var{entry_type} *) + @var{base_newfunc} ((struct bfd_hash_entry *) ret, table, string)); + + /* Initialize the local fields here. */ + + return (struct bfd_hash_entry *) ret; +@} +@end example +The creation routine for the linker hash table, which is in +@code{linker.c}, looks just like this example. +@var{function_name} is @code{_bfd_link_hash_newfunc}. +@var{entry_type} is @code{struct bfd_link_hash_entry}. +@var{base_newfunc} is @code{bfd_hash_newfunc}, the creation +routine for a basic hash table. + +@code{_bfd_link_hash_newfunc} also initializes the local fields +in a linker hash table entry: @code{type}, @code{written} and +@code{next}. + +@node Write Other Derived Routines, , Write the Derived Creation Routine, Deriving a New Hash Table Type +@subsubsection Write other derived routines +You will want to write other routines for your new hash table, +as well. + +You will want an initialization routine which calls the +initialization routine of the hash table you are deriving from +and initializes any other local fields. For the linker hash +table, this is @code{_bfd_link_hash_table_init} in @code{linker.c}. + +You will want a lookup routine which calls the lookup routine +of the hash table you are deriving from and casts the result. +The linker hash table uses @code{bfd_link_hash_lookup} in +@code{linker.c} (this actually takes an additional argument which +it uses to decide how to return the looked up value). + +You may want a traversal routine. This should just call the +traversal routine of the hash table you are deriving from with +appropriate casts. The linker hash table uses +@code{bfd_link_hash_traverse} in @code{linker.c}. + +These routines may simply be defined as macros. For example, +the a.out backend linker hash table, which is derived from the +linker hash table, uses macros for the lookup and traversal +routines. These are @code{aout_link_hash_lookup} and +@code{aout_link_hash_traverse} in aoutx.h. + +@findex bfd_hash_table_init_n +@subsubsection @code{bfd_hash_table_init_n} +@deftypefn {Function} bool bfd_hash_table_init_n (struct bfd_hash_table *, struct bfd_hash_entry *(* {*newfunc*}) (struct bfd_hash_entry *, struct bfd_hash_table *, const char *), unsigned int {*entsize*}, unsigned int {*size*}); +Create a new hash table, given a number of entries. + +@end deftypefn +@findex bfd_hash_table_init +@subsubsection @code{bfd_hash_table_init} +@deftypefn {Function} bool bfd_hash_table_init (struct bfd_hash_table *, struct bfd_hash_entry *(* {*newfunc*}) (struct bfd_hash_entry *, struct bfd_hash_table *, const char *), unsigned int {*entsize*}); +Create a new hash table with the default number of entries. + +@end deftypefn +@findex bfd_hash_table_free +@subsubsection @code{bfd_hash_table_free} +@deftypefn {Function} void bfd_hash_table_free (struct bfd_hash_table *); +Free a hash table. + +@end deftypefn +@findex bfd_hash_lookup +@subsubsection @code{bfd_hash_lookup} +@deftypefn {Function} struct bfd_hash_entry *bfd_hash_lookup (struct bfd_hash_table *, const char *, bool {*create*}, bool {*copy*}); +Look up a string in a hash table. + +@end deftypefn +@findex bfd_hash_insert +@subsubsection @code{bfd_hash_insert} +@deftypefn {Function} struct bfd_hash_entry *bfd_hash_insert (struct bfd_hash_table *, const char *, unsigned long {*hash*}); +Insert an entry in a hash table. + +@end deftypefn +@findex bfd_hash_rename +@subsubsection @code{bfd_hash_rename} +@deftypefn {Function} void bfd_hash_rename (struct bfd_hash_table *, const char *, struct bfd_hash_entry *); +Rename an entry in a hash table. + +@end deftypefn +@findex bfd_hash_replace +@subsubsection @code{bfd_hash_replace} +@deftypefn {Function} void bfd_hash_replace (struct bfd_hash_table *, struct bfd_hash_entry * {*old*}, struct bfd_hash_entry * {*new*}); +Replace an entry in a hash table. + +@end deftypefn +@findex bfd_hash_allocate +@subsubsection @code{bfd_hash_allocate} +@deftypefn {Function} void *bfd_hash_allocate (struct bfd_hash_table *, unsigned int {*size*}); +Allocate space in a hash table. + +@end deftypefn +@findex bfd_hash_newfunc +@subsubsection @code{bfd_hash_newfunc} +@deftypefn {Function} struct bfd_hash_entry *bfd_hash_newfunc (struct bfd_hash_entry *, struct bfd_hash_table *, const char *); +Base method for creating a new hash table entry. + +@end deftypefn +@findex bfd_hash_traverse +@subsubsection @code{bfd_hash_traverse} +@deftypefn {Function} void bfd_hash_traverse (struct bfd_hash_table *, bool (*) (struct bfd_hash_entry *, void *), void *); +Traverse a hash table. + +@end deftypefn +@findex bfd_hash_set_default_size +@subsubsection @code{bfd_hash_set_default_size} +@deftypefn {Function} unsigned int bfd_hash_set_default_size (unsigned int); +Set hash table default size. + +@end deftypefn +@findex _bfd_stringtab_init +@subsubsection @code{_bfd_stringtab_init} +@deftypefn {Function} struct bfd_strtab_hash *_bfd_stringtab_init (void); +Create a new strtab. + +@end deftypefn +@findex _bfd_xcoff_stringtab_init +@subsubsection @code{_bfd_xcoff_stringtab_init} +@deftypefn {Function} struct bfd_strtab_hash *_bfd_xcoff_stringtab_init (bool {*isxcoff64*}); +Create a new strtab in which the strings are output in the format +used in the XCOFF .debug section: a two byte length precedes each +string. + +@end deftypefn +@findex _bfd_stringtab_free +@subsubsection @code{_bfd_stringtab_free} +@deftypefn {Function} void _bfd_stringtab_free (struct bfd_strtab_hash *); +Free a strtab. + +@end deftypefn +@findex _bfd_stringtab_add +@subsubsection @code{_bfd_stringtab_add} +@deftypefn {Function} bfd_size_type _bfd_stringtab_add (struct bfd_strtab_hash *, const char *, bool {*hash*}, bool {*copy*}); +Get the index of a string in a strtab, adding it if it is not +already present. If HASH is FALSE, we don't really use the hash +table, and we don't eliminate duplicate strings. If COPY is true +then store a copy of STR if creating a new entry. + +@end deftypefn +@findex _bfd_stringtab_size +@subsubsection @code{_bfd_stringtab_size} +@deftypefn {Function} bfd_size_type _bfd_stringtab_size (struct bfd_strtab_hash *); +Get the number of bytes in a strtab. + +@end deftypefn +@findex _bfd_stringtab_emit +@subsubsection @code{_bfd_stringtab_emit} +@deftypefn {Function} bool _bfd_stringtab_emit (bfd *, struct bfd_strtab_hash *); +Write out a strtab. ABFD must already be at the right location in +the file. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/libbfd.texi 16.3-5ubuntu1/bfd/doc/libbfd.texi --- 16.3-5/bfd/doc/libbfd.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/libbfd.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,274 @@ +@section Implementation details + +@subsection Internal functions + + +These routines are used within BFD. +They are not intended for export, but are documented here for +completeness. + +@findex bfd_malloc +@subsubsection @code{bfd_malloc} +@deftypefn {Function} void *bfd_malloc (bfd_size_type {*size*}); +Returns a pointer to an allocated block of memory that is at least +SIZE bytes long. If SIZE is 0 then it will be treated as if it were +1. If SIZE is too big then NULL will be returned. +Returns NULL upon error and sets bfd_error. + +@end deftypefn +@findex bfd_realloc +@subsubsection @code{bfd_realloc} +@deftypefn {Function} void *bfd_realloc (void *{*mem*}, bfd_size_type {*size*}); +Returns a pointer to an allocated block of memory that is at least +SIZE bytes long. If SIZE is 0 then it will be treated as if it were +1. If SIZE is too big then NULL will be returned. +If MEM is not NULL then it must point to an allocated block of memory. +If this block is large enough then MEM may be used as the return +value for this function, but this is not guaranteed. + +If MEM is not returned then the first N bytes in the returned block +will be identical to the first N bytes in region pointed to by MEM, +where N is the lessor of SIZE and the length of the region of memory +currently addressed by MEM. + +Returns NULL upon error and sets bfd_error. + +@end deftypefn +@findex bfd_realloc_or_free +@subsubsection @code{bfd_realloc_or_free} +@deftypefn {Function} void *bfd_realloc_or_free (void *{*mem*}, bfd_size_type {*size*}); +Returns a pointer to an allocated block of memory that is at least +SIZE bytes long. If SIZE is 0 then no memory will be allocated, +MEM will be freed, and NULL will be returned. This will not cause +bfd_error to be set. + +If SIZE is too big then NULL will be returned and bfd_error will be +set. +If MEM is not NULL then it must point to an allocated block of memory. +If this block is large enough then MEM may be used as the return +value for this function, but this is not guaranteed. + +If MEM is not returned then the first N bytes in the returned block +will be identical to the first N bytes in region pointed to by MEM, +where N is the lessor of SIZE and the length of the region of memory +currently addressed by MEM. + +@end deftypefn +@findex bfd_zmalloc +@subsubsection @code{bfd_zmalloc} +@deftypefn {Function} void *bfd_zmalloc (bfd_size_type {*size*}); +Returns a pointer to an allocated block of memory that is at least +SIZE bytes long. If SIZE is 0 then it will be treated as if it were +1. If SIZE is too big then NULL will be returned. +Returns NULL upon error and sets bfd_error. + +If NULL is not returned then the allocated block of memory will +have been cleared. + +@end deftypefn +@findex bfd_alloc +@subsubsection @code{bfd_alloc} +@deftypefn {Function} void *bfd_alloc (bfd *abfd, bfd_size_type wanted); +Allocate a block of @var{wanted} bytes of memory attached to +@code{abfd} and return a pointer to it. + +@end deftypefn +@findex bfd_zalloc +@subsubsection @code{bfd_zalloc} +@deftypefn {Function} void *bfd_zalloc (bfd *abfd, bfd_size_type wanted); +Allocate a block of @var{wanted} bytes of zeroed memory +attached to @code{abfd} and return a pointer to it. + +@end deftypefn +@findex bfd_release +@subsubsection @code{bfd_release} +@deftypefn {Function} void bfd_release (bfd *, void *); +Free a block allocated for a BFD. +Note: Also frees all more recently allocated blocks! + +@end deftypefn +@findex bfd_write_bigendian_4byte_int +@subsubsection @code{bfd_write_bigendian_4byte_int} +@deftypefn {Function} bool bfd_write_bigendian_4byte_int (bfd *, unsigned int); +Write a 4 byte integer @var{i} to the output BFD @var{abfd}, in big +endian order regardless of what else is going on. This is useful in +archives. + +@end deftypefn +@findex bfd_put_size +@subsubsection @code{bfd_put_size} +@findex bfd_get_size +@subsubsection @code{bfd_get_size} +These macros as used for reading and writing raw data in +sections; each access (except for bytes) is vectored through +the target format of the BFD and mangled accordingly. The +mangling performs any necessary endian translations and +removes alignment restrictions. Note that types accepted and +returned by these macros are identical so they can be swapped +around in macros---for example, @file{libaout.h} defines @code{GET_WORD} +to either @code{bfd_get_32} or @code{bfd_get_64}. + +In the put routines, @var{val} must be a @code{bfd_vma}. If we are on a +system without prototypes, the caller is responsible for making +sure that is true, with a cast if necessary. We don't cast +them in the macro definitions because that would prevent @code{lint} +or @code{gcc -Wall} from detecting sins such as passing a pointer. +To detect calling these with less than a @code{bfd_vma}, use +@code{gcc -Wconversion} on a host with 64 bit @code{bfd_vma}'s. +@example + +/* Byte swapping macros for user section data. */ + +#define bfd_put_8(abfd, val, ptr) \ + ((void) (*((bfd_byte *) (ptr)) = (val) & 0xff)) +#define bfd_put_signed_8 \ + bfd_put_8 +#define bfd_get_8(abfd, ptr) \ + ((bfd_vma) *(const bfd_byte *) (ptr) & 0xff) +#define bfd_get_signed_8(abfd, ptr) \ + ((((bfd_signed_vma) *(const bfd_byte *) (ptr) & 0xff) ^ 0x80) - 0x80) + +#define bfd_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx16, ((val),(ptr))) +#define bfd_put_signed_16 \ + bfd_put_16 +#define bfd_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx16, (ptr)) +#define bfd_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_16, (ptr)) + +#define bfd_put_24(abfd, val, ptr) \ + do \ + if (bfd_big_endian (abfd)) \ + bfd_putb24 ((val), (ptr)); \ + else \ + bfd_putl24 ((val), (ptr)); \ + while (0) + +bfd_vma bfd_getb24 (const void *p); +bfd_vma bfd_getl24 (const void *p); + +#define bfd_get_24(abfd, ptr) \ + (bfd_big_endian (abfd) ? bfd_getb24 (ptr) : bfd_getl24 (ptr)) + +#define bfd_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx32, ((val),(ptr))) +#define bfd_put_signed_32 \ + bfd_put_32 +#define bfd_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx32, (ptr)) +#define bfd_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_32, (ptr)) + +#define bfd_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_putx64, ((val), (ptr))) +#define bfd_put_signed_64 \ + bfd_put_64 +#define bfd_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx64, (ptr)) +#define bfd_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_getx_signed_64, (ptr)) + +#define bfd_get(bits, abfd, ptr) \ + ((bits) == 8 ? bfd_get_8 (abfd, ptr) \ + : (bits) == 16 ? bfd_get_16 (abfd, ptr) \ + : (bits) == 32 ? bfd_get_32 (abfd, ptr) \ + : (bits) == 64 ? bfd_get_64 (abfd, ptr) \ + : (abort (), (bfd_vma) - 1)) + +#define bfd_put(bits, abfd, val, ptr) \ + ((bits) == 8 ? bfd_put_8 (abfd, val, ptr) \ + : (bits) == 16 ? bfd_put_16 (abfd, val, ptr) \ + : (bits) == 32 ? bfd_put_32 (abfd, val, ptr) \ + : (bits) == 64 ? bfd_put_64 (abfd, val, ptr) \ + : (abort (), (void) 0)) + +@end example + +@findex bfd_h_put_size +@subsubsection @code{bfd_h_put_size} +These macros have the same function as their @code{bfd_get_x} +brethren, except that they are used for removing information +for the header records of object files. Believe it or not, +some object files keep their header records in big endian +order and their data in little endian order. +@example + +/* Byte swapping macros for file header data. */ + +#define bfd_h_put_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_put_signed_8(abfd, val, ptr) \ + bfd_put_8 (abfd, val, ptr) +#define bfd_h_get_8(abfd, ptr) \ + bfd_get_8 (abfd, ptr) +#define bfd_h_get_signed_8(abfd, ptr) \ + bfd_get_signed_8 (abfd, ptr) + +#define bfd_h_put_16(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx16, (val, ptr)) +#define bfd_h_put_signed_16 \ + bfd_h_put_16 +#define bfd_h_get_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx16, (ptr)) +#define bfd_h_get_signed_16(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_16, (ptr)) + +#define bfd_h_put_32(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx32, (val, ptr)) +#define bfd_h_put_signed_32 \ + bfd_h_put_32 +#define bfd_h_get_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx32, (ptr)) +#define bfd_h_get_signed_32(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_32, (ptr)) + +#define bfd_h_put_64(abfd, val, ptr) \ + BFD_SEND (abfd, bfd_h_putx64, (val, ptr)) +#define bfd_h_put_signed_64 \ + bfd_h_put_64 +#define bfd_h_get_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx64, (ptr)) +#define bfd_h_get_signed_64(abfd, ptr) \ + BFD_SEND (abfd, bfd_h_getx_signed_64, (ptr)) + +/* Aliases for the above, which should eventually go away. */ + +#define H_PUT_64 bfd_h_put_64 +#define H_PUT_32 bfd_h_put_32 +#define H_PUT_16 bfd_h_put_16 +#define H_PUT_8 bfd_h_put_8 +#define H_PUT_S64 bfd_h_put_signed_64 +#define H_PUT_S32 bfd_h_put_signed_32 +#define H_PUT_S16 bfd_h_put_signed_16 +#define H_PUT_S8 bfd_h_put_signed_8 +#define H_GET_64 bfd_h_get_64 +#define H_GET_32 bfd_h_get_32 +#define H_GET_16 bfd_h_get_16 +#define H_GET_8 bfd_h_get_8 +#define H_GET_S64 bfd_h_get_signed_64 +#define H_GET_S32 bfd_h_get_signed_32 +#define H_GET_S16 bfd_h_get_signed_16 +#define H_GET_S8 bfd_h_get_signed_8 + + +@end example + +@findex Byte swapping routines. +@subsubsection @code{Byte swapping routines.} +@deftypefn {Function} uint64_t bfd_getb64 (const void *); uint64_t bfd_getl64 (const void *); int64_t bfd_getb_signed_64 (const void *); int64_t bfd_getl_signed_64 (const void *); bfd_vma bfd_getb32 (const void *); bfd_vma bfd_getl32 (const void *); bfd_signed_vma bfd_getb_signed_32 (const void *); bfd_signed_vma bfd_getl_signed_32 (const void *); bfd_vma bfd_getb16 (const void *); bfd_vma bfd_getl16 (const void *); bfd_signed_vma bfd_getb_signed_16 (const void *); bfd_signed_vma bfd_getl_signed_16 (const void *); void bfd_putb64 (uint64_t, void *); void bfd_putl64 (uint64_t, void *); void bfd_putb32 (bfd_vma, void *); void bfd_putl32 (bfd_vma, void *); void bfd_putb24 (bfd_vma, void *); void bfd_putl24 (bfd_vma, void *); void bfd_putb16 (bfd_vma, void *); void bfd_putl16 (bfd_vma, void *); uint64_t bfd_get_bits (const void *, int, bool); void bfd_put_bits (uint64_t, void *, int, bool); +Read and write integers in a particular endian order. getb +and putb functions handle big-endian, getl and putl handle +little-endian. bfd_get_bits and bfd_put_bits specify +big-endian by passing TRUE in the last parameter, +little-endian by passing FALSE. + +@end deftypefn +@findex bfd_log2 +@subsubsection @code{bfd_log2} +@deftypefn {Function} unsigned int bfd_log2 (bfd_vma x); +Return the log base 2 of the value supplied, rounded up. E.g., an +@var{x} of 1025 returns 11. A @var{x} of 0 returns 0. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/linker.texi 16.3-5ubuntu1/bfd/doc/linker.texi --- 16.3-5/bfd/doc/linker.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/linker.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,470 @@ +@section Linker Functions +@cindex Linker +The linker uses three special entry points in the BFD target +vector. It is not necessary to write special routines for +these entry points when creating a new BFD back end, since +generic versions are provided. However, writing them can +speed up linking and make it use significantly less runtime +memory. +The first routine creates a hash table used by the other +routines. The second routine adds the symbols from an object +file to the hash table. The third routine takes all the +object files and links them together to create the output +file. These routines are designed so that the linker proper +does not need to know anything about the symbols in the object +files that it is linking. The linker merely arranges the +sections as directed by the linker script and lets BFD handle +the details of symbols and relocs. + +The second routine and third routines are passed a pointer to +a @code{struct bfd_link_info} structure (defined in +@code{bfdlink.h}) which holds information relevant to the link, +including the linker hash table (which was created by the +first routine) and a set of callback functions to the linker +proper. + +The generic linker routines are in @code{linker.c}, and use the +header file @code{genlink.h}. As of this writing, the only back +ends which have implemented versions of these routines are +a.out (in @code{aoutx.h}) and ECOFF (in @code{ecoff.c}). The a.out +routines are used as examples throughout this section. + +@menu +* Creating a Linker Hash Table:: +* Adding Symbols to the Hash Table:: +* Performing the Final Link:: +@end menu + +@node Creating a Linker Hash Table, Adding Symbols to the Hash Table, Linker Functions, Linker Functions +@subsection Creating a linker hash table +@cindex _bfd_link_hash_table_create in target vector +@cindex target vector (_bfd_link_hash_table_create) +The linker routines must create a hash table, which must be +derived from @code{struct bfd_link_hash_table} described in +@code{bfdlink.c}. @xref{Hash Tables}, for information on how to +create a derived hash table. This entry point is called using +the target vector of the linker output file. + +The @code{_bfd_link_hash_table_create} entry point must allocate +and initialize an instance of the desired hash table. If the +back end does not require any additional information to be +stored with the entries in the hash table, the entry point may +simply create a @code{struct bfd_link_hash_table}. Most likely, +however, some additional information will be needed. + +For example, with each entry in the hash table the a.out +linker keeps the index the symbol has in the final output file +(this index number is used so that when doing a relocatable +link the symbol index used in the output file can be quickly +filled in when copying over a reloc). The a.out linker code +defines the required structures and functions for a hash table +derived from @code{struct bfd_link_hash_table}. The a.out linker +hash table is created by the function +@code{NAME(aout,link_hash_table_create)}; it simply allocates +space for the hash table, initializes it, and returns a +pointer to it. + +When writing the linker routines for a new back end, you will +generally not know exactly which fields will be required until +you have finished. You should simply create a new hash table +which defines no additional fields, and then simply add fields +as they become necessary. + +@node Adding Symbols to the Hash Table, Performing the Final Link, Creating a Linker Hash Table, Linker Functions +@subsection Adding symbols to the hash table +@cindex _bfd_link_add_symbols in target vector +@cindex target vector (_bfd_link_add_symbols) +The linker proper will call the @code{_bfd_link_add_symbols} +entry point for each object file or archive which is to be +linked (typically these are the files named on the command +line, but some may also come from the linker script). The +entry point is responsible for examining the file. For an +object file, BFD must add any relevant symbol information to +the hash table. For an archive, BFD must determine which +elements of the archive should be used and adding them to the +link. + +The a.out version of this entry point is +@code{NAME(aout,link_add_symbols)}. + +@menu +* Differing file formats:: +* Adding symbols from an object file:: +* Adding symbols from an archive:: +@end menu + +@node Differing file formats, Adding symbols from an object file, Adding Symbols to the Hash Table, Adding Symbols to the Hash Table +@subsubsection Differing file formats +Normally all the files involved in a link will be of the same +format, but it is also possible to link together different +format object files, and the back end must support that. The +@code{_bfd_link_add_symbols} entry point is called via the target +vector of the file to be added. This has an important +consequence: the function may not assume that the hash table +is the type created by the corresponding +@code{_bfd_link_hash_table_create} vector. All the +@code{_bfd_link_add_symbols} function can assume about the hash +table is that it is derived from @code{struct +bfd_link_hash_table}. + +Sometimes the @code{_bfd_link_add_symbols} function must store +some information in the hash table entry to be used by the +@code{_bfd_final_link} function. In such a case the output bfd +xvec must be checked to make sure that the hash table was +created by an object file of the same format. + +The @code{_bfd_final_link} routine must be prepared to handle a +hash entry without any extra information added by the +@code{_bfd_link_add_symbols} function. A hash entry without +extra information will also occur when the linker script +directs the linker to create a symbol. Note that, regardless +of how a hash table entry is added, all the fields will be +initialized to some sort of null value by the hash table entry +initialization function. + +See @code{ecoff_link_add_externals} for an example of how to +check the output bfd before saving information (in this +case, the ECOFF external symbol debugging information) in a +hash table entry. + +@node Adding symbols from an object file, Adding symbols from an archive, Differing file formats, Adding Symbols to the Hash Table +@subsubsection Adding symbols from an object file +When the @code{_bfd_link_add_symbols} routine is passed an object +file, it must add all externally visible symbols in that +object file to the hash table. The actual work of adding the +symbol to the hash table is normally handled by the function +@code{_bfd_generic_link_add_one_symbol}. The +@code{_bfd_link_add_symbols} routine is responsible for reading +all the symbols from the object file and passing the correct +information to @code{_bfd_generic_link_add_one_symbol}. + +The @code{_bfd_link_add_symbols} routine should not use +@code{bfd_canonicalize_symtab} to read the symbols. The point of +providing this routine is to avoid the overhead of converting +the symbols into generic @code{asymbol} structures. + +@findex _bfd_generic_link_add_one_symbol +@code{_bfd_generic_link_add_one_symbol} handles the details of +combining common symbols, warning about multiple definitions, +and so forth. It takes arguments which describe the symbol to +add, notably symbol flags, a section, and an offset. The +symbol flags include such things as @code{BSF_WEAK} or +@code{BSF_INDIRECT}. The section is a section in the object +file, or something like @code{bfd_und_section_ptr} for an undefined +symbol or @code{bfd_com_section_ptr} for a common symbol. + +If the @code{_bfd_final_link} routine is also going to need to +read the symbol information, the @code{_bfd_link_add_symbols} +routine should save it somewhere attached to the object file +BFD. However, the information should only be saved if the +@code{keep_memory} field of the @code{info} argument is TRUE, so +that the @code{-no-keep-memory} linker switch is effective. + +The a.out function which adds symbols from an object file is +@code{aout_link_add_object_symbols}, and most of the interesting +work is in @code{aout_link_add_symbols}. The latter saves +pointers to the hash tables entries created by +@code{_bfd_generic_link_add_one_symbol} indexed by symbol number, +so that the @code{_bfd_final_link} routine does not have to call +the hash table lookup routine to locate the entry. + +@node Adding symbols from an archive, , Adding symbols from an object file, Adding Symbols to the Hash Table +@subsubsection Adding symbols from an archive +When the @code{_bfd_link_add_symbols} routine is passed an +archive, it must look through the symbols defined by the +archive and decide which elements of the archive should be +included in the link. For each such element it must call the +@code{add_archive_element} linker callback, and it must add the +symbols from the object file to the linker hash table. (The +callback may in fact indicate that a replacement BFD should be +used, in which case the symbols from that BFD should be added +to the linker hash table instead.) + +@findex _bfd_generic_link_add_archive_symbols +In most cases the work of looking through the symbols in the +archive should be done by the +@code{_bfd_generic_link_add_archive_symbols} function. +@code{_bfd_generic_link_add_archive_symbols} is passed a function +to call to make the final decision about adding an archive +element to the link and to do the actual work of adding the +symbols to the linker hash table. If the element is to +be included, the @code{add_archive_element} linker callback +routine must be called with the element as an argument, and +the element's symbols must be added to the linker hash table +just as though the element had itself been passed to the +@code{_bfd_link_add_symbols} function. + +When the a.out @code{_bfd_link_add_symbols} function receives an +archive, it calls @code{_bfd_generic_link_add_archive_symbols} +passing @code{aout_link_check_archive_element} as the function +argument. @code{aout_link_check_archive_element} calls +@code{aout_link_check_ar_symbols}. If the latter decides to add +the element (an element is only added if it provides a real, +non-common, definition for a previously undefined or common +symbol) it calls the @code{add_archive_element} callback and then +@code{aout_link_check_archive_element} calls +@code{aout_link_add_symbols} to actually add the symbols to the +linker hash table - possibly those of a substitute BFD, if the +@code{add_archive_element} callback avails itself of that option. + +The ECOFF back end is unusual in that it does not normally +call @code{_bfd_generic_link_add_archive_symbols}, because ECOFF +archives already contain a hash table of symbols. The ECOFF +back end searches the archive itself to avoid the overhead of +creating a new hash table. + +@node Performing the Final Link, , Adding Symbols to the Hash Table, Linker Functions +@subsection Performing the final link +@cindex _bfd_link_final_link in target vector +@cindex target vector (_bfd_final_link) +When all the input files have been processed, the linker calls +the @code{_bfd_final_link} entry point of the output BFD. This +routine is responsible for producing the final output file, +which has several aspects. It must relocate the contents of +the input sections and copy the data into the output sections. +It must build an output symbol table including any local +symbols from the input files and the global symbols from the +hash table. When producing relocatable output, it must +modify the input relocs and write them into the output file. +There may also be object format dependent work to be done. + +The linker will also call the @code{write_object_contents} entry +point when the BFD is closed. The two entry points must work +together in order to produce the correct output file. + +The details of how this works are inevitably dependent upon +the specific object file format. The a.out +@code{_bfd_final_link} routine is @code{NAME(aout,final_link)}. + +@menu +* Information provided by the linker:: +* Relocating the section contents:: +* Writing the symbol table:: +@end menu + +@node Information provided by the linker, Relocating the section contents, Performing the Final Link, Performing the Final Link +@subsubsection Information provided by the linker +Before the linker calls the @code{_bfd_final_link} entry point, +it sets up some data structures for the function to use. + +The @code{input_bfds} field of the @code{bfd_link_info} structure +will point to a list of all the input files included in the +link. These files are linked through the @code{link.next} field +of the @code{bfd} structure. + +Each section in the output file will have a list of +@code{link_order} structures attached to the @code{map_head.link_order} +field (the @code{link_order} structure is defined in +@code{bfdlink.h}). These structures describe how to create the +contents of the output section in terms of the contents of +various input sections, fill constants, and, eventually, other +types of information. They also describe relocs that must be +created by the BFD backend, but do not correspond to any input +file; this is used to support -Ur, which builds constructors +while generating a relocatable object file. + +@node Relocating the section contents, Writing the symbol table, Information provided by the linker, Performing the Final Link +@subsubsection Relocating the section contents +The @code{_bfd_final_link} function should look through the +@code{link_order} structures attached to each section of the +output file. Each @code{link_order} structure should either be +handled specially, or it should be passed to the function +@code{_bfd_default_link_order} which will do the right thing +(@code{_bfd_default_link_order} is defined in @code{linker.c}). + +For efficiency, a @code{link_order} of type +@code{bfd_indirect_link_order} whose associated section belongs +to a BFD of the same format as the output BFD must be handled +specially. This type of @code{link_order} describes part of an +output section in terms of a section belonging to one of the +input files. The @code{_bfd_final_link} function should read the +contents of the section and any associated relocs, apply the +relocs to the section contents, and write out the modified +section contents. If performing a relocatable link, the +relocs themselves must also be modified and written out. + +@findex _bfd_relocate_contents +@findex _bfd_final_link_relocate +The functions @code{_bfd_relocate_contents} and +@code{_bfd_final_link_relocate} provide some general support for +performing the actual relocations, notably overflow checking. +Their arguments include information about the symbol the +relocation is against and a @code{reloc_howto_type} argument +which describes the relocation to perform. These functions +are defined in @code{reloc.c}. + +The a.out function which handles reading, relocating, and +writing section contents is @code{aout_link_input_section}. The +actual relocation is done in @code{aout_link_input_section_std} +and @code{aout_link_input_section_ext}. + +@node Writing the symbol table, , Relocating the section contents, Performing the Final Link +@subsubsection Writing the symbol table +The @code{_bfd_final_link} function must gather all the symbols +in the input files and write them out. It must also write out +all the symbols in the global hash table. This must be +controlled by the @code{strip} and @code{discard} fields of the +@code{bfd_link_info} structure. + +The local symbols of the input files will not have been +entered into the linker hash table. The @code{_bfd_final_link} +routine must consider each input file and include the symbols +in the output file. It may be convenient to do this when +looking through the @code{link_order} structures, or it may be +done by stepping through the @code{input_bfds} list. + +The @code{_bfd_final_link} routine must also traverse the global +hash table to gather all the externally visible symbols. It +is possible that most of the externally visible symbols may be +written out when considering the symbols of each input file, +but it is still necessary to traverse the hash table since the +linker script may have defined some symbols that are not in +any of the input files. + +The @code{strip} field of the @code{bfd_link_info} structure +controls which symbols are written out. The possible values +are listed in @code{bfdlink.h}. If the value is @code{strip_some}, +then the @code{keep_hash} field of the @code{bfd_link_info} +structure is a hash table of symbols to keep; each symbol +should be looked up in this hash table, and only symbols which +are present should be included in the output file. + +If the @code{strip} field of the @code{bfd_link_info} structure +permits local symbols to be written out, the @code{discard} field +is used to further controls which local symbols are included +in the output file. If the value is @code{discard_l}, then all +local symbols which begin with a certain prefix are discarded; +this is controlled by the @code{bfd_is_local_label_name} entry point. + +The a.out backend handles symbols by calling +@code{aout_link_write_symbols} on each input BFD and then +traversing the global hash table with the function +@code{aout_link_write_other_symbol}. It builds a string table +while writing out the symbols, which is written to the output +file at the end of @code{NAME(aout,final_link)}. + +@findex bfd_link_split_section +@subsubsection @code{bfd_link_split_section} +@deftypefn {Function} bool bfd_link_split_section (bfd *abfd, asection *sec); +Return nonzero if @var{sec} should be split during a +reloceatable or final link. +@example +#define bfd_link_split_section(abfd, sec) \ + BFD_SEND (abfd, _bfd_link_split_section, (abfd, sec)) + +@end example + +@end deftypefn +@findex bfd_section_already_linked +@subsubsection @code{bfd_section_already_linked} +@deftypefn {Function} bool bfd_section_already_linked (bfd *abfd, asection *sec, struct bfd_link_info *info); +Check if @var{data} has been already linked during a reloceatable +or final link. Return TRUE if it has. +@example +#define bfd_section_already_linked(abfd, sec, info) \ + BFD_SEND (abfd, _section_already_linked, (abfd, sec, info)) + +@end example + +@end deftypefn +@findex bfd_generic_define_common_symbol +@subsubsection @code{bfd_generic_define_common_symbol} +@deftypefn {Function} bool bfd_generic_define_common_symbol (bfd *output_bfd, struct bfd_link_info *info, struct bfd_link_hash_entry *h); +Convert common symbol @var{h} into a defined symbol. +Return TRUE on success and FALSE on failure. +@example +#define bfd_define_common_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_define_common_symbol, (output_bfd, info, h)) + +@end example + +@end deftypefn +@findex _bfd_generic_link_hide_symbol +@subsubsection @code{_bfd_generic_link_hide_symbol} +@deftypefn {Function} void _bfd_generic_link_hide_symbol (bfd *output_bfd, struct bfd_link_info *info, struct bfd_link_hash_entry *h); +Hide symbol @var{h}. +This is an internal function. It should not be called from +outside the BFD library. +@example +#define bfd_link_hide_symbol(output_bfd, info, h) \ + BFD_SEND (output_bfd, _bfd_link_hide_symbol, (output_bfd, info, h)) + +@end example + +@end deftypefn +@findex bfd_generic_define_start_stop +@subsubsection @code{bfd_generic_define_start_stop} +@deftypefn {Function} struct bfd_link_hash_entry *bfd_generic_define_start_stop (struct bfd_link_info *info, const char *symbol, asection *sec); +Define a __start, __stop, .startof. or .sizeof. symbol. +Return the symbol or NULL if no such undefined symbol exists. +@example +#define bfd_define_start_stop(output_bfd, info, symbol, sec) \ + BFD_SEND (output_bfd, _bfd_define_start_stop, (info, symbol, sec)) + +@end example + +@end deftypefn +@findex bfd_find_version_for_sym +@subsubsection @code{bfd_find_version_for_sym} +@deftypefn {Function} struct bfd_elf_version_tree * bfd_find_version_for_sym (struct bfd_elf_version_tree *verdefs, const char *sym_name, bool *hide); +Search an elf version script tree for symbol versioning +info and export / don't-export status for a given symbol. +Return non-NULL on success and NULL on failure; also sets +the output @samp{hide} boolean parameter. + +@end deftypefn +@findex bfd_hide_sym_by_version +@subsubsection @code{bfd_hide_sym_by_version} +@deftypefn {Function} bool bfd_hide_sym_by_version (struct bfd_elf_version_tree *verdefs, const char *sym_name); +Search an elf version script tree for symbol versioning +info for a given symbol. Return TRUE if the symbol is hidden. + +@end deftypefn +@findex bfd_link_check_relocs +@subsubsection @code{bfd_link_check_relocs} +@deftypefn {Function} bool bfd_link_check_relocs (bfd *abfd, struct bfd_link_info *info); +Checks the relocs in ABFD for validity. +Does not execute the relocs. +Return TRUE if everything is OK, FALSE otherwise. +This is the external entry point to this code. + +@end deftypefn +@findex _bfd_generic_link_check_relocs +@subsubsection @code{_bfd_generic_link_check_relocs} +@deftypefn {Function} bool _bfd_generic_link_check_relocs (bfd *abfd, struct bfd_link_info *info); +Stub function for targets that do not implement reloc checking. +Return TRUE. +This is an internal function. It should not be called from +outside the BFD library. + +@end deftypefn +@findex bfd_merge_private_bfd_data +@subsubsection @code{bfd_merge_private_bfd_data} +@deftypefn {Function} bool bfd_merge_private_bfd_data (bfd *ibfd, struct bfd_link_info *info); +Merge private BFD information from the BFD @var{ibfd} to the +the output file BFD when linking. Return @code{TRUE} on success, +@code{FALSE} on error. Possible error returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{obfd}. +@end itemize +@example +#define bfd_merge_private_bfd_data(ibfd, info) \ + BFD_SEND ((info)->output_bfd, _bfd_merge_private_bfd_data, \ + (ibfd, info)) + +@end example + +@end deftypefn +@findex _bfd_generic_verify_endian_match +@subsubsection @code{_bfd_generic_verify_endian_match} +@deftypefn {Function} bool _bfd_generic_verify_endian_match (bfd *ibfd, struct bfd_link_info *info); +Can be used from / for bfd_merge_private_bfd_data to check that +endianness matches between input and output file. Returns +TRUE for a match, otherwise returns FALSE and emits an error. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/mmo.texi 16.3-5ubuntu1/bfd/doc/mmo.texi --- 16.3-5/bfd/doc/mmo.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/mmo.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,369 @@ +@section mmo backend +The mmo object format is used exclusively together with Professor +Donald E.@: Knuth's educational 64-bit processor MMIX. The simulator +@command{mmix} which is available at +@url{http://mmix.cs.hm.edu/src/index.html} +understands this format. That package also includes a combined +assembler and linker called @command{mmixal}. The mmo format has +no advantages feature-wise compared to e.g. ELF. It is a simple +non-relocatable object format with no support for archives or +debugging information, except for symbol value information and +line numbers (which is not yet implemented in BFD). See +@url{http://mmix.cs.hm.edu/} for more +information about MMIX. The ELF format is used for intermediate +object files in the BFD implementation. +@c We want to xref the symbol table node. A feature in "chew" +@c requires that "commands" do not contain spaces in the +@c arguments. Hence the hyphen in "Symbol-table". +@menu +* File layout:: +* Symbol-table:: +* mmo section mapping:: +@end menu + +@node File layout, Symbol-table, mmo, mmo +@subsection File layout +The mmo file contents is not partitioned into named sections as +with e.g.@: ELF. Memory areas is formed by specifying the +location of the data that follows. Only the memory area +@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} is executable, so +it is used for code (and constants) and the area +@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} is used for +writable data. @xref{mmo section mapping}. + +There is provision for specifying ``special data'' of 65536 +different types. We use type 80 (decimal), arbitrarily chosen the +same as the ELF @code{e_machine} number for MMIX, filling it with +section information normally found in ELF objects. @xref{mmo +section mapping}. + +Contents is entered as 32-bit words, xor:ed over previous +contents, always zero-initialized. A word that starts with the +byte @samp{0x98} forms a command called a @samp{lopcode}, where +the next byte distinguished between the thirteen lopcodes. The +two remaining bytes, called the @samp{Y} and @samp{Z} fields, or +the @samp{YZ} field (a 16-bit big-endian number), are used for +various purposes different for each lopcode. As documented in +@url{http://mmix.cs.hm.edu/doc/mmixal.pdf}, +the lopcodes are: + +@table @code +@item lop_quote +0x98000001. The next word is contents, regardless of whether it +starts with 0x98 or not. + +@item lop_loc +0x9801YYZZ, where @samp{Z} is 1 or 2. This is a location +directive, setting the location for the next data to the next +32-bit word (for @math{Z = 1}) or 64-bit word (for @math{Z = 2}), +plus @math{Y * 2^56}. Normally @samp{Y} is 0 for the text segment +and 2 for the data segment. Beware that the low bits of non- +tetrabyte-aligned values are silently discarded when being +automatically incremented and when storing contents (in contrast +to e.g. its use as current location when followed by lop_fixo +et al before the next possibly-quoted tetrabyte contents). + +@item lop_skip +0x9802YYZZ. Increase the current location by @samp{YZ} bytes. + +@item lop_fixo +0x9803YYZZ, where @samp{Z} is 1 or 2. Store the current location +as 64 bits into the location pointed to by the next 32-bit +(@math{Z = 1}) or 64-bit (@math{Z = 2}) word, plus @math{Y * +2^56}. + +@item lop_fixr +0x9804YYZZ. @samp{YZ} is stored into the current location plus +@math{2 - 4 * YZ}. + +@item lop_fixrx +0x980500ZZ. @samp{Z} is 16 or 24. A value @samp{L} derived from +the following 32-bit word are used in a manner similar to +@samp{YZ} in lop_fixr: it is xor:ed into the current location +minus @math{4 * L}. The first byte of the word is 0 or 1. If it +is 1, then @math{L = (@var{lowest 24 bits of word}) - 2^Z}, if 0, +then @math{L = (@var{lowest 24 bits of word})}. + +@item lop_file +0x9806YYZZ. @samp{Y} is the file number, @samp{Z} is count of +32-bit words. Set the file number to @samp{Y} and the line +counter to 0. The next @math{Z * 4} bytes contain the file name, +padded with zeros if the count is not a multiple of four. The +same @samp{Y} may occur multiple times, but @samp{Z} must be 0 for +all but the first occurrence. + +@item lop_line +0x9807YYZZ. @samp{YZ} is the line number. Together with +lop_file, it forms the source location for the next 32-bit word. +Note that for each non-lopcode 32-bit word, line numbers are +assumed incremented by one. + +@item lop_spec +0x9808YYZZ. @samp{YZ} is the type number. Data until the next +lopcode other than lop_quote forms special data of type @samp{YZ}. +@xref{mmo section mapping}. + +Other types than 80, (or type 80 with a content that does not +parse) is stored in sections named @code{.MMIX.spec_data.@var{n}} +where @var{n} is the @samp{YZ}-type. The flags for such a +sections say not to allocate or load the data. The vma is 0. +Contents of multiple occurrences of special data @var{n} is +concatenated to the data of the previous lop_spec @var{n}s. The +location in data or code at which the lop_spec occurred is lost. + +@item lop_pre +0x980901ZZ. The first lopcode in a file. The @samp{Z} field forms the +length of header information in 32-bit words, where the first word +tells the time in seconds since @samp{00:00:00 GMT Jan 1 1970}. + +@item lop_post +0x980a00ZZ. @math{Z > 32}. This lopcode follows after all +content-generating lopcodes in a program. The @samp{Z} field +denotes the value of @samp{rG} at the beginning of the program. +The following @math{256 - Z} big-endian 64-bit words are loaded +into global registers @samp{$G} @dots{} @samp{$255}. + +@item lop_stab +0x980b0000. The next-to-last lopcode in a program. Must follow +immediately after the lop_post lopcode and its data. After this +lopcode follows all symbols in a compressed format +(@pxref{Symbol-table}). + +@item lop_end +0x980cYYZZ. The last lopcode in a program. It must follow the +lop_stab lopcode and its data. The @samp{YZ} field contains the +number of 32-bit words of symbol table information after the +preceding lop_stab lopcode. +@end table + +Note that the lopcode "fixups"; @code{lop_fixr}, @code{lop_fixrx} and +@code{lop_fixo} are not generated by BFD, but are handled. They are +generated by @code{mmixal}. + +This trivial one-label, one-instruction file: + +@example + :Main TRAP 1,2,3 +@end example + +can be represented this way in mmo: + +@example + 0x98090101 - lop_pre, one 32-bit word with timestamp. + + 0x98010002 - lop_loc, text segment, using a 64-bit address. + Note that mmixal does not emit this for the file above. + 0x00000000 - Address, high 32 bits. + 0x00000000 - Address, low 32 bits. + 0x98060002 - lop_file, 2 32-bit words for file-name. + 0x74657374 - "test" + 0x2e730000 - ".s\0\0" + 0x98070001 - lop_line, line 1. + 0x00010203 - TRAP 1,2,3 + 0x980a00ff - lop_post, setting $255 to 0. + 0x00000000 + 0x00000000 + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 @xref{Symbol-table}. + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 + 0x980c0005 - lop_end; symbol table contained five 32-bit words. +@end example +@node Symbol-table, mmo section mapping, File layout, mmo +@subsection Symbol table format +From mmixal.w (or really, the generated mmixal.tex) in the +MMIXware package which also contains the @command{mmix} simulator: +``Symbols are stored and retrieved by means of a @samp{ternary +search trie}, following ideas of Bentley and Sedgewick. (See +ACM--SIAM Symp.@: on Discrete Algorithms @samp{8} (1997), 360--369; +R.@:Sedgewick, @samp{Algorithms in C} (Reading, Mass.@: +Addison--Wesley, 1998), @samp{15.4}.) Each trie node stores a +character, and there are branches to subtries for the cases where +a given character is less than, equal to, or greater than the +character in the trie. There also is a pointer to a symbol table +entry if a symbol ends at the current node.'' + +So it's a tree encoded as a stream of bytes. The stream of bytes +acts on a single virtual global symbol, adding and removing +characters and signalling complete symbol points. Here, we read +the stream and create symbols at the completion points. + +First, there's a control byte @code{m}. If any of the listed bits +in @code{m} is nonzero, we execute what stands at the right, in +the listed order: + +@example + (MMO3_LEFT) + 0x40 - Traverse left trie. + (Read a new command byte and recurse.) + + (MMO3_SYMBITS) + 0x2f - Read the next byte as a character and store it in the + current character position; increment character position. + Test the bits of @code{m}: + + (MMO3_WCHAR) + 0x80 - The character is 16-bit (so read another byte, + merge into current character. + + (MMO3_TYPEBITS) + 0xf - We have a complete symbol; parse the type, value + and serial number and do what should be done + with a symbol. The type and length information + is in j = (m & 0xf). + + (MMO3_REGQUAL_BITS) + j == 0xf: A register variable. The following + byte tells which register. + j <= 8: An absolute symbol. Read j bytes as the + big-endian number the symbol equals. + A j = 2 with two zero bytes denotes an + unknown symbol. + j > 8: As with j <= 8, but add (0x20 << 56) + to the value in the following j - 8 + bytes. + + Then comes the serial number, as a variant of + uleb128, but better named ubeb128: + Read bytes and shift the previous value left 7 + (multiply by 128). Add in the new byte, repeat + until a byte has bit 7 set. The serial number + is the computed value minus 128. + + (MMO3_MIDDLE) + 0x20 - Traverse middle trie. (Read a new command byte + and recurse.) Decrement character position. + + (MMO3_RIGHT) + 0x10 - Traverse right trie. (Read a new command byte and + recurse.) +@end example + +Let's look again at the @code{lop_stab} for the trivial file +(@pxref{File layout}). + +@example + 0x980b0000 - lop_stab for ":Main" = 0, serial 1. + 0x203a4040 + 0x10404020 + 0x4d206120 + 0x69016e00 + 0x81000000 +@end example + +This forms the trivial trie (note that the path between ``:'' and +``M'' is redundant): + +@example + 203a ":" + 40 / + 40 / + 10 \ + 40 / + 40 / + 204d "M" + 2061 "a" + 2069 "i" + 016e "n" is the last character in a full symbol, and + with a value represented in one byte. + 00 The value is 0. + 81 The serial number is 1. +@end example + +@node mmo section mapping, , Symbol-table, mmo +@subsection mmo section mapping +The implementation in BFD uses special data type 80 (decimal) to +encapsulate and describe named sections, containing e.g.@: debug +information. If needed, any datum in the encapsulation will be +quoted using lop_quote. First comes a 32-bit word holding the +number of 32-bit words containing the zero-terminated zero-padded +segment name. After the name there's a 32-bit word holding flags +describing the section type. Then comes a 64-bit big-endian word +with the section length (in bytes), then another with the section +start address. Depending on the type of section, the contents +might follow, zero-padded to 32-bit boundary. For a loadable +section (such as data or code), the contents might follow at some +later point, not necessarily immediately, as a lop_loc with the +same start address as in the section description, followed by the +contents. This in effect forms a descriptor that must be emitted +before the actual contents. Sections described this way must not +overlap. + +For areas that don't have such descriptors, synthetic sections are +formed by BFD. Consecutive contents in the two memory areas +@samp{0x0000@dots{}00} to @samp{0x01ff@dots{}ff} and +@samp{0x2000@dots{}00} to @samp{0x20ff@dots{}ff} are entered in +sections named @code{.text} and @code{.data} respectively. If an area +is not otherwise described, but would together with a neighboring +lower area be less than @samp{0x40000000} bytes long, it is joined +with the lower area and the gap is zero-filled. For other cases, +a new section is formed, named @code{.MMIX.sec.@var{n}}. Here, +@var{n} is a number, a running count through the mmo file, +starting at 0. + +A loadable section specified as: + +@example + .section secname,"ax" + TETRA 1,2,3,4,-1,-2009 + BYTE 80 +@end example + +and linked to address @samp{0x4}, is represented by the sequence: + +@example + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "secn" + 0x616d6500 - "ame\0" + 0x00000033 - flags CODE, READONLY, LOAD, ALLOC + 0x00000000 - high 32 bits of section length + 0x0000001c - section length is 28 bytes; 6 * 4 + 1 + alignment to 32 bits + 0x00000000 - high 32 bits of section address + 0x00000004 - section address is 4 + 0x98010002 - 64 bits with address of following data + 0x00000000 - high 32 bits of address + 0x00000004 - low 32 bits: data starts at address 4 + 0x00000001 - 1 + 0x00000002 - 2 + 0x00000003 - 3 + 0x00000004 - 4 + 0xffffffff - -1 + 0xfffff827 - -2009 + 0x50000000 - 80 as a byte, padded with zeros. +@end example + +Note that the lop_spec wrapping does not include the section +contents. Compare this to a non-loaded section specified as: + +@example + .section thirdsec + TETRA 200001,100002 + BYTE 38,40 +@end example + +This, when linked to address @samp{0x200000000000001c}, is +represented by: + +@example + 0x98080050 - lop_spec 80 + 0x00000002 - two 32-bit words for the section name + 0x7365636e - "thir" + 0x616d6500 - "dsec" + 0x00000010 - flag READONLY + 0x00000000 - high 32 bits of section length + 0x0000000c - section length is 12 bytes; 2 * 4 + 2 + alignment to 32 bits + 0x20000000 - high 32 bits of address + 0x0000001c - low 32 bits of address 0x200000000000001c + 0x00030d41 - 200001 + 0x000186a2 - 100002 + 0x26280000 - 38, 40 as bytes, padded with zeros +@end example + +For the latter example, the section contents must not be +loaded in memory, and is therefore specified as part of the +special data. The address is usually unimportant but might +provide information for e.g.@: the DWARF 2 debugging format. diff -pruN 16.3-5/bfd/doc/opncls.texi 16.3-5ubuntu1/bfd/doc/opncls.texi --- 16.3-5/bfd/doc/opncls.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/opncls.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,373 @@ +@section Opening and closing BFDs + +@subsection Functions for opening and closing + + +@findex _bfd_new_bfd +@subsubsection @code{_bfd_new_bfd} +@deftypefn {Function} bfd *_bfd_new_bfd (void); +Return a new BFD. All BFD's are allocated through this routine. + +@end deftypefn +@findex _bfd_new_bfd_contained_in +@subsubsection @code{_bfd_new_bfd_contained_in} +@deftypefn {Function} bfd *_bfd_new_bfd_contained_in (bfd *); +Allocate a new BFD as a member of archive OBFD. + +@end deftypefn +@findex _bfd_free_cached_info +@subsubsection @code{_bfd_free_cached_info} +@deftypefn {Function} bool _bfd_free_cached_info (bfd *); +Free objalloc memory. + +@end deftypefn +@findex bfd_fopen +@subsubsection @code{bfd_fopen} +@deftypefn {Function} bfd *bfd_fopen (const char *filename, const char *target, const char *mode, int fd); +Open the file @var{filename} with the target @var{target}. +Return a pointer to the created BFD. If @var{fd} is not -1, +then @code{fdopen} is used to open the file; otherwise, @code{fopen} +is used. @var{mode} is passed directly to @code{fopen} or +@code{fdopen}. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +The new BFD is marked as cacheable iff @var{fd} is -1. + +If @code{NULL} is returned then an error has occured. Possible errors +are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or +@code{system_call} error. + +On error, @var{fd} is always closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_openr +@subsubsection @code{bfd_openr} +@deftypefn {Function} bfd *bfd_openr (const char *filename, const char *target); +Open the file @var{filename} (using @code{fopen}) with the target +@var{target}. Return a pointer to the created BFD. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +If @code{NULL} is returned then an error has occured. Possible errors +are @code{bfd_error_no_memory}, @code{bfd_error_invalid_target} or +@code{system_call} error. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_fdopenr +@subsubsection @code{bfd_fdopenr} +@deftypefn {Function} bfd *bfd_fdopenr (const char *filename, const char *target, int fd); +@code{bfd_fdopenr} is to @code{bfd_fopenr} much like @code{fdopen} is to +@code{fopen}. It opens a BFD on a file already described by the +@var{fd} supplied. + +When the file is later @code{bfd_close}d, the file descriptor will +be closed. If the caller desires that this file descriptor be +cached by BFD (opened as needed, closed as needed to free +descriptors for other opens), with the supplied @var{fd} used as +an initial file descriptor (but subject to closure at any time), +call bfd_set_cacheable(bfd, 1) on the returned BFD. The default +is to assume no caching; the file descriptor will remain open +until @code{bfd_close}, and will not be affected by BFD operations +on other files. + +Possible errors are @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. + +On error, @var{fd} is closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_fdopenw +@subsubsection @code{bfd_fdopenw} +@deftypefn {Function} bfd *bfd_fdopenw (const char *filename, const char *target, int fd); +@code{bfd_fdopenw} is exactly like @code{bfd_fdopenr} with the exception that +the resulting BFD is suitable for output. + +@end deftypefn +@findex bfd_openstreamr +@subsubsection @code{bfd_openstreamr} +@deftypefn {Function} bfd *bfd_openstreamr (const char * filename, const char * target, void * stream); +Open a BFD for read access on an existing stdio stream. When +the BFD is passed to @code{bfd_close}, the stream will be closed. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_openr_iovec +@subsubsection @code{bfd_openr_iovec} +@deftypefn {Function} bfd *bfd_openr_iovec (const char *filename, const char *target, void *(*open_func) (struct bfd *nbfd, void *open_closure), void *open_closure, file_ptr (*pread_func) (struct bfd *nbfd, void *stream, void *buf, file_ptr nbytes, file_ptr offset), int (*close_func) (struct bfd *nbfd, void *stream), int (*stat_func) (struct bfd *abfd, void *stream, struct stat *sb)); +Create and return a BFD backed by a read-only @var{stream}. +The @var{stream} is created using @var{open_func}, accessed using +@var{pread_func} and destroyed using @var{close_func}. + +Calls @code{bfd_find_target}, so @var{target} is interpreted as by +that function. + +Calls @var{open_func} (which can call @code{bfd_zalloc} and +@code{bfd_get_filename}) to obtain the read-only stream backing +the BFD. @var{open_func} either succeeds returning the +non-@code{NULL} @var{stream}, or fails returning @code{NULL} +(setting @code{bfd_error}). + +Calls @var{pread_func} to request @var{nbytes} of data from +@var{stream} starting at @var{offset} (e.g., via a call to +@code{bfd_read}). @var{pread_func} either succeeds returning the +number of bytes read (which can be less than @var{nbytes} when +end-of-file), or fails returning -1 (setting @code{bfd_error}). + +Calls @var{close_func} when the BFD is later closed using +@code{bfd_close}. @var{close_func} either succeeds returning 0, or +fails returning -1 (setting @code{bfd_error}). + +Calls @var{stat_func} to fill in a stat structure for bfd_stat, +bfd_get_size, and bfd_get_mtime calls. @var{stat_func} returns 0 +on success, or returns -1 on failure (setting @code{bfd_error}). + +If @code{bfd_openr_iovec} returns @code{NULL} then an error has +occurred. Possible errors are @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target} and @code{bfd_error_system_call}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_openw +@subsubsection @code{bfd_openw} +@deftypefn {Function} bfd *bfd_openw (const char *filename, const char *target); +Create a BFD, associated with file @var{filename}, using the +file format @var{target}, and return a pointer to it. + +Possible errors are @code{bfd_error_system_call}, @code{bfd_error_no_memory}, +@code{bfd_error_invalid_target}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_elf_bfd_from_remote_memory +@subsubsection @code{bfd_elf_bfd_from_remote_memory} +@deftypefn {Function} bfd *bfd_elf_bfd_from_remote_memory (bfd *templ, bfd_vma ehdr_vma, bfd_size_type size, bfd_vma *loadbasep, int (*target_read_memory) (bfd_vma vma, bfd_byte *myaddr, bfd_size_type len)); +Create a new BFD as if by bfd_openr. Rather than opening a +file, reconstruct an ELF file by reading the segments out of +remote memory based on the ELF file header at EHDR_VMA and the +ELF program headers it points to. If non-zero, SIZE is the +known extent of the object. If not null, *LOADBASEP is filled +in with the difference between the VMAs from which the +segments were read, and the VMAs the file headers (and hence +BFD's idea of each section's VMA) put them at. + +The function TARGET_READ_MEMORY is called to copy LEN bytes +from the remote memory at target address VMA into the local +buffer at MYADDR; it should return zero on success or an +errno code on failure. TEMPL must be a BFD for an ELF +target with the word size and byte order found in the remote +memory. + +@end deftypefn +@findex bfd_close +@subsubsection @code{bfd_close} +@deftypefn {Function} bool bfd_close (bfd *abfd); +Close a BFD. If the BFD was open for writing, then pending +operations are completed and the file written out and closed. +If the created file is executable, then @code{chmod} is called +to mark it as such. + +All memory attached to the BFD is released. + +The file descriptor associated with the BFD is closed (even +if it was passed in to BFD by @code{bfd_fdopenr}). + +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@end deftypefn +@findex bfd_close_all_done +@subsubsection @code{bfd_close_all_done} +@deftypefn {Function} bool bfd_close_all_done (bfd *); +Close a BFD. Differs from @code{bfd_close} since it does not +complete any pending operations. This routine would be used +if the application had just used BFD for swapping and didn't +want to use any of the writing code. + +If the created file is executable, then @code{chmod} is called +to mark it as such. + +All memory attached to the BFD is released. + +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@end deftypefn +@findex bfd_create +@subsubsection @code{bfd_create} +@deftypefn {Function} bfd *bfd_create (const char *filename, bfd *templ); +Create a new BFD in the manner of @code{bfd_openw}, but without +opening a file. The new BFD takes the target from the target +used by @var{templ}. The format is always set to @code{bfd_object}. + +A copy of the @var{filename} argument is stored in the newly created +BFD. It can be accessed via the bfd_get_filename() macro. + +@end deftypefn +@findex bfd_make_writable +@subsubsection @code{bfd_make_writable} +@deftypefn {Function} bool bfd_make_writable (bfd *abfd); +Takes a BFD as created by @code{bfd_create} and converts it +into one like as returned by @code{bfd_openw}. It does this +by converting the BFD to BFD_IN_MEMORY. It's assumed that +you will call @code{bfd_make_readable} on this bfd later. + +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@end deftypefn +@findex bfd_make_readable +@subsubsection @code{bfd_make_readable} +@deftypefn {Function} bool bfd_make_readable (bfd *abfd); +Takes a BFD as created by @code{bfd_create} and +@code{bfd_make_writable} and converts it into one like as +returned by @code{bfd_openr}. It does this by writing the +contents out to the memory buffer, then reversing the +direction. + +@code{TRUE} is returned if all is ok, otherwise @code{FALSE}. + +@end deftypefn +@findex bfd_calc_gnu_debuglink_crc32 +@subsubsection @code{bfd_calc_gnu_debuglink_crc32} +@deftypefn {Function} uint32_t bfd_calc_gnu_debuglink_crc32 (uint32_t crc, const bfd_byte *buf, bfd_size_type len); +Computes a CRC value as used in the .gnu_debuglink section. +Advances the previously computed @var{crc} value by computing +and adding in the crc32 for @var{len} bytes of @var{buf}. + +Return the updated CRC32 value. + +@end deftypefn +@findex bfd_get_debug_link_info +@subsubsection @code{bfd_get_debug_link_info} +@deftypefn {Function} char *bfd_get_debug_link_info (bfd *abfd, uint32_t *crc32_out); +Extracts the filename and CRC32 value for any separate debug +information file associated with @var{abfd}. + +Returns the filename of the associated debug information file, +or NULL if there is no such file. If the filename was found +then the contents of @var{crc32_out} are updated to hold the +corresponding CRC32 value for the file. + +The returned filename is allocated with @code{malloc}; freeing +it is the responsibility of the caller. + +@end deftypefn +@findex bfd_get_alt_debug_link_info +@subsubsection @code{bfd_get_alt_debug_link_info} +@deftypefn {Function} char *bfd_get_alt_debug_link_info (bfd * abfd, bfd_size_type *buildid_len, bfd_byte **buildid_out); +Fetch the filename and BuildID value for any alternate debuginfo +associated with @var{abfd}. Return NULL if no such info found, +otherwise return filename and update @var{buildid_len} and +@var{buildid_out}. The returned filename and build_id are +allocated with @code{malloc}; freeing them is the responsibility +of the caller. + +@end deftypefn +@findex bfd_follow_gnu_debuglink +@subsubsection @code{bfd_follow_gnu_debuglink} +@deftypefn {Function} char *bfd_follow_gnu_debuglink (bfd *abfd, const char *dir); +Takes a BFD and searches it for a .gnu_debuglink section. If this +section is found, it examines the section for the name and checksum +of a '.debug' file containing auxiliary debugging information. It +then searches the filesystem for this .debug file in some standard +locations, including the directory tree rooted at @var{dir}, and if +found returns the full filename. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +Returns @code{NULL} on any errors or failure to locate the .debug +file, otherwise a pointer to a heap-allocated string +containing the filename. The caller is responsible for +freeing this string. + +@end deftypefn +@findex bfd_follow_gnu_debugaltlink +@subsubsection @code{bfd_follow_gnu_debugaltlink} +@deftypefn {Function} char *bfd_follow_gnu_debugaltlink (bfd *abfd, const char *dir); +Takes a BFD and searches it for a .gnu_debugaltlink section. If this +section is found, it examines the section for the name of a file +containing auxiliary debugging information. It then searches the +filesystem for this file in a set of standard locations, including +the directory tree rooted at @var{dir}, and if found returns the +full filename. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +Returns @code{NULL} on any errors or failure to locate the debug +file, otherwise a pointer to a heap-allocated string +containing the filename. The caller is responsible for +freeing this string. + +@end deftypefn +@findex bfd_create_gnu_debuglink_section +@subsubsection @code{bfd_create_gnu_debuglink_section} +@deftypefn {Function} struct bfd_section *bfd_create_gnu_debuglink_section (bfd *abfd, const char *filename); +Takes a @var{BFD} and adds a .gnu_debuglink section to it. The +section is sized to be big enough to contain a link to the specified +@var{filename}. + +A pointer to the new section is returned if all is ok. Otherwise +@code{NULL} is returned and bfd_error is set. + +@end deftypefn +@findex bfd_fill_in_gnu_debuglink_section +@subsubsection @code{bfd_fill_in_gnu_debuglink_section} +@deftypefn {Function} bool bfd_fill_in_gnu_debuglink_section (bfd *abfd, struct bfd_section *sect, const char *filename); +Takes a @var{BFD} and containing a .gnu_debuglink section @var{SECT} +and fills in the contents of the section to contain a link to the +specified @var{filename}. The filename should be absolute or +relative to the current directory. + +@code{TRUE} is returned if all is ok. Otherwise @code{FALSE} is returned +and bfd_error is set. + +@end deftypefn +@findex bfd_follow_build_id_debuglink +@subsubsection @code{bfd_follow_build_id_debuglink} +@deftypefn {Function} char *bfd_follow_build_id_debuglink (bfd *abfd, const char *dir); +Takes @var{abfd} and searches it for a .note.gnu.build-id section. +If this section is found, it extracts the value of the NT_GNU_BUILD_ID +note, which should be a hexadecimal value @var{NNNN+NN} (for +32+ hex digits). It then searches the filesystem for a file named +@var{.build-id/NN/NN+NN.debug} in a set of standard locations, +including the directory tree rooted at @var{dir}. The filename +of the first matching file to be found is returned. A matching +file should contain a .note.gnu.build-id section with the same +@var{NNNN+NN} note as @var{abfd}, although this check is currently +not implemented. + +If @var{dir} is NULL, the search will take place starting at +the current directory. + +Returns @code{NULL} on any errors or failure to locate the debug +file, otherwise a pointer to a heap-allocated string +containing the filename. The caller is responsible for +freeing this string. + +@end deftypefn +@findex bfd_set_filename +@subsubsection @code{bfd_set_filename} +@deftypefn {Function} const char *bfd_set_filename (bfd *abfd, const char *filename); +Set the filename of @var{abfd}, copying the FILENAME parameter to +bfd_alloc'd memory owned by @var{abfd}. Returns a pointer the +newly allocated name, or NULL if the allocation failed. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/reloc.texi 16.3-5ubuntu1/bfd/doc/reloc.texi --- 16.3-5/bfd/doc/reloc.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/reloc.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,4668 @@ +@section Relocations +BFD maintains relocations in much the same way it maintains +symbols: they are left alone until required, then read in +en-masse and translated into an internal form. A common +routine @code{bfd_perform_relocation} acts upon the +canonical form to do the fixup. +Relocations are maintained on a per section basis, +while symbols are maintained on a per BFD basis. + +All that a back end has to do to fit the BFD interface is to create +a @code{struct reloc_cache_entry} for each relocation +in a particular section, and fill in the right bits of the structures. + +@menu +* typedef arelent:: +* howto manager:: +@end menu + + +@node typedef arelent, howto manager, Relocations, Relocations +@subsection typedef arelent +This is the structure of a relocation entry: + + +@example +struct reloc_cache_entry +@{ + /* A pointer into the canonical table of pointers. */ + struct bfd_symbol **sym_ptr_ptr; + + /* offset in section. */ + bfd_size_type address; + + /* addend for relocation value. */ + bfd_vma addend; + + /* Pointer to how to perform the required relocation. */ + reloc_howto_type *howto; + +@}; + +@end example +Here is a description of each of the fields within an @code{arelent}: + +@itemize @bullet + +@item +@code{sym_ptr_ptr} +@end itemize +The symbol table pointer points to a pointer to the symbol +associated with the relocation request. It is the pointer +into the table returned by the back end's +@code{canonicalize_symtab} action. @xref{Symbols}. The symbol is +referenced through a pointer to a pointer so that tools like +the linker can fix up all the symbols of the same name by +modifying only one pointer. The relocation routine looks in +the symbol and uses the base of the section the symbol is +attached to and the value of the symbol as the initial +relocation offset. If the symbol pointer is zero, then the +section provided is looked up. + +@itemize @bullet + +@item +@code{address} +@end itemize +The @code{address} field gives the offset in bytes from the base of +the section data which owns the relocation record to the first +byte of relocatable information. The actual data relocated +will be relative to this point; for example, a relocation +type which modifies the bottom two bytes of a four byte word +would not touch the first byte pointed to in a big endian +world. + +@itemize @bullet + +@item +@code{addend} +@end itemize +The @code{addend} is a value provided by the back end to be added (!) +to the relocation offset. Its interpretation is dependent upon +the howto. For example, on the 68k the code: + +@example + char foo[]; + main() + @{ + return foo[0x12345678]; + @} +@end example + +Could be compiled into: + +@example + linkw fp,#-4 + moveb @@#12345678,d0 + extbl d0 + unlk fp + rts +@end example + +This could create a reloc pointing to @code{foo}, but leave the +offset in the data, something like: + +@example +RELOCATION RECORDS FOR [.text]: +offset type value +00000006 32 _foo + +00000000 4e56 fffc ; linkw fp,#-4 +00000004 1039 1234 5678 ; moveb @@#12345678,d0 +0000000a 49c0 ; extbl d0 +0000000c 4e5e ; unlk fp +0000000e 4e75 ; rts +@end example + +Using coff and an 88k, some instructions don't have enough +space in them to represent the full address range, and +pointers have to be loaded in two parts. So you'd get something like: + +@example + or.u r13,r0,hi16(_foo+0x12345678) + ld.b r2,r13,lo16(_foo+0x12345678) + jmp r1 +@end example + +This should create two relocs, both pointing to @code{_foo}, and with +0x12340000 in their addend field. The data would consist of: + +@example +RELOCATION RECORDS FOR [.text]: +offset type value +00000002 HVRT16 _foo+0x12340000 +00000006 LVRT16 _foo+0x12340000 + +00000000 5da05678 ; or.u r13,r0,0x5678 +00000004 1c4d5678 ; ld.b r2,r13,0x5678 +00000008 f400c001 ; jmp r1 +@end example + +The relocation routine digs out the value from the data, adds +it to the addend to get the original offset, and then adds the +value of @code{_foo}. Note that all 32 bits have to be kept around +somewhere, to cope with carry from bit 15 to bit 16. + +One further example is the sparc and the a.out format. The +sparc has a similar problem to the 88k, in that some +instructions don't have room for an entire offset, but on the +sparc the parts are created in odd sized lumps. The designers of +the a.out format chose to not use the data within the section +for storing part of the offset; all the offset is kept within +the reloc. Anything in the data should be ignored. + +@example + save %sp,-112,%sp + sethi %hi(_foo+0x12345678),%g2 + ldsb [%g2+%lo(_foo+0x12345678)],%i0 + ret + restore +@end example + +Both relocs contain a pointer to @code{foo}, and the offsets +contain junk. + +@example +RELOCATION RECORDS FOR [.text]: +offset type value +00000004 HI22 _foo+0x12345678 +00000008 LO10 _foo+0x12345678 + +00000000 9de3bf90 ; save %sp,-112,%sp +00000004 05000000 ; sethi %hi(_foo+0),%g2 +00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 +0000000c 81c7e008 ; ret +00000010 81e80000 ; restore +@end example + +@itemize @bullet + +@item +@code{howto} +@end itemize +The @code{howto} field can be imagined as a +relocation instruction. It is a pointer to a structure which +contains information on what to do with all of the other +information in the reloc record and data section. A back end +would normally have a relocation instruction set and turn +relocations into pointers to the correct structure on input - +but it would be possible to create each howto field on demand. + +@subsubsection @code{enum complain_overflow} +Indicates what sort of overflow checking should be done when +performing a relocation. + + +@example +enum complain_overflow +@{ + /* Do not complain on overflow. */ + complain_overflow_dont, + + /* Complain if the value overflows when considered as a signed + number one bit larger than the field. ie. A bitfield of N bits + is allowed to represent -2**n to 2**n-1. */ + complain_overflow_bitfield, + + /* Complain if the value overflows when considered as a signed + number. */ + complain_overflow_signed, + + /* Complain if the value overflows when considered as an + unsigned number. */ + complain_overflow_unsigned +@}; + +@end example +@subsubsection @code{reloc_howto_type} +The @code{reloc_howto_type} is a structure which contains all the +information that libbfd needs to know to tie up a back end's data. + + +@example +struct reloc_howto_struct +@{ + /* The type field has mainly a documentary use - the back end can + do what it wants with it, though normally the back end's idea of + an external reloc number is stored in this field. */ + unsigned int type; + + /* The size of the item to be relocated in bytes. */ + unsigned int size:4; + + /* The number of bits in the field to be relocated. This is used + when doing overflow checking. */ + unsigned int bitsize:7; + + /* The value the final relocation is shifted right by. This drops + unwanted data from the relocation. */ + unsigned int rightshift:6; + + /* The bit position of the reloc value in the destination. + The relocated value is left shifted by this amount. */ + unsigned int bitpos:6; + + /* What type of overflow error should be checked for when + relocating. */ + ENUM_BITFIELD (complain_overflow) complain_on_overflow:2; + + /* The relocation value should be negated before applying. */ + unsigned int negate:1; + + /* The relocation is relative to the item being relocated. */ + unsigned int pc_relative:1; + + /* Some formats record a relocation addend in the section contents + rather than with the relocation. For ELF formats this is the + distinction between USE_REL and USE_RELA (though the code checks + for USE_REL == 1/0). The value of this field is TRUE if the + addend is recorded with the section contents; when performing a + partial link (ld -r) the section contents (the data) will be + modified. The value of this field is FALSE if addends are + recorded with the relocation (in arelent.addend); when performing + a partial link the relocation will be modified. + All relocations for all ELF USE_RELA targets should set this field + to FALSE (values of TRUE should be looked on with suspicion). + However, the converse is not true: not all relocations of all ELF + USE_REL targets set this field to TRUE. Why this is so is peculiar + to each particular target. For relocs that aren't used in partial + links (e.g. GOT stuff) it doesn't matter what this is set to. */ + unsigned int partial_inplace:1; + + /* When some formats create PC relative instructions, they leave + the value of the pc of the place being relocated in the offset + slot of the instruction, so that a PC relative relocation can + be made just by adding in an ordinary offset (e.g., sun3 a.out). + Some formats leave the displacement part of an instruction + empty (e.g., ELF); this flag signals the fact. */ + unsigned int pcrel_offset:1; + + /* Whether bfd_install_relocation should just install the addend, + or should follow the practice of some older object formats and + install a value including the symbol. */ + unsigned int install_addend:1; + + /* src_mask selects the part of the instruction (or data) to be used + in the relocation sum. If the target relocations don't have an + addend in the reloc, eg. ELF USE_REL, src_mask will normally equal + dst_mask to extract the addend from the section contents. If + relocations do have an addend in the reloc, eg. ELF USE_RELA, this + field should normally be zero. Non-zero values for ELF USE_RELA + targets should be viewed with suspicion as normally the value in + the dst_mask part of the section contents should be ignored. */ + bfd_vma src_mask; + + /* dst_mask selects which parts of the instruction (or data) are + replaced with a relocated value. */ + bfd_vma dst_mask; + + /* If this field is non null, then the supplied function is + called rather than the normal function. This allows really + strange relocation methods to be accommodated. */ + bfd_reloc_status_type (*special_function) + (bfd *, arelent *, struct bfd_symbol *, void *, asection *, + bfd *, char **); + + /* The textual name of the relocation type. */ + const char *name; +@}; + +@end example +@findex The HOWTO Macro +@subsubsection @code{The HOWTO Macro} +The HOWTO macro fills in a reloc_howto_type (a typedef for +const struct reloc_howto_struct). +@example +#define HOWTO_INSTALL_ADDEND 0 +#define HOWTO_RSIZE(sz) ((sz) < 0 ? -(sz) : (sz)) +#define HOWTO(type, right, size, bits, pcrel, left, ovf, func, name, \ + inplace, src_mask, dst_mask, pcrel_off) \ + @{ (unsigned) type, HOWTO_RSIZE (size), bits, right, left, ovf, \ + size < 0, pcrel, inplace, pcrel_off, HOWTO_INSTALL_ADDEND, \ + src_mask, dst_mask, func, name @} +@end example + +This is used to fill in an empty howto entry in an array. +@example +#define EMPTY_HOWTO(C) \ + HOWTO ((C), 0, 1, 0, false, 0, complain_overflow_dont, NULL, \ + NULL, false, 0, 0, false) + +static inline unsigned int +bfd_get_reloc_size (reloc_howto_type *howto) +@{ + return howto->size; +@} + +@end example + +@findex arelent_chain +@subsubsection @code{arelent_chain} +How relocs are tied together in an @code{asection}: +@example +typedef struct relent_chain +@{ + arelent relent; + struct relent_chain *next; +@} +arelent_chain; + +@end example + +@findex bfd_check_overflow +@subsubsection @code{bfd_check_overflow} +@deftypefn {Function} bfd_reloc_status_type bfd_check_overflow (enum complain_overflow how, unsigned int bitsize, unsigned int rightshift, unsigned int addrsize, bfd_vma relocation); +Perform overflow checking on @var{relocation} which has +@var{bitsize} significant bits and will be shifted right by +@var{rightshift} bits, on a machine with addresses containing +@var{addrsize} significant bits. The result is either of +@code{bfd_reloc_ok} or @code{bfd_reloc_overflow}. + +@end deftypefn +@findex bfd_reloc_offset_in_range +@subsubsection @code{bfd_reloc_offset_in_range} +@deftypefn {Function} bool bfd_reloc_offset_in_range (reloc_howto_type *howto, bfd *abfd, asection *section, bfd_size_type offset); +Returns TRUE if the reloc described by @var{HOWTO} can be +applied at @var{OFFSET} octets in @var{SECTION}. + +@end deftypefn +@findex bfd_perform_relocation +@subsubsection @code{bfd_perform_relocation} +@deftypefn {Function} bfd_reloc_status_type bfd_perform_relocation (bfd *abfd, arelent *reloc_entry, void *data, asection *input_section, bfd *output_bfd, char **error_message); +If @var{output_bfd} is supplied to this function, the +generated image will be relocatable; the relocations are +copied to the output file after they have been changed to +reflect the new state of the world. There are two ways of +reflecting the results of partial linkage in an output file: +by modifying the output data in place, and by modifying the +relocation record. Some native formats (e.g., basic a.out and +basic coff) have no way of specifying an addend in the +relocation type, so the addend has to go in the output data. +This is no big deal since in these formats the output data +slot will always be big enough for the addend. Complex reloc +types with addends were invented to solve just this problem. +The @var{error_message} argument is set to an error message if +this return @code{bfd_reloc_dangerous}. + +@end deftypefn +@findex bfd_install_relocation +@subsubsection @code{bfd_install_relocation} +@deftypefn {Function} bfd_reloc_status_type bfd_install_relocation (bfd *abfd, arelent *reloc_entry, void *data, bfd_vma data_start, asection *input_section, char **error_message); +This looks remarkably like @code{bfd_perform_relocation}, except it +does not expect that the section contents have been filled in. +I.e., it's suitable for use when creating, rather than applying +a relocation. + +For now, this function should be considered reserved for the +assembler. + +@end deftypefn + +@node howto manager, , typedef arelent, Relocations +@subsection The howto manager +When an application wants to create a relocation, but doesn't +know what the target machine might call it, it can find out by +using this bit of code. + +@findex bfd_reloc_code_real_type +@subsubsection @code{bfd_reloc_code_real_type} +The insides of a reloc code. The idea is that, eventually, there +will be one enumerator for every type of relocation we ever do. +Pass one of these values to @code{bfd_reloc_type_lookup}, and it'll +return a howto pointer. + +This does mean that the application must determine the correct +enumerator value; you can't get a howto pointer from a random set +of attributes. + +Here are the possible values for @code{enum bfd_reloc_code_real}: + +@deffn {} BFD_RELOC_64 +@deffnx {} BFD_RELOC_32 +@deffnx {} BFD_RELOC_26 +@deffnx {} BFD_RELOC_24 +@deffnx {} BFD_RELOC_16 +@deffnx {} BFD_RELOC_14 +@deffnx {} BFD_RELOC_8 +Basic absolute relocations of N bits. +@end deffn +@deffn {} BFD_RELOC_64_PCREL +@deffnx {} BFD_RELOC_32_PCREL +@deffnx {} BFD_RELOC_24_PCREL +@deffnx {} BFD_RELOC_16_PCREL +@deffnx {} BFD_RELOC_12_PCREL +@deffnx {} BFD_RELOC_8_PCREL +PC-relative relocations. Sometimes these are relative to the +address of the relocation itself; sometimes they are relative to the +start of the section containing the relocation. It depends on the +specific target. +@end deffn +@deffn {} BFD_RELOC_32_SECREL +@deffnx {} BFD_RELOC_16_SECIDX +Section relative relocations. Some targets need this for DWARF2. +@end deffn +@deffn {} BFD_RELOC_32_GOT_PCREL +@deffnx {} BFD_RELOC_16_GOT_PCREL +@deffnx {} BFD_RELOC_8_GOT_PCREL +@deffnx {} BFD_RELOC_32_GOTOFF +@deffnx {} BFD_RELOC_16_GOTOFF +@deffnx {} BFD_RELOC_LO16_GOTOFF +@deffnx {} BFD_RELOC_HI16_GOTOFF +@deffnx {} BFD_RELOC_HI16_S_GOTOFF +@deffnx {} BFD_RELOC_8_GOTOFF +@deffnx {} BFD_RELOC_64_PLT_PCREL +@deffnx {} BFD_RELOC_32_PLT_PCREL +@deffnx {} BFD_RELOC_24_PLT_PCREL +@deffnx {} BFD_RELOC_16_PLT_PCREL +@deffnx {} BFD_RELOC_8_PLT_PCREL +@deffnx {} BFD_RELOC_64_PLTOFF +@deffnx {} BFD_RELOC_32_PLTOFF +@deffnx {} BFD_RELOC_16_PLTOFF +@deffnx {} BFD_RELOC_LO16_PLTOFF +@deffnx {} BFD_RELOC_HI16_PLTOFF +@deffnx {} BFD_RELOC_HI16_S_PLTOFF +@deffnx {} BFD_RELOC_8_PLTOFF +For ELF. +@end deffn +@deffn {} BFD_RELOC_SIZE32 +@deffnx {} BFD_RELOC_SIZE64 +Size relocations. +@end deffn +@deffn {} BFD_RELOC_68K_GLOB_DAT +@deffnx {} BFD_RELOC_68K_JMP_SLOT +@deffnx {} BFD_RELOC_68K_RELATIVE +@deffnx {} BFD_RELOC_68K_TLS_GD32 +@deffnx {} BFD_RELOC_68K_TLS_GD16 +@deffnx {} BFD_RELOC_68K_TLS_GD8 +@deffnx {} BFD_RELOC_68K_TLS_LDM32 +@deffnx {} BFD_RELOC_68K_TLS_LDM16 +@deffnx {} BFD_RELOC_68K_TLS_LDM8 +@deffnx {} BFD_RELOC_68K_TLS_LDO32 +@deffnx {} BFD_RELOC_68K_TLS_LDO16 +@deffnx {} BFD_RELOC_68K_TLS_LDO8 +@deffnx {} BFD_RELOC_68K_TLS_IE32 +@deffnx {} BFD_RELOC_68K_TLS_IE16 +@deffnx {} BFD_RELOC_68K_TLS_IE8 +@deffnx {} BFD_RELOC_68K_TLS_LE32 +@deffnx {} BFD_RELOC_68K_TLS_LE16 +@deffnx {} BFD_RELOC_68K_TLS_LE8 +Relocations used by 68K ELF. +@end deffn +@deffn {} BFD_RELOC_32_BASEREL +@deffnx {} BFD_RELOC_16_BASEREL +@deffnx {} BFD_RELOC_LO16_BASEREL +@deffnx {} BFD_RELOC_HI16_BASEREL +@deffnx {} BFD_RELOC_HI16_S_BASEREL +@deffnx {} BFD_RELOC_8_BASEREL +@deffnx {} BFD_RELOC_RVA +Linkage-table relative. +@end deffn +@deffn {} BFD_RELOC_8_FFnn +Absolute 8-bit relocation, but used to form an address like 0xFFnn. +@end deffn +@deffn {} BFD_RELOC_32_PCREL_S2 +@deffnx {} BFD_RELOC_16_PCREL_S2 +@deffnx {} BFD_RELOC_23_PCREL_S2 +These PC-relative relocations are stored as word displacements -- +i.e., byte displacements shifted right two bits. The 30-bit word +displacement (<<32_PCREL_S2>> -- 32 bits, shifted 2) is used on the +SPARC. (SPARC tools generally refer to this as <>.) The +signed 16-bit displacement is used on the MIPS, and the 23-bit +displacement is used on the Alpha. +@end deffn +@deffn {} BFD_RELOC_HI22 +@deffnx {} BFD_RELOC_LO10 +High 22 bits and low 10 bits of 32-bit value, placed into lower bits +of the target word. These are used on the SPARC. +@end deffn +@deffn {} BFD_RELOC_GPREL16 +@deffnx {} BFD_RELOC_GPREL32 +For systems that allocate a Global Pointer register, these are +displacements off that register. These relocation types are +handled specially, because the value the register will have is +decided relatively late. +@end deffn +@deffn {} BFD_RELOC_NONE +@deffnx {} BFD_RELOC_SPARC_WDISP22 +@deffnx {} BFD_RELOC_SPARC22 +@deffnx {} BFD_RELOC_SPARC13 +@deffnx {} BFD_RELOC_SPARC_GOT10 +@deffnx {} BFD_RELOC_SPARC_GOT13 +@deffnx {} BFD_RELOC_SPARC_GOT22 +@deffnx {} BFD_RELOC_SPARC_PC10 +@deffnx {} BFD_RELOC_SPARC_PC22 +@deffnx {} BFD_RELOC_SPARC_WPLT30 +@deffnx {} BFD_RELOC_SPARC_COPY +@deffnx {} BFD_RELOC_SPARC_GLOB_DAT +@deffnx {} BFD_RELOC_SPARC_JMP_SLOT +@deffnx {} BFD_RELOC_SPARC_RELATIVE +@deffnx {} BFD_RELOC_SPARC_UA16 +@deffnx {} BFD_RELOC_SPARC_UA32 +@deffnx {} BFD_RELOC_SPARC_UA64 +@deffnx {} BFD_RELOC_SPARC_GOTDATA_HIX22 +@deffnx {} BFD_RELOC_SPARC_GOTDATA_LOX10 +@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP_HIX22 +@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP_LOX10 +@deffnx {} BFD_RELOC_SPARC_GOTDATA_OP +@deffnx {} BFD_RELOC_SPARC_JMP_IREL +@deffnx {} BFD_RELOC_SPARC_IRELATIVE +SPARC ELF relocations. There is probably some overlap with other +relocation types already defined. +@end deffn +@deffn {} BFD_RELOC_SPARC_BASE13 +@deffnx {} BFD_RELOC_SPARC_BASE22 +I think these are specific to SPARC a.out (e.g., Sun 4). +@end deffn +@deffn {} BFD_RELOC_SPARC_64 +@deffnx {} BFD_RELOC_SPARC_10 +@deffnx {} BFD_RELOC_SPARC_11 +@deffnx {} BFD_RELOC_SPARC_OLO10 +@deffnx {} BFD_RELOC_SPARC_HH22 +@deffnx {} BFD_RELOC_SPARC_HM10 +@deffnx {} BFD_RELOC_SPARC_LM22 +@deffnx {} BFD_RELOC_SPARC_PC_HH22 +@deffnx {} BFD_RELOC_SPARC_PC_HM10 +@deffnx {} BFD_RELOC_SPARC_PC_LM22 +@deffnx {} BFD_RELOC_SPARC_WDISP16 +@deffnx {} BFD_RELOC_SPARC_WDISP19 +@deffnx {} BFD_RELOC_SPARC_7 +@deffnx {} BFD_RELOC_SPARC_6 +@deffnx {} BFD_RELOC_SPARC_5 +@deffnx {} BFD_RELOC_SPARC_DISP64 +@deffnx {} BFD_RELOC_SPARC_PLT32 +@deffnx {} BFD_RELOC_SPARC_PLT64 +@deffnx {} BFD_RELOC_SPARC_HIX22 +@deffnx {} BFD_RELOC_SPARC_LOX10 +@deffnx {} BFD_RELOC_SPARC_H44 +@deffnx {} BFD_RELOC_SPARC_M44 +@deffnx {} BFD_RELOC_SPARC_L44 +@deffnx {} BFD_RELOC_SPARC_REGISTER +@deffnx {} BFD_RELOC_SPARC_H34 +@deffnx {} BFD_RELOC_SPARC_SIZE32 +@deffnx {} BFD_RELOC_SPARC_SIZE64 +@deffnx {} BFD_RELOC_SPARC_WDISP10 +SPARC64 relocations. +@end deffn +@deffn {} BFD_RELOC_SPARC_REV32 +SPARC little endian relocation. +@end deffn +@deffn {} BFD_RELOC_SPARC_TLS_GD_HI22 +@deffnx {} BFD_RELOC_SPARC_TLS_GD_LO10 +@deffnx {} BFD_RELOC_SPARC_TLS_GD_ADD +@deffnx {} BFD_RELOC_SPARC_TLS_GD_CALL +@deffnx {} BFD_RELOC_SPARC_TLS_LDM_HI22 +@deffnx {} BFD_RELOC_SPARC_TLS_LDM_LO10 +@deffnx {} BFD_RELOC_SPARC_TLS_LDM_ADD +@deffnx {} BFD_RELOC_SPARC_TLS_LDM_CALL +@deffnx {} BFD_RELOC_SPARC_TLS_LDO_HIX22 +@deffnx {} BFD_RELOC_SPARC_TLS_LDO_LOX10 +@deffnx {} BFD_RELOC_SPARC_TLS_LDO_ADD +@deffnx {} BFD_RELOC_SPARC_TLS_IE_HI22 +@deffnx {} BFD_RELOC_SPARC_TLS_IE_LO10 +@deffnx {} BFD_RELOC_SPARC_TLS_IE_LD +@deffnx {} BFD_RELOC_SPARC_TLS_IE_LDX +@deffnx {} BFD_RELOC_SPARC_TLS_IE_ADD +@deffnx {} BFD_RELOC_SPARC_TLS_LE_HIX22 +@deffnx {} BFD_RELOC_SPARC_TLS_LE_LOX10 +@deffnx {} BFD_RELOC_SPARC_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_SPARC_TLS_DTPMOD64 +@deffnx {} BFD_RELOC_SPARC_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_SPARC_TLS_DTPOFF64 +@deffnx {} BFD_RELOC_SPARC_TLS_TPOFF32 +@deffnx {} BFD_RELOC_SPARC_TLS_TPOFF64 +SPARC TLS relocations. +@end deffn +@deffn {} BFD_RELOC_SPU_IMM7 +@deffnx {} BFD_RELOC_SPU_IMM8 +@deffnx {} BFD_RELOC_SPU_IMM10 +@deffnx {} BFD_RELOC_SPU_IMM10W +@deffnx {} BFD_RELOC_SPU_IMM16 +@deffnx {} BFD_RELOC_SPU_IMM16W +@deffnx {} BFD_RELOC_SPU_IMM18 +@deffnx {} BFD_RELOC_SPU_PCREL9a +@deffnx {} BFD_RELOC_SPU_PCREL9b +@deffnx {} BFD_RELOC_SPU_PCREL16 +@deffnx {} BFD_RELOC_SPU_LO16 +@deffnx {} BFD_RELOC_SPU_HI16 +@deffnx {} BFD_RELOC_SPU_PPU32 +@deffnx {} BFD_RELOC_SPU_PPU64 +@deffnx {} BFD_RELOC_SPU_ADD_PIC +SPU Relocations. +@end deffn +@deffn {} BFD_RELOC_ALPHA_GPDISP_HI16 +Alpha ECOFF and ELF relocations. Some of these treat the symbol or +"addend" in some special way. +For GPDISP_HI16 ("gpdisp") relocations, the symbol is ignored when +writing; when reading, it will be the absolute section symbol. The +addend is the displacement in bytes of the "lda" instruction from +the "ldah" instruction (which is at the address of this reloc). +@end deffn +@deffn {} BFD_RELOC_ALPHA_GPDISP_LO16 +For GPDISP_LO16 ("ignore") relocations, the symbol is handled as +with GPDISP_HI16 relocs. The addend is ignored when writing the +relocations out, and is filled in with the file's GP value on +reading, for convenience. +@end deffn +@deffn {} BFD_RELOC_ALPHA_GPDISP +The ELF GPDISP relocation is exactly the same as the GPDISP_HI16 +relocation except that there is no accompanying GPDISP_LO16 +relocation. +@end deffn +@deffn {} BFD_RELOC_ALPHA_LITERAL +@deffnx {} BFD_RELOC_ALPHA_ELF_LITERAL +@deffnx {} BFD_RELOC_ALPHA_LITUSE +The Alpha LITERAL/LITUSE relocs are produced by a symbol reference; +the assembler turns it into a LDQ instruction to load the address of +the symbol, and then fills in a register in the real instruction. + +The LITERAL reloc, at the LDQ instruction, refers to the .lita +section symbol. The addend is ignored when writing, but is filled +in with the file's GP value on reading, for convenience, as with the +GPDISP_LO16 reloc. + +The ELF_LITERAL reloc is somewhere between 16_GOTOFF and GPDISP_LO16. +It should refer to the symbol to be referenced, as with 16_GOTOFF, +but it generates output not based on the position within the .got +section, but relative to the GP value chosen for the file during the +final link stage. + +The LITUSE reloc, on the instruction using the loaded address, gives +information to the linker that it might be able to use to optimize +away some literal section references. The symbol is ignored (read +as the absolute section symbol), and the "addend" indicates the type +of instruction using the register: +1 - "memory" fmt insn +2 - byte-manipulation (byte offset reg) +3 - jsr (target of branch) +@end deffn +@deffn {} BFD_RELOC_ALPHA_HINT +The HINT relocation indicates a value that should be filled into the +"hint" field of a jmp/jsr/ret instruction, for possible branch- +prediction logic which may be provided on some processors. +@end deffn +@deffn {} BFD_RELOC_ALPHA_LINKAGE +The LINKAGE relocation outputs a linkage pair in the object file, +which is filled by the linker. +@end deffn +@deffn {} BFD_RELOC_ALPHA_CODEADDR +The CODEADDR relocation outputs a STO_CA in the object file, +which is filled by the linker. +@end deffn +@deffn {} BFD_RELOC_ALPHA_GPREL_HI16 +@deffnx {} BFD_RELOC_ALPHA_GPREL_LO16 +The GPREL_HI/LO relocations together form a 32-bit offset from the +GP register. +@end deffn +@deffn {} BFD_RELOC_ALPHA_BRSGP +Like BFD_RELOC_23_PCREL_S2, except that the source and target must +share a common GP, and the target address is adjusted for +STO_ALPHA_STD_GPLOAD. +@end deffn +@deffn {} BFD_RELOC_ALPHA_NOP +The NOP relocation outputs a NOP if the longword displacement +between two procedure entry points is < 2^21. +@end deffn +@deffn {} BFD_RELOC_ALPHA_BSR +The BSR relocation outputs a BSR if the longword displacement +between two procedure entry points is < 2^21. +@end deffn +@deffn {} BFD_RELOC_ALPHA_LDA +The LDA relocation outputs a LDA if the longword displacement +between two procedure entry points is < 2^16. +@end deffn +@deffn {} BFD_RELOC_ALPHA_BOH +The BOH relocation outputs a BSR if the longword displacement +between two procedure entry points is < 2^21, or else a hint. +@end deffn +@deffn {} BFD_RELOC_ALPHA_TLSGD +@deffnx {} BFD_RELOC_ALPHA_TLSLDM +@deffnx {} BFD_RELOC_ALPHA_DTPMOD64 +@deffnx {} BFD_RELOC_ALPHA_GOTDTPREL16 +@deffnx {} BFD_RELOC_ALPHA_DTPREL64 +@deffnx {} BFD_RELOC_ALPHA_DTPREL_HI16 +@deffnx {} BFD_RELOC_ALPHA_DTPREL_LO16 +@deffnx {} BFD_RELOC_ALPHA_DTPREL16 +@deffnx {} BFD_RELOC_ALPHA_GOTTPREL16 +@deffnx {} BFD_RELOC_ALPHA_TPREL64 +@deffnx {} BFD_RELOC_ALPHA_TPREL_HI16 +@deffnx {} BFD_RELOC_ALPHA_TPREL_LO16 +@deffnx {} BFD_RELOC_ALPHA_TPREL16 +Alpha thread-local storage relocations. +@end deffn +@deffn {} BFD_RELOC_MIPS_JMP +@deffnx {} BFD_RELOC_MICROMIPS_JMP +The MIPS jump instruction. +@end deffn +@deffn {} BFD_RELOC_MIPS16_JMP +The MIPS16 jump instruction. +@end deffn +@deffn {} BFD_RELOC_MIPS16_GPREL +MIPS16 GP relative reloc. +@end deffn +@deffn {} BFD_RELOC_HI16 +High 16 bits of 32-bit value; simple reloc. +@end deffn +@deffn {} BFD_RELOC_HI16_S +High 16 bits of 32-bit value but the low 16 bits will be sign +extended and added to form the final result. If the low 16 +bits form a negative number, we need to add one to the high value +to compensate for the borrow when the low bits are added. +@end deffn +@deffn {} BFD_RELOC_LO16 +Low 16 bits. +@end deffn +@deffn {} BFD_RELOC_HI16_PCREL +High 16 bits of 32-bit pc-relative value. +@end deffn +@deffn {} BFD_RELOC_HI16_S_PCREL +High 16 bits of 32-bit pc-relative value, adjusted. +@end deffn +@deffn {} BFD_RELOC_LO16_PCREL +Low 16 bits of pc-relative value. +@end deffn +@deffn {} BFD_RELOC_MIPS16_GOT16 +@deffnx {} BFD_RELOC_MIPS16_CALL16 +Equivalent of BFD_RELOC_MIPS_*, but with the MIPS16 layout of +16-bit immediate fields. +@end deffn +@deffn {} BFD_RELOC_MIPS16_HI16 +MIPS16 high 16 bits of 32-bit value. +@end deffn +@deffn {} BFD_RELOC_MIPS16_HI16_S +MIPS16 high 16 bits of 32-bit value but the low 16 bits will be sign +extended and added to form the final result. If the low 16 +bits form a negative number, we need to add one to the high value +to compensate for the borrow when the low bits are added. +@end deffn +@deffn {} BFD_RELOC_MIPS16_LO16 +MIPS16 low 16 bits. +@end deffn +@deffn {} BFD_RELOC_MIPS16_TLS_GD +@deffnx {} BFD_RELOC_MIPS16_TLS_LDM +@deffnx {} BFD_RELOC_MIPS16_TLS_DTPREL_HI16 +@deffnx {} BFD_RELOC_MIPS16_TLS_DTPREL_LO16 +@deffnx {} BFD_RELOC_MIPS16_TLS_GOTTPREL +@deffnx {} BFD_RELOC_MIPS16_TLS_TPREL_HI16 +@deffnx {} BFD_RELOC_MIPS16_TLS_TPREL_LO16 +MIPS16 TLS relocations. +@end deffn +@deffn {} BFD_RELOC_MIPS_LITERAL +@deffnx {} BFD_RELOC_MICROMIPS_LITERAL +Relocation against a MIPS literal section. +@end deffn +@deffn {} BFD_RELOC_MICROMIPS_7_PCREL_S1 +@deffnx {} BFD_RELOC_MICROMIPS_10_PCREL_S1 +@deffnx {} BFD_RELOC_MICROMIPS_16_PCREL_S1 +microMIPS PC-relative relocations. +@end deffn +@deffn {} BFD_RELOC_MIPS16_16_PCREL_S1 +MIPS16 PC-relative relocation. +@end deffn +@deffn {} BFD_RELOC_MIPS_21_PCREL_S2 +@deffnx {} BFD_RELOC_MIPS_26_PCREL_S2 +@deffnx {} BFD_RELOC_MIPS_18_PCREL_S3 +@deffnx {} BFD_RELOC_MIPS_19_PCREL_S2 +MIPS PC-relative relocations. +@end deffn +@deffn {} BFD_RELOC_MICROMIPS_GPREL16 +@deffnx {} BFD_RELOC_MICROMIPS_HI16 +@deffnx {} BFD_RELOC_MICROMIPS_HI16_S +@deffnx {} BFD_RELOC_MICROMIPS_LO16 +microMIPS versions of generic BFD relocs. +@end deffn +@deffn {} BFD_RELOC_MIPS_GOT16 +@deffnx {} BFD_RELOC_MICROMIPS_GOT16 +@deffnx {} BFD_RELOC_MIPS_CALL16 +@deffnx {} BFD_RELOC_MICROMIPS_CALL16 +@deffnx {} BFD_RELOC_MIPS_GOT_HI16 +@deffnx {} BFD_RELOC_MICROMIPS_GOT_HI16 +@deffnx {} BFD_RELOC_MIPS_GOT_LO16 +@deffnx {} BFD_RELOC_MICROMIPS_GOT_LO16 +@deffnx {} BFD_RELOC_MIPS_CALL_HI16 +@deffnx {} BFD_RELOC_MICROMIPS_CALL_HI16 +@deffnx {} BFD_RELOC_MIPS_CALL_LO16 +@deffnx {} BFD_RELOC_MICROMIPS_CALL_LO16 +@deffnx {} BFD_RELOC_MIPS_SUB +@deffnx {} BFD_RELOC_MICROMIPS_SUB +@deffnx {} BFD_RELOC_MIPS_GOT_PAGE +@deffnx {} BFD_RELOC_MICROMIPS_GOT_PAGE +@deffnx {} BFD_RELOC_MIPS_GOT_OFST +@deffnx {} BFD_RELOC_MICROMIPS_GOT_OFST +@deffnx {} BFD_RELOC_MIPS_GOT_DISP +@deffnx {} BFD_RELOC_MICROMIPS_GOT_DISP +@deffnx {} BFD_RELOC_MIPS_SHIFT5 +@deffnx {} BFD_RELOC_MIPS_SHIFT6 +@deffnx {} BFD_RELOC_MIPS_INSERT_A +@deffnx {} BFD_RELOC_MIPS_INSERT_B +@deffnx {} BFD_RELOC_MIPS_DELETE +@deffnx {} BFD_RELOC_MIPS_HIGHEST +@deffnx {} BFD_RELOC_MICROMIPS_HIGHEST +@deffnx {} BFD_RELOC_MIPS_HIGHER +@deffnx {} BFD_RELOC_MICROMIPS_HIGHER +@deffnx {} BFD_RELOC_MIPS_SCN_DISP +@deffnx {} BFD_RELOC_MICROMIPS_SCN_DISP +@deffnx {} BFD_RELOC_MIPS_16 +@deffnx {} BFD_RELOC_MIPS_RELGOT +@deffnx {} BFD_RELOC_MIPS_JALR +@deffnx {} BFD_RELOC_MICROMIPS_JALR +@deffnx {} BFD_RELOC_MIPS_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL32 +@deffnx {} BFD_RELOC_MIPS_TLS_DTPMOD64 +@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL64 +@deffnx {} BFD_RELOC_MIPS_TLS_GD +@deffnx {} BFD_RELOC_MICROMIPS_TLS_GD +@deffnx {} BFD_RELOC_MIPS_TLS_LDM +@deffnx {} BFD_RELOC_MICROMIPS_TLS_LDM +@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL_HI16 +@deffnx {} BFD_RELOC_MICROMIPS_TLS_DTPREL_HI16 +@deffnx {} BFD_RELOC_MIPS_TLS_DTPREL_LO16 +@deffnx {} BFD_RELOC_MICROMIPS_TLS_DTPREL_LO16 +@deffnx {} BFD_RELOC_MIPS_TLS_GOTTPREL +@deffnx {} BFD_RELOC_MICROMIPS_TLS_GOTTPREL +@deffnx {} BFD_RELOC_MIPS_TLS_TPREL32 +@deffnx {} BFD_RELOC_MIPS_TLS_TPREL64 +@deffnx {} BFD_RELOC_MIPS_TLS_TPREL_HI16 +@deffnx {} BFD_RELOC_MICROMIPS_TLS_TPREL_HI16 +@deffnx {} BFD_RELOC_MIPS_TLS_TPREL_LO16 +@deffnx {} BFD_RELOC_MICROMIPS_TLS_TPREL_LO16 +@deffnx {} BFD_RELOC_MIPS_EH +MIPS ELF relocations. +@end deffn +@deffn {} BFD_RELOC_MIPS_COPY +@deffnx {} BFD_RELOC_MIPS_JUMP_SLOT +MIPS ELF relocations (VxWorks and PLT extensions). +@end deffn +@deffn {} BFD_RELOC_MOXIE_10_PCREL +Moxie ELF relocations. +@end deffn +@deffn {} BFD_RELOC_FT32_10 +@deffnx {} BFD_RELOC_FT32_20 +@deffnx {} BFD_RELOC_FT32_17 +@deffnx {} BFD_RELOC_FT32_18 +@deffnx {} BFD_RELOC_FT32_RELAX +@deffnx {} BFD_RELOC_FT32_SC0 +@deffnx {} BFD_RELOC_FT32_SC1 +@deffnx {} BFD_RELOC_FT32_15 +@deffnx {} BFD_RELOC_FT32_DIFF32 +FT32 ELF relocations. +@end deffn +@deffn {} BFD_RELOC_FRV_LABEL16 +@deffnx {} BFD_RELOC_FRV_LABEL24 +@deffnx {} BFD_RELOC_FRV_LO16 +@deffnx {} BFD_RELOC_FRV_HI16 +@deffnx {} BFD_RELOC_FRV_GPREL12 +@deffnx {} BFD_RELOC_FRV_GPRELU12 +@deffnx {} BFD_RELOC_FRV_GPREL32 +@deffnx {} BFD_RELOC_FRV_GPRELHI +@deffnx {} BFD_RELOC_FRV_GPRELLO +@deffnx {} BFD_RELOC_FRV_GOT12 +@deffnx {} BFD_RELOC_FRV_GOTHI +@deffnx {} BFD_RELOC_FRV_GOTLO +@deffnx {} BFD_RELOC_FRV_FUNCDESC +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOT12 +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTHI +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTLO +@deffnx {} BFD_RELOC_FRV_FUNCDESC_VALUE +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFF12 +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFFHI +@deffnx {} BFD_RELOC_FRV_FUNCDESC_GOTOFFLO +@deffnx {} BFD_RELOC_FRV_GOTOFF12 +@deffnx {} BFD_RELOC_FRV_GOTOFFHI +@deffnx {} BFD_RELOC_FRV_GOTOFFLO +@deffnx {} BFD_RELOC_FRV_GETTLSOFF +@deffnx {} BFD_RELOC_FRV_TLSDESC_VALUE +@deffnx {} BFD_RELOC_FRV_GOTTLSDESC12 +@deffnx {} BFD_RELOC_FRV_GOTTLSDESCHI +@deffnx {} BFD_RELOC_FRV_GOTTLSDESCLO +@deffnx {} BFD_RELOC_FRV_TLSMOFF12 +@deffnx {} BFD_RELOC_FRV_TLSMOFFHI +@deffnx {} BFD_RELOC_FRV_TLSMOFFLO +@deffnx {} BFD_RELOC_FRV_GOTTLSOFF12 +@deffnx {} BFD_RELOC_FRV_GOTTLSOFFHI +@deffnx {} BFD_RELOC_FRV_GOTTLSOFFLO +@deffnx {} BFD_RELOC_FRV_TLSOFF +@deffnx {} BFD_RELOC_FRV_TLSDESC_RELAX +@deffnx {} BFD_RELOC_FRV_GETTLSOFF_RELAX +@deffnx {} BFD_RELOC_FRV_TLSOFF_RELAX +@deffnx {} BFD_RELOC_FRV_TLSMOFF +Fujitsu Frv Relocations. +@end deffn +@deffn {} BFD_RELOC_MN10300_GOTOFF24 +This is a 24bit GOT-relative reloc for the mn10300. +@end deffn +@deffn {} BFD_RELOC_MN10300_GOT32 +This is a 32bit GOT-relative reloc for the mn10300, offset by two +bytes in the instruction. +@end deffn +@deffn {} BFD_RELOC_MN10300_GOT24 +This is a 24bit GOT-relative reloc for the mn10300, offset by two +bytes in the instruction. +@end deffn +@deffn {} BFD_RELOC_MN10300_GOT16 +This is a 16bit GOT-relative reloc for the mn10300, offset by two +bytes in the instruction. +@end deffn +@deffn {} BFD_RELOC_MN10300_COPY +Copy symbol at runtime. +@end deffn +@deffn {} BFD_RELOC_MN10300_GLOB_DAT +Create GOT entry. +@end deffn +@deffn {} BFD_RELOC_MN10300_JMP_SLOT +Create PLT entry. +@end deffn +@deffn {} BFD_RELOC_MN10300_RELATIVE +Adjust by program base. +@end deffn +@deffn {} BFD_RELOC_MN10300_SYM_DIFF +Together with another reloc targeted at the same location, allows +for a value that is the difference of two symbols in the same +section. +@end deffn +@deffn {} BFD_RELOC_MN10300_ALIGN +The addend of this reloc is an alignment power that must be honoured +at the offset's location, regardless of linker relaxation. +@end deffn +@deffn {} BFD_RELOC_MN10300_TLS_GD +@deffnx {} BFD_RELOC_MN10300_TLS_LD +@deffnx {} BFD_RELOC_MN10300_TLS_LDO +@deffnx {} BFD_RELOC_MN10300_TLS_GOTIE +@deffnx {} BFD_RELOC_MN10300_TLS_IE +@deffnx {} BFD_RELOC_MN10300_TLS_LE +@deffnx {} BFD_RELOC_MN10300_TLS_DTPMOD +@deffnx {} BFD_RELOC_MN10300_TLS_DTPOFF +@deffnx {} BFD_RELOC_MN10300_TLS_TPOFF +Various TLS-related relocations. +@end deffn +@deffn {} BFD_RELOC_MN10300_32_PCREL +This is a 32bit pcrel reloc for the mn10300, offset by two bytes in +the instruction. +@end deffn +@deffn {} BFD_RELOC_MN10300_16_PCREL +This is a 16bit pcrel reloc for the mn10300, offset by two bytes in +the instruction. +@end deffn +@deffn {} BFD_RELOC_386_GOT32 +@deffnx {} BFD_RELOC_386_PLT32 +@deffnx {} BFD_RELOC_386_COPY +@deffnx {} BFD_RELOC_386_GLOB_DAT +@deffnx {} BFD_RELOC_386_JUMP_SLOT +@deffnx {} BFD_RELOC_386_RELATIVE +@deffnx {} BFD_RELOC_386_GOTOFF +@deffnx {} BFD_RELOC_386_GOTPC +@deffnx {} BFD_RELOC_386_TLS_TPOFF +@deffnx {} BFD_RELOC_386_TLS_IE +@deffnx {} BFD_RELOC_386_TLS_GOTIE +@deffnx {} BFD_RELOC_386_TLS_LE +@deffnx {} BFD_RELOC_386_TLS_GD +@deffnx {} BFD_RELOC_386_TLS_LDM +@deffnx {} BFD_RELOC_386_TLS_LDO_32 +@deffnx {} BFD_RELOC_386_TLS_IE_32 +@deffnx {} BFD_RELOC_386_TLS_LE_32 +@deffnx {} BFD_RELOC_386_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_386_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_386_TLS_TPOFF32 +@deffnx {} BFD_RELOC_386_TLS_GOTDESC +@deffnx {} BFD_RELOC_386_TLS_DESC_CALL +@deffnx {} BFD_RELOC_386_TLS_DESC +@deffnx {} BFD_RELOC_386_IRELATIVE +@deffnx {} BFD_RELOC_386_GOT32X +i386/elf relocations. +@end deffn +@deffn {} BFD_RELOC_X86_64_GOT32 +@deffnx {} BFD_RELOC_X86_64_PLT32 +@deffnx {} BFD_RELOC_X86_64_COPY +@deffnx {} BFD_RELOC_X86_64_GLOB_DAT +@deffnx {} BFD_RELOC_X86_64_JUMP_SLOT +@deffnx {} BFD_RELOC_X86_64_RELATIVE +@deffnx {} BFD_RELOC_X86_64_GOTPCREL +@deffnx {} BFD_RELOC_X86_64_32S +@deffnx {} BFD_RELOC_X86_64_DTPMOD64 +@deffnx {} BFD_RELOC_X86_64_DTPOFF64 +@deffnx {} BFD_RELOC_X86_64_TPOFF64 +@deffnx {} BFD_RELOC_X86_64_TLSGD +@deffnx {} BFD_RELOC_X86_64_TLSLD +@deffnx {} BFD_RELOC_X86_64_DTPOFF32 +@deffnx {} BFD_RELOC_X86_64_GOTTPOFF +@deffnx {} BFD_RELOC_X86_64_TPOFF32 +@deffnx {} BFD_RELOC_X86_64_GOTOFF64 +@deffnx {} BFD_RELOC_X86_64_GOTPC32 +@deffnx {} BFD_RELOC_X86_64_GOT64 +@deffnx {} BFD_RELOC_X86_64_GOTPCREL64 +@deffnx {} BFD_RELOC_X86_64_GOTPC64 +@deffnx {} BFD_RELOC_X86_64_GOTPLT64 +@deffnx {} BFD_RELOC_X86_64_PLTOFF64 +@deffnx {} BFD_RELOC_X86_64_GOTPC32_TLSDESC +@deffnx {} BFD_RELOC_X86_64_TLSDESC_CALL +@deffnx {} BFD_RELOC_X86_64_TLSDESC +@deffnx {} BFD_RELOC_X86_64_IRELATIVE +@deffnx {} BFD_RELOC_X86_64_PC32_BND +@deffnx {} BFD_RELOC_X86_64_PLT32_BND +@deffnx {} BFD_RELOC_X86_64_GOTPCRELX +@deffnx {} BFD_RELOC_X86_64_REX_GOTPCRELX +@deffnx {} BFD_RELOC_X86_64_CODE_4_GOTPCRELX +@deffnx {} BFD_RELOC_X86_64_CODE_4_GOTTPOFF +@deffnx {} BFD_RELOC_X86_64_CODE_4_GOTPC32_TLSDESC +@deffnx {} BFD_RELOC_X86_64_CODE_5_GOTPCRELX +@deffnx {} BFD_RELOC_X86_64_CODE_5_GOTTPOFF +@deffnx {} BFD_RELOC_X86_64_CODE_5_GOTPC32_TLSDESC +@deffnx {} BFD_RELOC_X86_64_CODE_6_GOTPCRELX +@deffnx {} BFD_RELOC_X86_64_CODE_6_GOTTPOFF +@deffnx {} BFD_RELOC_X86_64_CODE_6_GOTPC32_TLSDESC +x86-64/elf relocations. +@end deffn +@deffn {} BFD_RELOC_NS32K_IMM_8 +@deffnx {} BFD_RELOC_NS32K_IMM_16 +@deffnx {} BFD_RELOC_NS32K_IMM_32 +@deffnx {} BFD_RELOC_NS32K_IMM_8_PCREL +@deffnx {} BFD_RELOC_NS32K_IMM_16_PCREL +@deffnx {} BFD_RELOC_NS32K_IMM_32_PCREL +@deffnx {} BFD_RELOC_NS32K_DISP_8 +@deffnx {} BFD_RELOC_NS32K_DISP_16 +@deffnx {} BFD_RELOC_NS32K_DISP_32 +@deffnx {} BFD_RELOC_NS32K_DISP_8_PCREL +@deffnx {} BFD_RELOC_NS32K_DISP_16_PCREL +@deffnx {} BFD_RELOC_NS32K_DISP_32_PCREL +ns32k relocations. +@end deffn +@deffn {} BFD_RELOC_PDP11_DISP_8_PCREL +@deffnx {} BFD_RELOC_PDP11_DISP_6_PCREL +PDP11 relocations. +@end deffn +@deffn {} BFD_RELOC_PJ_CODE_HI16 +@deffnx {} BFD_RELOC_PJ_CODE_LO16 +@deffnx {} BFD_RELOC_PJ_CODE_DIR16 +@deffnx {} BFD_RELOC_PJ_CODE_DIR32 +@deffnx {} BFD_RELOC_PJ_CODE_REL16 +@deffnx {} BFD_RELOC_PJ_CODE_REL32 +Picojava relocs. Not all of these appear in object files. +@end deffn +@deffn {} BFD_RELOC_PPC_B26 +@deffnx {} BFD_RELOC_PPC_BA26 +@deffnx {} BFD_RELOC_PPC_TOC16 +@deffnx {} BFD_RELOC_PPC_TOC16_LO +@deffnx {} BFD_RELOC_PPC_TOC16_HI +@deffnx {} BFD_RELOC_PPC_B16 +@deffnx {} BFD_RELOC_PPC_B16_BRTAKEN +@deffnx {} BFD_RELOC_PPC_B16_BRNTAKEN +@deffnx {} BFD_RELOC_PPC_BA16 +@deffnx {} BFD_RELOC_PPC_BA16_BRTAKEN +@deffnx {} BFD_RELOC_PPC_BA16_BRNTAKEN +@deffnx {} BFD_RELOC_PPC_COPY +@deffnx {} BFD_RELOC_PPC_GLOB_DAT +@deffnx {} BFD_RELOC_PPC_JMP_SLOT +@deffnx {} BFD_RELOC_PPC_RELATIVE +@deffnx {} BFD_RELOC_PPC_LOCAL24PC +@deffnx {} BFD_RELOC_PPC_EMB_NADDR32 +@deffnx {} BFD_RELOC_PPC_EMB_NADDR16 +@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_LO +@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HI +@deffnx {} BFD_RELOC_PPC_EMB_NADDR16_HA +@deffnx {} BFD_RELOC_PPC_EMB_SDAI16 +@deffnx {} BFD_RELOC_PPC_EMB_SDA2I16 +@deffnx {} BFD_RELOC_PPC_EMB_SDA2REL +@deffnx {} BFD_RELOC_PPC_EMB_SDA21 +@deffnx {} BFD_RELOC_PPC_EMB_MRKREF +@deffnx {} BFD_RELOC_PPC_EMB_RELSEC16 +@deffnx {} BFD_RELOC_PPC_EMB_RELST_LO +@deffnx {} BFD_RELOC_PPC_EMB_RELST_HI +@deffnx {} BFD_RELOC_PPC_EMB_RELST_HA +@deffnx {} BFD_RELOC_PPC_EMB_BIT_FLD +@deffnx {} BFD_RELOC_PPC_EMB_RELSDA +@deffnx {} BFD_RELOC_PPC_VLE_REL8 +@deffnx {} BFD_RELOC_PPC_VLE_REL15 +@deffnx {} BFD_RELOC_PPC_VLE_REL24 +@deffnx {} BFD_RELOC_PPC_VLE_LO16A +@deffnx {} BFD_RELOC_PPC_VLE_LO16D +@deffnx {} BFD_RELOC_PPC_VLE_HI16A +@deffnx {} BFD_RELOC_PPC_VLE_HI16D +@deffnx {} BFD_RELOC_PPC_VLE_HA16A +@deffnx {} BFD_RELOC_PPC_VLE_HA16D +@deffnx {} BFD_RELOC_PPC_VLE_SDA21 +@deffnx {} BFD_RELOC_PPC_VLE_SDA21_LO +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_LO16A +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_LO16D +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_HI16A +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_HI16D +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_HA16A +@deffnx {} BFD_RELOC_PPC_VLE_SDAREL_HA16D +@deffnx {} BFD_RELOC_PPC_16DX_HA +@deffnx {} BFD_RELOC_PPC_REL16DX_HA +@deffnx {} BFD_RELOC_PPC_NEG +@deffnx {} BFD_RELOC_PPC64_HIGHER +@deffnx {} BFD_RELOC_PPC64_HIGHER_S +@deffnx {} BFD_RELOC_PPC64_HIGHEST +@deffnx {} BFD_RELOC_PPC64_HIGHEST_S +@deffnx {} BFD_RELOC_PPC64_TOC16_LO +@deffnx {} BFD_RELOC_PPC64_TOC16_HI +@deffnx {} BFD_RELOC_PPC64_TOC16_HA +@deffnx {} BFD_RELOC_PPC64_TOC +@deffnx {} BFD_RELOC_PPC64_PLTGOT16 +@deffnx {} BFD_RELOC_PPC64_PLTGOT16_LO +@deffnx {} BFD_RELOC_PPC64_PLTGOT16_HI +@deffnx {} BFD_RELOC_PPC64_PLTGOT16_HA +@deffnx {} BFD_RELOC_PPC64_ADDR16_DS +@deffnx {} BFD_RELOC_PPC64_ADDR16_LO_DS +@deffnx {} BFD_RELOC_PPC64_GOT16_DS +@deffnx {} BFD_RELOC_PPC64_GOT16_LO_DS +@deffnx {} BFD_RELOC_PPC64_PLT16_LO_DS +@deffnx {} BFD_RELOC_PPC64_SECTOFF_DS +@deffnx {} BFD_RELOC_PPC64_SECTOFF_LO_DS +@deffnx {} BFD_RELOC_PPC64_TOC16_DS +@deffnx {} BFD_RELOC_PPC64_TOC16_LO_DS +@deffnx {} BFD_RELOC_PPC64_PLTGOT16_DS +@deffnx {} BFD_RELOC_PPC64_PLTGOT16_LO_DS +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGH +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGHA +@deffnx {} BFD_RELOC_PPC64_REL16_HIGH +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHA +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHER +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHERA +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHEST +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHESTA +@deffnx {} BFD_RELOC_PPC64_ADDR64_LOCAL +@deffnx {} BFD_RELOC_PPC64_ENTRY +@deffnx {} BFD_RELOC_PPC64_REL24_NOTOC +@deffnx {} BFD_RELOC_PPC64_REL24_P9NOTOC +@deffnx {} BFD_RELOC_PPC64_D34 +@deffnx {} BFD_RELOC_PPC64_D34_LO +@deffnx {} BFD_RELOC_PPC64_D34_HI30 +@deffnx {} BFD_RELOC_PPC64_D34_HA30 +@deffnx {} BFD_RELOC_PPC64_PCREL34 +@deffnx {} BFD_RELOC_PPC64_GOT_PCREL34 +@deffnx {} BFD_RELOC_PPC64_PLT_PCREL34 +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGHER34 +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGHERA34 +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGHEST34 +@deffnx {} BFD_RELOC_PPC64_ADDR16_HIGHESTA34 +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHER34 +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHERA34 +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHEST34 +@deffnx {} BFD_RELOC_PPC64_REL16_HIGHESTA34 +@deffnx {} BFD_RELOC_PPC64_D28 +@deffnx {} BFD_RELOC_PPC64_PCREL28 +Power(rs6000) and PowerPC relocations. +@end deffn +@deffn {} BFD_RELOC_PPC_TLS +@deffnx {} BFD_RELOC_PPC_TLSGD +@deffnx {} BFD_RELOC_PPC_TLSLD +@deffnx {} BFD_RELOC_PPC_TLSLE +@deffnx {} BFD_RELOC_PPC_TLSIE +@deffnx {} BFD_RELOC_PPC_TLSM +@deffnx {} BFD_RELOC_PPC_TLSML +@deffnx {} BFD_RELOC_PPC_DTPMOD +@deffnx {} BFD_RELOC_PPC_TPREL16 +@deffnx {} BFD_RELOC_PPC_TPREL16_LO +@deffnx {} BFD_RELOC_PPC_TPREL16_HI +@deffnx {} BFD_RELOC_PPC_TPREL16_HA +@deffnx {} BFD_RELOC_PPC_TPREL +@deffnx {} BFD_RELOC_PPC_DTPREL16 +@deffnx {} BFD_RELOC_PPC_DTPREL16_LO +@deffnx {} BFD_RELOC_PPC_DTPREL16_HI +@deffnx {} BFD_RELOC_PPC_DTPREL16_HA +@deffnx {} BFD_RELOC_PPC_DTPREL +@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16 +@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_LO +@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_HI +@deffnx {} BFD_RELOC_PPC_GOT_TLSGD16_HA +@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16 +@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_LO +@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_HI +@deffnx {} BFD_RELOC_PPC_GOT_TLSLD16_HA +@deffnx {} BFD_RELOC_PPC_GOT_TPREL16 +@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_LO +@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_HI +@deffnx {} BFD_RELOC_PPC_GOT_TPREL16_HA +@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16 +@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_LO +@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_HI +@deffnx {} BFD_RELOC_PPC_GOT_DTPREL16_HA +@deffnx {} BFD_RELOC_PPC64_TLSGD +@deffnx {} BFD_RELOC_PPC64_TLSLD +@deffnx {} BFD_RELOC_PPC64_TLSLE +@deffnx {} BFD_RELOC_PPC64_TLSIE +@deffnx {} BFD_RELOC_PPC64_TLSM +@deffnx {} BFD_RELOC_PPC64_TLSML +@deffnx {} BFD_RELOC_PPC64_TPREL16_DS +@deffnx {} BFD_RELOC_PPC64_TPREL16_LO_DS +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGH +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHA +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHER +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHERA +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHEST +@deffnx {} BFD_RELOC_PPC64_TPREL16_HIGHESTA +@deffnx {} BFD_RELOC_PPC64_DTPREL16_DS +@deffnx {} BFD_RELOC_PPC64_DTPREL16_LO_DS +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGH +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHA +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHER +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHERA +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHEST +@deffnx {} BFD_RELOC_PPC64_DTPREL16_HIGHESTA +@deffnx {} BFD_RELOC_PPC64_TPREL34 +@deffnx {} BFD_RELOC_PPC64_DTPREL34 +@deffnx {} BFD_RELOC_PPC64_GOT_TLSGD_PCREL34 +@deffnx {} BFD_RELOC_PPC64_GOT_TLSLD_PCREL34 +@deffnx {} BFD_RELOC_PPC64_GOT_TPREL_PCREL34 +@deffnx {} BFD_RELOC_PPC64_GOT_DTPREL_PCREL34 +@deffnx {} BFD_RELOC_PPC64_TLS_PCREL +PowerPC and PowerPC64 thread-local storage relocations. +@end deffn +@deffn {} BFD_RELOC_I370_D12 +IBM 370/390 relocations. +@end deffn +@deffn {} BFD_RELOC_CTOR +The type of reloc used to build a constructor table - at the moment +probably a 32 bit wide absolute relocation, but the target can choose. +It generally does map to one of the other relocation types. +@end deffn +@deffn {} BFD_RELOC_ARM_PCREL_BRANCH +ARM 26 bit pc-relative branch. The lowest two bits must be zero and +are not stored in the instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_PCREL_BLX +ARM 26 bit pc-relative branch. The lowest bit must be zero and is +not stored in the instruction. The 2nd lowest bit comes from a 1 bit +field in the instruction. +@end deffn +@deffn {} BFD_RELOC_THUMB_PCREL_BLX +Thumb 22 bit pc-relative branch. The lowest bit must be zero and is +not stored in the instruction. The 2nd lowest bit comes from a 1 bit +field in the instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_PCREL_CALL +ARM 26-bit pc-relative branch for an unconditional BL or BLX +instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_PCREL_JUMP +ARM 26-bit pc-relative branch for B or conditional BL instruction. +@end deffn +@deffn {} BFD_RELOC_THUMB_PCREL_BRANCH5 +ARM 5-bit pc-relative branch for Branch Future instructions. +@end deffn +@deffn {} BFD_RELOC_THUMB_PCREL_BFCSEL +ARM 6-bit pc-relative branch for BFCSEL instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_BF17 +ARM 17-bit pc-relative branch for Branch Future instructions. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_BF13 +ARM 13-bit pc-relative branch for BFCSEL instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_BF19 +ARM 19-bit pc-relative branch for Branch Future Link instruction. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_LOOP12 +ARM 12-bit pc-relative branch for Low Overhead Loop instructions. +@end deffn +@deffn {} BFD_RELOC_THUMB_PCREL_BRANCH7 +@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH9 +@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH12 +@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH20 +@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH23 +@deffnx {} BFD_RELOC_THUMB_PCREL_BRANCH25 +Thumb 7-, 9-, 12-, 20-, 23-, and 25-bit pc-relative branches. +The lowest bit must be zero and is not stored in the instruction. +Note that the corresponding ELF R_ARM_THM_JUMPnn constant has an +"nn" one smaller in all cases. Note further that BRANCH23 +corresponds to R_ARM_THM_CALL. +@end deffn +@deffn {} BFD_RELOC_ARM_OFFSET_IMM +12-bit immediate offset, used in ARM-format ldr and str instructions. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_OFFSET +5-bit immediate offset, used in Thumb-format ldr and str instructions. +@end deffn +@deffn {} BFD_RELOC_ARM_TARGET1 +Pc-relative or absolute relocation depending on target. Used for +entries in .init_array sections. +@end deffn +@deffn {} BFD_RELOC_ARM_ROSEGREL32 +Read-only segment base relative address. +@end deffn +@deffn {} BFD_RELOC_ARM_SBREL32 +Data segment base relative address. +@end deffn +@deffn {} BFD_RELOC_ARM_TARGET2 +This reloc is used for references to RTTI data from exception +handling tables. The actual definition depends on the target. It +may be a pc-relative or some form of GOT-indirect relocation. +@end deffn +@deffn {} BFD_RELOC_ARM_PREL31 +31-bit PC relative address. +@end deffn +@deffn {} BFD_RELOC_ARM_MOVW +@deffnx {} BFD_RELOC_ARM_MOVT +@deffnx {} BFD_RELOC_ARM_MOVW_PCREL +@deffnx {} BFD_RELOC_ARM_MOVT_PCREL +@deffnx {} BFD_RELOC_ARM_THUMB_MOVW +@deffnx {} BFD_RELOC_ARM_THUMB_MOVT +@deffnx {} BFD_RELOC_ARM_THUMB_MOVW_PCREL +@deffnx {} BFD_RELOC_ARM_THUMB_MOVT_PCREL +Low and High halfword relocations for MOVW and MOVT instructions. +@end deffn +@deffn {} BFD_RELOC_ARM_GOTFUNCDESC +@deffnx {} BFD_RELOC_ARM_GOTOFFFUNCDESC +@deffnx {} BFD_RELOC_ARM_FUNCDESC +@deffnx {} BFD_RELOC_ARM_FUNCDESC_VALUE +@deffnx {} BFD_RELOC_ARM_TLS_GD32_FDPIC +@deffnx {} BFD_RELOC_ARM_TLS_LDM32_FDPIC +@deffnx {} BFD_RELOC_ARM_TLS_IE32_FDPIC +ARM FDPIC specific relocations. +@end deffn +@deffn {} BFD_RELOC_ARM_JUMP_SLOT +@deffnx {} BFD_RELOC_ARM_GLOB_DAT +@deffnx {} BFD_RELOC_ARM_GOT32 +@deffnx {} BFD_RELOC_ARM_PLT32 +@deffnx {} BFD_RELOC_ARM_RELATIVE +@deffnx {} BFD_RELOC_ARM_GOTOFF +@deffnx {} BFD_RELOC_ARM_GOTPC +@deffnx {} BFD_RELOC_ARM_GOT_PREL +Relocations for setting up GOTs and PLTs for shared libraries. +@end deffn +@deffn {} BFD_RELOC_ARM_TLS_GD32 +@deffnx {} BFD_RELOC_ARM_TLS_LDO32 +@deffnx {} BFD_RELOC_ARM_TLS_LDM32 +@deffnx {} BFD_RELOC_ARM_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_ARM_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_ARM_TLS_TPOFF32 +@deffnx {} BFD_RELOC_ARM_TLS_IE32 +@deffnx {} BFD_RELOC_ARM_TLS_LE32 +@deffnx {} BFD_RELOC_ARM_TLS_GOTDESC +@deffnx {} BFD_RELOC_ARM_TLS_CALL +@deffnx {} BFD_RELOC_ARM_THM_TLS_CALL +@deffnx {} BFD_RELOC_ARM_TLS_DESCSEQ +@deffnx {} BFD_RELOC_ARM_THM_TLS_DESCSEQ +@deffnx {} BFD_RELOC_ARM_TLS_DESC +ARM thread-local storage relocations. +@end deffn +@deffn {} BFD_RELOC_ARM_ALU_PC_G0_NC +@deffnx {} BFD_RELOC_ARM_ALU_PC_G0 +@deffnx {} BFD_RELOC_ARM_ALU_PC_G1_NC +@deffnx {} BFD_RELOC_ARM_ALU_PC_G1 +@deffnx {} BFD_RELOC_ARM_ALU_PC_G2 +@deffnx {} BFD_RELOC_ARM_LDR_PC_G0 +@deffnx {} BFD_RELOC_ARM_LDR_PC_G1 +@deffnx {} BFD_RELOC_ARM_LDR_PC_G2 +@deffnx {} BFD_RELOC_ARM_LDRS_PC_G0 +@deffnx {} BFD_RELOC_ARM_LDRS_PC_G1 +@deffnx {} BFD_RELOC_ARM_LDRS_PC_G2 +@deffnx {} BFD_RELOC_ARM_LDC_PC_G0 +@deffnx {} BFD_RELOC_ARM_LDC_PC_G1 +@deffnx {} BFD_RELOC_ARM_LDC_PC_G2 +@deffnx {} BFD_RELOC_ARM_ALU_SB_G0_NC +@deffnx {} BFD_RELOC_ARM_ALU_SB_G0 +@deffnx {} BFD_RELOC_ARM_ALU_SB_G1_NC +@deffnx {} BFD_RELOC_ARM_ALU_SB_G1 +@deffnx {} BFD_RELOC_ARM_ALU_SB_G2 +@deffnx {} BFD_RELOC_ARM_LDR_SB_G0 +@deffnx {} BFD_RELOC_ARM_LDR_SB_G1 +@deffnx {} BFD_RELOC_ARM_LDR_SB_G2 +@deffnx {} BFD_RELOC_ARM_LDRS_SB_G0 +@deffnx {} BFD_RELOC_ARM_LDRS_SB_G1 +@deffnx {} BFD_RELOC_ARM_LDRS_SB_G2 +@deffnx {} BFD_RELOC_ARM_LDC_SB_G0 +@deffnx {} BFD_RELOC_ARM_LDC_SB_G1 +@deffnx {} BFD_RELOC_ARM_LDC_SB_G2 +ARM group relocations. +@end deffn +@deffn {} BFD_RELOC_ARM_V4BX +Annotation of BX instructions. +@end deffn +@deffn {} BFD_RELOC_ARM_IRELATIVE +ARM support for STT_GNU_IFUNC. +@end deffn +@deffn {} BFD_RELOC_ARM_THUMB_ALU_ABS_G0_NC +@deffnx {} BFD_RELOC_ARM_THUMB_ALU_ABS_G1_NC +@deffnx {} BFD_RELOC_ARM_THUMB_ALU_ABS_G2_NC +@deffnx {} BFD_RELOC_ARM_THUMB_ALU_ABS_G3_NC +Thumb1 relocations to support execute-only code. +@end deffn +@deffn {} BFD_RELOC_ARM_IMMEDIATE +@deffnx {} BFD_RELOC_ARM_ADRL_IMMEDIATE +@deffnx {} BFD_RELOC_ARM_T32_IMMEDIATE +@deffnx {} BFD_RELOC_ARM_T32_ADD_IMM +@deffnx {} BFD_RELOC_ARM_T32_IMM12 +@deffnx {} BFD_RELOC_ARM_T32_ADD_PC12 +@deffnx {} BFD_RELOC_ARM_SHIFT_IMM +@deffnx {} BFD_RELOC_ARM_SMC +@deffnx {} BFD_RELOC_ARM_HVC +@deffnx {} BFD_RELOC_ARM_SWI +@deffnx {} BFD_RELOC_ARM_MULTI +@deffnx {} BFD_RELOC_ARM_CP_OFF_IMM +@deffnx {} BFD_RELOC_ARM_CP_OFF_IMM_S2 +@deffnx {} BFD_RELOC_ARM_T32_CP_OFF_IMM +@deffnx {} BFD_RELOC_ARM_T32_CP_OFF_IMM_S2 +@deffnx {} BFD_RELOC_ARM_T32_VLDR_VSTR_OFF_IMM +@deffnx {} BFD_RELOC_ARM_ADR_IMM +@deffnx {} BFD_RELOC_ARM_LDR_IMM +@deffnx {} BFD_RELOC_ARM_LITERAL +@deffnx {} BFD_RELOC_ARM_IN_POOL +@deffnx {} BFD_RELOC_ARM_OFFSET_IMM8 +@deffnx {} BFD_RELOC_ARM_T32_OFFSET_U8 +@deffnx {} BFD_RELOC_ARM_T32_OFFSET_IMM +@deffnx {} BFD_RELOC_ARM_HWLITERAL +@deffnx {} BFD_RELOC_ARM_THUMB_ADD +@deffnx {} BFD_RELOC_ARM_THUMB_IMM +@deffnx {} BFD_RELOC_ARM_THUMB_SHIFT +These relocs are only used within the ARM assembler. They are not +(at present) written to any object files. +@end deffn +@deffn {} BFD_RELOC_SH_PCDISP8BY2 +@deffnx {} BFD_RELOC_SH_PCDISP12BY2 +@deffnx {} BFD_RELOC_SH_IMM3 +@deffnx {} BFD_RELOC_SH_IMM3U +@deffnx {} BFD_RELOC_SH_DISP12 +@deffnx {} BFD_RELOC_SH_DISP12BY2 +@deffnx {} BFD_RELOC_SH_DISP12BY4 +@deffnx {} BFD_RELOC_SH_DISP12BY8 +@deffnx {} BFD_RELOC_SH_DISP20 +@deffnx {} BFD_RELOC_SH_DISP20BY8 +@deffnx {} BFD_RELOC_SH_IMM4 +@deffnx {} BFD_RELOC_SH_IMM4BY2 +@deffnx {} BFD_RELOC_SH_IMM4BY4 +@deffnx {} BFD_RELOC_SH_IMM8 +@deffnx {} BFD_RELOC_SH_IMM8BY2 +@deffnx {} BFD_RELOC_SH_IMM8BY4 +@deffnx {} BFD_RELOC_SH_PCRELIMM8BY2 +@deffnx {} BFD_RELOC_SH_PCRELIMM8BY4 +@deffnx {} BFD_RELOC_SH_SWITCH16 +@deffnx {} BFD_RELOC_SH_SWITCH32 +@deffnx {} BFD_RELOC_SH_USES +@deffnx {} BFD_RELOC_SH_COUNT +@deffnx {} BFD_RELOC_SH_ALIGN +@deffnx {} BFD_RELOC_SH_CODE +@deffnx {} BFD_RELOC_SH_DATA +@deffnx {} BFD_RELOC_SH_LABEL +@deffnx {} BFD_RELOC_SH_LOOP_START +@deffnx {} BFD_RELOC_SH_LOOP_END +@deffnx {} BFD_RELOC_SH_COPY +@deffnx {} BFD_RELOC_SH_GLOB_DAT +@deffnx {} BFD_RELOC_SH_JMP_SLOT +@deffnx {} BFD_RELOC_SH_RELATIVE +@deffnx {} BFD_RELOC_SH_GOTPC +@deffnx {} BFD_RELOC_SH_GOT_LOW16 +@deffnx {} BFD_RELOC_SH_GOT_MEDLOW16 +@deffnx {} BFD_RELOC_SH_GOT_MEDHI16 +@deffnx {} BFD_RELOC_SH_GOT_HI16 +@deffnx {} BFD_RELOC_SH_GOTPLT_LOW16 +@deffnx {} BFD_RELOC_SH_GOTPLT_MEDLOW16 +@deffnx {} BFD_RELOC_SH_GOTPLT_MEDHI16 +@deffnx {} BFD_RELOC_SH_GOTPLT_HI16 +@deffnx {} BFD_RELOC_SH_PLT_LOW16 +@deffnx {} BFD_RELOC_SH_PLT_MEDLOW16 +@deffnx {} BFD_RELOC_SH_PLT_MEDHI16 +@deffnx {} BFD_RELOC_SH_PLT_HI16 +@deffnx {} BFD_RELOC_SH_GOTOFF_LOW16 +@deffnx {} BFD_RELOC_SH_GOTOFF_MEDLOW16 +@deffnx {} BFD_RELOC_SH_GOTOFF_MEDHI16 +@deffnx {} BFD_RELOC_SH_GOTOFF_HI16 +@deffnx {} BFD_RELOC_SH_GOTPC_LOW16 +@deffnx {} BFD_RELOC_SH_GOTPC_MEDLOW16 +@deffnx {} BFD_RELOC_SH_GOTPC_MEDHI16 +@deffnx {} BFD_RELOC_SH_GOTPC_HI16 +@deffnx {} BFD_RELOC_SH_COPY64 +@deffnx {} BFD_RELOC_SH_GLOB_DAT64 +@deffnx {} BFD_RELOC_SH_JMP_SLOT64 +@deffnx {} BFD_RELOC_SH_RELATIVE64 +@deffnx {} BFD_RELOC_SH_GOT10BY4 +@deffnx {} BFD_RELOC_SH_GOT10BY8 +@deffnx {} BFD_RELOC_SH_GOTPLT10BY4 +@deffnx {} BFD_RELOC_SH_GOTPLT10BY8 +@deffnx {} BFD_RELOC_SH_GOTPLT32 +@deffnx {} BFD_RELOC_SH_SHMEDIA_CODE +@deffnx {} BFD_RELOC_SH_IMMU5 +@deffnx {} BFD_RELOC_SH_IMMS6 +@deffnx {} BFD_RELOC_SH_IMMS6BY32 +@deffnx {} BFD_RELOC_SH_IMMU6 +@deffnx {} BFD_RELOC_SH_IMMS10 +@deffnx {} BFD_RELOC_SH_IMMS10BY2 +@deffnx {} BFD_RELOC_SH_IMMS10BY4 +@deffnx {} BFD_RELOC_SH_IMMS10BY8 +@deffnx {} BFD_RELOC_SH_IMMS16 +@deffnx {} BFD_RELOC_SH_IMMU16 +@deffnx {} BFD_RELOC_SH_IMM_LOW16 +@deffnx {} BFD_RELOC_SH_IMM_LOW16_PCREL +@deffnx {} BFD_RELOC_SH_IMM_MEDLOW16 +@deffnx {} BFD_RELOC_SH_IMM_MEDLOW16_PCREL +@deffnx {} BFD_RELOC_SH_IMM_MEDHI16 +@deffnx {} BFD_RELOC_SH_IMM_MEDHI16_PCREL +@deffnx {} BFD_RELOC_SH_IMM_HI16 +@deffnx {} BFD_RELOC_SH_IMM_HI16_PCREL +@deffnx {} BFD_RELOC_SH_PT_16 +@deffnx {} BFD_RELOC_SH_TLS_GD_32 +@deffnx {} BFD_RELOC_SH_TLS_LD_32 +@deffnx {} BFD_RELOC_SH_TLS_LDO_32 +@deffnx {} BFD_RELOC_SH_TLS_IE_32 +@deffnx {} BFD_RELOC_SH_TLS_LE_32 +@deffnx {} BFD_RELOC_SH_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_SH_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_SH_TLS_TPOFF32 +@deffnx {} BFD_RELOC_SH_GOT20 +@deffnx {} BFD_RELOC_SH_GOTOFF20 +@deffnx {} BFD_RELOC_SH_GOTFUNCDESC +@deffnx {} BFD_RELOC_SH_GOTFUNCDESC20 +@deffnx {} BFD_RELOC_SH_GOTOFFFUNCDESC +@deffnx {} BFD_RELOC_SH_GOTOFFFUNCDESC20 +@deffnx {} BFD_RELOC_SH_FUNCDESC +Renesas / SuperH SH relocs. Not all of these appear in object files. +@end deffn +@deffn {} BFD_RELOC_ARC_NONE +@deffnx {} BFD_RELOC_ARC_8 +@deffnx {} BFD_RELOC_ARC_16 +@deffnx {} BFD_RELOC_ARC_24 +@deffnx {} BFD_RELOC_ARC_32 +@deffnx {} BFD_RELOC_ARC_N8 +@deffnx {} BFD_RELOC_ARC_N16 +@deffnx {} BFD_RELOC_ARC_N24 +@deffnx {} BFD_RELOC_ARC_N32 +@deffnx {} BFD_RELOC_ARC_SDA +@deffnx {} BFD_RELOC_ARC_SECTOFF +@deffnx {} BFD_RELOC_ARC_S21H_PCREL +@deffnx {} BFD_RELOC_ARC_S21W_PCREL +@deffnx {} BFD_RELOC_ARC_S25H_PCREL +@deffnx {} BFD_RELOC_ARC_S25W_PCREL +@deffnx {} BFD_RELOC_ARC_SDA32 +@deffnx {} BFD_RELOC_ARC_SDA_LDST +@deffnx {} BFD_RELOC_ARC_SDA_LDST1 +@deffnx {} BFD_RELOC_ARC_SDA_LDST2 +@deffnx {} BFD_RELOC_ARC_SDA16_LD +@deffnx {} BFD_RELOC_ARC_SDA16_LD1 +@deffnx {} BFD_RELOC_ARC_SDA16_LD2 +@deffnx {} BFD_RELOC_ARC_S13_PCREL +@deffnx {} BFD_RELOC_ARC_W +@deffnx {} BFD_RELOC_ARC_32_ME +@deffnx {} BFD_RELOC_ARC_32_ME_S +@deffnx {} BFD_RELOC_ARC_N32_ME +@deffnx {} BFD_RELOC_ARC_SECTOFF_ME +@deffnx {} BFD_RELOC_ARC_SDA32_ME +@deffnx {} BFD_RELOC_ARC_W_ME +@deffnx {} BFD_RELOC_AC_SECTOFF_U8 +@deffnx {} BFD_RELOC_AC_SECTOFF_U8_1 +@deffnx {} BFD_RELOC_AC_SECTOFF_U8_2 +@deffnx {} BFD_RELOC_AC_SECTOFF_S9 +@deffnx {} BFD_RELOC_AC_SECTOFF_S9_1 +@deffnx {} BFD_RELOC_AC_SECTOFF_S9_2 +@deffnx {} BFD_RELOC_ARC_SECTOFF_ME_1 +@deffnx {} BFD_RELOC_ARC_SECTOFF_ME_2 +@deffnx {} BFD_RELOC_ARC_SECTOFF_1 +@deffnx {} BFD_RELOC_ARC_SECTOFF_2 +@deffnx {} BFD_RELOC_ARC_SDA_12 +@deffnx {} BFD_RELOC_ARC_SDA16_ST2 +@deffnx {} BFD_RELOC_ARC_32_PCREL +@deffnx {} BFD_RELOC_ARC_PC32 +@deffnx {} BFD_RELOC_ARC_GOT32 +@deffnx {} BFD_RELOC_ARC_GOTPC32 +@deffnx {} BFD_RELOC_ARC_PLT32 +@deffnx {} BFD_RELOC_ARC_COPY +@deffnx {} BFD_RELOC_ARC_GLOB_DAT +@deffnx {} BFD_RELOC_ARC_JMP_SLOT +@deffnx {} BFD_RELOC_ARC_RELATIVE +@deffnx {} BFD_RELOC_ARC_GOTOFF +@deffnx {} BFD_RELOC_ARC_GOTPC +@deffnx {} BFD_RELOC_ARC_S21W_PCREL_PLT +@deffnx {} BFD_RELOC_ARC_S25H_PCREL_PLT +@deffnx {} BFD_RELOC_ARC_TLS_DTPMOD +@deffnx {} BFD_RELOC_ARC_TLS_TPOFF +@deffnx {} BFD_RELOC_ARC_TLS_GD_GOT +@deffnx {} BFD_RELOC_ARC_TLS_GD_LD +@deffnx {} BFD_RELOC_ARC_TLS_GD_CALL +@deffnx {} BFD_RELOC_ARC_TLS_IE_GOT +@deffnx {} BFD_RELOC_ARC_TLS_DTPOFF +@deffnx {} BFD_RELOC_ARC_TLS_DTPOFF_S9 +@deffnx {} BFD_RELOC_ARC_TLS_LE_S9 +@deffnx {} BFD_RELOC_ARC_TLS_LE_32 +@deffnx {} BFD_RELOC_ARC_S25W_PCREL_PLT +@deffnx {} BFD_RELOC_ARC_S21H_PCREL_PLT +@deffnx {} BFD_RELOC_ARC_NPS_CMEM16 +@deffnx {} BFD_RELOC_ARC_JLI_SECTOFF +ARC relocs. +@end deffn +@deffn {} BFD_RELOC_BFIN_16_IMM +ADI Blackfin 16 bit immediate absolute reloc. +@end deffn +@deffn {} BFD_RELOC_BFIN_16_HIGH +ADI Blackfin 16 bit immediate absolute reloc higher 16 bits. +@end deffn +@deffn {} BFD_RELOC_BFIN_4_PCREL +ADI Blackfin 'a' part of LSETUP. +@end deffn +@deffn {} BFD_RELOC_BFIN_5_PCREL +ADI Blackfin. +@end deffn +@deffn {} BFD_RELOC_BFIN_16_LOW +ADI Blackfin 16 bit immediate absolute reloc lower 16 bits. +@end deffn +@deffn {} BFD_RELOC_BFIN_10_PCREL +ADI Blackfin. +@end deffn +@deffn {} BFD_RELOC_BFIN_11_PCREL +ADI Blackfin 'b' part of LSETUP. +@end deffn +@deffn {} BFD_RELOC_BFIN_12_PCREL_JUMP +ADI Blackfin. +@end deffn +@deffn {} BFD_RELOC_BFIN_12_PCREL_JUMP_S +ADI Blackfin Short jump, pcrel. +@end deffn +@deffn {} BFD_RELOC_BFIN_24_PCREL_CALL_X +ADI Blackfin Call.x not implemented. +@end deffn +@deffn {} BFD_RELOC_BFIN_24_PCREL_JUMP_L +ADI Blackfin Long Jump pcrel. +@end deffn +@deffn {} BFD_RELOC_BFIN_GOT17M4 +@deffnx {} BFD_RELOC_BFIN_GOTHI +@deffnx {} BFD_RELOC_BFIN_GOTLO +@deffnx {} BFD_RELOC_BFIN_FUNCDESC +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOT17M4 +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTHI +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTLO +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_VALUE +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFF17M4 +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFFHI +@deffnx {} BFD_RELOC_BFIN_FUNCDESC_GOTOFFLO +@deffnx {} BFD_RELOC_BFIN_GOTOFF17M4 +@deffnx {} BFD_RELOC_BFIN_GOTOFFHI +@deffnx {} BFD_RELOC_BFIN_GOTOFFLO +ADI Blackfin FD-PIC relocations. +@end deffn +@deffn {} BFD_RELOC_BFIN_GOT +ADI Blackfin GOT relocation. +@end deffn +@deffn {} BFD_RELOC_BFIN_PLTPC +ADI Blackfin PLTPC relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_PUSH +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_CONST +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_ADD +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_SUB +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_MULT +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_DIV +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_MOD +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_LSHIFT +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_RSHIFT +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_AND +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_OR +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_XOR +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_LAND +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_LOR +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_LEN +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_NEG +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_COMP +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_PAGE +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_HWPAGE +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_ARELOC_BFIN_ADDR +ADI Blackfin arithmetic relocation. +@end deffn +@deffn {} BFD_RELOC_D10V_10_PCREL_R +Mitsubishi D10V relocs. +This is a 10-bit reloc with the right 2 bits assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_D10V_10_PCREL_L +Mitsubishi D10V relocs. +This is a 10-bit reloc with the right 2 bits assumed to be 0. This +is the same as the previous reloc except it is in the left +container, i.e., shifted left 15 bits. +@end deffn +@deffn {} BFD_RELOC_D10V_18 +This is an 18-bit reloc with the right 2 bits assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_D10V_18_PCREL +This is an 18-bit reloc with the right 2 bits assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_6 +Mitsubishi D30V relocs. +This is a 6-bit absolute reloc. +@end deffn +@deffn {} BFD_RELOC_D30V_9_PCREL +This is a 6-bit pc-relative reloc with the right 3 bits assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_9_PCREL_R +This is a 6-bit pc-relative reloc with the right 3 bits assumed to +be 0. Same as the previous reloc but on the right side of the +container. +@end deffn +@deffn {} BFD_RELOC_D30V_15 +This is a 12-bit absolute reloc with the right 3 bitsassumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_15_PCREL +This is a 12-bit pc-relative reloc with the right 3 bits assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_15_PCREL_R +This is a 12-bit pc-relative reloc with the right 3 bits assumed to +be 0. Same as the previous reloc but on the right side of the +container. +@end deffn +@deffn {} BFD_RELOC_D30V_21 +This is an 18-bit absolute reloc with the right 3 bits assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_21_PCREL +This is an 18-bit pc-relative reloc with the right 3 bits assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_D30V_21_PCREL_R +This is an 18-bit pc-relative reloc with the right 3 bits assumed to +be 0. Same as the previous reloc but on the right side of the +container. +@end deffn +@deffn {} BFD_RELOC_D30V_32 +This is a 32-bit absolute reloc. +@end deffn +@deffn {} BFD_RELOC_D30V_32_PCREL +This is a 32-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_DLX_HI16_S +@deffnx {} BFD_RELOC_DLX_LO16 +@deffnx {} BFD_RELOC_DLX_JMP26 +DLX relocs. +@end deffn +@deffn {} BFD_RELOC_M32C_HI8 +@deffnx {} BFD_RELOC_M32C_RL_JUMP +@deffnx {} BFD_RELOC_M32C_RL_1ADDR +@deffnx {} BFD_RELOC_M32C_RL_2ADDR +Renesas M16C/M32C Relocations. +@end deffn +@deffn {} BFD_RELOC_M32R_24 +Renesas M32R (formerly Mitsubishi M32R) relocs. +This is a 24 bit absolute address. +@end deffn +@deffn {} BFD_RELOC_M32R_10_PCREL +This is a 10-bit pc-relative reloc with the right 2 bits assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_M32R_18_PCREL +This is an 18-bit reloc with the right 2 bits assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_M32R_26_PCREL +This is a 26-bit reloc with the right 2 bits assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_M32R_HI16_ULO +This is a 16-bit reloc containing the high 16 bits of an address +used when the lower 16 bits are treated as unsigned. +@end deffn +@deffn {} BFD_RELOC_M32R_HI16_SLO +This is a 16-bit reloc containing the high 16 bits of an address +used when the lower 16 bits are treated as signed. +@end deffn +@deffn {} BFD_RELOC_M32R_LO16 +This is a 16-bit reloc containing the lower 16 bits of an address. +@end deffn +@deffn {} BFD_RELOC_M32R_SDA16 +This is a 16-bit reloc containing the small data area offset for use +in add3, load, and store instructions. +@end deffn +@deffn {} BFD_RELOC_M32R_GOT24 +@deffnx {} BFD_RELOC_M32R_26_PLTREL +@deffnx {} BFD_RELOC_M32R_COPY +@deffnx {} BFD_RELOC_M32R_GLOB_DAT +@deffnx {} BFD_RELOC_M32R_JMP_SLOT +@deffnx {} BFD_RELOC_M32R_RELATIVE +@deffnx {} BFD_RELOC_M32R_GOTOFF +@deffnx {} BFD_RELOC_M32R_GOTOFF_HI_ULO +@deffnx {} BFD_RELOC_M32R_GOTOFF_HI_SLO +@deffnx {} BFD_RELOC_M32R_GOTOFF_LO +@deffnx {} BFD_RELOC_M32R_GOTPC24 +@deffnx {} BFD_RELOC_M32R_GOT16_HI_ULO +@deffnx {} BFD_RELOC_M32R_GOT16_HI_SLO +@deffnx {} BFD_RELOC_M32R_GOT16_LO +@deffnx {} BFD_RELOC_M32R_GOTPC_HI_ULO +@deffnx {} BFD_RELOC_M32R_GOTPC_HI_SLO +@deffnx {} BFD_RELOC_M32R_GOTPC_LO +For PIC. +@end deffn +@deffn {} BFD_RELOC_NDS32_20 +NDS32 relocs. +This is a 20 bit absolute address. +@end deffn +@deffn {} BFD_RELOC_NDS32_9_PCREL +This is a 9-bit pc-relative reloc with the right 1 bit assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_WORD_9_PCREL +This is a 9-bit pc-relative reloc with the right 1 bit assumed to +be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_15_PCREL +This is an 15-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_17_PCREL +This is an 17-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_25_PCREL +This is a 25-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_HI20 +This is a 20-bit reloc containing the high 20 bits of an address +used with the lower 12 bits. +@end deffn +@deffn {} BFD_RELOC_NDS32_LO12S3 +This is a 12-bit reloc containing the lower 12 bits of an address +then shift right by 3. This is used with ldi,sdi. +@end deffn +@deffn {} BFD_RELOC_NDS32_LO12S2 +This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 2. This is used with lwi,swi. +@end deffn +@deffn {} BFD_RELOC_NDS32_LO12S1 +This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 1. This is used with lhi,shi. +@end deffn +@deffn {} BFD_RELOC_NDS32_LO12S0 +This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 0. This is used with lbisbi. +@end deffn +@deffn {} BFD_RELOC_NDS32_LO12S0_ORI +This is a 12-bit reloc containing the lower 12 bits of an address +then shift left by 0. This is only used with branch relaxations. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA15S3 +This is a 15-bit reloc containing the small data area 18-bit signed +offset and shift left by 3 for use in ldi, sdi. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA15S2 +This is a 15-bit reloc containing the small data area 17-bit signed +offset and shift left by 2 for use in lwi, swi. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA15S1 +This is a 15-bit reloc containing the small data area 16-bit signed +offset and shift left by 1 for use in lhi, shi. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA15S0 +This is a 15-bit reloc containing the small data area 15-bit signed +offset and shift left by 0 for use in lbi, sbi. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA16S3 +This is a 16-bit reloc containing the small data area 16-bit signed +offset and shift left by 3. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA17S2 +This is a 17-bit reloc containing the small data area 17-bit signed +offset and shift left by 2 for use in lwi.gp, swi.gp. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA18S1 +This is a 18-bit reloc containing the small data area 18-bit signed +offset and shift left by 1 for use in lhi.gp, shi.gp. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA19S0 +This is a 19-bit reloc containing the small data area 19-bit signed +offset and shift left by 0 for use in lbi.gp, sbi.gp. +@end deffn +@deffn {} BFD_RELOC_NDS32_GOT20 +@deffnx {} BFD_RELOC_NDS32_9_PLTREL +@deffnx {} BFD_RELOC_NDS32_25_PLTREL +@deffnx {} BFD_RELOC_NDS32_COPY +@deffnx {} BFD_RELOC_NDS32_GLOB_DAT +@deffnx {} BFD_RELOC_NDS32_JMP_SLOT +@deffnx {} BFD_RELOC_NDS32_RELATIVE +@deffnx {} BFD_RELOC_NDS32_GOTOFF +@deffnx {} BFD_RELOC_NDS32_GOTOFF_HI20 +@deffnx {} BFD_RELOC_NDS32_GOTOFF_LO12 +@deffnx {} BFD_RELOC_NDS32_GOTPC20 +@deffnx {} BFD_RELOC_NDS32_GOT_HI20 +@deffnx {} BFD_RELOC_NDS32_GOT_LO12 +@deffnx {} BFD_RELOC_NDS32_GOTPC_HI20 +@deffnx {} BFD_RELOC_NDS32_GOTPC_LO12 +For PIC. +@end deffn +@deffn {} BFD_RELOC_NDS32_INSN16 +@deffnx {} BFD_RELOC_NDS32_LABEL +@deffnx {} BFD_RELOC_NDS32_LONGCALL1 +@deffnx {} BFD_RELOC_NDS32_LONGCALL2 +@deffnx {} BFD_RELOC_NDS32_LONGCALL3 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP1 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP2 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP3 +@deffnx {} BFD_RELOC_NDS32_LOADSTORE +@deffnx {} BFD_RELOC_NDS32_9_FIXED +@deffnx {} BFD_RELOC_NDS32_15_FIXED +@deffnx {} BFD_RELOC_NDS32_17_FIXED +@deffnx {} BFD_RELOC_NDS32_25_FIXED +@deffnx {} BFD_RELOC_NDS32_LONGCALL4 +@deffnx {} BFD_RELOC_NDS32_LONGCALL5 +@deffnx {} BFD_RELOC_NDS32_LONGCALL6 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP4 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP5 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP6 +@deffnx {} BFD_RELOC_NDS32_LONGJUMP7 +For relax. +@end deffn +@deffn {} BFD_RELOC_NDS32_PLTREL_HI20 +@deffnx {} BFD_RELOC_NDS32_PLTREL_LO12 +@deffnx {} BFD_RELOC_NDS32_PLT_GOTREL_HI20 +@deffnx {} BFD_RELOC_NDS32_PLT_GOTREL_LO12 +For PIC. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA12S2_DP +@deffnx {} BFD_RELOC_NDS32_SDA12S2_SP +@deffnx {} BFD_RELOC_NDS32_LO12S2_DP +@deffnx {} BFD_RELOC_NDS32_LO12S2_SP +For floating point. +@end deffn +@deffn {} BFD_RELOC_NDS32_DWARF2_OP1 +@deffnx {} BFD_RELOC_NDS32_DWARF2_OP2 +@deffnx {} BFD_RELOC_NDS32_DWARF2_LEB +For dwarf2 debug_line. +@end deffn +@deffn {} BFD_RELOC_NDS32_UPDATE_TA +For eliminating 16-bit instructions. +@end deffn +@deffn {} BFD_RELOC_NDS32_PLT_GOTREL_LO20 +@deffnx {} BFD_RELOC_NDS32_PLT_GOTREL_LO15 +@deffnx {} BFD_RELOC_NDS32_PLT_GOTREL_LO19 +@deffnx {} BFD_RELOC_NDS32_GOT_LO15 +@deffnx {} BFD_RELOC_NDS32_GOT_LO19 +@deffnx {} BFD_RELOC_NDS32_GOTOFF_LO15 +@deffnx {} BFD_RELOC_NDS32_GOTOFF_LO19 +@deffnx {} BFD_RELOC_NDS32_GOT15S2 +@deffnx {} BFD_RELOC_NDS32_GOT17S2 +For PIC object relaxation. +@end deffn +@deffn {} BFD_RELOC_NDS32_5 +NDS32 relocs. +This is a 5 bit absolute address. +@end deffn +@deffn {} BFD_RELOC_NDS32_10_UPCREL +This is a 10-bit unsigned pc-relative reloc with the right 1 bit +assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_NDS32_SDA_FP7U2_RELA +If fp were omitted, fp can used as another gp. +@end deffn +@deffn {} BFD_RELOC_NDS32_RELAX_ENTRY +@deffnx {} BFD_RELOC_NDS32_GOT_SUFF +@deffnx {} BFD_RELOC_NDS32_GOTOFF_SUFF +@deffnx {} BFD_RELOC_NDS32_PLT_GOT_SUFF +@deffnx {} BFD_RELOC_NDS32_MULCALL_SUFF +@deffnx {} BFD_RELOC_NDS32_PTR +@deffnx {} BFD_RELOC_NDS32_PTR_COUNT +@deffnx {} BFD_RELOC_NDS32_PTR_RESOLVED +@deffnx {} BFD_RELOC_NDS32_PLTBLOCK +@deffnx {} BFD_RELOC_NDS32_RELAX_REGION_BEGIN +@deffnx {} BFD_RELOC_NDS32_RELAX_REGION_END +@deffnx {} BFD_RELOC_NDS32_MINUEND +@deffnx {} BFD_RELOC_NDS32_SUBTRAHEND +@deffnx {} BFD_RELOC_NDS32_DIFF8 +@deffnx {} BFD_RELOC_NDS32_DIFF16 +@deffnx {} BFD_RELOC_NDS32_DIFF32 +@deffnx {} BFD_RELOC_NDS32_DIFF_ULEB128 +@deffnx {} BFD_RELOC_NDS32_EMPTY +Relaxation relative relocation types. +@end deffn +@deffn {} BFD_RELOC_NDS32_25_ABS +This is a 25 bit absolute address. +@end deffn +@deffn {} BFD_RELOC_NDS32_DATA +@deffnx {} BFD_RELOC_NDS32_TRAN +@deffnx {} BFD_RELOC_NDS32_17IFC_PCREL +@deffnx {} BFD_RELOC_NDS32_10IFCU_PCREL +For ex9 and ifc using. +@end deffn +@deffn {} BFD_RELOC_NDS32_TPOFF +@deffnx {} BFD_RELOC_NDS32_GOTTPOFF +@deffnx {} BFD_RELOC_NDS32_TLS_LE_HI20 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_LO12 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_20 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_15S0 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_15S1 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_15S2 +@deffnx {} BFD_RELOC_NDS32_TLS_LE_ADD +@deffnx {} BFD_RELOC_NDS32_TLS_LE_LS +@deffnx {} BFD_RELOC_NDS32_TLS_IE_HI20 +@deffnx {} BFD_RELOC_NDS32_TLS_IE_LO12 +@deffnx {} BFD_RELOC_NDS32_TLS_IE_LO12S2 +@deffnx {} BFD_RELOC_NDS32_TLS_IEGP_HI20 +@deffnx {} BFD_RELOC_NDS32_TLS_IEGP_LO12 +@deffnx {} BFD_RELOC_NDS32_TLS_IEGP_LO12S2 +@deffnx {} BFD_RELOC_NDS32_TLS_IEGP_LW +@deffnx {} BFD_RELOC_NDS32_TLS_DESC +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_HI20 +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_LO12 +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_20 +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_SDA17S2 +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_ADD +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_FUNC +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_CALL +@deffnx {} BFD_RELOC_NDS32_TLS_DESC_MEM +@deffnx {} BFD_RELOC_NDS32_REMOVE +@deffnx {} BFD_RELOC_NDS32_GROUP +For TLS. +@end deffn +@deffn {} BFD_RELOC_NDS32_LSI +For floating load store relaxation. +@end deffn +@deffn {} BFD_RELOC_V850_9_PCREL +This is a 9-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_22_PCREL +This is a 22-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_SDA_16_16_OFFSET +This is a 16 bit offset from the short data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_SDA_15_16_OFFSET +This is a 16 bit offset (of which only 15 bits are used) from the +short data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_ZDA_16_16_OFFSET +This is a 16 bit offset from the zero data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_ZDA_15_16_OFFSET +This is a 16 bit offset (of which only 15 bits are used) from the +zero data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_6_8_OFFSET +This is an 8 bit offset (of which only 6 bits are used) from the +tiny data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_7_8_OFFSET +This is an 8bit offset (of which only 7 bits are used) from the tiny +data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_7_7_OFFSET +This is a 7 bit offset from the tiny data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_16_16_OFFSET +This is a 16 bit offset from the tiny data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_4_5_OFFSET +This is a 5 bit offset (of which only 4 bits are used) from the tiny +data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_TDA_4_4_OFFSET +This is a 4 bit offset from the tiny data area pointer. +@end deffn +@deffn {} BFD_RELOC_V850_SDA_16_16_SPLIT_OFFSET +This is a 16 bit offset from the short data area pointer, with the +bits placed non-contiguously in the instruction. +@end deffn +@deffn {} BFD_RELOC_V850_ZDA_16_16_SPLIT_OFFSET +This is a 16 bit offset from the zero data area pointer, with the +bits placed non-contiguously in the instruction. +@end deffn +@deffn {} BFD_RELOC_V850_CALLT_6_7_OFFSET +This is a 6 bit offset from the call table base pointer. +@end deffn +@deffn {} BFD_RELOC_V850_CALLT_16_16_OFFSET +This is a 16 bit offset from the call table base pointer. +@end deffn +@deffn {} BFD_RELOC_V850_LONGCALL +Used for relaxing indirect function calls. +@end deffn +@deffn {} BFD_RELOC_V850_LONGJUMP +Used for relaxing indirect jumps. +@end deffn +@deffn {} BFD_RELOC_V850_ALIGN +Used to maintain alignment whilst relaxing. +@end deffn +@deffn {} BFD_RELOC_V850_LO16_SPLIT_OFFSET +This is a variation of BFD_RELOC_LO16 that can be used in v850e +ld.bu instructions. +@end deffn +@deffn {} BFD_RELOC_V850_16_PCREL +This is a 16-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_17_PCREL +This is a 17-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_23 +This is a 23-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_32_PCREL +This is a 32-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_32_ABS +This is a 32-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_16_SPLIT_OFFSET +This is a 16-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_16_S1 +This is a 16-bit reloc. +@end deffn +@deffn {} BFD_RELOC_V850_LO16_S1 +Low 16 bits. 16 bit shifted by 1. +@end deffn +@deffn {} BFD_RELOC_V850_CALLT_15_16_OFFSET +This is a 16 bit offset from the call table base pointer. +@end deffn +@deffn {} BFD_RELOC_V850_32_GOTPCREL +@deffnx {} BFD_RELOC_V850_16_GOT +@deffnx {} BFD_RELOC_V850_32_GOT +@deffnx {} BFD_RELOC_V850_22_PLT_PCREL +@deffnx {} BFD_RELOC_V850_32_PLT_PCREL +@deffnx {} BFD_RELOC_V850_COPY +@deffnx {} BFD_RELOC_V850_GLOB_DAT +@deffnx {} BFD_RELOC_V850_JMP_SLOT +@deffnx {} BFD_RELOC_V850_RELATIVE +@deffnx {} BFD_RELOC_V850_16_GOTOFF +@deffnx {} BFD_RELOC_V850_32_GOTOFF +DSO relocations. +@end deffn +@deffn {} BFD_RELOC_V850_CODE +Start code. +@end deffn +@deffn {} BFD_RELOC_V850_DATA +Start data in text. +@end deffn +@deffn {} BFD_RELOC_TIC30_LDP +This is a 8bit DP reloc for the tms320c30, where the most +significant 8 bits of a 24 bit word are placed into the least +significant 8 bits of the opcode. +@end deffn +@deffn {} BFD_RELOC_TIC54X_PARTLS7 +This is a 7bit reloc for the tms320c54x, where the least +significant 7 bits of a 16 bit word are placed into the least +significant 7 bits of the opcode. +@end deffn +@deffn {} BFD_RELOC_TIC54X_PARTMS9 +This is a 9bit DP reloc for the tms320c54x, where the most +significant 9 bits of a 16 bit word are placed into the least +significant 9 bits of the opcode. +@end deffn +@deffn {} BFD_RELOC_TIC54X_23 +This is an extended address 23-bit reloc for the tms320c54x. +@end deffn +@deffn {} BFD_RELOC_TIC54X_16_OF_23 +This is a 16-bit reloc for the tms320c54x, where the least +significant 16 bits of a 23-bit extended address are placed into +the opcode. +@end deffn +@deffn {} BFD_RELOC_TIC54X_MS7_OF_23 +This is a reloc for the tms320c54x, where the most +significant 7 bits of a 23-bit extended address are placed into +the opcode. +@end deffn +@deffn {} BFD_RELOC_C6000_PCR_S21 +@deffnx {} BFD_RELOC_C6000_PCR_S12 +@deffnx {} BFD_RELOC_C6000_PCR_S10 +@deffnx {} BFD_RELOC_C6000_PCR_S7 +@deffnx {} BFD_RELOC_C6000_ABS_S16 +@deffnx {} BFD_RELOC_C6000_ABS_L16 +@deffnx {} BFD_RELOC_C6000_ABS_H16 +@deffnx {} BFD_RELOC_C6000_SBR_U15_B +@deffnx {} BFD_RELOC_C6000_SBR_U15_H +@deffnx {} BFD_RELOC_C6000_SBR_U15_W +@deffnx {} BFD_RELOC_C6000_SBR_S16 +@deffnx {} BFD_RELOC_C6000_SBR_L16_B +@deffnx {} BFD_RELOC_C6000_SBR_L16_H +@deffnx {} BFD_RELOC_C6000_SBR_L16_W +@deffnx {} BFD_RELOC_C6000_SBR_H16_B +@deffnx {} BFD_RELOC_C6000_SBR_H16_H +@deffnx {} BFD_RELOC_C6000_SBR_H16_W +@deffnx {} BFD_RELOC_C6000_SBR_GOT_U15_W +@deffnx {} BFD_RELOC_C6000_SBR_GOT_L16_W +@deffnx {} BFD_RELOC_C6000_SBR_GOT_H16_W +@deffnx {} BFD_RELOC_C6000_DSBT_INDEX +@deffnx {} BFD_RELOC_C6000_PREL31 +@deffnx {} BFD_RELOC_C6000_COPY +@deffnx {} BFD_RELOC_C6000_JUMP_SLOT +@deffnx {} BFD_RELOC_C6000_EHTYPE +@deffnx {} BFD_RELOC_C6000_PCR_H16 +@deffnx {} BFD_RELOC_C6000_PCR_L16 +@deffnx {} BFD_RELOC_C6000_ALIGN +@deffnx {} BFD_RELOC_C6000_FPHEAD +@deffnx {} BFD_RELOC_C6000_NOCMP +TMS320C6000 relocations. +@end deffn +@deffn {} BFD_RELOC_FR30_48 +This is a 48 bit reloc for the FR30 that stores 32 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_20 +This is a 32 bit reloc for the FR30 that stores 20 bits split up +into two sections. +@end deffn +@deffn {} BFD_RELOC_FR30_6_IN_4 +This is a 16 bit reloc for the FR30 that stores a 6 bit word offset +in 4 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_8_IN_8 +This is a 16 bit reloc for the FR30 that stores an 8 bit byte offset +into 8 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_9_IN_8 +This is a 16 bit reloc for the FR30 that stores a 9 bit short offset +into 8 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_10_IN_8 +This is a 16 bit reloc for the FR30 that stores a 10 bit word offset +into 8 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_9_PCREL +This is a 16 bit reloc for the FR30 that stores a 9 bit pc relative +short offset into 8 bits. +@end deffn +@deffn {} BFD_RELOC_FR30_12_PCREL +This is a 16 bit reloc for the FR30 that stores a 12 bit pc relative +short offset into 11 bits. +@end deffn +@deffn {} BFD_RELOC_MCORE_PCREL_IMM8BY4 +@deffnx {} BFD_RELOC_MCORE_PCREL_IMM11BY2 +@deffnx {} BFD_RELOC_MCORE_PCREL_IMM4BY2 +@deffnx {} BFD_RELOC_MCORE_PCREL_32 +@deffnx {} BFD_RELOC_MCORE_PCREL_JSR_IMM11BY2 +@deffnx {} BFD_RELOC_MCORE_RVA +Motorola Mcore relocations. +@end deffn +@deffn {} BFD_RELOC_MEP_8 +@deffnx {} BFD_RELOC_MEP_16 +@deffnx {} BFD_RELOC_MEP_32 +@deffnx {} BFD_RELOC_MEP_PCREL8A2 +@deffnx {} BFD_RELOC_MEP_PCREL12A2 +@deffnx {} BFD_RELOC_MEP_PCREL17A2 +@deffnx {} BFD_RELOC_MEP_PCREL24A2 +@deffnx {} BFD_RELOC_MEP_PCABS24A2 +@deffnx {} BFD_RELOC_MEP_LOW16 +@deffnx {} BFD_RELOC_MEP_HI16U +@deffnx {} BFD_RELOC_MEP_HI16S +@deffnx {} BFD_RELOC_MEP_GPREL +@deffnx {} BFD_RELOC_MEP_TPREL +@deffnx {} BFD_RELOC_MEP_TPREL7 +@deffnx {} BFD_RELOC_MEP_TPREL7A2 +@deffnx {} BFD_RELOC_MEP_TPREL7A4 +@deffnx {} BFD_RELOC_MEP_UIMM24 +@deffnx {} BFD_RELOC_MEP_ADDR24A4 +@deffnx {} BFD_RELOC_MEP_GNU_VTINHERIT +@deffnx {} BFD_RELOC_MEP_GNU_VTENTRY +Toshiba Media Processor Relocations. +@end deffn +@deffn {} BFD_RELOC_METAG_HIADDR16 +@deffnx {} BFD_RELOC_METAG_LOADDR16 +@deffnx {} BFD_RELOC_METAG_RELBRANCH +@deffnx {} BFD_RELOC_METAG_GETSETOFF +@deffnx {} BFD_RELOC_METAG_HIOG +@deffnx {} BFD_RELOC_METAG_LOOG +@deffnx {} BFD_RELOC_METAG_REL8 +@deffnx {} BFD_RELOC_METAG_REL16 +@deffnx {} BFD_RELOC_METAG_HI16_GOTOFF +@deffnx {} BFD_RELOC_METAG_LO16_GOTOFF +@deffnx {} BFD_RELOC_METAG_GETSET_GOTOFF +@deffnx {} BFD_RELOC_METAG_GETSET_GOT +@deffnx {} BFD_RELOC_METAG_HI16_GOTPC +@deffnx {} BFD_RELOC_METAG_LO16_GOTPC +@deffnx {} BFD_RELOC_METAG_HI16_PLT +@deffnx {} BFD_RELOC_METAG_LO16_PLT +@deffnx {} BFD_RELOC_METAG_RELBRANCH_PLT +@deffnx {} BFD_RELOC_METAG_GOTOFF +@deffnx {} BFD_RELOC_METAG_PLT +@deffnx {} BFD_RELOC_METAG_COPY +@deffnx {} BFD_RELOC_METAG_JMP_SLOT +@deffnx {} BFD_RELOC_METAG_RELATIVE +@deffnx {} BFD_RELOC_METAG_GLOB_DAT +@deffnx {} BFD_RELOC_METAG_TLS_GD +@deffnx {} BFD_RELOC_METAG_TLS_LDM +@deffnx {} BFD_RELOC_METAG_TLS_LDO_HI16 +@deffnx {} BFD_RELOC_METAG_TLS_LDO_LO16 +@deffnx {} BFD_RELOC_METAG_TLS_LDO +@deffnx {} BFD_RELOC_METAG_TLS_IE +@deffnx {} BFD_RELOC_METAG_TLS_IENONPIC +@deffnx {} BFD_RELOC_METAG_TLS_IENONPIC_HI16 +@deffnx {} BFD_RELOC_METAG_TLS_IENONPIC_LO16 +@deffnx {} BFD_RELOC_METAG_TLS_TPOFF +@deffnx {} BFD_RELOC_METAG_TLS_DTPMOD +@deffnx {} BFD_RELOC_METAG_TLS_DTPOFF +@deffnx {} BFD_RELOC_METAG_TLS_LE +@deffnx {} BFD_RELOC_METAG_TLS_LE_HI16 +@deffnx {} BFD_RELOC_METAG_TLS_LE_LO16 +Imagination Technologies Meta relocations. +@end deffn +@deffn {} BFD_RELOC_MMIX_GETA +@deffnx {} BFD_RELOC_MMIX_GETA_1 +@deffnx {} BFD_RELOC_MMIX_GETA_2 +@deffnx {} BFD_RELOC_MMIX_GETA_3 +These are relocations for the GETA instruction. +@end deffn +@deffn {} BFD_RELOC_MMIX_CBRANCH +@deffnx {} BFD_RELOC_MMIX_CBRANCH_J +@deffnx {} BFD_RELOC_MMIX_CBRANCH_1 +@deffnx {} BFD_RELOC_MMIX_CBRANCH_2 +@deffnx {} BFD_RELOC_MMIX_CBRANCH_3 +These are relocations for a conditional branch instruction. +@end deffn +@deffn {} BFD_RELOC_MMIX_PUSHJ +@deffnx {} BFD_RELOC_MMIX_PUSHJ_1 +@deffnx {} BFD_RELOC_MMIX_PUSHJ_2 +@deffnx {} BFD_RELOC_MMIX_PUSHJ_3 +@deffnx {} BFD_RELOC_MMIX_PUSHJ_STUBBABLE +These are relocations for the PUSHJ instruction. +@end deffn +@deffn {} BFD_RELOC_MMIX_JMP +@deffnx {} BFD_RELOC_MMIX_JMP_1 +@deffnx {} BFD_RELOC_MMIX_JMP_2 +@deffnx {} BFD_RELOC_MMIX_JMP_3 +These are relocations for the JMP instruction. +@end deffn +@deffn {} BFD_RELOC_MMIX_ADDR19 +This is a relocation for a relative address as in a GETA instruction +or a branch. +@end deffn +@deffn {} BFD_RELOC_MMIX_ADDR27 +This is a relocation for a relative address as in a JMP instruction. +@end deffn +@deffn {} BFD_RELOC_MMIX_REG_OR_BYTE +This is a relocation for an instruction field that may be a general +register or a value 0..255. +@end deffn +@deffn {} BFD_RELOC_MMIX_REG +This is a relocation for an instruction field that may be a general +register. +@end deffn +@deffn {} BFD_RELOC_MMIX_BASE_PLUS_OFFSET +This is a relocation for two instruction fields holding a register +and an offset, the equivalent of the relocation. +@end deffn +@deffn {} BFD_RELOC_MMIX_LOCAL +This relocation is an assertion that the expression is not allocated +as a global register. It does not modify contents. +@end deffn +@deffn {} BFD_RELOC_AVR_7_PCREL +This is a 16 bit reloc for the AVR that stores 8 bit pc relative +short offset into 7 bits. +@end deffn +@deffn {} BFD_RELOC_AVR_13_PCREL +This is a 16 bit reloc for the AVR that stores 13 bit pc relative +short offset into 12 bits. +@end deffn +@deffn {} BFD_RELOC_AVR_16_PM +This is a 16 bit reloc for the AVR that stores 17 bit value (usually +program memory address) into 16 bits. +@end deffn +@deffn {} BFD_RELOC_AVR_LO8_LDI +This is a 16 bit reloc for the AVR that stores 8 bit value (usually +data memory address) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HI8_LDI +This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of data memory address) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HH8_LDI +This is a 16 bit reloc for the AVR that stores 8 bit value (most +high 8 bit of program memory address) into 8 bit immediate value of +LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_MS8_LDI +This is a 16 bit reloc for the AVR that stores 8 bit value (most +high 8 bit of 32 bit value) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_LO8_LDI_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(usually data memory address) into 8 bit immediate value of SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HI8_LDI_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 8 bit of data memory address) into 8 bit immediate value of +SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HH8_LDI_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(most high 8 bit of program memory address) into 8 bit immediate +value of LDI or SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_MS8_LDI_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(msb of 32 bit value) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_LO8_LDI_PM +This is a 16 bit reloc for the AVR that stores 8 bit value (usually +command address) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_LO8_LDI_GS +This is a 16 bit reloc for the AVR that stores 8 bit value +(command address) into 8 bit immediate value of LDI insn. If the +address is beyond the 128k boundary, the linker inserts a jump stub +for this reloc in the lower 128k. +@end deffn +@deffn {} BFD_RELOC_AVR_HI8_LDI_PM +This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of command address) into 8 bit immediate value of LDI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HI8_LDI_GS +This is a 16 bit reloc for the AVR that stores 8 bit value (high 8 bit +of command address) into 8 bit immediate value of LDI insn. If the +address is beyond the 128k boundary, the linker inserts a jump stub +for this reloc below 128k. +@end deffn +@deffn {} BFD_RELOC_AVR_HH8_LDI_PM +This is a 16 bit reloc for the AVR that stores 8 bit value (most +high 8 bit of command address) into 8 bit immediate value of LDI +insn. +@end deffn +@deffn {} BFD_RELOC_AVR_LO8_LDI_PM_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(usually command address) into 8 bit immediate value of SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HI8_LDI_PM_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 8 bit of 16 bit command address) into 8 bit immediate value +of SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_HH8_LDI_PM_NEG +This is a 16 bit reloc for the AVR that stores negated 8 bit value +(high 6 bit of 22 bit command address) into 8 bit immediate +value of SUBI insn. +@end deffn +@deffn {} BFD_RELOC_AVR_CALL +This is a 32 bit reloc for the AVR that stores 23 bit value +into 22 bits. +@end deffn +@deffn {} BFD_RELOC_AVR_LDI +This is a 16 bit reloc for the AVR that stores all needed bits +for absolute addressing with ldi with overflow check to linktime. +@end deffn +@deffn {} BFD_RELOC_AVR_6 +This is a 6 bit reloc for the AVR that stores offset for ldd/std +instructions. +@end deffn +@deffn {} BFD_RELOC_AVR_6_ADIW +This is a 6 bit reloc for the AVR that stores offset for adiw/sbiw +instructions. +@end deffn +@deffn {} BFD_RELOC_AVR_8_LO +This is a 8 bit reloc for the AVR that stores bits 0..7 of a symbol +in .byte lo8(symbol). +@end deffn +@deffn {} BFD_RELOC_AVR_8_HI +This is a 8 bit reloc for the AVR that stores bits 8..15 of a symbol +in .byte hi8(symbol). +@end deffn +@deffn {} BFD_RELOC_AVR_8_HLO +This is a 8 bit reloc for the AVR that stores bits 16..23 of a symbol +in .byte hlo8(symbol). +@end deffn +@deffn {} BFD_RELOC_AVR_DIFF8 +@deffnx {} BFD_RELOC_AVR_DIFF16 +@deffnx {} BFD_RELOC_AVR_DIFF32 +AVR relocations to mark the difference of two local symbols. +These are only needed to support linker relaxation and can be ignored +when not relaxing. The field is set to the value of the difference +assuming no relaxation. The relocation encodes the position of the +second symbol so the linker can determine whether to adjust the field +value. +@end deffn +@deffn {} BFD_RELOC_AVR_LDS_STS_16 +This is a 7 bit reloc for the AVR that stores SRAM address for 16bit +lds and sts instructions supported only tiny core. +@end deffn +@deffn {} BFD_RELOC_AVR_PORT6 +This is a 6 bit reloc for the AVR that stores an I/O register +number for the IN and OUT instructions. +@end deffn +@deffn {} BFD_RELOC_AVR_PORT5 +This is a 5 bit reloc for the AVR that stores an I/O register +number for the SBIC, SBIS, SBI and CBI instructions. +@end deffn +@deffn {} BFD_RELOC_RISCV_HI20 +@deffnx {} BFD_RELOC_RISCV_PCREL_HI20 +@deffnx {} BFD_RELOC_RISCV_PCREL_LO12_I +@deffnx {} BFD_RELOC_RISCV_PCREL_LO12_S +@deffnx {} BFD_RELOC_RISCV_LO12_I +@deffnx {} BFD_RELOC_RISCV_LO12_S +@deffnx {} BFD_RELOC_RISCV_GPREL12_I +@deffnx {} BFD_RELOC_RISCV_GPREL12_S +@deffnx {} BFD_RELOC_RISCV_TPREL_HI20 +@deffnx {} BFD_RELOC_RISCV_TPREL_LO12_I +@deffnx {} BFD_RELOC_RISCV_TPREL_LO12_S +@deffnx {} BFD_RELOC_RISCV_TPREL_ADD +@deffnx {} BFD_RELOC_RISCV_CALL +@deffnx {} BFD_RELOC_RISCV_CALL_PLT +@deffnx {} BFD_RELOC_RISCV_ADD8 +@deffnx {} BFD_RELOC_RISCV_ADD16 +@deffnx {} BFD_RELOC_RISCV_ADD32 +@deffnx {} BFD_RELOC_RISCV_ADD64 +@deffnx {} BFD_RELOC_RISCV_SUB8 +@deffnx {} BFD_RELOC_RISCV_SUB16 +@deffnx {} BFD_RELOC_RISCV_SUB32 +@deffnx {} BFD_RELOC_RISCV_SUB64 +@deffnx {} BFD_RELOC_RISCV_GOT_HI20 +@deffnx {} BFD_RELOC_RISCV_TLS_GOT_HI20 +@deffnx {} BFD_RELOC_RISCV_TLS_GD_HI20 +@deffnx {} BFD_RELOC_RISCV_JMP +@deffnx {} BFD_RELOC_RISCV_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_RISCV_TLS_DTPREL32 +@deffnx {} BFD_RELOC_RISCV_TLS_DTPMOD64 +@deffnx {} BFD_RELOC_RISCV_TLS_DTPREL64 +@deffnx {} BFD_RELOC_RISCV_TLS_TPREL32 +@deffnx {} BFD_RELOC_RISCV_TLS_TPREL64 +@deffnx {} BFD_RELOC_RISCV_TLSDESC_HI20 +@deffnx {} BFD_RELOC_RISCV_TLSDESC_LOAD_LO12 +@deffnx {} BFD_RELOC_RISCV_TLSDESC_ADD_LO12 +@deffnx {} BFD_RELOC_RISCV_TLSDESC_CALL +@deffnx {} BFD_RELOC_RISCV_ALIGN +@deffnx {} BFD_RELOC_RISCV_RVC_BRANCH +@deffnx {} BFD_RELOC_RISCV_RVC_JUMP +@deffnx {} BFD_RELOC_RISCV_RELAX +@deffnx {} BFD_RELOC_RISCV_CFA +@deffnx {} BFD_RELOC_RISCV_SUB6 +@deffnx {} BFD_RELOC_RISCV_SET6 +@deffnx {} BFD_RELOC_RISCV_SET8 +@deffnx {} BFD_RELOC_RISCV_SET16 +@deffnx {} BFD_RELOC_RISCV_SET32 +@deffnx {} BFD_RELOC_RISCV_32_PCREL +@deffnx {} BFD_RELOC_RISCV_SET_ULEB128 +@deffnx {} BFD_RELOC_RISCV_SUB_ULEB128 +RISC-V relocations. +@end deffn +@deffn {} BFD_RELOC_RL78_NEG8 +@deffnx {} BFD_RELOC_RL78_NEG16 +@deffnx {} BFD_RELOC_RL78_NEG24 +@deffnx {} BFD_RELOC_RL78_NEG32 +@deffnx {} BFD_RELOC_RL78_16_OP +@deffnx {} BFD_RELOC_RL78_24_OP +@deffnx {} BFD_RELOC_RL78_32_OP +@deffnx {} BFD_RELOC_RL78_8U +@deffnx {} BFD_RELOC_RL78_16U +@deffnx {} BFD_RELOC_RL78_24U +@deffnx {} BFD_RELOC_RL78_DIR3U_PCREL +@deffnx {} BFD_RELOC_RL78_DIFF +@deffnx {} BFD_RELOC_RL78_GPRELB +@deffnx {} BFD_RELOC_RL78_GPRELW +@deffnx {} BFD_RELOC_RL78_GPRELL +@deffnx {} BFD_RELOC_RL78_SYM +@deffnx {} BFD_RELOC_RL78_OP_SUBTRACT +@deffnx {} BFD_RELOC_RL78_OP_NEG +@deffnx {} BFD_RELOC_RL78_OP_AND +@deffnx {} BFD_RELOC_RL78_OP_SHRA +@deffnx {} BFD_RELOC_RL78_ABS8 +@deffnx {} BFD_RELOC_RL78_ABS16 +@deffnx {} BFD_RELOC_RL78_ABS16_REV +@deffnx {} BFD_RELOC_RL78_ABS32 +@deffnx {} BFD_RELOC_RL78_ABS32_REV +@deffnx {} BFD_RELOC_RL78_ABS16U +@deffnx {} BFD_RELOC_RL78_ABS16UW +@deffnx {} BFD_RELOC_RL78_ABS16UL +@deffnx {} BFD_RELOC_RL78_RELAX +@deffnx {} BFD_RELOC_RL78_HI16 +@deffnx {} BFD_RELOC_RL78_HI8 +@deffnx {} BFD_RELOC_RL78_LO16 +@deffnx {} BFD_RELOC_RL78_CODE +@deffnx {} BFD_RELOC_RL78_SADDR +Renesas RL78 Relocations. +@end deffn +@deffn {} BFD_RELOC_RX_NEG8 +@deffnx {} BFD_RELOC_RX_NEG16 +@deffnx {} BFD_RELOC_RX_NEG24 +@deffnx {} BFD_RELOC_RX_NEG32 +@deffnx {} BFD_RELOC_RX_16_OP +@deffnx {} BFD_RELOC_RX_24_OP +@deffnx {} BFD_RELOC_RX_32_OP +@deffnx {} BFD_RELOC_RX_8U +@deffnx {} BFD_RELOC_RX_16U +@deffnx {} BFD_RELOC_RX_24U +@deffnx {} BFD_RELOC_RX_DIR3U_PCREL +@deffnx {} BFD_RELOC_RX_DIFF +@deffnx {} BFD_RELOC_RX_GPRELB +@deffnx {} BFD_RELOC_RX_GPRELW +@deffnx {} BFD_RELOC_RX_GPRELL +@deffnx {} BFD_RELOC_RX_SYM +@deffnx {} BFD_RELOC_RX_OP_SUBTRACT +@deffnx {} BFD_RELOC_RX_OP_NEG +@deffnx {} BFD_RELOC_RX_ABS8 +@deffnx {} BFD_RELOC_RX_ABS16 +@deffnx {} BFD_RELOC_RX_ABS16_REV +@deffnx {} BFD_RELOC_RX_ABS32 +@deffnx {} BFD_RELOC_RX_ABS32_REV +@deffnx {} BFD_RELOC_RX_ABS16U +@deffnx {} BFD_RELOC_RX_ABS16UW +@deffnx {} BFD_RELOC_RX_ABS16UL +@deffnx {} BFD_RELOC_RX_RELAX +Renesas RX Relocations. +@end deffn +@deffn {} BFD_RELOC_390_12 +Direct 12 bit. +@end deffn +@deffn {} BFD_RELOC_390_GOT12 +12 bit GOT offset. +@end deffn +@deffn {} BFD_RELOC_390_PLT32 +32 bit PC relative PLT address. +@end deffn +@deffn {} BFD_RELOC_390_COPY +Copy symbol at runtime. +@end deffn +@deffn {} BFD_RELOC_390_GLOB_DAT +Create GOT entry. +@end deffn +@deffn {} BFD_RELOC_390_JMP_SLOT +Create PLT entry. +@end deffn +@deffn {} BFD_RELOC_390_RELATIVE +Adjust by program base. +@end deffn +@deffn {} BFD_RELOC_390_GOTPC +32 bit PC relative offset to GOT. +@end deffn +@deffn {} BFD_RELOC_390_GOT16 +16 bit GOT offset. +@end deffn +@deffn {} BFD_RELOC_390_PC12DBL +PC relative 12 bit shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PLT12DBL +12 bit PC rel. PLT shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PC16DBL +PC relative 16 bit shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PLT16DBL +16 bit PC rel. PLT shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PC24DBL +PC relative 24 bit shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PLT24DBL +24 bit PC rel. PLT shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PC32DBL +PC relative 32 bit shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_PLT32DBL +32 bit PC rel. PLT shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_GOTPCDBL +32 bit PC rel. GOT shifted by 1. +@end deffn +@deffn {} BFD_RELOC_390_GOT64 +64 bit GOT offset. +@end deffn +@deffn {} BFD_RELOC_390_PLT64 +64 bit PC relative PLT address. +@end deffn +@deffn {} BFD_RELOC_390_GOTENT +32 bit rel. offset to GOT entry. +@end deffn +@deffn {} BFD_RELOC_390_GOTOFF64 +64 bit offset to GOT. +@end deffn +@deffn {} BFD_RELOC_390_GOTPLT12 +12-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_390_GOTPLT16 +16-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_390_GOTPLT32 +32-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_390_GOTPLT64 +64-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_390_GOTPLTENT +32-bit rel. offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_390_PLTOFF16 +16-bit rel. offset from the GOT to a PLT entry. +@end deffn +@deffn {} BFD_RELOC_390_PLTOFF32 +32-bit rel. offset from the GOT to a PLT entry. +@end deffn +@deffn {} BFD_RELOC_390_PLTOFF64 +64-bit rel. offset from the GOT to a PLT entry. +@end deffn +@deffn {} BFD_RELOC_390_TLS_LOAD +@deffnx {} BFD_RELOC_390_TLS_GDCALL +@deffnx {} BFD_RELOC_390_TLS_LDCALL +@deffnx {} BFD_RELOC_390_TLS_GD32 +@deffnx {} BFD_RELOC_390_TLS_GD64 +@deffnx {} BFD_RELOC_390_TLS_GOTIE12 +@deffnx {} BFD_RELOC_390_TLS_GOTIE32 +@deffnx {} BFD_RELOC_390_TLS_GOTIE64 +@deffnx {} BFD_RELOC_390_TLS_LDM32 +@deffnx {} BFD_RELOC_390_TLS_LDM64 +@deffnx {} BFD_RELOC_390_TLS_IE32 +@deffnx {} BFD_RELOC_390_TLS_IE64 +@deffnx {} BFD_RELOC_390_TLS_IEENT +@deffnx {} BFD_RELOC_390_TLS_LE32 +@deffnx {} BFD_RELOC_390_TLS_LE64 +@deffnx {} BFD_RELOC_390_TLS_LDO32 +@deffnx {} BFD_RELOC_390_TLS_LDO64 +@deffnx {} BFD_RELOC_390_TLS_DTPMOD +@deffnx {} BFD_RELOC_390_TLS_DTPOFF +@deffnx {} BFD_RELOC_390_TLS_TPOFF +s390 tls relocations. +@end deffn +@deffn {} BFD_RELOC_390_20 +@deffnx {} BFD_RELOC_390_GOT20 +@deffnx {} BFD_RELOC_390_GOTPLT20 +@deffnx {} BFD_RELOC_390_TLS_GOTIE20 +Long displacement extension. +@end deffn +@deffn {} BFD_RELOC_390_IRELATIVE +STT_GNU_IFUNC relocation. +@end deffn +@deffn {} BFD_RELOC_SCORE_GPREL15 +Score relocations. +Low 16 bit for load/store. +@end deffn +@deffn {} BFD_RELOC_SCORE_DUMMY2 +@deffnx {} BFD_RELOC_SCORE_JMP +This is a 24-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_SCORE_BRANCH +This is a 19-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_SCORE_IMM30 +This is a 32-bit reloc for 48-bit instructions. +@end deffn +@deffn {} BFD_RELOC_SCORE_IMM32 +This is a 32-bit reloc for 48-bit instructions. +@end deffn +@deffn {} BFD_RELOC_SCORE16_JMP +This is a 11-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_SCORE16_BRANCH +This is a 8-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_SCORE_BCMP +This is a 9-bit reloc with the right 1 bit assumed to be 0. +@end deffn +@deffn {} BFD_RELOC_SCORE_GOT15 +@deffnx {} BFD_RELOC_SCORE_GOT_LO16 +@deffnx {} BFD_RELOC_SCORE_CALL15 +@deffnx {} BFD_RELOC_SCORE_DUMMY_HI16 +Undocumented Score relocs. +@end deffn +@deffn {} BFD_RELOC_IP2K_FR9 +Scenix IP2K - 9-bit register number / data address. +@end deffn +@deffn {} BFD_RELOC_IP2K_BANK +Scenix IP2K - 4-bit register/data bank number. +@end deffn +@deffn {} BFD_RELOC_IP2K_ADDR16CJP +Scenix IP2K - low 13 bits of instruction word address. +@end deffn +@deffn {} BFD_RELOC_IP2K_PAGE3 +Scenix IP2K - high 3 bits of instruction word address. +@end deffn +@deffn {} BFD_RELOC_IP2K_LO8DATA +@deffnx {} BFD_RELOC_IP2K_HI8DATA +@deffnx {} BFD_RELOC_IP2K_EX8DATA +Scenix IP2K - ext/low/high 8 bits of data address. +@end deffn +@deffn {} BFD_RELOC_IP2K_LO8INSN +@deffnx {} BFD_RELOC_IP2K_HI8INSN +Scenix IP2K - low/high 8 bits of instruction word address. +@end deffn +@deffn {} BFD_RELOC_IP2K_PC_SKIP +Scenix IP2K - even/odd PC modifier to modify snb pcl.0. +@end deffn +@deffn {} BFD_RELOC_IP2K_TEXT +Scenix IP2K - 16 bit word address in text section. +@end deffn +@deffn {} BFD_RELOC_IP2K_FR_OFFSET +Scenix IP2K - 7-bit sp or dp offset. +@end deffn +@deffn {} BFD_RELOC_VPE4KMATH_DATA +@deffnx {} BFD_RELOC_VPE4KMATH_INSN +Scenix VPE4K coprocessor - data/insn-space addressing. +@end deffn +@deffn {} BFD_RELOC_VTABLE_INHERIT +@deffnx {} BFD_RELOC_VTABLE_ENTRY +These two relocations are used by the linker to determine which of +the entries in a C++ virtual function table are actually used. When +the --gc-sections option is given, the linker will zero out the +entries that are not used, so that the code for those functions need +not be included in the output. + +VTABLE_INHERIT is a zero-space relocation used to describe to the +linker the inheritance tree of a C++ virtual function table. The +relocation's symbol should be the parent class' vtable, and the +relocation should be located at the child vtable. + +VTABLE_ENTRY is a zero-space relocation that describes the use of a +virtual function table entry. The reloc's symbol should refer to +the table of the class mentioned in the code. Off of that base, an +offset describes the entry that is being used. For Rela hosts, this +offset is stored in the reloc's addend. For Rel hosts, we are +forced to put this offset in the reloc's section offset. +@end deffn +@deffn {} BFD_RELOC_IA64_IMM14 +@deffnx {} BFD_RELOC_IA64_IMM22 +@deffnx {} BFD_RELOC_IA64_IMM64 +@deffnx {} BFD_RELOC_IA64_DIR32MSB +@deffnx {} BFD_RELOC_IA64_DIR32LSB +@deffnx {} BFD_RELOC_IA64_DIR64MSB +@deffnx {} BFD_RELOC_IA64_DIR64LSB +@deffnx {} BFD_RELOC_IA64_GPREL22 +@deffnx {} BFD_RELOC_IA64_GPREL64I +@deffnx {} BFD_RELOC_IA64_GPREL32MSB +@deffnx {} BFD_RELOC_IA64_GPREL32LSB +@deffnx {} BFD_RELOC_IA64_GPREL64MSB +@deffnx {} BFD_RELOC_IA64_GPREL64LSB +@deffnx {} BFD_RELOC_IA64_LTOFF22 +@deffnx {} BFD_RELOC_IA64_LTOFF64I +@deffnx {} BFD_RELOC_IA64_PLTOFF22 +@deffnx {} BFD_RELOC_IA64_PLTOFF64I +@deffnx {} BFD_RELOC_IA64_PLTOFF64MSB +@deffnx {} BFD_RELOC_IA64_PLTOFF64LSB +@deffnx {} BFD_RELOC_IA64_FPTR64I +@deffnx {} BFD_RELOC_IA64_FPTR32MSB +@deffnx {} BFD_RELOC_IA64_FPTR32LSB +@deffnx {} BFD_RELOC_IA64_FPTR64MSB +@deffnx {} BFD_RELOC_IA64_FPTR64LSB +@deffnx {} BFD_RELOC_IA64_PCREL21B +@deffnx {} BFD_RELOC_IA64_PCREL21BI +@deffnx {} BFD_RELOC_IA64_PCREL21M +@deffnx {} BFD_RELOC_IA64_PCREL21F +@deffnx {} BFD_RELOC_IA64_PCREL22 +@deffnx {} BFD_RELOC_IA64_PCREL60B +@deffnx {} BFD_RELOC_IA64_PCREL64I +@deffnx {} BFD_RELOC_IA64_PCREL32MSB +@deffnx {} BFD_RELOC_IA64_PCREL32LSB +@deffnx {} BFD_RELOC_IA64_PCREL64MSB +@deffnx {} BFD_RELOC_IA64_PCREL64LSB +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR22 +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64I +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR32MSB +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR32LSB +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64MSB +@deffnx {} BFD_RELOC_IA64_LTOFF_FPTR64LSB +@deffnx {} BFD_RELOC_IA64_SEGREL32MSB +@deffnx {} BFD_RELOC_IA64_SEGREL32LSB +@deffnx {} BFD_RELOC_IA64_SEGREL64MSB +@deffnx {} BFD_RELOC_IA64_SEGREL64LSB +@deffnx {} BFD_RELOC_IA64_SECREL32MSB +@deffnx {} BFD_RELOC_IA64_SECREL32LSB +@deffnx {} BFD_RELOC_IA64_SECREL64MSB +@deffnx {} BFD_RELOC_IA64_SECREL64LSB +@deffnx {} BFD_RELOC_IA64_REL32MSB +@deffnx {} BFD_RELOC_IA64_REL32LSB +@deffnx {} BFD_RELOC_IA64_REL64MSB +@deffnx {} BFD_RELOC_IA64_REL64LSB +@deffnx {} BFD_RELOC_IA64_LTV32MSB +@deffnx {} BFD_RELOC_IA64_LTV32LSB +@deffnx {} BFD_RELOC_IA64_LTV64MSB +@deffnx {} BFD_RELOC_IA64_LTV64LSB +@deffnx {} BFD_RELOC_IA64_IPLTMSB +@deffnx {} BFD_RELOC_IA64_IPLTLSB +@deffnx {} BFD_RELOC_IA64_COPY +@deffnx {} BFD_RELOC_IA64_LTOFF22X +@deffnx {} BFD_RELOC_IA64_LDXMOV +@deffnx {} BFD_RELOC_IA64_TPREL14 +@deffnx {} BFD_RELOC_IA64_TPREL22 +@deffnx {} BFD_RELOC_IA64_TPREL64I +@deffnx {} BFD_RELOC_IA64_TPREL64MSB +@deffnx {} BFD_RELOC_IA64_TPREL64LSB +@deffnx {} BFD_RELOC_IA64_LTOFF_TPREL22 +@deffnx {} BFD_RELOC_IA64_DTPMOD64MSB +@deffnx {} BFD_RELOC_IA64_DTPMOD64LSB +@deffnx {} BFD_RELOC_IA64_LTOFF_DTPMOD22 +@deffnx {} BFD_RELOC_IA64_DTPREL14 +@deffnx {} BFD_RELOC_IA64_DTPREL22 +@deffnx {} BFD_RELOC_IA64_DTPREL64I +@deffnx {} BFD_RELOC_IA64_DTPREL32MSB +@deffnx {} BFD_RELOC_IA64_DTPREL32LSB +@deffnx {} BFD_RELOC_IA64_DTPREL64MSB +@deffnx {} BFD_RELOC_IA64_DTPREL64LSB +@deffnx {} BFD_RELOC_IA64_LTOFF_DTPREL22 +Intel IA64 Relocations. +@end deffn +@deffn {} BFD_RELOC_M68HC11_HI8 +Motorola 68HC11 reloc. +This is the 8 bit high part of an absolute address. +@end deffn +@deffn {} BFD_RELOC_M68HC11_LO8 +Motorola 68HC11 reloc. +This is the 8 bit low part of an absolute address. +@end deffn +@deffn {} BFD_RELOC_M68HC11_3B +Motorola 68HC11 reloc. +This is the 3 bit of a value. +@end deffn +@deffn {} BFD_RELOC_M68HC11_RL_JUMP +Motorola 68HC11 reloc. +This reloc marks the beginning of a jump/call instruction. +It is used for linker relaxation to correctly identify beginning +of instruction and change some branches to use PC-relative +addressing mode. +@end deffn +@deffn {} BFD_RELOC_M68HC11_RL_GROUP +Motorola 68HC11 reloc. +This reloc marks a group of several instructions that gcc generates +and for which the linker relaxation pass can modify and/or remove +some of them. +@end deffn +@deffn {} BFD_RELOC_M68HC11_LO16 +Motorola 68HC11 reloc. +This is the 16-bit lower part of an address. It is used for 'call' +instruction to specify the symbol address without any special +transformation (due to memory bank window). +@end deffn +@deffn {} BFD_RELOC_M68HC11_PAGE +Motorola 68HC11 reloc. +This is a 8-bit reloc that specifies the page number of an address. +It is used by 'call' instruction to specify the page number of +the symbol. +@end deffn +@deffn {} BFD_RELOC_M68HC11_24 +Motorola 68HC11 reloc. +This is a 24-bit reloc that represents the address with a 16-bit +value and a 8-bit page number. The symbol address is transformed +to follow the 16K memory bank of 68HC12 (seen as mapped in the +window). +@end deffn +@deffn {} BFD_RELOC_M68HC12_5B +Motorola 68HC12 reloc. +This is the 5 bits of a value. +@end deffn +@deffn {} BFD_RELOC_XGATE_RL_JUMP +Freescale XGATE reloc. +This reloc marks the beginning of a bra/jal instruction. +@end deffn +@deffn {} BFD_RELOC_XGATE_RL_GROUP +Freescale XGATE reloc. +This reloc marks a group of several instructions that gcc generates +and for which the linker relaxation pass can modify and/or remove +some of them. +@end deffn +@deffn {} BFD_RELOC_XGATE_LO16 +Freescale XGATE reloc. +This is the 16-bit lower part of an address. It is used for the +'16-bit' instructions. +@end deffn +@deffn {} BFD_RELOC_XGATE_GPAGE +Freescale XGATE reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_24 +Freescale XGATE reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_PCREL_9 +Freescale XGATE reloc. +This is a 9-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_PCREL_10 +Freescale XGATE reloc. +This is a 10-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_IMM8_LO +Freescale XGATE reloc. +This is the 16-bit lower part of an address. It is used for the +'16-bit' instructions. +@end deffn +@deffn {} BFD_RELOC_XGATE_IMM8_HI +Freescale XGATE reloc. +This is the 16-bit higher part of an address. It is used for the +'16-bit' instructions. +@end deffn +@deffn {} BFD_RELOC_XGATE_IMM3 +Freescale XGATE reloc. +This is a 3-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_IMM4 +Freescale XGATE reloc. +This is a 4-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_XGATE_IMM5 +Freescale XGATE reloc. +This is a 5-bit pc-relative reloc. +@end deffn +@deffn {} BFD_RELOC_M68HC12_9B +Motorola 68HC12 reloc. +This is the 9 bits of a value. +@end deffn +@deffn {} BFD_RELOC_M68HC12_16B +Motorola 68HC12 reloc. +This is the 16 bits of a value. +@end deffn +@deffn {} BFD_RELOC_M68HC12_9_PCREL +Motorola 68HC12/XGATE reloc. +This is a PCREL9 branch. +@end deffn +@deffn {} BFD_RELOC_M68HC12_10_PCREL +Motorola 68HC12/XGATE reloc. +This is a PCREL10 branch. +@end deffn +@deffn {} BFD_RELOC_M68HC12_LO8XG +Motorola 68HC12/XGATE reloc. +This is the 8 bit low part of an absolute address and immediately +precedes a matching HI8XG part. +@end deffn +@deffn {} BFD_RELOC_M68HC12_HI8XG +Motorola 68HC12/XGATE reloc. +This is the 8 bit high part of an absolute address and immediately +follows a matching LO8XG part. +@end deffn +@deffn {} BFD_RELOC_S12Z_15_PCREL +Freescale S12Z reloc. +This is a 15 bit relative address. If the most significant bits are +all zero then it may be truncated to 8 bits. +@end deffn +@deffn {} BFD_RELOC_CR16_NUM8 +@deffnx {} BFD_RELOC_CR16_NUM16 +@deffnx {} BFD_RELOC_CR16_NUM32 +@deffnx {} BFD_RELOC_CR16_NUM32a +@deffnx {} BFD_RELOC_CR16_REGREL0 +@deffnx {} BFD_RELOC_CR16_REGREL4 +@deffnx {} BFD_RELOC_CR16_REGREL4a +@deffnx {} BFD_RELOC_CR16_REGREL14 +@deffnx {} BFD_RELOC_CR16_REGREL14a +@deffnx {} BFD_RELOC_CR16_REGREL16 +@deffnx {} BFD_RELOC_CR16_REGREL20 +@deffnx {} BFD_RELOC_CR16_REGREL20a +@deffnx {} BFD_RELOC_CR16_ABS20 +@deffnx {} BFD_RELOC_CR16_ABS24 +@deffnx {} BFD_RELOC_CR16_IMM4 +@deffnx {} BFD_RELOC_CR16_IMM8 +@deffnx {} BFD_RELOC_CR16_IMM16 +@deffnx {} BFD_RELOC_CR16_IMM20 +@deffnx {} BFD_RELOC_CR16_IMM24 +@deffnx {} BFD_RELOC_CR16_IMM32 +@deffnx {} BFD_RELOC_CR16_IMM32a +@deffnx {} BFD_RELOC_CR16_DISP4 +@deffnx {} BFD_RELOC_CR16_DISP8 +@deffnx {} BFD_RELOC_CR16_DISP16 +@deffnx {} BFD_RELOC_CR16_DISP20 +@deffnx {} BFD_RELOC_CR16_DISP24 +@deffnx {} BFD_RELOC_CR16_DISP24a +@deffnx {} BFD_RELOC_CR16_SWITCH8 +@deffnx {} BFD_RELOC_CR16_SWITCH16 +@deffnx {} BFD_RELOC_CR16_SWITCH32 +@deffnx {} BFD_RELOC_CR16_GOT_REGREL20 +@deffnx {} BFD_RELOC_CR16_GOTC_REGREL20 +@deffnx {} BFD_RELOC_CR16_GLOB_DAT +NS CR16 Relocations. +@end deffn +@deffn {} BFD_RELOC_CRX_REL4 +@deffnx {} BFD_RELOC_CRX_REL8 +@deffnx {} BFD_RELOC_CRX_REL8_CMP +@deffnx {} BFD_RELOC_CRX_REL16 +@deffnx {} BFD_RELOC_CRX_REL24 +@deffnx {} BFD_RELOC_CRX_REL32 +@deffnx {} BFD_RELOC_CRX_REGREL12 +@deffnx {} BFD_RELOC_CRX_REGREL22 +@deffnx {} BFD_RELOC_CRX_REGREL28 +@deffnx {} BFD_RELOC_CRX_REGREL32 +@deffnx {} BFD_RELOC_CRX_ABS16 +@deffnx {} BFD_RELOC_CRX_ABS32 +@deffnx {} BFD_RELOC_CRX_NUM8 +@deffnx {} BFD_RELOC_CRX_NUM16 +@deffnx {} BFD_RELOC_CRX_NUM32 +@deffnx {} BFD_RELOC_CRX_IMM16 +@deffnx {} BFD_RELOC_CRX_IMM32 +@deffnx {} BFD_RELOC_CRX_SWITCH8 +@deffnx {} BFD_RELOC_CRX_SWITCH16 +@deffnx {} BFD_RELOC_CRX_SWITCH32 +NS CRX Relocations. +@end deffn +@deffn {} BFD_RELOC_CRIS_BDISP8 +@deffnx {} BFD_RELOC_CRIS_UNSIGNED_5 +@deffnx {} BFD_RELOC_CRIS_SIGNED_6 +@deffnx {} BFD_RELOC_CRIS_UNSIGNED_6 +@deffnx {} BFD_RELOC_CRIS_SIGNED_8 +@deffnx {} BFD_RELOC_CRIS_UNSIGNED_8 +@deffnx {} BFD_RELOC_CRIS_SIGNED_16 +@deffnx {} BFD_RELOC_CRIS_UNSIGNED_16 +@deffnx {} BFD_RELOC_CRIS_LAPCQ_OFFSET +@deffnx {} BFD_RELOC_CRIS_UNSIGNED_4 +These relocs are only used within the CRIS assembler. They are not +(at present) written to any object files. +@end deffn +@deffn {} BFD_RELOC_CRIS_COPY +@deffnx {} BFD_RELOC_CRIS_GLOB_DAT +@deffnx {} BFD_RELOC_CRIS_JUMP_SLOT +@deffnx {} BFD_RELOC_CRIS_RELATIVE +Relocs used in ELF shared libraries for CRIS. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_GOT +32-bit offset to symbol-entry within GOT. +@end deffn +@deffn {} BFD_RELOC_CRIS_16_GOT +16-bit offset to symbol-entry within GOT. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_GOTPLT +32-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_CRIS_16_GOTPLT +16-bit offset to symbol-entry within GOT, with PLT handling. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_GOTREL +32-bit offset to symbol, relative to GOT. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_PLT_GOTREL +32-bit offset to symbol with PLT entry, relative to GOT. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_PLT_PCREL +32-bit offset to symbol with PLT entry, relative to this +relocation. +@end deffn +@deffn {} BFD_RELOC_CRIS_32_GOT_GD +@deffnx {} BFD_RELOC_CRIS_16_GOT_GD +@deffnx {} BFD_RELOC_CRIS_32_GD +@deffnx {} BFD_RELOC_CRIS_DTP +@deffnx {} BFD_RELOC_CRIS_32_DTPREL +@deffnx {} BFD_RELOC_CRIS_16_DTPREL +@deffnx {} BFD_RELOC_CRIS_32_GOT_TPREL +@deffnx {} BFD_RELOC_CRIS_16_GOT_TPREL +@deffnx {} BFD_RELOC_CRIS_32_TPREL +@deffnx {} BFD_RELOC_CRIS_16_TPREL +@deffnx {} BFD_RELOC_CRIS_DTPMOD +@deffnx {} BFD_RELOC_CRIS_32_IE +Relocs used in TLS code for CRIS. +@end deffn +@deffn {} BFD_RELOC_OR1K_REL_26 +@deffnx {} BFD_RELOC_OR1K_SLO16 +@deffnx {} BFD_RELOC_OR1K_PCREL_PG21 +@deffnx {} BFD_RELOC_OR1K_LO13 +@deffnx {} BFD_RELOC_OR1K_SLO13 +@deffnx {} BFD_RELOC_OR1K_GOTPC_HI16 +@deffnx {} BFD_RELOC_OR1K_GOTPC_LO16 +@deffnx {} BFD_RELOC_OR1K_GOT_AHI16 +@deffnx {} BFD_RELOC_OR1K_GOT16 +@deffnx {} BFD_RELOC_OR1K_GOT_PG21 +@deffnx {} BFD_RELOC_OR1K_GOT_LO13 +@deffnx {} BFD_RELOC_OR1K_PLT26 +@deffnx {} BFD_RELOC_OR1K_PLTA26 +@deffnx {} BFD_RELOC_OR1K_GOTOFF_SLO16 +@deffnx {} BFD_RELOC_OR1K_COPY +@deffnx {} BFD_RELOC_OR1K_GLOB_DAT +@deffnx {} BFD_RELOC_OR1K_JMP_SLOT +@deffnx {} BFD_RELOC_OR1K_RELATIVE +@deffnx {} BFD_RELOC_OR1K_TLS_GD_HI16 +@deffnx {} BFD_RELOC_OR1K_TLS_GD_LO16 +@deffnx {} BFD_RELOC_OR1K_TLS_GD_PG21 +@deffnx {} BFD_RELOC_OR1K_TLS_GD_LO13 +@deffnx {} BFD_RELOC_OR1K_TLS_LDM_HI16 +@deffnx {} BFD_RELOC_OR1K_TLS_LDM_LO16 +@deffnx {} BFD_RELOC_OR1K_TLS_LDM_PG21 +@deffnx {} BFD_RELOC_OR1K_TLS_LDM_LO13 +@deffnx {} BFD_RELOC_OR1K_TLS_LDO_HI16 +@deffnx {} BFD_RELOC_OR1K_TLS_LDO_LO16 +@deffnx {} BFD_RELOC_OR1K_TLS_IE_HI16 +@deffnx {} BFD_RELOC_OR1K_TLS_IE_AHI16 +@deffnx {} BFD_RELOC_OR1K_TLS_IE_LO16 +@deffnx {} BFD_RELOC_OR1K_TLS_IE_PG21 +@deffnx {} BFD_RELOC_OR1K_TLS_IE_LO13 +@deffnx {} BFD_RELOC_OR1K_TLS_LE_HI16 +@deffnx {} BFD_RELOC_OR1K_TLS_LE_AHI16 +@deffnx {} BFD_RELOC_OR1K_TLS_LE_LO16 +@deffnx {} BFD_RELOC_OR1K_TLS_LE_SLO16 +@deffnx {} BFD_RELOC_OR1K_TLS_TPOFF +@deffnx {} BFD_RELOC_OR1K_TLS_DTPOFF +@deffnx {} BFD_RELOC_OR1K_TLS_DTPMOD +OpenRISC 1000 Relocations. +@end deffn +@deffn {} BFD_RELOC_H8_DIR16A8 +@deffnx {} BFD_RELOC_H8_DIR16R8 +@deffnx {} BFD_RELOC_H8_DIR24A8 +@deffnx {} BFD_RELOC_H8_DIR24R8 +@deffnx {} BFD_RELOC_H8_DIR32A16 +@deffnx {} BFD_RELOC_H8_DISP32A16 +H8 elf Relocations. +@end deffn +@deffn {} BFD_RELOC_XSTORMY16_REL_12 +@deffnx {} BFD_RELOC_XSTORMY16_12 +@deffnx {} BFD_RELOC_XSTORMY16_24 +@deffnx {} BFD_RELOC_XSTORMY16_FPTR16 +Sony Xstormy16 Relocations. +@end deffn +@deffn {} BFD_RELOC_RELC +Self-describing complex relocations. +@end deffn +@deffn {} BFD_RELOC_VAX_GLOB_DAT +@deffnx {} BFD_RELOC_VAX_JMP_SLOT +@deffnx {} BFD_RELOC_VAX_RELATIVE +Relocations used by VAX ELF. +@end deffn +@deffn {} BFD_RELOC_MT_PC16 +Morpho MT - 16 bit immediate relocation. +@end deffn +@deffn {} BFD_RELOC_MT_HI16 +Morpho MT - Hi 16 bits of an address. +@end deffn +@deffn {} BFD_RELOC_MT_LO16 +Morpho MT - Low 16 bits of an address. +@end deffn +@deffn {} BFD_RELOC_MT_GNU_VTINHERIT +Morpho MT - Used to tell the linker which vtable entries are used. +@end deffn +@deffn {} BFD_RELOC_MT_GNU_VTENTRY +Morpho MT - Used to tell the linker which vtable entries are used. +@end deffn +@deffn {} BFD_RELOC_MT_PCINSN8 +Morpho MT - 8 bit immediate relocation. +@end deffn +@deffn {} BFD_RELOC_MSP430_10_PCREL +@deffnx {} BFD_RELOC_MSP430_16_PCREL +@deffnx {} BFD_RELOC_MSP430_16 +@deffnx {} BFD_RELOC_MSP430_16_PCREL_BYTE +@deffnx {} BFD_RELOC_MSP430_16_BYTE +@deffnx {} BFD_RELOC_MSP430_2X_PCREL +@deffnx {} BFD_RELOC_MSP430_RL_PCREL +@deffnx {} BFD_RELOC_MSP430_ABS8 +@deffnx {} BFD_RELOC_MSP430X_PCR20_EXT_SRC +@deffnx {} BFD_RELOC_MSP430X_PCR20_EXT_DST +@deffnx {} BFD_RELOC_MSP430X_PCR20_EXT_ODST +@deffnx {} BFD_RELOC_MSP430X_ABS20_EXT_SRC +@deffnx {} BFD_RELOC_MSP430X_ABS20_EXT_DST +@deffnx {} BFD_RELOC_MSP430X_ABS20_EXT_ODST +@deffnx {} BFD_RELOC_MSP430X_ABS20_ADR_SRC +@deffnx {} BFD_RELOC_MSP430X_ABS20_ADR_DST +@deffnx {} BFD_RELOC_MSP430X_PCR16 +@deffnx {} BFD_RELOC_MSP430X_PCR20_CALL +@deffnx {} BFD_RELOC_MSP430X_ABS16 +@deffnx {} BFD_RELOC_MSP430_ABS_HI16 +@deffnx {} BFD_RELOC_MSP430_PREL31 +@deffnx {} BFD_RELOC_MSP430_SYM_DIFF +@deffnx {} BFD_RELOC_MSP430_SET_ULEB128 +@deffnx {} BFD_RELOC_MSP430_SUB_ULEB128 +msp430 specific relocation codes. +@end deffn +@deffn {} BFD_RELOC_PRU_U16 +PRU LDI 16-bit unsigned data-memory relocation. +@end deffn +@deffn {} BFD_RELOC_PRU_U16_PMEMIMM +PRU LDI 16-bit unsigned instruction-memory relocation. +@end deffn +@deffn {} BFD_RELOC_PRU_LDI32 +PRU relocation for two consecutive LDI load instructions that load a +32 bit value into a register. If the higher bits are all zero, then +the second instruction may be relaxed. +@end deffn +@deffn {} BFD_RELOC_PRU_S10_PCREL +PRU QBBx 10-bit signed PC-relative relocation. +@end deffn +@deffn {} BFD_RELOC_PRU_U8_PCREL +PRU 8-bit unsigned relocation used for the LOOP instruction. +@end deffn +@deffn {} BFD_RELOC_PRU_32_PMEM +@deffnx {} BFD_RELOC_PRU_16_PMEM +PRU Program Memory relocations. Used to convert from byte +addressing to 32-bit word addressing. +@end deffn +@deffn {} BFD_RELOC_PRU_GNU_DIFF8 +@deffnx {} BFD_RELOC_PRU_GNU_DIFF16 +@deffnx {} BFD_RELOC_PRU_GNU_DIFF32 +@deffnx {} BFD_RELOC_PRU_GNU_DIFF16_PMEM +@deffnx {} BFD_RELOC_PRU_GNU_DIFF32_PMEM +PRU relocations to mark the difference of two local symbols. +These are only needed to support linker relaxation and can be +ignored when not relaxing. The field is set to the value of the +difference assuming no relaxation. The relocation encodes the +position of the second symbol so the linker can determine whether to +adjust the field value. The PMEM variants encode the word +difference, instead of byte difference between symbols. +@end deffn +@deffn {} BFD_RELOC_IQ2000_OFFSET_16 +@deffnx {} BFD_RELOC_IQ2000_OFFSET_21 +@deffnx {} BFD_RELOC_IQ2000_UHI16 +IQ2000 Relocations. +@end deffn +@deffn {} BFD_RELOC_XTENSA_RTLD +Special Xtensa relocation used only by PLT entries in ELF shared +objects to indicate that the runtime linker should set the value +to one of its own internal functions or data structures. +@end deffn +@deffn {} BFD_RELOC_XTENSA_GLOB_DAT +@deffnx {} BFD_RELOC_XTENSA_JMP_SLOT +@deffnx {} BFD_RELOC_XTENSA_RELATIVE +Xtensa relocations for ELF shared objects. +@end deffn +@deffn {} BFD_RELOC_XTENSA_PLT +Xtensa relocation used in ELF object files for symbols that may +require PLT entries. Otherwise, this is just a generic 32-bit +relocation. +@end deffn +@deffn {} BFD_RELOC_XTENSA_DIFF8 +@deffnx {} BFD_RELOC_XTENSA_DIFF16 +@deffnx {} BFD_RELOC_XTENSA_DIFF32 +Xtensa relocations for backward compatibility. These have been +replaced by BFD_RELOC_XTENSA_PDIFF and BFD_RELOC_XTENSA_NDIFF. +Xtensa relocations to mark the difference of two local symbols. +These are only needed to support linker relaxation and can be +ignored when not relaxing. The field is set to the value of the +difference assuming no relaxation. The relocation encodes the +position of the first symbol so the linker can determine whether to +adjust the field value. +@end deffn +@deffn {} BFD_RELOC_XTENSA_SLOT0_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT1_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT2_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT3_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT4_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT5_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT6_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT7_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT8_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT9_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT10_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT11_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT12_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT13_OP +@deffnx {} BFD_RELOC_XTENSA_SLOT14_OP +Generic Xtensa relocations for instruction operands. Only the slot +number is encoded in the relocation. The relocation applies to the +last PC-relative immediate operand, or if there are no PC-relative +immediates, to the last immediate operand. +@end deffn +@deffn {} BFD_RELOC_XTENSA_SLOT0_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT1_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT2_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT3_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT4_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT5_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT6_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT7_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT8_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT9_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT10_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT11_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT12_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT13_ALT +@deffnx {} BFD_RELOC_XTENSA_SLOT14_ALT +Alternate Xtensa relocations. Only the slot is encoded in the +relocation. The meaning of these relocations is opcode-specific. +@end deffn +@deffn {} BFD_RELOC_XTENSA_OP0 +@deffnx {} BFD_RELOC_XTENSA_OP1 +@deffnx {} BFD_RELOC_XTENSA_OP2 +Xtensa relocations for backward compatibility. These have all been +replaced by BFD_RELOC_XTENSA_SLOT0_OP. +@end deffn +@deffn {} BFD_RELOC_XTENSA_ASM_EXPAND +Xtensa relocation to mark that the assembler expanded the +instructions from an original target. The expansion size is +encoded in the reloc size. +@end deffn +@deffn {} BFD_RELOC_XTENSA_ASM_SIMPLIFY +Xtensa relocation to mark that the linker should simplify +assembler-expanded instructions. This is commonly used +internally by the linker after analysis of a +BFD_RELOC_XTENSA_ASM_EXPAND. +@end deffn +@deffn {} BFD_RELOC_XTENSA_TLSDESC_FN +@deffnx {} BFD_RELOC_XTENSA_TLSDESC_ARG +@deffnx {} BFD_RELOC_XTENSA_TLS_DTPOFF +@deffnx {} BFD_RELOC_XTENSA_TLS_TPOFF +@deffnx {} BFD_RELOC_XTENSA_TLS_FUNC +@deffnx {} BFD_RELOC_XTENSA_TLS_ARG +@deffnx {} BFD_RELOC_XTENSA_TLS_CALL +Xtensa TLS relocations. +@end deffn +@deffn {} BFD_RELOC_XTENSA_PDIFF8 +@deffnx {} BFD_RELOC_XTENSA_PDIFF16 +@deffnx {} BFD_RELOC_XTENSA_PDIFF32 +@deffnx {} BFD_RELOC_XTENSA_NDIFF8 +@deffnx {} BFD_RELOC_XTENSA_NDIFF16 +@deffnx {} BFD_RELOC_XTENSA_NDIFF32 +Xtensa relocations to mark the difference of two local symbols. +These are only needed to support linker relaxation and can be +ignored when not relaxing. The field is set to the value of the +difference assuming no relaxation. The relocation encodes the +position of the subtracted symbol so the linker can determine +whether to adjust the field value. PDIFF relocations are used for +positive differences, NDIFF relocations are used for negative +differences. The difference value is treated as unsigned with these +relocation types, giving full 8/16 value ranges. +@end deffn +@deffn {} BFD_RELOC_Z80_DISP8 +8 bit signed offset in (ix+d) or (iy+d). +@end deffn +@deffn {} BFD_RELOC_Z80_BYTE0 +First 8 bits of multibyte (32, 24 or 16 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_BYTE1 +Second 8 bits of multibyte (32, 24 or 16 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_BYTE2 +Third 8 bits of multibyte (32 or 24 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_BYTE3 +Fourth 8 bits of multibyte (32 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_WORD0 +Lowest 16 bits of multibyte (32 or 24 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_WORD1 +Highest 16 bits of multibyte (32 or 24 bit) value. +@end deffn +@deffn {} BFD_RELOC_Z80_16_BE +Like BFD_RELOC_16 but big-endian. +@end deffn +@deffn {} BFD_RELOC_Z8K_DISP7 +DJNZ offset. +@end deffn +@deffn {} BFD_RELOC_Z8K_CALLR +CALR offset. +@end deffn +@deffn {} BFD_RELOC_Z8K_IMM4L +4 bit value. +@end deffn +@deffn {} BFD_RELOC_LM32_CALL +@deffnx {} BFD_RELOC_LM32_BRANCH +@deffnx {} BFD_RELOC_LM32_16_GOT +@deffnx {} BFD_RELOC_LM32_GOTOFF_HI16 +@deffnx {} BFD_RELOC_LM32_GOTOFF_LO16 +@deffnx {} BFD_RELOC_LM32_COPY +@deffnx {} BFD_RELOC_LM32_GLOB_DAT +@deffnx {} BFD_RELOC_LM32_JMP_SLOT +@deffnx {} BFD_RELOC_LM32_RELATIVE +Lattice Mico32 relocations. +@end deffn +@deffn {} BFD_RELOC_MACH_O_SECTDIFF +Difference between two section addreses. Must be followed by a +BFD_RELOC_MACH_O_PAIR. +@end deffn +@deffn {} BFD_RELOC_MACH_O_LOCAL_SECTDIFF +Like BFD_RELOC_MACH_O_SECTDIFF but with a local symbol. +@end deffn +@deffn {} BFD_RELOC_MACH_O_PAIR +Pair of relocation. Contains the first symbol. +@end deffn +@deffn {} BFD_RELOC_MACH_O_SUBTRACTOR32 +Symbol will be substracted. Must be followed by a BFD_RELOC_32. +@end deffn +@deffn {} BFD_RELOC_MACH_O_SUBTRACTOR64 +Symbol will be substracted. Must be followed by a BFD_RELOC_64. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_BRANCH32 +@deffnx {} BFD_RELOC_MACH_O_X86_64_BRANCH8 +PCREL relocations. They are marked as branch to create PLT entry if +required. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_GOT +Used when referencing a GOT entry. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_GOT_LOAD +Used when loading a GOT entry with movq. It is specially marked so +that the linker could optimize the movq to a leaq if possible. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_PCREL32_1 +Same as BFD_RELOC_32_PCREL but with an implicit -1 addend. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_PCREL32_2 +Same as BFD_RELOC_32_PCREL but with an implicit -2 addend. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_PCREL32_4 +Same as BFD_RELOC_32_PCREL but with an implicit -4 addend. +@end deffn +@deffn {} BFD_RELOC_MACH_O_X86_64_TLV +Used when referencing a TLV entry. +@end deffn +@deffn {} BFD_RELOC_MACH_O_ARM64_ADDEND +Addend for PAGE or PAGEOFF. +@end deffn +@deffn {} BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGE21 +Relative offset to page of GOT slot. +@end deffn +@deffn {} BFD_RELOC_MACH_O_ARM64_GOT_LOAD_PAGEOFF12 +Relative offset within page of GOT slot. +@end deffn +@deffn {} BFD_RELOC_MACH_O_ARM64_POINTER_TO_GOT +Address of a GOT entry. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_LO +This is a 32 bit reloc for the microblaze that stores the low 16 +bits of a value. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_LO_PCREL +This is a 32 bit pc-relative reloc for the microblaze that stores +the low 16 bits of a value. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_ROSDA +This is a 32 bit reloc for the microblaze that stores a value +relative to the read-only small data area anchor. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_RWSDA +This is a 32 bit reloc for the microblaze that stores a value +relative to the read-write small data area anchor. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_SYM_OP_SYM +This is a 32 bit reloc for the microblaze to handle expressions of +the form "Symbol Op Symbol". +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_NONE +This is a 32 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). No relocation is done here - +only used for relaxing. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_NONE +This is a 64 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). No relocation is done here - +only used for relaxing. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_GOTPC +This is a 64 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). The relocation is PC-relative +GOT offset. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_GOT +This is a 64 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). The relocation is GOT offset. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_PLT +This is a 64 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). The relocation is PC-relative +offset into PLT. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_GOTOFF +This is a 64 bit reloc that stores the 32 bit GOT relative value in +two words (with an imm instruction). The relocation is relative +offset from _GLOBAL_OFFSET_TABLE_. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_GOTOFF +This is a 32 bit reloc that stores the 32 bit GOT relative value in +a word. The relocation is relative offset from +_GLOBAL_OFFSET_TABLE_. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_COPY +This is used to tell the dynamic linker to copy the value out of +the dynamic object into the runtime process image. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLS +Unused Reloc. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLSGD +This is a 64 bit reloc that stores the 32 bit GOT relative value +of the GOT TLS GD info entry in two words (with an imm instruction). +The relocation is GOT offset. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLSLD +This is a 64 bit reloc that stores the 32 bit GOT relative value +of the GOT TLS LD info entry in two words (with an imm instruction). +The relocation is GOT offset. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_TLSDTPMOD +This is a 32 bit reloc that stores the Module ID to GOT(n). +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_32_TLSDTPREL +This is a 32 bit reloc that stores TLS offset to GOT(n+1). +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLSDTPREL +This is a 32 bit reloc for storing TLS offset to two words (uses imm +instruction). +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLSGOTTPREL +This is a 64 bit reloc that stores 32-bit thread pointer relative +offset to two words (uses imm instruction). +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TLSTPREL +This is a 64 bit reloc that stores 32-bit thread pointer relative +offset to two words (uses imm instruction). +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TEXTPCREL +This is a 64 bit reloc that stores the 32 bit pc relative value in +two words (with an imm instruction). The relocation is PC-relative +offset from start of TEXT. +@end deffn +@deffn {} BFD_RELOC_MICROBLAZE_64_TEXTREL +This is a 64 bit reloc that stores the 32 bit offset value in two +words (with an imm instruction). The relocation is relative offset +from start of TEXT. +@end deffn +@deffn {} BFD_RELOC_KVX_RELOC_START +KVX pseudo relocation code to mark the start of the KVX relocation +enumerators. N.B. the order of the enumerators is important as +several tables in the KVX bfd backend are indexed by these +enumerators; make sure they are all synced. +@end deffn +@deffn {} BFD_RELOC_KVX_NONE +KVX null relocation code. +@end deffn +@deffn {} BFD_RELOC_KVX_16 +@deffnx {} BFD_RELOC_KVX_32 +@deffnx {} BFD_RELOC_KVX_64 +@deffnx {} BFD_RELOC_KVX_S16_PCREL +@deffnx {} BFD_RELOC_KVX_PCREL17 +@deffnx {} BFD_RELOC_KVX_PCREL27 +@deffnx {} BFD_RELOC_KVX_32_PCREL +@deffnx {} BFD_RELOC_KVX_S37_PCREL_LO10 +@deffnx {} BFD_RELOC_KVX_S37_PCREL_UP27 +@deffnx {} BFD_RELOC_KVX_S43_PCREL_LO10 +@deffnx {} BFD_RELOC_KVX_S43_PCREL_UP27 +@deffnx {} BFD_RELOC_KVX_S43_PCREL_EX6 +@deffnx {} BFD_RELOC_KVX_S64_PCREL_LO10 +@deffnx {} BFD_RELOC_KVX_S64_PCREL_UP27 +@deffnx {} BFD_RELOC_KVX_S64_PCREL_EX27 +@deffnx {} BFD_RELOC_KVX_64_PCREL +@deffnx {} BFD_RELOC_KVX_S16 +@deffnx {} BFD_RELOC_KVX_S32_LO5 +@deffnx {} BFD_RELOC_KVX_S32_UP27 +@deffnx {} BFD_RELOC_KVX_S37_LO10 +@deffnx {} BFD_RELOC_KVX_S37_UP27 +@deffnx {} BFD_RELOC_KVX_S37_GOTOFF_LO10 +@deffnx {} BFD_RELOC_KVX_S37_GOTOFF_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOTOFF_LO10 +@deffnx {} BFD_RELOC_KVX_S43_GOTOFF_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOTOFF_EX6 +@deffnx {} BFD_RELOC_KVX_32_GOTOFF +@deffnx {} BFD_RELOC_KVX_64_GOTOFF +@deffnx {} BFD_RELOC_KVX_32_GOT +@deffnx {} BFD_RELOC_KVX_S37_GOT_LO10 +@deffnx {} BFD_RELOC_KVX_S37_GOT_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOT_LO10 +@deffnx {} BFD_RELOC_KVX_S43_GOT_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOT_EX6 +@deffnx {} BFD_RELOC_KVX_64_GOT +@deffnx {} BFD_RELOC_KVX_GLOB_DAT +@deffnx {} BFD_RELOC_KVX_COPY +@deffnx {} BFD_RELOC_KVX_JMP_SLOT +@deffnx {} BFD_RELOC_KVX_RELATIVE +@deffnx {} BFD_RELOC_KVX_S43_LO10 +@deffnx {} BFD_RELOC_KVX_S43_UP27 +@deffnx {} BFD_RELOC_KVX_S43_EX6 +@deffnx {} BFD_RELOC_KVX_S64_LO10 +@deffnx {} BFD_RELOC_KVX_S64_UP27 +@deffnx {} BFD_RELOC_KVX_S64_EX27 +@deffnx {} BFD_RELOC_KVX_S37_GOTADDR_LO10 +@deffnx {} BFD_RELOC_KVX_S37_GOTADDR_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOTADDR_LO10 +@deffnx {} BFD_RELOC_KVX_S43_GOTADDR_UP27 +@deffnx {} BFD_RELOC_KVX_S43_GOTADDR_EX6 +@deffnx {} BFD_RELOC_KVX_S64_GOTADDR_LO10 +@deffnx {} BFD_RELOC_KVX_S64_GOTADDR_UP27 +@deffnx {} BFD_RELOC_KVX_S64_GOTADDR_EX27 +@deffnx {} BFD_RELOC_KVX_64_DTPMOD +@deffnx {} BFD_RELOC_KVX_64_DTPOFF +@deffnx {} BFD_RELOC_KVX_S37_TLS_DTPOFF_LO10 +@deffnx {} BFD_RELOC_KVX_S37_TLS_DTPOFF_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_DTPOFF_LO10 +@deffnx {} BFD_RELOC_KVX_S43_TLS_DTPOFF_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_DTPOFF_EX6 +@deffnx {} BFD_RELOC_KVX_S37_TLS_GD_LO10 +@deffnx {} BFD_RELOC_KVX_S37_TLS_GD_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_GD_LO10 +@deffnx {} BFD_RELOC_KVX_S43_TLS_GD_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_GD_EX6 +@deffnx {} BFD_RELOC_KVX_S37_TLS_LD_LO10 +@deffnx {} BFD_RELOC_KVX_S37_TLS_LD_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LD_LO10 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LD_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LD_EX6 +@deffnx {} BFD_RELOC_KVX_64_TPOFF +@deffnx {} BFD_RELOC_KVX_S37_TLS_IE_LO10 +@deffnx {} BFD_RELOC_KVX_S37_TLS_IE_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_IE_LO10 +@deffnx {} BFD_RELOC_KVX_S43_TLS_IE_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_IE_EX6 +@deffnx {} BFD_RELOC_KVX_S37_TLS_LE_LO10 +@deffnx {} BFD_RELOC_KVX_S37_TLS_LE_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LE_LO10 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LE_UP27 +@deffnx {} BFD_RELOC_KVX_S43_TLS_LE_EX6 +@deffnx {} BFD_RELOC_KVX_8 +KVX Relocations. +@end deffn +@deffn {} BFD_RELOC_KVX_RELOC_END +KVX pseudo relocation code to mark the end of the KVX relocation +enumerators that have direct mapping to ELF reloc codes. There are +a few more enumerators after this one; those are mainly used by the +KVX assembler for the internal fixup or to select one of the above +enumerators. +@end deffn +@deffn {} BFD_RELOC_AARCH64_RELOC_START +AArch64 pseudo relocation code to mark the start of the AArch64 +relocation enumerators. N.B. the order of the enumerators is +important as several tables in the AArch64 bfd backend are indexed +by these enumerators; make sure they are all synced. +@end deffn +@deffn {} BFD_RELOC_AARCH64_NULL +Deprecated AArch64 null relocation code. +@end deffn +@deffn {} BFD_RELOC_AARCH64_NONE +AArch64 null relocation code. +@end deffn +@deffn {} BFD_RELOC_AARCH64_64 +@deffnx {} BFD_RELOC_AARCH64_32 +@deffnx {} BFD_RELOC_AARCH64_16 +Basic absolute relocations of N bits. These are equivalent to +BFD_RELOC_N and they were added to assist the indexing of the howto +table. +@end deffn +@deffn {} BFD_RELOC_AARCH64_64_PCREL +@deffnx {} BFD_RELOC_AARCH64_32_PCREL +@deffnx {} BFD_RELOC_AARCH64_16_PCREL +PC-relative relocations. These are equivalent to BFD_RELOC_N_PCREL +and they were added to assist the indexing of the howto table. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G0 +AArch64 MOV[NZK] instruction with most significant bits 0 to 15 of +an unsigned address/value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G0_NC +AArch64 MOV[NZK] instruction with less significant bits 0 to 15 of +an address/value. No overflow checking. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G1 +AArch64 MOV[NZK] instruction with most significant bits 16 to 31 of +an unsigned address/value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G1_NC +AArch64 MOV[NZK] instruction with less significant bits 16 to 31 of +an address/value. No overflow checking. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G2 +AArch64 MOV[NZK] instruction with most significant bits 32 to 47 of +an unsigned address/value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G2_NC +AArch64 MOV[NZK] instruction with less significant bits 32 to 47 of +an address/value. No overflow checking. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G3 +AArch64 MOV[NZK] instruction with most signficant bits 48 to 64 of a +signed or unsigned address/value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G0_S +AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a +signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G1_S +AArch64 MOV[NZ] instruction with most significant bits 16 to 31 of a +signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_G2_S +AArch64 MOV[NZ] instruction with most significant bits 32 to 47 of a +signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G0 +AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a +signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G0_NC +AArch64 MOV[NZ] instruction with most significant bits 0 to 15 of a +signed value. Changes instruction to MOVZ or MOVN depending on the +value's sign. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G1 +AArch64 MOVK instruction with most significant bits 16 to 31 of a +signed value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G1_NC +AArch64 MOVK instruction with most significant bits 16 to 31 of a +signed value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G2 +AArch64 MOVK instruction with most significant bits 32 to 47 of a +signed value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G2_NC +AArch64 MOVK instruction with most significant bits 32 to 47 of a +signed value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_PREL_G3 +AArch64 MOVK instruction with most significant bits 47 to 63 of a +signed value. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD_LO19_PCREL +AArch64 Load Literal instruction, holding a 19 bit pc-relative word +offset. The lowest two bits must be zero and are not stored in the +instruction, giving a 21 bit signed byte offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_ADR_LO21_PCREL +AArch64 ADR instruction, holding a simple 21 bit pc-relative byte +offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_ADR_HI21_PCREL +AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page +offset, giving a 4KB aligned page base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_ADR_HI21_NC_PCREL +AArch64 ADRP instruction, with bits 12 to 32 of a pc-relative page +offset, giving a 4KB aligned page base address, but with no overflow +checking. +@end deffn +@deffn {} BFD_RELOC_AARCH64_ADD_LO12 +AArch64 ADD immediate instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST8_LO12 +AArch64 8-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TSTBR14 +AArch64 14 bit pc-relative test bit and branch. +The lowest two bits must be zero and are not stored in the +instruction, giving a 16 bit signed byte offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_BRANCH19 +AArch64 19 bit pc-relative conditional branch and compare & branch. +The lowest two bits must be zero and are not stored in the +instruction, giving a 21 bit signed byte offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_JUMP26 +AArch64 26 bit pc-relative unconditional branch. +The lowest two bits must be zero and are not stored in the +instruction, giving a 28 bit signed byte offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_CALL26 +AArch64 26 bit pc-relative unconditional branch and link. +The lowest two bits must be zero and are not stored in the +instruction, giving a 28 bit signed byte offset. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST16_LO12 +AArch64 16-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST32_LO12 +AArch64 32-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST64_LO12 +AArch64 64-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST128_LO12 +AArch64 128-bit load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_GOT_LD_PREL19 +AArch64 Load Literal instruction, holding a 19 bit PC relative word +offset of the global offset table entry for a symbol. The lowest +two bits must be zero and are not stored in the instruction, giving +a 21 bit signed byte offset. This relocation type requires signed +overflow checking. +@end deffn +@deffn {} BFD_RELOC_AARCH64_ADR_GOT_PAGE +Get to the page base of the global offset table entry for a symbol +as part of an ADRP instruction using a 21 bit PC relative value. +Used in conjunction with BFD_RELOC_AARCH64_LD64_GOT_LO12_NC. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD64_GOT_LO12_NC +Unsigned 12 bit byte offset for 64 bit load/store from the page of +the GOT entry for this symbol. Used in conjunction with +BFD_RELOC_AARCH64_ADR_GOT_PAGE. Valid in LP64 ABI only. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD32_GOT_LO12_NC +Unsigned 12 bit byte offset for 32 bit load/store from the page of +the GOT entry for this symbol. Used in conjunction with +BFD_RELOC_AARCH64_ADR_GOT_PAGE. Valid in ILP32 ABI only. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_GOTOFF_G0_NC +Unsigned 16 bit byte offset for 64 bit load/store from the GOT entry +for this symbol. Valid in LP64 ABI only. +@end deffn +@deffn {} BFD_RELOC_AARCH64_MOVW_GOTOFF_G1 +Unsigned 16 bit byte higher offset for 64 bit load/store from the +GOT entry for this symbol. Valid in LP64 ABI only. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD64_GOTOFF_LO15 +Unsigned 15 bit byte offset for 64 bit load/store from the page of +the GOT entry for this symbol. Valid in LP64 ABI only. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD32_GOTPAGE_LO14 +Scaled 14 bit byte offset to the page base of the global offset +table. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD64_GOTPAGE_LO15 +Scaled 15 bit byte offset to the page base of the global offset +table. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21 +Get to the page base of the global offset table entry for a symbols +tls_index structure as part of an adrp instruction using a 21 bit PC +relative value. Used in conjunction with +BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSGD_ADR_PREL21 +AArch64 TLS General Dynamic. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSGD_ADD_LO12_NC +Unsigned 12 bit byte offset to global offset table entry for a +symbol's tls_index structure. Used in conjunction with +BFD_RELOC_AARCH64_TLSGD_ADR_PAGE21. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSGD_MOVW_G0_NC +AArch64 TLS General Dynamic relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSGD_MOVW_G1 +AArch64 TLS General Dynamic relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_ADR_GOTTPREL_PAGE21 +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_LD64_GOTTPREL_LO12_NC +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_LD32_GOTTPREL_LO12_NC +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_PREL19 +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G0_NC +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_MOVW_GOTTPREL_G1 +AArch64 TLS INITIAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_HI12 +bit[23:12] of byte offset to module TLS base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12 +Unsigned 12 bit byte offset to module TLS base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12_NC +No overflow check version of +BFD_RELOC_AARCH64_TLSLD_ADD_DTPREL_LO12. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADD_LO12_NC +Unsigned 12 bit byte offset to global offset table entry for a +symbol's tls_index structure. Used in conjunction with +BFD_RELOC_AARCH64_TLSLD_ADR_PAGE21. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADR_PAGE21 +GOT entry page address for AArch64 TLS Local Dynamic, used with ADRP +instruction. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_ADR_PREL21 +GOT entry address for AArch64 TLS Local Dynamic, used with ADR +instruction. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12 +bit[11:1] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLD_LDST16_DTPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12 +bit[11:2] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLD_LDST32_DTPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12 +bit[11:3] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLD_LDST64_DTPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12 +bit[11:0] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLD_LDST8_DTPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0 +bit[15:0] of byte offset to module TLS base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0_NC +No overflow check version of BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G0. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1 +bit[31:16] of byte offset to module TLS base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1_NC +No overflow check version of BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G1. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_MOVW_DTPREL_G2 +bit[47:32] of byte offset to module TLS base address. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G2 +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1 +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G1_NC +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0 +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_MOVW_TPREL_G0_NC +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_HI12 +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12 +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_ADD_TPREL_LO12_NC +AArch64 TLS LOCAL EXEC relocation. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12 +bit[11:1] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLE_LDST16_TPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12 +bit[11:2] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLE_LDST32_TPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12 +bit[11:3] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLE_LDST64_TPREL_LO12, but no +overflow check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12 +bit[11:0] of byte offset to module TLS base address, encoded in ldst +instructions. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLE_LDST8_TPREL_LO12, but no overflow +check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSDESC_LD_PREL19 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_ADR_PREL21 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_ADR_PAGE21 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_LD64_LO12 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_LD32_LO12_NC +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_ADD_LO12 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_OFF_G1 +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_OFF_G0_NC +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_LDR +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_ADD +@deffnx {} BFD_RELOC_AARCH64_TLSDESC_CALL +AArch64 TLS DESC relocations. +@end deffn +@deffn {} BFD_RELOC_AARCH64_COPY +@deffnx {} BFD_RELOC_AARCH64_GLOB_DAT +@deffnx {} BFD_RELOC_AARCH64_JUMP_SLOT +@deffnx {} BFD_RELOC_AARCH64_RELATIVE +AArch64 DSO relocations. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLS_DTPMOD +@deffnx {} BFD_RELOC_AARCH64_TLS_DTPREL +@deffnx {} BFD_RELOC_AARCH64_TLS_TPREL +@deffnx {} BFD_RELOC_AARCH64_TLSDESC +AArch64 TLS relocations. +@end deffn +@deffn {} BFD_RELOC_AARCH64_IRELATIVE +AArch64 support for STT_GNU_IFUNC. +@end deffn +@deffn {} BFD_RELOC_AARCH64_RELOC_END +AArch64 pseudo relocation code to mark the end of the AArch64 +relocation enumerators that have direct mapping to ELF reloc codes. +There are a few more enumerators after this one; those are mainly +used by the AArch64 assembler for the internal fixup or to select +one of the above enumerators. +@end deffn +@deffn {} BFD_RELOC_AARCH64_GAS_INTERNAL_FIXUP +AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LDST_LO12 +AArch64 unspecified load/store instruction, holding bits 0 to 11 of the +address. Used in conjunction with BFD_RELOC_AARCH64_ADR_HI21_PCREL. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12 +AArch64 pseudo relocation code for TLS local dynamic mode. It's to +be used internally by the AArch64 assembler and not (currently) +written to any object files. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLD_LDST_DTPREL_LO12, but no overflow +check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12 +AArch64 pseudo relocation code for TLS local exec mode. It's to be +used internally by the AArch64 assembler and not (currently) written +to any object files. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12_NC +Similar to BFD_RELOC_AARCH64_TLSLE_LDST_TPREL_LO12, but no overflow +check. +@end deffn +@deffn {} BFD_RELOC_AARCH64_LD_GOT_LO12_NC +AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSIE_LD_GOTTPREL_LO12_NC +AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. +@end deffn +@deffn {} BFD_RELOC_AARCH64_TLSDESC_LD_LO12_NC +AArch64 pseudo relocation code to be used internally by the AArch64 +assembler and not (currently) written to any object files. +@end deffn +@deffn {} BFD_RELOC_TILEPRO_COPY +@deffnx {} BFD_RELOC_TILEPRO_GLOB_DAT +@deffnx {} BFD_RELOC_TILEPRO_JMP_SLOT +@deffnx {} BFD_RELOC_TILEPRO_RELATIVE +@deffnx {} BFD_RELOC_TILEPRO_BROFF_X1 +@deffnx {} BFD_RELOC_TILEPRO_JOFFLONG_X1 +@deffnx {} BFD_RELOC_TILEPRO_JOFFLONG_X1_PLT +@deffnx {} BFD_RELOC_TILEPRO_IMM8_X0 +@deffnx {} BFD_RELOC_TILEPRO_IMM8_Y0 +@deffnx {} BFD_RELOC_TILEPRO_IMM8_X1 +@deffnx {} BFD_RELOC_TILEPRO_IMM8_Y1 +@deffnx {} BFD_RELOC_TILEPRO_DEST_IMM8_X1 +@deffnx {} BFD_RELOC_TILEPRO_MT_IMM15_X1 +@deffnx {} BFD_RELOC_TILEPRO_MF_IMM15_X1 +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0 +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1 +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_LO_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_LO_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_HI_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_HI_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_HA_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_HA_PCREL +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_GOT +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_GOT +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_GOT_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_GOT_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_GOT_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_GOT_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_GOT_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_GOT_HA +@deffnx {} BFD_RELOC_TILEPRO_MMSTART_X0 +@deffnx {} BFD_RELOC_TILEPRO_MMEND_X0 +@deffnx {} BFD_RELOC_TILEPRO_MMSTART_X1 +@deffnx {} BFD_RELOC_TILEPRO_MMEND_X1 +@deffnx {} BFD_RELOC_TILEPRO_SHAMT_X0 +@deffnx {} BFD_RELOC_TILEPRO_SHAMT_X1 +@deffnx {} BFD_RELOC_TILEPRO_SHAMT_Y0 +@deffnx {} BFD_RELOC_TILEPRO_SHAMT_Y1 +@deffnx {} BFD_RELOC_TILEPRO_TLS_GD_CALL +@deffnx {} BFD_RELOC_TILEPRO_IMM8_X0_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEPRO_IMM8_X1_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEPRO_IMM8_Y0_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEPRO_IMM8_Y1_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEPRO_TLS_IE_LOAD +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_GD_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_GD_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_IE_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_IE_HA +@deffnx {} BFD_RELOC_TILEPRO_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_TILEPRO_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_TILEPRO_TLS_TPOFF32 +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_LO +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HI +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X0_TLS_LE_HA +@deffnx {} BFD_RELOC_TILEPRO_IMM16_X1_TLS_LE_HA +Tilera TILEPro Relocations. +@end deffn +@deffn {} BFD_RELOC_TILEGX_HW0 +@deffnx {} BFD_RELOC_TILEGX_HW1 +@deffnx {} BFD_RELOC_TILEGX_HW2 +@deffnx {} BFD_RELOC_TILEGX_HW3 +@deffnx {} BFD_RELOC_TILEGX_HW0_LAST +@deffnx {} BFD_RELOC_TILEGX_HW1_LAST +@deffnx {} BFD_RELOC_TILEGX_HW2_LAST +@deffnx {} BFD_RELOC_TILEGX_COPY +@deffnx {} BFD_RELOC_TILEGX_GLOB_DAT +@deffnx {} BFD_RELOC_TILEGX_JMP_SLOT +@deffnx {} BFD_RELOC_TILEGX_RELATIVE +@deffnx {} BFD_RELOC_TILEGX_BROFF_X1 +@deffnx {} BFD_RELOC_TILEGX_JUMPOFF_X1 +@deffnx {} BFD_RELOC_TILEGX_JUMPOFF_X1_PLT +@deffnx {} BFD_RELOC_TILEGX_IMM8_X0 +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y0 +@deffnx {} BFD_RELOC_TILEGX_IMM8_X1 +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y1 +@deffnx {} BFD_RELOC_TILEGX_DEST_IMM8_X1 +@deffnx {} BFD_RELOC_TILEGX_MT_IMM14_X1 +@deffnx {} BFD_RELOC_TILEGX_MF_IMM14_X1 +@deffnx {} BFD_RELOC_TILEGX_MMSTART_X0 +@deffnx {} BFD_RELOC_TILEGX_MMEND_X0 +@deffnx {} BFD_RELOC_TILEGX_SHAMT_X0 +@deffnx {} BFD_RELOC_TILEGX_SHAMT_X1 +@deffnx {} BFD_RELOC_TILEGX_SHAMT_Y0 +@deffnx {} BFD_RELOC_TILEGX_SHAMT_Y1 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW3 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW3 +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW3_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW3_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_GOT +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW3_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW3_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_LE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_GD +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW2_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW2_LAST_PLT_PCREL +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW0_LAST_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW0_LAST_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X0_HW1_LAST_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_IMM16_X1_HW1_LAST_TLS_IE +@deffnx {} BFD_RELOC_TILEGX_TLS_DTPMOD64 +@deffnx {} BFD_RELOC_TILEGX_TLS_DTPOFF64 +@deffnx {} BFD_RELOC_TILEGX_TLS_TPOFF64 +@deffnx {} BFD_RELOC_TILEGX_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_TILEGX_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_TILEGX_TLS_TPOFF32 +@deffnx {} BFD_RELOC_TILEGX_TLS_GD_CALL +@deffnx {} BFD_RELOC_TILEGX_IMM8_X0_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_X1_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y0_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y1_TLS_GD_ADD +@deffnx {} BFD_RELOC_TILEGX_TLS_IE_LOAD +@deffnx {} BFD_RELOC_TILEGX_IMM8_X0_TLS_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_X1_TLS_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y0_TLS_ADD +@deffnx {} BFD_RELOC_TILEGX_IMM8_Y1_TLS_ADD +Tilera TILE-Gx Relocations. +@end deffn +@deffn {} BFD_RELOC_BPF_64 +@deffnx {} BFD_RELOC_BPF_DISP32 +@deffnx {} BFD_RELOC_BPF_DISPCALL32 +@deffnx {} BFD_RELOC_BPF_DISP16 +Linux eBPF relocations. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_SIMM8 +Adapteva EPIPHANY - 8 bit signed pc-relative displacement. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_SIMM24 +Adapteva EPIPHANY - 24 bit signed pc-relative displacement. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_HIGH +Adapteva EPIPHANY - 16 most-significant bits of absolute address. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_LOW +Adapteva EPIPHANY - 16 least-significant bits of absolute address. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_SIMM11 +Adapteva EPIPHANY - 11 bit signed number - add/sub immediate. +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_IMM11 +Adapteva EPIPHANY - 11 bit sign-magnitude number (ld/st +displacement). +@end deffn +@deffn {} BFD_RELOC_EPIPHANY_IMM8 +Adapteva EPIPHANY - 8 bit immediate for 16 bit mov instruction. +@end deffn +@deffn {} BFD_RELOC_VISIUM_HI16 +@deffnx {} BFD_RELOC_VISIUM_LO16 +@deffnx {} BFD_RELOC_VISIUM_IM16 +@deffnx {} BFD_RELOC_VISIUM_REL16 +@deffnx {} BFD_RELOC_VISIUM_HI16_PCREL +@deffnx {} BFD_RELOC_VISIUM_LO16_PCREL +@deffnx {} BFD_RELOC_VISIUM_IM16_PCREL +Visium Relocations. +@end deffn +@deffn {} BFD_RELOC_WASM32_LEB128 +@deffnx {} BFD_RELOC_WASM32_LEB128_GOT +@deffnx {} BFD_RELOC_WASM32_LEB128_GOT_CODE +@deffnx {} BFD_RELOC_WASM32_LEB128_PLT +@deffnx {} BFD_RELOC_WASM32_PLT_INDEX +@deffnx {} BFD_RELOC_WASM32_ABS32_CODE +@deffnx {} BFD_RELOC_WASM32_COPY +@deffnx {} BFD_RELOC_WASM32_CODE_POINTER +@deffnx {} BFD_RELOC_WASM32_INDEX +@deffnx {} BFD_RELOC_WASM32_PLT_SIG +WebAssembly relocations. +@end deffn +@deffn {} BFD_RELOC_CKCORE_NONE +@deffnx {} BFD_RELOC_CKCORE_ADDR32 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM8BY4 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM11BY2 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM4BY2 +@deffnx {} BFD_RELOC_CKCORE_PCREL32 +@deffnx {} BFD_RELOC_CKCORE_PCREL_JSR_IMM11BY2 +@deffnx {} BFD_RELOC_CKCORE_GNU_VTINHERIT +@deffnx {} BFD_RELOC_CKCORE_GNU_VTENTRY +@deffnx {} BFD_RELOC_CKCORE_RELATIVE +@deffnx {} BFD_RELOC_CKCORE_COPY +@deffnx {} BFD_RELOC_CKCORE_GLOB_DAT +@deffnx {} BFD_RELOC_CKCORE_JUMP_SLOT +@deffnx {} BFD_RELOC_CKCORE_GOTOFF +@deffnx {} BFD_RELOC_CKCORE_GOTPC +@deffnx {} BFD_RELOC_CKCORE_GOT32 +@deffnx {} BFD_RELOC_CKCORE_PLT32 +@deffnx {} BFD_RELOC_CKCORE_ADDRGOT +@deffnx {} BFD_RELOC_CKCORE_ADDRPLT +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM26BY2 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM16BY2 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM16BY4 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM10BY2 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM10BY4 +@deffnx {} BFD_RELOC_CKCORE_ADDR_HI16 +@deffnx {} BFD_RELOC_CKCORE_ADDR_LO16 +@deffnx {} BFD_RELOC_CKCORE_GOTPC_HI16 +@deffnx {} BFD_RELOC_CKCORE_GOTPC_LO16 +@deffnx {} BFD_RELOC_CKCORE_GOTOFF_HI16 +@deffnx {} BFD_RELOC_CKCORE_GOTOFF_LO16 +@deffnx {} BFD_RELOC_CKCORE_GOT12 +@deffnx {} BFD_RELOC_CKCORE_GOT_HI16 +@deffnx {} BFD_RELOC_CKCORE_GOT_LO16 +@deffnx {} BFD_RELOC_CKCORE_PLT12 +@deffnx {} BFD_RELOC_CKCORE_PLT_HI16 +@deffnx {} BFD_RELOC_CKCORE_PLT_LO16 +@deffnx {} BFD_RELOC_CKCORE_ADDRGOT_HI16 +@deffnx {} BFD_RELOC_CKCORE_ADDRGOT_LO16 +@deffnx {} BFD_RELOC_CKCORE_ADDRPLT_HI16 +@deffnx {} BFD_RELOC_CKCORE_ADDRPLT_LO16 +@deffnx {} BFD_RELOC_CKCORE_PCREL_JSR_IMM26BY2 +@deffnx {} BFD_RELOC_CKCORE_TOFFSET_LO16 +@deffnx {} BFD_RELOC_CKCORE_DOFFSET_LO16 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM18BY2 +@deffnx {} BFD_RELOC_CKCORE_DOFFSET_IMM18 +@deffnx {} BFD_RELOC_CKCORE_DOFFSET_IMM18BY2 +@deffnx {} BFD_RELOC_CKCORE_DOFFSET_IMM18BY4 +@deffnx {} BFD_RELOC_CKCORE_GOTOFF_IMM18 +@deffnx {} BFD_RELOC_CKCORE_GOT_IMM18BY4 +@deffnx {} BFD_RELOC_CKCORE_PLT_IMM18BY4 +@deffnx {} BFD_RELOC_CKCORE_PCREL_IMM7BY4 +@deffnx {} BFD_RELOC_CKCORE_TLS_LE32 +@deffnx {} BFD_RELOC_CKCORE_TLS_IE32 +@deffnx {} BFD_RELOC_CKCORE_TLS_GD32 +@deffnx {} BFD_RELOC_CKCORE_TLS_LDM32 +@deffnx {} BFD_RELOC_CKCORE_TLS_LDO32 +@deffnx {} BFD_RELOC_CKCORE_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_CKCORE_TLS_DTPOFF32 +@deffnx {} BFD_RELOC_CKCORE_TLS_TPOFF32 +@deffnx {} BFD_RELOC_CKCORE_PCREL_FLRW_IMM8BY4 +@deffnx {} BFD_RELOC_CKCORE_NOJSRI +@deffnx {} BFD_RELOC_CKCORE_CALLGRAPH +@deffnx {} BFD_RELOC_CKCORE_IRELATIVE +@deffnx {} BFD_RELOC_CKCORE_PCREL_BLOOP_IMM4BY4 +@deffnx {} BFD_RELOC_CKCORE_PCREL_BLOOP_IMM12BY4 +C-SKY relocations. +@end deffn +@deffn {} BFD_RELOC_S12Z_OPR +S12Z relocations. +@end deffn +@deffn {} BFD_RELOC_LARCH_TLS_DTPMOD32 +@deffnx {} BFD_RELOC_LARCH_TLS_DTPREL32 +@deffnx {} BFD_RELOC_LARCH_TLS_DTPMOD64 +@deffnx {} BFD_RELOC_LARCH_TLS_DTPREL64 +@deffnx {} BFD_RELOC_LARCH_TLS_TPREL32 +@deffnx {} BFD_RELOC_LARCH_TLS_TPREL64 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC32 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC64 +@deffnx {} BFD_RELOC_LARCH_MARK_LA +@deffnx {} BFD_RELOC_LARCH_MARK_PCREL +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_PCREL +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_ABSOLUTE +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_DUP +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_GPREL +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_TLS_TPREL +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_TLS_GOT +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_TLS_GD +@deffnx {} BFD_RELOC_LARCH_SOP_PUSH_PLT_PCREL +@deffnx {} BFD_RELOC_LARCH_SOP_ASSERT +@deffnx {} BFD_RELOC_LARCH_SOP_NOT +@deffnx {} BFD_RELOC_LARCH_SOP_SUB +@deffnx {} BFD_RELOC_LARCH_SOP_SL +@deffnx {} BFD_RELOC_LARCH_SOP_SR +@deffnx {} BFD_RELOC_LARCH_SOP_ADD +@deffnx {} BFD_RELOC_LARCH_SOP_AND +@deffnx {} BFD_RELOC_LARCH_SOP_IF_ELSE +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_10_5 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_U_10_12 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_10_12 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_10_16 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_10_16_S2 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_5_20 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_0_5_10_16_S2 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_S_0_10_10_16_S2 +@deffnx {} BFD_RELOC_LARCH_SOP_POP_32_U +@deffnx {} BFD_RELOC_LARCH_ADD8 +@deffnx {} BFD_RELOC_LARCH_ADD16 +@deffnx {} BFD_RELOC_LARCH_ADD24 +@deffnx {} BFD_RELOC_LARCH_ADD32 +@deffnx {} BFD_RELOC_LARCH_ADD64 +@deffnx {} BFD_RELOC_LARCH_SUB8 +@deffnx {} BFD_RELOC_LARCH_SUB16 +@deffnx {} BFD_RELOC_LARCH_SUB24 +@deffnx {} BFD_RELOC_LARCH_SUB32 +@deffnx {} BFD_RELOC_LARCH_SUB64 +@deffnx {} BFD_RELOC_LARCH_B16 +@deffnx {} BFD_RELOC_LARCH_B21 +@deffnx {} BFD_RELOC_LARCH_B26 +@deffnx {} BFD_RELOC_LARCH_ABS_HI20 +@deffnx {} BFD_RELOC_LARCH_ABS_LO12 +@deffnx {} BFD_RELOC_LARCH_ABS64_LO20 +@deffnx {} BFD_RELOC_LARCH_ABS64_HI12 +@deffnx {} BFD_RELOC_LARCH_PCALA_HI20 +@deffnx {} BFD_RELOC_LARCH_PCALA_LO12 +@deffnx {} BFD_RELOC_LARCH_PCALA64_LO20 +@deffnx {} BFD_RELOC_LARCH_PCALA64_HI12 +@deffnx {} BFD_RELOC_LARCH_GOT_PC_HI20 +@deffnx {} BFD_RELOC_LARCH_GOT_PC_LO12 +@deffnx {} BFD_RELOC_LARCH_GOT64_PC_LO20 +@deffnx {} BFD_RELOC_LARCH_GOT64_PC_HI12 +@deffnx {} BFD_RELOC_LARCH_GOT_HI20 +@deffnx {} BFD_RELOC_LARCH_GOT_LO12 +@deffnx {} BFD_RELOC_LARCH_GOT64_LO20 +@deffnx {} BFD_RELOC_LARCH_GOT64_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_LE_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_LE_LO12 +@deffnx {} BFD_RELOC_LARCH_TLS_LE64_LO20 +@deffnx {} BFD_RELOC_LARCH_TLS_LE64_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_IE_PC_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_IE_PC_LO12 +@deffnx {} BFD_RELOC_LARCH_TLS_IE64_PC_LO20 +@deffnx {} BFD_RELOC_LARCH_TLS_IE64_PC_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_IE_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_IE_LO12 +@deffnx {} BFD_RELOC_LARCH_TLS_IE64_LO20 +@deffnx {} BFD_RELOC_LARCH_TLS_IE64_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_LD_PC_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_LD_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_GD_PC_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_GD_HI20 +@deffnx {} BFD_RELOC_LARCH_32_PCREL +@deffnx {} BFD_RELOC_LARCH_RELAX +@deffnx {} BFD_RELOC_LARCH_DELETE +@deffnx {} BFD_RELOC_LARCH_ALIGN +@deffnx {} BFD_RELOC_LARCH_PCREL20_S2 +@deffnx {} BFD_RELOC_LARCH_CFA +@deffnx {} BFD_RELOC_LARCH_ADD6 +@deffnx {} BFD_RELOC_LARCH_SUB6 +@deffnx {} BFD_RELOC_LARCH_ADD_ULEB128 +@deffnx {} BFD_RELOC_LARCH_SUB_ULEB128 +@deffnx {} BFD_RELOC_LARCH_64_PCREL +@deffnx {} BFD_RELOC_LARCH_CALL36 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_PC_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_PC_LO12 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC64_PC_LO20 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC64_PC_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_HI20 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_LO12 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC64_LO20 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC64_HI12 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_LD +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_CALL +@deffnx {} BFD_RELOC_LARCH_TLS_LE_HI20_R +@deffnx {} BFD_RELOC_LARCH_TLS_LE_ADD_R +@deffnx {} BFD_RELOC_LARCH_TLS_LE_LO12_R +@deffnx {} BFD_RELOC_LARCH_TLS_LD_PCREL20_S2 +@deffnx {} BFD_RELOC_LARCH_TLS_GD_PCREL20_S2 +@deffnx {} BFD_RELOC_LARCH_TLS_DESC_PCREL20_S2 +LARCH relocations. +@end deffn + +@example +typedef enum bfd_reloc_code_real bfd_reloc_code_real_type; + +@end example +@findex bfd_reloc_type_lookup +@subsubsection @code{bfd_reloc_type_lookup} +@deftypefn {Function} reloc_howto_type *bfd_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code); reloc_howto_type *bfd_reloc_name_lookup (bfd *abfd, const char *reloc_name); +Return a pointer to a howto structure which, when +invoked, will perform the relocation @var{code} on data from the +architecture noted. + +@end deftypefn +@findex bfd_default_reloc_type_lookup +@subsubsection @code{bfd_default_reloc_type_lookup} +@deftypefn {Function} reloc_howto_type *bfd_default_reloc_type_lookup (bfd *abfd, bfd_reloc_code_real_type code); +Provides a default relocation lookup routine for any architecture. + +@end deftypefn +@findex bfd_get_reloc_code_name +@subsubsection @code{bfd_get_reloc_code_name} +@deftypefn {Function} const char *bfd_get_reloc_code_name (bfd_reloc_code_real_type code); +Provides a printable name for the supplied relocation code. +Useful mainly for printing error messages. + +@end deftypefn +@findex bfd_generic_relax_section +@subsubsection @code{bfd_generic_relax_section} +@deftypefn {Function} bool bfd_generic_relax_section (bfd *abfd, asection *section, struct bfd_link_info *, bool *); +Provides default handling for relaxing for back ends which +don't do relaxing. + +@end deftypefn +@findex bfd_generic_gc_sections +@subsubsection @code{bfd_generic_gc_sections} +@deftypefn {Function} bool bfd_generic_gc_sections (bfd *, struct bfd_link_info *); +Provides default handling for relaxing for back ends which +don't do section gc -- i.e., does nothing. + +@end deftypefn +@findex bfd_generic_lookup_section_flags +@subsubsection @code{bfd_generic_lookup_section_flags} +@deftypefn {Function} bool bfd_generic_lookup_section_flags (struct bfd_link_info *, struct flag_info *, asection *); +Provides default handling for section flags lookup +-- i.e., does nothing. +Returns FALSE if the section should be omitted, otherwise TRUE. + +@end deftypefn +@findex bfd_generic_merge_sections +@subsubsection @code{bfd_generic_merge_sections} +@deftypefn {Function} bool bfd_generic_merge_sections (bfd *, struct bfd_link_info *); +Provides default handling for SEC_MERGE section merging for back ends +which don't have SEC_MERGE support -- i.e., does nothing. + +@end deftypefn +@findex bfd_generic_get_relocated_section_contents +@subsubsection @code{bfd_generic_get_relocated_section_contents} +@deftypefn {Function} bfd_byte *bfd_generic_get_relocated_section_contents (bfd *abfd, struct bfd_link_info *link_info, struct bfd_link_order *link_order, bfd_byte *data, bool relocatable, asymbol **symbols); +Provides default handling of relocation effort for back ends +which can't be bothered to do it efficiently. + +@end deftypefn +@findex _bfd_generic_set_reloc +@subsubsection @code{_bfd_generic_set_reloc} +@deftypefn {Function} void _bfd_generic_set_reloc (bfd *abfd, sec_ptr section, arelent **relptr, unsigned int count); +Installs a new set of internal relocations in SECTION. + +@end deftypefn +@findex _bfd_unrecognized_reloc +@subsubsection @code{_bfd_unrecognized_reloc} +@deftypefn {Function} bool _bfd_unrecognized_reloc (bfd * abfd, sec_ptr section, unsigned int r_type); +Reports an unrecognized reloc. +Written as a function in order to reduce code duplication. +Returns FALSE so that it can be called from a return statement. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/section.texi 16.3-5ubuntu1/bfd/doc/section.texi --- 16.3-5/bfd/doc/section.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/section.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,828 @@ +@section Sections +The raw data contained within a BFD is maintained through the +section abstraction. A single BFD may have any number of +sections. It keeps hold of them by pointing to the first; +each one points to the next in the list. +Sections are supported in BFD in @code{section.c}. + +@menu +* Section Input:: +* Section Output:: +* typedef asection:: +* section prototypes:: +@end menu + +@node Section Input, Section Output, Sections, Sections +@subsection Section input +When a BFD is opened for reading, the section structures are +created and attached to the BFD. + +Each section has a name which describes the section in the +outside world---for example, @code{a.out} would contain at least +three sections, called @code{.text}, @code{.data} and @code{.bss}. + +Names need not be unique; for example a COFF file may have several +sections named @code{.data}. + +Sometimes a BFD will contain more than the ``natural'' number of +sections. A back end may attach other sections containing +constructor data, or an application may add a section (using +@code{bfd_make_section}) to the sections attached to an already open +BFD. For example, the linker creates an extra section +@code{COMMON} for each input file's BFD to hold information about +common storage. + +The raw data is not necessarily read in when +the section descriptor is created. Some targets may leave the +data in place until a @code{bfd_get_section_contents} call is +made. Other back ends may read in all the data at once. For +example, an S-record file has to be read once to determine the +size of the data. + +@node Section Output, typedef asection, Section Input, Sections +@subsection Section output +To write a new object style BFD, the various sections to be +written have to be created. They are attached to the BFD in +the same way as input sections; data is written to the +sections using @code{bfd_set_section_contents}. + +Any program that creates or combines sections (e.g., the assembler +and linker) must use the @code{asection} fields @code{output_section} and +@code{output_offset} to indicate the file sections to which each +section must be written. (If the section is being created from +scratch, @code{output_section} should probably point to the section +itself and @code{output_offset} should probably be zero.) + +The data to be written comes from input sections attached +(via @code{output_section} pointers) to +the output sections. The output section structure can be +considered a filter for the input section: the output section +determines the vma of the output data and the name, but the +input section determines the offset into the output section of +the data to be written. + +E.g., to create a section "O", starting at 0x100, 0x123 long, +containing two subsections, "A" at offset 0x0 (i.e., at vma +0x100) and "B" at offset 0x20 (i.e., at vma 0x120) the @code{asection} +structures would look like: + +@example + section name "A" + output_offset 0x00 + size 0x20 + output_section -----------> section name "O" + | vma 0x100 + section name "B" | size 0x123 + output_offset 0x20 | + size 0x103 | + output_section --------| +@end example + +@subsection Link orders +The data within a section is stored in a @dfn{link_order}. +These are much like the fixups in @code{gas}. The link_order +abstraction allows a section to grow and shrink within itself. + +A link_order knows how big it is, and which is the next +link_order and where the raw data for it is; it also points to +a list of relocations which apply to it. + +The link_order is used by the linker to perform relaxing on +final code. The compiler creates code which is as big as +necessary to make it work without relaxing, and the user can +select whether to relax. Sometimes relaxing takes a lot of +time. The linker runs around the relocations to see if any +are attached to data which can be shrunk, if so it does it on +a link_order by link_order basis. + + +@node typedef asection, section prototypes, Section Output, Sections +@subsection typedef asection +Here is the section structure: + + +@example +typedef struct bfd_section +@{ + /* The name of the section; the name isn't a copy, the pointer is + the same as that passed to bfd_make_section. */ + const char *name; + + /* The next section in the list belonging to the BFD, or NULL. */ + struct bfd_section *next; + + /* The previous section in the list belonging to the BFD, or NULL. */ + struct bfd_section *prev; + + /* A unique sequence number. */ + unsigned int id; + + /* A unique section number which can be used by assembler to + distinguish different sections with the same section name. */ + unsigned int section_id; + + /* Which section in the bfd; 0..n-1 as sections are created in a bfd. */ + unsigned int index; + + /* The field flags contains attributes of the section. Some + flags are read in from the object file, and some are + synthesized from other information. */ + flagword flags; + +#define SEC_NO_FLAGS 0x0 + + /* Tells the OS to allocate space for this section when loading. + This is clear for a section containing debug information only. */ +#define SEC_ALLOC 0x1 + + /* Tells the OS to load the section from the file when loading. + This is clear for a .bss section. */ +#define SEC_LOAD 0x2 + + /* The section contains data still to be relocated, so there is + some relocation information too. */ +#define SEC_RELOC 0x4 + + /* A signal to the OS that the section contains read only data. */ +#define SEC_READONLY 0x8 + + /* The section contains code only. */ +#define SEC_CODE 0x10 + + /* The section contains data only. */ +#define SEC_DATA 0x20 + + /* The section will reside in ROM. */ +#define SEC_ROM 0x40 + + /* The section contains constructor information. This section + type is used by the linker to create lists of constructors and + destructors used by @code{g++}. When a back end sees a symbol + which should be used in a constructor list, it creates a new + section for the type of name (e.g., @code{__CTOR_LIST__}), attaches + the symbol to it, and builds a relocation. To build the lists + of constructors, all the linker has to do is catenate all the + sections called @code{__CTOR_LIST__} and relocate the data + contained within - exactly the operations it would peform on + standard data. */ +#define SEC_CONSTRUCTOR 0x80 + + /* The section has contents - a data section could be + @code{SEC_ALLOC} | @code{SEC_HAS_CONTENTS}; a debug section could be + @code{SEC_HAS_CONTENTS} */ +#define SEC_HAS_CONTENTS 0x100 + + /* An instruction to the linker to not output the section + even if it has information which would normally be written. */ +#define SEC_NEVER_LOAD 0x200 + + /* The section contains thread local data. */ +#define SEC_THREAD_LOCAL 0x400 + + /* The section's size is fixed. Generic linker code will not + recalculate it and it is up to whoever has set this flag to + get the size right. */ +#define SEC_FIXED_SIZE 0x800 + + /* The section contains common symbols (symbols may be defined + multiple times, the value of a symbol is the amount of + space it requires, and the largest symbol value is the one + used). Most targets have exactly one of these (which we + translate to bfd_com_section_ptr), but ECOFF has two. */ +#define SEC_IS_COMMON 0x1000 + + /* The section contains only debugging information. For + example, this is set for ELF .debug and .stab sections. + strip tests this flag to see if a section can be + discarded. */ +#define SEC_DEBUGGING 0x2000 + + /* The contents of this section are held in memory pointed to + by the contents field. This is checked by bfd_get_section_contents, + and the data is retrieved from memory if appropriate. */ +#define SEC_IN_MEMORY 0x4000 + + /* The contents of this section are to be excluded by the + linker for executable and shared objects unless those + objects are to be further relocated. */ +#define SEC_EXCLUDE 0x8000 + + /* The contents of this section are to be sorted based on the sum of + the symbol and addend values specified by the associated relocation + entries. Entries without associated relocation entries will be + appended to the end of the section in an unspecified order. */ +#define SEC_SORT_ENTRIES 0x10000 + + /* When linking, duplicate sections of the same name should be + discarded, rather than being combined into a single section as + is usually done. This is similar to how common symbols are + handled. See SEC_LINK_DUPLICATES below. */ +#define SEC_LINK_ONCE 0x20000 + + /* If SEC_LINK_ONCE is set, this bitfield describes how the linker + should handle duplicate sections. */ +#define SEC_LINK_DUPLICATES 0xc0000 + + /* This value for SEC_LINK_DUPLICATES means that duplicate + sections with the same name should simply be discarded. */ +#define SEC_LINK_DUPLICATES_DISCARD 0x0 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if there are any duplicate sections, although + it should still only link one copy. */ +#define SEC_LINK_DUPLICATES_ONE_ONLY 0x40000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections are a different size. */ +#define SEC_LINK_DUPLICATES_SAME_SIZE 0x80000 + + /* This value for SEC_LINK_DUPLICATES means that the linker + should warn if any duplicate sections contain different + contents. */ +#define SEC_LINK_DUPLICATES_SAME_CONTENTS \ + (SEC_LINK_DUPLICATES_ONE_ONLY | SEC_LINK_DUPLICATES_SAME_SIZE) + + /* This section was created by the linker as part of dynamic + relocation or other arcane processing. It is skipped when + going through the first-pass output, trusting that someone + else up the line will take care of it later. */ +#define SEC_LINKER_CREATED 0x100000 + + /* This section contains a section ID to distinguish different + sections with the same section name. */ +#define SEC_ASSEMBLER_SECTION_ID 0x100000 + + /* This section should not be subject to garbage collection. + Also set to inform the linker that this section should not be + listed in the link map as discarded. */ +#define SEC_KEEP 0x200000 + + /* This section contains "short" data, and should be placed + "near" the GP. */ +#define SEC_SMALL_DATA 0x400000 + + /* Attempt to merge identical entities in the section. + Entity size is given in the entsize field. */ +#define SEC_MERGE 0x800000 + + /* If given with SEC_MERGE, entities to merge are zero terminated + strings where entsize specifies character size instead of fixed + size entries. */ +#define SEC_STRINGS 0x1000000 + + /* This section contains data about section groups. */ +#define SEC_GROUP 0x2000000 + + /* The section is a COFF shared library section. This flag is + only for the linker. If this type of section appears in + the input file, the linker must copy it to the output file + without changing the vma or size. FIXME: Although this + was originally intended to be general, it really is COFF + specific (and the flag was renamed to indicate this). It + might be cleaner to have some more general mechanism to + allow the back end to control what the linker does with + sections. */ +#define SEC_COFF_SHARED_LIBRARY 0x4000000 + + /* This input section should be copied to output in reverse order + as an array of pointers. This is for ELF linker internal use + only. */ +#define SEC_ELF_REVERSE_COPY 0x4000000 + + /* This section contains data which may be shared with other + executables or shared objects. This is for COFF only. */ +#define SEC_COFF_SHARED 0x8000000 + + /* Indicate that section has the purecode flag set. */ +#define SEC_ELF_PURECODE 0x8000000 + + /* When a section with this flag is being linked, then if the size of + the input section is less than a page, it should not cross a page + boundary. If the size of the input section is one page or more, + it should be aligned on a page boundary. This is for TI + TMS320C54X only. */ +#define SEC_TIC54X_BLOCK 0x10000000 + + /* This section has the SHF_X86_64_LARGE flag. This is ELF x86-64 only. */ +#define SEC_ELF_LARGE 0x10000000 + + /* Conditionally link this section; do not link if there are no + references found to any symbol in the section. This is for TI + TMS320C54X only. */ +#define SEC_TIC54X_CLINK 0x20000000 + + /* This section contains vliw code. This is for Toshiba MeP only. */ +#define SEC_MEP_VLIW 0x20000000 + + /* All symbols, sizes and relocations in this section are octets + instead of bytes. Required for DWARF debug sections as DWARF + information is organized in octets, not bytes. */ +#define SEC_ELF_OCTETS 0x40000000 + + /* Indicate that section has the no read flag set. This happens + when memory read flag isn't set. */ +#define SEC_COFF_NOREAD 0x40000000 + + /* End of section flags. */ + + /* Some internal packed boolean fields. */ + + /* See the vma field. */ + unsigned int user_set_vma : 1; + + /* A mark flag used by some of the linker backends. */ + unsigned int linker_mark : 1; + + /* Another mark flag used by some of the linker backends. Set for + output sections that have an input section. */ + unsigned int linker_has_input : 1; + + /* Mark flag used by some linker backends for garbage collection. */ + unsigned int gc_mark : 1; + + /* Section compression status. */ + unsigned int compress_status : 2; +#define COMPRESS_SECTION_NONE 0 +#define COMPRESS_SECTION_DONE 1 +#define DECOMPRESS_SECTION_ZLIB 2 +#define DECOMPRESS_SECTION_ZSTD 3 + + /* The following flags are used by the ELF linker. */ + + /* Mark sections which have been allocated to segments. */ + unsigned int segment_mark : 1; + + /* Type of sec_info information. */ + unsigned int sec_info_type:3; +#define SEC_INFO_TYPE_NONE 0 +#define SEC_INFO_TYPE_STABS 1 +#define SEC_INFO_TYPE_MERGE 2 +#define SEC_INFO_TYPE_EH_FRAME 3 +#define SEC_INFO_TYPE_JUST_SYMS 4 +#define SEC_INFO_TYPE_TARGET 5 +#define SEC_INFO_TYPE_EH_FRAME_ENTRY 6 +#define SEC_INFO_TYPE_SFRAME 7 + + /* Nonzero if this section uses RELA relocations, rather than REL. */ + unsigned int use_rela_p:1; + + /* Nonzero if this section contents are mmapped, rather than malloced. */ + unsigned int mmapped_p:1; + + /* Bits used by various backends. The generic code doesn't touch + these fields. */ + + unsigned int sec_flg0:1; + unsigned int sec_flg1:1; + unsigned int sec_flg2:1; + unsigned int sec_flg3:1; + unsigned int sec_flg4:1; + unsigned int sec_flg5:1; + + /* End of internal packed boolean fields. */ + + /* The virtual memory address of the section - where it will be + at run time. The symbols are relocated against this. The + user_set_vma flag is maintained by bfd; if it's not set, the + backend can assign addresses (for example, in @code{a.out}, where + the default address for @code{.data} is dependent on the specific + target and various flags). */ + bfd_vma vma; + + /* The load address of the section - where it would be in a + rom image; really only used for writing section header + information. */ + bfd_vma lma; + + /* The size of the section in *octets*, as it will be output. + Contains a value even if the section has no contents (e.g., the + size of @code{.bss}). */ + bfd_size_type size; + + /* For input sections, the original size on disk of the section, in + octets. This field should be set for any section whose size is + changed by linker relaxation. It is required for sections where + the linker relaxation scheme doesn't cache altered section and + reloc contents (stabs, eh_frame, SEC_MERGE, some coff relaxing + targets), and thus the original size needs to be kept to read the + section multiple times. For output sections, rawsize holds the + section size calculated on a previous linker relaxation pass. */ + bfd_size_type rawsize; + + /* The compressed size of the section in octets. */ + bfd_size_type compressed_size; + + /* If this section is going to be output, then this value is the + offset in *bytes* into the output section of the first byte in the + input section (byte ==> smallest addressable unit on the + target). In most cases, if this was going to start at the + 100th octet (8-bit quantity) in the output section, this value + would be 100. However, if the target byte size is 16 bits + (bfd_octets_per_byte is "2"), this value would be 50. */ + bfd_vma output_offset; + + /* The output section through which to map on output. */ + struct bfd_section *output_section; + + /* If an input section, a pointer to a vector of relocation + records for the data in this section. */ + struct reloc_cache_entry *relocation; + + /* If an output section, a pointer to a vector of pointers to + relocation records for the data in this section. */ + struct reloc_cache_entry **orelocation; + + /* The number of relocation records in one of the above. */ + unsigned reloc_count; + + /* The alignment requirement of the section, as an exponent of 2 - + e.g., 3 aligns to 2^3 (or 8). */ + unsigned int alignment_power; + + /* Information below is back end specific - and not always used + or updated. */ + + /* File position of section data. */ + file_ptr filepos; + + /* File position of relocation info. */ + file_ptr rel_filepos; + + /* File position of line data. */ + file_ptr line_filepos; + + /* Pointer to data for applications. */ + void *userdata; + + /* If the SEC_IN_MEMORY flag is set, this points to the actual + contents. */ + bfd_byte *contents; + + /* Attached line number information. */ + alent *lineno; + + /* Number of line number records. */ + unsigned int lineno_count; + + /* Entity size for merging purposes. */ + unsigned int entsize; + + /* Points to the kept section if this section is a link-once section, + and is discarded. */ + struct bfd_section *kept_section; + + /* When a section is being output, this value changes as more + linenumbers are written out. */ + file_ptr moving_line_filepos; + + /* What the section number is in the target world. */ + int target_index; + + void *used_by_bfd; + + /* If this is a constructor section then here is a list of the + relocations created to relocate items within it. */ + struct relent_chain *constructor_chain; + + /* The BFD which owns the section. */ + bfd *owner; + + /* A symbol which points at this section only. */ + struct bfd_symbol *symbol; + + /* Early in the link process, map_head and map_tail are used to build + a list of input sections attached to an output section. Later, + output sections use these fields for a list of bfd_link_order + structs. The linked_to_symbol_name field is for ELF assembler + internal use. */ + union @{ + struct bfd_link_order *link_order; + struct bfd_section *s; + const char *linked_to_symbol_name; + @} map_head, map_tail; + + /* Points to the output section this section is already assigned to, + if any. This is used when support for non-contiguous memory + regions is enabled. */ + struct bfd_section *already_assigned; + + /* Explicitly specified section type, if non-zero. */ + unsigned int type; + +@} asection; + +@end example + +@node section prototypes, , typedef asection, Sections +@subsection Section prototypes +These are the functions exported by the section handling part of BFD. + +@findex bfd_section_list_clear +@subsubsection @code{bfd_section_list_clear} +@deftypefn {Function} void bfd_section_list_clear (bfd *); +Clears the section list, and also resets the section count and +hash table entries. + +@end deftypefn +@findex bfd_get_section_by_name +@subsubsection @code{bfd_get_section_by_name} +@deftypefn {Function} asection *bfd_get_section_by_name (bfd *abfd, const char *name); +Return the most recently created section attached to @var{abfd} +named @var{name}. Return NULL if no such section exists. + +@end deftypefn +@findex bfd_get_next_section_by_name +@subsubsection @code{bfd_get_next_section_by_name} +@deftypefn {Function} asection *bfd_get_next_section_by_name (bfd *ibfd, asection *sec); +Given @var{sec} is a section returned by @code{bfd_get_section_by_name}, +return the next most recently created section attached to the same +BFD with the same name, or if no such section exists in the same BFD and +IBFD is non-NULL, the next section with the same name in any input +BFD following IBFD. Return NULL on finding no section. + +@end deftypefn +@findex bfd_get_linker_section +@subsubsection @code{bfd_get_linker_section} +@deftypefn {Function} asection *bfd_get_linker_section (bfd *abfd, const char *name); +Return the linker created section attached to @var{abfd} +named @var{name}. Return NULL if no such section exists. + +@end deftypefn +@findex bfd_get_section_by_name_if +@subsubsection @code{bfd_get_section_by_name_if} +@deftypefn {Function} asection *bfd_get_section_by_name_if (bfd *abfd, const char *name, bool (*func) (bfd *abfd, asection *sect, void *obj), void *obj); +Call the provided function @var{func} for each section +attached to the BFD @var{abfd} whose name matches @var{name}, +passing @var{obj} as an argument. The function will be called +as if by + +@example + func (abfd, the_section, obj); +@end example + +It returns the first section for which @var{func} returns true, +otherwise @code{NULL}. + +@end deftypefn +@findex bfd_get_unique_section_name +@subsubsection @code{bfd_get_unique_section_name} +@deftypefn {Function} char *bfd_get_unique_section_name (bfd *abfd, const char *templat, int *count); +Invent a section name that is unique in @var{abfd} by tacking +a dot and a digit suffix onto the original @var{templat}. If +@var{count} is non-NULL, then it specifies the first number +tried as a suffix to generate a unique name. The value +pointed to by @var{count} will be incremented in this case. + +@end deftypefn +@findex bfd_make_section_old_way +@subsubsection @code{bfd_make_section_old_way} +@deftypefn {Function} asection *bfd_make_section_old_way (bfd *abfd, const char *name); +Create a new empty section called @var{name} +and attach it to the end of the chain of sections for the +BFD @var{abfd}. An attempt to create a section with a name which +is already in use returns its pointer without changing the +section chain. + +It has the funny name since this is the way it used to be +before it was rewritten.... + +Possible errors are: +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - +If output has already started for this BFD. +@item +@code{bfd_error_no_memory} - +If memory allocation fails. +@end itemize + +@end deftypefn +@findex bfd_make_section_anyway_with_flags +@subsubsection @code{bfd_make_section_anyway_with_flags} +@deftypefn {Function} asection *bfd_make_section_anyway_with_flags (bfd *abfd, const char *name, flagword flags); +Create a new empty section called @var{name} and attach it to the end of +the chain of sections for @var{abfd}. Create a new section even if there +is already a section with that name. Also set the attributes of the +new section to the value @var{flags}. + +Return @code{NULL} and set @code{bfd_error} on error; possible errors are: +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}. +@item +@code{bfd_error_no_memory} - If memory allocation fails. +@end itemize + +@end deftypefn +@findex bfd_make_section_anyway +@subsubsection @code{bfd_make_section_anyway} +@deftypefn {Function} asection *bfd_make_section_anyway (bfd *abfd, const char *name); +Create a new empty section called @var{name} and attach it to the end of +the chain of sections for @var{abfd}. Create a new section even if there +is already a section with that name. + +Return @code{NULL} and set @code{bfd_error} on error; possible errors are: +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - If output has already started for @var{abfd}. +@item +@code{bfd_error_no_memory} - If memory allocation fails. +@end itemize + +@end deftypefn +@findex bfd_make_section_with_flags +@subsubsection @code{bfd_make_section_with_flags} +@deftypefn {Function} asection *bfd_make_section_with_flags (bfd *, const char *name, flagword flags); +Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling +bfd_set_error ()) without changing the section chain if there is already a +section named @var{name}. Also set the attributes of the new section to +the value @var{flags}. If there is an error, return @code{NULL} and set +@code{bfd_error}. + +@end deftypefn +@findex bfd_make_section +@subsubsection @code{bfd_make_section} +@deftypefn {Function} asection *bfd_make_section (bfd *, const char *name); +Like @code{bfd_make_section_anyway}, but return @code{NULL} (without calling +bfd_set_error ()) without changing the section chain if there is already a +section named @var{name}. If there is an error, return @code{NULL} and set +@code{bfd_error}. + +@end deftypefn +@findex bfd_set_section_flags +@subsubsection @code{bfd_set_section_flags} +@deftypefn {Function} bool bfd_set_section_flags (asection *sec, flagword flags); +Set the attributes of the section @var{sec} to the value @var{flags}. +Return @code{TRUE} on success, @code{FALSE} on error. Possible error +returns are: + +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - +The section cannot have one or more of the attributes +requested. For example, a .bss section in @code{a.out} may not +have the @code{SEC_HAS_CONTENTS} field set. +@end itemize + +@end deftypefn +@findex bfd_rename_section +@subsubsection @code{bfd_rename_section} +@deftypefn {Function} void bfd_rename_section (asection *sec, const char *newname); +Rename section @var{sec} to @var{newname}. + +@end deftypefn +@findex bfd_map_over_sections +@subsubsection @code{bfd_map_over_sections} +@deftypefn {Function} void bfd_map_over_sections (bfd *abfd, void (*func) (bfd *abfd, asection *sect, void *obj), void *obj); +Call the provided function @var{func} for each section +attached to the BFD @var{abfd}, passing @var{obj} as an +argument. The function will be called as if by + +@example + func (abfd, the_section, obj); +@end example + +This is the preferred method for iterating over sections; an +alternative would be to use a loop: + +@example + asection *p; + for (p = abfd->sections; p != NULL; p = p->next) + func (abfd, p, ...) +@end example + +@end deftypefn +@findex bfd_sections_find_if +@subsubsection @code{bfd_sections_find_if} +@deftypefn {Function} asection *bfd_sections_find_if (bfd *abfd, bool (*operation) (bfd *abfd, asection *sect, void *obj), void *obj); +Call the provided function @var{operation} for each section +attached to the BFD @var{abfd}, passing @var{obj} as an +argument. The function will be called as if by + +@example + operation (abfd, the_section, obj); +@end example + +It returns the first section for which @var{operation} returns true. + +@end deftypefn +@findex bfd_set_section_size +@subsubsection @code{bfd_set_section_size} +@deftypefn {Function} bool bfd_set_section_size (asection *sec, bfd_size_type val); +Set @var{sec} to the size @var{val}. If the operation is +ok, then @code{TRUE} is returned, else @code{FALSE}. + +Possible error returns: +@itemize @bullet + +@item +@code{bfd_error_invalid_operation} - +Writing has started to the BFD, so setting the size is invalid. +@end itemize + +@end deftypefn +@findex bfd_set_section_contents +@subsubsection @code{bfd_set_section_contents} +@deftypefn {Function} bool bfd_set_section_contents (bfd *abfd, asection *section, const void *data, file_ptr offset, bfd_size_type count); +Sets the contents of the section @var{section} in BFD +@var{abfd} to the data starting in memory at @var{location}. +The data is written to the output section starting at offset +@var{offset} for @var{count} octets. + +Normally @code{TRUE} is returned, but @code{FALSE} is returned if +there was an error. Possible error returns are: +@itemize @bullet + +@item +@code{bfd_error_no_contents} - +The output section does not have the @code{SEC_HAS_CONTENTS} +attribute, so nothing can be written to it. +@item +@code{bfd_error_bad_value} - +The section is unable to contain all of the data. +@item +@code{bfd_error_invalid_operation} - +The BFD is not writeable. +@item +and some more too. +@end itemize +This routine is front end to the back end function +@code{_bfd_set_section_contents}. + +@end deftypefn +@findex bfd_get_section_contents +@subsubsection @code{bfd_get_section_contents} +@deftypefn {Function} bool bfd_get_section_contents (bfd *abfd, asection *section, void *location, file_ptr offset, bfd_size_type count); +Read data from @var{section} in BFD @var{abfd} +into memory starting at @var{location}. The data is read at an +offset of @var{offset} from the start of the input section, +and is read for @var{count} bytes. + +If the contents of a constructor with the @code{SEC_CONSTRUCTOR} +flag set are requested or if the section does not have the +@code{SEC_HAS_CONTENTS} flag set, then the @var{location} is filled +with zeroes. If no errors occur, @code{TRUE} is returned, else +@code{FALSE}. + +@end deftypefn +@findex bfd_malloc_and_get_section +@subsubsection @code{bfd_malloc_and_get_section} +@deftypefn {Function} bool bfd_malloc_and_get_section (bfd *abfd, asection *section, bfd_byte **buf); +Read all data from @var{section} in BFD @var{abfd} +into a buffer, *@var{buf}, malloc'd by this function. +Return @code{true} on success, @code{false} on failure in which +case *@var{buf} will be NULL. + +@end deftypefn +@findex bfd_copy_private_section_data +@subsubsection @code{bfd_copy_private_section_data} +@deftypefn {Function} bool bfd_copy_private_section_data (bfd *ibfd, asection *isec, bfd *obfd, asection *osec); +Copy private section information from @var{isec} in the BFD +@var{ibfd} to the section @var{osec} in the BFD @var{obfd}. +Return @code{TRUE} on success, @code{FALSE} on error. Possible error +returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{osec}. +@end itemize +@example +#define bfd_copy_private_section_data(ibfd, isection, obfd, osection) \ + BFD_SEND (obfd, _bfd_copy_private_section_data, \ + (ibfd, isection, obfd, osection)) +@end example + +@end deftypefn +@findex bfd_generic_is_group_section +@subsubsection @code{bfd_generic_is_group_section} +@deftypefn {Function} bool bfd_generic_is_group_section (bfd *, const asection *sec); +Returns TRUE if @var{sec} is a member of a group. + +@end deftypefn +@findex bfd_generic_group_name +@subsubsection @code{bfd_generic_group_name} +@deftypefn {Function} const char *bfd_generic_group_name (bfd *, const asection *sec); +Returns group name if @var{sec} is a member of a group. + +@end deftypefn +@findex bfd_generic_discard_group +@subsubsection @code{bfd_generic_discard_group} +@deftypefn {Function} bool bfd_generic_discard_group (bfd *abfd, asection *group); +Remove all members of @var{group} from the output. + +@end deftypefn +@findex bfd_section_size_insane +@subsubsection @code{bfd_section_size_insane} +@deftypefn {Function} bool bfd_section_size_insane (bfd *abfd, asection *sec); +Returns true if the given section has a size that indicates +it cannot be read from file. Return false if the size is OK +or* this function can't say one way or the other. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/syms.texi 16.3-5ubuntu1/bfd/doc/syms.texi --- 16.3-5/bfd/doc/syms.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/syms.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,446 @@ +@section Symbols +BFD tries to maintain as much symbol information as it can when +it moves information from file to file. BFD passes information +to applications though the @code{asymbol} structure. When the +application requests the symbol table, BFD reads the table in +the native form and translates parts of it into the internal +format. To maintain more than the information passed to +applications, some targets keep some information ``behind the +scenes'' in a structure only the particular back end knows +about. For example, the coff back end keeps the original +symbol table structure as well as the canonical structure when +a BFD is read in. On output, the coff back end can reconstruct +the output symbol table so that no information is lost, even +information unique to coff which BFD doesn't know or +understand. If a coff symbol table were read, but were written +through an a.out back end, all the coff specific information +would be lost. The symbol table of a BFD +is not necessarily read in until a canonicalize request is +made. Then the BFD back end fills in a table provided by the +application with pointers to the canonical information. To +output symbols, the application provides BFD with a table of +pointers to pointers to @code{asymbol}s. This allows applications +like the linker to output a symbol as it was read, since the ``behind +the scenes'' information will be still available. +@menu +* Reading Symbols:: +* Writing Symbols:: +* Mini Symbols:: +* typedef asymbol:: +* symbol handling functions:: +@end menu +@node Reading Symbols, Writing Symbols, Symbols, Symbols +@subsection Reading symbols +There are two stages to reading a symbol table from a BFD: +allocating storage, and the actual reading process. This is an +excerpt from an application which reads the symbol table: + +@example + long storage_needed; + asymbol **symbol_table; + long number_of_symbols; + long i; + + storage_needed = bfd_get_symtab_upper_bound (abfd); + + if (storage_needed < 0) + FAIL + + if (storage_needed == 0) + return; + + symbol_table = xmalloc (storage_needed); + ... + number_of_symbols = + bfd_canonicalize_symtab (abfd, symbol_table); + + if (number_of_symbols < 0) + FAIL + + for (i = 0; i < number_of_symbols; i++) + process_symbol (symbol_table[i]); +@end example + +All storage for the symbols themselves is in an objalloc +connected to the BFD; it is freed when the BFD is closed. + +@node Writing Symbols, Mini Symbols, Reading Symbols, Symbols +@subsection Writing symbols +Writing of a symbol table is automatic when a BFD open for +writing is closed. The application attaches a vector of +pointers to pointers to symbols to the BFD being written, and +fills in the symbol count. The close and cleanup code reads +through the table provided and performs all the necessary +operations. The BFD output code must always be provided with an +``owned'' symbol: one which has come from another BFD, or one +which has been created using @code{bfd_make_empty_symbol}. Here is an +example showing the creation of a symbol table with only one element: + +@example + #include "sysdep.h" + #include "bfd.h" + int main (void) + @{ + bfd *abfd; + asymbol *ptrs[2]; + asymbol *new; + + abfd = bfd_openw ("foo","a.out-sunos-big"); + bfd_set_format (abfd, bfd_object); + new = bfd_make_empty_symbol (abfd); + new->name = "dummy_symbol"; + new->section = bfd_make_section_old_way (abfd, ".text"); + new->flags = BSF_GLOBAL; + new->value = 0x12345; + + ptrs[0] = new; + ptrs[1] = 0; + + bfd_set_symtab (abfd, ptrs, 1); + bfd_close (abfd); + return 0; + @} + + ./makesym + nm foo + 00012345 A dummy_symbol +@end example + +Many formats cannot represent arbitrary symbol information; for +instance, the @code{a.out} object format does not allow an +arbitrary number of sections. A symbol pointing to a section +which is not one of @code{.text}, @code{.data} or @code{.bss} cannot +be described. + +@node Mini Symbols, typedef asymbol, Writing Symbols, Symbols +@subsection Mini Symbols +Mini symbols provide read-only access to the symbol table. +They use less memory space, but require more time to access. +They can be useful for tools like nm or objdump, which may +have to handle symbol tables of extremely large executables. + +The @code{bfd_read_minisymbols} function will read the symbols +into memory in an internal form. It will return a @code{void *} +pointer to a block of memory, a symbol count, and the size of +each symbol. The pointer is allocated using @code{malloc}, and +should be freed by the caller when it is no longer needed. + +The function @code{bfd_minisymbol_to_symbol} will take a pointer +to a minisymbol, and a pointer to a structure returned by +@code{bfd_make_empty_symbol}, and return a @code{asymbol} structure. +The return value may or may not be the same as the value from +@code{bfd_make_empty_symbol} which was passed in. + + +@node typedef asymbol, symbol handling functions, Mini Symbols, Symbols +@subsection typedef asymbol +An @code{asymbol} has the form: + + +@example +typedef struct bfd_symbol +@{ + /* A pointer to the BFD which owns the symbol. This information + is necessary so that a back end can work out what additional + information (invisible to the application writer) is carried + with the symbol. + + This field is *almost* redundant, since you can use section->owner + instead, except that some symbols point to the global sections + bfd_@{abs,com,und@}_section. This could be fixed by making + these globals be per-bfd (or per-target-flavor). FIXME. */ + struct bfd *the_bfd; /* Use bfd_asymbol_bfd(sym) to access this field. */ + + /* The text of the symbol. The name is left alone, and not copied; the + application may not alter it. */ + const char *name; + + /* The value of the symbol. This really should be a union of a + numeric value with a pointer, since some flags indicate that + a pointer to another symbol is stored here. */ + symvalue value; + + /* Attributes of a symbol. */ +#define BSF_NO_FLAGS 0 + + /* The symbol has local scope; @code{static} in @code{C}. The value + is the offset into the section of the data. */ +#define BSF_LOCAL (1 << 0) + + /* The symbol has global scope; initialized data in @code{C}. The + value is the offset into the section of the data. */ +#define BSF_GLOBAL (1 << 1) + + /* The symbol has global scope and is exported. The value is + the offset into the section of the data. */ +#define BSF_EXPORT BSF_GLOBAL /* No real difference. */ + + /* A normal C symbol would be one of: + @code{BSF_LOCAL}, @code{BSF_UNDEFINED} or @code{BSF_GLOBAL}. */ + + /* The symbol is a debugging record. The value has an arbitrary + meaning, unless BSF_DEBUGGING_RELOC is also set. */ +#define BSF_DEBUGGING (1 << 2) + + /* The symbol denotes a function entry point. Used in ELF, + perhaps others someday. */ +#define BSF_FUNCTION (1 << 3) + + /* Used by the linker. */ +#define BSF_KEEP (1 << 5) + + /* An ELF common symbol. */ +#define BSF_ELF_COMMON (1 << 6) + + /* A weak global symbol, overridable without warnings by + a regular global symbol of the same name. */ +#define BSF_WEAK (1 << 7) + + /* This symbol was created to point to a section, e.g. ELF's + STT_SECTION symbols. */ +#define BSF_SECTION_SYM (1 << 8) + + /* The symbol used to be a common symbol, but now it is + allocated. */ +#define BSF_OLD_COMMON (1 << 9) + + /* In some files the type of a symbol sometimes alters its + location in an output file - ie in coff a @code{ISFCN} symbol + which is also @code{C_EXT} symbol appears where it was + declared and not at the end of a section. This bit is set + by the target BFD part to convey this information. */ +#define BSF_NOT_AT_END (1 << 10) + + /* Signal that the symbol is the label of constructor section. */ +#define BSF_CONSTRUCTOR (1 << 11) + + /* Signal that the symbol is a warning symbol. The name is a + warning. The name of the next symbol is the one to warn about; + if a reference is made to a symbol with the same name as the next + symbol, a warning is issued by the linker. */ +#define BSF_WARNING (1 << 12) + + /* Signal that the symbol is indirect. This symbol is an indirect + pointer to the symbol with the same name as the next symbol. */ +#define BSF_INDIRECT (1 << 13) + + /* BSF_FILE marks symbols that contain a file name. This is used + for ELF STT_FILE symbols. */ +#define BSF_FILE (1 << 14) + + /* Symbol is from dynamic linking information. */ +#define BSF_DYNAMIC (1 << 15) + + /* The symbol denotes a data object. Used in ELF, and perhaps + others someday. */ +#define BSF_OBJECT (1 << 16) + + /* This symbol is a debugging symbol. The value is the offset + into the section of the data. BSF_DEBUGGING should be set + as well. */ +#define BSF_DEBUGGING_RELOC (1 << 17) + + /* This symbol is thread local. Used in ELF. */ +#define BSF_THREAD_LOCAL (1 << 18) + + /* This symbol represents a complex relocation expression, + with the expression tree serialized in the symbol name. */ +#define BSF_RELC (1 << 19) + + /* This symbol represents a signed complex relocation expression, + with the expression tree serialized in the symbol name. */ +#define BSF_SRELC (1 << 20) + + /* This symbol was created by bfd_get_synthetic_symtab. */ +#define BSF_SYNTHETIC (1 << 21) + + /* This symbol is an indirect code object. Unrelated to BSF_INDIRECT. + The dynamic linker will compute the value of this symbol by + calling the function that it points to. BSF_FUNCTION must + also be also set. */ +#define BSF_GNU_INDIRECT_FUNCTION (1 << 22) + /* This symbol is a globally unique data object. The dynamic linker + will make sure that in the entire process there is just one symbol + with this name and type in use. BSF_OBJECT must also be set. */ +#define BSF_GNU_UNIQUE (1 << 23) + + /* This section symbol should be included in the symbol table. */ +#define BSF_SECTION_SYM_USED (1 << 24) + + flagword flags; + + /* A pointer to the section to which this symbol is + relative. This will always be non NULL, there are special + sections for undefined and absolute symbols. */ + struct bfd_section *section; + + /* Back end special data. */ + union + @{ + void *p; + bfd_vma i; + @} + udata; +@} +asymbol; + +@end example + +@node symbol handling functions, , typedef asymbol, Symbols +@subsection Symbol handling functions + + +@findex bfd_get_symtab_upper_bound +@subsubsection @code{bfd_get_symtab_upper_bound} +Return the number of bytes required to store a vector of pointers +to @code{asymbols} for all the symbols in the BFD @var{abfd}, +including a terminal NULL pointer. If there are no symbols in +the BFD, then return 0. If an error occurs, return -1. +@example +#define bfd_get_symtab_upper_bound(abfd) \ + BFD_SEND (abfd, _bfd_get_symtab_upper_bound, (abfd)) + +@end example + +@findex bfd_is_local_label +@subsubsection @code{bfd_is_local_label} +@deftypefn {Function} bool bfd_is_local_label (bfd *abfd, asymbol *sym); +Return TRUE if the given symbol @var{sym} in the BFD @var{abfd} is +a compiler generated local label, else return FALSE. + +@end deftypefn +@findex bfd_is_local_label_name +@subsubsection @code{bfd_is_local_label_name} +@deftypefn {Function} bool bfd_is_local_label_name (bfd *abfd, const char *name); +Return TRUE if a symbol with the name @var{name} in the BFD +@var{abfd} is a compiler generated local label, else return +FALSE. This just checks whether the name has the form of a +local label. +@example +#define bfd_is_local_label_name(abfd, name) \ + BFD_SEND (abfd, _bfd_is_local_label_name, (abfd, name)) + +@end example + +@end deftypefn +@findex bfd_is_target_special_symbol +@subsubsection @code{bfd_is_target_special_symbol} +@deftypefn {Function} bool bfd_is_target_special_symbol (bfd *abfd, asymbol *sym); +Return TRUE iff a symbol @var{sym} in the BFD @var{abfd} is something +special to the particular target represented by the BFD. Such symbols +should normally not be mentioned to the user. +@example +#define bfd_is_target_special_symbol(abfd, sym) \ + BFD_SEND (abfd, _bfd_is_target_special_symbol, (abfd, sym)) + +@end example + +@end deftypefn +@findex bfd_canonicalize_symtab +@subsubsection @code{bfd_canonicalize_symtab} +Read the symbols from the BFD @var{abfd}, and fills in +the vector @var{location} with pointers to the symbols and +a trailing NULL. +Return the actual number of symbol pointers, not +including the NULL. +@example +#define bfd_canonicalize_symtab(abfd, location) \ + BFD_SEND (abfd, _bfd_canonicalize_symtab, (abfd, location)) + +@end example + +@findex bfd_set_symtab +@subsubsection @code{bfd_set_symtab} +@deftypefn {Function} bool bfd_set_symtab (bfd *abfd, asymbol **location, unsigned int count); +Arrange that when the output BFD @var{abfd} is closed, +the table @var{location} of @var{count} pointers to symbols +will be written. + +@end deftypefn +@findex bfd_print_symbol_vandf +@subsubsection @code{bfd_print_symbol_vandf} +@deftypefn {Function} void bfd_print_symbol_vandf (bfd *abfd, void *file, asymbol *symbol); +Print the value and flags of the @var{symbol} supplied to the +stream @var{file}. + +@end deftypefn +@findex bfd_make_empty_symbol +@subsubsection @code{bfd_make_empty_symbol} +Create a new @code{asymbol} structure for the BFD @var{abfd} +and return a pointer to it. + +This routine is necessary because each back end has private +information surrounding the @code{asymbol}. Building your own +@code{asymbol} and pointing to it will not create the private +information, and will cause problems later on. +@example +#define bfd_make_empty_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_empty_symbol, (abfd)) + +@end example + +@findex _bfd_generic_make_empty_symbol +@subsubsection @code{_bfd_generic_make_empty_symbol} +@deftypefn {Function} asymbol *_bfd_generic_make_empty_symbol (bfd *); +Create a new @code{asymbol} structure for the BFD @var{abfd} +and return a pointer to it. Used by core file routines, +binary back-end and anywhere else where no private info +is needed. + +@end deftypefn +@findex bfd_make_debug_symbol +@subsubsection @code{bfd_make_debug_symbol} +Create a new @code{asymbol} structure for the BFD @var{abfd}, +to be used as a debugging symbol. +@example +#define bfd_make_debug_symbol(abfd) \ + BFD_SEND (abfd, _bfd_make_debug_symbol, (abfd)) + +@end example + +@findex bfd_decode_symclass +@subsubsection @code{bfd_decode_symclass} +@deftypefn {Function} int bfd_decode_symclass (asymbol *symbol); +Return a character corresponding to the symbol +class of @var{symbol}, or '?' for an unknown class. + +@end deftypefn +@findex bfd_is_undefined_symclass +@subsubsection @code{bfd_is_undefined_symclass} +@deftypefn {Function} bool bfd_is_undefined_symclass (int symclass); +Returns non-zero if the class symbol returned by +bfd_decode_symclass represents an undefined symbol. +Returns zero otherwise. + +@end deftypefn +@findex bfd_symbol_info +@subsubsection @code{bfd_symbol_info} +@deftypefn {Function} void bfd_symbol_info (asymbol *symbol, symbol_info *ret); +Fill in the basic info about symbol that nm needs. +Additional info may be added by the back-ends after +calling this function. + +@end deftypefn +@findex bfd_copy_private_symbol_data +@subsubsection @code{bfd_copy_private_symbol_data} +@deftypefn {Function} bool bfd_copy_private_symbol_data (bfd *ibfd, asymbol *isym, bfd *obfd, asymbol *osym); +Copy private symbol information from @var{isym} in the BFD +@var{ibfd} to the symbol @var{osym} in the BFD @var{obfd}. +Return @code{TRUE} on success, @code{FALSE} on error. Possible error +returns are: + +@itemize @bullet + +@item +@code{bfd_error_no_memory} - +Not enough memory exists to create private data for @var{osec}. +@end itemize +@example +#define bfd_copy_private_symbol_data(ibfd, isymbol, obfd, osymbol) \ + BFD_SEND (obfd, _bfd_copy_private_symbol_data, \ + (ibfd, isymbol, obfd, osymbol)) + +@end example + +@end deftypefn diff -pruN 16.3-5/bfd/doc/targets.texi 16.3-5ubuntu1/bfd/doc/targets.texi --- 16.3-5/bfd/doc/targets.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/targets.texi 2025-04-20 17:24:58.000000000 +0000 @@ -1 +1,675 @@ +@section Targets + +Each port of BFD to a different machine requires the creation +of a target back end. All the back end provides to the root +part of BFD is a structure containing pointers to functions +which perform certain low level operations on files. BFD +translates the applications's requests through a pointer into +calls to the back end routines. + +When a file is opened with @code{bfd_openr}, its format and +target are unknown. BFD uses various mechanisms to determine +how to interpret the file. The operations performed are: + +@itemize @bullet + +@item +Create a BFD by calling the internal routine +@code{_bfd_new_bfd}, then call @code{bfd_find_target} with the +target string supplied to @code{bfd_openr} and the new BFD pointer. + +@item +If a null target string was provided to @code{bfd_find_target}, +look up the environment variable @code{GNUTARGET} and use +that as the target string. + +@item +If the target string is still @code{NULL}, or the target string is +@code{default}, then use the first item in the target vector +as the target type, and set @code{target_defaulted} in the BFD to +cause @code{bfd_check_format} to loop through all the targets. +@xref{bfd_target}. @xref{Formats}. + +@item +Otherwise, inspect the elements in the target vector +one by one, until a match on target name is found. When found, +use it. + +@item +Otherwise return the error @code{bfd_error_invalid_target} to +@code{bfd_openr}. + +@item +@code{bfd_openr} attempts to open the file using +@code{bfd_open_file}, and returns the BFD. +@end itemize +Once the BFD has been opened and the target selected, the file +format may be determined. This is done by calling +@code{bfd_check_format} on the BFD with a suggested format. +If @code{target_defaulted} has been set, each possible target +type is tried to see if it recognizes the specified format. +@code{bfd_check_format} returns @code{TRUE} when the caller guesses right. +@menu +* bfd_target:: +@end menu + +@node bfd_target, , Targets, Targets + +@subsection bfd_target + + +This structure contains everything that BFD knows about a +target. It includes things like its byte order, name, and which +routines to call to do various operations. + +Every BFD points to a target structure with its @code{xvec} +member. + +The macros below are used to dispatch to functions through the +@code{bfd_target} vector. They are used in a number of macros further +down in @file{bfd.h}, and are also used when calling various +routines by hand inside the BFD implementation. The @var{arglist} +argument must be parenthesized; it contains all the arguments +to the called function. + +They make the documentation (more) unpleasant to read, so if +someone wants to fix this and not break the above, please do. +@example +#define BFD_SEND(bfd, message, arglist) \ + ((*((bfd)->xvec->message)) arglist) + +#ifdef DEBUG_BFD_SEND +#undef BFD_SEND +#define BFD_SEND(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + ((*((bfd)->xvec->message)) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) +#endif +@end example +For operations which index on the BFD format: +@example +#define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) + +#ifdef DEBUG_BFD_SEND +#undef BFD_SEND_FMT +#define BFD_SEND_FMT(bfd, message, arglist) \ + (((bfd) && (bfd)->xvec && (bfd)->xvec->message) ? \ + (((bfd)->xvec->message[(int) ((bfd)->format)]) arglist) : \ + (bfd_assert (__FILE__,__LINE__), NULL)) +#endif + +/* Defined to TRUE if unused section symbol should be kept. */ +#ifndef TARGET_KEEP_UNUSED_SECTION_SYMBOLS +#define TARGET_KEEP_UNUSED_SECTION_SYMBOLS true +#endif + +@end example +This is the structure which defines the type of BFD this is. The +@code{xvec} member of the struct @code{bfd} itself points here. Each +module that implements access to a different target under BFD, +defines one of these. + +FIXME, these names should be rationalised with the names of +the entry points which call them. Too bad we can't have one +macro to define them both! + + +@example +typedef struct bfd_target +@{ + /* Identifies the kind of target, e.g., SunOS4, Ultrix, etc. */ + const char *name; + + /* The "flavour" of a back end is a general indication about + the contents of a file. */ + enum bfd_flavour flavour; + + /* The order of bytes within the data area of a file. */ + enum bfd_endian byteorder; + + /* The order of bytes within the header parts of a file. */ + enum bfd_endian header_byteorder; + + /* A mask of all the flags which an executable may have set - + from the set @code{BFD_NO_FLAGS}, @code{HAS_RELOC}, ...@code{D_PAGED}. */ + flagword object_flags; + + /* A mask of all the flags which a section may have set - from + the set @code{SEC_NO_FLAGS}, @code{SEC_ALLOC}, ...@code{SET_NEVER_LOAD}. */ + flagword section_flags; + + /* The character normally found at the front of a symbol. + (if any), perhaps `_'. */ + char symbol_leading_char; + + /* The pad character for file names within an archive header. */ + char ar_pad_char; + + /* The maximum number of characters in an archive header. */ + unsigned char ar_max_namelen; + + /* How well this target matches, used to select between various + possible targets when more than one target matches. */ + unsigned char match_priority; + + /* TRUE if unused section symbols should be kept. */ + bool keep_unused_section_symbols; + + /* Entries for byte swapping for data. These are different from the + other entry points, since they don't take a BFD as the first argument. + Certain other handlers could do the same. */ + uint64_t (*bfd_getx64) (const void *); + int64_t (*bfd_getx_signed_64) (const void *); + void (*bfd_putx64) (uint64_t, void *); + bfd_vma (*bfd_getx32) (const void *); + bfd_signed_vma (*bfd_getx_signed_32) (const void *); + void (*bfd_putx32) (bfd_vma, void *); + bfd_vma (*bfd_getx16) (const void *); + bfd_signed_vma (*bfd_getx_signed_16) (const void *); + void (*bfd_putx16) (bfd_vma, void *); + + /* Byte swapping for the headers. */ + uint64_t (*bfd_h_getx64) (const void *); + int64_t (*bfd_h_getx_signed_64) (const void *); + void (*bfd_h_putx64) (uint64_t, void *); + bfd_vma (*bfd_h_getx32) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_32) (const void *); + void (*bfd_h_putx32) (bfd_vma, void *); + bfd_vma (*bfd_h_getx16) (const void *); + bfd_signed_vma (*bfd_h_getx_signed_16) (const void *); + void (*bfd_h_putx16) (bfd_vma, void *); + + /* Format dependent routines: these are vectors of entry points + within the target vector structure, one for each format to check. */ + + /* Check the format of a file being read. Return a @code{bfd_cleanup} on + success or zero on failure. */ + bfd_cleanup (*_bfd_check_format[bfd_type_end]) (bfd *); + + /* Set the format of a file being written. */ + bool (*_bfd_set_format[bfd_type_end]) (bfd *); + + /* Write cached information into a file being written, at @code{bfd_close}. */ + bool (*_bfd_write_contents[bfd_type_end]) (bfd *); + +@end example +The general target vector. These vectors are initialized using the +BFD_JUMP_TABLE macros. +@example + /* Generic entry points. */ +#define BFD_JUMP_TABLE_GENERIC(NAME) \ + NAME##_close_and_cleanup, \ + NAME##_bfd_free_cached_info, \ + NAME##_new_section_hook, \ + NAME##_get_section_contents + + /* Called when the BFD is being closed to do any necessary cleanup. */ + bool (*_close_and_cleanup) (bfd *); + /* Ask the BFD to free all cached information. */ + bool (*_bfd_free_cached_info) (bfd *); + /* Called when a new section is created. */ + bool (*_new_section_hook) (bfd *, sec_ptr); + /* Read the contents of a section. */ + bool (*_bfd_get_section_contents) (bfd *, sec_ptr, void *, file_ptr, + bfd_size_type); + + /* Entry points to copy private data. */ +#define BFD_JUMP_TABLE_COPY(NAME) \ + NAME##_bfd_copy_private_bfd_data, \ + NAME##_bfd_merge_private_bfd_data, \ + NAME##_init_private_section_data, \ + NAME##_bfd_copy_private_section_data, \ + NAME##_bfd_copy_private_symbol_data, \ + NAME##_bfd_copy_private_header_data, \ + NAME##_bfd_set_private_flags, \ + NAME##_bfd_print_private_bfd_data + + /* Called to copy BFD general private data from one object file + to another. */ + bool (*_bfd_copy_private_bfd_data) (bfd *, bfd *); + /* Called to merge BFD general private data from one object file + to a common output file when linking. */ + bool (*_bfd_merge_private_bfd_data) (bfd *, struct bfd_link_info *); + /* Called to initialize BFD private section data from one object file + to another. */ +#define bfd_init_private_section_data(ibfd, isec, obfd, osec, link_info) \ + BFD_SEND (obfd, _bfd_init_private_section_data, \ + (ibfd, isec, obfd, osec, link_info)) + bool (*_bfd_init_private_section_data) (bfd *, sec_ptr, bfd *, sec_ptr, + struct bfd_link_info *); + /* Called to copy BFD private section data from one object file + to another. */ + bool (*_bfd_copy_private_section_data) (bfd *, sec_ptr, bfd *, sec_ptr); + /* Called to copy BFD private symbol data from one symbol + to another. */ + bool (*_bfd_copy_private_symbol_data) (bfd *, asymbol *, + bfd *, asymbol *); + /* Called to copy BFD private header data from one object file + to another. */ + bool (*_bfd_copy_private_header_data) (bfd *, bfd *); + /* Called to set private backend flags. */ + bool (*_bfd_set_private_flags) (bfd *, flagword); + + /* Called to print private BFD data. */ + bool (*_bfd_print_private_bfd_data) (bfd *, void *); + + /* Core file entry points. */ +#define BFD_JUMP_TABLE_CORE(NAME) \ + NAME##_core_file_failing_command, \ + NAME##_core_file_failing_signal, \ + NAME##_core_file_matches_executable_p, \ + NAME##_core_file_pid + + char *(*_core_file_failing_command) (bfd *); + int (*_core_file_failing_signal) (bfd *); + bool (*_core_file_matches_executable_p) (bfd *, bfd *); + int (*_core_file_pid) (bfd *); + + /* Archive entry points. */ +#define BFD_JUMP_TABLE_ARCHIVE(NAME) \ + NAME##_slurp_armap, \ + NAME##_slurp_extended_name_table, \ + NAME##_construct_extended_name_table, \ + NAME##_truncate_arname, \ + NAME##_write_armap, \ + NAME##_read_ar_hdr, \ + NAME##_write_ar_hdr, \ + NAME##_openr_next_archived_file, \ + NAME##_get_elt_at_index, \ + NAME##_generic_stat_arch_elt, \ + NAME##_update_armap_timestamp + + bool (*_bfd_slurp_armap) (bfd *); + bool (*_bfd_slurp_extended_name_table) (bfd *); + bool (*_bfd_construct_extended_name_table) (bfd *, char **, + bfd_size_type *, + const char **); + void (*_bfd_truncate_arname) (bfd *, const char *, char *); + bool (*write_armap) (bfd *, unsigned, struct orl *, unsigned, int); + void *(*_bfd_read_ar_hdr_fn) (bfd *); + bool (*_bfd_write_ar_hdr_fn) (bfd *, bfd *); + bfd *(*openr_next_archived_file) (bfd *, bfd *); +#define bfd_get_elt_at_index(b,i) \ + BFD_SEND (b, _bfd_get_elt_at_index, (b,i)) + bfd *(*_bfd_get_elt_at_index) (bfd *, symindex); + int (*_bfd_stat_arch_elt) (bfd *, struct stat *); + bool (*_bfd_update_armap_timestamp) (bfd *); + + /* Entry points used for symbols. */ +#define BFD_JUMP_TABLE_SYMBOLS(NAME) \ + NAME##_get_symtab_upper_bound, \ + NAME##_canonicalize_symtab, \ + NAME##_make_empty_symbol, \ + NAME##_print_symbol, \ + NAME##_get_symbol_info, \ + NAME##_get_symbol_version_string, \ + NAME##_bfd_is_local_label_name, \ + NAME##_bfd_is_target_special_symbol, \ + NAME##_get_lineno, \ + NAME##_find_nearest_line, \ + NAME##_find_nearest_line_with_alt, \ + NAME##_find_line, \ + NAME##_find_inliner_info, \ + NAME##_bfd_make_debug_symbol, \ + NAME##_read_minisymbols, \ + NAME##_minisymbol_to_symbol + + long (*_bfd_get_symtab_upper_bound) (bfd *); + long (*_bfd_canonicalize_symtab) (bfd *, struct bfd_symbol **); + struct bfd_symbol * + (*_bfd_make_empty_symbol) (bfd *); + void (*_bfd_print_symbol) (bfd *, void *, struct bfd_symbol *, + bfd_print_symbol_type); +#define bfd_print_symbol(b,p,s,e) \ + BFD_SEND (b, _bfd_print_symbol, (b,p,s,e)) + void (*_bfd_get_symbol_info) (bfd *, struct bfd_symbol *, symbol_info *); +#define bfd_get_symbol_info(b,p,e) \ + BFD_SEND (b, _bfd_get_symbol_info, (b,p,e)) + const char * + (*_bfd_get_symbol_version_string) (bfd *, struct bfd_symbol *, + bool, bool *); +#define bfd_get_symbol_version_string(b,s,p,h) \ + BFD_SEND (b, _bfd_get_symbol_version_string, (b,s,p,h)) + bool (*_bfd_is_local_label_name) (bfd *, const char *); + bool (*_bfd_is_target_special_symbol) (bfd *, asymbol *); + alent * + (*_get_lineno) (bfd *, struct bfd_symbol *); + bool (*_bfd_find_nearest_line) (bfd *, struct bfd_symbol **, + struct bfd_section *, bfd_vma, + const char **, const char **, + unsigned int *, unsigned int *); + bool (*_bfd_find_nearest_line_with_alt) (bfd *, const char *, + struct bfd_symbol **, + struct bfd_section *, bfd_vma, + const char **, const char **, + unsigned int *, unsigned int *); + bool (*_bfd_find_line) (bfd *, struct bfd_symbol **, + struct bfd_symbol *, const char **, + unsigned int *); + bool (*_bfd_find_inliner_info) + (bfd *, const char **, const char **, unsigned int *); + /* Back-door to allow format-aware applications to create debug symbols + while using BFD for everything else. Currently used by the assembler + when creating COFF files. */ + asymbol * + (*_bfd_make_debug_symbol) (bfd *); +#define bfd_read_minisymbols(b, d, m, s) \ + BFD_SEND (b, _read_minisymbols, (b, d, m, s)) + long (*_read_minisymbols) (bfd *, bool, void **, unsigned int *); +#define bfd_minisymbol_to_symbol(b, d, m, f) \ + BFD_SEND (b, _minisymbol_to_symbol, (b, d, m, f)) + asymbol * + (*_minisymbol_to_symbol) (bfd *, bool, const void *, asymbol *); + + /* Routines for relocs. */ +#define BFD_JUMP_TABLE_RELOCS(NAME) \ + NAME##_get_reloc_upper_bound, \ + NAME##_canonicalize_reloc, \ + NAME##_set_reloc, \ + NAME##_bfd_reloc_type_lookup, \ + NAME##_bfd_reloc_name_lookup + + long (*_get_reloc_upper_bound) (bfd *, sec_ptr); + long (*_bfd_canonicalize_reloc) (bfd *, sec_ptr, arelent **, + struct bfd_symbol **); + void (*_bfd_set_reloc) (bfd *, sec_ptr, arelent **, unsigned int); + /* See documentation on reloc types. */ + reloc_howto_type * + (*reloc_type_lookup) (bfd *, bfd_reloc_code_real_type); + reloc_howto_type * + (*reloc_name_lookup) (bfd *, const char *); + + /* Routines used when writing an object file. */ +#define BFD_JUMP_TABLE_WRITE(NAME) \ + NAME##_set_arch_mach, \ + NAME##_set_section_contents + + bool (*_bfd_set_arch_mach) (bfd *, enum bfd_architecture, + unsigned long); + bool (*_bfd_set_section_contents) (bfd *, sec_ptr, const void *, + file_ptr, bfd_size_type); + + /* Routines used by the linker. */ +#define BFD_JUMP_TABLE_LINK(NAME) \ + NAME##_sizeof_headers, \ + NAME##_bfd_get_relocated_section_contents, \ + NAME##_bfd_relax_section, \ + NAME##_bfd_link_hash_table_create, \ + NAME##_bfd_link_add_symbols, \ + NAME##_bfd_link_just_syms, \ + NAME##_bfd_copy_link_hash_symbol_type, \ + NAME##_bfd_final_link, \ + NAME##_bfd_link_split_section, \ + NAME##_bfd_link_check_relocs, \ + NAME##_bfd_gc_sections, \ + NAME##_bfd_lookup_section_flags, \ + NAME##_bfd_merge_sections, \ + NAME##_bfd_is_group_section, \ + NAME##_bfd_group_name, \ + NAME##_bfd_discard_group, \ + NAME##_section_already_linked, \ + NAME##_bfd_define_common_symbol, \ + NAME##_bfd_link_hide_symbol, \ + NAME##_bfd_define_start_stop + + int (*_bfd_sizeof_headers) (bfd *, struct bfd_link_info *); + bfd_byte * + (*_bfd_get_relocated_section_contents) (bfd *, + struct bfd_link_info *, + struct bfd_link_order *, + bfd_byte *, bool, + struct bfd_symbol **); + + bool (*_bfd_relax_section) (bfd *, struct bfd_section *, + struct bfd_link_info *, bool *); + + /* Create a hash table for the linker. Different backends store + different information in this table. */ + struct bfd_link_hash_table * + (*_bfd_link_hash_table_create) (bfd *); + + /* Add symbols from this object file into the hash table. */ + bool (*_bfd_link_add_symbols) (bfd *, struct bfd_link_info *); + + /* Indicate that we are only retrieving symbol values from this section. */ + void (*_bfd_link_just_syms) (asection *, struct bfd_link_info *); + + /* Copy the symbol type and other attributes for a linker script + assignment of one symbol to another. */ +#define bfd_copy_link_hash_symbol_type(b, t, f) \ + BFD_SEND (b, _bfd_copy_link_hash_symbol_type, (b, t, f)) + void (*_bfd_copy_link_hash_symbol_type) (bfd *, + struct bfd_link_hash_entry *, + struct bfd_link_hash_entry *); + + /* Do a link based on the link_order structures attached to each + section of the BFD. */ + bool (*_bfd_final_link) (bfd *, struct bfd_link_info *); + + /* Should this section be split up into smaller pieces during linking. */ + bool (*_bfd_link_split_section) (bfd *, struct bfd_section *); + + /* Check the relocations in the bfd for validity. */ + bool (* _bfd_link_check_relocs)(bfd *, struct bfd_link_info *); + + /* Remove sections that are not referenced from the output. */ + bool (*_bfd_gc_sections) (bfd *, struct bfd_link_info *); + + /* Sets the bitmask of allowed and disallowed section flags. */ + bool (*_bfd_lookup_section_flags) (struct bfd_link_info *, + struct flag_info *, asection *); + + /* Attempt to merge SEC_MERGE sections. */ + bool (*_bfd_merge_sections) (bfd *, struct bfd_link_info *); + + /* Is this section a member of a group? */ + bool (*_bfd_is_group_section) (bfd *, const struct bfd_section *); + + /* The group name, if section is a member of a group. */ + const char *(*_bfd_group_name) (bfd *, const struct bfd_section *); + + /* Discard members of a group. */ + bool (*_bfd_discard_group) (bfd *, struct bfd_section *); + + /* Check if SEC has been already linked during a reloceatable or + final link. */ + bool (*_section_already_linked) (bfd *, asection *, + struct bfd_link_info *); + + /* Define a common symbol. */ + bool (*_bfd_define_common_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Hide a symbol. */ + void (*_bfd_link_hide_symbol) (bfd *, struct bfd_link_info *, + struct bfd_link_hash_entry *); + + /* Define a __start, __stop, .startof. or .sizeof. symbol. */ + struct bfd_link_hash_entry * + (*_bfd_define_start_stop) (struct bfd_link_info *, const char *, + asection *); + + /* Routines to handle dynamic symbols and relocs. */ +#define BFD_JUMP_TABLE_DYNAMIC(NAME) \ + NAME##_get_dynamic_symtab_upper_bound, \ + NAME##_canonicalize_dynamic_symtab, \ + NAME##_get_synthetic_symtab, \ + NAME##_get_dynamic_reloc_upper_bound, \ + NAME##_canonicalize_dynamic_reloc + + /* Get the amount of memory required to hold the dynamic symbols. */ + long (*_bfd_get_dynamic_symtab_upper_bound) (bfd *); + /* Read in the dynamic symbols. */ + long (*_bfd_canonicalize_dynamic_symtab) (bfd *, struct bfd_symbol **); + /* Create synthetized symbols. */ + long (*_bfd_get_synthetic_symtab) (bfd *, long, struct bfd_symbol **, + long, struct bfd_symbol **, + struct bfd_symbol **); + /* Get the amount of memory required to hold the dynamic relocs. */ + long (*_bfd_get_dynamic_reloc_upper_bound) (bfd *); + /* Read in the dynamic relocs. */ + long (*_bfd_canonicalize_dynamic_reloc) (bfd *, arelent **, + struct bfd_symbol **); + +@end example +A pointer to an alternative bfd_target in case the current one is not +satisfactory. This can happen when the target cpu supports both big +and little endian code, and target chosen by the linker has the wrong +endianness. The function open_output() in ld/ldlang.c uses this field +to find an alternative output format that is suitable. +@example + /* Opposite endian version of this target. */ + const struct bfd_target *alternative_target; + + /* Data for use by back-end routines, which isn't + generic enough to belong in this structure. */ + const void *backend_data; + +@} bfd_target; + +static inline const char * +bfd_get_target (const bfd *abfd) +@{ + return abfd->xvec->name; +@} + +static inline enum bfd_flavour +bfd_get_flavour (const bfd *abfd) +@{ + return abfd->xvec->flavour; +@} + +static inline flagword +bfd_applicable_file_flags (const bfd *abfd) +@{ + return abfd->xvec->object_flags; +@} + +static inline bool +bfd_family_coff (const bfd *abfd) +@{ + return (bfd_get_flavour (abfd) == bfd_target_coff_flavour + || bfd_get_flavour (abfd) == bfd_target_xcoff_flavour); +@} + +static inline bool +bfd_big_endian (const bfd *abfd) +@{ + return abfd->xvec->byteorder == BFD_ENDIAN_BIG; +@} +static inline bool +bfd_little_endian (const bfd *abfd) +@{ + return abfd->xvec->byteorder == BFD_ENDIAN_LITTLE; +@} + +static inline bool +bfd_header_big_endian (const bfd *abfd) +@{ + return abfd->xvec->header_byteorder == BFD_ENDIAN_BIG; +@} + +static inline bool +bfd_header_little_endian (const bfd *abfd) +@{ + return abfd->xvec->header_byteorder == BFD_ENDIAN_LITTLE; +@} + +static inline flagword +bfd_applicable_section_flags (const bfd *abfd) +@{ + return abfd->xvec->section_flags; +@} + +static inline char +bfd_get_symbol_leading_char (const bfd *abfd) +@{ + return abfd->xvec->symbol_leading_char; +@} + +static inline enum bfd_flavour +bfd_asymbol_flavour (const asymbol *sy) +@{ + if ((sy->flags & BSF_SYNTHETIC) != 0) + return bfd_target_unknown_flavour; + return sy->the_bfd->xvec->flavour; +@} + +static inline bool +bfd_keep_unused_section_symbols (const bfd *abfd) +@{ + return abfd->xvec->keep_unused_section_symbols; +@} + +@end example +@findex bfd_set_default_target +@subsubsection @code{bfd_set_default_target} +@deftypefn {Function} bool bfd_set_default_target (const char *name); +Set the default target vector to use when recognizing a BFD. +This takes the name of the target, which may be a BFD target +name or a configuration triplet. + +@end deftypefn +@findex bfd_find_target +@subsubsection @code{bfd_find_target} +@deftypefn {Function} const bfd_target *bfd_find_target (const char *target_name, bfd *abfd); +Return a pointer to the transfer vector for the object target +named @var{target_name}. If @var{target_name} is @code{NULL}, +choose the one in the environment variable @code{GNUTARGET}; if +that is null or not defined, then choose the first entry in the +target list. Passing in the string "default" or setting the +environment variable to "default" will cause the first entry in +the target list to be returned, and "target_defaulted" will be +set in the BFD if @var{abfd} isn't @code{NULL}. This causes +@code{bfd_check_format} to loop over all the targets to find the +one that matches the file being read. + +@end deftypefn +@findex bfd_get_target_info +@subsubsection @code{bfd_get_target_info} +@deftypefn {Function} const bfd_target *bfd_get_target_info (const char *target_name, bfd *abfd, bool *is_bigendian, int *underscoring, const char **def_target_arch); +Return a pointer to the transfer vector for the object target +named @var{target_name}. If @var{target_name} is @code{NULL}, +choose the one in the environment variable @code{GNUTARGET}; if +that is null or not defined, then choose the first entry in the +target list. Passing in the string "default" or setting the +environment variable to "default" will cause the first entry in +the target list to be returned, and "target_defaulted" will be +set in the BFD if @var{abfd} isn't @code{NULL}. This causes +@code{bfd_check_format} to loop over all the targets to find the +one that matches the file being read. +If @var{is_bigendian} is not @code{NULL}, then set this value to target's +endian mode. True for big-endian, FALSE for little-endian or for +invalid target. +If @var{underscoring} is not @code{NULL}, then set this value to target's +underscoring mode. Zero for none-underscoring, -1 for invalid target, +else the value of target vector's symbol underscoring. +If @var{def_target_arch} is not @code{NULL}, then set it to the architecture +string specified by the target_name. + +@end deftypefn +@findex bfd_target_list +@subsubsection @code{bfd_target_list} +@deftypefn {Function} const char ** bfd_target_list (void); +Return a freshly malloced NULL-terminated +vector of the names of all the valid BFD targets. Do not +modify the names. + +@end deftypefn +@findex bfd_iterate_over_targets +@subsubsection @code{bfd_iterate_over_targets} +@deftypefn {Function} const bfd_target *bfd_iterate_over_targets (int (*func) (const bfd_target *, void *), void *data); +Call @var{func} for each target in the list of BFD target +vectors, passing @var{data} to @var{func}. Stop iterating if +@var{func} returns a non-zero result, and return that target +vector. Return NULL if @var{func} always returns zero. + +@end deftypefn +@findex bfd_flavour_name +@subsubsection @code{bfd_flavour_name} +@deftypefn {Function} const char *bfd_flavour_name (enum bfd_flavour flavour); +Return the string form of @var{flavour}. + +@end deftypefn diff -pruN 16.3-5/bfd/doc/webassembly.texi 16.3-5ubuntu1/bfd/doc/webassembly.texi --- 16.3-5/bfd/doc/webassembly.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/bfd/doc/webassembly.texi 2024-12-29 02:50:06.000000000 +0000 @@ -1 +1,33 @@ +@section WebAssembly backend +The WebAssembly module file format, at present, is a very simple +object file format with up to 11 numbered sections plus named +``custom'' sections. At present, there is no standard for relocations +or symbols, though a @code{"name"} subsection can assign names to +function indices and local variables. +As such, it offers no real advantages over ELF, and intermediate ELF +files can be used to produce WebAssembly modules. The WebAssembly +backend aims to enable the opposite: reading a WebAssembly module and +producing an ELF file containing the same information, which can then +be manipulated and inspected with standard tools. + +When writing WebAssembly modules, the WebAssembly backend attempts to +determine based on the section name whether to use a numeric section +id, a named section header, or to include the section verbatim, +assuming it already contains any necessary header. + +Function names are supported as symbols; local names and WebAssembly +relocation sections are currently unsupported. + +There are slight differences in the LEB128 integer implementations +between the WebAssembly specification and the BFD code; these result +in some malformed WebAssembly modules being treated as valid. + +@menu +* File layout:: +@end menu + +@node File layout, WebAssembly +@subsection File layout +For a description of the WebAssembly file format, see +@url{https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md}. diff -pruN 16.3-5/debian/changelog 16.3-5ubuntu1/debian/changelog --- 16.3-5/debian/changelog 2025-09-05 18:20:51.000000000 +0000 +++ 16.3-5ubuntu1/debian/changelog 2025-11-06 07:32:59.000000000 +0000 @@ -1,3 +1,38 @@ +gdb (16.3-5ubuntu1) resolute; urgency=medium + + * Merge with Debian unstable (LP: #2130723). Remaining changes: + - import upstream tarball for building manpages + - d/control: + + added gdb-doc package + + added (build-)dependency libc6-dbg on armhf + + exclude libsource-highlight-dev on i386 + + moved libc-dbg from suggests to recommends + - d/control.in: + + added (build-)dependency libc6-dbg on armhf + + exclude libsource-highlight-dev on i386 + + moved libc-dbg from suggests to recommends + - d/p/gdb-strings.patch: fix grammar in warning message + - d/p/ptrace-error-verbosity.patch: try to make the PTRACE scope sysctl + more discoverable via a verbose error message when failures happen. + - d/p/series: disable gfdl-dont-build-manpages.patch + - debian/gdb.install & debian/gdbserver.install: + + include manpages in binary packages + - d/rules: + + skip tests on armhf, hanging on the buildds + + disable lto on ppc64el + + configure with --disable-werror + + disable configure with --disable-sim + + clean gdb/doc/GDBvn.texi before build + + show test summary after test run + + disable man-page installation (moved to *.install files) + * Drop Chnges: + - d/rules: + + explicitly build with hardening=-all,+format. + This was not doing anything - DEB_BUILD_MAINT_OPTIONS + were overriden to hardening=+all on the next line. + + -- Vladimir Petko Thu, 06 Nov 2025 08:32:59 +0100 + gdb (16.3-5) unstable; urgency=medium * d/rules: Remove unused FORCE_CONTROL variable. @@ -41,6 +76,46 @@ gdb (16.3-2) unstable; urgency=medium -- Sergio Durigan Junior Sat, 23 Aug 2025 20:18:48 -0400 +gdb (16.3-1ubuntu2) questing; urgency=medium + + * Rebuild to include updated RISC-V base ISA RVA23 + + -- Heinrich Schuchardt Thu, 28 Aug 2025 19:19:04 +0000 + +gdb (16.3-1ubuntu1) questing; urgency=medium + + * Merge with Debian unstable (LP: #2118491). Remaining changes: + - import upstream tarball for building manpages + - d/control: + + added gdb-doc package + + added (build-)dependency libc6-dbg on armhf + + exclude libsource-highlight-dev on i386 + + moved libc-dbg from suggests to recommends + - d/control.in: + + added (build-)dependency libc6-dbg on armhf + + exclude libsource-highlight-dev on i386 + + moved libc-dbg from suggests to recommends + - d/p/gdb-strings.patch: fix grammar in warning message + - d/p/ptrace-error-verbosity.patch: try to make the PTRACE scope sysctl + more discoverable via a verbose error message when failures happen. + - d/p/series: disable gfdl-dont-build-manpages.patch + - debian/gdb.install & debian/gdbserver.install: + + include manpages in binary packages + - d/rules: + + skip tests on armhf, hanging on the buildds + + disable lto on ppc64el + + configure with --disable-werror + + disable configure with --disable-sim + + clean gdb/doc/GDBvn.texi before build + + show test summary after test run + + disable man-page installation (moved to *.install files) + + explicitly build with hardening=-all,+format. + * Dropped changes: + - d/rules: unnecessary delta splitting dh_installchangelogs call for gdb + and gdbserver packages. + + -- Mateus Rodrigues de Morais Thu, 31 Jul 2025 11:48:28 -0300 + gdb (16.3-1) unstable; urgency=medium * d/u/signing-key.asc: Remove problematic key. @@ -52,6 +127,33 @@ gdb (16.3-1) unstable; urgency=medium -- Sergio Durigan Junior Mon, 21 Apr 2025 12:29:40 -0400 +gdb (16.2-8ubuntu1) plucky; urgency=medium + + * Merge with Debian unstable. Remaining changes: + - import upstream tarball for building manpages + - debian/control: + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - disable lto on ppc64el + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + - Explicitly build with hardening=-all,+format. + + -- Tim Andersson Thu, 20 Mar 2025 16:02:08 +0000 + gdb (16.2-8) unstable; urgency=medium * d/rules: Invert rule deciding when libinproctrace is installed. @@ -101,6 +203,33 @@ gdb (16.2-3) unstable; urgency=medium -- Sergio Durigan Junior Sat, 15 Mar 2025 00:04:57 -0400 +gdb (16.2-2ubuntu2) plucky; urgency=medium + + * Merge with Debian; remaining changes: + - import upstream tarball for building manpages + - debian/control: + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - disable lto on ppc64el + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + - Explicitly build with hardening=-all,+format. + + -- Matthias Klose Thu, 20 Feb 2025 13:14:05 +0100 + gdb (16.2-2) unstable; urgency=medium * d/rules: Disable tests on alpha due to flakiness. @@ -114,6 +243,37 @@ gdb (16.2-2) unstable; urgency=medium -- Sergio Durigan Junior Mon, 17 Feb 2025 01:09:26 -0500 +gdb (16.2-1ubuntu1) plucky; urgency=medium + + * Merge with Debian; remaining changes: + - import upstream tarball for building manpages + - debian/control: + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - disable lto on ppc64el + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + - Explicitly build with hardening=-all,+format. + + * Drop changes: + - d/rules: delta related to minimal and multiarch support + [minimal & multiarch support removed by Debian] + + -- Pushkar Kulkarni Mon, 10 Feb 2025 11:14:56 +0530 + gdb (16.2-1) unstable; urgency=medium * New upstream version 16.2 @@ -183,6 +343,18 @@ gdb (16.0.90.20250111-1~exp1) experiment -- Sergio Durigan Junior Sat, 11 Jan 2025 19:40:14 -0500 +gdb (16.0.90.20241230-0ubuntu2) plucky; urgency=medium + + * No-change rebuild for Python 3.13 as the default. + + -- Matthias Klose Fri, 03 Jan 2025 12:02:56 +0100 + +gdb (16.0.90.20241230-0ubuntu1) plucky; urgency=medium + + * Snapshot, taken from the gdb-16 branch. + + -- Matthias Klose Mon, 30 Dec 2024 13:19:59 +0100 + gdb (15.2-2~exp1) experimental; urgency=medium * d/rules: Simplify "install" definition. @@ -194,6 +366,40 @@ gdb (15.2-2~exp1) experimental; urgency= -- Sergio Durigan Junior Thu, 09 Jan 2025 20:12:05 -0500 +gdb (15.2-1ubuntu2) plucky; urgency=medium + + * Test build. + + -- Matthias Klose Sun, 15 Dec 2024 11:16:47 +0100 + +gdb (15.2-1ubuntu1) plucky; urgency=medium + + * Merge with Debian; remaining changes: + - build from upstream tarball + - debian/control: + - removed gdb-minimal package + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + - Add loongarch64-linux-gnu as a target for gdb-multiarch. + - Explicitly build with hardening=-all,+format. + + -- Matthias Klose Tue, 12 Nov 2024 12:22:30 +0100 + gdb (15.2-1) unstable; urgency=medium * d/p/gdb-glibc-vdso-workaround.patch: Remove unnecessary patch. @@ -213,6 +419,47 @@ gdb (15.2-1) unstable; urgency=medium -- Sergio Durigan Junior Mon, 11 Nov 2024 18:19:38 -0500 +gdb (15.1-1ubuntu2) oracular; urgency=medium + + * Update from the gdb-15 branch 20240912: + - Fix loading a saved recording. + - gdb/solib-frv: Move lm_info object to solib. + - Mark unavailable bytes of limited-length arrays when allocating + contents. + - [gdb] Handle ^C during disassembly. + - Recognize -2 as a tombstone value in .debug_line. + - Clear the X86_XSTATE_MPX bit in XCRO for x32. + + -- Matthias Klose Thu, 12 Sep 2024 08:38:53 +0200 + +gdb (15.1-1ubuntu1) oracular; urgency=medium + + * Merge with Debian; remaining Ubuntu changes: + - build from upstream tarball + - debian/control: + - removed gdb-minimal package + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + * Add loongarch64-linux-gnu as a target for gdb-multiarch. + * Explicitly build with hardening=-all,+format. + + -- Matthias Klose Sat, 10 Aug 2024 08:21:32 +0200 + gdb (15.1-1) unstable; urgency=medium [ Guillem Jover ] @@ -239,6 +486,90 @@ gdb (15.1-1) unstable; urgency=medium -- Héctor Orón Martínez Thu, 01 Aug 2024 07:27:27 +0200 +gdb (15.1-0ubuntu1) oracular; urgency=medium + + * New upstream release. + + -- Matthias Klose Wed, 10 Jul 2024 12:36:00 +0200 + +gdb (15.0.50.20240403-0ubuntu1) noble; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Wed, 03 Apr 2024 12:51:19 +0200 + +gdb (15.0.50.20240320-0ubuntu1) noble; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Wed, 20 Mar 2024 14:25:50 +0100 + +gdb (15.0.50.20240312-0ubuntu1) noble; urgency=medium + + * New upstream snapshot. + * Drop the time64 workarounds for armhf. + + -- Matthias Klose Tue, 12 Mar 2024 12:00:38 +0100 + +gdb (15.0.50.20240219-0ubuntu1) noble; urgency=medium + + * New upstream snapshot. + * Support for new IBM Z Hardware (IBM z16). LP: #1982336. + + -- Matthias Klose Mon, 19 Feb 2024 21:49:40 +0100 + +gdb (15.0.50.20231231-0ubuntu1) noble; urgency=medium + + * New upstream snapshot. + - Disable the gdb-glibc-vdso-workaround patch. + + -- Matthias Klose Sun, 31 Dec 2023 10:44:11 +0100 + +gdb (14.1-0ubuntu1) noble; urgency=medium + + * New upstream release. + + -- Matthias Klose Fri, 08 Dec 2023 13:25:02 +0100 + +gdb (14.0.50.20230907-0ubuntu1) mantic; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Thu, 07 Sep 2023 07:55:41 +0200 + +gdb (14.0.50.20230810-0ubuntu1) mantic; urgency=medium + + * New upstream snapshot. + * Configure without --with-mpfr (picked up by default). + + -- Matthias Klose Fri, 11 Aug 2023 07:21:03 +0200 + +gdb (13.2-1ubuntu1) mantic; urgency=medium + + * Merge with Debian from unstable (LP: #2023016) + - build from upstream tarball + - debian/control: + - removed gdb-minimal package + - added gdb-doc package + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/control.in: + - added (build-)dependency libc6-dbg on armhf + - exclude libsource-highlight-dev on i386 + - debian/patches/series: + - apply patches gdb-strings and ptrace-error-verbosity + - debian/gdb.install & debian/gdbserver.install: + - include manpages in binary packages + - debian/rules: + - skip tests on armhf, hanging on the buildds + - configure with --disable-werror + - disable configure with --disable-sim + - clean gdb/doc/GDBvn.texi before build + - show test summary after test run + - disable man-page installation (moved to *.install files) + + -- Dominik Viererbe Fri, 16 Jun 2023 14:42:38 +0300 + gdb (13.2-1) unstable; urgency=medium * New upstream release. @@ -256,6 +587,24 @@ gdb (13.1-3) unstable; urgency=medium -- Héctor Orón Martínez Sat, 13 May 2023 13:04:35 +0200 +gdb (13.1-2ubuntu2) lunar; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Build a gdb-doc package, include manpages in binary packages. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + - (Build-)depend on libc6-dbg on armhf. + - Don't configure with --disable-sim. + - Configure with --disable-werror. + - Clean gdb/doc/GDBvn.texi before build. + - Show test summary after test run. + - Don't build a gdb-minimal package. + + -- Matthias Klose Sat, 25 Feb 2023 06:59:44 +0100 + gdb (13.1-2) unstable; urgency=medium * Apply upstream proposed fix for PR/30158 @@ -267,6 +616,25 @@ gdb (13.1-2) unstable; urgency=medium -- Héctor Orón Martínez Fri, 24 Feb 2023 22:58:29 +0100 +gdb (13.1-1ubuntu1) lunar; urgency=medium + + * GDB 13.1 release. + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Build a gdb-doc package, include manpages in binary packages. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + - (Build-)depend on libc6-dbg on armhf. + - Don't configure with --disable-sim. + - Configure with --disable-werror. + - Clean gdb/doc/GDBvn.texi before build. + - Show test summary after test run. + - Don't build a gdb-minimal package. + + -- Matthias Klose Tue, 21 Feb 2023 07:58:50 +0100 + gdb (13.1-1) unstable; urgency=medium * New upstream release. @@ -274,6 +642,17 @@ gdb (13.1-1) unstable; urgency=medium -- Héctor Orón Martínez Mon, 20 Feb 2023 16:33:36 +0100 +gdb (13.0.91.20230210-1ubuntu1) lunar; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Fri, 10 Feb 2023 05:35:58 +0100 + gdb (13.0.91.20230210-0.1) unstable; urgency=medium * Non-maintainer upload. @@ -309,6 +688,17 @@ gdb (13.0.50.20221012-1) experimental; u -- Héctor Orón Martínez Wed, 12 Oct 2022 17:48:19 +0200 +gdb (12.1-4ubuntu1) lunar; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Sat, 14 Jan 2023 08:44:52 +0100 + gdb (12.1-4) unstable; urgency=medium * debian/patches/upstream-fix-core-detach-crash.patch: taken from GDB 12 branch @@ -317,6 +707,29 @@ gdb (12.1-4) unstable; urgency=medium -- Héctor Orón Martínez Wed, 12 Oct 2022 16:28:09 +0200 +gdb (12.1-3ubuntu3) lunar; urgency=medium + + * No-change rebuild with Python 3.11 as default + + -- Graham Inggs Sun, 25 Dec 2022 19:46:12 +0000 + +gdb (12.1-3ubuntu2) kinetic; urgency=medium + + * Fix FTBFS with readline 8.2. + + -- Matthias Klose Thu, 29 Sep 2022 10:34:43 +0200 + +gdb (12.1-3ubuntu1) kinetic; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Thu, 25 Aug 2022 08:46:34 +0200 + gdb (12.1-3) unstable; urgency=medium * No changes, source-only upload. @@ -340,12 +753,133 @@ gdb (12.1-1) unstable; urgency=medium -- Héctor Orón Martínez Wed, 22 Jun 2022 18:10:19 +0200 +gdb (12.1-0ubuntu1) kinetic; urgency=medium + + * GDB 12.1 release. + + -- Matthias Klose Tue, 03 May 2022 18:58:48 +0200 + +gdb (12.0.90-0ubuntu1) jammy; urgency=medium + + * New upstream snapshot, taken from the gdb-12 release branch. + + -- Matthias Klose Mon, 21 Mar 2022 16:27:58 +0100 + +gdb (12.0.50.20220217-0ubuntu1) jammy; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Thu, 17 Feb 2022 07:33:33 +0100 + gdb (11.2-1) unstable; urgency=medium * New upstream release. -- Héctor Orón Martínez Fri, 29 Apr 2022 18:20:54 +0200 +gdb (11.2-0ubuntu1) jammy; urgency=medium + + * GDB 11.2 release. + + -- Matthias Klose Wed, 19 Jan 2022 10:11:23 +0100 + +gdb (11.1-0ubuntu3) jammy; urgency=medium + + * No-change rebuild with Python 3.10 as default version + + -- Graham Inggs Thu, 13 Jan 2022 19:15:33 +0000 + +gdb (11.1-0ubuntu2) impish; urgency=medium + + * GDB 11.1 release. + + -- Matthias Klose Tue, 14 Sep 2021 13:32:16 +0200 + +gdb (11.0.90.20210903-0ubuntu3) impish; urgency=medium + + * Also disable building the simulator on riscv64. + + -- Matthias Klose Fri, 03 Sep 2021 14:15:42 +0200 + +gdb (11.0.90.20210903-0ubuntu2) impish; urgency=medium + + * Also disable building the simulator on armhf and arm64. + + -- Matthias Klose Fri, 03 Sep 2021 09:26:23 +0200 + +gdb (11.0.90.20210903-0ubuntu1) impish; urgency=medium + + * New upstream snapshot, taken from the gdb-11 release branch. + + -- Matthias Klose Fri, 03 Sep 2021 08:36:50 +0200 + +gdb (11.0.90.20210809-0ubuntu1) impish; urgency=medium + + * New upstream snapshot, taken from the gdb-11 release branch. + + -- Matthias Klose Mon, 09 Aug 2021 19:16:34 +0200 + +gdb (11.0.90.20210706-0ubuntu1) impish; urgency=medium + + * New upstream snapshot, taken from the gdb-11 release branch. + + -- Matthias Klose Wed, 07 Jul 2021 10:14:09 +0200 + +gdb (11.0.90.20210705-0ubuntu2) impish; urgency=medium + + * Apply proposed patch for PR gdb/28056. + + -- Matthias Klose Mon, 05 Jul 2021 21:14:03 +0200 + +gdb (11.0.90.20210705-0ubuntu1) impish; urgency=medium + + * New upstream snapshot, taken from the gdb-11 release branch. + + -- Matthias Klose Mon, 05 Jul 2021 09:38:27 +0200 + +gdb (11.0.50.20210630-0ubuntu1) impish; urgency=medium + + * New upstream snapshot. + * Configure with --disable-werror. + * Configure with --disable-sim on ppc64el. + * Build-depend / depend on libc6-dbg on armhf. LP: #1927192. + + -- Matthias Klose Wed, 30 Jun 2021 11:53:33 +0200 + +gdb (10.2-0ubuntu2) impish; urgency=medium + + * Ship an (empty) /etc/gdb/gdbinit. + + -- Matthias Klose Wed, 28 Apr 2021 17:20:47 +0200 + +gdb (10.2-0ubuntu1) impish; urgency=medium + + * gdb 10.2 release. Changes compared to 10.1-2ubuntu2: + - Fix getting range of flexible array member in Python. + + -- Matthias Klose Mon, 26 Apr 2021 15:26:04 +0200 + +gdb (10.1-2ubuntu2) hirsute; urgency=medium + + * Update from the gdb-10-branch: + - Fix PR gdb/27541, PR threads/27239, PR symtab/27341, PR build/27536, + PR build/27535, PR symtab/27333, PR gdb/27147, PR gdb/26861, + PR gdb/26828, PR gdb/27435, PR build/27385, PR tdep/27369, + PR breakpoints/27330, PR gdb/26813, PR gdb/26881, PR remote/26614. + + -- Matthias Klose Sun, 11 Apr 2021 12:32:56 +0200 + +gdb (10.1-2ubuntu1) hirsute; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Fri, 05 Mar 2021 18:48:32 +0100 + gdb (10.1-2) unstable; urgency=high * Acknowledge past contributions from Matthias and Samuel. @@ -370,6 +904,38 @@ gdb (10.1-1.7) unstable; urgency=high -- Matthias Klose Sun, 03 Jan 2021 12:07:38 +0100 +gdb (10.1-1.6ubuntu1) hirsute; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + - Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Sun, 03 Jan 2021 11:06:40 +0100 + +gdb (10.1-1.6) unstable; urgency=high + + * Non-maintainer upload. + * Update to the gdb-10-branch 20210103 (copyright updates). + * Fix building the gdb-source package. Closes: #978391. + * Call dh_dwz before dh_strip. + * Add x86_64-linux-gnux32 as a target for gdb-multiarch. + + -- Matthias Klose Sun, 03 Jan 2021 11:03:21 +0100 + +gdb (10.1-1.5ubuntu2) hirsute; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + - Don't use libsource-highlight-dev on i386. + * Skip tests on armhf, hanging on the buildds. + + -- Matthias Klose Thu, 17 Dec 2020 10:08:08 +0100 + gdb (10.1-1.5) unstable; urgency=medium * Non-maintainer upload. @@ -379,6 +945,16 @@ gdb (10.1-1.5) unstable; urgency=medium -- Matthias Klose Thu, 17 Dec 2020 10:06:12 +0100 +gdb (10.1-1.4ubuntu2) hirsute; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream source tarball. + - Regenerate the control file. + - Apply patches gdb-strings and ptrace-error-verbosity. + * Don't use libsource-highlight-dev on i386. + + -- Matthias Klose Sat, 12 Dec 2020 12:06:12 +0100 + gdb (10.1-1.4) unstable; urgency=medium * Non-maintainer upload. @@ -412,356 +988,418 @@ gdb (10.1-1) unstable; urgency=medium -- Héctor Orón Martínez Sun, 08 Nov 2020 16:34:21 +0100 -gdb (10.0.50.20200913-1~exp1) experimental; urgency=medium +gdb (10.1-0ubuntu1) hirsute; urgency=medium - * New upstream version 10.0.50.20200913 - * enable debuginfod support - * debian/patches: refresh + * New upstream version. - -- Héctor Orón Martínez Sat, 19 Sep 2020 19:21:55 +0200 + -- Matthias Klose Thu, 29 Oct 2020 10:14:31 +0100 -gdb (9.2-1) unstable; urgency=medium +gdb (9.2-0ubuntu1) groovy; urgency=medium - * New upstream release. + * New upstream version (bug fix release). - -- Héctor Orón Martínez Wed, 27 May 2020 17:39:34 +0200 + -- Matthias Klose Tue, 02 Jun 2020 11:43:50 +0200 -gdb (9.1-3) unstable; urgency=medium +gdb (9.1-0ubuntu1) focal; urgency=medium - * debian/patches/fix-symbol-reread-hang.patch: new patch + * New upstream version. - -- Héctor Orón Martínez Fri, 03 Apr 2020 19:28:25 +0200 + -- Matthias Klose Tue, 11 Feb 2020 08:11:47 +0100 -gdb (9.1-2) unstable; urgency=medium - - [ Christian Biesinger ] - * Load gdbinit files from /etc/gdb/gdbinit.d/*. Files need to have a - .gdb/.py extension. - * Fix W-compiler-flags-hidden. - Set V=1 when building so the full compile commandline is shown. - Fixes W-compiler-flags-hidden.html from - https://qa.debian.org/bls/packages/g/gdb.html - - [ Sergio Durigan Junior ] - * Enable libxxhash during build. - * Create directory /etc/gdb/gdbinit.d. - With the new "--with-system-gdbinit-dir" option, we also need to make - sure the new directory exists. - * Backport patch to fix printf convenience var regression. - This was a regression upstream that caused failures on - libapp-stacktrace-perl. (Closes: #936055) - * Adjust python-config.patch to use the new "--embed" from Python 3.8's config. - This adjustment is needed because python3.8-config implements a new - '--embed' option, which should be used by applications building an - embedded Python interpreter. For more info, see - . - * Enable libmpfr during build. +gdb (9.0.90.20200117-0ubuntu1) focal; urgency=medium - -- Sergio Durigan Junior Tue, 03 Mar 2020 23:49:25 -0500 + * New upstream snapshot, taken from the release branch. + * Fix build with Python 3.8. -gdb (9.1-1) unstable; urgency=medium + -- Matthias Klose Sat, 25 Jan 2020 06:32:27 +0100 - [ Héctor Orón Martínez ] - * New upstream version 9.1 (Closes: #906822) - * debian/control{,.in}: python2 removal (Closes: #936591) - * debian/patches: refresh - + debian/patches/load-versioned-libcc1.patch: add SONAME to - gcc-cp-interface.h (Closes: #950778) - + debian/patches/gdb-PATH_MAX.patch: drop - * debian/control{,.in}: build depend on pkg-config - * debian/control{,.in}: add Sergio Durigan Junior as uploader - * debian/README.source: point to xz upstream source instead bz2 - * debian/gcore.1: update (Closes: #904628) +gdb (9.0.90.20200105-0ubuntu1) focal; urgency=medium - [ Debian Janitor ] - * Trim trailing whitespace. - * Use secure URI in debian/watch. - * Make "Files: *" paragraph the first in the copyright file. - * Rely on pre-initialized dpkg-architecture variables. + * New upstream snapshot, taken from the release branch. - [ Christian Biesinger ] - * debian/control: update homepage to an https URL - * debian/{control,rules}: Enable source highlighting (Closes: #942552) + -- Matthias Klose Sun, 05 Jan 2020 12:04:27 +0100 - [ Vagrant Cascadian ] - * debian/rules: Use tar arguments to ensure consistant tarballs, setting file - mode, uid/gid, timestamps and sort order. (Closes: #950606) +gdb (9.0.90.20191216-0ubuntu1) focal; urgency=medium - -- Héctor Orón Martínez Sun, 09 Feb 2020 14:15:45 +0100 + * New upstream snapshot, taken from the release branch. -gdb (8.3.1-1) unstable; urgency=medium + -- Matthias Klose Mon, 16 Dec 2019 16:09:22 +0100 - * New upstream version 8.3.1 (Closes: #865607) - * debian/control: drop flex-old build depend. (Closes: #932514) - * debian/salsa-ci.yml: add support for continous integration - * debian/control: bump standards version, no changes +gdb (9.0.50.20191119-0ubuntu1) focal; urgency=medium - -- Héctor Orón Martínez Fri, 11 Oct 2019 13:26:07 +0200 + * New upstream snapshot. -gdb (8.3-1) unstable; urgency=medium + -- Matthias Klose Tue, 19 Nov 2019 06:22:40 +0100 - * New upstream version 8.3. +gdb (9.0.50.20191110-0ubuntu1) focal; urgency=medium - -- Héctor Orón Martínez Mon, 22 Jul 2019 04:36:24 +0200 + * New upstream snapshot. -gdb (8.2.50.20190222-1) experimental; urgency=medium + -- Matthias Klose Sun, 10 Nov 2019 11:33:12 +0100 - * New upstream version 8.2.50.20190222 - * debian/patches: rebase patchset +gdb (9.0.50.20191019-0ubuntu1) focal; urgency=medium - -- Héctor Orón Martínez Fri, 22 Feb 2019 11:38:18 +0100 + * New upstream snapshot. -gdb (8.2.1-2) unstable; urgency=medium + -- Matthias Klose Sat, 19 Oct 2019 16:50:37 +0200 - * debian/patches: binutils PR/23919 (Closes: #922745) - * debian/patches: fix gdb PR/23712 (Closes: #922030) - * debian/rules: include riscv* in multiarch targets (Closes: #922796) - * Bump standards version - * fix kfreebsd-any build (Closes: #917806) +gdb (8.3.50.20190910-0ubuntu1) eoan; urgency=medium - -- Héctor Orón Martínez Fri, 22 Feb 2019 09:46:36 +0100 + * New upstream snapshot. + * Don't run the tests on armhf, timing out on the buildd. -gdb (8.2.1-1) unstable; urgency=medium + -- Matthias Klose Tue, 10 Sep 2019 11:07:42 +0200 - * New upstream version 8.2.1 +gdb (8.3.50.20190907-0ubuntu1) eoan; urgency=medium - -- Héctor Orón Martínez Fri, 08 Feb 2019 13:24:11 +0100 + * New upstream snapshot. -gdb (8.2-1) unstable; urgency=medium + -- Matthias Klose Sat, 07 Sep 2019 09:55:03 +0200 - * Imported upstream version 8.2, changes in this release: - - Support for the following target has been added: - + RiscV ELF (riscv*-*-elf) - - Support for following targets and native configurations has been removed: - + m88k running OpenBSD (m88*-*-openbsd*) - + SH-5/SH64 ELF (sh64-*-elf*) - + SH-5/SH64 (sh*) - + SH-5/SH64 running GNU/Linux (sh*-*-linux*) - + SH-5/SH64 running OpenBSD (sh*-*-openbsd*) - - Various Python API enhancements - - Aarch64/Linux enhancements: - + SVE support. - + Hardware watchpoints improvements for entities stored at unaligned addresses. - * debian/patches: refresh to newer version - * drop support for gdb-python2 binary package - * Fix "gdb ftbfs with Python 3.7" - (Closes: #914744) +gdb (8.3.50.20190828-0ubuntu1) eoan; urgency=medium - -- Héctor Orón Martínez Tue, 27 Nov 2018 17:08:00 +0100 + * New upstream snapshot. -gdb (8.1-4) unstable; urgency=medium + -- Matthias Klose Wed, 28 Aug 2019 20:15:20 +0200 - * debian/patches/gcore-needs-bash.patch: update with patch from upstream - (Closes: #904160) +gdb (8.3-0ubuntu1) eoan; urgency=medium - -- Héctor Orón Martínez Mon, 23 Jul 2018 04:55:10 +0200 + * gdb 8.3 release. + * Enable riscvXX targets for the multiarch build. -gdb (8.1-3) unstable; urgency=medium + -- Matthias Klose Fri, 17 May 2019 16:05:14 +0200 - * debian/patches: hurd-i386 support fixes - (Closes: #881569) +gdb (8.2.91.20190405-0ubuntu3) disco; urgency=medium - -- Héctor Orón Martínez Tue, 17 Jul 2018 02:00:09 +0200 + * Try to kill testsuite processes, after running the tests. -gdb (8.1-2) unstable; urgency=medium + -- Matthias Klose Mon, 08 Apr 2019 17:50:34 +0200 - * debian/control.in: install libipt-dev on i386 and x32 - * debian/control.in: use binary-targets in Rules-Requires-Root - (change from previous version) +gdb (8.2.91.20190405-0ubuntu1) disco; urgency=medium - -- Héctor Orón Martínez Mon, 16 Jul 2018 03:10:45 +0200 + * New upstream snapshot, taken from the gdb-8.3 branch. -gdb (8.1-1) unstable; urgency=medium + -- Matthias Klose Sat, 06 Apr 2019 02:38:42 +0200 - [ Héctor Orón Martínez ] - * Imported Upstream version 8.1, changes in this release: - - Breakpoints on C++ functions are now set on all scopes by default - ("wild" matching); - - Support for inserting breakpoints on functions marked with C++ ABI tags; - - Target floating-point arithmetic emulation during expression evaluation - (requires MPFR 3.1 or later); - - Various Python Scripting enhancements; - - Improved Rust support; in particular, Trait objects can now be inspected - when debugging Rust code; - - GDB no longer makes assumptions about the type of symbols without - debugging information to avoid producing erroneous and often confusing - results; - - The 'enable' and 'disable' commands now accept a range of breakpoint - locations; - - New 'starti' command to start the program at the first instruction; - - New 'rbreak' command to insert a number of breakpoints via a regular - expression pattern (requires Python); - - The 'ptype' command now supports printing the offset and size of - the fields in a struct; - - The 'gcore' command now supports dumping all the memory mappings - ('-a' command-line option); - - New shortcuts for TUI Single-Key mode: 'i' for stepi, and 'o' for nexti; - - GDBserver enhancements: - + Support for transmitting environment variables to GDBserver; - + Support for starting inferior processes with a specified initial - working directory; - + On Unix systems, support for globbing expansion and variable - substitution of inferior command-line arguments; - - Various completion enhancements; - - The command used to compile and inject code with the 'compile' command - is now configurable; - - New '--readnever' command-line option to speed the GDB startup when - debugging information is not needed; - - Support for the following new native configurations: - + FreeBSD/aarch64 (aarch64*-*-freebsd*); - + FreeBSD/arm (arm*-*-freebsd*); - - Support for the following new targets: - + FreeBSD/aarch64 (aarch64*-*-freebsd*); - + FreeBSD/arm (arm*-*-freebsd*); - + OpenRISC ELF (or1k*-*-elf) - - Removed support for the following targets and native configurations: - + Solaris2/x86 (i?86-*-solaris2.[0-9]); - + Solaris2/sparc (sparc*-*-solaris2.[0-9]); - (Closes: #886658, #881569, #894702) - * debian/patches: refresh series - * debian/copyright: use https instead http - * debian/control.in: set Rules-Requires-Root to no - * debian/control.in: bump standards version - * debian/control.in: thanks Samuel Bronson for past work - (Closes: #883814) - * debian/control.in: thanks Luca Bruno for past work - * debian/control: sync to debian/control.in - - [ James Clarke ] - * Use unversioned libunwind-dev build dependency on ia64 - (Closes: #884105) - - [ Jack Henschel ] - * Enable Intel PT - (Closes: #872800) - - -- Héctor Orón Martínez Wed, 11 Jul 2018 19:59:33 +0200 - -gdb (8.0-1) experimental; urgency=medium - - * Imported Upstream version 8.0, changes in this release: - - C++: Support for rvalue references - - Python scripting enhancements: - + New functions to start, stop and access a running btrace recording. - + Rvalue reference support in gdb.Type. - - GDB commands interpreter: - + User commands now accept an unlimited number of arguments. - + The "eval" command now expands user-defined arguments. - - DWARF version 5 support - (note that its .debug_names index is not supported yet). - - GDB/MI enhancements: - + New -file-list-shared-libraries command to list the shared libraries - in the program. - + New -target-flash-erase command, to erase flash memory. - - Support for native FreeBSD/mips (mips*-*-freebsd) - - Support for the following targets: - + Synopsys ARC (arc*-*-elf32) - + FreeBSD/mips (mips*-*-freebsd) - - Miscellaneous enhancements: - + Command-line redirection now supported on MS-Windows hosts. - + Support for thread names on MS-Windows. - + Support for the PKU register on GNU/Linux. - + Support for Target descriptions on sparc32 and sparc64. - + New GDB/CLI command to erase flash memory - + rdrand and rdseed instructions record/replay support. - * Support for the following features have been removed: - - Support for Java programs compiled with gcj - - Support for the following configurations: - + FreeBSD/alpha (alpha*-*-freebsd*) - + GNU/kFreeBSD/alpha (alpha*-*-kfreebsd*-gnu) - * debian/patches: refresh for new release. - - -- Héctor Orón Martínez Sun, 04 Jun 2017 20:10:39 +0200 - -gdb (7.12-6) unstable; urgency=medium - - * debian/patches: import 7.12 branch fixes - - -- Héctor Orón Martínez Thu, 19 Jan 2017 11:28:25 +0100 - -gdb (7.12-5) unstable; urgency=medium - - * debian/control{,.in}: replace mipsel64 by mips64el. - (Closes: #835522) - - -- Héctor Orón Martínez Tue, 17 Jan 2017 12:01:16 +0100 - -gdb (7.12-4) unstable; urgency=medium - - * debian/sanitize-gdb.sh: drop chm from doc tarball as well. - - lintian complains *.chm files are included without sources - * Revert "debian/control: declare gdb{,-python2} m-a same" - (Closes: #848362) - * debian/patches: fix python framefilter. - - get address as long instead of unsigned long. - (Closes: #814558) - * debian/gbp.conf: add upstream branch, pristine-tar. - - -- Héctor Orón Martínez Sun, 18 Dec 2016 01:44:24 +0100 - -gdb (7.12-3) unstable; urgency=medium - - * debian/patches: - - backport build fixes for Hurd. - (Closes: #834575) - * debian/rules: clean target, remove debian/files. - - -- Héctor Orón Martínez Thu, 15 Dec 2016 01:50:31 +0100 - -gdb (7.12-2) unstable; urgency=medium - - * debian/control*: - - add mipsel64 arch to gdbserver. - (Closes: #835522) - - demote gdbserver to suggests. - (Closes: #820459) - - gdb-multiarch alternatively depend on gdb-python2. - (Closes: #798405) - - add kFreeBSD build depend on libutil-freebsd-dev. - - restrict libutil-freebsd-dev to kfreebsd arches. - - declare gdb{,-python2} multi-arch same. - * debian/gdb{,-python2}.install: add jit-reader header. - (Closes: #761903) - * debian/rules: - - build with fPIC, attempt to fix build failures on kfreebsd and x32. - - lowercase package name on DEB_DH_STRIP_ARGS. - * debian/patches: drop linuxthreads_signal_handling.patch - - kFreeBSD seem to be using fptl now, no need for linuxthreads signals. - - -- Héctor Orón Martínez Wed, 14 Dec 2016 12:18:36 +0100 - -gdb (7.12-1) unstable; urgency=medium - - [ Agustin Henze ] - * Add `arm-none-eabi` as target for bare metal embedded systems - * Set Conflicts, Breaks and Provides fields to replace gdb-arm-none-eabi for gdb-multiarch +gdb (8.2.90.20190311-0ubuntu1) disco; urgency=medium - [ Héctor Orón Martínez ] - * New upstream version 7.12 - * debian/patches: refresh patchset - * migrate from dbg to dbgsym debug package + * New upstream snapshot, taken from the gdb-8.3 branch. - -- Héctor Orón Martínez Mon, 12 Dec 2016 17:04:48 +0100 + -- Matthias Klose Mon, 11 Mar 2019 17:09:56 +0100 -gdb (7.11.1-2) unstable; urgency=medium +gdb (8.2.90-0ubuntu1) disco; urgency=medium - * Fix build when run.1 is missing + * New upstream snapshot, taken from the gdb-8.3 branch. - -- Riku Voipio Fri, 17 Jun 2016 15:43:34 +0300 + -- Matthias Klose Wed, 27 Feb 2019 22:45:10 +0100 -gdb (7.11.1-1) unstable; urgency=medium +gdb (8.2.50.20190214-0ubuntu1) disco; urgency=medium - * New upstream version - * Ack NMU, Fixed gdb-python, thanks Andreas! + * New upstream snapshot. + * Don't run the multi-term-settings test, doesn't terminate. - -- Riku Voipio Thu, 16 Jun 2016 14:49:19 +0300 + -- Matthias Klose Thu, 14 Feb 2019 10:13:57 +0100 -gdb (7.10-1.1) unstable; urgency=medium +gdb (8.2.1-0ubuntu1) disco; urgency=medium - * Non-maintainer upload. - * Fix build of gdb-python2 package (Closes: #798401) + * gdb 8.2.1 release. + + -- Matthias Klose Mon, 14 Jan 2019 19:41:45 +0100 + +gdb (8.2-0ubuntu1~16.04.1) xenial; urgency=medium + + * PPA upload. + + -- Matthias Klose Tue, 25 Sep 2018 21:43:52 +0200 + +gdb (8.2-0ubuntu1) cosmic; urgency=medium + + * gdb 8.2 release. + + -- Matthias Klose Wed, 12 Sep 2018 12:41:04 +0200 + +gdb (8.1.90.20180904-0ubuntu1) cosmic; urgency=medium + + * Snapshot, taken from the gdb-8.1-branch. + + -- Matthias Klose Tue, 04 Sep 2018 16:41:10 +0200 + +gdb (8.1-0ubuntu8) cosmic; urgency=medium + + * Enable Intel PT recording format on x86 architectures. Closes: #872800. + + -- Matthias Klose Fri, 20 Jul 2018 22:15:11 +0200 + +gdb (8.1-0ubuntu6) cosmic; urgency=medium + + * gdb: Provide gdb-minimal. + + -- Matthias Klose Sat, 12 May 2018 18:21:38 -0400 + +gdb (8.1-0ubuntu5) cosmic; urgency=medium + + * debian/control: Update libncurses build-deps to the new scheme. + + -- Adam Conrad Fri, 04 May 2018 09:58:50 -0600 + +gdb (8.1-0ubuntu4) cosmic; urgency=medium + + * No-change rebuild for ncurses soname changes. + + -- Matthias Klose Thu, 03 May 2018 15:19:42 +0000 + +gdb (8.1-0ubuntu3) bionic; urgency=medium + + * Update, taken from the gdb-8.1-branch 20180409. + * Use bash instead of /bin/sh as this script uses arrays which require bash. + (Trent Lloyd). LP: #1762320. + + -- Matthias Klose Mon, 09 Apr 2018 11:31:42 +0200 + +gdb (8.1-0ubuntu2) bionic; urgency=medium + + * Remove build dependency on gcj-jdk. + + -- Matthias Klose Mon, 26 Mar 2018 09:19:36 +0800 + +gdb (8.1-0ubuntu1) bionic; urgency=medium + + * gdb 8.1 release. + + -- Matthias Klose Thu, 01 Feb 2018 09:34:03 +0100 + +gdb (8.0.90.20180111-0ubuntu2) bionic; urgency=medium + + * Snapshot, taken from the gdb-8.1-branch. + + -- Matthias Klose Thu, 11 Jan 2018 17:29:12 +0100 + +gdb (8.0.1-0ubuntu3) bionic; urgency=medium + + * Now that we don't buil gdb64 anymore, stop depending on lib64expat1 + altogether. + + -- Łukasz 'sil2100' Zemczak Wed, 03 Jan 2018 11:42:27 +0100 + +gdb (8.0.1-0ubuntu2) bionic; urgency=medium + + * Stop building gdb64. + + -- Matthias Klose Fri, 22 Dec 2017 16:37:06 +0100 + +gdb (8.0.1-0ubuntu1) artful; urgency=medium + + * New upstream bug fix release. + + -- Matthias Klose Wed, 13 Sep 2017 12:21:48 +0200 + +gdb (8.0-0ubuntu6) artful; urgency=medium + + * Fix build dependencies for the gdb64 build. + + -- Matthias Klose Fri, 01 Sep 2017 09:00:04 +0200 + +gdb (8.0-0ubuntu5) artful; urgency=medium + + * Build using ncursesw. LP: #1275210. + + -- Matthias Klose Fri, 01 Sep 2017 08:50:14 +0200 + +gdb (8.0-0ubuntu4) artful; urgency=medium + + * Add patch to support Infinity notes. + + -- Matthias Klose Mon, 21 Aug 2017 15:18:17 +0200 + +gdb (8.0-0ubuntu3) artful; urgency=medium + + * SECURITY UPDATE: denial of service via infinite recursion + - debian/patches/CVE-2016-4491-2.patch: limit more recursion in + libiberty/cp-demangle.c. + - CVE-2016-4491 + + -- Marc Deslauriers Wed, 26 Jul 2017 13:17:18 -0400 + +gdb (8.0-0ubuntu2) artful; urgency=medium + + * No-change rebuild to build with python3.6. + + -- Matthias Klose Mon, 24 Jul 2017 14:07:49 +0000 + +gdb (8.0-0ubuntu1) artful; urgency=medium + + * gdb 8.0 release. + + -- Matthias Klose Wed, 07 Jun 2017 09:22:21 -0700 + +gdb (7.99.90.20170502-0ubuntu1) artful; urgency=medium + + * Snapshot, taken from the gdb-8-branch. + + -- Matthias Klose Tue, 02 May 2017 13:00:05 +0200 + +gdb (7.12.50.20170407-0ubuntu1) zesty; urgency=medium + + * Snapshot, taken from the trunk. + + -- Matthias Klose Fri, 07 Apr 2017 16:12:15 +0200 + +gdb (7.12.50.20170314-0ubuntu1) zesty; urgency=medium + + * Snapshot, taken from the trunk. + + -- Matthias Klose Tue, 14 Mar 2017 14:12:54 +0100 + +gdb (7.12.50.20170207-0ubuntu2) zesty; urgency=medium + + * Configure with --disable-werror. + + -- Matthias Klose Tue, 07 Feb 2017 10:22:15 +0100 + +gdb (7.12.50.20170207-0ubuntu1) zesty; urgency=medium + + * Snapshot, taken from the trunk. + + -- Matthias Klose Tue, 07 Feb 2017 07:03:04 +0100 + +gdb (7.12-0ubuntu4) zesty; urgency=medium + + * Modify debian/patches/armhf-fpregset.patch per upstream. LP: #1645501. + + -- Brian Murray Wed, 18 Jan 2017 11:51:42 -0800 + +gdb (7.12-0ubuntu3) zesty; urgency=medium + + * Add debian/patches/armhf-fpregset.patch. LP: #1645501. + + -- Kees Cook Tue, 29 Nov 2016 15:30:20 -0800 + +gdb (7.12-0ubuntu2) zesty; urgency=medium + + * Add Power ISA 3.0/POWER9 instructions record support. LP: #1642304. + + -- Matthias Klose Wed, 16 Nov 2016 19:58:53 +0100 + +gdb (7.12-0ubuntu1) yakkety; urgency=medium + + * New upstream release. + + -- Matthias Klose Tue, 11 Oct 2016 16:33:24 +0200 + +gdb (7.11.90.20161005-0ubuntu1) yakkety; urgency=medium + + * Snapshot, taken from the gdb-7.12 branch. + + -- Matthias Klose Wed, 05 Oct 2016 23:55:15 +0200 + +gdb (7.11.90.20160927-0ubuntu1) yakkety; urgency=medium + + * Snapshot, taken from the gdb-7.12 branch. + + -- Matthias Klose Tue, 27 Sep 2016 18:42:57 +0200 + +gdb (7.11.90.20160917-0ubuntu2) yakkety; urgency=medium + + * Build again the gdb64 package. + * Configure with --with-babeltrace on every architecture. + + -- Matthias Klose Sun, 18 Sep 2016 19:46:33 +0200 + +gdb (7.11.90.20160917-0ubuntu1) yakkety; urgency=medium + + * Snapshot, taken from the gdb-7.12 branch. + + -- Matthias Klose Sat, 17 Sep 2016 15:49:50 +0200 + +gdb (7.11.90.20160906-0ubuntu1) yakkety; urgency=medium + + * Snapshot, taken from the gdb-7.12 branch. + + -- Matthias Klose Tue, 06 Sep 2016 12:39:48 +0200 + +gdb (7.11.90.20160824-0ubuntu2) yakkety; urgency=medium + + * Don't build gdb64 for now. + + -- Matthias Klose Mon, 29 Aug 2016 11:11:26 +0200 + +gdb (7.11.90.20160824-0ubuntu1) yakkety; urgency=medium + + * Snapshot, taken from the gdb-7.12 branch. + + -- Matthias Klose Wed, 24 Aug 2016 14:54:04 +0200 + +gdb (7.11.1-0ubuntu1) yakkety; urgency=medium + + * New upstream bug fix release. + - Fix PR gdb/19828, PR gdb/20045, PR gdb/18077, PR gdb/20039, + PR python/20037, PR remote/19840, PR gdb/19858, PR gdb/19829, + PR gdb/19676. + + -- Matthias Klose Wed, 01 Jun 2016 17:05:58 +0200 + +gdb (7.11-0ubuntu1) xenial; urgency=medium + + * New upstream release. + + -- Matthias Klose Wed, 24 Feb 2016 18:27:39 +0100 + +gdb (7.10.90.20160220-0ubuntu1) xenial; urgency=medium + + * Snapshot, taken from the gdb-7.11 branch. + * Build again the pdf docs with fixed texinfo. + * Fix OverflowError in backtrace command on 32bit kernels. LP: #1513922. + + -- Matthias Klose Sat, 20 Feb 2016 17:52:18 +0100 + +gdb (7.10.90.20160215-0ubuntu2) xenial; urgency=medium + + * Don't build the pdf docs, broken with recent texinfo. + + -- Matthias Klose Mon, 15 Feb 2016 20:50:26 +0100 + +gdb (7.10.90.20160215-0ubuntu1) xenial; urgency=medium + + * Snapshot, taken from the gdb-7.11 branch. + + -- Matthias Klose Mon, 15 Feb 2016 17:40:33 +0100 + +gdb (7.10.1-0ubuntu1) xenial; urgency=medium + + * New upstream release. + + -- Matthias Klose Sat, 16 Jan 2016 11:33:19 +0100 + +gdb (7.10-1ubuntu2) wily; urgency=medium + + * Fix build dependencies on i386 and powerpc for gdb64. + + -- Matthias Klose Sun, 13 Sep 2015 14:59:07 +0200 + +gdb (7.10-1ubuntu1) wily; urgency=medium + + * Merge with Debian; remaining changes: + * Remaining changes: + - Keep building the gdb64 package. + - Build from the upstream sources. + - Build the gdb-doc package. + - Include the man pages in the gdb package. + - Build-depend on gcj-jdk. + - Drop build dependency on python-dev. + - Additional patches branch-updates, gdb-strings, ptrace-error-verbosity, + ppc64el-gdbserver, ppc64el-attach-jvm. + - Don't build a gdb-python2 package. + - Configure with babeltrace on ppc64 and ppc64el. + - gdb: Add a replaces to gdb-doc, which used to ship the manual pages. + - Again, stop building the gdb-minimal package, not used anymore on any + image. + - Add build dependencies for the gdb-doc package. + - Make gdb Multi-Arch: allowed again. + - gdb: Recommend libcc1-0. + * Update to the 7.9 branch 20150321. + - Fix undefined behavior in TUI's TAB expansion. - -- Andreas Bombe Sat, 28 May 2016 17:22:54 +0200 + -- Matthias Klose Sun, 13 Sep 2015 13:47:01 +0200 gdb (7.10-1) unstable; urgency=medium @@ -801,24 +1439,52 @@ gdb (7.10-1) unstable; urgency=medium -- Hector Oron Wed, 02 Sep 2015 04:04:33 +0200 -gdb (7.9.1-1) unstable; urgency=medium +gdb (7.10-0ubuntu1) wily; urgency=medium - * Imported Upstream version 7.9.1: - - This is a minor corrective release over GDB 7.9, fixing the following issues: - + PR build/18033 (C++ style comment used in gdb/iq2000-tdep.c and gdb/compile/compile-*.c) - + PR build/18298 ("compile" command cannot find compiler if tools configured with triplet instead of quadruplet) - + PR tui/18311 (Random SEGV when displaying registers in TUI mode) - + PR python/18299 (exception when registering a global pretty-printer in verbose mode) - + PR python/18066 (argument "word" seems broken in Command.complete (text, word)) - + PR pascal/17815 (Fix pascal behavior for class fields with testcase) - + PR python/18285 (ptype expr-with-xmethod causes SEGV) - * d/p/load-versioned-libcc1.patch: - - load libcc1.so.0 instead unversioned file. - * d/p/Segmentation-fault-on-add-symbol-file-command.patch: - - fix: segfault on add-symbol-file - * d/patches: refresh + * Gdb 7.10. - -- Hector Oron Wed, 19 Aug 2015 21:27:17 +0200 + -- Matthias Klose Sun, 30 Aug 2015 14:40:47 +0200 + +gdb (7.9.90.20150809-0ubuntu1) wily; urgency=medium + + * Snapshot, taken from the 7.10 branch. + + -- Matthias Klose Mon, 10 Aug 2015 00:35:59 +0200 + +gdb (7.9.1-0ubuntu1) wily; urgency=medium + + * New upstream (bug fix) version. + + -- Matthias Klose Wed, 22 Jul 2015 18:33:52 +0200 + +gdb (7.9-1ubuntu1) vivid; urgency=medium + + * Merge in the Debian packaging changes for 7.9. + * Remaining changes: + - Keep building the gdb64 package. + - Build from the upstream sources. + - Build the gdb-doc package. + - Include the man pages in the gdb package. + - Build-depend on gcj-jdk. + - Drop build dependency on python-dev. + - Additional patches branch-updates, gdb-strings, ptrace-error-verbosity, + ppc64el-gdbserver, ppc64el-attach-jvm. + - Don't build a gdb-python2 package. + - Configure with babeltrace on ppc64 and ppc64el. + - gdb: Add a replaces to gdb-doc, which used to ship the manual pages. + - Again, stop building the gdb-minimal package, not used anymore on any + image. + - Add build dependencies for the gdb-doc package. + - Make gdb Multi-Arch: allowed again. + * gdb: Suggest libcc1-0 (should really be a recommends, but it is + still in universe, same as the needed gcc-5/gccgo-5). + * Don't look for the libcc1.so symlink, but for the real library name. + * Fix the regexp for searching the compiler, so that it recognizes + triplets as well. + * Update to the 7.9 branch 20150321. + - Fix undefined behavior in TUI's TAB expansion. + + -- Matthias Klose Sat, 21 Mar 2015 17:07:37 +0100 gdb (7.9-1) experimental; urgency=medium @@ -864,18 +1530,45 @@ gdb (7.9-1) experimental; urgency=medium -- Hector Oron Thu, 19 Mar 2015 13:18:58 +0100 -gdb (7.8.2-1) experimental; urgency=medium +gdb (7.9-0ubuntu1) vivid; urgency=medium + + * GDB 7.9 release. + + -- Matthias Klose Wed, 25 Feb 2015 22:27:54 +0100 + +gdb (7.8.2-0ubuntu1) vivid; urgency=medium + + * GDB 7.8.2 release. + + -- Matthias Klose Tue, 20 Jan 2015 20:34:21 +0100 + +gdb (7.8.1-1ubuntu2) vivid; urgency=medium + + * Fix PR ld/17677, performance regression compared to 7.7. + LP: #1388999. - * Imported Upstream version 7.8.2 - - This is a minor corrective release over GDB 7.8.1, fixing the following issues: - + PR symtab/17642 ([7.8 regression] internal-error: resolve_dynamic_struct: Assertion `TYPE_NFIELDS (type) > 0' failed.) - + PR binutils/17677 (_bfd_elf_get_synthetic_symtab runs in O(n^2) complexity) - + PR gdb/16215 (SPARC: can't compute CFA for this frame) - + PR gdb/17525 (target-async: breakpoint commands not executed when program run from -x script) - + PR cli/17828 ([7.8 regression] -batch -ex r breaks terminal) - * d/{control*,gdb64*,rules}: drop gdb64 support. + -- Matthias Klose Tue, 09 Dec 2014 10:25:17 +0100 - -- Hector Oron Thu, 22 Jan 2015 02:24:52 +0100 +gdb (7.8.1-1ubuntu1) vivid; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream sources. + - Build the gdb-doc package. + - Include the man pages in the gdb package. + - Build-depend on gcj-jdk. + - Drop build dependency on python-dev. + - Additional patches branch-updates, gdb-strings, ptrace-error-verbosity, + ppc64el-gdbserver, ppc64el-attach-jvm. + - Don't build a gdb-python2 package. + - Configure with babeltrace on ppc64 and ppc64el. + - gdb: Add a replaces to gdb-doc, which used to ship the manual pages. + - Again, stop building the gdb-minimal package, not used anymore on any + image. + - Add build dependencies for the gdb-doc package. + - Make gdb Multi-Arch: allowed again. + * Upstream fixes LP: #1348275. + + -- Matthias Klose Thu, 20 Nov 2014 09:28:37 +0100 gdb (7.8.1-1) experimental; urgency=medium @@ -917,6 +1610,44 @@ gdb (7.8.1-1) experimental; urgency=medi -- Hector Oron Sun, 09 Nov 2014 16:29:31 +0100 +gdb (7.8-1ubuntu4) utopic; urgency=medium + + * Make gdb Multi-Arch: allowed again. + + -- Matthias Klose Thu, 09 Oct 2014 08:23:49 +0200 + +gdb (7.8-1ubuntu3) utopic; urgency=medium + + * Add build dependencies for the gdb-doc package. + + -- Matthias Klose Tue, 07 Oct 2014 18:20:50 +0200 + +gdb (7.8-1ubuntu2) utopic; urgency=medium + + * Drop build dependency on gccgo (universe). + + -- Matthias Klose Tue, 07 Oct 2014 17:48:27 +0200 + +gdb (7.8-1ubuntu1) utopic; urgency=medium + + * Merge with Debian; remaining changes: + - Build from the upstream sources. + - Build the gdb-doc package. + - Include the man pages in the gdb package. + - Build-depend on gcj-jdk. + - Drop build dependency on python-dev. + - Additional patches branch-updates, gdb-strings, ptrace-error-verbosity, + ppc64el-gdbserver, ppc64el-attach-jvm. + * Don't build a gdb-python2 package. + * Configure with babeltrace on ppc64 and ppc64el. + * gdb: Add a replaces to gdb-doc, which used to ship the manual pages. + LP: #1370690. + * Build-depend on gccgo to run the Go tests during the build. + * Again, stop building the gdb-minimal package, not used anymore on any + image. + + -- Matthias Klose Tue, 07 Oct 2014 13:04:14 +0200 + gdb (7.8-1) experimental; urgency=medium [ Samuel Bronson ] @@ -985,272 +1716,135 @@ gdb (7.8-1) experimental; urgency=medium -- Samuel Bronson Tue, 26 Aug 2014 15:34:03 -0400 -gdb (7.7.1+dfsg-3) unstable; urgency=medium +gdb (7.8-0ubuntu2) utopic; urgency=medium - * d/p/restore-run.1.patch: Temporary patch to fix sim FTBFS. - Turns out that without sim/common/run.1, sim fails to build. - This doesn't have any cover texts or invariant sections, - so in this patch we simply add it back. - (It turns out that sim doesn't support x86.) - * d/sanitize-gdb.sh: In future, only strip manpages from gdb/ subtree. - * d/NEWS: Add warning about impending switch to Python 3 + * Update gdb from the 7.8 release branch. + - Fix regression for Linux vDSO in GDB (PR gdb/17407). + - Fix regression, GDB stopped on run with attached process (PR gdb/17347). + - Fix PR guile/17367, PR guile/17247. + - Fix crash on Python frame filters with unreadable arg. + - Fix xmethod Python so that it works with Python3. + - Fix 'gcore' with exited threads. + - Fix Fix build/17104, build configured with --with-babeltrace. + - Aarch64: Make CPSR a 32-bit register again in the target description. + * Build-depend on binutils 2.24.51.20141001 for running the tests. + LP: #1365664. + * Fix gdbserver conditionals on ppc64le. LP: #1367832. + * Fix attaching to a java process on ppc64el. - -- Samuel Bronson Thu, 14 Aug 2014 18:16:50 -0400 + -- Matthias Klose Wed, 01 Oct 2014 22:41:51 +0200 -gdb (7.7.1+dfsg-2) unstable; urgency=medium +gdb (7.8-0ubuntu1) utopic; urgency=medium - * Fix FTBFS on non-x86 trying to install unbuilt libinproctrace.so + * gdb-7.8 release. - -- Samuel Bronson Tue, 12 Aug 2014 16:21:03 -0400 + -- Matthias Klose Thu, 31 Jul 2014 21:54:05 +0200 -gdb (7.7.1+dfsg-1) unstable; urgency=medium +gdb (7.7.91.20140723-0ubuntu1) utopic; urgency=medium - [ Héctor Orón Martínez ] - * d/changelog: replace nickname by real name in previous block + * Snapshot, taken from the 7.8 branch. - [ Gabriele Giacone ] - * Fix FTBFS on Hurd. - + Cherry-pick from upstream: - hurd-new-RPC-reply-stub-functions.patch - hurd-adapt-to-changed-MIG-output.patch - hurd-adjust-to-startup-with-shell-changes.patch - hurd-make-MIG-output-parsing-more-robust.patch - (Closes: #752574) + -- Matthias Klose Wed, 23 Jul 2014 16:01:10 +0200 - [ Samuel Bronson ] - * Ship /usr/lib/libinproctrace.so with gdbserver. - This enables the "agent" features. - * d/copyright: correct a licensecheck error; add required license texts/blurbs - * d/gdb.install: Include gcore in gdb package (Closes: #752317). - Thanks to Lorenzo Beretta for the report. - * New patch to fix the build on kFreeBSD. - Thanks to Steven Chamberlain for a fix (Closes: #752390, #752295). - * d/watch: Update to be more flexible about upstream tarball format. - - Last but not least, - * Use correct tarball, with non-free upstream manpages stripped. - Restores DFSG-compliance. +gdb (7.7.1-0ubuntu5) utopic; urgency=medium - [ Hector Oron ] - * Rename upstream tarball to not conflict with the one in archive. + * Fix regression introduced in previous upload, again supporting + powerpc64le in the multilib build. LP: #1233185. - -- Samuel Bronson Sat, 09 Aug 2014 13:11:35 -0400 + -- Matthias Klose Wed, 23 Jul 2014 15:19:13 +0200 -gdb (7.7.1-2) unstable; urgency=medium +gdb (7.7.1-0ubuntu4) utopic; urgency=medium - [ Samuel Bronson ] - * Don't require Java stuff just to gather test results we don't look at. - * Disable babeltrace; it doesn't build everywhere. - Thanks to Julien Cristau for the heads up. - * Go back to python2; it's causing people trouble and Matthias Klose never - actually explained the need. - Thanks to Ben Longbons for the report and Jakub Wilk for corroborating it. - (Closes: #748711, Reopens: #727003) + [ Martin Pitt ] + * debian/rules: Revert configuring with "MULTIARCH_TARGET=all" and go back + to static list of targets. "all" is broken and does not work at least on + ARM. (LP: #1233185) - -- Hector Oron Wed, 18 Jun 2014 01:42:25 +0200 + -- Brian Murray Mon, 30 Jun 2014 15:28:20 -0700 -gdb (7.7.1-1) unstable; urgency=medium +gdb (7.7.1-0ubuntu3) utopic; urgency=medium - [ Samuel Bronson ] - * Switch to .xz for our ".orig" tarballs - * Imported Upstream version 7.7 - - GDB 7.7 brings new targets, features and improvements, including: - * C++: - ** GDB now implements the 'typeid' operator. - ** Exception Catchpoints can now filter by type. - * Python scripting: - ** Frame filters and frame decorators have been added. - ** Temporary breakpoints are now supported. - ** Line tables representation has been added. - ** New attribute 'parent_type' for gdb.Field objects. - ** gdb.Field objects can be used as subscripts on gdb.Value objects. - ** New attribute 'name' for gdb.Type objects. - * New commands: - ** show configuration - ** catch rethrow - ** info exceptions [REGEXP] - ** remove-symbol-file [FILENAME | -a ADDRESS] - ** maint check-psymtabs - ** maint check-symtabs - ** maint expand-symtabs - ** maint set|show per-command [space | time | symtab] - * New options: - ** set|show debug symfile off|on - ** set|show print raw frame-arguments - ** set|show remote trace-status-packet - ** set|show debug nios2 - ** set|show range-stepping - ** set|show startup-with-shell - ** set|show code-cache - For all options that interpret 0 or -1 as meaning "unlimited", - the literal 'unlimited' can ot be used. - * New convenience variables/functions: - ** $_exception - ** $_exitsignal - ** $_isvoid - * GDB/MI: - ** All MI commands now accept an optional "--language" option. - ** "undefined-command" error code provided in "^error" result - records when trying to run a non-existing command. - ** New commands -catch-assert and -catch-exceptions - ** New command -info-ada-exceptions - ** New command -info-gdb-mi-command - ** New command -dprintf-insert - ** New command -trace-frame-collected - ** -trace-save CTF (Common Trace Format) support. - ** -data-list-register-values, -stack-list-locals, -stack-list-arguments - and -stack-list-variables optional "--skip-unavailable" option. - ** -exec-run optional "--start" option. - * Remote Protocol: - ** Target-assigned range stepping support. - GDBserver implements this feature on x86/x86_64 GNU/Linux targets. - ** vCont new 'r' action. - ** qXfer:libraries-svr4:read's annex used to pass argument list. - * New target configurations: - ** Nios II ELF nios2*-*-elf - ** Nios II GNU/Linux nios2*-*-linux - ** Texas Instruments MSP430 msp430*-*-elf - * GDB Windows x64 unwinding data support. - * SystemTap SDT probes support on AArch64 GNU/Linux. - * The 'tsave' command now supports CTF (Common Trace Format). - * New script gcore, installed in $prefix/bin - * New script contrib/gdb-add-index.sh for adding .gdb_index sections - to binaries. - * Improve arm*-linux record/replay support. - * Removed support for a.out NetBSD and OpenBSD obsolete configurations. - ELF variants of these configurations are kept supported. - * The "set|show remotebaud" commands are deprecated. Use "show|show serial - baud" instead. - - For a complete list and more details on each item, please see the - NEWS file. - * Update patches for new upstream version: - - Drop man-page-args.patch and man-page-order.patch: - Manpages are dead to us now (not DFSG free), and the source is in - texinfo now anyway. - - Drop upstream-arm-catch-syscall.patch and - upstream-print_insn_rl78-workaround.patch: - Already applied upstream. - - Update linuxthreads_signal_handling.patch and - gdb-6.5-bz185337-resolve-tls-without-debuginfo-v2.patch - * d/gdb-minimal.manpages: Remove because manpages are dead to us - * d/rules: - - Update for the new release. - * Don't expect all tests to pass, they never do. - ("make check" finally stopped lying?) - * Adjust for "gcore" getting its source renamed and getting installed - - Other improvements - * Install contrib/ in /usr/share/doc/gdb/ - * Carry over more configure flags to secondary packages, so - e.g. gdb-multiarch can find it's message catalogs - - Nitpicks: - * Replace a $(findstring ...) call with $(filter ...) - (It's probably not all that likely that DEB_BUILD_OPTIONS would contain - an item with nocheck as a substring, but still ...) - * Use --disable-readline; we have our own ... - * d/control: - - Update Vcs-Git/Vcs-Browser URLs + * Fix PR 14963, infinite recursion in the demangler. LP: #1315590. - [ Héctor Orón Martínez ] - * d/control.in, d/rules: add gdb-dbg package. - (closes: #696197) - * d/control.in: update Vcs-* references - * d/control.in: bump standards version, no changes required - * d/compat, d/control.in: bump dh compat to 9 to get build-id based - debug info paths - * d/p/ppc64le.diff: apply upstream patch for ppc64le support - * d/control.in: add ppc64el architecture - - Thanks Frédéric Bonnard for report - (closes: #744204) - * d/control.in: gdb-minimal provides gdb - (closes: #588775) - * d/control.in: gdb recommends gdbserver - (closes: #675623) - * Fix gdb: confusing error message "$HOME/pid: No such file or directory" - (closes: #712671) - * d/p/gdb-glibc-vdso-workaround.patch: - - Work around PR libc/13097 "linux-vdso.so.1" - (closes: #738702) - * d/rules: do not misuse the version field to encode the distro name - (closes: #738331) - * d/copyright: update file to conform DEP5. + -- Matthias Klose Thu, 12 Jun 2014 21:14:58 +0200 - [ Samuel Bronson ] - * d/control.in: Misc fixes, like not building an - "Architecture: all".-dbg package - * d/control: Regenerate after above changes ... - * d/rules: Enable CTF support through babeltrace - * d/rules: Be more specific about which features to build with - * d/control.in, d/control: Drop B-D on libbz2-dev; gdb doesn't want it - * debian/gdbserver.install: Don't install an empty gdbserver manpage either. - * d/watch, d/upstream-signing-key.pgp: Verify sigs; remove dh_make stuff - * d/control.in, d/control: Make gdb and gdb-minimal conflict as policy says - * d/include-binary-files: Appease dpkg-source about the upstream key ... - * d/patches/python-config.patch: Add header, fix typo pointed out upstream - * d/sanitize-gdb.sh: stop filtering gdb-doc, drop all manpages from gdb - * Imported Upstream version 7.7.1 - - GDB 7.7.1 provides the following fixes and improvements to GDB 7.7: - * PR win32/14018 (pc register not available error on Windows) - * PR python/16547 (GDB crashing on gdb.python/py-linetable.exp) - * PR build/16550 (64-bit GDB doesn't build on Solaris) - * PR gdb/16626 (auto-load regression: gdb uses wrong file to test safety) - * PR breakpoints/16292 (GDB oversteps a range in some cases.) - * PR gdb/16575 (stale breakpoint instructions in the code cache) - * PR gdb/16696 (AIX 32-bit cores, high section addresses) - * PR gdb/16721 (Erroneous backtrace on AVR) - * PR gdb/16832 (Erroneous backtrace on avrxmega architectures) - * PR build/16873 (GDB 7.7 does not build with GCC 4.9) - (Closes: #746855) +gdb (7.7.1-0ubuntu2) utopic; urgency=medium - -- Hector Oron Sat, 31 May 2014 11:12:46 +0200 + * Add the ARM change from the gdb-linaro 7.7-2014.05 release. + * Build-depend on systemtap-sdt-test (test dependency). -gdb (7.6.2-1.1) unstable; urgency=medium + -- Matthias Klose Tue, 27 May 2014 16:53:09 +0200 - * Non-maintainer upload. - * Build using python3. Closes: #727003. +gdb (7.7.1-0ubuntu1) utopic; urgency=medium - -- Matthias Klose Sat, 03 May 2014 15:56:03 +0200 + * GDB 7.7.1 release. -gdb (7.6.2-1) unstable; urgency=low + -- Matthias Klose Tue, 13 May 2014 02:23:53 +0200 - * Imported upstream version 7.6.2 - - GDB 7.6.2 provides the following fixes and improvements to GDB 7.6.1: - * PR breakpoint/16251 (AArch64 hardware breakpoint error after fork) - * PR gdb/16303 (GDB 7.6.1 does not work with binutils 2.24 on MIPS16 - and microMIPS) - * d/rules: Revert configuring with "MULTIARCH_TARGET=all" and go back - to static list of targets. "all" is broken and does not work at least on - ARM. (LP: #1233185). Thanks Martin Pitt for report. - (Closes: #725078) - * d/rules: Add aarch64-linux-gnu to multiarch target list. +gdb (7.7-0ubuntu4) utopic; urgency=medium - -- Hector Oron Sat, 18 Jan 2014 14:28:01 +0100 + * re-enable patch that got disabled at some point (LP: #1317136) + - ptrace-error-verbosity.patch: Try to make the PTRACE scope sysctl + more discoverable via a verbose error message when failures happen. -gdb (7.6.1-1) unstable; urgency=low + -- Marc Deslauriers Wed, 07 May 2014 15:46:53 -0400 - [ Samuel Bronson ] - * Imported Upstream version 7.6.1 - - GDB 7.6.1 provides the following fixes and improvements to GDB 7.6: - * PR tdep/15420 (Cannot debug threaded programs on newer versions - of x86-solaris - Solaris 10, Update 10 or later) - * PR remote/15455 (QTro remote packet broken) - * PR build/15476 (Build failure due to incomplete enum type in utils.h) - * PR server/15594 (tls support in 64x32 x86 gdbserver doesn't extend - address to 64 bit) - * PR server/15075 (dprintf inteferes with "next") - * PR server/15434 (dprintf uses a synchronous 'continue' even in - non-stop mode) - * PR tui/14880 (in split register layouts, up results in assertion - failure in value.c) - * PR c++/15519 (GDB 7.6 is 94x slower than GDB 7.5.1 using a certain - core file) - * PR gdb/15837 (GDB prints entry values for local variables) - * PR gdb/15415 (gdb resolves symbolic links when passing argv[0]) - * PR cli/15603 (CTRL-C can no longer interrupt inferior) - * PR gdb/15604 (gdbserver socket leak 7.5 regression) - * Backport ARM Linux `catch syscall' support from my upstream - patch. (Closes: #709937) +gdb (7.7-0ubuntu3) trusty; urgency=medium + + * Rebuild with Python 3.4. + + -- Matthias Klose Wed, 19 Feb 2014 11:41:03 +0100 + +gdb (7.7-0ubuntu2) trusty; urgency=medium + + * Don't encode the distribution name into the version string. + + -- Matthias Klose Sat, 08 Feb 2014 20:23:43 +0100 + +gdb (7.7-0ubuntu1) trusty; urgency=medium + + * GDB 7.7 release. + + -- Matthias Klose Fri, 07 Feb 2014 18:59:59 +0100 + +gdb (7.6.50.20140106-0ubuntu1) trusty; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Mon, 06 Jan 2014 11:01:33 +0100 + +gdb (7.6.50.20131218-0ubuntu1) trusty; urgency=medium + + * New upstream snapshot. + * Configure with --disable-werror. + * Handle Debian's local elf.h / sys/auxv.h header reorganization. + + -- Matthias Klose Wed, 18 Dec 2013 13:50:41 +0100 - -- Héctor Orón Martínez Tue, 08 Oct 2013 17:23:45 +0000 +gdb (7.6.50.20131214-0ubuntu1) trusty; urgency=medium + + * New upstream snapshot. + + -- Matthias Klose Sat, 14 Dec 2013 12:31:29 +0100 + +gdb (7.6-5ubuntu2) saucy; urgency=low + + * Re-apply changes dropped in last merge: + - gdb suggest gdbserver, instead of depending on it. + - gdb depends on libpython3-stdlib. + + -- Matthias Klose Tue, 30 Jul 2013 09:24:29 +0200 + +gdb (7.6-5ubuntu1) saucy; urgency=low + + * Merge with Debian; remaining changes: + - Add Multi-arch: allowed field to gdb. + - gdb-strings.patch: Fix typo in gdb/remote.c. + - ptrace-error-verbosity.patch: Try to make the PTRACE scope sysctl + more discoverable via a verbose error message when failures happen. + * Build using python3, recommend python3. + + -- Matthias Klose Sun, 28 Jul 2013 10:55:50 +0200 gdb (7.6-5) unstable; urgency=low @@ -1387,100 +1981,60 @@ gdb (7.6-1) unstable; urgency=low -- Héctor Orón Martínez Sun, 19 May 2013 00:14:02 +0200 -gdb (7.5.1-1) experimental; urgency=low +gdb (7.6~20130417-0ubuntu1) raring; urgency=low - * New upstream release (Closes: #685388). - * New upstream features: - [7.5] - - Go language support. - - New targets (x32 ABI, microMIPS, Renesas RL78, HP OpenVMS ia64). - - More Python scripting improvements. - - SDT (Static Defined Tracing) probes support with SystemTap probes. - - GDBserver improvements (stdio connections, target-side evaluation - of breakpoint conditions, remote protocol improvements). - - Other miscellaneous improvements (ability to stop when a shared - library is loaded/unloaded, dynamic printf, etc). - - Reverse debugging on ARM. - - The binary "gdbtui" has been abandoned and can no longer be built. - Use "gdb -tui" instead. - - Better handling of symlinked libraries, like ld.so (Closes: #680173). - [7.5.1] - - Offer some helpful tips when detecting a file/script for which - auto-loading has been declined. - - Special handling of program's '.exe' suffix when searching for - auto-load-able scripts. - * Upstream bugfixes: - [7.5.1] - - strict-aliasing warnings in libiberty/md5.c generated by GCC 4.7. - - An "Attempt to dereference a generic pointer" error (-var-create). - This error only occurs when the "print object" setting is "on". - - Backtrace problems on x32 (PR backtrace/14646). - - next/step/finish problems on x32 (PR gdb/14647). - - A "malformed linespec error: unexpected keyword, [...]" error - (PR breakpoints/14643) - - GDB crash while stepping through powerpc (32bits) code. - - A failed assertion in linux_ptrace_test_ret_to_nx. - - A "!frame_id_inlined_p (frame_id)" failed assertion. - - A "No more reverse-execution history." error during reverse "next" - execution (PR 14548). - - Incomplete command descriptions in "apropos" output. - - PR gdb/14494 (a GDB crash difficult to characterize). - - A build warning in allocate_symtab when building on x86_64-windows. - * Updated patches: - - Tweaked man-page-order.patch and linuxthreads_signal_handling.patch - so they apply to new upstream source. - - Dropped m68k-thread-debugging.patch; upstream already had it. - - Dropped debian-changes-7.3.50~cvs20110627-1 and gdbinit-ownership.patch: - upstream closed [CVE-2005-1705] with a new option "set auto-load - safe-path" (Closes: #694256). - * Drop libgdb-dev, since libgdb.a was dropped upstream. - * Update architecture list for gdbserver. - * Fix documentation symlinking stuff: - - Fix manpage symlinks (Closes: #595179). - - Add "Depends: gdb (= ${binary:Version})" where needed for symlinked - doc directories. - - Migrate gdb-source to a real doc-directory, not a symlink, to avoid - having an :all package depend on a fixed version of an :any package, - which wouldn't survive binNMUs. - * Adjust lintian overrides: - - Use wildcards for dates of unused readline/support/config.{guess,sub}. - - gdb64 is *supposed* to be built for another architecture. - * debian/control: Drop redundant "Section:" fields. - * Configure gdb-multiarch with --enable-64-bit-bfd so it supports 64-bit - targets (Closes: #699582). - * Recommend libc-dbg (Closes: #246315, #309460). - * Bump Standards-Version in debian/control.in too, so it *stays* bumped. - * Add support for debug info compressed with bzip2 and lzma/xz: - Build-Depend on libbz2-dev and liblzma-dev. - * Add myself to Uploaders. + * gdb 7.6 snapshot, taken from the 7.6 release branch. LP: #1166304. + * Build again with Python2, not all pretty printers are ready for 3.x. - -- Samuel Bronson Wed, 20 Feb 2013 17:22:51 -0500 + -- Matthias Klose Thu, 18 Apr 2013 00:00:23 +0200 -gdb (7.4.1+dfsg-0.1) unstable; urgency=low +gdb (7.6~20130408-0ubuntu1) raring; urgency=low - * Non-maintainer upload. - * Fix debian/sanitize-gdb.sh to use bash. - * Run that script to get the expected dfsg-compliant tarball. - (Closes: #698074) + * gdb 7.6 snapshot, taken from the 7.6 release branch. LP: #1166304. + - Adds support for Aarch64. + * Build using Python3. + + -- Matthias Klose Mon, 08 Apr 2013 16:06:17 +0200 + +gdb (7.5-0ubuntu4) raring; urgency=low + + * Use python-config to pick up the python version. + * Build-depend on libpython-dev, python:any. + + -- Matthias Klose Thu, 20 Dec 2012 16:21:32 +0100 + +gdb (7.5-0ubuntu3) raring; urgency=low + + * Remove excessive fclose in gdbinit patch (LP: #1069897). + + -- Dr. David Alan Gilbert Sat, 24 Nov 2012 16:54:53 +0000 + +gdb (7.5-0ubuntu2) quantal; urgency=low - -- David Prévot Sun, 27 Jan 2013 12:18:15 -0400 + [ Mark Russell ] + * Add Multi-arch: allowed field to gdb. (LP: #1036834) -gdb (7.4.1-3) unstable; urgency=low + -- Adam Stokes Thu, 16 Aug 2012 14:29:05 -0400 - * Fix typo: replace mutliarch by multiarch. +gdb (7.5-0ubuntu1) quantal; urgency=low - -- Hector Oron Fri, 05 Oct 2012 08:58:19 +0000 + * New upstream release 7.5. + * Backport fix for PR gdb/14365. LP: #1006860. + * Stop building libgdb-dev (libgdb.a not built anymore). -gdb (7.4.1-2) unstable; urgency=low + -- Matthias Klose Wed, 22 Aug 2012 17:39:32 +0200 - * Fix empty doc directory when upgrading from squeeze to wheezy. - (Closes: #684375) - * d/p/m68k-thread-debugging.patch: - - Add thread debugging function for m68k. Taken from upstream. - Thanks Thorsten Glaser. - * d/control: bump standars version to 3.9.3 +gdb (7.4-2012.06-0ubuntu1) quantal; urgency=low - -- Hector Oron Wed, 19 Sep 2012 21:16:17 +0000 + * Update to the Linaro 7.4-2012.06 release. + + -- Matthias Klose Thu, 14 Jun 2012 09:38:38 +0200 + +gdb (7.4-2012.04-0ubuntu3) quantal; urgency=low + + * Merge packaging bits from Debian unstable. + + -- Matthias Klose Tue, 12 Jun 2012 12:56:30 +0200 gdb (7.4.1-1.1) unstable; urgency=low @@ -1506,114 +2060,156 @@ gdb (7.4.1-1) unstable; urgency=low -- Hector Oron Thu, 26 Apr 2012 18:26:18 +0200 -gdb (7.4really-1) unstable; urgency=low +gdb (7.4-2012.04-0ubuntu2) precise-proposed; urgency=low - * New upstream release: - - Many Python scripting improvements - - Better support for ambiguous linespecs - - Masked watchpoints - - Tracepoint support improvements - - Support for Texas Instruments TMS320C6x (tic6x-*-*) - - A Renesas RL78 simulator (rl78-*-elf) - - Some minor Remote protocol extensions and GDB/MI changes - * Temporarily disable gdb-multiarch and gdb-dbg. - - -- Hector Oron Sat, 28 Jan 2012 00:41:20 +0100 - -gdb (7.4-1~cvs20111117.2) experimental; urgency=low - - * Add build dependency on lib64ncurses5-dev for multilib targets. - - -- Hector Oron Fri, 18 Nov 2011 19:35:17 +0000 - -gdb (7.4-1~cvs20111117.1) experimental; urgency=low - - * Add accidentally dropped armhf to architecture list - * Add GDB debug package (Closes: #592512, #490049) - * Provide GDB multiarch package (Closes: #610519) - - Add gdb-multiarch package supporting extra bfd targets similarly to - binutils-multiarch; the package is constructed much like gdb64 except that - it's build with the gdb configure flags and --enable-targets=all for now. - - Thanks Loïc Minier. - * Fix conflicts between cross and regular gdb (Closes: #603347) - - Pass --gdb-datadir=/usr/share/gdb-$triplet when building a cross-gdb and - update gdb.install sed snippet to match; fixes conflict with gdb; - - Thanks Loïc Minier. - - -- Hector Oron Thu, 17 Nov 2011 18:37:45 +0000 - -gdb (7.4-1~cvs20111117) experimental; urgency=low - - * CVS snapshot release (20111117) - * debian/control.in: Stop using deprecated type-handling Build-Depends - Thanks Guillem Jover. (Closes: #639164) - * debian/control.in: Mention D language support in description - - Also mention other supported languages. (Closes: #595892) - * debian/control.in: Add Vcs-Git, Vcs-Browser and Homepage fields. - * debian/control.in: Bump Standards-Version + * debian/control: enabling gdbserver package for armhf (LP: #989153) - -- Hector Oron Wed, 24 Aug 2011 20:02:33 +0100 + -- Ricardo Salveti de Araujo Thu, 26 Apr 2012 15:59:49 -0300 -gdb (7.3-1) unstable; urgency=low +gdb (7.4-2012.04-0ubuntu1) precise-proposed; urgency=low - * New upstream release, including: - - Initial OpenCL C language support has been added - - C++ enhancements: - * Template parameters are now in scope when debugging in an - instantiation - * The motion commands "next", "finish", "until", and "advance" now - work better when exceptions are thrown - - Improved Python support, enhancing the existing APIs as well as - introducing new ones. - - Improved thread debugging support: - * GDB now understands thread names - * A new command "thread find [REGEXP]" has been added - - GDBserver enhancements: - * Support for PowerPC LynxOS (versions 4.x and 5.x) and i686 LynxOS - (version 5.x) - * Support for Blackfin Linux - - Support for reading and writing a new .gdb_index section, - containing a fast index of DWARF debugging info - - Various GDB/MI improvements - - Support for ia64 HP-UX (ia64-*-hpux*) has been added - - Target support for Analog Devices, Inc. Blackfin Processors (bfin-*) - - GNU simulator improvements: - * New --map-info flag - * CFI flash simulation support - - Other worthy improvments (in random order): - * The "catch syscall" command is now available on mips-linux. - * New GDB Commands: "set directories" - * Support for using labels in linespecs (Eg you can use "advance label") - * The "watch" command now accepts an optional "-location" argument - * Thread debugging of core dumps now supported on GNU/Linux - * Ranged breakpoints support (PowerPC BookE running Linux 2.6.34 or later) - * Support for Ada task switching inside programs using the Ravenscar profile - - See gdb/NEWS for more detailed information. - - -- Hector Oron Tue, 23 Aug 2011 11:13:36 +0100 - -gdb (7.3.50~cvs20110627-2) experimental; urgency=low - - * Restrict prelink build depend to linux-any architectures. - * Fix cross-build target: - - Set DEB_BUILD_GNU_TYPE and use it for --build= instead of - DEB_HOST_GNU_TYPE; Thanks Loïc Minier (Closes: #601028) - * Add preliminary support for armhf. - - Thanks Konstantinos Margaritis (Closes: #596953) - - -- Hector Oron Tue, 05 Jul 2011 22:37:20 +0100 - -gdb (7.3.50~cvs20110627-1) experimental; urgency=low - - * Upstream pre-release based on CVS date 20110627. - * Drop Daniel Jacobowitz as Maintainer. - - Thanks for all this years. - * Add myself as Maintainer. - * Bump standards version. - * Add local-option for unapply-patches. - * Add prelink build depend, needed for tests run. + * Update to the Linaro 7.4-2012.04 release. LP: #984994. + + -- Matthias Klose Wed, 18 Apr 2012 17:08:57 +0200 + +gdb (7.4-2012.02-0ubuntu2) precise; urgency=low + + * Update and re-enable the gdb-7.2-gcore-relro-writer patch (Steve Beattie). + LP: #954714. + + -- Matthias Klose Fri, 16 Mar 2012 01:32:38 +0100 + +gdb (7.4-2012.02-0ubuntu1) precise; urgency=low + + * Update to the Linaro 7.4-2012.02 release. + * Disable the gdb-7.2-gcore-relro-writer patch (needs an update). + + -- Matthias Klose Tue, 13 Mar 2012 20:12:36 +0100 + +gdb (7.4-0ubuntu1) precise; urgency=low + + * gdb 7.4 release. + + -- Matthias Klose Tue, 24 Jan 2012 11:23:25 +0100 + +gdb (7.3.92-0ubuntu3) precise; urgency=low + + * Fix PR 9538 (handle debuginfo for symlinked files), taken from the trunk. + + -- Matthias Klose Tue, 24 Jan 2012 11:08:40 +0100 + +gdb (7.3.92-0ubuntu2) precise; urgency=low + + * Build-depend on lib64ncurses5-dev [i386 powerpc s390 sparc]. + + -- Matthias Klose Sat, 21 Jan 2012 01:45:54 +0100 + +gdb (7.3.92-0ubuntu1) precise; urgency=low + + * gdb-7.4 release candidate 2. + + -- Matthias Klose Fri, 20 Jan 2012 21:26:22 +0100 + +gdb (7.3.1-2011.12-0ubuntu1) precise; urgency=low + + * Update to the Linaro 7.3-2011-12 release. + + -- Matthias Klose Fri, 09 Dec 2011 16:15:50 +0100 + +gdb (7.3-0ubuntu2) oneiric; urgency=low + + * Update to the Linaro 7.3-2011-08 release. + + -- Matthias Klose Thu, 18 Aug 2011 11:00:25 +0200 + +gdb (7.3-0ubuntu1) oneiric; urgency=low + + * New upstream release. + * Update Linaro changes to 7.3-2011-08~. + + -- Matthias Klose Mon, 08 Aug 2011 07:45:57 +0200 + +gdb (7.2-1ubuntu11) natty; urgency=low - -- Hector Oron Tue, 28 Jun 2011 10:30:52 +0100 + * Fix minor ARM prologue parsing bug (Ulrich Weigand). LP: #684218. + + -- Matthias Klose Thu, 24 Mar 2011 10:41:22 +0100 + +gdb (7.2-1ubuntu10) natty; urgency=low + + * Update with changes from the Linaro 7.2-2011.03-0 release (Ulrich Weigand). + * Configure with --with-pkgversion, don't run post-patches. + + -- Matthias Klose Tue, 15 Mar 2011 16:14:08 +0100 + +gdb (7.2-1ubuntu9) natty; urgency=low + + * Set MULTIARCH_TARGETS similarly to binutils-multiarch to avoid the need + for users to specify which actual target they care about. + + -- Loïc Minier Tue, 08 Mar 2011 14:31:09 +0100 + +gdb (7.2-1ubuntu8) natty; urgency=low + + * Add gdb-multiarch package supporting extra bfd targets similarly to + binutils-multiarch; the package is constructed much like gdb64 except that + it's build with the gdb configure flags and --enable-targets=all for now. + * New patch, disable-werror-on-coff-tic, fixes build of coff stuff with + gcc-4.5; from upstream mailing-list. + + -- Loïc Minier Tue, 18 Jan 2011 17:44:56 +0100 + +gdb (7.2-1ubuntu7) natty; urgency=low + + * Pass --gdb-datadir=/usr/share/gdb-$triplet when building a cross-gdb and + update gdb.install sed snippet to match; fixes conflict with gdb; + Debian #603347. + + -- Loïc Minier Mon, 17 Jan 2011 17:50:20 +0100 + +gdb (7.2-1ubuntu6) natty; urgency=low + + * Add support to "gcore" command for executables with GNU_RELRO + sections (Debian bug 606667, LP: #680588). + + -- Kees Cook Thu, 09 Dec 2010 19:47:22 -0800 + +gdb (7.2-1ubuntu5) natty; urgency=low + + * Rebuild with python 2.7. + + -- Matthias Klose Thu, 09 Dec 2010 15:09:43 +0100 + +gdb (7.2-1ubuntu4) natty; urgency=low + + * No-change upload to drop upstream changelog. + + -- Martin Pitt Fri, 03 Dec 2010 08:55:48 +0100 + +gdb (7.2-1ubuntu3) maverick-proposed; urgency=low + + * Re-add debian/patches/ptrace-error-verbosity.patch that got + accidentally dropped in the 7.2 merge: try to make PTRACE scope + sysctl more discoverable (LP: #667815). + + -- Kees Cook Thu, 28 Oct 2010 07:16:05 -0700 + +gdb (7.2-1ubuntu2) maverick; urgency=low + + * Really disable building the gdb-minimal package. + + -- Matthias Klose Mon, 06 Sep 2010 13:43:20 +0200 + +gdb (7.2-1ubuntu1) maverick; urgency=low + + * Merge with Debian; remaining changes: + - PIE testsuite support. + - Fix some typos in messages. + - Don't build the gdb-minimal package. + - Install symlink to compressed gdb64 manpage. + - Don't install the upstream changelog in gdbserver. + + -- Matthias Klose Mon, 06 Sep 2010 11:43:18 +0200 gdb (7.2-1) unstable; urgency=low @@ -1641,6 +2237,36 @@ gdb (7.1-2) unstable; urgency=low -- Daniel Jacobowitz Tue, 31 Aug 2010 10:57:57 -0400 +gdb (7.1-1ubuntu4) maverick; urgency=low + + * debian/patches/ptrace-error-verbosity.patch: update for new yama path. + + -- Kees Cook Tue, 06 Jul 2010 15:26:03 -0700 + +gdb (7.1-1ubuntu3) maverick; urgency=low + + * Add debian/patches/ptrace-error-verbosity.patch: try to make PTRACE + scope sysctl more discoverable. + + -- Kees Cook Tue, 08 Jun 2010 15:46:44 -0700 + +gdb (7.1-1ubuntu2) lucid; urgency=low + + * Fix TBB TBH decoding in Thumb-2, patch taken from the trunk. + + -- Matthias Klose Thu, 08 Apr 2010 11:48:33 +0200 + +gdb (7.1-1ubuntu1) lucid; urgency=low + + * Merge with Debian; remaining changes: + - PIE testsuite support. + - Fix some typos in messages. + - Don't build the gdb-minimal package. + - Install symlink to compressed gdb64 manpage. + - Don't install the upstream changelog in gdbserver. + + -- Matthias Klose Sat, 20 Mar 2010 14:19:26 +0100 + gdb (7.1-1) unstable; urgency=low * New upstream release, including: @@ -1660,6 +2286,45 @@ gdb (7.1-1) unstable; urgency=low -- Daniel Jacobowitz Sat, 20 Mar 2010 01:21:29 -0400 +gdb (7.0.90.20100309-0ubuntu2) lucid; urgency=low + + [ Matthias Klose ] + * Snapshot, taken from the 7.1 release branch. + * Adjust patches, remove obsolete patches. + + [ Kees Cook ] + * Rebase PIE testsuite, updates patch series. + + -- Matthias Klose Wed, 10 Mar 2010 01:25:14 +0100 + +gdb (7.0.1-2ubuntu3) lucid; urgency=low + + * On ARM, add support for single-stepping through IF-THEN blocks (taken + from the trunk). + + -- Matthias Klose Tue, 09 Mar 2010 15:37:16 +0100 + +gdb (7.0.1-2ubuntu2) lucid; urgency=low + + * gdb: Make gdbserver a suggestion instead of a dependency. + * gdbserver: Don't install the toplevel upstream changelog. + + -- Matthias Klose Sat, 27 Feb 2010 10:58:31 +0100 + +gdb (7.0.1-2ubuntu1) lucid; urgency=low + + * Merge with Debian; remaining changes: + - debian/rules: on sparc, configure the 64bit build with --disable-werror. + - Work around a build failure on the ia64 buildd. + - PIE support. + - Add patch to handle debug_info less frames better. + - Fix some typos in messages. + - reduce build-id verbosity. + - fixup PPC auxv prototype. + * Don't build the gdb-minimal package. + + -- Matthias Klose Tue, 23 Feb 2010 18:27:19 +0100 + gdb (7.0.1-2) unstable; urgency=low * Add Replaces to the new gdbserver package (Closes: #567925, #568018). @@ -1683,6 +2348,34 @@ gdb (7.0.1-1) unstable; urgency=low -- Daniel Jacobowitz Sat, 30 Jan 2010 15:16:35 -0500 +gdb (7.0.1-0ubuntu1) lucid; urgency=low + + * New upstream version. + + -- Matthias Klose Thu, 31 Dec 2009 10:07:48 +0100 + +gdb (7.0-1ubuntu2) lucid; urgency=low + + * [arm] Prevent disassembler from aborting on an invalid Thumb2 instruction, + taken from the trunk. + + -- Matthias Klose Tue, 15 Dec 2009 14:41:05 +0100 + +gdb (7.0-1ubuntu1) lucid; urgency=low + + * Merge with Debian; remaining changes: + - debian/rules: on sparc, configure the 64bit build with --disable-werror. + - Work around a build failure on the ia64 buildd. + - PIE support. + - Add patch to handle debug_info less frames better. + - Fix some typos in messages. + - reduce build-id verbosity. + - fixup PPC auxv prototype. + * Update to the 7.0 branch 20091120. + - Add Thumb2 debugging for armel. + + -- Matthias Klose Fri, 20 Nov 2009 14:48:57 -0600 + gdb (7.0-1) unstable; urgency=low * New upstream release (Closes: #550567). @@ -1690,6 +2383,45 @@ gdb (7.0-1) unstable; urgency=low -- Daniel Jacobowitz Sun, 11 Oct 2009 17:16:26 -0400 +gdb (7.0-0ubuntu1) karmic; urgency=low + + * 7.0 final release. + - Fix PR gdb/10649. + + -- Matthias Klose Fri, 09 Oct 2009 09:27:53 +0200 + +gdb (6.8.92-0ubuntu1) karmic; urgency=low + + * 7.0 prerelease 2. + + -- Matthias Klose Thu, 01 Oct 2009 15:04:44 +0200 + +gdb (6.8.90.20090918-0ubuntu2) karmic; urgency=low + + * Update gdb-workaround-rh-stack-off.patch: + - reduce build-id verbosity. + - fixup PPC auxv prototype. + + -- Kees Cook Sat, 19 Sep 2009 10:26:41 -0700 + +gdb (6.8.90.20090918-0ubuntu1) karmic; urgency=low + + [ Matthias Klose ] + * Merge with Debian; remaining changes: + - debian/rules: on sparc, configure the 64bit build with --disable-werror. + * Update to the 7.0 release branch. + + [ Kees Cook ] + * Add patches to support PIE, thanks to RH's 6.8.91.20090917 branch: + - gdb-6.3-test-pie-20050107.patch + - gdb-6.5-bz203661-emit-relocs.patch + - gdb-workaround-rh-stack-on.patch (workaround lack of Archer, CRC) + - gdb-6.6-buildid-locate.patch + - gdb-6.3-pie-20050110.patch + - gdb-workaround-rh-stack-off.patch (undo workarounds) + + -- Matthias Klose Sat, 19 Sep 2009 15:38:43 +0000 + gdb (6.8.50.20090628-4) unstable; urgency=low * Mention online documentation in README.Debian (Closes: #537795). @@ -1723,6 +2455,31 @@ gdb (6.8.50.20090628-2) unstable; urgenc -- Daniel Jacobowitz Mon, 06 Jul 2009 14:52:31 -0400 +gdb (6.8.50.20090628-1ubuntu3) karmic; urgency=low + + * Refresh PIE support patches to gain analysis of PIE core files. + + -- Kees Cook Tue, 14 Jul 2009 13:20:57 -0700 + +gdb (6.8.50.20090628-1ubuntu2) karmic; urgency=low + + * Replace the gdbtui binary by a shell script. LP: #244065. + * Enable parallel builds. + + -- Matthias Klose Mon, 06 Jul 2009 13:59:42 +0200 + +gdb (6.8.50.20090628-1ubuntu1) karmic; urgency=low + + * Merge with Debian; remaining changes: + - debian/rules: on sparc, configure the 64bit build with --disable-werror. + - Support nocheck and parallel= in DEB_BUILD_OPTIONS. + - lpia fix for running the check target. + - Work around a build failure on the ia64 buildd. + * Disable patches (not yet updated): pie-support-alt, pie-support-tests, + handle-nodebuginfo-better. + + -- Matthias Klose Mon, 06 Jul 2009 09:51:58 +0200 + gdb (6.8.50.20090628-1) unstable; urgency=low * New snapshot from trunk. The experimental packages used the @@ -1801,9 +2558,28 @@ gdb (6.8.50.20081120.python-1) experimen and m68k-nat-build-fix.patch, merged upstream. * Build depend on procps for testsuite cleanup calls to "kill". * Remove use of -p0 in series file (Closes: #484945). - + -- Daniel Jacobowitz Fri, 28 Nov 2008 14:28:47 -0500 +gdb (6.8-3ubuntu2) intrepid; urgency=low + + * debian/rules: on sparc, configure the 64bit build with --disable-werror. + * Reapply debian/patches/gdb-cvs-reinit_frame_cache.patch. LP: #196274. + + -- Matthias Klose Tue, 24 Jun 2008 15:42:23 +0200 + +gdb (6.8-3ubuntu1) intrepid; urgency=low + + * Merge with Debian; remaining changes: + - PIE support. + - dwarf2-stack-boundry.diff - security fix for CVE-2006-4146. + - Add patch to handle debug_info less frames better. + - Fix some typos in messages. + * Fix build errors with gcc-4.3. + * TODO: Fix testcases failing with default hardening options. + + -- Matthias Klose Tue, 24 Jun 2008 15:42:23 +0200 + gdb (6.8-3) unstable; urgency=low * Initialize some uninitialized variables (Closes: #479561). @@ -1823,6 +2599,28 @@ gdb (6.8-2) unstable; urgency=low -- Daniel Jacobowitz Fri, 02 May 2008 18:28:37 -0400 +gdb (6.8-1ubuntu2) hardy-proposed; urgency=low + + [ Robert Collins ] + * Add patch from Michael Matz to handle debug_info less frames better. + Origin of patch: https://bugzilla.novell.com/show_bug.cgi?id=390722#c25 + (LP: #111869). + + [ Martin Pitt ] + * Port above patch for amd64, too, since it suffers from the same problem. + + -- Robert Collins Mon, 26 May 2008 11:49:07 +0200 + +gdb (6.8-1ubuntu1) hardy; urgency=low + + * Merge with Debian; remaining changes: + - PIE support. + - dwarf2-stack-boundry.diff - security fix for CVE-2006-4146. + * Remove patches merged upstream. + * Update pie-support patch. + + -- Matthias Klose Tue, 01 Apr 2008 15:25:20 +0200 + gdb (6.8-1) unstable; urgency=low * New upstream release. @@ -1839,6 +2637,33 @@ gdb (6.8-1) unstable; urgency=low -- Daniel Jacobowitz Thu, 27 Mar 2008 18:13:39 -0400 +gdb (6.7.1-2ubuntu3) hardy; urgency=low + + * debian/patches/pie-support.patch: updated for 6.7.1; works for + attach and core, but not "run". + * debian/patches/pie-support-tests.patch: re-enabled, some failures remain. + * debian/rules: fix logic to enable running testsuite by default. + + -- Kees Cook Thu, 20 Mar 2008 02:00:27 -0700 + +gdb (6.7.1-2ubuntu2) hardy; urgency=low + + * debian/patches/gdb-cvs-reinit_frame_cache.patch: upstream fix for SEGV + when dealing with register caches (LP: #196274). + + -- Kees Cook Fri, 07 Mar 2008 09:51:58 -0800 + +gdb (6.7.1-2ubuntu1) hardy; urgency=low + + * Merge with Debian; remaining changes: + - Do not depend on type-handling. + - PIE support. + - dwarf2-stack-boundry.diff - security fix for CVE-2006-4146. + * Add patch from Ulrich Weigand to fix stepping over shared library + functions on PowerPC (Closes: #432461). LP: #137312. + + -- Matthias Klose Mon, 14 Jan 2008 17:32:12 +0100 + gdb (6.7.1-2) unstable; urgency=low * Add patch from Ulrich Weigand to fix stepping over shared library @@ -1850,6 +2675,16 @@ gdb (6.7.1-2) unstable; urgency=low -- Daniel Jacobowitz Wed, 02 Jan 2008 08:49:43 -0500 +gdb (6.7.1-1ubuntu1) hardy; urgency=low + + * Merge with Debian; remaining changes: + - Do not depend on type-handling. + - PIE support. + - dwarf2-stack-boundry.diff - security fix for CVE-2006-4146. + * Add build-dependency on lib64expat1-dev. + + -- Matthias Klose Tue, 04 Dec 2007 09:13:57 +0100 + gdb (6.7.1-1) unstable; urgency=low * New upstream release. @@ -1892,6 +2727,55 @@ gdb (6.6.dfsg-2) unstable; urgency=low -- Daniel Jacobowitz Thu, 23 Aug 2007 22:26:20 -0400 +gdb (6.6.dfsg-1ubuntu7) gutsy; urgency=low + + * Cross-compile gdb64. + * Don't try to install gdbserver on architectures where it doesn't exist. + + -- Matthias Klose Mon, 10 Sep 2007 21:28:07 +0200 + +gdb (6.6.dfsg-1ubuntu6) gutsy; urgency=low + + * Fix build failures on targets only building gdb. + * Remove the gdb32 package. + * Fix typos in message strings (LP: #63200). + + -- Matthias Klose Fri, 07 Sep 2007 18:06:20 +0000 + +gdb (6.6.dfsg-1ubuntu5) gutsy; urgency=low + + * Build a gdb64/gdb32 package on biarch architectures. LP: #25559. + * Set Ubuntu maintainer address. + + -- Matthias Klose Wed, 15 Aug 2007 19:01:05 +0000 + +gdb (6.6.dfsg-1ubuntu4) gutsy; urgency=low + + * Fix register definitions for hppa (Randolph Chung). + + -- Matthias Klose Fri, 03 Aug 2007 17:11:20 +0000 + +gdb (6.6.dfsg-1ubuntu3) gutsy; urgency=low + + * Run the testsuite on lpia. + + -- Matthias Klose Sat, 28 Jul 2007 18:32:30 +0200 + +gdb (6.6.dfsg-1ubuntu2) feisty; urgency=low + + * Reenable the workaround for a build failure on the ia64 buildd. + + -- Matthias Klose Sun, 11 Feb 2007 23:34:47 +0100 + +gdb (6.6.dfsg-1ubuntu1) feisty; urgency=low + + * Merge with Debian unstable; remaining changes: + - Do not depend on type-handling. + - PIE support. + - dwarf2-stack-boundry.diff - security fix for CVE-2006-4146. + + -- Matthias Klose Sun, 11 Feb 2007 14:54:38 +0100 + gdb (6.6.dfsg-1) unstable; urgency=low [ Matthias Klose ] @@ -1913,6 +2797,43 @@ gdb (6.6.dfsg-1) unstable; urgency=low -- Daniel Jacobowitz Sat, 27 Jan 2007 21:59:06 -0500 +gdb (6.6-0ubuntu1) feisty; urgency=low + + * New upstream version. + * sim-destdir.patch, gdbinit-ownership.patch, bfd-get-mtime-less.patch, + pie-support.patch, thread-db-multiple-libraries.patch: Update. + * thread-db-live-threads.patch, fork-context-switch.patch, + glibc2.5-gnu-hash.patch: Remove, applied upstream. + + -- Matthias Klose Thu, 4 Jan 2007 15:11:39 +0100 + +gdb (6.5.dfsg-2ubuntu3) feisty; urgency=low + + * Add PIE support, taken from Fedora patch bundle: + - debian/patches/pie-support.patch: core PIE support. + - debian/patches/pie-support-tests.patch: PIE operational tests. + * debian/rules: drop use of "tee" to solve strange hangs on i386/amd64. + + -- Kees Cook Thu, 14 Dec 2006 15:05:33 -0800 + +gdb (6.5.dfsg-2ubuntu2) feisty; urgency=low + + * Add debian/patches/glibc2.5-gnu-hash.patch: + - Teach gdb how to deal with glibc 2.5's .gnu.hash sections, so that gdb + works on feisty at all. + - Patch taken from upstream CVS head. + - Closes: LP#73724 + + -- Martin Pitt Thu, 14 Dec 2006 09:17:51 +0100 + +gdb (6.5.dfsg-2ubuntu1) feisty; urgency=low + + * Merge from debian unstable. Changes left: + - type-handling + - 'dwarf2-stack-boundry.diff' - security fix for CVE-2006-4146 + + -- Michael Vogt Thu, 23 Nov 2006 06:56:42 +0100 + gdb (6.5.dfsg-2) unstable; urgency=low * Backport a patch to fix GDB segfaults on threaded programs. @@ -1930,6 +2851,33 @@ gdb (6.5.dfsg-1) unstable; urgency=low -- Daniel Jacobowitz Sun, 5 Nov 2006 18:33:48 -0500 +gdb (6.4.90.dfsg-1ubuntu3) edgy; urgency=low + + * SECURITY UPDATE: fix local arbitrary code execution in DWARF processing. + * Add 'dwarf2-stack-boundry.diff': limits the DWARF operation stack. + Without this, arbitrary code execution would be possible if a user + were tricked into debugging an executable with malicious DWARF headers. + * References: + CVE-2006-4146 + https://bugzilla.redhat.com/bugzilla/show_bug.cgi?id=204845 + + -- Kees Cook Thu, 28 Sep 2006 11:13:50 -0700 + +gdb (6.4.90.dfsg-1ubuntu2) edgy; urgency=low + + * debian/patches/from_upstream_fix_context_switch.patch: + - upstream patch (http://sourceware.org/ml/gdb-cvs/2006-09/msg00053.html), + should fix a multi-threading issue (Ubuntu: #56391) + + -- Sebastien Bacher Fri, 29 Sep 2006 17:42:43 +0200 + +gdb (6.4.90.dfsg-1ubuntu1) edgy; urgency=low + + * Merge from debian unstable: + - left only type-handling bit. + + -- Fabio M. Di Nitto Tue, 04 Jul 2006 07:46:08 +0200 + gdb (6.4.90.dfsg-1) unstable; urgency=low * New upstream snapshot (GDB 6.5 prerelease). @@ -1951,6 +2899,55 @@ gdb (6.4.90.dfsg-1) unstable; urgency=lo -- Daniel Jacobowitz Tue, 6 Jun 2006 09:23:45 -0400 +gdb (6.4-1ubuntu5) dapper; urgency=low + + Changes by David S. Miller: + + * Fix linux_nat regression introduced with the last upload. + + -- Fabio M. Di Nitto Tue, 09 May 2006 07:48:51 +0200 + +gdb (6.4-1ubuntu4) dapper; urgency=low + + Changes by David S. Miller: + + * Fix core file generation on sparc. + + * sparc patches split and clean up as applied upstream. + + -- Fabio M. Di Nitto Sat, 06 May 2006 06:44:31 +0200 + +gdb (6.4-1ubuntu3) dapper; urgency=low + + Changes by David S. Miller: + + * Fix signal frame handling on sparc and use dwarf2 frame unwinding on + sparc/linux: + - Add patch sparc-dwarf2-and-sigframe.patch. + - Update debian/patches/series. + + -- Fabio M. Di Nitto Thu, 06 Apr 2006 07:16:23 +0200 + +gdb (6.4-1ubuntu2) dapper; urgency=low + + Changes by David S. Miller: + + * Fix sparc threads support: + - Add patch gdb-sparclinux-threads.patch. + - Update debian/patches/series. + + NOTE: the patch will work only with properly patched kernel. + The patch should be in 2.6.15-20 kernel serie. + + -- Fabio M. Di Nitto Sun, 02 Apr 2006 09:42:13 +0200 + +gdb (6.4-1ubuntu1) dapper; urgency=low + + * merged with debian, + * debian/control, debian/rules: Remove type-handling. + + -- Michael Vogt Wed, 28 Dec 2005 11:19:23 +0100 + gdb (6.4-1) unstable; urgency=low * New upstream release. @@ -1966,6 +2963,12 @@ gdb (6.4-1) unstable; urgency=low -- Daniel Jacobowitz Sun, 11 Dec 2005 13:14:04 -0500 +gdb (6.3.90.20051119-1ubuntu1) dapper; urgency=low + + * debian/control, debian/rules: Remove type-handling. + + -- Martin Pitt Mon, 21 Nov 2005 19:50:49 +0000 + gdb (6.3.90.20051119-1) unstable; urgency=low * New upstream snapshot (6.4 branch prerelease). diff -pruN 16.3-5/debian/control 16.3-5ubuntu1/debian/control --- 16.3-5/debian/control 2025-08-31 18:57:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/control 2025-11-06 07:32:59.000000000 +0000 @@ -1,5 +1,6 @@ Source: gdb -Maintainer: Debian GDB Team +Maintainer: Ubuntu Developers +XSBC-Original-Maintainer: Debian GDB Team Uploaders: Héctor Orón Martínez , Sergio Durigan Junior Section: devel Priority: optional @@ -31,7 +32,7 @@ Build-Depends: libzstd-dev, libbabeltrace-dev, libipt-dev [amd64 i386 x32], - libsource-highlight-dev, + libsource-highlight-dev [!i386], libxxhash-dev, libmpfr-dev, pkgconf, @@ -40,6 +41,7 @@ Build-Depends: libunwind-dev [ia64], # debuginfod libdebuginfod-dev [linux-any], + libc6-dbg [armhf], # Reproducible build faketime, Vcs-Git: https://salsa.debian.org/gdb-team/gdb.git @@ -50,9 +52,10 @@ Package: gdb Architecture: any Depends: ${misc:Depends}, ${shlibs:Depends}, + libc6-dbg [armhf], +Recommends: libc-dbg Suggests: gdb-doc, gdbserver [linux-any], - libc-dbg Breaks: gdb-minimal (<< 15.2-2~exp1) Replaces: gdb-minimal (<< 15.2-2~exp1) Provides: gdb-minimal @@ -117,3 +120,18 @@ Description: GNU Debugger (source) . This package contains the sources and patches which are needed to build GDB. + +Package: gdb-doc +Architecture: all +Section: doc +Depends: ${misc:Depends} +Breaks: gdb (<< 7.8), gdbserver (<< 7.8) +Replaces: gdb (<< 7.8), gdbserver (<< 7.8) +Description: The GNU Debugger Documentation + GDB is a source-level debugger, capable of breaking programs at + any specific line, displaying variable values, and determining + where errors occurred. Currently, it works for C, C++, Fortran, + Modula 2 and Java programs. A must-have for any serious + programmer. + . + This package contains the GDB manual. diff -pruN 16.3-5/debian/control.in 16.3-5ubuntu1/debian/control.in --- 16.3-5/debian/control.in 2025-08-31 18:57:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/control.in 2025-11-06 07:32:59.000000000 +0000 @@ -1,5 +1,6 @@ Source: gdb -Maintainer: Debian GDB Team +Maintainer: Ubuntu Developers +XSBC-Original-Maintainer: Debian GDB Team Uploaders: Héctor Orón Martínez , Sergio Durigan Junior Section: devel Priority: optional @@ -31,7 +32,7 @@ Build-Depends: libzstd-dev, libbabeltrace-dev, libipt-dev [amd64 i386 x32], - libsource-highlight-dev, + libsource-highlight-dev [!i386], libxxhash-dev, libmpfr-dev, pkgconf, @@ -40,6 +41,7 @@ Build-Depends: libunwind-dev [ia64], # debuginfod libdebuginfod-dev [linux-any], + libc6-dbg [armhf], # Reproducible build faketime, Vcs-Git: https://salsa.debian.org/gdb-team/gdb.git @@ -50,10 +52,11 @@ Package: gdb@TS@ Architecture: any Depends: ${misc:Depends}, ${shlibs:Depends}, + libc6-dbg [armhf], ${python3:Depends} +Recommends: libc-dbg Suggests: gdb-doc, gdbserver [linux-any], - libc-dbg Breaks: gdb-minimal (<< 15.2-2~exp1) Replaces: gdb-minimal (<< 15.2-2~exp1) Provides: gdb-minimal diff -pruN 16.3-5/debian/gdb.install 16.3-5ubuntu1/debian/gdb.install --- 16.3-5/debian/gdb.install 2025-08-31 18:57:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/gdb.install 2025-11-06 07:32:59.000000000 +0000 @@ -3,6 +3,8 @@ usr/bin/gcore usr/bin/gstack usr/share/gdb usr/include/gdb/jit-reader.h -# usr/share/man/man1/gdb.1 -# usr/share/man/man1/gdb-add-index.1 -# usr/share/man/man5/gdbinit.5 +usr/share/man/man1/gdb.1 +usr/share/man/man1/gdb-add-index.1 +usr/share/man/man1/gcore.1 +usr/share/man/man1/gstack.1 +usr/share/man/man5/gdbinit.5 diff -pruN 16.3-5/debian/gdbserver.install 16.3-5ubuntu1/debian/gdbserver.install --- 16.3-5/debian/gdbserver.install 2025-08-31 18:57:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/gdbserver.install 2025-11-06 07:32:59.000000000 +0000 @@ -1,3 +1,3 @@ usr/bin/gdbserver -# usr/share/man/man1/gdbserver.1 +usr/share/man/man1/gdbserver.1 diff -pruN 16.3-5/debian/patches/gdb-strings.patch 16.3-5ubuntu1/debian/patches/gdb-strings.patch --- 16.3-5/debian/patches/gdb-strings.patch 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/patches/gdb-strings.patch 2025-11-06 07:32:59.000000000 +0000 @@ -0,0 +1,15 @@ +Description: fix grammar in warning message + +Index: b/gdb/remote.c +=================================================================== +--- a/gdb/remote.c ++++ b/gdb/remote.c +@@ -11248,7 +11248,7 @@ compare_sections_command (const char *ar + } + } + if (mismatched > 0) +- warning (_("One or more sections of the target image does " ++ warning (_("One or more sections of the target image do " + "not match the loaded file")); + if (args && !matched) + gdb_printf (_("No loaded section named '%s'.\n"), args); diff -pruN 16.3-5/debian/patches/ptrace-error-verbosity.patch 16.3-5ubuntu1/debian/patches/ptrace-error-verbosity.patch --- 16.3-5/debian/patches/ptrace-error-verbosity.patch 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/debian/patches/ptrace-error-verbosity.patch 2025-11-06 07:32:59.000000000 +0000 @@ -0,0 +1,26 @@ +Description: try to make the PTRACE scope sysctl more discoverable via a + verbose error message when failures happen. +Author: Kees Cook + +Index: b/gdb/inf-ptrace.c +=================================================================== +--- a/gdb/inf-ptrace.c ++++ b/gdb/inf-ptrace.c +@@ -207,7 +207,16 @@ inf_ptrace_attach (struct target_ops *op + errno = 0; + ptrace (PT_ATTACH, pid, (PTRACE_TYPE_ARG3)0, 0); + if (errno != 0) +- perror_with_name (("ptrace")); ++ { ++ if (errno == EPERM) ++ { ++ printf_unfiltered ( ++ _("Could not attach to process. If your uid matches the uid of the target\n" ++ "process, check the setting of /proc/sys/kernel/yama/ptrace_scope, or try\n" ++ "again as the root user. For more details, see /etc/sysctl.d/10-ptrace.conf\n")); ++ } ++ perror_with_name (("ptrace")); ++ } + #else + error (_("This system does not support attaching to a process")); + #endif diff -pruN 16.3-5/debian/patches/series 16.3-5ubuntu1/debian/patches/series --- 16.3-5/debian/patches/series 2025-09-05 18:17:07.000000000 +0000 +++ 16.3-5ubuntu1/debian/patches/series 2025-11-06 07:32:59.000000000 +0000 @@ -1,6 +1,10 @@ load-versioned-libcc1.patch fix-blhc-libiberty.patch fix-blhc-chew.patch -gfdl-dont-build-manpages.patch +#gfdl-dont-build-manpages.patch Port-GDB-to-Hurd-x86_64.patch fix-hurd-amd64-warning-osabi.patch + +# Ubuntu/Linaro +gdb-strings.patch +ptrace-error-verbosity.patch diff -pruN 16.3-5/debian/rules 16.3-5ubuntu1/debian/rules --- 16.3-5/debian/rules 2025-09-01 21:48:59.000000000 +0000 +++ 16.3-5ubuntu1/debian/rules 2025-11-06 07:32:59.000000000 +0000 @@ -9,6 +9,10 @@ COMMA = , # The top-level configure script fails to pass these down properly ... export DEB_BUILD_MAINT_OPTIONS = hardening=+all +ifneq (,$(filter $(DEB_HOST_ARCH),ppc64el)) + export DEB_BUILD_MAINT_OPTIONS += optimize=-lto +endif + DPKG_EXPORT_BUILDFLAGS = 1 include /usr/share/dpkg/buildflags.mk @@ -119,6 +123,11 @@ ifeq (,$(findstring linux, $(DEB_HOST_GN run_tests = only enabled for Linux targets endif +# FIXME: hanging on the Ubuntu buildds? +#ifneq (,$(filter armhf, $(DEB_HOST_ARCH))) +# run_tests := not enabled for $(DEB_HOST_ARCH) +#endif + ifdef GDB_TARGET run_tests = disabled for cross builds endif @@ -157,6 +166,7 @@ common_configure_args = \ --host=$(DEB_HOST_GNU_TYPE) \ --prefix=/usr \ --libexecdir="\$${prefix}/lib/gdb" \ + --disable-werror \ --disable-maintainer-mode \ --disable-dependency-tracking \ --disable-silent-rules \ @@ -173,6 +183,8 @@ common_configure_args = \ $(if $(filter linux, $(DEB_HOST_ARCH_OS)),--with-debuginfod) \ $(arch_config_args) \ +# $(if $(filter $(DEB_HOST_ARCH), armhf arm64 mips mipsel ppc64el riscv64),--disable-sim) \ + default_configure_args = \ $(common_configure_args) \ $(configure_target_args) \ @@ -195,6 +207,10 @@ builddir_source = build/gdb %: dh $@ +override_dh_auto_clean: + dh_auto_clean + rm -f gdb/doc/GDBvn.texi + # There's no need to run autoreconf as upstream already ships a # working configure script. override_dh_autoreconf: @@ -275,6 +291,9 @@ ifeq ($(run_tests),yes) ifeq ($(with_multiarch),yes) $(call test-gdb,multiarch) endif + @echo "===== TEST SUMMARY BEGIN =====" + -cat $(builddir_default)/gdb/testsuite/gdb.sum + @echo "===== TEST SUMMARY END =====" else @echo "***Tests disabled: $(run_tests) ***" endif @@ -327,15 +346,16 @@ ifeq ($(with_doc),yes) fi endif -ifneq ($(GFDL_INVARIANT_FREE),yes) - mkdir -p debian/gdb$(TS)/usr/share/man/man5 - install -m 644 $(builddir_default)/gdb/doc/gdbinit.5 \ - debian/gdb$(TS)/usr/share/man/man5/. - install -m 644 $(builddir_default)/gdb/doc/gdb.1 \ - debian/gdb$(TS)/usr/share/man/man1/. - install -m 644 $(builddir_default)/gdb/doc/gdb-add-index.1 \ - debian/gdb$(TS)/usr/share/man/man1/. -endif +# FIXME: now in gdb.install +#ifneq ($(GFDL_INVARIANT_FREE),yes) +# mkdir -p debian/gdb$(TS)/usr/share/man/man5 +# install -m 644 $(builddir_default)/gdb/doc/gdbinit.5 \ +# debian/gdb$(TS)/usr/share/man/man5/. +# install -m 644 $(builddir_default)/gdb/doc/gdb.1 \ +# debian/gdb$(TS)/usr/share/man/man1/. +# install -m 644 $(builddir_default)/gdb/doc/gdb-add-index.1 \ +# debian/gdb$(TS)/usr/share/man/man1/. +#endif ifneq ($(DEB_CROSS),yes) # Only ship a global gdbinit for the native GDB. diff -pruN 16.3-5/gdb/doc/GDBvn.texi 16.3-5ubuntu1/gdb/doc/GDBvn.texi --- 16.3-5/gdb/doc/GDBvn.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/GDBvn.texi 2025-04-20 17:25:32.000000000 +0000 @@ -1 +1,3 @@ - +@set GDBVN 16.3 +@set VERSION_PACKAGE (GDB) +@set BUGURL @uref{https://www.gnu.org/software/gdb/bugs/} diff -pruN 16.3-5/gdb/doc/agentexpr.texi 16.3-5ubuntu1/gdb/doc/agentexpr.texi --- 16.3-5/gdb/doc/agentexpr.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/agentexpr.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,768 @@ +@c \input texinfo +@c %**start of header +@c @setfilename agentexpr.info +@c @settitle GDB Agent Expressions +@c @setchapternewpage off +@c %**end of header +@c This file is part of the GDB manual. +@c +@c Copyright (C) 2003--2024 Free Software Foundation, Inc. +@c +@c See the file gdb.texinfo for copying conditions. + +@node Agent Expressions +@appendix The GDB Agent Expression Mechanism + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + +Using GDB's @code{trace} and @code{collect} commands, the user can +specify locations in the program, and arbitrary expressions to evaluate +when those locations are reached. Later, using the @code{tfind} +command, she can examine the values those expressions had when the +program hit the trace points. The expressions may also denote objects +in memory --- structures or arrays, for example --- whose values GDB +should record; while visiting a particular tracepoint, the user may +inspect those objects as if they were in memory at that moment. +However, because GDB records these values without interacting with the +user, it can do so quickly and unobtrusively, hopefully not disturbing +the program's behavior. + +When GDB is debugging a remote target, the GDB @dfn{agent} code running +on the target computes the values of the expressions itself. To avoid +having a full symbolic expression evaluator on the agent, GDB translates +expressions in the source language into a simpler bytecode language, and +then sends the bytecode to the agent; the agent then executes the +bytecode, and records the values for GDB to retrieve later. + +The bytecode language is simple; there are forty-odd opcodes, the bulk +of which are the usual vocabulary of C operands (addition, subtraction, +shifts, and so on) and various sizes of literals and memory reference +operations. The bytecode interpreter operates strictly on machine-level +values --- various sizes of integers and floating point numbers --- and +requires no information about types or symbols; thus, the interpreter's +internal data structures are simple, and each bytecode requires only a +few native machine instructions to implement it. The interpreter is +small, and strict limits on the memory and time required to evaluate an +expression are easy to determine, making it suitable for use by the +debugging agent in real-time applications. + +@menu +* General Bytecode Design:: Overview of the interpreter. +* Bytecode Descriptions:: What each one does. +* Using Agent Expressions:: How agent expressions fit into the big picture. +* Varying Target Capabilities:: How to discover what the target can do. +* Rationale:: Why we did it this way. +@end menu + + +@c @node Rationale +@c @section Rationale + + +@node General Bytecode Design +@section General Bytecode Design + +The agent represents bytecode expressions as an array of bytes. Each +instruction is one byte long (thus the term @dfn{bytecode}). Some +instructions are followed by operand bytes; for example, the @code{goto} +instruction is followed by a destination for the jump. + +The bytecode interpreter is a stack-based machine; most instructions pop +their operands off the stack, perform some operation, and push the +result back on the stack for the next instruction to consume. Each +element of the stack may contain either a integer or a floating point +value; these values are as many bits wide as the largest integer that +can be directly manipulated in the source language. Stack elements +carry no record of their type; bytecode could push a value as an +integer, then pop it as a floating point value. However, GDB will not +generate code which does this. In C, one might define the type of a +stack element as follows: +@example +union agent_val @{ + LONGEST l; + DOUBLEST d; +@}; +@end example +@noindent +where @code{LONGEST} and @code{DOUBLEST} are @code{typedef} names for +the largest integer and floating point types on the machine. + +By the time the bytecode interpreter reaches the end of the expression, +the value of the expression should be the only value left on the stack. +For tracing applications, @code{trace} bytecodes in the expression will +have recorded the necessary data, and the value on the stack may be +discarded. For other applications, like conditional breakpoints, the +value may be useful. + +Separate from the stack, the interpreter has two registers: +@table @code +@item pc +The address of the next bytecode to execute. + +@item start +The address of the start of the bytecode expression, necessary for +interpreting the @code{goto} and @code{if_goto} instructions. + +@end table +@noindent +Neither of these registers is directly visible to the bytecode language +itself, but they are useful for defining the meanings of the bytecode +operations. + +There are no instructions to perform side effects on the running +program, or call the program's functions; we assume that these +expressions are only used for unobtrusive debugging, not for patching +the running code. + +Most bytecode instructions do not distinguish between the various sizes +of values, and operate on full-width values; the upper bits of the +values are simply ignored, since they do not usually make a difference +to the value computed. The exceptions to this rule are: +@table @asis + +@item memory reference instructions (@code{ref}@var{n}) +There are distinct instructions to fetch different word sizes from +memory. Once on the stack, however, the values are treated as full-size +integers. They may need to be sign-extended; the @code{ext} instruction +exists for this purpose. + +@item the sign-extension instruction (@code{ext} @var{n}) +These clearly need to know which portion of their operand is to be +extended to occupy the full length of the word. + +@end table + +If the interpreter is unable to evaluate an expression completely for +some reason (a memory location is inaccessible, or a divisor is zero, +for example), we say that interpretation ``terminates with an error''. +This means that the problem is reported back to the interpreter's caller +in some helpful way. In general, code using agent expressions should +assume that they may attempt to divide by zero, fetch arbitrary memory +locations, and misbehave in other ways. + +Even complicated C expressions compile to a few bytecode instructions; +for example, the expression @code{x + y * z} would typically produce +code like the following, assuming that @code{x} and @code{y} live in +registers, and @code{z} is a global variable holding a 32-bit +@code{int}: +@example +reg 1 +reg 2 +const32 @i{address of z} +ref32 +ext 32 +mul +add +end +@end example + +In detail, these mean: +@table @code + +@item reg 1 +Push the value of register 1 (presumably holding @code{x}) onto the +stack. + +@item reg 2 +Push the value of register 2 (holding @code{y}). + +@item const32 @i{address of z} +Push the address of @code{z} onto the stack. + +@item ref32 +Fetch a 32-bit word from the address at the top of the stack; replace +the address on the stack with the value. Thus, we replace the address +of @code{z} with @code{z}'s value. + +@item ext 32 +Sign-extend the value on the top of the stack from 32 bits to full +length. This is necessary because @code{z} is a signed integer. + +@item mul +Pop the top two numbers on the stack, multiply them, and push their +product. Now the top of the stack contains the value of the expression +@code{y * z}. + +@item add +Pop the top two numbers, add them, and push the sum. Now the top of the +stack contains the value of @code{x + y * z}. + +@item end +Stop executing; the value left on the stack top is the value to be +recorded. + +@end table + + +@node Bytecode Descriptions +@section Bytecode Descriptions + +Each bytecode description has the following form: + +@table @asis + +@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} + +Pop the top two stack items, @var{a} and @var{b}, as integers; push +their sum, as an integer. + +@end table + +In this example, @code{add} is the name of the bytecode, and +@code{(0x02)} is the one-byte value used to encode the bytecode, in +hexadecimal. The phrase ``@var{a} @var{b} @result{} @var{a+b}'' shows +the stack before and after the bytecode executes. Beforehand, the stack +must contain at least two values, @var{a} and @var{b}; since the top of +the stack is to the right, @var{b} is on the top of the stack, and +@var{a} is underneath it. After execution, the bytecode will have +popped @var{a} and @var{b} from the stack, and replaced them with a +single value, @var{a+b}. There may be other values on the stack below +those shown, but the bytecode affects only those shown. + +Here is another example: + +@table @asis + +@item @code{const8} (0x22) @var{n}: @result{} @var{n} +Push the 8-bit integer constant @var{n} on the stack, without sign +extension. + +@end table + +In this example, the bytecode @code{const8} takes an operand @var{n} +directly from the bytecode stream; the operand follows the @code{const8} +bytecode itself. We write any such operands immediately after the name +of the bytecode, before the colon, and describe the exact encoding of +the operand in the bytecode stream in the body of the bytecode +description. + +For the @code{const8} bytecode, there are no stack items given before +the @result{}; this simply means that the bytecode consumes no values +from the stack. If a bytecode consumes no values, or produces no +values, the list on either side of the @result{} may be empty. + +If a value is written as @var{a}, @var{b}, or @var{n}, then the bytecode +treats it as an integer. If a value is written is @var{addr}, then the +bytecode treats it as an address. + +We do not fully describe the floating point operations here; although +this design can be extended in a clean way to handle floating point +values, they are not of immediate interest to the customer, so we avoid +describing them, to save time. + + +@table @asis + +@item @code{float} (0x01): @result{} + +Prefix for floating-point bytecodes. Not implemented yet. + +@item @code{add} (0x02): @var{a} @var{b} @result{} @var{a+b} +Pop two integers from the stack, and push their sum, as an integer. + +@item @code{sub} (0x03): @var{a} @var{b} @result{} @var{a-b} +Pop two integers from the stack, subtract the top value from the +next-to-top value, and push the difference. + +@item @code{mul} (0x04): @var{a} @var{b} @result{} @var{a*b} +Pop two integers from the stack, multiply them, and push the product on +the stack. Note that, when one multiplies two @var{n}-bit numbers +yielding another @var{n}-bit number, it is irrelevant whether the +numbers are signed or not; the results are the same. + +@item @code{div_signed} (0x05): @var{a} @var{b} @result{} @var{a/b} +Pop two signed integers from the stack; divide the next-to-top value by +the top value, and push the quotient. If the divisor is zero, terminate +with an error. + +@item @code{div_unsigned} (0x06): @var{a} @var{b} @result{} @var{a/b} +Pop two unsigned integers from the stack; divide the next-to-top value +by the top value, and push the quotient. If the divisor is zero, +terminate with an error. + +@item @code{rem_signed} (0x07): @var{a} @var{b} @result{} @var{a modulo b} +Pop two signed integers from the stack; divide the next-to-top value by +the top value, and push the remainder. If the divisor is zero, +terminate with an error. + +@item @code{rem_unsigned} (0x08): @var{a} @var{b} @result{} @var{a modulo b} +Pop two unsigned integers from the stack; divide the next-to-top value +by the top value, and push the remainder. If the divisor is zero, +terminate with an error. + +@item @code{lsh} (0x09): @var{a} @var{b} @result{} @var{a<>b} +Pop two integers from the stack; let @var{a} be the next-to-top value, +and @var{b} be the top value. Shift @var{a} right by @var{b} bits, +inserting copies of the top bit at the high end, and push the result. + +@item @code{rsh_unsigned} (0x0b): @var{a} @var{b} @result{} @var{a>>b} +Pop two integers from the stack; let @var{a} be the next-to-top value, +and @var{b} be the top value. Shift @var{a} right by @var{b} bits, +inserting zero bits at the high end, and push the result. + +@item @code{log_not} (0x0e): @var{a} @result{} @var{!a} +Pop an integer from the stack; if it is zero, push the value one; +otherwise, push the value zero. + +@item @code{bit_and} (0x0f): @var{a} @var{b} @result{} @var{a&b} +Pop two integers from the stack, and push their bitwise @code{and}. + +@item @code{bit_or} (0x10): @var{a} @var{b} @result{} @var{a|b} +Pop two integers from the stack, and push their bitwise @code{or}. + +@item @code{bit_xor} (0x11): @var{a} @var{b} @result{} @var{a^b} +Pop two integers from the stack, and push their bitwise +exclusive-@code{or}. + +@item @code{bit_not} (0x12): @var{a} @result{} @var{~a} +Pop an integer from the stack, and push its bitwise complement. + +@item @code{equal} (0x13): @var{a} @var{b} @result{} @var{a=b} +Pop two integers from the stack; if they are equal, push the value one; +otherwise, push the value zero. + +@item @code{less_signed} (0x14): @var{a} @var{b} @result{} @var{a @var{a} @var{a} +Push another copy of the stack's top element. + +@item @code{swap} (0x2b): @var{a} @var{b} => @var{b} @var{a} +Exchange the top two items on the stack. + +@item @code{pop} (0x29): @var{a} => +Discard the top value on the stack. + +@item @code{pick} (0x32) @var{n}: @var{a} @dots{} @var{b} => @var{a} @dots{} @var{b} @var{a} +Duplicate an item from the stack and push it on the top of the stack. +@var{n}, a single byte, indicates the stack item to copy. If @var{n} +is zero, this is the same as @code{dup}; if @var{n} is one, it copies +the item under the top item, etc. If @var{n} exceeds the number of +items on the stack, terminate with an error. + +@item @code{rot} (0x33): @var{a} @var{b} @var{c} => @var{c} @var{a} @var{b} +Rotate the top three items on the stack. The top item (c) becomes the third +item, the next-to-top item (b) becomes the top item and the third item (a) from +the top becomes the next-to-top item. + +@item @code{if_goto} (0x20) @var{offset}: @var{a} @result{} +Pop an integer off the stack; if it is non-zero, branch to the given +offset in the bytecode string. Otherwise, continue to the next +instruction in the bytecode stream. In other words, if @var{a} is +non-zero, set the @code{pc} register to @code{start} + @var{offset}. +Thus, an offset of zero denotes the beginning of the expression. + +The @var{offset} is stored as a sixteen-bit unsigned value, stored +immediately following the @code{if_goto} bytecode. It is always stored +most significant byte first, regardless of the target's normal +endianness. The offset is not guaranteed to fall at any particular +alignment within the bytecode stream; thus, on machines where fetching a +16-bit on an unaligned address raises an exception, you should fetch the +offset one byte at a time. + +@item @code{goto} (0x21) @var{offset}: @result{} +Branch unconditionally to @var{offset}; in other words, set the +@code{pc} register to @code{start} + @var{offset}. + +The offset is stored in the same way as for the @code{if_goto} bytecode. + +@item @code{const8} (0x22) @var{n}: @result{} @var{n} +@itemx @code{const16} (0x23) @var{n}: @result{} @var{n} +@itemx @code{const32} (0x24) @var{n}: @result{} @var{n} +@itemx @code{const64} (0x25) @var{n}: @result{} @var{n} +Push the integer constant @var{n} on the stack, without sign extension. +To produce a small negative value, push a small twos-complement value, +and then sign-extend it using the @code{ext} bytecode. + +The constant @var{n} is stored in the appropriate number of bytes +following the @code{const}@var{b} bytecode. The constant @var{n} is +always stored most significant byte first, regardless of the target's +normal endianness. The constant is not guaranteed to fall at any +particular alignment within the bytecode stream; thus, on machines where +fetching a 16-bit on an unaligned address raises an exception, you +should fetch @var{n} one byte at a time. + +@item @code{reg} (0x26) @var{n}: @result{} @var{a} +Push the value of register number @var{n}, without sign extension. The +registers are numbered following GDB's conventions. + +The register number @var{n} is encoded as a 16-bit unsigned integer +immediately following the @code{reg} bytecode. It is always stored most +significant byte first, regardless of the target's normal endianness. +The register number is not guaranteed to fall at any particular +alignment within the bytecode stream; thus, on machines where fetching a +16-bit on an unaligned address raises an exception, you should fetch the +register number one byte at a time. + +@item @code{getv} (0x2c) @var{n}: @result{} @var{v} +Push the value of trace state variable number @var{n}, without sign +extension. + +The variable number @var{n} is encoded as a 16-bit unsigned integer +immediately following the @code{getv} bytecode. It is always stored most +significant byte first, regardless of the target's normal endianness. +The variable number is not guaranteed to fall at any particular +alignment within the bytecode stream; thus, on machines where fetching a +16-bit on an unaligned address raises an exception, you should fetch the +register number one byte at a time. + +@item @code{setv} (0x2d) @var{n}: @var{v} @result{} @var{v} +Set trace state variable number @var{n} to the value found on the top +of the stack. The stack is unchanged, so that the value is readily +available if the assignment is part of a larger expression. The +handling of @var{n} is as described for @code{getv}. + +@item @code{trace} (0x0c): @var{addr} @var{size} @result{} +Record the contents of the @var{size} bytes at @var{addr} in a trace +buffer, for later retrieval by GDB. + +@item @code{trace_quick} (0x0d) @var{size}: @var{addr} @result{} @var{addr} +Record the contents of the @var{size} bytes at @var{addr} in a trace +buffer, for later retrieval by GDB. @var{size} is a single byte +unsigned integer following the @code{trace} opcode. + +This bytecode is equivalent to the sequence @code{dup const8 @var{size} +trace}, but we provide it anyway to save space in bytecode strings. + +@item @code{trace16} (0x30) @var{size}: @var{addr} @result{} @var{addr} +Identical to trace_quick, except that @var{size} is a 16-bit big-endian +unsigned integer, not a single byte. This should probably have been +named @code{trace_quick16}, for consistency. + +@item @code{tracev} (0x2e) @var{n}: @result{} @var{a} +Record the value of trace state variable number @var{n} in the trace +buffer. The handling of @var{n} is as described for @code{getv}. + +@item @code{tracenz} (0x2f) @var{addr} @var{size} @result{} +Record the bytes at @var{addr} in a trace buffer, for later retrieval +by GDB. Stop at either the first zero byte, or when @var{size} bytes +have been recorded, whichever occurs first. + +@item @code{printf} (0x34) @var{numargs} @var{string} @result{} +Do a formatted print, in the style of the C function @code{printf}). +The value of @var{numargs} is the number of arguments to expect on the +stack, while @var{string} is the format string, prefixed with a +two-byte length. The last byte of the string must be zero, and is +included in the length. The format string includes escaped sequences +just as it appears in C source, so for instance the format string +@code{"\t%d\n"} is six characters long, and the output will consist of +a tab character, a decimal number, and a newline. At the top of the +stack, above the values to be printed, this bytecode will pop a +``function'' and ``channel''. If the function is nonzero, then the +target may treat it as a function and call it, passing the channel as +a first argument, as with the C function @code{fprintf}. If the +function is zero, then the target may simply call a standard formatted +print function of its choice. In all, this bytecode pops 2 + +@var{numargs} stack elements, and pushes nothing. + +@item @code{end} (0x27): @result{} +Stop executing bytecode; the result should be the top element of the +stack. If the purpose of the expression was to compute an lvalue or a +range of memory, then the next-to-top of the stack is the lvalue's +address, and the top of the stack is the lvalue's size, in bytes. + +@end table + + +@node Using Agent Expressions +@section Using Agent Expressions + +Agent expressions can be used in several different ways by @value{GDBN}, +and the debugger can generate different bytecode sequences as appropriate. + +One possibility is to do expression evaluation on the target rather +than the host, such as for the conditional of a conditional +tracepoint. In such a case, @value{GDBN} compiles the source +expression into a bytecode sequence that simply gets values from +registers or memory, does arithmetic, and returns a result. + +Another way to use agent expressions is for tracepoint data +collection. @value{GDBN} generates a different bytecode sequence for +collection; in addition to bytecodes that do the calculation, +@value{GDBN} adds @code{trace} bytecodes to save the pieces of +memory that were used. + +@itemize @bullet + +@item +The user selects trace points in the program's code at which GDB should +collect data. + +@item +The user specifies expressions to evaluate at each trace point. These +expressions may denote objects in memory, in which case those objects' +contents are recorded as the program runs, or computed values, in which +case the values themselves are recorded. + +@item +GDB transmits the tracepoints and their associated expressions to the +GDB agent, running on the debugging target. + +@item +The agent arranges to be notified when a trace point is hit. + +@item +When execution on the target reaches a trace point, the agent evaluates +the expressions associated with that trace point, and records the +resulting values and memory ranges. + +@item +Later, when the user selects a given trace event and inspects the +objects and expression values recorded, GDB talks to the agent to +retrieve recorded data as necessary to meet the user's requests. If the +user asks to see an object whose contents have not been recorded, GDB +reports an error. + +@end itemize + + +@node Varying Target Capabilities +@section Varying Target Capabilities + +Some targets don't support floating-point, and some would rather not +have to deal with @code{long long} operations. Also, different targets +will have different stack sizes, and different bytecode buffer lengths. + +Thus, GDB needs a way to ask the target about itself. We haven't worked +out the details yet, but in general, GDB should be able to send the +target a packet asking it to describe itself. The reply should be a +packet whose length is explicit, so we can add new information to the +packet in future revisions of the agent, without confusing old versions +of GDB, and it should contain a version number. It should contain at +least the following information: + +@itemize @bullet + +@item +whether floating point is supported + +@item +whether @code{long long} is supported + +@item +maximum acceptable size of bytecode stack + +@item +maximum acceptable length of bytecode expressions + +@item +which registers are actually available for collection + +@item +whether the target supports disabled tracepoints + +@end itemize + +@node Rationale +@section Rationale + +Some of the design decisions apparent above are arguable. + +@table @b + +@item What about stack overflow/underflow? +GDB should be able to query the target to discover its stack size. +Given that information, GDB can determine at translation time whether a +given expression will overflow the stack. But this spec isn't about +what kinds of error-checking GDB ought to do. + +@item Why are you doing everything in LONGEST? + +Speed isn't important, but agent code size is; using LONGEST brings in a +bunch of support code to do things like division, etc. So this is a +serious concern. + +First, note that you don't need different bytecodes for different +operand sizes. You can generate code without @emph{knowing} how big the +stack elements actually are on the target. If the target only supports +32-bit ints, and you don't send any 64-bit bytecodes, everything just +works. The observation here is that the MIPS and the Alpha have only +fixed-size registers, and you can still get C's semantics even though +most instructions only operate on full-sized words. You just need to +make sure everything is properly sign-extended at the right times. So +there is no need for 32- and 64-bit variants of the bytecodes. Just +implement everything using the largest size you support. + +GDB should certainly check to see what sizes the target supports, so the +user can get an error earlier, rather than later. But this information +is not necessary for correctness. + + +@item Why don't you have @code{>} or @code{<=} operators? +I want to keep the interpreter small, and we don't need them. We can +combine the @code{less_} opcodes with @code{log_not}, and swap the order +of the operands, yielding all four asymmetrical comparison operators. +For example, @code{(x <= y)} is @code{! (x > y)}, which is @code{! (y < +x)}. + +@item Why do you have @code{log_not}? +@itemx Why do you have @code{ext}? +@itemx Why do you have @code{zero_ext}? +These are all easily synthesized from other instructions, but I expect +them to be used frequently, and they're simple, so I include them to +keep bytecode strings short. + +@code{log_not} is equivalent to @code{const8 0 equal}; it's used in half +the relational operators. + +@code{ext @var{n}} is equivalent to @code{const8 @var{s-n} lsh const8 +@var{s-n} rsh_signed}, where @var{s} is the size of the stack elements; +it follows @code{ref@var{m}} and @var{reg} bytecodes when the value +should be signed. See the next bulleted item. + +@code{zero_ext @var{n}} is equivalent to @code{const@var{m} @var{mask} +log_and}; it's used whenever we push the value of a register, because we +can't assume the upper bits of the register aren't garbage. + +@item Why not have sign-extending variants of the @code{ref} operators? +Because that would double the number of @code{ref} operators, and we +need the @code{ext} bytecode anyway for accessing bitfields. + +@item Why not have constant-address variants of the @code{ref} operators? +Because that would double the number of @code{ref} operators again, and +@code{const32 @var{address} ref32} is only one byte longer. + +@item Why do the @code{ref@var{n}} operators have to support unaligned fetches? +GDB will generate bytecode that fetches multi-byte values at unaligned +addresses whenever the executable's debugging information tells it to. +Furthermore, GDB does not know the value the pointer will have when GDB +generates the bytecode, so it cannot determine whether a particular +fetch will be aligned or not. + +In particular, structure bitfields may be several bytes long, but follow +no alignment rules; members of packed structures are not necessarily +aligned either. + +In general, there are many cases where unaligned references occur in +correct C code, either at the programmer's explicit request, or at the +compiler's discretion. Thus, it is simpler to make the GDB agent +bytecodes work correctly in all circumstances than to make GDB guess in +each case whether the compiler did the usual thing. + +@item Why are there no side-effecting operators? +Because our current client doesn't want them? That's a cheap answer. I +think the real answer is that I'm afraid of implementing function +calls. We should re-visit this issue after the present contract is +delivered. + +@item Why aren't the @code{goto} ops PC-relative? +The interpreter has the base address around anyway for PC bounds +checking, and it seemed simpler. + +@item Why is there only one offset size for the @code{goto} ops? +Offsets are currently sixteen bits. I'm not happy with this situation +either: + +Suppose we have multiple branch ops with different offset sizes. As I +generate code left-to-right, all my jumps are forward jumps (there are +no loops in expressions), so I never know the target when I emit the +jump opcode. Thus, I have to either always assume the largest offset +size, or do jump relaxation on the code after I generate it, which seems +like a big waste of time. + +I can imagine a reasonable expression being longer than 256 bytes. I +can't imagine one being longer than 64k. Thus, we need 16-bit offsets. +This kind of reasoning is so bogus, but relaxation is pathetic. + +The other approach would be to generate code right-to-left. Then I'd +always know my offset size. That might be fun. + +@item Where is the function call bytecode? + +When we add side-effects, we should add this. + +@item Why does the @code{reg} bytecode take a 16-bit register number? + +Intel's IA-64 architecture has 128 general-purpose registers, +and 128 floating-point registers, and I'm sure it has some random +control registers. + +@item Why do we need @code{trace} and @code{trace_quick}? +Because GDB needs to record all the memory contents and registers an +expression touches. If the user wants to evaluate an expression +@code{x->y->z}, the agent must record the values of @code{x} and +@code{x->y} as well as the value of @code{x->y->z}. + +@item Don't the @code{trace} bytecodes make the interpreter less general? +They do mean that the interpreter contains special-purpose code, but +that doesn't mean the interpreter can only be used for that purpose. If +an expression doesn't use the @code{trace} bytecodes, they don't get in +its way. + +@item Why doesn't @code{trace_quick} consume its arguments the way everything else does? +In general, you do want your operators to consume their arguments; it's +consistent, and generally reduces the amount of stack rearrangement +necessary. However, @code{trace_quick} is a kludge to save space; it +only exists so we needn't write @code{dup const8 @var{SIZE} trace} +before every memory reference. Therefore, it's okay for it not to +consume its arguments; it's meant for a specific context in which we +know exactly what it should do with the stack. If we're going to have a +kludge, it should be an effective kludge. + +@item Why does @code{trace16} exist? +That opcode was added by the customer that contracted Cygnus for the +data tracing work. I personally think it is unnecessary; objects that +large will be quite rare, so it is okay to use @code{dup const16 +@var{size} trace} in those cases. + +Whatever we decide to do with @code{trace16}, we should at least leave +opcode 0x30 reserved, to remain compatible with the customer who added +it. + +@end table diff -pruN 16.3-5/gdb/doc/all-cfg.texi 16.3-5ubuntu1/gdb/doc/all-cfg.texi --- 16.3-5/gdb/doc/all-cfg.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/all-cfg.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,45 @@ - +@c GDB MANUAL configuration file. +@c +@c Copyright (C) 1993--2024 Free Software Foundation, Inc. +@c +@c NOTE: While the GDB manual is configurable (by changing these +@c switches), its configuration is ***NOT*** automatically tied in to +@c source configuration---because the authors expect that, save in +@c unusual cases, the most inclusive form of the manual is appropriate +@c no matter how the program itself is configured. +@c +@c The only automatically-varying variable is the GDB version number, +@c which the Makefile rewrites based on the VERSION variable from +@c `../Makefile.in'. +@c +@c GDB version number is recorded in the variable GDBVN +@include GDBvn.texi +@c +@c ---------------------------------------------------------------------- +@c PLATFORM FLAGS: +@set GENERIC +@c +@c HP PA-RISC target ONLY: +@clear HPPA +@c +@c Refrain from discussing how to configure sw and format doc? +@clear PRECONFIGURED +@c +@c ---------------------------------------------------------------------- +@c STRINGS: +@c +@c Name of GDB program. Used also for (gdb) prompt string. +@set GDBP gdb +@c +@c Name of GDB product. Used in running text. +@set GDBN @sc{gdb} +@c +@c Name of host. Should not be used in generic configs, but generic +@c value may catch some flubs. +@set HOST machine specific +@c +@c Name of GCC product +@set NGCC @sc{gcc} +@c +@c Name of GCC program +@set GCC gcc diff -pruN 16.3-5/gdb/doc/annotate.info 16.3-5ubuntu1/gdb/doc/annotate.info --- 16.3-5/gdb/doc/annotate.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/annotate.info 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,1198 @@ +This is annotate.info, produced by makeinfo version 6.8 from +annotate.texinfo. + +Copyright (C) 1994-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Annotate: (annotate). The obsolete annotation interface. +END-INFO-DIR-ENTRY + + This file documents GDB's obsolete annotations. + + Copyright (C) 1994-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + +File: annotate.info, Node: Top, Next: Annotations Overview, Up: (dir) + +GDB Annotations +*************** + +This document describes the obsolete level two annotation interface +implemented in older GDB versions. + +* Menu: + +* Annotations Overview:: What annotations are; the general syntax. +* Limitations:: Limitations of the annotation interface. +* Migrating to GDB/MI:: Migrating to GDB/MI +* Server Prefix:: Issuing a command without affecting user state. +* Value Annotations:: Values are marked as such. +* Frame Annotations:: Stack frames are annotated. +* Displays:: GDB can be told to display something periodically. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Breakpoint Info:: Information on breakpoints. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. +* Multi-threaded Apps:: An annotation that reports multi-threadedness. + +* GNU Free Documentation License:: + + +File: annotate.info, Node: Annotations Overview, Next: Limitations, Prev: Top, Up: Top + +1 What is an Annotation? +************************ + +To produce obsolete level two annotations, start GDB with the +'--annotate=2' option. + + Annotations start with a newline character, two 'control-z' +characters, and the name of the annotation. If there is no additional +information associated with this annotation, the name of the annotation +is followed immediately by a newline. If there is additional +information, the name of the annotation is followed by a space, the +additional information, and a newline. The additional information +cannot contain newline characters. + + Any output not beginning with a newline and two 'control-z' +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two 'control-z' characters, but +if there was such a need, the annotations could be extended with an +'escape' annotation which means those three characters as output. + + A simple example of starting up GDB with annotations is: + + $ gdb --annotate=2 + GNU GDB 5.0 + Copyright 2000 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or distribute copies of it + under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" + for details. + This GDB was configured as "sparc-sun-sunos4.1.3" + + ^Z^Zpre-prompt + (gdb) + ^Z^Zprompt + quit + + ^Z^Zpost-prompt + $ + + Here 'quit' is input to GDB; the rest is output from GDB. The three +lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are +annotations; the rest is output from GDB. + + +File: annotate.info, Node: Limitations, Next: Migrating to GDB/MI, Prev: Annotations Overview, Up: Top + +2 Limitations of the Annotation Interface +***************************************** + +The level two annotations mechanism is known to have a number of +technical and architectural limitations. As a consequence, in 2001, +with the release of GDB 5.1 and the addition of GDB/MI, the annotation +interface was marked as deprecated. + + This chapter discusses the known problems. + +2.1 Dependant on CLI output +=========================== + +The annotation interface works by interspersing markups with GDB normal +command-line interpreter output. Unfortunately, this makes the +annotation client dependant on not just the annotations, but also the +CLI output. This is because the client is forced to assume that +specific GDB commands provide specific information. Any change to GDB's +CLI output modifies or removes that information and, consequently, +likely breaks the client. + + Since the GDB/MI output is independent of the CLI, it does not have +this problem. + +2.2 Scalability +=============== + +The annotation interface relies on value annotations (*note Value +Annotations::) and the display mechanism as a way of obtaining +up-to-date value information. These mechanisms are not scalable. + + In a graphical environment, where many values can be displayed +simultaneously, a serious performance problem occurs when the client +tries to first extract from GDB, and then re-display, all those values. +The client should instead only request and update the values that +changed. + + The GDB/MI Variable Objects provide just that mechanism. + +2.3 Correctness +=============== + +The annotation interface assumes that a variable's value can only be +changed when the target is running. This assumption is not correct. A +single assignment to a single variable can result in the entire target, +and all displayed values, needing an update. + + The GDB/MI Variable Objects include a mechanism for efficiently +reporting such changes. + +2.4 Reliability +=============== + +The GDB/MI interface includes a dedicated test directory ('gdb/gdb.mi'), +and any addition or fix to GDB/MI must include testsuite changes. + +2.5 Maintainability +=================== + +The annotation mechanism was implemented by interspersing CLI print +statements with various annotations. As a consequence, any CLI output +change can alter the annotation output. + + Since the GDB/MI output is independent of the CLI, and the GDB/MI is +increasingly implemented independent of the CLI code, its long term +maintenance is much easier. + + +File: annotate.info, Node: Migrating to GDB/MI, Next: Server Prefix, Prev: Limitations, Up: Top + +3 Migrating to GDB/MI +********************* + +By using the 'interp mi' command, it is possible for annotation clients +to invoke GDB/MI commands, and hence access the GDB/MI. By doing this, +existing annotation clients have a migration path from this obsolete +interface to GDB/MI. + + +File: annotate.info, Node: Server Prefix, Next: Value Annotations, Prev: Migrating to GDB/MI, Up: Top + +4 The Server Prefix +******************* + +To issue a command to GDB without affecting certain aspects of the state +which is seen by users, prefix it with 'server '. This means that this +command will not affect the command history, nor will it affect GDB's +notion of which command to repeat if is pressed on a line by +itself. + + The server prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + +File: annotate.info, Node: Value Annotations, Next: Frame Annotations, Prev: Server Prefix, Up: Top + +5 Values +******** + +_Value Annotations have been removed. GDB/MI instead provides Variable +Objects._ + + When a value is printed in various contexts, GDB uses annotations to +delimit the value from the surrounding text. + + If a value is printed using 'print' and added to the value history, +the annotation looks like + + ^Z^Zvalue-history-begin HISTORY-NUMBER VALUE-FLAGS + HISTORY-STRING + ^Z^Zvalue-history-value + THE-VALUE + ^Z^Zvalue-history-end + +where HISTORY-NUMBER is the number it is getting in the value history, +HISTORY-STRING is a string, such as '$5 = ', which introduces the value +to the user, THE-VALUE is the output corresponding to the value itself, +and VALUE-FLAGS is '*' for a value which can be dereferenced and '-' for +a value which cannot. + + If the value is not added to the value history (it is an invalid +float or it is printed with the 'output' command), the annotation is +similar: + + ^Z^Zvalue-begin VALUE-FLAGS + THE-VALUE + ^Z^Zvalue-end + + When GDB prints an argument to a function (for example, in the output +from the 'backtrace' command), it annotates it as follows: + + ^Z^Zarg-begin + ARGUMENT-NAME + ^Z^Zarg-name-end + SEPARATOR-STRING + ^Z^Zarg-value VALUE-FLAGS + THE-VALUE + ^Z^Zarg-end + +where ARGUMENT-NAME is the name of the argument, SEPARATOR-STRING is +text which separates the name from the value for the user's benefit +(such as '='), and VALUE-FLAGS and THE-VALUE have the same meanings as +in a 'value-history-begin' annotation. + + When printing a structure, GDB annotates it as follows: + + ^Z^Zfield-begin VALUE-FLAGS + FIELD-NAME + ^Z^Zfield-name-end + SEPARATOR-STRING + ^Z^Zfield-value + THE-VALUE + ^Z^Zfield-end + +where FIELD-NAME is the name of the field, SEPARATOR-STRING is text +which separates the name from the value for the user's benefit (such as +'='), and VALUE-FLAGS and THE-VALUE have the same meanings as in a +'value-history-begin' annotation. + + When printing an array, GDB annotates it as follows: + + ^Z^Zarray-section-begin ARRAY-INDEX VALUE-FLAGS + +where ARRAY-INDEX is the index of the first element being annotated and +VALUE-FLAGS has the same meaning as in a 'value-history-begin' +annotation. This is followed by any number of elements, where is +element can be either a single element: + + ',' WHITESPACE ; omitted for the first element + THE-VALUE + ^Z^Zelt + + or a repeated element + + ',' WHITESPACE ; omitted for the first element + THE-VALUE + ^Z^Zelt-rep NUMBER-OF-REPETITIONS + REPETITION-STRING + ^Z^Zelt-rep-end + + In both cases, THE-VALUE is the output for the value of the element +and WHITESPACE can contain spaces, tabs, and newlines. In the repeated +case, NUMBER-OF-REPETITIONS is the number of consecutive array elements +which contain that value, and REPETITION-STRING is a string which is +designed to convey to the user that repetition is being depicted. + + Once all the array elements have been output, the array annotation is +ended with + + ^Z^Zarray-section-end + + +File: annotate.info, Node: Frame Annotations, Next: Displays, Prev: Value Annotations, Up: Top + +6 Frames +******** + +_Value Annotations have been removed. GDB/MI instead provides a number +of frame commands._ + + _Frame annotations are no longer available. The GDB/MI provides +'-stack-list-arguments', '-stack-list-locals', and '-stack-list-frames' +commands._ + + Whenever GDB prints a frame, it annotates it. For example, this +applies to frames printed when GDB stops, output from commands such as +'backtrace' or 'up', etc. + + The frame annotation begins with + + ^Z^Zframe-begin LEVEL ADDRESS + LEVEL-STRING + +where LEVEL is the number of the frame (0 is the innermost frame, and +other frames have positive numbers), ADDRESS is the address of the code +executing in that frame, and LEVEL-STRING is a string designed to convey +the level to the user. ADDRESS is in the form '0x' followed by one or +more lowercase hex digits (note that this does not depend on the +language). The frame ends with + + ^Z^Zframe-end + + Between these annotations is the main body of the frame, which can +consist of + + * ^Z^Zfunction-call + FUNCTION-CALL-STRING + + where FUNCTION-CALL-STRING is text designed to convey to the user + that this frame is associated with a function call made by GDB to a + function in the program being debugged. + + * ^Z^Zsignal-handler-caller + SIGNAL-HANDLER-CALLER-STRING + + where SIGNAL-HANDLER-CALLER-STRING is text designed to convey to + the user that this frame is associated with whatever mechanism is + used by this operating system to call a signal handler (it is the + frame which calls the signal handler, not the frame for the signal + handler itself). + + * A normal frame. + + This can optionally (depending on whether this is thought of as + interesting information for the user to see) begin with + + ^Z^Zframe-address + ADDRESS + ^Z^Zframe-address-end + SEPARATOR-STRING + + where ADDRESS is the address executing in the frame (the same + address as in the 'frame-begin' annotation, but printed in a form + which is intended for user consumption--in particular, the syntax + varies depending on the language), and SEPARATOR-STRING is a string + intended to separate this address from what follows for the user's + benefit. + + Then comes + + ^Z^Zframe-function-name + FUNCTION-NAME + ^Z^Zframe-args + ARGUMENTS + + where FUNCTION-NAME is the name of the function executing in the + frame, or '??' if not known, and ARGUMENTS are the arguments to the + frame, with parentheses around them (each argument is annotated + individually as well, *note Value Annotations::). + + If source information is available, a reference to it is then + printed: + + ^Z^Zframe-source-begin + SOURCE-INTRO-STRING + ^Z^Zframe-source-file + FILENAME + ^Z^Zframe-source-file-end + : + ^Z^Zframe-source-line + LINE-NUMBER + ^Z^Zframe-source-end + + where SOURCE-INTRO-STRING separates for the user's benefit the + reference from the text which precedes it, FILENAME is the name of + the source file, and LINE-NUMBER is the line number within that + file (the first line is line 1). + + If GDB prints some information about where the frame is from (which + library, which load segment, etc.; currently only done on the + RS/6000), it is annotated with + + ^Z^Zframe-where + INFORMATION + + Then, if source is to actually be displayed for this frame (for + example, this is not true for output from the 'backtrace' command), + then a 'source' annotation (*note Source Annotations::) is + displayed. Unlike most annotations, this is output instead of the + normal text which would be output, not in addition. + + +File: annotate.info, Node: Displays, Next: Prompting, Prev: Frame Annotations, Up: Top + +7 Displays +********** + +_Display Annotations have been removed. GDB/MI instead provides +Variable Objects._ + + When GDB is told to display something using the 'display' command, +the results of the display are annotated: + + ^Z^Zdisplay-begin + NUMBER + ^Z^Zdisplay-number-end + NUMBER-SEPARATOR + ^Z^Zdisplay-format + FORMAT + ^Z^Zdisplay-expression + EXPRESSION + ^Z^Zdisplay-expression-end + EXPRESSION-SEPARATOR + ^Z^Zdisplay-value + VALUE + ^Z^Zdisplay-end + +where NUMBER is the number of the display, NUMBER-SEPARATOR is intended +to separate the number from what follows for the user, FORMAT includes +information such as the size, format, or other information about how the +value is being displayed, EXPRESSION is the expression being displayed, +EXPRESSION-SEPARATOR is intended to separate the expression from the +text that follows for the user, and VALUE is the actual value being +displayed. + + +File: annotate.info, Node: Prompting, Next: Errors, Prev: Displays, Up: Top + +8 Annotation for GDB Input +************************** + +When GDB prompts for input, it annotates this fact so it is possible to +know when to send output, when the output from a given command is over, +etc. + + Different kinds of input each have a different "input type". Each +input type has three annotations: a 'pre-' annotation, which denotes the +beginning of any prompt which is being output, a plain annotation, which +denotes the end of the prompt, and then a 'post-' annotation which +denotes the end of any echo which may (or may not) be associated with +the input. For example, the 'prompt' input type features the following +annotations: + + ^Z^Zpre-prompt + ^Z^Zprompt + ^Z^Zpost-prompt + + The input types are + +'prompt' + When GDB is prompting for a command (the main GDB prompt). + +'commands' + When GDB prompts for a set of commands, like in the 'commands' + command. The annotations are repeated for each command which is + input. + +'overload-choice' + When GDB wants the user to select between various overloaded + functions. + +'query' + When GDB wants the user to confirm a potentially dangerous + operation. + +'prompt-for-continue' + When GDB is asking the user to press return to continue. Note: + Don't expect this to work well; instead use 'set height 0' to + disable prompting. This is because the counting of lines is buggy + in the presence of annotations. + + +File: annotate.info, Node: Errors, Next: Breakpoint Info, Prev: Prompting, Up: Top + +9 Errors +******** + + ^Z^Zquit + + This annotation occurs right before GDB responds to an interrupt. + + ^Z^Zerror + + This annotation occurs right before GDB responds to an error. + + Quit and error annotations indicate that any annotations which GDB +was in the middle of may end abruptly. For example, if a +'value-history-begin' annotation is followed by a 'error', one cannot +expect to receive the matching 'value-history-end'. One cannot expect +not to receive it either, however; an error annotation does not +necessarily mean that GDB is immediately returning all the way to the +top level. + + A quit or error annotation may be preceded by + + ^Z^Zerror-begin + + Any output between that and the quit or error annotation is the error +message. + + Warning messages are not yet annotated. + + +File: annotate.info, Node: Breakpoint Info, Next: Invalidation, Prev: Errors, Up: Top + +10 Information on Breakpoints +***************************** + +_Breakpoint Annotations have been removed. GDB/MI instead provides +breakpoint commands._ + + The output from the 'info breakpoints' command is annotated as +follows: + + ^Z^Zbreakpoints-headers + HEADER-ENTRY + ^Z^Zbreakpoints-table + +where HEADER-ENTRY has the same syntax as an entry (see below) but +instead of containing data, it contains strings which are intended to +convey the meaning of each field to the user. This is followed by any +number of entries. If a field does not apply for this entry, it is +omitted. Fields may contain trailing whitespace. Each entry consists +of: + + ^Z^Zrecord + ^Z^Zfield 0 + NUMBER + ^Z^Zfield 1 + TYPE + ^Z^Zfield 2 + DISPOSITION + ^Z^Zfield 3 + ENABLE + ^Z^Zfield 4 + ADDRESS + ^Z^Zfield 5 + WHAT + ^Z^Zfield 6 + FRAME + ^Z^Zfield 7 + CONDITION + ^Z^Zfield 8 + IGNORE-COUNT + ^Z^Zfield 9 + COMMANDS + + Note that ADDRESS is intended for user consumption--the syntax varies +depending on the language. + + The output ends with + + ^Z^Zbreakpoints-table-end + + +File: annotate.info, Node: Invalidation, Next: Annotations for Running, Prev: Breakpoint Info, Up: Top + +11 Invalidation Notices +*********************** + +The following annotations say that certain pieces of state may have +changed. + +'^Z^Zframes-invalid' + + The frames (for example, output from the 'backtrace' command) may + have changed. + +'^Z^Zbreakpoints-invalid' + + The breakpoints may have changed. For example, the user just added + or deleted a breakpoint. + + +File: annotate.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Top + +12 Running the Program +********************** + +When the program starts executing due to a GDB command such as 'step' or +'continue', + + ^Z^Zstarting + + is output. When the program stops, + + ^Z^Zstopped + + is output. Before the 'stopped' annotation, a variety of annotations +describe how the program stopped. + +'^Z^Zexited EXIT-STATUS' + The program exited, and EXIT-STATUS is the exit status (zero for + successful exit, otherwise nonzero). + +'^Z^Zsignalled' + The program exited with a signal. After the '^Z^Zsignalled', the + annotation continues: + + INTRO-TEXT + ^Z^Zsignal-name + NAME + ^Z^Zsignal-name-end + MIDDLE-TEXT + ^Z^Zsignal-string + STRING + ^Z^Zsignal-string-end + END-TEXT + + where NAME is the name of the signal, such as 'SIGILL' or + 'SIGSEGV', and STRING is the explanation of the signal, such as + 'Illegal Instruction' or 'Segmentation fault'. INTRO-TEXT, + MIDDLE-TEXT, and END-TEXT are for the user's benefit and have no + particular format. + +'^Z^Zsignal' + The syntax of this annotation is just like 'signalled', but GDB is + just saying that the program received the signal, not that it was + terminated with it. + +'^Z^Zbreakpoint NUMBER' + The program hit breakpoint number NUMBER. + +'^Z^Zwatchpoint NUMBER' + The program hit watchpoint number NUMBER. + + +File: annotate.info, Node: Source Annotations, Next: Multi-threaded Apps, Prev: Annotations for Running, Up: Top + +13 Displaying Source +******************** + +The following annotation is used instead of displaying source code: + + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR + + where FILENAME is an absolute file name indicating which source file, +LINE is the line number within that file (where 1 is the first line in +the file), CHARACTER is the character position within the file (where 0 +is the first character in the file) (for most debug formats this will +necessarily point to the beginning of a line), MIDDLE is 'middle' if +ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning +of the line, and ADDR is the address in the target program associated +with the source which is being displayed. ADDR is in the form '0x' +followed by one or more lowercase hex digits (note that this does not +depend on the language). + + +File: annotate.info, Node: Multi-threaded Apps, Next: GNU Free Documentation License, Prev: Source Annotations, Up: Top + +14 Multi-threaded Applications +****************************** + +The following annotations report thread related changes of state. + +'^Z^Znew-thread' + + This annotation is issued once for each thread that is created + apart from the main thread, which is not reported. + +'^Z^Zthread-changed' + + The selected thread has changed. This may occur at the request of + the user with the 'thread' command, or as a result of execution, + e.g., another thread hits a breakpoint. + +'^Z^Zthread-exited,id="ID",group-id="GID"' + + This annotation is issued once for each thread that exits. The ID + field contains the global GDB identifier of the thread. The GID + field identifies the thread group this thread belongs to. + + +File: annotate.info, Node: GNU Free Documentation License, Prev: Multi-threaded Apps, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + + +Tag Table: +Node: Top1166 +Node: Annotations Overview2336 +Node: Limitations4135 +Node: Migrating to GDB/MI6720 +Node: Server Prefix7103 +Node: Value Annotations7749 +Node: Frame Annotations10919 +Node: Displays14818 +Node: Prompting15849 +Node: Errors17352 +Node: Breakpoint Info18242 +Node: Invalidation19467 +Node: Annotations for Running19948 +Node: Source Annotations21461 +Node: Multi-threaded Apps22407 +Node: GNU Free Documentation License23267 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/gdb/doc/annotate.texinfo 16.3-5ubuntu1/gdb/doc/annotate.texinfo --- 16.3-5/gdb/doc/annotate.texinfo 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/annotate.texinfo 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,859 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename annotate.info +@c This is a dir.info fragment to support semi-automated addition of +@c manuals to an info tree. +@dircategory Software development +@direntry +* Annotate: (annotate). The obsolete annotation interface. +@end direntry + +@c +@include gdb-cfg.texi +@c +@settitle @value{GDBN}'s Obsolete Annotations +@setchapternewpage off +@c %**end of header + +@set EDITION 1.0 +@set DATE July 2003 + +@c NOTE: cagney/2003-07-28: +@c Don't make this migration document an appendix of GDB's user guide. +@c By keeping this separate, the size of the user guide is contained. If +@c the user guide to get much bigger it would need to switch to a larger, +@c more expensive, form factor and would drive up the manuals publication +@c cost. Having a smaller cheaper manual helps the GNU Press with its sales. + +@copying +Copyright @copyright{} 1994--2024 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end copying + +@ifnottex +This file documents @value{GDBN}'s obsolete annotations. + +@insertcopying +@end ifnottex + +@titlepage +@title @value{GDBN}'s Obsolete Annotations +@subtitle Edition @value{EDITION} +@subtitle @value{DATE} +@author Free Software Foundation +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top +@top GDB Annotations + +This document describes the obsolete level two annotation interface +implemented in older @value{GDBN} versions. + +@ignore +This is Edition @value{EDITION}, @value{DATE}. +@end ignore +@end ifnottex + +@menu +* Annotations Overview:: What annotations are; the general syntax. +* Limitations:: Limitations of the annotation interface. +* Migrating to GDB/MI:: Migrating to GDB/MI +* Server Prefix:: Issuing a command without affecting user state. +* Value Annotations:: Values are marked as such. +* Frame Annotations:: Stack frames are annotated. +* Displays:: @value{GDBN} can be told to display something periodically. +* Prompting:: Annotations marking @value{GDBN}'s need for input. +* Errors:: Annotations for error messages. +* Breakpoint Info:: Information on breakpoints. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. +* Multi-threaded Apps:: An annotation that reports multi-threadedness. + +* GNU Free Documentation License:: +@end menu + +@contents + +@node Annotations Overview +@chapter What is an Annotation? +@cindex annotations + +To produce obsolete level two annotations, start @value{GDBN} with the +@code{--annotate=2} option. + +Annotations start with a newline character, two @samp{control-z} +characters, and the name of the annotation. If there is no additional +information associated with this annotation, the name of the annotation +is followed immediately by a newline. If there is additional +information, the name of the annotation is followed by a space, the +additional information, and a newline. The additional information +cannot contain newline characters. + +Any output not beginning with a newline and two @samp{control-z} +characters denotes literal output from @value{GDBN}. Currently there is +no need for @value{GDBN} to output a newline followed by two +@samp{control-z} characters, but if there was such a need, the +annotations could be extended with an @samp{escape} annotation which +means those three characters as output. + +A simple example of starting up @value{GDBN} with annotations is: + +@smallexample +$ gdb --annotate=2 +GNU GDB 5.0 +Copyright 2000 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, +and you are welcome to change it and/or distribute copies of it +under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" +for details. +This GDB was configured as "sparc-sun-sunos4.1.3" + +^Z^Zpre-prompt +(gdb) +^Z^Zprompt +quit + +^Z^Zpost-prompt +$ +@end smallexample + +Here @samp{quit} is input to @value{GDBN}; the rest is output from +@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} +denotes a @samp{control-z} character) are annotations; the rest is +output from @value{GDBN}. + +@node Limitations +@chapter Limitations of the Annotation Interface + +The level two annotations mechanism is known to have a number of +technical and architectural limitations. As a consequence, in 2001, +with the release of @value{GDBN} 5.1 and the addition of @sc{gdb/mi}, +the annotation interface was marked as deprecated. + +This chapter discusses the known problems. + +@section Dependant on @sc{cli} output + +The annotation interface works by interspersing markups with +@value{GDBN} normal command-line interpreter output. Unfortunately, this +makes the annotation client dependant on not just the annotations, but +also the @sc{cli} output. This is because the client is forced to +assume that specific @value{GDBN} commands provide specific information. +Any change to @value{GDBN}'s @sc{cli} output modifies or removes that +information and, consequently, likely breaks the client. + +Since the @sc{gdb/mi} output is independent of the @sc{cli}, it does not +have this problem. + +@section Scalability + +The annotation interface relies on value annotations (@pxref{Value +Annotations}) and the display mechanism as a way of obtaining up-to-date +value information. These mechanisms are not scalable. + +In a graphical environment, where many values can be displayed +simultaneously, a serious performance problem occurs when the client +tries to first extract from @value{GDBN}, and then re-display, all those +values. The client should instead only request and update the values +that changed. + +The @sc{gdb/mi} Variable Objects provide just that mechanism. + +@section Correctness + +The annotation interface assumes that a variable's value can only be +changed when the target is running. This assumption is not correct. A +single assignment to a single variable can result in the entire target, +and all displayed values, needing an update. + +The @sc{gdb/mi} Variable Objects include a mechanism for efficiently +reporting such changes. + +@section Reliability + +The @sc{gdb/mi} interface includes a dedicated test directory +(@file{gdb/gdb.mi}), and any addition or fix to @sc{gdb/mi} must include +testsuite changes. + +@section Maintainability + +The annotation mechanism was implemented by interspersing @sc{cli} print +statements with various annotations. As a consequence, any @sc{cli} +output change can alter the annotation output. + +Since the @sc{gdb/mi} output is independent of the @sc{cli}, and the +@sc{gdb/mi} is increasingly implemented independent of the @sc{cli} +code, its long term maintenance is much easier. + +@node Migrating to GDB/MI +@chapter Migrating to @sc{gdb/mi} + +By using the @samp{interp mi} command, it is possible for annotation +clients to invoke @sc{gdb/mi} commands, and hence access the +@sc{gdb/mi}. By doing this, existing annotation clients have a +migration path from this obsolete interface to @sc{gdb/mi}. + +@node Server Prefix +@chapter The Server Prefix +@cindex server prefix for annotations + +To issue a command to @value{GDBN} without affecting certain aspects of +the state which is seen by users, prefix it with @samp{server }. This +means that this command will not affect the command history, nor will it +affect @value{GDBN}'s notion of which command to repeat if @key{RET} is +pressed on a line by itself. + +The server prefix does not affect the recording of values into the value +history; to print a value without recording it into the value history, +use the @code{output} command instead of the @code{print} command. + +@node Value Annotations +@chapter Values + +@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides +Variable Objects.} + +@cindex annotations for values +When a value is printed in various contexts, @value{GDBN} uses +annotations to delimit the value from the surrounding text. + +@findex value-history-begin +@findex value-history-value +@findex value-history-end +If a value is printed using @code{print} and added to the value history, +the annotation looks like + +@smallexample +^Z^Zvalue-history-begin @var{history-number} @var{value-flags} +@var{history-string} +^Z^Zvalue-history-value +@var{the-value} +^Z^Zvalue-history-end +@end smallexample + +@noindent +where @var{history-number} is the number it is getting in the value +history, @var{history-string} is a string, such as @samp{$5 = }, which +introduces the value to the user, @var{the-value} is the output +corresponding to the value itself, and @var{value-flags} is @samp{*} for +a value which can be dereferenced and @samp{-} for a value which cannot. + +@findex value-begin +@findex value-end +If the value is not added to the value history (it is an invalid float +or it is printed with the @code{output} command), the annotation is similar: + +@smallexample +^Z^Zvalue-begin @var{value-flags} +@var{the-value} +^Z^Zvalue-end +@end smallexample + +@findex arg-begin +@findex arg-name-end +@findex arg-value +@findex arg-end +When @value{GDBN} prints an argument to a function (for example, in the output +from the @code{backtrace} command), it annotates it as follows: + +@smallexample +^Z^Zarg-begin +@var{argument-name} +^Z^Zarg-name-end +@var{separator-string} +^Z^Zarg-value @var{value-flags} +@var{the-value} +^Z^Zarg-end +@end smallexample + +@noindent +where @var{argument-name} is the name of the argument, +@var{separator-string} is text which separates the name from the value +for the user's benefit (such as @samp{=}), and @var{value-flags} and +@var{the-value} have the same meanings as in a +@code{value-history-begin} annotation. + +@findex field-begin +@findex field-name-end +@findex field-value +@findex field-end +When printing a structure, @value{GDBN} annotates it as follows: + +@smallexample +^Z^Zfield-begin @var{value-flags} +@var{field-name} +^Z^Zfield-name-end +@var{separator-string} +^Z^Zfield-value +@var{the-value} +^Z^Zfield-end +@end smallexample + +@noindent +where @var{field-name} is the name of the field, @var{separator-string} +is text which separates the name from the value for the user's benefit +(such as @samp{=}), and @var{value-flags} and @var{the-value} have the +same meanings as in a @code{value-history-begin} annotation. + +When printing an array, @value{GDBN} annotates it as follows: + +@smallexample +^Z^Zarray-section-begin @var{array-index} @var{value-flags} +@end smallexample + +@noindent +where @var{array-index} is the index of the first element being +annotated and @var{value-flags} has the same meaning as in a +@code{value-history-begin} annotation. This is followed by any number +of elements, where is element can be either a single element: + +@findex elt +@smallexample +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt +@end smallexample + +or a repeated element + +@findex elt-rep +@findex elt-rep-end +@smallexample +@samp{,} @var{whitespace} ; @r{omitted for the first element} +@var{the-value} +^Z^Zelt-rep @var{number-of-repetitions} +@var{repetition-string} +^Z^Zelt-rep-end +@end smallexample + +In both cases, @var{the-value} is the output for the value of the +element and @var{whitespace} can contain spaces, tabs, and newlines. In +the repeated case, @var{number-of-repetitions} is the number of +consecutive array elements which contain that value, and +@var{repetition-string} is a string which is designed to convey to the +user that repetition is being depicted. + +@findex array-section-end +Once all the array elements have been output, the array annotation is +ended with + +@smallexample +^Z^Zarray-section-end +@end smallexample + +@node Frame Annotations +@chapter Frames + +@emph{Value Annotations have been removed. @sc{gdb/mi} instead provides +a number of frame commands.} + +@emph{Frame annotations are no longer available. The @sc{gdb/mi} +provides @samp{-stack-list-arguments}, @samp{-stack-list-locals}, and +@samp{-stack-list-frames} commands.} + +@cindex annotations for frames +Whenever @value{GDBN} prints a frame, it annotates it. For example, this applies +to frames printed when @value{GDBN} stops, output from commands such as +@code{backtrace} or @code{up}, etc. + +@findex frame-begin +The frame annotation begins with + +@smallexample +^Z^Zframe-begin @var{level} @var{address} +@var{level-string} +@end smallexample + +@noindent +where @var{level} is the number of the frame (0 is the innermost frame, +and other frames have positive numbers), @var{address} is the address of +the code executing in that frame, and @var{level-string} is a string +designed to convey the level to the user. @var{address} is in the form +@samp{0x} followed by one or more lowercase hex digits (note that this +does not depend on the language). The frame ends with + +@findex frame-end +@smallexample +^Z^Zframe-end +@end smallexample + +Between these annotations is the main body of the frame, which can +consist of + +@itemize @bullet +@item +@findex function-call +@smallexample +^Z^Zfunction-call +@var{function-call-string} +@end smallexample + +where @var{function-call-string} is text designed to convey to the user +that this frame is associated with a function call made by @value{GDBN} to a +function in the program being debugged. + +@item +@findex signal-handler-caller +@smallexample +^Z^Zsignal-handler-caller +@var{signal-handler-caller-string} +@end smallexample + +where @var{signal-handler-caller-string} is text designed to convey to +the user that this frame is associated with whatever mechanism is used +by this operating system to call a signal handler (it is the frame which +calls the signal handler, not the frame for the signal handler itself). + +@item +A normal frame. + +@findex frame-address +@findex frame-address-end +This can optionally (depending on whether this is thought of as +interesting information for the user to see) begin with + +@smallexample +^Z^Zframe-address +@var{address} +^Z^Zframe-address-end +@var{separator-string} +@end smallexample + +where @var{address} is the address executing in the frame (the same +address as in the @code{frame-begin} annotation, but printed in a form +which is intended for user consumption---in particular, the syntax varies +depending on the language), and @var{separator-string} is a string +intended to separate this address from what follows for the user's +benefit. + +@findex frame-function-name +@findex frame-args +Then comes + +@smallexample +^Z^Zframe-function-name +@var{function-name} +^Z^Zframe-args +@var{arguments} +@end smallexample + +where @var{function-name} is the name of the function executing in the +frame, or @samp{??} if not known, and @var{arguments} are the arguments +to the frame, with parentheses around them (each argument is annotated +individually as well, @pxref{Value Annotations}). + +@findex frame-source-begin +@findex frame-source-file +@findex frame-source-file-end +@findex frame-source-line +@findex frame-source-end +If source information is available, a reference to it is then printed: + +@smallexample +^Z^Zframe-source-begin +@var{source-intro-string} +^Z^Zframe-source-file +@var{filename} +^Z^Zframe-source-file-end +: +^Z^Zframe-source-line +@var{line-number} +^Z^Zframe-source-end +@end smallexample + +where @var{source-intro-string} separates for the user's benefit the +reference from the text which precedes it, @var{filename} is the name of +the source file, and @var{line-number} is the line number within that +file (the first line is line 1). + +@findex frame-where +If @value{GDBN} prints some information about where the frame is from (which +library, which load segment, etc.; currently only done on the RS/6000), +it is annotated with + +@smallexample +^Z^Zframe-where +@var{information} +@end smallexample + +Then, if source is to actually be displayed for this frame (for example, +this is not true for output from the @code{backtrace} command), then a +@code{source} annotation (@pxref{Source Annotations}) is displayed. Unlike +most annotations, this is output instead of the normal text which would be +output, not in addition. +@end itemize + +@node Displays +@chapter Displays + +@emph{Display Annotations have been removed. @sc{gdb/mi} instead +provides Variable Objects.} + +@findex display-begin +@findex display-number-end +@findex display-format +@findex display-expression +@findex display-expression-end +@findex display-value +@findex display-end +@cindex annotations for display +When @value{GDBN} is told to display something using the @code{display} command, +the results of the display are annotated: + +@smallexample +^Z^Zdisplay-begin +@var{number} +^Z^Zdisplay-number-end +@var{number-separator} +^Z^Zdisplay-format +@var{format} +^Z^Zdisplay-expression +@var{expression} +^Z^Zdisplay-expression-end +@var{expression-separator} +^Z^Zdisplay-value +@var{value} +^Z^Zdisplay-end +@end smallexample + +@noindent +where @var{number} is the number of the display, @var{number-separator} +is intended to separate the number from what follows for the user, +@var{format} includes information such as the size, format, or other +information about how the value is being displayed, @var{expression} is +the expression being displayed, @var{expression-separator} is intended +to separate the expression from the text that follows for the user, +and @var{value} is the actual value being displayed. + +@node Prompting +@chapter Annotation for @value{GDBN} Input + +@cindex annotations for prompts +When @value{GDBN} prompts for input, it annotates this fact so it is possible +to know when to send output, when the output from a given command is +over, etc. + +Different kinds of input each have a different @dfn{input type}. Each +input type has three annotations: a @code{pre-} annotation, which +denotes the beginning of any prompt which is being output, a plain +annotation, which denotes the end of the prompt, and then a @code{post-} +annotation which denotes the end of any echo which may (or may not) be +associated with the input. For example, the @code{prompt} input type +features the following annotations: + +@smallexample +^Z^Zpre-prompt +^Z^Zprompt +^Z^Zpost-prompt +@end smallexample + +The input types are + +@table @code +@findex pre-prompt +@findex prompt +@findex post-prompt +@item prompt +When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). + +@findex pre-commands +@findex commands +@findex post-commands +@item commands +When @value{GDBN} prompts for a set of commands, like in the @code{commands} +command. The annotations are repeated for each command which is input. + +@findex pre-overload-choice +@findex overload-choice +@findex post-overload-choice +@item overload-choice +When @value{GDBN} wants the user to select between various overloaded functions. + +@findex pre-query +@findex query +@findex post-query +@item query +When @value{GDBN} wants the user to confirm a potentially dangerous operation. + +@findex pre-prompt-for-continue +@findex prompt-for-continue +@findex post-prompt-for-continue +@item prompt-for-continue +When @value{GDBN} is asking the user to press return to continue. Note: Don't +expect this to work well; instead use @code{set height 0} to disable +prompting. This is because the counting of lines is buggy in the +presence of annotations. +@end table + +@node Errors +@chapter Errors +@cindex annotations for errors, warnings and interrupts + +@findex quit +@smallexample +^Z^Zquit +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an interrupt. + +@findex error +@smallexample +^Z^Zerror +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an error. + +Quit and error annotations indicate that any annotations which @value{GDBN} was +in the middle of may end abruptly. For example, if a +@code{value-history-begin} annotation is followed by a @code{error}, one +cannot expect to receive the matching @code{value-history-end}. One +cannot expect not to receive it either, however; an error annotation +does not necessarily mean that @value{GDBN} is immediately returning all the way +to the top level. + +@findex error-begin +A quit or error annotation may be preceded by + +@smallexample +^Z^Zerror-begin +@end smallexample + +Any output between that and the quit or error annotation is the error +message. + +Warning messages are not yet annotated. +@c If we want to change that, need to fix warning(), type_error(), +@c range_error(), and possibly other places. + +@node Breakpoint Info +@chapter Information on Breakpoints + +@emph{Breakpoint Annotations have been removed. @sc{gdb/mi} instead +provides breakpoint commands.} + +@cindex annotations for breakpoints +The output from the @code{info breakpoints} command is annotated as follows: + +@findex breakpoints-headers +@findex breakpoints-table +@smallexample +^Z^Zbreakpoints-headers +@var{header-entry} +^Z^Zbreakpoints-table +@end smallexample + +@noindent +where @var{header-entry} has the same syntax as an entry (see below) but +instead of containing data, it contains strings which are intended to +convey the meaning of each field to the user. This is followed by any +number of entries. If a field does not apply for this entry, it is +omitted. Fields may contain trailing whitespace. Each entry consists +of: + +@findex record +@findex field +@smallexample +^Z^Zrecord +^Z^Zfield 0 +@var{number} +^Z^Zfield 1 +@var{type} +^Z^Zfield 2 +@var{disposition} +^Z^Zfield 3 +@var{enable} +^Z^Zfield 4 +@var{address} +^Z^Zfield 5 +@var{what} +^Z^Zfield 6 +@var{frame} +^Z^Zfield 7 +@var{condition} +^Z^Zfield 8 +@var{ignore-count} +^Z^Zfield 9 +@var{commands} +@end smallexample + +Note that @var{address} is intended for user consumption---the syntax +varies depending on the language. + +The output ends with + +@findex breakpoints-table-end +@smallexample +^Z^Zbreakpoints-table-end +@end smallexample + +@node Invalidation +@chapter Invalidation Notices + +@cindex annotations for invalidation messages +The following annotations say that certain pieces of state may have +changed. + +@table @code +@findex frames-invalid +@item ^Z^Zframes-invalid + +The frames (for example, output from the @code{backtrace} command) may +have changed. + +@findex breakpoints-invalid +@item ^Z^Zbreakpoints-invalid + +The breakpoints may have changed. For example, the user just added or +deleted a breakpoint. +@end table + +@node Annotations for Running +@chapter Running the Program +@cindex annotations for running programs + +@findex starting +@findex stopping +When the program starts executing due to a @value{GDBN} command such as +@code{step} or @code{continue}, + +@smallexample +^Z^Zstarting +@end smallexample + +is output. When the program stops, + +@smallexample +^Z^Zstopped +@end smallexample + +is output. Before the @code{stopped} annotation, a variety of +annotations describe how the program stopped. + +@table @code +@findex exited +@item ^Z^Zexited @var{exit-status} +The program exited, and @var{exit-status} is the exit status (zero for +successful exit, otherwise nonzero). + +@findex signalled +@findex signal-name +@findex signal-name-end +@findex signal-string +@findex signal-string-end +@item ^Z^Zsignalled +The program exited with a signal. After the @code{^Z^Zsignalled}, the +annotation continues: + +@smallexample +@var{intro-text} +^Z^Zsignal-name +@var{name} +^Z^Zsignal-name-end +@var{middle-text} +^Z^Zsignal-string +@var{string} +^Z^Zsignal-string-end +@var{end-text} +@end smallexample + +@noindent +where @var{name} is the name of the signal, such as @code{SIGILL} or +@code{SIGSEGV}, and @var{string} is the explanation of the signal, such +as @code{Illegal Instruction} or @code{Segmentation fault}. +@var{intro-text}, @var{middle-text}, and @var{end-text} are for the +user's benefit and have no particular format. + +@findex signal +@item ^Z^Zsignal +The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is +just saying that the program received the signal, not that it was +terminated with it. + +@findex breakpoint +@item ^Z^Zbreakpoint @var{number} +The program hit breakpoint number @var{number}. + +@findex watchpoint +@item ^Z^Zwatchpoint @var{number} +The program hit watchpoint number @var{number}. +@end table + +@node Source Annotations +@chapter Displaying Source +@cindex annotations for source display + +@findex source +The following annotation is used instead of displaying source code: + +@smallexample +^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} +@end smallexample + +where @var{filename} is an absolute file name indicating which source +file, @var{line} is the line number within that file (where 1 is the +first line in the file), @var{character} is the character position +within the file (where 0 is the first character in the file) (for most +debug formats this will necessarily point to the beginning of a line), +@var{middle} is @samp{middle} if @var{addr} is in the middle of the +line, or @samp{beg} if @var{addr} is at the beginning of the line, and +@var{addr} is the address in the target program associated with the +source which is being displayed. @var{addr} is in the form @samp{0x} +followed by one or more lowercase hex digits (note that this does not +depend on the language). + +@node Multi-threaded Apps +@chapter Multi-threaded Applications +@cindex annotations for multi-threaded apps + +The following annotations report thread related changes of state. + +@table @code +@findex new-thread@r{, annotation} +@item ^Z^Znew-thread + +This annotation is issued once for each thread that is created apart from +the main thread, which is not reported. + +@findex thread-changed@r{, annotation} +@item ^Z^Zthread-changed + +The selected thread has changed. This may occur at the request of the +user with the @code{thread} command, or as a result of execution, +e.g., another thread hits a breakpoint. + +@findex thread-exited@r{, annotation} +@item ^Z^Zthread-exited,id="@var{id}",group-id="@var{gid}" + +This annotation is issued once for each thread that exits. The @var{id} +field contains the global @value{GDBN} identifier of the thread. The +@var{gid} field identifies the thread group this thread belongs to. + +@end table + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include fdl.texi + +@ignore +@node Index +@unnumbered Index + +@printindex fn +@end ignore + +@bye diff -pruN 16.3-5/gdb/doc/fdl.texi 16.3-5ubuntu1/gdb/doc/fdl.texi --- 16.3-5/gdb/doc/fdl.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/fdl.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,505 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff -pruN 16.3-5/gdb/doc/gcore.1 16.3-5ubuntu1/gdb/doc/gcore.1 --- 16.3-5/gdb/doc/gcore.1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gcore.1 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,202 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GCORE 1" +.TH GCORE 1 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gcore \- Generate a core file of a running program +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gcore [\-a] [\-o \fIprefix\fR] [\-d \fIdirectory\fR] \fIpid1\fR [\fIpid2\fR...\fIpidN\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Generate core dumps of one or more running programs with process IDs +\&\fIpid1\fR, \fIpid2\fR, etc. A core file produced by \fBgcore\fR +is equivalent to one produced by the kernel when the process crashes +(and when \f(CW\*(C`ulimit \-c\*(C'\fR was used to set up an appropriate core dump +limit). However, unlike after a crash, after \fBgcore\fR finishes +its job the program remains running without any change. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-a\fR" 4 +.IX Item "-a" +Dump all memory mappings. The actual effect of this option depends on +the Operating System. On GNU/Linux, it will disable +\&\f(CW\*(C`use\-coredump\-filter\*(C'\fR and +enable \f(CW\*(C`dump\-excluded\-mappings\*(C'\fR. +.IP "\fB\-o\fR \fIprefix\fR" 4 +.IX Item "-o prefix" +The optional argument \fIprefix\fR specifies the prefix to be used +when composing the file names of the core dumps. The file name is +composed as \fI\fIprefix\fI.\fIpid\fI\fR, where \fIpid\fR is the +process \s-1ID\s0 of the running program being analyzed by \fBgcore\fR. +If not specified, \fIprefix\fR defaults to \fIgcore\fR. +.IP "\fB\-d\fR \fIdirectory\fR" 4 +.IX Item "-d directory" +Use \fIdirectory\fR as the data directory when invoking \s-1GDB\s0 for running +the gcore command. This argument is optional. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/gdb-add-index.1 16.3-5ubuntu1/gdb/doc/gdb-add-index.1 --- 16.3-5/gdb/doc/gdb-add-index.1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb-add-index.1 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,226 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDB-ADD-INDEX 1" +.TH GDB-ADD-INDEX 1 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdb\-add\-index \- Add index files to speed up GDB +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gdb-add-index [\-dwarf\-5] \fIfilename\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +When \s-1GDB\s0 finds a symbol file, it scans the symbols in the +file in order to construct an internal symbol table. This lets most +\&\s-1GDB\s0 operations work quickly\*(--at the cost of a delay early on. +For large programs, this delay can be quite lengthy, so \s-1GDB\s0 +provides a way to build an index, which speeds up startup. +.PP +To determine whether a file contains such an index, use the command +\&\f(CW\*(C`readelf \-S filename\*(C'\fR: the index is stored in a section named +\&\f(CW\*(C`.gdb_index\*(C'\fR (pre-DWARF 5) or \f(CW\*(C`.debug_names\*(C'\fR and +\&\f(CW\*(C`.debug_str\*(C'\fR (\s-1DWARF 5\s0). Indexes can only be produced on systems +which use \s-1ELF\s0 binaries and \s-1DWARF\s0 debug information (i.e., sections +named \f(CW\*(C`.debug_*\*(C'\fR). +.PP +By default \fBgdb-add-index\fR will add a pre-DWARF 5 +\&\f(CW\*(C`.gdb_index\*(C'\fR section to \fIfilename\fR. With \fB\-dwarf\-5\fR +\&\s-1DWARF 5\s0 sections are added instead. +.PP +\&\fIfilename\fR must be writable. +.PP +\&\fBgdb-add-index\fR uses \s-1GDB,\s0 \fBobjcopy\fR, and +\&\fBreadelf\fR found in the \fB\s-1PATH\s0\fR environment variable. If +you want to use different versions of these programs, you can specify +them through the appropriate environment variables (see below). +.PP +\&\fBgdb-add-index\fR exits with status 0 if it succeeds in creating +the index for \fIfilename\fR or greater than 0 if an error occurs. +.PP +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`Index Files\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n "Index Files"\*(C'\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-dwarf\-5\fR" 4 +.IX Item "-dwarf-5" +Add \s-1DWARF 5\s0 sections instead of previous \f(CW\*(C`.debug_index\*(C'\fR section. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.IP "\fB\s-1GDB\s0\fR" 4 +.IX Item "GDB" +Full file name of the \f(CW\*(C`gdb\*(C'\fR program to use for index generation. +If not set, the \fB\s-1PATH\s0\fR will be searched for a \f(CW\*(C`gdb\*(C'\fR program. +.IP "\fB\s-1OBJCOPY\s0\fR" 4 +.IX Item "OBJCOPY" +Full file name of the \f(CW\*(C`objcopy\*(C'\fR program to use to copy section +information into the given file. If not set, the \fB\s-1PATH\s0\fR will be searched +for a \f(CW\*(C`objcopy\*(C'\fR program. +.IP "\fB\s-1READELF\s0\fR" 4 +.IX Item "READELF" +Full file name of the \f(CW\*(C`readelf\*(C'\fR program to use to inspect +properties of the given file. If not set, the \fB\s-1PATH\s0\fR will be searched +for a \f(CW\*(C`readelf\*(C'\fR program. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/gdb.1 16.3-5ubuntu1/gdb/doc/gdb.1 --- 16.3-5/gdb/doc/gdb.1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.1 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,508 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDB 1" +.TH GDB 1 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdb \- The GNU Debugger +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gdb [\s-1OPTIONS\s0] [\fIprog\fR|\fIprog\fR \fIprocID\fR|\fIprog\fR \fIcore\fR] +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +The purpose of a debugger such as \s-1GDB\s0 is to allow you to see what is +going on \*(L"inside\*(R" another program while it executes \*(-- or what another +program was doing at the moment it crashed. +.PP +\&\s-1GDB\s0 can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: +.IP "\(bu" 4 +Start your program, specifying anything that might affect its behavior. +.IP "\(bu" 4 +Make your program stop on specified conditions. +.IP "\(bu" 4 +Examine what has happened, when your program has stopped. +.IP "\(bu" 4 +Change things in your program, so you can experiment with correcting the +effects of one bug and go on to learn about another. +.PP +You can use \s-1GDB\s0 to debug programs written in C, \*(C+, Fortran and +Modula\-2. +.PP +\&\s-1GDB\s0 is invoked with the shell command \f(CW\*(C`gdb\*(C'\fR. Once started, it reads +commands from the terminal until you tell it to exit with the \s-1GDB\s0 +command \f(CW\*(C`quit\*(C'\fR or \f(CW\*(C`exit\*(C'\fR. You can get online help from \s-1GDB\s0 itself +by using the command \f(CW\*(C`help\*(C'\fR. +.PP +You can run \f(CW\*(C`gdb\*(C'\fR with no arguments or options; but the most +usual way to start \s-1GDB\s0 is with one argument or two, specifying an +executable program as the argument: +.PP +.Vb 1 +\& gdb program +.Ve +.PP +You can also start with both an executable program and a core file specified: +.PP +.Vb 1 +\& gdb program core +.Ve +.PP +You can, instead, specify a process \s-1ID\s0 as a second argument or use option +\&\f(CW\*(C`\-p\*(C'\fR, if you want to debug a running process: +.PP +.Vb 2 +\& gdb program 1234 +\& gdb \-p 1234 +.Ve +.PP +would attach \s-1GDB\s0 to process \f(CW1234\fR. With option \fB\-p\fR you +can omit the \fIprogram\fR filename. +.PP +Here are some of the most frequently needed \s-1GDB\s0 commands: +.IP "\fBbreak [\fR\fIfile\fR\fB:][\fR\fIfunction\fR\fB|\fR\fIline\fR\fB]\fR" 4 +.IX Item "break [file:][function|line]" +Set a breakpoint at \fIfunction\fR or \fIline\fR (in \fIfile\fR). +.IP "\fBrun [\fR\fIarglist\fR\fB]\fR" 4 +.IX Item "run [arglist]" +Start your program (with \fIarglist\fR, if specified). +.IP "\fBbt\fR" 4 +.IX Item "bt" +Backtrace: display the program stack. +.IP "\fBprint\fR \fIexpr\fR" 4 +.IX Item "print expr" +Display the value of an expression. +.IP "\fBc\fR" 4 +.IX Item "c" +Continue running your program (after stopping, e.g. at a breakpoint). +.IP "\fBnext\fR" 4 +.IX Item "next" +Execute next program line (after stopping); step \fIover\fR any +function calls in the line. +.IP "\fBedit [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 +.IX Item "edit [file:]function" +look at the program line where it is presently stopped. +.IP "\fBlist [\fR\fIfile\fR\fB:]\fR\fIfunction\fR" 4 +.IX Item "list [file:]function" +type the text of the program in the vicinity of where it is presently stopped. +.IP "\fBstep\fR" 4 +.IX Item "step" +Execute next program line (after stopping); step \fIinto\fR any +function calls in the line. +.IP "\fBhelp [\fR\fIname\fR\fB]\fR" 4 +.IX Item "help [name]" +Show information about \s-1GDB\s0 command \fIname\fR, or general information +about using \s-1GDB.\s0 +.IP "\fBquit\fR" 4 +.IX Item "quit" +.PD 0 +.IP "\fBexit\fR" 4 +.IX Item "exit" +.PD +Exit from \s-1GDB.\s0 +.PP +For full details on \s-1GDB,\s0 +see \fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +by Richard M. Stallman and Roland H. Pesch. The same text is available online +as the \f(CW\*(C`gdb\*(C'\fR entry in the \f(CW\*(C`info\*(C'\fR program. +.SH "OPTIONS" +.IX Header "OPTIONS" +Any arguments other than options specify an executable +file and core file (or process \s-1ID\s0); that is, the first argument +encountered with no +associated option flag is equivalent to a \fB\-\-se\fR option, and the second, +if any, is equivalent to a \fB\-c\fR option if it's the name of a file. +Many options have +both long and abbreviated forms; both are shown here. The long forms are also +recognized if you truncate them, so long as enough of the option is +present to be unambiguous. +.PP +The abbreviated forms are shown here with \fB\-\fR and long forms are shown +with \fB\-\-\fR to reflect how they are shown in \fB\-\-help\fR. However, +\&\s-1GDB\s0 recognizes all of the following conventions for most options: +.ie n .IP """\-\-option=\fIvalue\fP""" 4 +.el .IP "\f(CW\-\-option=\f(CIvalue\f(CW\fR" 4 +.IX Item "--option=value" +.PD 0 +.ie n .IP """\-\-option \fIvalue\fP""" 4 +.el .IP "\f(CW\-\-option \f(CIvalue\f(CW\fR" 4 +.IX Item "--option value" +.ie n .IP """\-option=\fIvalue\fP""" 4 +.el .IP "\f(CW\-option=\f(CIvalue\f(CW\fR" 4 +.IX Item "-option=value" +.ie n .IP """\-option \fIvalue\fP""" 4 +.el .IP "\f(CW\-option \f(CIvalue\f(CW\fR" 4 +.IX Item "-option value" +.ie n .IP """\-\-o=\fIvalue\fP""" 4 +.el .IP "\f(CW\-\-o=\f(CIvalue\f(CW\fR" 4 +.IX Item "--o=value" +.ie n .IP """\-\-o \fIvalue\fP""" 4 +.el .IP "\f(CW\-\-o \f(CIvalue\f(CW\fR" 4 +.IX Item "--o value" +.ie n .IP """\-o=\fIvalue\fP""" 4 +.el .IP "\f(CW\-o=\f(CIvalue\f(CW\fR" 4 +.IX Item "-o=value" +.ie n .IP """\-o \fIvalue\fP""" 4 +.el .IP "\f(CW\-o \f(CIvalue\f(CW\fR" 4 +.IX Item "-o value" +.PD +.PP +All the options and command line arguments you give are processed +in sequential order. The order makes a difference when the \fB\-x\fR +option is used. +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD 0 +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD +List all options, with brief explanations. +.IP "\fB\-\-symbols=\fR\fIfile\fR" 4 +.IX Item "--symbols=file" +.PD 0 +.IP "\fB\-s\fR \fIfile\fR" 4 +.IX Item "-s file" +.PD +Read symbol table from \fIfile\fR. +.IP "\fB\-\-write\fR" 4 +.IX Item "--write" +Enable writing into executable and core files. +.IP "\fB\-\-exec=\fR\fIfile\fR" 4 +.IX Item "--exec=file" +.PD 0 +.IP "\fB\-e\fR \fIfile\fR" 4 +.IX Item "-e file" +.PD +Use \fIfile\fR as the executable file to execute when +appropriate, and for examining pure data in conjunction with a core +dump. +.IP "\fB\-\-se=\fR\fIfile\fR" 4 +.IX Item "--se=file" +Read symbol table from \fIfile\fR and use it as the executable +file. +.IP "\fB\-\-core=\fR\fIfile\fR" 4 +.IX Item "--core=file" +.PD 0 +.IP "\fB\-c\fR \fIfile\fR" 4 +.IX Item "-c file" +.PD +Use \fIfile\fR as a core dump to examine. +.IP "\fB\-\-command=\fR\fIfile\fR" 4 +.IX Item "--command=file" +.PD 0 +.IP "\fB\-x\fR \fIfile\fR" 4 +.IX Item "-x file" +.PD +Execute \s-1GDB\s0 commands from \fIfile\fR. +.IP "\fB\-\-eval\-command=\fR\fIcommand\fR" 4 +.IX Item "--eval-command=command" +.PD 0 +.IP "\fB\-ex\fR \fIcommand\fR" 4 +.IX Item "-ex command" +.PD +Execute given \s-1GDB\s0 \fIcommand\fR. +.IP "\fB\-\-init\-eval\-command=\fR\fIcommand\fR" 4 +.IX Item "--init-eval-command=command" +.PD 0 +.IP "\fB\-iex\fR" 4 +.IX Item "-iex" +.PD +Execute \s-1GDB\s0 \fIcommand\fR before loading the inferior. +.IP "\fB\-\-directory=\fR\fIdirectory\fR" 4 +.IX Item "--directory=directory" +.PD 0 +.IP "\fB\-d\fR \fIdirectory\fR" 4 +.IX Item "-d directory" +.PD +Add \fIdirectory\fR to the path to search for source files. +.IP "\fB\-\-nh\fR" 4 +.IX Item "--nh" +Do not execute commands from \fI~/.config/gdb/gdbinit\fR, +\&\fI~/.gdbinit\fR, \fI~/.config/gdb/gdbearlyinit\fR, or +\&\fI~/.gdbearlyinit\fR +.IP "\fB\-\-nx\fR" 4 +.IX Item "--nx" +.PD 0 +.IP "\fB\-n\fR" 4 +.IX Item "-n" +.PD +Do not execute commands from any \fI.gdbinit\fR or +\&\fI.gdbearlyinit\fR initialization files. +.IP "\fB\-\-quiet\fR" 4 +.IX Item "--quiet" +.PD 0 +.IP "\fB\-\-silent\fR" 4 +.IX Item "--silent" +.IP "\fB\-q\fR" 4 +.IX Item "-q" +.PD +\&\*(L"Quiet\*(R". Do not print the introductory and copyright messages. These +messages are also suppressed in batch mode. +.IP "\fB\-\-batch\fR" 4 +.IX Item "--batch" +Run in batch mode. Exit with status \f(CW0\fR after processing all the command +files specified with \fB\-x\fR (and \fI.gdbinit\fR, if not inhibited). +Exit with nonzero status if an error occurs in executing the \s-1GDB\s0 +commands in the command files. +.Sp +Batch mode may be useful for running \s-1GDB\s0 as a filter, for example to +download and run a program on another computer; in order to make this +more useful, the message +.Sp +.Vb 1 +\& Program exited normally. +.Ve +.Sp +(which is ordinarily issued whenever a program running under \s-1GDB\s0 control +terminates) is not issued when running in batch mode. +.IP "\fB\-\-batch\-silent\fR" 4 +.IX Item "--batch-silent" +Run in batch mode, just like \fB\-\-batch\fR, but totally silent. All \s-1GDB\s0 +output is suppressed (stderr is unaffected). This is much quieter than +\&\fB\-\-silent\fR and would be useless for an interactive session. +.Sp +This is particularly useful when using targets that give \fBLoading section\fR +messages, for example. +.Sp +Note that targets that give their output via \s-1GDB,\s0 as opposed to writing +directly to \f(CW\*(C`stdout\*(C'\fR, will also be made silent. +.IP "\fB\-\-args\fR \fIprog\fR \fB[\fR\fIarglist\fR\fB]\fR" 4 +.IX Item "--args prog [arglist]" +Change interpretation of command line so that arguments following this +option are passed as arguments to the inferior. As an example, take +the following command: +.Sp +.Vb 1 +\& gdb ./a.out \-q +.Ve +.Sp +It would start \s-1GDB\s0 with \fB\-q\fR, not printing the introductory message. On +the other hand, using: +.Sp +.Vb 1 +\& gdb \-\-args ./a.out \-q +.Ve +.Sp +starts \s-1GDB\s0 with the introductory message, and passes the option to the inferior. +.IP "\fB\-\-pid=\fR\fIpid\fR" 4 +.IX Item "--pid=pid" +Attach \s-1GDB\s0 to an already running program, with the \s-1PID\s0 \fIpid\fR. +.IP "\fB\-\-tui\fR" 4 +.IX Item "--tui" +Open the terminal user interface. +.IP "\fB\-\-readnow\fR" 4 +.IX Item "--readnow" +Read all symbols from the given symfile on the first access. +.IP "\fB\-\-readnever\fR" 4 +.IX Item "--readnever" +Do not read symbol files. +.IP "\fB\-\-return\-child\-result\fR" 4 +.IX Item "--return-child-result" +\&\s-1GDB\s0's exit code will be the same as the child's exit code. +.IP "\fB\-\-configuration\fR" 4 +.IX Item "--configuration" +Print details about \s-1GDB\s0 configuration and then exit. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +Print version information and then exit. +.IP "\fB\-\-cd=\fR\fIdirectory\fR" 4 +.IX Item "--cd=directory" +Run \s-1GDB\s0 using \fIdirectory\fR as its working directory, +instead of the current directory. +.IP "\fB\-\-data\-directory=\fR\fIdirectory\fR" 4 +.IX Item "--data-directory=directory" +.PD 0 +.IP "\fB\-D\fR" 4 +.IX Item "-D" +.PD +Run \s-1GDB\s0 using \fIdirectory\fR as its data directory. The data +directory is where \s-1GDB\s0 searches for its auxiliary files. +.IP "\fB\-\-fullname\fR" 4 +.IX Item "--fullname" +.PD 0 +.IP "\fB\-f\fR" 4 +.IX Item "-f" +.PD +Emacs sets this option when it runs \s-1GDB\s0 as a subprocess. It tells +\&\s-1GDB\s0 to output the full file name and line number in a standard, +recognizable fashion each time a stack frame is displayed (which +includes each time the program stops). This recognizable format looks +like two \fB\e032\fR characters, followed by the file name, line number +and character position separated by colons, and a newline. The +Emacs-to-GDB interface program uses the two \fB\e032\fR +characters as a signal to display the source code for the frame. +.IP "\fB\-b\fR \fIbaudrate\fR" 4 +.IX Item "-b baudrate" +Set the line speed (baud rate or bits per second) of any serial +interface used by \s-1GDB\s0 for remote debugging. +.IP "\fB\-l\fR \fItimeout\fR" 4 +.IX Item "-l timeout" +Set timeout, in seconds, for remote debugging. +.IP "\fB\-\-tty=\fR\fIdevice\fR" 4 +.IX Item "--tty=device" +Run using \fIdevice\fR for your program's standard input and output. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/gdb.info 16.3-5ubuntu1/gdb/doc/gdb.info --- 16.3-5/gdb/doc/gdb.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,937 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +Indirect: +gdb.info-1: 1701 +gdb.info-2: 306134 +gdb.info-3: 602347 +gdb.info-4: 902128 +gdb.info-5: 1206509 +gdb.info-6: 1504844 +gdb.info-7: 1805249 +gdb.info-8: 2119919 +gdb.info-9: 2548518 + +Tag Table: +(Indirect) +Node: Top1701 +Node: Summary5330 +Node: Free Software7191 +Node: Free Documentation7931 +Node: Contributors12865 +Node: Sample Session21896 +Node: Invocation28733 +Node: Invoking GDB29284 +Node: File Options31679 +Ref: --readnever35305 +Node: Mode Options35779 +Ref: -nx36006 +Ref: -nh36118 +Node: Startup42893 +Ref: Option -init-eval-command44118 +Node: Initialization Files45894 +Ref: System Wide Init Files49501 +Ref: Home Directory Init File50782 +Ref: Init File in the Current Directory during Startup51945 +Ref: Initialization Files-Footnote-152668 +Ref: Initialization Files-Footnote-252777 +Node: Quitting GDB52886 +Node: Shell Commands53828 +Ref: pipe54949 +Node: Logging Output56463 +Node: Commands57582 +Node: Command Syntax58398 +Node: Command Settings60570 +Node: Completion63583 +Ref: Completion-Footnote-170926 +Node: Filename Arguments71086 +Node: Command Options73557 +Node: Help75979 +Ref: show configuration83166 +Node: Running83877 +Node: Compilation85130 +Node: Starting87209 +Ref: set exec-wrapper92999 +Ref: set startup-with-shell94074 +Ref: set auto-connect-native-target95135 +Node: Arguments99607 +Node: Environment100876 +Ref: set environment102758 +Ref: unset environment103940 +Node: Working Directory104946 +Ref: set cwd command105518 +Ref: cd command106458 +Node: Input/Output107152 +Node: Attach109212 +Ref: set exec-file-mismatch110429 +Node: Kill Process112565 +Node: Inferiors Connections and Programs113558 +Ref: add_inferior_cli118486 +Ref: remove_inferiors_cli120504 +Node: Inferior-Specific Breakpoints124440 +Node: Threads126149 +Ref: thread numbers128272 +Ref: thread ID lists129162 +Ref: global thread numbers130202 +Ref: info_threads131737 +Ref: thread apply all134395 +Ref: set libthread-db-search-path139245 +Node: Forks141443 +Node: Checkpoint/Restart148008 +Ref: Checkpoint/Restart-Footnote-1152540 +Node: Stopping152575 +Node: Breakpoints153883 +Node: Set Breaks157140 +Node: Set Watchpoints181045 +Node: Set Catchpoints190581 +Ref: catch syscall196079 +Node: Delete Breaks203844 +Node: Disabling206566 +Node: Conditions209985 +Node: Break Commands215907 +Node: Dynamic Printf219496 +Node: Save Breakpoints224556 +Node: Static Probe Points225731 +Ref: enable probes228279 +Ref: Static Probe Points-Footnote-1229909 +Ref: Static Probe Points-Footnote-2230069 +Node: Error in Breakpoints230209 +Node: Breakpoint-related Warnings230945 +Node: Continuing and Stepping233272 +Ref: range stepping243080 +Node: Skipping Over Functions and Files244160 +Node: Signals250030 +Ref: stepping and signal handlers254574 +Ref: stepping into signal handlers255370 +Ref: extra signal information256603 +Node: Thread Stops258107 +Node: All-Stop Mode259242 +Ref: set scheduler-locking260727 +Node: Non-Stop Mode263584 +Node: Background Execution266997 +Node: Thread-Specific Breakpoints269213 +Node: Interrupted System Calls271442 +Node: Observer Mode272956 +Node: Reverse Execution276392 +Ref: Reverse Execution-Footnote-1281313 +Ref: Reverse Execution-Footnote-2281940 +Node: Process Record and Replay281990 +Node: Stack306134 +Node: Frames307751 +Node: Backtrace310089 +Ref: backtrace-command310426 +Ref: set backtrace past-main316873 +Ref: set backtrace past-entry317201 +Ref: set backtrace limit317768 +Ref: Backtrace-Footnote-1318392 +Node: Selection318580 +Node: Frame Info323363 +Node: Frame Apply327785 +Node: Frame Filter Management332215 +Ref: disable frame-filter all332743 +Node: Source337051 +Node: List338177 +Node: Location Specifications341817 +Node: Linespec Locations346421 +Node: Explicit Locations349827 +Node: Address Locations353046 +Node: Edit354804 +Ref: Edit-Footnote-1356491 +Node: Search356726 +Node: Source Path357534 +Ref: set substitute-path366474 +Node: Machine Code368694 +Ref: disassemble370692 +Node: Disable Reading Source380680 +Node: Data381442 +Ref: print options382281 +Node: Expressions393323 +Node: Ambiguous Expressions395426 +Node: Variables398656 +Node: Arrays405254 +Node: Output Formats407785 +Ref: Output Formats-Footnote-1411354 +Node: Memory411511 +Ref: addressable memory unit418466 +Node: Memory Tagging419960 +Node: Auto Display422643 +Node: Print Settings427193 +Ref: set print address427491 +Ref: set print symbol431153 +Ref: set print array431641 +Ref: set print array-indexes431969 +Ref: set print nibbles432455 +Ref: set print characters433002 +Ref: set print elements434069 +Ref: set print frame-arguments435189 +Ref: set print raw-frame-arguments437358 +Ref: set print entry-values437774 +Ref: set print frame-info442153 +Ref: set print repeats443819 +Ref: set print max-depth444461 +Ref: set print memory-tag-violations446153 +Ref: set print null-stop446580 +Ref: set print pretty446904 +Ref: set print raw-values447491 +Ref: set print union448508 +Ref: set print object450814 +Ref: set print static-members451608 +Ref: set print vtbl452285 +Node: Pretty Printing452669 +Node: Pretty-Printer Introduction453185 +Node: Pretty-Printer Example454942 +Node: Pretty-Printer Commands455722 +Node: Value History458606 +Node: Convenience Vars461028 +Node: Convenience Funs468806 +Ref: $_shell convenience function473610 +Node: Registers479809 +Ref: info_registers_reggroup480466 +Ref: standard registers481017 +Ref: Registers-Footnote-1485968 +Node: Floating Point Hardware486363 +Node: Vector Unit486895 +Node: OS Information487282 +Ref: linux info os infotypes489306 +Node: Memory Region Attributes493897 +Node: Dump/Restore Files498560 +Node: Core File Generation500963 +Ref: set use-coredump-filter502634 +Ref: set dump-excluded-mappings504082 +Node: Character Sets504364 +Node: Caching Target Data510729 +Ref: Caching Target Data-Footnote-1513621 +Node: Searching Memory513859 +Node: Value Sizes517002 +Ref: set max-value-size517429 +Node: Optimized Code518654 +Node: Inline Functions520331 +Node: Tail Call Frames522958 +Ref: set debug entry-values525096 +Node: Macros529160 +Ref: Macros-Footnote-1536778 +Node: Tracepoints536931 +Node: Set Tracepoints538993 +Node: Create and Delete Tracepoints541931 +Node: Enable and Disable Tracepoints548386 +Node: Tracepoint Passcounts549626 +Node: Tracepoint Conditions551037 +Node: Trace State Variables552731 +Node: Tracepoint Actions554926 +Node: Listing Tracepoints561711 +Node: Listing Static Tracepoint Markers563413 +Node: Starting and Stopping Trace Experiments565261 +Ref: disconnected tracing567006 +Node: Tracepoint Restrictions571426 +Node: Analyze Collected Data575195 +Node: tfind576501 +Node: tdump580983 +Node: save tracepoints583498 +Node: Tracepoint Variables583994 +Node: Trace Files585122 +Node: Overlays587637 +Node: How Overlays Work588357 +Ref: A code overlay590892 +Node: Overlay Commands594325 +Node: Automatic Overlay Debugging598507 +Node: Overlay Sample Program602347 +Node: Languages604084 +Node: Setting605247 +Node: Filenames606948 +Node: Manually607759 +Node: Automatically608968 +Node: Show610389 +Ref: show language610677 +Node: Checks611711 +Node: Type Checking612716 +Node: Range Checking614545 +Node: Supported Languages616952 +Node: C618289 +Node: C Operators619253 +Node: C Constants623592 +Node: C Plus Plus Expressions626471 +Node: C Defaults629831 +Node: C Checks630499 +Node: Debugging C631059 +Node: Debugging C Plus Plus631543 +Node: Decimal Floating Point637149 +Node: D638418 +Node: Go638676 +Node: Objective-C639770 +Node: Method Names in Commands640233 +Node: The Print Command with Objective-C641924 +Node: OpenCL C642575 +Node: OpenCL C Datatypes642850 +Node: OpenCL C Expressions643225 +Node: OpenCL C Operators643582 +Node: Fortran643814 +Node: Fortran Types644805 +Node: Fortran Operators646722 +Node: Fortran Intrinsics647791 +Node: Special Fortran Commands650419 +Node: Pascal651820 +Node: Rust652331 +Node: Modula-2655425 +Node: M2 Operators656398 +Node: Built-In Func/Proc659396 +Node: M2 Constants662358 +Node: M2 Types663959 +Node: M2 Defaults667177 +Node: Deviations667778 +Node: M2 Checks668879 +Node: M2 Scope669696 +Node: GDB/M2670720 +Node: Ada671633 +Node: Ada Mode Intro672937 +Node: Omissions from Ada674439 +Node: Additions to Ada678852 +Node: Overloading support for Ada683223 +Node: Stopping Before Main Program684863 +Node: Ada Exceptions685410 +Node: Ada Tasks686609 +Node: Ada Tasks and Core Files694987 +Node: Ravenscar Profile695834 +Node: Ada Source Character Set698017 +Node: Ada Glitches698814 +Node: Unsupported Languages702834 +Node: Symbols703524 +Ref: quoting names704127 +Ref: maint print symbols732219 +Node: Altering739061 +Node: Assignment740099 +Node: Jumping743205 +Node: Signaling746021 +Node: Returning748950 +Node: Calling752301 +Ref: stack unwind settings753876 +Ref: set unwind-on-timeout755180 +Node: Patching762545 +Node: Compiling and Injecting Code763659 +Ref: set debug compile767412 +Ref: set debug compile-cplus-types767662 +Node: GDB Files777684 +Node: Files778532 +Ref: core-file command784056 +Ref: Shared Libraries793345 +Ref: Files-Footnote-1805510 +Node: File Caching805639 +Node: Separate Debug Files806773 +Ref: build ID808014 +Ref: debug-file-directory810482 +Node: MiniDebugInfo819214 +Node: Index Files821665 +Node: Debug Names826469 +Node: Symbol Errors827775 +Node: Data Files831391 +Node: Targets832347 +Node: Active Targets833827 +Node: Target Commands834901 +Ref: load839541 +Ref: flash-erase840734 +Node: Byte Order840794 +Node: Remote Debugging842233 +Node: Connecting843500 +Ref: --multi Option in Types of Remote Connnections845726 +Ref: Attaching in Types of Remote Connections847141 +Ref: Host and target files848021 +Node: File Transfer856643 +Node: Server857582 +Ref: Running gdbserver859158 +Ref: Attaching to a program861376 +Ref: Other Command-Line Arguments for gdbserver863901 +Ref: Monitor Commands for gdbserver868241 +Ref: Server-Footnote-1874298 +Node: Remote Configuration874418 +Ref: set remotebreak875678 +Ref: set remote hardware-watchpoint-limit877140 +Ref: set remote hardware-breakpoint-limit877140 +Ref: set remote hardware-watchpoint-length-limit877642 +Ref: set remote exec-file878097 +Node: Remote Stub891610 +Node: Stub Contents894505 +Node: Bootstrapping896612 +Node: Debug Session902128 +Node: Configurations904169 +Node: Native904938 +Node: BSD libkvm Interface905564 +Node: Process Information906616 +Node: DJGPP Native912001 +Node: Cygwin Native918554 +Node: Non-debug DLL Symbols923475 +Node: Hurd Native927714 +Node: Darwin932970 +Node: FreeBSD934247 +Node: Embedded OS934967 +Node: Embedded Processors935378 +Node: ARC936420 +Node: ARM936967 +Node: BPF939869 +Node: M68K940349 +Node: MicroBlaze940522 +Node: MIPS Embedded941971 +Node: OpenRISC 1000943268 +Node: PowerPC Embedded944174 +Node: AVR947581 +Node: CRIS947953 +Node: Super-H948931 +Node: Architectures949990 +Node: AArch64950418 +Ref: vl951695 +Ref: vq951806 +Ref: vg951916 +Ref: AArch64 SME951963 +Ref: svl953700 +Ref: svq953858 +Ref: svg953970 +Ref: aarch64 sme svcr954724 +Ref: AArch64 SME2959771 +Ref: AArch64 PAC961209 +Node: x86963830 +Node: Alpha964962 +Node: MIPS965094 +Node: HPPA968988 +Node: PowerPC969510 +Node: Sparc64970246 +Node: S12Z972614 +Node: AMD GPU972923 +Ref: AMD GPU Signals977053 +Ref: AMD GPU Attaching Restrictions982680 +Node: Controlling GDB983392 +Node: Prompt984335 +Node: Editing986053 +Node: Command History987501 +Node: Screen Size992695 +Node: Output Styling994711 +Ref: style_disassembler_enabled996494 +Node: Numbers1004687 +Node: ABI1006669 +Node: Auto-loading1009842 +Ref: set auto-load off1010908 +Ref: show auto-load1011544 +Ref: info auto-load1012323 +Node: Init File in the Current Directory1015599 +Ref: set auto-load local-gdbinit1016174 +Ref: show auto-load local-gdbinit1016356 +Ref: info auto-load local-gdbinit1016520 +Node: libthread_db.so.1 file1016668 +Ref: set auto-load libthread-db1017607 +Ref: show auto-load libthread-db1017738 +Ref: info auto-load libthread-db1017875 +Node: Auto-loading safe path1018059 +Ref: set auto-load safe-path1019360 +Ref: show auto-load safe-path1020099 +Ref: add-auto-load-safe-path1020222 +Node: Auto-loading verbose mode1023125 +Ref: set debug auto-load1024288 +Ref: show debug auto-load1024389 +Node: Messages/Warnings1024511 +Ref: confirmation requests1025945 +Node: Debugging Output1027149 +Ref: set debug amd-dbgapi-lib1028536 +Ref: set debug amd-dbgapi1029157 +Node: Other Misc Settings1039398 +Node: Extending GDB1042592 +Node: Sequences1044417 +Node: Define1045079 +Node: Hooks1051372 +Node: Command Files1053738 +Node: Output1058811 +Ref: %V Format Specifier1063613 +Ref: eval1064498 +Node: Auto-loading sequences1064660 +Ref: set auto-load gdb-scripts1065155 +Ref: show auto-load gdb-scripts1065279 +Ref: info auto-load gdb-scripts1065409 +Node: Aliases1065640 +Node: Command aliases default args1069091 +Ref: Command aliases default args-Footnote-11072812 +Node: Python1072966 +Node: Python Commands1074137 +Ref: set_python_print_stack1075512 +Ref: Python Commands-Footnote-11078594 +Node: Python API1078684 +Node: Basic Python1081912 +Ref: prompt_hook1093952 +Ref: gdb_architecture_names1094550 +Ref: gdbpy_connections1094897 +Node: Threading in GDB1097562 +Node: Exception Handling1100129 +Node: Values From Inferior1102991 +Ref: Value.assign1109946 +Node: Types In Python1123283 +Ref: Type.is_array_like1127281 +Node: Pretty Printing API1136118 +Node: Selecting Pretty-Printers1142706 +Node: Writing a Pretty-Printer1145433 +Node: Type Printing API1150945 +Node: Frame Filter API1153561 +Node: Frame Decorator API1160875 +Ref: frame_args1164614 +Node: Writing a Frame Filter1167942 +Node: Unwinding Frames in Python1179416 +Ref: gdb.PendingFrame.create_unwind_info1182709 +Ref: gdb.unwinder.FrameId1187642 +Ref: Managing Registered Unwinders1190996 +Node: Xmethods In Python1192268 +Node: Xmethod API1195164 +Node: Writing an Xmethod1198976 +Node: Inferiors In Python1206509 +Ref: gdbpy_inferior_connection1207468 +Ref: gdbpy_inferior_read_memory1210082 +Ref: choosing attribute names1212490 +Node: Events In Python1213629 +Node: Threads In Python1228071 +Ref: inferior_thread_ptid1229593 +Node: Recordings In Python1233493 +Node: CLI Commands In Python1241430 +Node: GDB/MI Commands In Python1251145 +Node: GDB/MI Notifications In Python1257802 +Node: Parameters In Python1259487 +Node: Functions In Python1268147 +Node: Progspaces In Python1270364 +Node: Objfiles In Python1277349 +Ref: Objfile.build_id1280579 +Node: Frames In Python1284349 +Ref: gdbpy_frame_read_register1290669 +Node: Blocks In Python1292993 +Node: Symbols In Python1297660 +Node: Symbol Tables In Python1308568 +Node: Line Tables In Python1311789 +Node: Breakpoints In Python1314628 +Ref: python_breakpoint_thread1321263 +Ref: python_breakpoint_inferior1321727 +Node: Finish Breakpoints in Python1328261 +Node: Lazy Strings In Python1330371 +Node: Architectures In Python1332650 +Ref: gdbpy_architecture_name1333111 +Ref: gdbpy_architecture_registers1335402 +Ref: gdbpy_architecture_reggroups1335723 +Node: Registers In Python1335922 +Node: Connections In Python1338192 +Node: TUI Windows In Python1343024 +Ref: python-window-click1347886 +Node: Disassembly In Python1348372 +Ref: DisassembleInfo Class1348764 +Ref: Disassembler Class1354445 +Ref: DisassemblerResult Class1356788 +Ref: Disassembler Styling Parts1360454 +Ref: Disassembler Style Constants1363743 +Ref: builtin_disassemble1371700 +Node: Missing Debug Info In Python1375299 +Node: Missing Objfiles In Python1381293 +Node: Python Auto-loading1389436 +Ref: set auto-load python-scripts1390065 +Ref: show auto-load python-scripts1390165 +Ref: info auto-load python-scripts1390271 +Node: Python modules1391405 +Node: gdb.printing1391857 +Node: gdb.types1393284 +Node: gdb.prompt1396296 +Node: gdb.ptwrite1397912 +Node: Guile1402146 +Node: Guile Introduction1402805 +Node: Guile Commands1403643 +Node: Guile API1405497 +Node: Basic Guile1407494 +Node: Guile Configuration1413176 +Node: GDB Scheme Data Types1414152 +Node: Guile Exception Handling1415984 +Node: Values From Inferior In Guile1420018 +Node: Arithmetic In Guile1436064 +Node: Types In Guile1437695 +Ref: Fields of a type in Guile1445940 +Node: Guile Pretty Printing API1447328 +Node: Selecting Guile Pretty-Printers1453068 +Node: Writing a Guile Pretty-Printer1455444 +Node: Commands In Guile1460629 +Node: Parameters In Guile1471414 +Ref: Parameters In Guile-Footnote-11478447 +Node: Progspaces In Guile1478563 +Node: Objfiles In Guile1481175 +Node: Frames In Guile1483456 +Node: Blocks In Guile1490035 +Node: Symbols In Guile1494843 +Node: Symbol Tables In Guile1504844 +Node: Breakpoints In Guile1507807 +Node: Lazy Strings In Guile1518932 +Node: Architectures In Guile1521223 +Node: Disassembly In Guile1525530 +Node: I/O Ports in Guile1528732 +Node: Memory Ports in Guile1529288 +Node: Iterators In Guile1533139 +Node: Guile Auto-loading1537428 +Ref: set auto-load guile-scripts1538051 +Ref: show auto-load guile-scripts1538149 +Ref: info auto-load guile-scripts1538253 +Node: Guile Modules1539212 +Node: Guile Printing Module1539534 +Node: Guile Types Module1540353 +Node: Auto-loading extensions1541658 +Node: objfile-gdbdotext file1543107 +Ref: set auto-load scripts-directory1544777 +Ref: with-auto-load-dir1545153 +Ref: show auto-load scripts-directory1545972 +Ref: add-auto-load-scripts-directory1546052 +Node: dotdebug_gdb_scripts section1546528 +Node: Which flavor to choose?1550278 +Node: Multiple Extension Languages1552099 +Node: Interpreters1553146 +Node: TUI1556628 +Node: TUI Overview1557676 +Node: TUI Keys1560435 +Node: TUI Single Key Mode1563158 +Node: TUI Mouse Support1564492 +Node: TUI Commands1565530 +Ref: info_win_command1566497 +Node: TUI Configuration1572438 +Ref: tui-mouse-events1574201 +Node: Emacs1574777 +Node: GDB/MI1580214 +Node: GDB/MI General Design1583003 +Node: Context management1585523 +Node: Asynchronous and non-stop modes1589309 +Node: Thread groups1592264 +Node: GDB/MI Command Syntax1594554 +Node: GDB/MI Input Syntax1594797 +Node: GDB/MI Output Syntax1596347 +Node: GDB/MI Compatibility with CLI1599932 +Node: GDB/MI Development and Front Ends1600668 +Node: GDB/MI Output Records1605047 +Node: GDB/MI Result Records1605453 +Node: GDB/MI Stream Records1606802 +Node: GDB/MI Async Records1608067 +Node: GDB/MI Breakpoint Information1618605 +Node: GDB/MI Frame Information1624467 +Node: GDB/MI Thread Information1625749 +Node: GDB/MI Ada Exception Information1627219 +Node: GDB/MI Simple Examples1627769 +Node: GDB/MI Command Description Format1630005 +Node: GDB/MI Breakpoint Commands1630885 +Ref: -break-insert1638159 +Node: GDB/MI Catchpoint Commands1652793 +Node: Shared Library GDB/MI Catchpoint Commands1653206 +Node: Ada Exception GDB/MI Catchpoint Commands1654864 +Node: C++ Exception GDB/MI Catchpoint Commands1658414 +Node: GDB/MI Program Context1662430 +Node: GDB/MI Thread Commands1666698 +Node: GDB/MI Ada Tasking Commands1669999 +Node: GDB/MI Program Execution1672271 +Node: GDB/MI Stack Manipulation1684984 +Ref: -stack-list-arguments1686908 +Ref: -stack-list-frames1690738 +Ref: -stack-list-locals1695000 +Ref: -stack-list-variables1696557 +Node: GDB/MI Variable Objects1698091 +Ref: -var-set-format1708033 +Ref: -var-list-children1709413 +Ref: -var-update1718221 +Ref: -var-set-frozen1721158 +Ref: -var-set-update-range1721943 +Ref: -var-set-visualizer1722476 +Node: GDB/MI Data Manipulation1724035 +Node: GDB/MI Tracepoint Commands1746899 +Node: GDB/MI Symbol Query1758867 +Ref: -symbol-info-functions1759061 +Ref: -symbol-info-module-functions1763560 +Ref: -symbol-info-module-variables1766542 +Ref: -symbol-info-modules1770277 +Ref: -symbol-info-types1772185 +Ref: -symbol-info-variables1774170 +Node: GDB/MI File Commands1779269 +Node: GDB/MI Target Manipulation1789108 +Node: GDB/MI File Transfer Commands1795766 +Node: GDB/MI Ada Exceptions Commands1797089 +Node: GDB/MI Support Commands1798442 +Node: GDB/MI Miscellaneous Commands1805249 +Ref: -interpreter-exec1817414 +Node: Annotations1821386 +Node: Annotations Overview1822317 +Node: Server Prefix1824780 +Node: Prompting1825514 +Node: Errors1827031 +Node: Invalidation1827927 +Node: Annotations for Running1828406 +Node: Source Annotations1829940 +Node: Debugger Adapter Protocol1830869 +Node: JIT Interface1835266 +Node: Declarations1837080 +Node: Registering Code1838467 +Node: Unregistering Code1839439 +Node: Custom Debug Info1840066 +Node: Using JIT Debug Info Readers1841362 +Node: Writing JIT Debug Info Readers1842524 +Node: In-Process Agent1844719 +Ref: Control Agent1846662 +Node: In-Process Agent Protocol1847529 +Node: IPA Protocol Objects1848320 +Ref: agent expression object1849318 +Ref: tracepoint action object1849523 +Ref: tracepoint object1849603 +Node: IPA Protocol Commands1852133 +Node: GDB Bugs1853533 +Node: Bug Criteria1854265 +Node: Bug Reporting1855142 +Node: Command Line Editing1862119 +Node: Introduction and Notation1862771 +Node: Readline Interaction1864392 +Node: Readline Bare Essentials1865581 +Node: Readline Movement Commands1867368 +Node: Readline Killing Commands1868326 +Node: Readline Arguments1870245 +Node: Searching1871287 +Node: Readline Init File1873437 +Node: Readline Init File Syntax1874590 +Node: Conditional Init Constructs1897890 +Node: Sample Init File1902084 +Node: Bindable Readline Commands1905206 +Node: Commands For Moving1906258 +Node: Commands For History1908014 +Node: Commands For Text1912975 +Node: Commands For Killing1916675 +Node: Numeric Arguments1919386 +Node: Commands For Completion1920523 +Node: Keyboard Macros1922489 +Node: Miscellaneous Commands1923175 +Node: Readline vi Mode1927100 +Node: Using History Interactively1928010 +Node: History Interaction1928525 +Node: Event Designators1930421 +Node: Word Designators1931693 +Node: Modifiers1933451 +Node: In Memoriam1934991 +Node: Formatting Documentation1935874 +Ref: Formatting Documentation-Footnote-11939190 +Node: Installing GDB1939256 +Node: Requirements1939828 +Ref: MPFR1941472 +Ref: Expat1943104 +Node: Running Configure1945983 +Node: Separate Objdir1948689 +Node: Config Names1951573 +Node: Configure Options1953020 +Node: System-wide configuration1962163 +Node: System-wide Configuration Scripts1964700 +Node: Maintenance Commands1965884 +Ref: maint info breakpoints1967608 +Ref: maint info python-disassemblers1970414 +Ref: maint packet1977529 +Ref: maint check libthread-db1979599 +Ref: maint_libopcodes_styling2002615 +Node: Remote Protocol2008166 +Node: Overview2008879 +Ref: Binary Data2011433 +Node: Standard Replies2014641 +Ref: textual error reply2015486 +Node: Packets2015588 +Ref: thread-id syntax2016496 +Ref: extended mode2017941 +Ref: ? packet2018199 +Ref: bc2019679 +Ref: bs2019889 +Ref: read registers packet2021471 +Ref: cycle step packet2023818 +Ref: write register packet2026764 +Ref: step with signal packet2027708 +Ref: vCont packet2029112 +Ref: vCtrlC packet2032291 +Ref: vKill packet2034604 +Ref: x packet2036062 +Ref: X packet2037099 +Ref: insert breakpoint or watchpoint packet2037433 +Node: Stop Reply Packets2041424 +Ref: swbreak stop reason2044675 +Ref: thread clone event2048208 +Ref: thread create event2048588 +Ref: thread exit event2049791 +Node: General Query Packets2052039 +Ref: qCRC packet2054869 +Ref: QEnvironmentHexEncoded2057661 +Ref: QEnvironmentUnset2058891 +Ref: QEnvironmentReset2059835 +Ref: QSetWorkingDir packet2060779 +Ref: qMemTags2065221 +Ref: qIsAddressTagged2065963 +Ref: QMemTags2066450 +Ref: QNonStop2069561 +Ref: QCatchSyscalls2070040 +Ref: QPassSignals2071409 +Ref: QProgramSignals2072415 +Ref: QThreadEvents2073778 +Ref: QThreadOptions2074878 +Ref: qSearch memory2078994 +Ref: QStartNoAckMode2079301 +Ref: qSupported2079725 +Ref: error-message2084217 +Ref: multiprocess extensions2096276 +Ref: install tracepoint in tracing2098306 +Ref: qThreadExtraInfo2103375 +Ref: qXfer read2104501 +Ref: qXfer auxiliary vector read2105734 +Ref: qXfer btrace read2106082 +Ref: qXfer btrace-conf read2107147 +Ref: qXfer executable filename read2107498 +Ref: qXfer target description read2108113 +Ref: qXfer library list read2108547 +Ref: qXfer svr4 library list read2109203 +Ref: qXfer memory map read2111458 +Ref: qXfer sdata read2111845 +Ref: qXfer siginfo read2112311 +Ref: qXfer threads read2112707 +Ref: qXfer traceframe info read2113110 +Ref: qXfer unwind info block2113528 +Ref: qXfer fdpic loadmap read2113762 +Ref: qXfer osdata read2114178 +Ref: qXfer write2114332 +Ref: qXfer siginfo write2115050 +Ref: General Query Packets-Footnote-12117891 +Node: Architecture-Specific Protocol Details2119919 +Node: ARM-Specific Protocol Details2120428 +Node: ARM Breakpoint Kinds2120701 +Node: ARM Memory Tag Types2121061 +Node: MIPS-Specific Protocol Details2121360 +Node: MIPS Register packet Format2121643 +Node: MIPS Breakpoint Kinds2122570 +Node: Tracepoint Packets2122988 +Ref: QTEnable2132104 +Ref: QTDisable2132300 +Ref: qTfSTM2137837 +Ref: qTsSTM2137837 +Ref: qTSTMat2138718 +Ref: QTBuffer-size2139869 +Node: Host I/O Packets2141726 +Node: Interrupts2147667 +Ref: interrupting remote targets2147811 +Node: Notification Packets2149979 +Node: Remote Non-Stop2155406 +Node: Packet Acknowledgment2158522 +Node: Examples2160637 +Node: File-I/O Remote Protocol Extension2161231 +Node: File-I/O Overview2161693 +Node: Protocol Basics2163892 +Node: The F Request Packet2166121 +Node: The F Reply Packet2167022 +Node: The Ctrl-C Message2167940 +Node: Console I/O2169563 +Node: List of Supported Calls2170778 +Node: open2171140 +Node: close2173648 +Node: read2174031 +Node: write2174640 +Node: lseek2175411 +Node: rename2176295 +Node: unlink2177702 +Node: stat/fstat2178649 +Node: gettimeofday2179542 +Node: isatty2179978 +Node: system2180574 +Node: Protocol-specific Representation of Datatypes2182116 +Node: Integral Datatypes2182493 +Node: Pointer Values2183300 +Node: Memory Transfer2184004 +Node: struct stat2184624 +Node: struct timeval2186826 +Node: Constants2187343 +Node: Open Flags2187792 +Node: mode_t Values2188133 +Node: Errno Values2188625 +Node: Lseek Flags2189435 +Node: Limits2189620 +Node: File-I/O Examples2189980 +Node: Library List Format2191068 +Node: Library List Format for SVR4 Targets2193850 +Node: Memory Map Format2196627 +Node: Thread List Format2199151 +Node: Traceframe Info Format2200171 +Node: Branch Trace Format2201857 +Node: Branch Trace Configuration Format2203557 +Node: Agent Expressions2204836 +Node: General Bytecode Design2207657 +Node: Bytecode Descriptions2212451 +Node: Using Agent Expressions2225918 +Node: Varying Target Capabilities2227895 +Node: Rationale2229056 +Node: Target Descriptions2236445 +Node: Retrieving Descriptions2238388 +Node: Target Description Format2239473 +Node: Predefined Target Types2249348 +Node: Enum Target Types2250931 +Node: Standard Target Features2251926 +Node: AArch64 Features2253928 +Node: ARC Features2264143 +Ref: ARC Features-Footnote-12265962 +Node: ARM Features2265995 +Node: i386 Features2275626 +Node: LoongArch Features2277690 +Node: MicroBlaze Features2278253 +Node: MIPS Features2278835 +Node: M68K Features2280026 +Node: NDS32 Features2281013 +Node: OpenRISC 1000 Features2282043 +Node: PowerPC Features2282407 +Node: RISC-V Features2286377 +Node: RX Features2288220 +Node: S/390 and System z Features2288582 +Node: Sparc Features2290722 +Node: TIC6x Features2291627 +Node: Operating System Information2292176 +Node: Process list2293012 +Node: Trace File Format2294075 +Node: Index Section Format2297289 +Node: Debuginfod2305906 +Node: Debuginfod Settings2306742 +Ref: set debuginfod enabled2306921 +Node: Man Pages2308604 +Node: gdb man2309137 +Node: gdbserver man2317047 +Node: gcore man2324969 +Node: gstack man2326244 +Node: gdbinit man2327352 +Node: gdb-add-index man2328592 +Ref: gdb-add-index2328701 +Node: Copying2330546 +Node: GNU Free Documentation License2368107 +Node: Concept Index2393254 +Node: Command and Variable Index2548518 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/gdb/doc/gdb.info-1 16.3-5ubuntu1/gdb/doc/gdb.info-1 --- 16.3-5/gdb/doc/gdb.info-1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-1 2025-04-20 17:25:32.000000000 +0000 @@ -0,0 +1,6992 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Top, Next: Summary, Up: (dir) + +Debugging with GDB +****************** + +This file describes GDB, the GNU symbolic debugger. + + This is the Tenth Edition, for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + This edition of the GDB manual is dedicated to the memory of Fred +Fish. Fred was a long-standing contributor to GDB and to Free software +in general. We will miss him. + +* Menu: + +* Summary:: Summary of GDB +* Sample Session:: A sample GDB session + +* Invocation:: Getting in and out of GDB +* Commands:: GDB commands +* Running:: Running programs under GDB +* Stopping:: Stopping and continuing +* Reverse Execution:: Running programs backward +* Process Record and Replay:: Recording inferior's execution and replaying it +* Stack:: Examining the stack +* Source:: Examining source files +* Data:: Examining data +* Optimized Code:: Debugging optimized code +* Macros:: Preprocessor Macros +* Tracepoints:: Debugging remote targets non-intrusively +* Overlays:: Debugging programs that use overlays + +* Languages:: Using GDB with different languages + +* Symbols:: Examining the symbol table +* Altering:: Altering execution +* GDB Files:: GDB files +* Targets:: Specifying a debugging target +* Remote Debugging:: Debugging remote programs +* Configurations:: Configuration-specific information +* Controlling GDB:: Controlling GDB +* Extending GDB:: Extending GDB +* Interpreters:: Command Interpreters +* TUI:: GDB Text User Interface +* Emacs:: Using GDB under GNU Emacs +* GDB/MI:: GDB's Machine Interface. +* Annotations:: GDB's annotation interface. +* Debugger Adapter Protocol:: The Debugger Adapter Protocol. +* JIT Interface:: Using the JIT debugging interface. +* In-Process Agent:: In-Process Agent + +* GDB Bugs:: Reporting bugs in GDB + +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +* In Memoriam:: In Memoriam +* Formatting Documentation:: How to format and print GDB documentation +* Installing GDB:: Installing GDB +* Maintenance Commands:: Maintenance Commands +* Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The GDB Agent Expression Mechanism +* Target Descriptions:: How targets can describe themselves to + GDB +* Operating System Information:: Getting additional information from + the operating system +* Trace File Format:: GDB trace file format +* Index Section Format:: .gdb_index section format +* Debuginfod:: Download debugging resources with 'debuginfod' +* Man Pages:: Manual pages +* Copying:: GNU General Public License says + how you can copy and share GDB +* GNU Free Documentation License:: The license for this documentation +* Concept Index:: Index of GDB concepts +* Command and Variable Index:: Index of GDB commands, variables, + functions, and Python data types + + +File: gdb.info, Node: Summary, Next: Sample Session, Up: Top + +Summary of GDB +************** + +The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes--or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C and C++. For more +information, see *note Supported Languages: Supported Languages. For +more information, see *note C and C++: C. + + Support for D is partial. For information on D, see *note D: D. + + Support for Modula-2 is partial. For information on Modula-2, see +*note Modula-2: Modula-2. + + Support for OpenCL C is partial. For information on OpenCL C, see +*note OpenCL C: OpenCL C. + + Debugging Pascal programs which use sets, subranges, file variables, +or nested functions does not currently work. GDB does not support +entering expressions, printing values, or similar features using Pascal +syntax. + + GDB can be used to debug programs written in Fortran, although it may +be necessary to refer to some variables with a trailing underscore. + + GDB can be used to debug programs written in Objective-C, using +either the Apple/NeXT or the GNU Objective-C runtime. + +* Menu: + +* Free Software:: Freely redistributable software +* Free Documentation:: Free Software Needs Free Documentation +* Contributors:: Contributors to GDB + + +File: gdb.info, Node: Free Software, Next: Free Documentation, Up: Summary + +Free Software +============= + +GDB is "free software", protected by the GNU General Public License +(GPL). The GPL gives you the freedom to copy or adapt a licensed +program--but every person getting a copy also gets with it the freedom +to modify that copy (which means that they must get access to the source +code), and the freedom to distribute further copies. Typical software +companies use copyrights to limit your freedoms; the Free Software +Foundation uses the GPL to preserve these freedoms. + + Fundamentally, the General Public License is a license which says +that you have these freedoms and that you cannot take these freedoms +away from anyone else. + + +File: gdb.info, Node: Free Documentation, Next: Contributors, Prev: Free Software, Up: Summary + +Free Software Needs Free Documentation +====================================== + +The biggest deficiency in the free software community today is not in +the software--it is the lack of good free documentation that we can +include with the free software. Many of our most important programs do +not come with free reference manuals and free introductory texts. +Documentation is an essential part of any software package; when an +important free software package does not come with a free manual and a +free tutorial, that is a major gap. We have many such gaps today. + + Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms--no +copying, no modification, source files not available--which exclude them +from the free software world. + + That wasn't the first time this sort of thing happened, and it was +far from the last. Many times we have heard a GNU user eagerly describe +a manual that he is writing, his intended contribution to the community, +only to learn that he had ruined everything by signing a publication +contract to make it non-free. + + Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies--that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The problem +is the restrictions on the use of the manual. Free manuals are +available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + + The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of commercial +redistribution) must be permitted, so that the manual can accompany +every copy of the program, both on-line and on paper. + + Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too--so they can provide +accurate and clear documentation for the modified program. A manual +that leaves you no choice but to write a new manual to document a +changed version of the program is not really available to our community. + + Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original author's +copyright notice, the distribution terms, or the list of authors, are +ok. It is also no problem to require modified versions to include +notice that they were modified. Even entire sections that may not be +deleted or changed are acceptable, as long as they deal with +nontechnical topics (like this one). These kinds of restrictions are +acceptable because they don't obstruct the community's normal use of the +manual. + + However, it must be possible to modify all the _technical_ content of +the manual, and then distribute the result in all the usual media, +through all the usual channels. Otherwise, the restrictions obstruct +the use of the manual, it is not free, and we need another manual to +replace it. + + Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that free +software needs free reference manuals and free tutorials, perhaps the +next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to the +free software community. + + If you are writing documentation, please insist on publishing it +under the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval--you don't +have to let the publisher decide. Some commercial publishers will use a +free license if you insist, but they will not propose the option; it is +up to you to raise the issue and say firmly that this is what you want. +If the publisher you are dealing with refuses, please try other +publishers. If you're not sure whether a proposed license is free, +write to . + + You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying copies +from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation at +all. Check the distribution terms of a manual before you buy it, and +insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try to reward the publishers that +have paid or pay the authors to work on it. + + The Free Software Foundation maintains a list of free documentation +published by other publishers, at +. + + +File: gdb.info, Node: Contributors, Prev: Free Documentation, Up: Summary + +Contributors to GDB +=================== + +Richard Stallman was the original author of GDB, and of many other GNU +programs. Many others have contributed to its development. This +section attempts to credit major contributors. One of the virtues of +free software is that everyone is free to contribute to it; with regret, +we cannot actually acknowledge everyone here. The file 'ChangeLog' in +the GDB distribution approximates a blow-by-blow account. + + Changes much prior to version 2.0 are lost in the mists of time. + + _Plea:_ Additions to this section are particularly welcome. If you + or your friends (or enemies, to be evenhanded) have been unfairly + omitted from this list, we would like to add your names! + + So that they may not regard their many labors as thankless, we +particularly thank those who shepherded GDB through major releases: +Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); Jim +Blandy (release 4.18); Jason Molenda (release 4.17); Stan Shebs (release +4.14); Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); +Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); +John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); Jim Kingdon +(releases 3.5, 3.4, and 3.3); and Randy Smith (releases 3.2, 3.1, and +3.0). + + Richard Stallman, assisted at various times by Peter TerMaat, Chris +Hanson, and Richard Mlynarik, handled releases through 2.8. + + Michael Tiemann is the author of most of the GNU C++ support in GDB, +with significant additional contributions from Per Bothner and Daniel +Berlin. James Clark wrote the GNU C++ demangler. Early work on C++ was +by Peter TerMaat (who also did much general update work leading to +release 3.0). + + GDB uses the BFD subroutine library to examine multiple object-file +formats; BFD was a joint project of David V. Henkel-Wallace, Rich +Pixley, Steve Chamberlain, and John Gilmore. + + David Johnson wrote the original COFF support; Pace Willison did the +original support for encapsulated COFF. + + Brent Benson of Harris Computer Systems contributed DWARF 2 support. + + Adam de Boor and Bradley Davis contributed the ISI Optimum V support. +Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS +support. Jean-Daniel Fekete contributed Sun 386i support. Chris Hanson +improved the HP9000 support. Noboyuki Hikichi and Tomoyuki Hasei +contributed Sony/News OS 3 support. David Johnson contributed Encore +Umax support. Jyrki Kuoppala contributed Altos 3068 support. Jeff Law +contributed HP PA and SOM support. Keith Packard contributed NS32K +support. Doug Rabson contributed Acorn Risc Machine support. Bob Rusk +contributed Harris Nighthawk CX-UX support. Chris Smith contributed +Convex support (and Fortran debugging). Jonathan Stone contributed +Pyramid support. Michael Tiemann contributed SPARC support. Tim Tucker +contributed support for the Gould NP1 and Gould Powernode. Pace +Willison contributed Intel 386 support. Jay Vosburgh contributed +Symmetry support. Marko Mlinar contributed OpenRISC 1000 support. + + Andreas Schwab contributed M68K GNU/Linux support. + + Rich Schaefer and Peter Schauer helped with support of SunOS shared +libraries. + + Jay Fenlason and Roland McGrath ensured that GDB and GAS agree about +several machine instruction sets. + + Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped +develop remote debugging. Intel Corporation, Wind River Systems, AMD, +and ARM contributed remote debugging modules for the i960, VxWorks, A29K +UDI, and RDI targets, respectively. + + Brian Fox is the author of the readline libraries providing +command-line editing and command history. + + Andrew Beers of SUNY Buffalo wrote the language-switching code, the +Modula-2 support, and contributed the Languages chapter of this manual. + + Fred Fish wrote most of the support for Unix System Vr4. He also +enhanced the command-completion support to cover C++ overloaded symbols. + + Hitachi America (now Renesas America), Ltd. sponsored the support +for H8/300, H8/500, and Super-H processors. + + NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx +processors. + + Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and +M32R/D processors. + + Toshiba sponsored the support for the TX39 Mips processor. + + Matsushita sponsored the support for the MN10200 and MN10300 +processors. + + Fujitsu sponsored the support for SPARClite and FR30 processors. + + Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + + Michael Snyder added support for tracepoints. + + Stu Grossman wrote gdbserver. + + Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made nearly +innumerable bug fixes and cleanups throughout GDB. + + The following people at the Hewlett-Packard Company contributed +support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 +(narrow mode), HP's implementation of kernel threads, HP's aC++ +compiler, and the Text User Interface (nee Terminal User Interface): Ben +Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, Satish +Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase provided +HP-specific information in this manual. + + DJ Delorie ported GDB to MS-DOS, for the DJGPP project. Robert +Hoehne made significant contributions to the DJGPP port. + + Cygnus Solutions has sponsored GDB maintenance and much of its +development since 1991. Cygnus engineers who have worked on GDB +fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin +Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim +Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, +Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek +Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In +addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, +JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug +Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff +Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, +Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin +Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela +Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David +Zuhn have made contributions both large and small. + + Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for +Cygnus Solutions, implemented the original GDB/MI interface. + + Jim Blandy added support for preprocessor macros, while working for +Red Hat. + + Andrew Cagney designed GDB's architecture vector. Many people +including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick Duffek, +Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei Sakamoto, +Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason Thorpe, Corinna +Vinschen, Ulrich Weigand, and Elena Zannoni, helped with the migration +of old architectures to this new framework. + + Andrew Cagney completely re-designed and re-implemented GDB's +unwinder framework, this consisting of a fresh new design featuring +frame IDs, independent frame sniffers, and the sentinel frame. Mark +Kettenis implemented the DWARF 2 unwinder, Jeff Johnston the libunwind +unwinder, and Andrew Cagney the dummy, sentinel, tramp, and trad +unwinders. The architecture-specific changes, each involving a complete +rewrite of the architecture's frame code, were carried out by Jim +Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane Carrez, +Randolph Chung, Orjan Friberg, Richard Henderson, Daniel Jacobowitz, +Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei Sakamoto, Yoshinori +Sato, Michael Snyder, Corinna Vinschen, and Ulrich Weigand. + + Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from +Tensilica, Inc. contributed support for Xtensa processors. Others who +have worked on the Xtensa port of GDB in the past include Steve Tjiang, +John Newlin, and Scott Foehner. + + Michael Eager and staff of Xilinx, Inc., contributed support for the +Xilinx MicroBlaze architecture. + + Initial support for the FreeBSD/mips target and native configuration +was developed by SRI International and the University of Cambridge +Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 +("CTSRD"), as part of the DARPA CRASH research programme. + + Initial support for the FreeBSD/riscv target and native configuration +was developed by SRI International and the University of Cambridge +Computer Laboratory (Department of Computer Science and Technology) +under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA +SSITH research programme. + + The original port to the OpenRISC 1000 is believed to be due to +Alessandro Forin and Per Bothner. More recent ports have been the work +of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and Stafford +Horne. + + Weimin Pan, David Faust and Jose E. Marchesi contributed support for +the Linux kernel BPF virtual architecture. This work was sponsored by +Oracle. + + +File: gdb.info, Node: Sample Session, Next: Invocation, Prev: Summary, Up: Top + +1 A Sample GDB Session +********************** + +You can use this manual at your leisure to read all about GDB. However, +a handful of commands are enough to get started using the debugger. +This chapter illustrates those commands. + + One of the preliminary versions of GNU 'm4' (a generic macro +processor) exhibits the following bug: sometimes, when we change its +quote strings from the default, the commands used to capture one macro +definition within another stop working. In the following short 'm4' +session, we define a macro 'foo' which expands to '0000'; we then use +the 'm4' built-in 'defn' to define 'bar' as the same thing. However, +when we change the open quote string to '' and the close quote +string to '', the same procedure fails to define a new synonym +'baz': + + $ cd gnu/m4 + $ ./m4 + define(foo,0000) + + foo + 0000 + define(bar,defn('foo')) + + bar + 0000 + changequote(,) + + define(baz,defn(foo)) + baz + Ctrl-d + m4: End of input: 0: fatal error: EOF in string + +Let us use GDB to try to see what is going on. + + $ gdb m4 + GDB is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. + There is absolutely no warranty for GDB; type "show warranty" + for details. + + GDB 16.3, Copyright 1999 Free Software Foundation, Inc... + (gdb) + +GDB reads only enough symbol data to know where to find the rest when +needed; as a result, the first prompt comes up very quickly. We now +tell GDB to use a narrower display width than usual, so that examples +fit in this manual. + + (gdb) set width 70 + +We need to see how the 'm4' built-in 'changequote' works. Having looked +at the source, we know the relevant subroutine is 'm4_changequote', so +we set a breakpoint there with the GDB 'break' command. + + (gdb) break m4_changequote + Breakpoint 1 at 0x62f4: file builtin.c, line 879. + +Using the 'run' command, we start 'm4' running under GDB control; as +long as control does not reach the 'm4_changequote' subroutine, the +program runs as usual: + + (gdb) run + Starting program: /work/Editorial/gdb/gnu/m4/m4 + define(foo,0000) + + foo + 0000 + +To trigger the breakpoint, we call 'changequote'. GDB suspends +execution of 'm4', displaying information about the context where it +stops. + + changequote(,) + + Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) + at builtin.c:879 + 879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) + +Now we use the command 'n' ('next') to advance execution to the next +line of the current function. + + (gdb) n + 882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ + : nil, + +'set_quotes' looks like a promising subroutine. We can go into it by +using the command 's' ('step') instead of 'next'. 'step' goes to the +next line to be executed in _any_ subroutine, so it steps into +'set_quotes'. + + (gdb) s + set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + 530 if (lquote != def_lquote) + +The display that shows the subroutine where 'm4' is now suspended (and +its arguments) is called a stack frame display. It shows a summary of +the stack. We can use the 'backtrace' command (which can also be +spelled 'bt'), to see where we are in the stack as a whole: the +'backtrace' command displays a stack frame for each active subroutine. + + (gdb) bt + #0 set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 + #1 0x6344 in m4_changequote (argc=3, argv=0x33c70) + at builtin.c:882 + #2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 + #3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) + at macro.c:71 + #4 0x79dc in expand_input () at macro.c:40 + #5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 + +We step through a few more lines to see what happens. The first two +times, we can use 's'; the next two times we use 'n' to avoid falling +into the 'xstrdup' subroutine. + + (gdb) s + 0x3b5c 532 if (rquote != def_rquote) + (gdb) s + 0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ + def_lquote : xstrdup(lq); + (gdb) n + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup(rq); + (gdb) n + 538 len_lquote = strlen(rquote); + +The last line displayed looks a little odd; we can examine the variables +'lquote' and 'rquote' to see if they are in fact the new left and right +quotes we specified. We use the command 'p' ('print') to see their +values. + + (gdb) p lquote + $1 = 0x35d40 "" + (gdb) p rquote + $2 = 0x35d50 "" + +'lquote' and 'rquote' are indeed the new left and right quotes. To look +at some context, we can display ten lines of source surrounding the +current line with the 'l' ('list') command. + + (gdb) l + 533 xfree(rquote); + 534 + 535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ + : xstrdup (lq); + 536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup (rq); + 537 + 538 len_lquote = strlen(rquote); + 539 len_rquote = strlen(lquote); + 540 } + 541 + 542 void + +Let us step past the two lines that set 'len_lquote' and 'len_rquote', +and then examine the values of those variables. + + (gdb) n + 539 len_rquote = strlen(lquote); + (gdb) n + 540 } + (gdb) p len_lquote + $3 = 9 + (gdb) p len_rquote + $4 = 7 + +That certainly looks wrong, assuming 'len_lquote' and 'len_rquote' are +meant to be the lengths of 'lquote' and 'rquote' respectively. We can +set them to better values using the 'p' command, since it can print the +value of any expression--and that expression can include subroutine +calls and assignments. + + (gdb) p len_lquote=strlen(lquote) + $5 = 7 + (gdb) p len_rquote=strlen(rquote) + $6 = 9 + +Is that enough to fix the problem of using the new quotes with the 'm4' +built-in 'defn'? We can allow 'm4' to continue executing with the 'c' +('continue') command, and then try the example that caused trouble +initially: + + (gdb) c + Continuing. + + define(baz,defn(foo)) + + baz + 0000 + +Success! The new quotes now work just as well as the default ones. The +problem seems to have been just the two typos defining the wrong +lengths. We allow 'm4' exit by giving it an EOF as input: + + Ctrl-d + Program exited normally. + +The message 'Program exited normally.' is from GDB; it indicates 'm4' +has finished executing. We can end our GDB session with the GDB 'quit' +command. + + (gdb) quit + + +File: gdb.info, Node: Invocation, Next: Commands, Prev: Sample Session, Up: Top + +2 Getting In and Out of GDB +*************************** + +This chapter discusses how to start GDB, and how to get out of it. The +essentials are: + * type 'gdb' to start GDB. + * type 'quit', 'exit' or 'Ctrl-d' to exit. + +* Menu: + +* Invoking GDB:: How to start GDB +* Quitting GDB:: How to quit GDB +* Shell Commands:: How to use shell commands inside GDB +* Logging Output:: How to log GDB's output to a file + + +File: gdb.info, Node: Invoking GDB, Next: Quitting GDB, Up: Invocation + +2.1 Invoking GDB +================ + +Invoke GDB by running the program 'gdb'. Once started, GDB reads +commands from the terminal until you tell it to exit. + + You can also run 'gdb' with a variety of arguments and options, to +specify more of your debugging environment at the outset. + + The command-line options described here are designed to cover a +variety of situations; in some environments, some of these options may +effectively be unavailable. + + The most usual way to start GDB is with one argument, specifying an +executable program: + + gdb PROGRAM + +You can also start with both an executable program and a core file +specified: + + gdb PROGRAM CORE + + You can, instead, specify a process ID as a second argument or use +option '-p', if you want to debug a running process: + + gdb PROGRAM 1234 + gdb -p 1234 + +would attach GDB to process '1234'. With option '-p' you can omit the +PROGRAM filename. + + Taking advantage of the second command-line argument requires a +fairly complete operating system; when you use GDB as a remote debugger +attached to a bare board, there may not be any notion of "process", and +there is often no way to get a core dump. GDB will warn you if it is +unable to attach or to read core dumps. + + You can optionally have 'gdb' pass any arguments after the executable +file to the inferior using '--args'. This option stops option +processing. + gdb --args gcc -O2 -c foo.c + This will cause 'gdb' to debug 'gcc', and to set 'gcc''s command-line +arguments (*note Arguments::) to '-O2 -c foo.c'. + + You can run 'gdb' without printing the front material, which +describes GDB's non-warranty, by specifying '--silent' (or +'-q'/'--quiet'): + + gdb --silent + +You can further control how GDB starts up by using command-line options. +GDB itself can remind you of the options available. + +Type + + gdb -help + +to display all available options and briefly describe their use ('gdb +-h' is a shorter equivalent). + + All options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +* Menu: + +* File Options:: Choosing files +* Mode Options:: Choosing modes +* Startup:: What GDB does during startup +* Initialization Files:: Initialization Files + + +File: gdb.info, Node: File Options, Next: Mode Options, Up: Invoking GDB + +2.1.1 Choosing Files +-------------------- + +When GDB starts, it reads any arguments other than options as specifying +an executable file and core file (or process ID). This is the same as if +the arguments were specified by the '-se' and '-c' (or '-p') options +respectively. (GDB reads the first argument that does not have an +associated option flag as equivalent to the '-se' option followed by +that argument; and the second argument that does not have an associated +option flag, if any, as equivalent to the '-c'/'-p' option followed by +that argument.) If the second argument begins with a decimal digit, GDB +will first attempt to attach to it as a process, and if that fails, +attempt to open it as a corefile. If you have a corefile whose name +begins with a digit, you can prevent GDB from treating it as a pid by +prefixing it with './', e.g. './12345'. + + If GDB has not been configured to included core file support, such as +for most embedded targets, then it will complain about a second argument +and ignore it. + + For the '-s', '-e', and '-se' options, and their long form +equivalents, the method used to search the file system for the symbol +and/or executable file is the same as that used by the 'file' command. +*Note file: Files. + + Many options have both long and short forms; both are shown in the +following list. GDB also recognizes the long forms if you truncate +them, so long as enough of the option is present to be unambiguous. (If +you prefer, you can flag option arguments with '--' rather than '-', +though we illustrate the more usual convention.) + +'-symbols FILE' +'-s FILE' + Read symbol table from file FILE. + +'-exec FILE' +'-e FILE' + Use file FILE as the executable file to execute when appropriate, + and for examining pure data in conjunction with a core dump. + +'-se FILE' + Read symbol table from file FILE and use it as the executable file. + +'-core FILE' +'-c FILE' + Use file FILE as a core dump to examine. + +'-pid NUMBER' +'-p NUMBER' + Connect to process ID NUMBER, as with the 'attach' command. + +'-command FILE' +'-x FILE' + Execute commands from file FILE. The contents of this file is + evaluated exactly as the 'source' command would. *Note Command + files: Command Files. + +'-eval-command COMMAND' +'-ex COMMAND' + Execute a single GDB command. + + This option may be used multiple times to call multiple commands. + It may also be interleaved with '-command' as required. + + gdb -ex 'target sim' -ex 'load' \ + -x setbreakpoints -ex 'run' a.out + +'-init-command FILE' +'-ix FILE' + Execute commands from file FILE before loading the inferior (but + after loading gdbinit files). *Note Startup::. + +'-init-eval-command COMMAND' +'-iex COMMAND' + Execute a single GDB command before loading the inferior (but after + loading gdbinit files). *Note Startup::. + +'-early-init-command FILE' +'-eix FILE' + Execute commands from FILE very early in the initialization + process, before any output is produced. *Note Startup::. + +'-early-init-eval-command COMMAND' +'-eiex COMMAND' + Execute a single GDB command very early in the initialization + process, before any output is produced. + +'-directory DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source and script files. + +'-r' +'-readnow' + Read each symbol file's entire symbol table immediately, rather + than the default, which is to read it incrementally as it is + needed. This makes startup slower, but makes future operations + faster. + +'--readnever' + Do not read each symbol file's symbolic debug information. This + makes startup faster but at the expense of not being able to + perform symbolic debugging. DWARF unwind information is also not + read, meaning backtraces may become incomplete or inaccurate. One + use of this is when a user simply wants to do the following + sequence: attach, dump core, detach. Loading the debugging + information in this case is an unnecessary cause of delay. + + +File: gdb.info, Node: Mode Options, Next: Startup, Prev: File Options, Up: Invoking GDB + +2.1.2 Choosing Modes +-------------------- + +You can run GDB in various alternative modes--for example, in batch mode +or quiet mode. + +'-nx' +'-n' + Do not execute commands found in any initialization files (*note + Initialization Files::). + +'-nh' + Do not execute commands found in any home directory initialization + file (*note Home directory initialization file: Initialization + Files.). The system wide and current directory initialization + files are still loaded. + +'-quiet' +'-silent' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + + This can also be enabled using 'set startup-quietly on'. The + default is 'off'. Use 'show startup-quietly' to see the current + setting. Place 'set startup-quietly on' into your early + initialization file (*note Initialization Files: Initialization + Files.) to have future GDB sessions startup quietly. + +'-batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and all commands from + initialization files, if not inhibited with '-n'). Exit with + nonzero status if an error occurs in executing the GDB commands in + the command files. Batch mode also disables pagination, sets + unlimited terminal width and height *note Screen Size::, and acts + as if 'set confirm off' were in effect (*note Messages/Warnings::). + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'-batch-silent' + Run in batch mode exactly like '-batch', but totally silently. All + GDB output to 'stdout' is prevented ('stderr' is unaffected). This + is much quieter than '-silent' and would be useless for an + interactive session. + + This is particularly useful when using targets that give 'Loading + section' messages, for example. + + Note that targets that give their output via GDB, as opposed to + writing directly to 'stdout', will also be made silent. + +'-return-child-result' + The return code from GDB will be the return code from the child + process (the process being debugged), with the following + exceptions: + + * GDB exits abnormally. E.g., due to an incorrect argument or + an internal error. In this case the exit code is the same as + it would have been without '-return-child-result'. + * The user quits with an explicit value. E.g., 'quit 1'. + * The child process never runs, or is not allowed to terminate, + in which case the exit code will be -1. + + This option is useful in conjunction with '-batch' or + '-batch-silent', when GDB is being used as a remote program loader + or simulator interface. + +'-nowindows' +'-nw' + "No windows". If GDB comes with a graphical user interface (GUI) + built in, then this option tells GDB to only use the command-line + interface. If no GUI is available, this option has no effect. + +'-windows' +'-w' + If GDB includes a GUI, then this option requires it to be used if + possible. + +'-cd DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'-data-directory DIRECTORY' +'-D DIRECTORY' + Run GDB using DIRECTORY as its data directory. The data directory + is where GDB searches for its auxiliary files. *Note Data Files::. + +'-fullname' +'-f' + GNU Emacs sets this option when it runs GDB as a subprocess. It + tells GDB to output the full file name and line number in a + standard, recognizable fashion each time a stack frame is displayed + (which includes each time your program stops). This recognizable + format looks like two '\032' characters, followed by the file name, + line number and character position separated by colons, and a + newline. The Emacs-to-GDB interface program uses the two '\032' + characters as a signal to display the source code for the frame. + +'-annotate LEVEL' + This option sets the "annotation level" inside GDB. Its effect is + identical to using 'set annotate LEVEL' (*note Annotations::). The + annotation LEVEL controls how much information GDB prints together + with its prompt, values of expressions, source lines, and other + types of output. Level 0 is the normal, level 1 is for use when + GDB is run as a subprocess of GNU Emacs, level 3 is the maximum + annotation suitable for programs that control GDB, and level 2 has + been deprecated. + + The annotation mechanism has largely been superseded by GDB/MI + (*note GDB/MI::). + +'--args' + Change interpretation of command line so that arguments following + the executable file are passed as command line arguments to the + inferior. This option stops option processing. + +'-baud BPS' +'-b BPS' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-l TIMEOUT' + Set the timeout (in seconds) of any communication used by GDB for + remote debugging. + +'-tty DEVICE' +'-t DEVICE' + Run using DEVICE for your program's standard input and output. + +'-tui' + Activate the "Text User Interface" when starting. The Text User + Interface manages several text windows on the terminal, showing + source, assembly, registers and GDB command outputs (*note GDB Text + User Interface: TUI.). Do not use this option if you run GDB from + Emacs (*note Using GDB under GNU Emacs: Emacs.). + +'-interpreter INTERP' + Use the interpreter INTERP for interface with the controlling + program or device. This option is meant to be set by programs + which communicate with GDB using it as a back end. *Note Command + Interpreters: Interpreters. + + '--interpreter=mi' (or '--interpreter=mi3') causes GDB to use the + "GDB/MI interface" version 3 (*note The GDB/MI Interface: GDB/MI.) + included since GDB version 9.1. GDB/MI version 2 ('mi2'), included + in GDB 6.0 and version 1 ('mi1'), included in GDB 5.3, are also + available. Earlier GDB/MI interfaces are no longer supported. + +'-write' + Open the executable and core files for both reading and writing. + This is equivalent to the 'set write on' command inside GDB (*note + Patching::). + +'-statistics' + This option causes GDB to print statistics about time and memory + usage after it completes each command and returns to the prompt. + +'-version' + This option causes GDB to print its version number and no-warranty + blurb, and exit. + +'-configuration' + This option causes GDB to print details about its build-time + configuration parameters, and then exit. These details can be + important when reporting GDB bugs (*note GDB Bugs::). + + +File: gdb.info, Node: Startup, Next: Initialization Files, Prev: Mode Options, Up: Invoking GDB + +2.1.3 What GDB Does During Startup +---------------------------------- + +Here's the description of what GDB does during session startup: + + 1. Performs minimal setup required to initialize basic internal state. + + 2. Reads commands from the early initialization file (if any) in your + home directory. Only a restricted set of commands can be placed + into an early initialization file, see *note Initialization + Files::, for details. + + 3. Executes commands and command files specified by the '-eiex' and + '-eix' command line options in their specified order. Only a + restricted set of commands can be used with '-eiex' and 'eix', see + *note Initialization Files::, for details. + + 4. Sets up the command interpreter as specified by the command line + (*note interpreter: Mode Options.). + + 5. Reads the system wide initialization file and the files from the + system wide initialization directory, *note System Wide Init + Files::. + + 6. Reads the initialization file (if any) in your home directory and + executes all the commands in that file, *note Home Directory Init + File::. + + 7. Executes commands and command files specified by the '-iex' and + '-ix' options in their specified order. Usually you should use the + '-ex' and '-x' options instead, but this way you can apply settings + before GDB init files get executed and before inferior gets loaded. + + 8. Processes command line options and operands. + + 9. Reads and executes the commands from the initialization file (if + any) in the current working directory as long as 'set auto-load + local-gdbinit' is set to 'on' (*note Init File in the Current + Directory::). This is only done if the current directory is + different from your home directory. Thus, you can have more than + one init file, one generic in your home directory, and another, + specific to the program you are debugging, in the directory where + you invoke GDB. *Note Init File in the Current Directory during + Startup::. + + 10. If the command line specified a program to debug, or a process to + attach to, or a core file, GDB loads any auto-loaded scripts + provided for the program or for its loaded shared libraries. *Note + Auto-loading::. + + If you wish to disable the auto-loading during startup, you must do + something like the following: + + $ gdb -iex "set auto-load python-scripts off" myprogram + + Option '-ex' does not work because the auto-loading is then turned + off too late. + + 11. Executes commands and command files specified by the '-ex' and + '-x' options in their specified order. *Note Command Files::, for + more details about GDB command files. + + 12. Reads the command history recorded in the "history file". *Note + Command History::, for more details about the command history and + the files where GDB records it. + + +File: gdb.info, Node: Initialization Files, Prev: Startup, Up: Invoking GDB + +2.1.4 Initialization Files +-------------------------- + +During startup (*note Startup::) GDB will execute commands from several +initialization files. These initialization files use the same syntax as +"command files" (*note Command Files::) and are processed by GDB in the +same way. + + To display the list of initialization files loaded by GDB at startup, +in the order they will be loaded, you can use 'gdb --help'. + + The "early initialization" file is loaded very early in GDB's +initialization process, before the interpreter (*note Interpreters::) +has been initialized, and before the default target (*note Targets::) is +initialized. Only 'set' or 'source' commands should be placed into an +early initialization file, and the only 'set' commands that can be used +are those that control how GDB starts up. + + Commands that can be placed into an early initialization file will be +documented as such throughout this manual. Any command that is not +documented as being suitable for an early initialization file should +instead be placed into a general initialization file. Command files +passed to '--early-init-command' or '-eix' are also early initialization +files, with the same command restrictions. Only commands that can +appear in an early initialization file should be passed to +'--early-init-eval-command' or '-eiex'. + + In contrast, the "general initialization" files are processed later, +after GDB has finished its own internal initialization process, any +valid command can be used in these files. + + Throughout the rest of this document the term "initialization file" +refers to one of the general initialization files, not the early +initialization file. Any discussion of the early initialization file +will specifically mention that it is the early initialization file being +discussed. + + As the system wide and home directory initialization files are +processed before most command line options, changes to settings (e.g. +'set complaints') can affect subsequent processing of command line +options and operands. + + The following sections describe where GDB looks for the early +initialization and initialization files, and the order that the files +are searched for. + +2.1.4.1 Home directory early initialization files +................................................. + +GDB initially looks for an early initialization file in the users home +directory(1). There are a number of locations that GDB will search in +the home directory, these locations are searched in order and GDB will +load the first file that it finds, and subsequent locations will not be +checked. + + On non-macOS hosts the locations searched are: + * The file 'gdb/gdbearlyinit' within the directory pointed to by the + environment variable 'XDG_CONFIG_HOME', if it is defined. + * The file '.config/gdb/gdbearlyinit' within the directory pointed to + by the environment variable 'HOME', if it is defined. + * The file '.gdbearlyinit' within the directory pointed to by the + environment variable 'HOME', if it is defined. + + By contrast, on macOS hosts the locations searched are: + * The file 'Library/Preferences/gdb/gdbearlyinit' within the + directory pointed to by the environment variable 'HOME', if it is + defined. + * The file '.gdbearlyinit' within the directory pointed to by the + environment variable 'HOME', if it is defined. + + It is possible to prevent the home directory early initialization +file from being loaded using the '-nx' or '-nh' command line options, +*note Choosing Modes: Mode Options. + +2.1.4.2 System wide initialization files +........................................ + +There are two locations that are searched for system wide initialization +files. Both of these locations are always checked: + +'system.gdbinit' + This is a single system-wide initialization file. Its location is + specified with the '--with-system-gdbinit' configure option (*note + System-wide configuration::). It is loaded first when GDB starts, + before command line options have been processed. + +'system.gdbinit.d' + This is the system-wide initialization directory. Its location is + specified with the '--with-system-gdbinit-dir' configure option + (*note System-wide configuration::). Files in this directory are + loaded in alphabetical order immediately after 'system.gdbinit' (if + enabled) when GDB starts, before command line options have been + processed. Files need to have a recognized scripting language + extension ('.py'/'.scm') or be named with a '.gdb' extension to be + interpreted as regular GDB commands. GDB will not recurse into any + subdirectories of this directory. + + It is possible to prevent the system wide initialization files from +being loaded using the '-nx' command line option, *note Choosing Modes: +Mode Options. + +2.1.4.3 Home directory initialization file +.......................................... + +After loading the system wide initialization files GDB will look for an +initialization file in the users home directory(2). There are a number +of locations that GDB will search in the home directory, these locations +are searched in order and GDB will load the first file that it finds, +and subsequent locations will not be checked. + + On non-Apple hosts the locations searched are: +'$XDG_CONFIG_HOME/gdb/gdbinit' +'$HOME/.config/gdb/gdbinit' +'$HOME/.gdbinit' + + While on Apple hosts the locations searched are: +'$HOME/Library/Preferences/gdb/gdbinit' +'$HOME/.gdbinit' + + It is possible to prevent the home directory initialization file from +being loaded using the '-nx' or '-nh' command line options, *note +Choosing Modes: Mode Options. + + The DJGPP port of GDB uses the name 'gdb.ini' instead of '.gdbinit' +or 'gdbinit', due to the limitations of file names imposed by DOS +filesystems. The Windows port of GDB uses the standard name, but if it +finds a 'gdb.ini' file in your home directory, it warns you about that +and suggests to rename the file to the standard name. + +2.1.4.4 Local directory initialization file +........................................... + +GDB will check the current directory for a file called '.gdbinit'. It +is loaded last, after command line options other than '-x' and '-ex' +have been processed. The command line options '-x' and '-ex' are +processed last, after '.gdbinit' has been loaded, *note Choosing Files: +File Options. + + If the file in the current directory was already loaded as the home +directory initialization file then it will not be loaded a second time. + + It is possible to prevent the local directory initialization file +from being loaded using the '-nx' command line option, *note Choosing +Modes: Mode Options. + + ---------- Footnotes ---------- + + (1) On DOS/Windows systems, the home directory is the one pointed to +by the 'HOME' environment variable. + + (2) On DOS/Windows systems, the home directory is the one pointed to +by the 'HOME' environment variable. + + +File: gdb.info, Node: Quitting GDB, Next: Shell Commands, Prev: Invoking GDB, Up: Invocation + +2.2 Quitting GDB +================ + +'quit [EXPRESSION]' +'exit [EXPRESSION]' +'q' + To exit GDB, use the 'quit' command (abbreviated 'q'), the 'exit' + command, or type an end-of-file character (usually 'Ctrl-d'). If + you do not supply EXPRESSION, GDB will terminate normally; + otherwise it will terminate using the result of EXPRESSION as the + error code. + + An interrupt (often 'Ctrl-c') does not exit from GDB, but rather +terminates the action of any GDB command that is in progress and returns +to GDB command level. It is safe to type the interrupt character at any +time because GDB does not allow it to take effect until a time when it +is safe. + + If you have been using GDB to control an attached process or device, +you can release it with the 'detach' command (*note Debugging an +Already-running Process: Attach.). + + +File: gdb.info, Node: Shell Commands, Next: Logging Output, Prev: Quitting GDB, Up: Invocation + +2.3 Shell Commands +================== + +If you need to execute occasional shell commands during your debugging +session, there is no need to leave or suspend GDB; you can just use the +'shell' command. + +'shell COMMAND-STRING' +'!COMMAND-STRING' + Invoke a shell to execute COMMAND-STRING. Note that no space is + needed between '!' and COMMAND-STRING. On GNU and Unix systems, + the environment variable 'SHELL', if it exists, determines which + shell to run. Otherwise GDB uses the default shell ('/bin/sh' on + GNU and Unix systems, 'cmd.exe' on MS-Windows, 'COMMAND.COM' on + MS-DOS, etc.). + + You may also invoke shell commands from expressions, using the +'$_shell' convenience function. *Note $_shell convenience function::. + + The utility 'make' is often needed in development environments. You +do not have to use the 'shell' command for this purpose in GDB: + +'make MAKE-ARGS' + Execute the 'make' program with the specified arguments. This is + equivalent to 'shell make MAKE-ARGS'. + +'pipe [COMMAND] | SHELL_COMMAND' +'| [COMMAND] | SHELL_COMMAND' +'pipe -d DELIM COMMAND DELIM SHELL_COMMAND' +'| -d DELIM COMMAND DELIM SHELL_COMMAND' + Executes COMMAND and sends its output to SHELL_COMMAND. Note that + no space is needed around '|'. If no COMMAND is provided, the last + command executed is repeated. + + In case the COMMAND contains a '|', the option '-d DELIM' can be + used to specify an alternate delimiter string DELIM that separates + the COMMAND from the SHELL_COMMAND. + + Example: + (gdb) p var + $1 = { + black = 144, + red = 233, + green = 377, + blue = 610, + white = 987 + } + (gdb) pipe p var|wc + 7 19 80 + (gdb) |p var|wc -l + 7 + (gdb) p /x var + $4 = { + black = 0x90, + red = 0xe9, + green = 0x179, + blue = 0x262, + white = 0x3db + } + (gdb) ||grep red + red => 0xe9, + (gdb) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' + this contains a PIPE char + (gdb) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' + this contains a PIPE char! + (gdb) + + The convenience variables '$_shell_exitcode' and '$_shell_exitsignal' +can be used to examine the exit status of the last shell command +launched by 'shell', 'make', 'pipe' and '|'. *Note Convenience +Variables: Convenience Vars. + + +File: gdb.info, Node: Logging Output, Prev: Shell Commands, Up: Invocation + +2.4 Logging Output +================== + +You may want to save the output of GDB commands to a file. There are +several commands to control GDB's logging. + +'set logging enabled [on|off]' + Enable or disable logging. +'set logging file FILE' + Change the name of the current logfile. The default logfile is + 'gdb.txt'. +'set logging overwrite [on|off]' + By default, GDB will append to the logfile. Set 'overwrite' if you + want 'set logging enabled on' to overwrite the logfile instead. +'set logging redirect [on|off]' + By default, GDB output will go to both the terminal and the + logfile. Set 'redirect' if you want output to go only to the log + file. +'set logging debugredirect [on|off]' + By default, GDB debug output will go to both the terminal and the + logfile. Set 'debugredirect' if you want debug output to go only + to the log file. +'show logging' + Show the current values of the logging settings. + + You can also redirect the output of a GDB command to a shell command. +*Note pipe::. + + +File: gdb.info, Node: Commands, Next: Running, Prev: Invocation, Up: Top + +3 GDB Commands +************** + +You can abbreviate a GDB command to the first few letters of the command +name, if that abbreviation is unambiguous; and you can repeat certain +GDB commands by typing just . You can also use the key to +get GDB to fill out the rest of a word in a command (or to show you the +alternatives available, if there is more than one possibility). + +* Menu: + +* Command Syntax:: How to give commands to GDB +* Command Settings:: How to change default behavior of commands +* Completion:: Command completion +* Filename Arguments:: Filenames As Command Arguments +* Command Options:: Command options +* Help:: How to ask GDB for help + + +File: gdb.info, Node: Command Syntax, Next: Command Settings, Up: Commands + +3.1 Command Syntax +================== + +A GDB command is a single line of input. There is no limit on how long +it can be. It starts with a command name, which is followed by +arguments whose meaning depends on the command name. For example, the +command 'step' accepts an argument which is the number of times to step, +as in 'step 5'. You can also use the 'step' command with no arguments. +Some commands do not allow any arguments. + + GDB command names may always be truncated if that abbreviation is +unambiguous. Other possible command abbreviations are listed in the +documentation for individual commands. In some cases, even ambiguous +abbreviations are allowed; for example, 's' is specially defined as +equivalent to 'step' even though there are other commands whose names +start with 's'. You can test abbreviations by using them as arguments +to the 'help' command. + + A blank line as input to GDB (typing just ) means to repeat the +previous command. Certain commands (for example, 'run') will not repeat +this way; these are commands whose unintentional repetition might cause +trouble and which you are unlikely to want to repeat. User-defined +commands can disable this feature; see *note dont-repeat: Define. + + The 'list' and 'x' commands, when you repeat them with , +construct new arguments rather than repeating exactly as typed. This +permits easy scanning of source or memory. + + GDB can also use in another way: to partition lengthy output, +in a way similar to the common utility 'more' (*note Screen Size: Screen +Size.). Since it is easy to press one too many in this situation, +GDB disables command repetition after any command that generates this +sort of display. + + Any text from a '#' to the end of the line is a comment; it does +nothing. This is useful mainly in command files (*note Command Files: +Command Files.). + + The 'Ctrl-o' binding is useful for repeating a complex sequence of +commands. This command accepts the current line, like , and then +fetches the next line relative to the current line from the history for +editing. + + +File: gdb.info, Node: Command Settings, Next: Completion, Prev: Command Syntax, Up: Commands + +3.2 Command Settings +==================== + +Many commands change their behavior according to command-specific +variables or settings. These settings can be changed with the 'set' +subcommands. For example, the 'print' command (*note Examining Data: +Data.) prints arrays differently depending on settings changeable with +the commands 'set print elements NUMBER-OF-ELEMENTS' and 'set print +array-indexes', among others. + + You can change these settings to your preference in the gdbinit files +loaded at GDB startup. *Note Startup::. + + The settings can also be changed interactively during the debugging +session. For example, to change the limit of array elements to print, +you can do the following: + (gdb) set print elements 10 + (gdb) print some_array + $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...} + + The above 'set print elements 10' command changes the number of +elements to print from the default of 200 to 10. If you only intend +this limit of 10 to be used for printing 'some_array', then you must +restore the limit back to 200, with 'set print elements 200'. + + Some commands allow overriding settings with command options. For +example, the 'print' command supports a number of options that allow +overriding relevant global print settings as set by 'set print' +subcommands. *Note print options::. The example above could be +rewritten as: + (gdb) print -elements 10 -- some_array + $1 = {0, 10, 20, 30, 40, 50, 60, 70, 80, 90...} + + Alternatively, you can use the 'with' command to change a setting +temporarily, for the duration of a command invocation. + +'with SETTING [VALUE] [-- COMMAND]' +'w SETTING [VALUE] [-- COMMAND]' + Temporarily set SETTING to VALUE for the duration of COMMAND. + + SETTING is any setting you can change with the 'set' subcommands. + VALUE is the value to assign to 'setting' while running 'command'. + + If no COMMAND is provided, the last command executed is repeated. + + If a COMMAND is provided, it must be preceded by a double dash + ('--') separator. This is required because some settings accept + free-form arguments, such as expressions or filenames. + + For example, the command + (gdb) with print array on -- print some_array + is equivalent to the following 3 commands: + (gdb) set print array on + (gdb) print some_array + (gdb) set print array off + + The 'with' command is particularly useful when you want to override + a setting while running user-defined commands, or commands defined + in Python or Guile. *Note Extending GDB: Extending GDB. + + (gdb) with print pretty on -- my_complex_command + + To change several settings for the same command, you can nest + 'with' commands. For example, 'with language ada -- with print + elements 10' temporarily changes the language to Ada and sets a + limit of 10 elements to print for arrays and strings. + + +File: gdb.info, Node: Completion, Next: Filename Arguments, Prev: Command Settings, Up: Commands + +3.3 Command Completion +====================== + +GDB can fill in the rest of a word in a command for you, if there is +only one possibility; it can also show you what the valid possibilities +are for the next word in a command, at any time. This works for GDB +commands, GDB subcommands, command options, and the names of symbols in +your program. + + Press the key whenever you want GDB to fill out the rest of a +word. If there is only one possibility, GDB fills in the word, and +waits for you to finish the command (or press to enter it). For +example, if you type + + (gdb) info bre + +GDB fills in the rest of the word 'breakpoints', since that is the only +'info' subcommand beginning with 'bre': + + (gdb) info breakpoints + +You can either press at this point, to run the 'info breakpoints' +command, or backspace and enter something else, if 'breakpoints' does +not look like the command you expected. (If you were sure you wanted +'info breakpoints' in the first place, you might as well just type +immediately after 'info bre', to exploit command abbreviations rather +than command completion). + + If there is more than one possibility for the next word when you +press , GDB sounds a bell. You can either supply more characters +and try again, or just press a second time; GDB displays all the +possible completions for that word. For example, you might want to set +a breakpoint on a subroutine whose name begins with 'make_', but when +you type 'b make_' GDB just sounds the bell. Typing again +displays all the function names in your program that begin with those +characters, for example: + + (gdb) b make_ +GDB sounds bell; press again, to see: + make_a_section_from_file make_environ + make_abs_section make_function_type + make_blockvector make_pointer_type + make_cleanup make_reference_type + make_command make_symbol_completion_list + (gdb) b make_ + +After displaying the available possibilities, GDB copies your partial +input ('b make_' in the example) so you can finish the command. + + If the command you are trying to complete expects either a keyword or +a number to follow, then 'NUMBER' will be shown among the available +completions, for example: + + (gdb) print -elements + NUMBER unlimited + (gdb) print -elements + +Here, the option expects a number (e.g., '100'), not literal 'NUMBER'. +Such metasyntactical arguments are always presented in uppercase. + + If you just want to see the list of alternatives in the first place, +you can press 'M-?' rather than pressing twice. 'M-?' means +' ?'. You can type this either by holding down a key designated +as the shift on your keyboard (if there is one) while typing '?', +or as followed by '?'. + + If the number of possible completions is large, GDB will print as +much of the list as it has collected, as well as a message indicating +that the list may be truncated. + + (gdb) b m + main + <... the rest of the possible completions ...> + *** List may be truncated, max-completions reached. *** + (gdb) b m + +This behavior can be controlled with the following commands: + +'set max-completions LIMIT' +'set max-completions unlimited' + Set the maximum number of completion candidates. GDB will stop + looking for more completions once it collects this many candidates. + This is useful when completing on things like function names as + collecting all the possible candidates can be time consuming. The + default value is 200. A value of zero disables tab-completion. + Note that setting either no limit or a very large limit can make + completion slow. +'show max-completions' + Show the maximum number of candidates that GDB will collect and + show during completion. + + Sometimes the string you need, while logically a "word", may contain +parentheses or other characters that GDB normally excludes from its +notion of a word. To permit word completion to work in this situation, +you may enclose words in ''' (single quote marks) in GDB commands. + + A likely situation where you might need this is in typing an +expression that involves a C++ symbol name with template parameters. +This is because when completing expressions, GDB treats the '<' +character as word delimiter, assuming that it's the less-than comparison +operator (*note C and C++ Operators: C Operators.). + + For example, when you want to call a C++ template function +interactively using the 'print' or 'call' commands, you may need to +distinguish whether you mean the version of 'name' that was specialized +for 'int', 'name()', or the version that was specialized for +'float', 'name()'. To use the word-completion facilities in this +situation, type a single quote ''' at the beginning of the function +name. This alerts GDB that it may need to consider more information +than usual when you press or 'M-?' to request word completion: + + (gdb) p 'func() func() + (gdb) p 'func< + + When setting breakpoints however (*note Location Specifications::), +you don't usually need to type a quote before the function name, because +GDB understands that you want to set a breakpoint on a function: + + (gdb) b func() func() + (gdb) b func< + + This is true even in the case of typing the name of C++ overloaded +functions (multiple definitions of the same function, distinguished by +argument type). For example, when you want to set a breakpoint you +don't need to distinguish whether you mean the version of 'name' that +takes an 'int' parameter, 'name(int)', or the version that takes a +'float' parameter, 'name(float)'. + + (gdb) b bubble(M-? + bubble(int) bubble(double) + (gdb) b bubble(douM-? + bubble(double) + + See *note quoting names:: for a description of other scenarios that +require quoting. + + For more information about overloaded functions, see *note C++ +Expressions: C Plus Plus Expressions. You can use the command 'set +overload-resolution off' to disable overload resolution; see *note GDB +Features for C++: Debugging C Plus Plus. + + When completing in an expression which looks up a field in a +structure, GDB also tries(1) to limit completions to the field names +available in the type of the left-hand-side: + + (gdb) p gdb_stdout.M-? + magic to_fputs to_rewind + to_data to_isatty to_write + to_delete to_put to_write_async_safe + to_flush to_read + +This is because the 'gdb_stdout' is a variable of the type 'struct +ui_file' that is defined in GDB sources as follows: + + struct ui_file + { + int *magic; + ui_file_flush_ftype *to_flush; + ui_file_write_ftype *to_write; + ui_file_write_async_safe_ftype *to_write_async_safe; + ui_file_fputs_ftype *to_fputs; + ui_file_read_ftype *to_read; + ui_file_delete_ftype *to_delete; + ui_file_isatty_ftype *to_isatty; + ui_file_rewind_ftype *to_rewind; + ui_file_put_ftype *to_put; + void *to_data; + } + + ---------- Footnotes ---------- + + (1) The completer can be confused by certain kinds of invalid +expressions. Also, it only examines the static type of the expression, +not the dynamic type. + + +File: gdb.info, Node: Filename Arguments, Next: Command Options, Prev: Completion, Up: Commands + +3.4 Filenames As Command Arguments +================================== + +When passing filenames (or directory names) as arguments to a command, +if the filename argument does not include any whitespace, double quotes, +or single quotes, then for all commands the filename can be written as a +simple string, for example: + + (gdb) file /path/to/some/file + + If the filename does include whitespace, double quotes, or single +quotes, then GDB has two approaches for how these filenames should be +formatted; which format to use depends on which command is being used. + + Most GDB commands don't require, or support, quoting and escaping. +These commands treat any text after the command name, that is not a +command option (*note Command Options::), as the filename, even if the +filename contains whitespace or quote characters. In the following +example the user is adding '/path/that contains/two spaces/' to the +auto-load safe-path (*note add-auto-load-safe-path::): + + (gdb) add-auto-load-safe-path /path/that contains/two spaces/ + + A small number of commands require that filenames containing +whitespace or quote characters are either quoted, or have the special +characters escaped with a backslash. Commands that support this style +are marked as such in the manual, any command not marked as accepting +quoting and escaping of its filename argument, does not accept this +filename argument style. + + For example, to load the file '/path/with spaces/to/a file' with the +'file' command (*note Commands to Specify Files: Files.), you can escape +the whitespace characters with a backslash: + + (gdb) file /path/with\ spaces/to/a\ file + + Alternatively the entire filename can be wrapped in either single or +double quotes, in which case no backlsashes are needed, for example: + + (gdb) symbol-file "/path/with spaces/to/a file" + (gdb) exec-file '/path/with spaces/to/a file' + + It is possible to include a quote character within a quoted filename +by escaping it with a backslash, for example, within a filename +surrounded by double quotes, a double quote character should be escaped +with a backslash, but a single quote character should not be escaped. +Within a single quoted string a single quote character needs to be +escaped, but a double quote character does not. + + A literal backslash character can also be included by escaping it +with a backslash. + + +File: gdb.info, Node: Command Options, Next: Help, Prev: Filename Arguments, Up: Commands + +3.5 Command options +=================== + +Some commands accept options starting with a leading dash. For example, +'print -pretty'. Similarly to command names, you can abbreviate a GDB +option to the first few letters of the option name, if that abbreviation +is unambiguous, and you can also use the key to get GDB to fill +out the rest of a word in an option (or to show you the alternatives +available, if there is more than one possibility). + + Some commands take raw input as argument. For example, the print +command processes arbitrary expressions in any of the languages +supported by GDB. With such commands, because raw input may start with +a leading dash that would be confused with an option or any of its +abbreviations, e.g. 'print -p' (short for 'print -pretty' or printing +negative 'p'?), if you specify any command option, then you must use a +double-dash ('--') delimiter to indicate the end of options. + + Some options are described as accepting an argument which can be +either 'on' or 'off'. These are known as "boolean options". Similarly +to boolean settings commands--'on' and 'off' are the typical values, but +any of '1', 'yes' and 'enable' can also be used as "true" value, and any +of '0', 'no' and 'disable' can also be used as "false" value. You can +also omit a "true" value, as it is implied by default. + + For example, these are equivalent: + + (gdb) print -object on -pretty off -element unlimited -- *myptr + (gdb) p -o -p 0 -e u -- *myptr + + You can discover the set of options some command accepts by +completing on '-' after the command name. For example: + + (gdb) print - + -address -max-depth -object -static-members + -array -memory-tag-violations -pretty -symbol + -array-indexes -nibbles -raw-values -union + -elements -null-stop -repeats -vtbl + + Completion will in some cases guide you with a suggestion of what +kind of argument an option expects. For example: + + (gdb) print -elements + NUMBER unlimited + +Here, the option expects a number (e.g., '100'), not literal 'NUMBER'. +Such metasyntactical arguments are always presented in uppercase. + + (For more on using the 'print' command, see *note Examining Data: +Data.) + + +File: gdb.info, Node: Help, Prev: Command Options, Up: Commands + +3.6 Getting Help +================ + +You can always ask GDB itself for information on its commands, using the +command 'help'. + +'help' +'h' + You can use 'help' (abbreviated 'h') with no arguments to display a + short list of named classes of commands: + + (gdb) help + List of classes of commands: + + aliases -- User-defined aliases of other commands + breakpoints -- Making program stop at certain points + data -- Examining data + files -- Specifying and examining files + internals -- Maintenance commands + obscure -- Obscure features + running -- Running the program + stack -- Examining the stack + status -- Status inquiries + support -- Support facilities + tracepoints -- Tracing of program execution without + stopping the program + user-defined -- User-defined commands + + Type "help" followed by a class name for a list of + commands in that class. + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help CLASS' + Using one of the general help classes as an argument, you can get a + list of the individual commands in that class. If a command has + aliases, the aliases are given after the command name, separated by + commas. If an alias has default arguments, the full definition of + the alias is given after the first line. For example, here is the + help display for the class 'status': + + (gdb) help status + Status inquiries. + + List of commands: + + info, inf, i -- Generic command for showing things + about the program being debugged + info address, iamain -- Describe where symbol SYM is stored. + alias iamain = info address main + info all-registers -- List of all registers and their contents, + for selected stack frame. + ... + show, info set -- Generic command for showing things + about the debugger + + Type "help" followed by command name for full + documentation. + Command name abbreviations are allowed if unambiguous. + (gdb) + +'help COMMAND' + With a command name as 'help' argument, GDB displays a short + paragraph on how to use that command. If that command has one or + more aliases, GDB will display a first line with the command name + and all its aliases separated by commas. This first line will be + followed by the full definition of all aliases having default + arguments. When asking the help for an alias, the documentation + for the aliased command is shown. + + A user-defined alias can optionally be documented using the + 'document' command (*note document: Define.). GDB then considers + this alias as different from the aliased command: this alias is not + listed in the aliased command help output, and asking help for this + alias will show the documentation provided for the alias instead of + the documentation of the aliased command. + +'apropos [-v] REGEXP' + The 'apropos' command searches through all of the GDB commands and + aliases, and their documentation, for the regular expression + specified in ARGS. It prints out all matches found. The optional + flag '-v', which stands for 'verbose', indicates to output the full + documentation of the matching commands and highlight the parts of + the documentation matching REGEXP. For example: + + apropos alias + + results in: + + alias -- Define a new command that is an alias of an existing command + aliases -- User-defined aliases of other commands + + while + + apropos -v cut.*thread apply + + results in the below output, where 'cut for 'thread apply' is + highlighted if styling is enabled. + + taas -- Apply a command to all threads (ignoring errors + and empty output). + Usage: taas COMMAND + shortcut for 'thread apply all -s COMMAND' + + tfaas -- Apply a command to all frames of all threads + (ignoring errors and empty output). + Usage: tfaas COMMAND + shortcut for 'thread apply all -s frame apply all -s COMMAND' + +'complete ARGS' + The 'complete ARGS' command lists all the possible completions for + the beginning of a command. Use ARGS to specify the beginning of + the command you want completed. For example: + + complete i + + results in: + + if + ignore + info + inspect + + This is intended for use by GNU Emacs. + + In addition to 'help', you can use the GDB commands 'info' and 'show' +to inquire about the state of your program, or the state of GDB itself. +Each command supports many topics of inquiry; this manual introduces +each of them in the appropriate context. The listings under 'info' and +under 'show' in the Command, Variable, and Function Index point to all +the sub-commands. *Note Command and Variable Index::. + +'info' + This command (abbreviated 'i') is for describing the state of your + program. For example, you can show the arguments passed to a + function with 'info args', list the registers currently in use with + 'info registers', or list the breakpoints you have set with 'info + breakpoints'. You can get a complete list of the 'info' + sub-commands with 'help info'. + +'set' + You can assign the result of an expression to an environment + variable with 'set'. For example, you can set the GDB prompt to a + $-sign with 'set prompt $'. + +'show' + In contrast to 'info', 'show' is for describing the state of GDB + itself. You can change most of the things you can 'show', by using + the related command 'set'; for example, you can control what number + system is used for displays with 'set radix', or simply inquire + which is currently in use with 'show radix'. + + To display all the settable parameters and their current values, + you can use 'show' with no arguments; you may also use 'info set'. + Both commands produce the same display. + + Here are several miscellaneous 'show' subcommands, all of which are +exceptional in lacking corresponding 'set' commands: + +'show version' + Show what version of GDB is running. You should include this + information in GDB bug-reports. If multiple versions of GDB are in + use at your site, you may need to determine which version of GDB + you are running; as GDB evolves, new commands are introduced, and + old ones may wither away. Also, many system vendors ship variant + versions of GDB, and there are variant versions of GDB in GNU/Linux + distributions as well. The version number is the same as the one + announced when you start GDB. + +'show copying' +'info copying' + Display information about permission for copying GDB. + +'show warranty' +'info warranty' + Display the GNU "NO WARRANTY" statement, or a warranty, if your + version of GDB comes with one. + +'show configuration' + Display detailed information about the way GDB was configured when + it was built. This displays the optional arguments passed to the + 'configure' script and also configuration parameters detected + automatically by 'configure'. When reporting a GDB bug (*note GDB + Bugs::), it is important to include this information in your + report. + + This commands also displays the version number of the Readline + library that GDB is using. After the version number will appear + either '(system)' indicating GDB is using the shared system + Readline library, or '(internal)' indicating GDB is using a + statically linked in version of the Readline library. + + +File: gdb.info, Node: Running, Next: Stopping, Prev: Commands, Up: Top + +4 Running Programs Under GDB +**************************** + +When you run a program under GDB, you must first generate debugging +information when you compile it. + + You may start GDB with its arguments, if any, in an environment of +your choice. If you are doing native debugging, you may redirect your +program's input and output, debug an already running process, or kill a +child process. + +* Menu: + +* Compilation:: Compiling for debugging +* Starting:: Starting your program +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process +* Inferiors Connections and Programs:: Debugging multiple inferiors + connections and programs +* Threads:: Debugging programs with multiple threads +* Forks:: Debugging forks +* Checkpoint/Restart:: Setting a _bookmark_ to return to later + + +File: gdb.info, Node: Compilation, Next: Starting, Up: Running + +4.1 Compiling for Debugging +=========================== + +In order to debug a program effectively, you need to generate debugging +information when you compile it. This debugging information is stored +in the object file; it describes the data type of each variable or +function and the correspondence between source line numbers and +addresses in the executable code. + + To request debugging information, specify the '-g' option when you +run the compiler. + + Programs that are to be shipped to your customers are compiled with +optimizations, using the '-O' compiler option. However, some compilers +are unable to handle the '-g' and '-O' options together. Using those +compilers, you cannot generate optimized executables containing +debugging information. + + GCC, the GNU C/C++ compiler, supports '-g' with or without '-O', +making it possible to debug optimized code. We recommend that you +_always_ use '-g' whenever you compile a program. You may think your +program is correct, but there is no sense in pushing your luck. For +more information, see *note Optimized Code::. + + Older versions of the GNU C compiler permitted a variant option '-gg' +for debugging information. GDB no longer supports this format; if your +GNU C compiler has this option, do not use it. + + GDB knows about preprocessor macros and can show you their expansion +(*note Macros::). Most compilers do not include information about +preprocessor macros in the debugging information if you specify the '-g' +flag alone. Version 3.1 and later of GCC, the GNU C compiler, provides +macro information if you are using the DWARF debugging format, and +specify the option '-g3'. + + *Note Options for Debugging Your Program or GCC: (gcc)Debugging +Options, for more information on GCC options affecting debug +information. + + You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in GDB. + + +File: gdb.info, Node: Starting, Next: Arguments, Prev: Compilation, Up: Running + +4.2 Starting your Program +========================= + +'run' +'r' + Use the 'run' command to start your program under GDB. You must + first specify the program name with an argument to GDB (*note + Getting In and Out of GDB: Invocation.), or by using the 'file' or + 'exec-file' command (*note Commands to Specify Files: Files.). + + If you are running your program in an execution environment that +supports processes, 'run' creates an inferior process and makes that +process run your program. In some environments without processes, 'run' +jumps to the start of your program. Other targets, like 'remote', are +always running. If you get an error message like this one: + + The "remote" target does not support "run". + Try "help target" or "continue". + +then use 'continue' to run your program. You may need 'load' first +(*note load::). + + The execution of a program is affected by certain information it +receives from its superior. GDB provides ways to specify this +information, which you must do _before_ starting your program. (You can +change it after starting your program, but such changes only affect your +program the next time you start it.) This information may be divided +into four categories: + +The _arguments._ + Specify the arguments to give your program as the arguments of the + 'run' command. If a shell is available on your target, the shell + is used to pass the arguments, so that you may use normal + conventions (such as wildcard expansion or variable substitution) + in describing the arguments. In Unix systems, you can control + which shell is used with the 'SHELL' environment variable. If you + do not define 'SHELL', GDB uses the default shell ('/bin/sh'). You + can disable use of any shell with the 'set startup-with-shell' + command (see below for details). + +The _environment._ + Your program normally inherits its environment from GDB, but you + can use the GDB commands 'set environment' and 'unset environment' + to change parts of the environment that affect your program. *Note + Your Program's Environment: Environment. + +The _working directory._ + You can set your program's working directory with the command 'set + cwd'. If you do not set any working directory with this command, + your program will inherit GDB's working directory if native + debugging, or the remote server's working directory if remote + debugging. *Note Your Program's Working Directory: Working + Directory. + +The _standard input and output._ + Your program normally uses the same device for standard input and + standard output as GDB is using. You can redirect input and output + in the 'run' command line, or you can use the 'tty' command to set + a different device for your program. *Note Your Program's Input + and Output: Input/Output. + + _Warning:_ While input and output redirection work, you cannot use + pipes to pass the output of the program you are debugging to + another program; if you attempt this, GDB is likely to wind up + debugging the wrong program. + + When you issue the 'run' command, your program begins to execute +immediately. *Note Stopping and Continuing: Stopping, for discussion of +how to arrange for your program to stop. Once your program has stopped, +you may call functions in your program, using the 'print' or 'call' +commands. *Note Examining Data: Data. + + If the modification time of your symbol file has changed since the +last time GDB read its symbols, GDB discards its symbol table, and reads +it again. When it does this, GDB tries to retain your current +breakpoints. + +'start' + The name of the main procedure can vary from language to language. + With C or C++, the main procedure name is always 'main', but other + languages such as Ada do not require a specific name for their main + procedure. The debugger provides a convenient way to start the + execution of the program and to stop at the beginning of the main + procedure, depending on the language used. + + The 'start' command does the equivalent of setting a temporary + breakpoint at the beginning of the main procedure and then invoking + the 'run' command. + + Some programs contain an "elaboration" phase where some startup + code is executed before the main procedure is called. This depends + on the languages used to write your program. In C++, for instance, + constructors for static and global objects are executed before + 'main' is called. It is therefore possible that the debugger stops + before reaching the main procedure. However, the temporary + breakpoint will remain to halt execution. + + Specify the arguments to give to your program as arguments to the + 'start' command. These arguments will be given verbatim to the + underlying 'run' command. Note that the same arguments will be + reused if no argument is provided during subsequent calls to + 'start' or 'run'. + + It is sometimes necessary to debug the program during elaboration. + In these cases, using the 'start' command would stop the execution + of your program too late, as the program would have already + completed the elaboration phase. Under these circumstances, either + insert breakpoints in your elaboration code before running your + program or use the 'starti' command. + +'starti' + The 'starti' command does the equivalent of setting a temporary + breakpoint at the first instruction of a program's execution and + then invoking the 'run' command. For programs containing an + elaboration phase, the 'starti' command will stop execution at the + start of the elaboration phase. + +'set exec-wrapper WRAPPER' +'show exec-wrapper' +'unset exec-wrapper' + When 'exec-wrapper' is set, the specified wrapper is used to launch + programs for debugging. GDB starts your program with a shell + command of the form 'exec WRAPPER PROGRAM'. Quoting is added to + PROGRAM and its arguments, but not to WRAPPER, so you should add + quotes if appropriate for your shell. The wrapper runs until it + executes your program, and then GDB takes control. + + You can use any program that eventually calls 'execve' with its + arguments as a wrapper. Several standard Unix utilities do this, + e.g. 'env' and 'nohup'. Any Unix shell script ending with 'exec + "$@"' will also work. + + For example, you can use 'env' to pass an environment variable to + the debugged program, without setting the variable in your shell's + environment: + + (gdb) set exec-wrapper env 'LD_PRELOAD=libtest.so' + (gdb) run + + This command is available when debugging locally on most targets, + excluding DJGPP, Cygwin, and MS Windows. + +'set startup-with-shell' +'set startup-with-shell on' +'set startup-with-shell off' +'show startup-with-shell' + On Unix systems, by default, if a shell is available on your + target, GDB) uses it to start your program. Arguments of the 'run' + command are passed to the shell, which does variable substitution, + expands wildcard characters and performs redirection of I/O. In + some circumstances, it may be useful to disable such use of a + shell, for example, when debugging the shell itself or diagnosing + startup failures such as: + + (gdb) run + Starting program: ./a.out + During startup program terminated with signal SIGSEGV, Segmentation fault. + + which indicates the shell or the wrapper specified with + 'exec-wrapper' crashed, not your program. Most often, this is + caused by something odd in your shell's non-interactive mode + initialization file--such as '.cshrc' for C-shell, $'.zshenv' for + the Z shell, or the file specified in the 'BASH_ENV' environment + variable for BASH. + +'set auto-connect-native-target' +'set auto-connect-native-target on' +'set auto-connect-native-target off' +'show auto-connect-native-target' + + By default, if the current inferior is not connected to any target + yet (e.g., with 'target remote'), the 'run' command starts your + program as a native process under GDB, on your local machine. If + you're sure you don't want to debug programs on your local machine, + you can tell GDB to not connect to the native target automatically + with the 'set auto-connect-native-target off' command. + + If 'on', which is the default, and if the current inferior is not + connected to a target already, the 'run' command automatically + connects to the native target, if one is available. + + If 'off', and if the current inferior is not connected to a target + already, the 'run' command fails with an error: + + (gdb) run + Don't know how to run. Try "help target". + + If the current inferior is already connected to a target, GDB + always uses it with the 'run' command. + + In any case, you can explicitly connect to the native target with + the 'target native' command. For example, + + (gdb) set auto-connect-native-target off + (gdb) run + Don't know how to run. Try "help target". + (gdb) target native + (gdb) run + Starting program: ./a.out + [Inferior 1 (process 10421) exited normally] + + In case you connected explicitly to the 'native' target, GDB + remains connected even if all inferiors exit, ready for the next + 'run' command. Use the 'disconnect' command to disconnect. + + Examples of other commands that likewise respect the + 'auto-connect-native-target' setting: 'attach', 'info proc', 'info + os'. + +'set disable-randomization' +'set disable-randomization on' + This option (enabled by default in GDB) will turn off the native + randomization of the virtual address space of the started program. + This option is useful for multiple debugging sessions to make the + execution better reproducible and memory addresses reusable across + debugging sessions. + + This feature is implemented only on certain targets, including + GNU/Linux. On GNU/Linux you can get the same behavior using + + (gdb) set exec-wrapper setarch `uname -m` -R + +'set disable-randomization off' + Leave the behavior of the started executable unchanged. Some bugs + rear their ugly heads only when the program is loaded at certain + addresses. If your bug disappears when you run the program under + GDB, that might be because GDB by default disables the address + randomization on platforms, such as GNU/Linux, which do that for + stand-alone programs. Use 'set disable-randomization off' to try + to reproduce such elusive bugs. + + On targets where it is available, virtual address space + randomization protects the programs against certain kinds of + security attacks. In these cases the attacker needs to know the + exact location of a concrete executable code. Randomizing its + location makes it impossible to inject jumps misusing a code at its + expected addresses. + + Prelinking shared libraries provides a startup performance + advantage but it makes addresses in these libraries predictable for + privileged processes by having just unprivileged access at the + target system. Reading the shared library binary gives enough + information for assembling the malicious code misusing it. Still + even a prelinked shared library can get loaded at a new random + address just requiring the regular relocation process during the + startup. Shared libraries not already prelinked are always loaded + at a randomly chosen address. + + Position independent executables (PIE) contain position independent + code similar to the shared libraries and therefore such executables + get loaded at a randomly chosen address upon startup. PIE + executables always load even already prelinked shared libraries at + a random address. You can build such executable using 'gcc -fPIE + -pie'. + + Heap (malloc storage), stack and custom mmap areas are always + placed randomly (as long as the randomization is enabled). + +'show disable-randomization' + Show the current setting of the explicit disable of the native + randomization of the virtual address space of the started program. + + +File: gdb.info, Node: Arguments, Next: Environment, Prev: Starting, Up: Running + +4.3 Your Program's Arguments +============================ + +The arguments to your program can be specified by the arguments of the +'run' command. They are passed to a shell, which expands wildcard +characters and performs redirection of I/O, and thence to your program. +Your 'SHELL' environment variable (if it exists) specifies what shell +GDB uses. If you do not define 'SHELL', GDB uses the default shell +('/bin/sh' on Unix). + + On non-Unix systems, the program is usually invoked directly by GDB, +which emulates I/O redirection via the appropriate system calls, and the +wildcard characters are expanded by the startup code of the program, not +by the shell. + + 'run' with no arguments uses the same arguments used by the previous +'run', or those set by the 'set args' command. + +'set args' + Specify the arguments to be used the next time your program is run. + If 'set args' has no arguments, 'run' executes your program with no + arguments. Once you have run your program with arguments, using + 'set args' before the next 'run' is the only way to run it again + without arguments. + +'show args' + Show the arguments to give your program when it is started. + + +File: gdb.info, Node: Environment, Next: Working Directory, Prev: Arguments, Up: Running + +4.4 Your Program's Environment +============================== + +The "environment" consists of a set of environment variables and their +values. Environment variables conventionally record such things as your +user name, your home directory, your terminal type, and your search path +for programs to run. Usually you set up environment variables with the +shell and they are inherited by all the other programs you run. When +debugging, it can be useful to try running your program with a modified +environment without having to start GDB over again. + +'path DIRECTORY' + Add DIRECTORY to the front of the 'PATH' environment variable (the + search path for executables) that will be passed to your program. + The value of 'PATH' used by GDB does not change. You may specify + several directory names, separated by whitespace or by a + system-dependent separator character (':' on Unix, ';' on MS-DOS + and MS-Windows). If DIRECTORY is already in the path, it is moved + to the front, so it is searched sooner. + + You can use the string '$cwd' to refer to whatever is the current + working directory at the time GDB searches the path. If you use + '.' instead, it refers to the directory where you executed the + 'path' command. GDB replaces '.' in the DIRECTORY argument (with + the current path) before adding DIRECTORY to the search path. + +'show paths' + Display the list of search paths for executables (the 'PATH' + environment variable). + +'show environment [VARNAME]' + Print the value of environment variable VARNAME to be given to your + program when it starts. If you do not supply VARNAME, print the + names and values of all environment variables to be given to your + program. You can abbreviate 'environment' as 'env'. + +'set environment VARNAME [=VALUE]' + Set environment variable VARNAME to VALUE. The value changes for + your program (and the shell GDB uses to launch it), not for GDB + itself. The VALUE may be any string; the values of environment + variables are just strings, and any interpretation is supplied by + your program itself. The VALUE parameter is optional; if it is + eliminated, the variable is set to a null value. + + For example, this command: + + set env USER = foo + + tells the debugged program, when subsequently run, that its user is + named 'foo'. (The spaces around '=' are used for clarity here; + they are not actually required.) + + Note that on Unix systems, GDB runs your program via a shell, which + also inherits the environment set with 'set environment'. If + necessary, you can avoid that by using the 'env' program as a + wrapper instead of using 'set environment'. *Note set + exec-wrapper::, for an example doing just that. + + Environment variables that are set by the user are also transmitted + to 'gdbserver' to be used when starting the remote inferior. *note + QEnvironmentHexEncoded::. + +'unset environment VARNAME' + Remove variable VARNAME from the environment to be passed to your + program. This is different from 'set env VARNAME ='; 'unset + environment' removes the variable from the environment, rather than + assigning it an empty value. + + Environment variables that are unset by the user are also unset on + 'gdbserver' when starting the remote inferior. *note + QEnvironmentUnset::. + + _Warning:_ On Unix systems, GDB runs your program using the shell +indicated by your 'SHELL' environment variable if it exists (or +'/bin/sh' if not). If your 'SHELL' variable names a shell that runs an +initialization file when started non-interactively--such as '.cshrc' for +C-shell, $'.zshenv' for the Z shell, or the file specified in the +'BASH_ENV' environment variable for BASH--any variables you set in that +file affect your program. You may wish to move setting of environment +variables to files that are only run when you sign on, such as '.login' +or '.profile'. + + +File: gdb.info, Node: Working Directory, Next: Input/Output, Prev: Environment, Up: Running + +4.5 Your Program's Working Directory +==================================== + +Each time you start your program with 'run', the inferior will be +initialized with the current working directory specified by the 'set +cwd' command. If no directory has been specified by this command, then +the inferior will inherit GDB's current working directory as its working +directory if native debugging, or it will inherit the remote server's +current working directory if remote debugging. + +'set cwd [DIRECTORY]' + Set the inferior's working directory to DIRECTORY, which will be + 'glob'-expanded in order to resolve tildes ('~'). If no argument + has been specified, the command clears the setting and resets it to + an empty state. This setting has no effect on GDB's working + directory, and it only takes effect the next time you start the + inferior. The '~' in DIRECTORY is a short for the "home + directory", usually pointed to by the 'HOME' environment variable. + On MS-Windows, if 'HOME' is not defined, GDB uses the concatenation + of 'HOMEDRIVE' and 'HOMEPATH' as fallback. + + You can also change GDB's current working directory by using the + 'cd' command. *Note cd command::. + +'show cwd' + Show the inferior's working directory. If no directory has been + specified by 'set cwd', then the default inferior's working + directory is the same as GDB's working directory. + +'cd [DIRECTORY]' + Set the GDB working directory to DIRECTORY. If not given, + DIRECTORY uses ''~''. + + The GDB working directory serves as a default for the commands that + specify files for GDB to operate on. *Note Commands to Specify + Files: Files. *Note set cwd command::. + +'pwd' + Print the GDB working directory. + + It is generally impossible to find the current working directory of +the process being debugged (since a program can change its directory +during its run). If you work on a system where GDB supports the 'info +proc' command (*note Process Information::), you can use the 'info proc' +command to find out the current working directory of the debuggee. + + +File: gdb.info, Node: Input/Output, Next: Attach, Prev: Working Directory, Up: Running + +4.6 Your Program's Input and Output +=================================== + +By default, the program you run under GDB does input and output to the +same terminal that GDB uses. GDB switches the terminal to its own +terminal modes to interact with you, but it records the terminal modes +your program was using and switches back to them when you continue +running your program. + +'info terminal' + Displays information recorded by GDB about the terminal modes your + program is using. + + You can redirect your program's input and/or output using shell +redirection with the 'run' command. For example, + + run > outfile + +starts your program, diverting its output to the file 'outfile'. + + Another way to specify where your program should do input and output +is with the 'tty' command. This command accepts a file name as +argument, and causes this file to be the default for future 'run' +commands. It also resets the controlling terminal for the child +process, for future 'run' commands. For example, + + tty /dev/ttyb + +directs that processes started with subsequent 'run' commands default to +do input and output on the terminal '/dev/ttyb' and have that as their +controlling terminal. + + An explicit redirection in 'run' overrides the 'tty' command's effect +on the input/output device, but not its effect on the controlling +terminal. + + When you use the 'tty' command or redirect input in the 'run' +command, only the input _for your program_ is affected. The input for +GDB still comes from your terminal. 'tty' is an alias for 'set +inferior-tty'. + + You can use the 'show inferior-tty' command to tell GDB to display +the name of the terminal that will be used for future runs of your +program. + +'set inferior-tty [ TTY ]' + Set the tty for the program being debugged to TTY. Omitting TTY + restores the default behavior, which is to use the same terminal as + GDB. + +'show inferior-tty' + Show the current tty for the program being debugged. + + +File: gdb.info, Node: Attach, Next: Kill Process, Prev: Input/Output, Up: Running + +4.7 Debugging an Already-running Process +======================================== + +'attach PROCESS-ID' + This command attaches to a running process--one that was started + outside GDB. ('info files' shows your active targets.) The + command takes as argument a process ID. The usual way to find out + the PROCESS-ID of a Unix process is with the 'ps' utility, or with + the 'jobs -l' shell command. + + 'attach' does not repeat if you press a second time after + executing the command. + + To use 'attach', your program must be running in an environment which +supports processes; for example, 'attach' does not work for programs on +bare-board targets that lack an operating system. You must also have +permission to send the process a signal. + + When you use 'attach', the debugger finds the program running in the +process first by looking in the current working directory, then (if the +program is not found) by using the source file search path (*note +Specifying Source Directories: Source Path.). You can also use the +'file' command to load the program. *Note Commands to Specify Files: +Files. + + If the debugger can determine that the executable file running in the +process it is attaching to does not match the current exec-file loaded +by GDB, the option 'exec-file-mismatch' specifies how to handle the +mismatch. GDB tries to compare the files by comparing their build IDs +(*note build ID::), if available. + +'set exec-file-mismatch 'ask|warn|off'' + + Whether to detect mismatch between the current executable file + loaded by GDB and the executable file used to start the process. + If 'ask', the default, display a warning and ask the user whether + to load the process executable file; if 'warn', just display a + warning; if 'off', don't attempt to detect a mismatch. If the user + confirms loading the process executable file, then its symbols will + be loaded as well. + +'show exec-file-mismatch' + Show the current value of 'exec-file-mismatch'. + + The first thing GDB does after arranging to debug the specified +process is to stop it. You can examine and modify an attached process +with all the GDB commands that are ordinarily available when you start +processes with 'run'. You can insert breakpoints; you can step and +continue; you can modify storage. If you would rather the process +continue running, you may use the 'continue' command after attaching GDB +to the process. + +'detach' + When you have finished debugging the attached process, you can use + the 'detach' command to release it from GDB control. Detaching the + process continues its execution. After the 'detach' command, that + process and GDB become completely independent once more, and you + are ready to 'attach' another process or start one with 'run'. + 'detach' does not repeat if you press again after executing + the command. + + If you exit GDB while you have an attached process, you detach that +process. If you use the 'run' command, you kill that process. By +default, GDB asks for confirmation if you try to do either of these +things; you can control whether or not you need to confirm by using the +'set confirm' command (*note Optional Warnings and Messages: +Messages/Warnings.). + + +File: gdb.info, Node: Kill Process, Next: Inferiors Connections and Programs, Prev: Attach, Up: Running + +4.8 Killing the Child Process +============================= + +'kill' + Kill the child process in which your program is running under GDB. + + This command is useful if you wish to debug a core dump instead of a +running process. GDB ignores any core dump file while your program is +running. + + On some operating systems, a program cannot be executed outside GDB +while you have breakpoints set on it inside GDB. You can use the 'kill' +command in this situation to permit running your program outside the +debugger. + + The 'kill' command is also useful if you wish to recompile and relink +your program, since on many systems it is impossible to modify an +executable file while it is running in a process. In this case, when +you next type 'run', GDB notices that the file has changed, and reads +the symbol table again (while trying to preserve your current breakpoint +settings). + + +File: gdb.info, Node: Inferiors Connections and Programs, Next: Threads, Prev: Kill Process, Up: Running + +4.9 Debugging Multiple Inferiors Connections and Programs +========================================================= + +GDB lets you run and debug multiple programs in a single session. In +addition, GDB on some systems may let you run several programs +simultaneously (otherwise you have to exit from one before starting +another). On some systems GDB may even let you debug several programs +simultaneously on different remote systems. In the most general case, +you can have multiple threads of execution in each of multiple +processes, launched from multiple executables, running on different +machines. + + GDB represents the state of each program execution with an object +called an "inferior". An inferior typically corresponds to a process, +but is more general and applies also to targets that do not have +processes. Inferiors may be created before a process runs, and may be +retained after a process exits. Inferiors have unique identifiers that +are different from process ids. Usually each inferior will also have +its own distinct address space, although some embedded targets may have +several inferiors running in different parts of a single address space. +Each inferior may in turn have multiple threads running in it. + + The commands 'info inferiors' and 'info connections', which will be +introduced below, accept a space-separated "ID list" as their argument +specifying one or more elements on which to operate. A list element can +be either a single non-negative number, like '5', or an ascending range +of such numbers, like '5-7'. A list can consist of any combination of +such elements, even duplicates or overlapping ranges are valid. E.g. '1 +4-6 5 4-4' or '1 2 4-7'. + + To find out what inferiors exist at any moment, use 'info inferiors': + +'info inferiors' + Print a list of all inferiors currently being managed by GDB. By + default all inferiors are printed, but the ID list ID... can be + used to limit the display to just the requested inferiors. + + GDB displays for each inferior (in this order): + + 1. the inferior number assigned by GDB + + 2. the target system's inferior identifier + + 3. the target connection the inferior is bound to, including the + unique connection number assigned by GDB, and the protocol + used by the connection. + + 4. the name of the executable the inferior is running. + + An asterisk '*' preceding the GDB inferior number indicates the + current inferior. + + For example, + + (gdb) info inferiors + Num Description Connection Executable + * 1 process 3401 1 (native) goodbye + 2 process 2307 2 (extended-remote host:10000) hello + + To get information about the current inferior, use 'inferior': + +'inferior' + Shows information about the current inferior. + + For example, + + (gdb) inferior + [Current inferior is 1 [process 3401] (helloworld)] + + To find out what open target connections exist at any moment, use +'info connections': + +'info connections' + Print a list of all open target connections currently being managed + by GDB. By default all connections are printed, but the ID list + ID... can be used to limit the display to just the requested + connections. + + GDB displays for each connection (in this order): + + 1. the connection number assigned by GDB. + + 2. the protocol used by the connection. + + 3. a textual description of the protocol used by the connection. + + An asterisk '*' preceding the connection number indicates the + connection of the current inferior. + + For example, + + (gdb) info connections + Num What Description + * 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol + 2 native Native process + 3 core Local core dump file + + To switch focus between inferiors, use the 'inferior' command: + +'inferior INFNO' + Make inferior number INFNO the current inferior. The argument + INFNO is the inferior number assigned by GDB, as shown in the first + field of the 'info inferiors' display. + + The debugger convenience variable '$_inferior' contains the number of +the current inferior. You may find this useful in writing breakpoint +conditional expressions, command scripts, and so forth. *Note +Convenience Variables: Convenience Vars, for general information on +convenience variables. + + You can get multiple executables into a debugging session via the +'add-inferior' and 'clone-inferior' commands. On some systems GDB can +add inferiors to the debug session automatically by following calls to +'fork' and 'exec'. To remove inferiors from the debugging session use +the 'remove-inferiors' command. + +'add-inferior [ -copies N ] [ -exec EXECUTABLE ] [-no-connection ]' + Adds N inferiors to be run using EXECUTABLE as the executable; N + defaults to 1. If no executable is specified, the inferiors begins + empty, with no program. You can still assign or change the program + assigned to the inferior at any time by using the 'file' command + with the executable name as its argument. + + By default, the new inferior begins connected to the same target + connection as the current inferior. For example, if the current + inferior was connected to 'gdbserver' with 'target remote', then + the new inferior will be connected to the same 'gdbserver' + instance. The '-no-connection' option starts the new inferior with + no connection yet. You can then for example use the 'target + remote' command to connect to some other 'gdbserver' instance, use + 'run' to spawn a local program, etc. + +'clone-inferior [ -copies N ] [ INFNO ]' + Adds N inferiors ready to execute the same program as inferior + INFNO; N defaults to 1, and INFNO defaults to the number of the + current inferior. This command copies the values of the ARGS, + INFERIOR-TTY and CWD properties from the current inferior to the + new one. It also propagates changes the user made to environment + variables using the 'set environment' and 'unset environment' + commands. This is a convenient command when you want to run + another instance of the inferior you are debugging. + + (gdb) info inferiors + Num Description Connection Executable + * 1 process 29964 1 (native) helloworld + (gdb) clone-inferior + Added inferior 2. + 1 inferiors added. + (gdb) info inferiors + Num Description Connection Executable + * 1 process 29964 1 (native) helloworld + 2 1 (native) helloworld + + You can now simply switch focus to inferior 2 and run it. + +'remove-inferiors INFNO...' + Removes the inferior or inferiors INFNO.... It is not possible to + remove an inferior that is running with this command. For those, + use the 'kill' or 'detach' command first. + + To quit debugging one of the running inferiors that is not the +current inferior, you can either detach from it by using the +'detach inferior' command (allowing it to run independently), or kill it +using the 'kill inferiors' command: + +'detach inferior INFNO...' + Detach from the inferior or inferiors identified by GDB inferior + number(s) INFNO.... Note that the inferior's entry still stays on + the list of inferiors shown by 'info inferiors', but its + Description will show ''. + +'kill inferiors INFNO...' + Kill the inferior or inferiors identified by GDB inferior number(s) + INFNO.... Note that the inferior's entry still stays on the list + of inferiors shown by 'info inferiors', but its Description will + show ''. + + After the successful completion of a command such as 'detach', +'detach inferiors', 'kill' or 'kill inferiors', or after a normal +process exit, the inferior is still valid and listed with 'info +inferiors', ready to be restarted. + + To be notified when inferiors are started or exit under GDB's control +use 'set print inferior-events': + +'set print inferior-events' +'set print inferior-events on' +'set print inferior-events off' + The 'set print inferior-events' command allows you to enable or + disable printing of messages when GDB notices that new inferiors + have started or that inferiors have exited or have been detached. + By default, these messages will be printed. + +'show print inferior-events' + Show whether messages will be printed when GDB detects that + inferiors have started, exited or have been detached. + + Many commands will work the same with multiple programs as with a +single program: e.g., 'print myglobal' will simply display the value of +'myglobal' in the current inferior. + + Occasionally, when debugging GDB itself, it may be useful to get more +info about the relationship of inferiors, programs, address spaces in a +debug session. You can do that with the 'maint info program-spaces' +command. + +'maint info program-spaces' + Print a list of all program spaces currently being managed by GDB. + + GDB displays for each program space (in this order): + + 1. the program space number assigned by GDB + + 2. the name of the executable loaded into the program space, with + e.g., the 'file' command. + + 3. the name of the core file loaded into the program space, with + e.g., the 'core-file' command. + + An asterisk '*' preceding the GDB program space number indicates + the current program space. + + In addition, below each program space line, GDB prints extra + information that isn't suitable to display in tabular form. For + example, the list of inferiors bound to the program space. + + (gdb) maint info program-spaces + Id Executable Core File + * 1 hello + 2 goodbye + Bound inferiors: ID 1 (process 21561) + + Here we can see that no inferior is running the program 'hello', + while 'process 21561' is running the program 'goodbye'. On some + targets, it is possible that multiple inferiors are bound to the + same program space. The most common example is that of debugging + both the parent and child processes of a 'vfork' call. For + example, + + (gdb) maint info program-spaces + Id Executable Core File + * 1 vfork-test + Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) + + Here, both inferior 2 and inferior 1 are running in the same + program space as a result of inferior 1 having executed a 'vfork' + call. + +* Menu: + +* Inferior-Specific Breakpoints:: Controlling breakpoints + + +File: gdb.info, Node: Inferior-Specific Breakpoints, Up: Inferiors Connections and Programs + +4.9.1 Inferior-Specific Breakpoints +----------------------------------- + +When debugging multiple inferiors, you can choose whether to set +breakpoints for all inferiors, or for a particular inferior. + +'break LOCSPEC inferior INFERIOR-ID' +'break LOCSPEC inferior INFERIOR-ID if ...' + LOCSPEC specifies a code location or locations in your program. + *Note Location Specifications::, for details. + + Use the qualifier 'inferior INFERIOR-ID' with a breakpoint command + to specify that you only want GDB to stop when a particular + inferior reaches this breakpoint. The INFERIOR-ID specifier is one + of the inferior identifiers assigned by GDB, shown in the first + column of the 'info inferiors' output. + + If you do not specify 'inferior INFERIOR-ID' when you set a + breakpoint, the breakpoint applies to _all_ inferiors of your + program. + + You can use the 'inferior' qualifier on conditional breakpoints as + well; in this case, place 'inferior INFERIOR-ID' before or after + the breakpoint condition, like this: + + (gdb) break frik.c:13 inferior 2 if bartab > lim + + Inferior-specific breakpoints are automatically deleted when the +corresponding inferior is removed from GDB. For example: + + (gdb) remove-inferiors 2 + Inferior-specific breakpoint 3 deleted - inferior 2 has been removed. + + A breakpoint can't be both inferior-specific and thread-specific +(*note Thread-Specific Breakpoints::), or task-specific (*note Ada +Tasks::); using more than one of the 'inferior', 'thread', or 'task' +keywords when creating a breakpoint will give an error. + + +File: gdb.info, Node: Threads, Next: Forks, Prev: Inferiors Connections and Programs, Up: Running + +4.10 Debugging Programs with Multiple Threads +============================================= + +In some operating systems, such as GNU/Linux and Solaris, a single +program may have more than one "thread" of execution. The precise +semantics of threads differ from one operating system to another, but in +general the threads of a single program are akin to multiple +processes--except that they share one address space (that is, they can +all examine and modify the same variables). On the other hand, each +thread has its own registers and execution stack, and perhaps private +memory. + + GDB provides these facilities for debugging multi-thread programs: + + * automatic notification of new threads + * 'thread THREAD-ID', a command to switch among threads + * 'info threads', a command to inquire about existing threads + * 'thread apply [THREAD-ID-LIST | all] ARGS', a command to apply a + command to a list of threads + * thread-specific breakpoints + * 'set print thread-events', which controls printing of messages on + thread start and exit. + * 'set libthread-db-search-path PATH', which lets the user specify + which 'libthread_db' to use if the default choice isn't compatible + with the program. + + The GDB thread debugging facility allows you to observe all threads +while your program runs--but whenever GDB takes control, one thread in +particular is always the focus of debugging. This thread is called the +"current thread". Debugging commands show program information from the +perspective of the current thread. + + Whenever GDB detects a new thread in your program, it displays the +target system's identification for the thread with a message in the form +'[New SYSTAG]', where SYSTAG is a thread identifier whose form varies +depending on the particular system. For example, on GNU/Linux, you +might see + + [New Thread 0x41e02940 (LWP 25582)] + +when GDB notices a new thread. In contrast, on other systems, the +SYSTAG is simply something like 'process 368', with no further +qualifier. + + For debugging purposes, GDB associates its own thread number --always +a single integer--with each thread of an inferior. This number is +unique between all threads of an inferior, but not unique between +threads of different inferiors. + + You can refer to a given thread in an inferior using the qualified +INFERIOR-NUM.THREAD-NUM syntax, also known as "qualified thread ID", +with INFERIOR-NUM being the inferior number and THREAD-NUM being the +thread number of the given inferior. For example, thread '2.3' refers +to thread number 3 of inferior 2. If you omit INFERIOR-NUM (e.g., +'thread 3'), then GDB infers you're referring to a thread of the current +inferior. + + Until you create a second inferior, GDB does not show the +INFERIOR-NUM part of thread IDs, even though you can always use the full +INFERIOR-NUM.THREAD-NUM form to refer to threads of inferior 1, the +initial inferior. + + Some commands accept a space-separated "thread ID list" as argument. +A list element can be: + + 1. A thread ID as shown in the first field of the 'info threads' + display, with or without an inferior qualifier. E.g., '2.1' or + '1'. + + 2. A range of thread numbers, again with or without an inferior + qualifier, as in INF.THR1-THR2 or THR1-THR2. E.g., '1.2-4' or + '2-4'. + + 3. All threads of an inferior, specified with a star wildcard, with or + without an inferior qualifier, as in INF.'*' (e.g., '1.*') or '*'. + The former refers to all threads of the given inferior, and the + latter form without an inferior qualifier refers to all threads of + the current inferior. + + For example, if the current inferior is 1, and inferior 7 has one +thread with ID 7.1, the thread list '1 2-3 4.5 6.7-9 7.*' includes +threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads 7 to 9 of +inferior 6 and all threads of inferior 7. That is, in expanded +qualified form, the same as '1.1 1.2 1.3 4.5 6.7 6.8 6.9 7.1'. + + In addition to a _per-inferior_ number, each thread is also assigned +a unique _global_ number, also known as "global thread ID", a single +integer. Unlike the thread number component of the thread ID, no two +threads have the same global ID, even when you're debugging multiple +inferiors. + + From GDB's perspective, a process always has at least one thread. In +other words, GDB assigns a thread number to the program's "main thread" +even if the program is not multi-threaded. + + The debugger convenience variables '$_thread' and '$_gthread' +contain, respectively, the per-inferior thread number and the global +thread number of the current thread. You may find this useful in +writing breakpoint conditional expressions, command scripts, and so +forth. The convenience variable '$_inferior_thread_count' contains the +number of live threads in the current inferior. *Note Convenience +Variables: Convenience Vars, for general information on convenience +variables. + + When running in non-stop mode (*note Non-Stop Mode::), where new +threads can be created, and existing threads exit, at any time, +'$_inferior_thread_count' could return a different value each time it is +evaluated. + + If GDB detects the program is multi-threaded, it augments the usual +message about stopping at a breakpoint with the ID and name of the +thread that hit the breakpoint. + + Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 + + Likewise when the program receives a signal: + + Thread 1 "main" received signal SIGINT, Interrupt. + +'info threads [-gid] [THREAD-ID-LIST]' + + Display information about one or more threads. With no arguments + displays information about all threads. You can specify the list + of threads that you want to display using the thread ID list syntax + (*note thread ID lists::). + + GDB displays for each thread (in this order): + + 1. the per-inferior thread number assigned by GDB + + 2. the global thread number assigned by GDB, if the '-gid' option + was specified + + 3. the target system's thread identifier (SYSTAG) + + 4. the thread's name, if one is known. A thread can either be + named by the user (see 'thread name', below), or, in some + cases, by the program itself. + + 5. the current stack frame summary for that thread + + An asterisk '*' to the left of the GDB thread number indicates the + current thread. + + For example, + + (gdb) info threads + Id Target Id Frame + * 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 2 process 35 thread 23 0x34e5 in sigpause () + 3 process 35 thread 27 0x34e5 in sigpause () + at threadtest.c:68 + + If you're debugging multiple inferiors, GDB displays thread IDs using +the qualified INFERIOR-NUM.THREAD-NUM format. Otherwise, only +THREAD-NUM is shown. + + If you specify the '-gid' option, GDB displays a column indicating +each thread's global thread ID: + + (gdb) info threads + Id GId Target Id Frame + 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 1.2 3 process 35 thread 23 0x34e5 in sigpause () + 1.3 4 process 35 thread 27 0x34e5 in sigpause () + * 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) + + On Solaris, you can display more information about user threads with +a Solaris-specific command: + +'maint info sol-threads' + Display info on Solaris user threads. + +'thread THREAD-ID' + Make thread ID THREAD-ID the current thread. The command argument + THREAD-ID is the GDB thread ID, as shown in the first field of the + 'info threads' display, with or without an inferior qualifier + (e.g., '2.1' or '1'). + + GDB responds by displaying the system identifier of the thread you + selected, and its current stack frame summary: + + (gdb) thread 2 + [Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] + #0 some_function (ignore=0x0) at example.c:8 + 8 printf ("hello\n"); + + As with the '[New ...]' message, the form of the text after + 'Switching to' depends on your system's conventions for identifying + threads. + +'thread apply [THREAD-ID-LIST | all [-ascending]] [FLAG]... COMMAND' + The 'thread apply' command allows you to apply the named COMMAND to + one or more threads. Specify the threads that you want affected + using the thread ID list syntax (*note thread ID lists::), or + specify 'all' to apply to all threads. To apply a command to all + threads in descending order, type 'thread apply all COMMAND'. To + apply a command to all threads in ascending order, type 'thread + apply all -ascending COMMAND'. + + The FLAG arguments control what output to produce and how to handle + errors raised when applying COMMAND to a thread. FLAG must start + with a '-' directly followed by one letter in 'qcs'. If several + flags are provided, they must be given individually, such as '-c + -q'. + + By default, GDB displays some thread information before the output + produced by COMMAND, and an error raised during the execution of a + COMMAND will abort 'thread apply'. The following flags can be used + to fine-tune this behavior: + + '-c' + The flag '-c', which stands for 'continue', causes any errors + in COMMAND to be displayed, and the execution of 'thread + apply' then continues. + '-s' + The flag '-s', which stands for 'silent', causes any errors or + empty output produced by a COMMAND to be silently ignored. + That is, the execution continues, but the thread information + and errors are not printed. + '-q' + The flag '-q' ('quiet') disables printing the thread + information. + + Flags '-c' and '-s' cannot be used together. + +'taas [OPTION]... COMMAND' + Shortcut for 'thread apply all -s [OPTION]... COMMAND'. Applies + COMMAND on all threads, ignoring errors and empty output. + + The 'taas' command accepts the same options as the 'thread apply + all' command. *Note thread apply all::. + +'tfaas [OPTION]... COMMAND' + Shortcut for 'thread apply all -s -- frame apply all -s [OPTION]... + COMMAND'. Applies COMMAND on all frames of all threads, ignoring + errors and empty output. Note that the flag '-s' is specified + twice: The first '-s' ensures that 'thread apply' only shows the + thread information of the threads for which 'frame apply' produces + some output. The second '-s' is needed to ensure that 'frame + apply' shows the frame information of a frame only if the COMMAND + successfully produced some output. + + It can for example be used to print a local variable or a function + argument without knowing the thread or frame where this variable or + argument is, using: + (gdb) tfaas p some_local_var_i_do_not_remember_where_it_is + + The 'tfaas' command accepts the same options as the 'frame apply' + command. *Note frame apply: Frame Apply. + +'thread name [NAME]' + This command assigns a name to the current thread. If no argument + is given, any existing user-specified name is removed. The thread + name appears in the 'info threads' display. + + On some systems, such as GNU/Linux, GDB is able to determine the + name of the thread as given by the OS. On these systems, a name + specified with 'thread name' will override the system-give name, + and removing the user-specified name will cause GDB to once again + display the system-specified name. + +'thread find [REGEXP]' + Search for and display thread ids whose name or SYSTAG matches the + supplied regular expression. + + As well as being the complement to the 'thread name' command, this + command also allows you to identify a thread by its target SYSTAG. + For instance, on GNU/Linux, the target SYSTAG is the LWP id. + + (gdb) thread find 26688 + Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' + (gdb) info thread 4 + Id Target Id Frame + 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () + +'set print thread-events' +'set print thread-events on' +'set print thread-events off' + The 'set print thread-events' command allows you to enable or + disable printing of messages when GDB notices that new threads have + started or that threads have exited. By default, these messages + will be printed if detection of these events is supported by the + target. Note that these messages cannot be disabled on all + targets. + +'show print thread-events' + Show whether messages will be printed when GDB detects that threads + have started and exited. + + *Note Stopping and Starting Multi-thread Programs: Thread Stops, for +more information about how GDB behaves when you stop and start programs +with multiple threads. + + *Note Setting Watchpoints: Set Watchpoints, for information about +watchpoints in programs with multiple threads. + +'set libthread-db-search-path [PATH]' + If this variable is set, PATH is a colon-separated list of + directories GDB will use to search for 'libthread_db'. If you omit + PATH, 'libthread-db-search-path' will be reset to its default value + ('$sdir:$pdir' on GNU/Linux and Solaris systems). Internally, the + default value comes from the 'LIBTHREAD_DB_SEARCH_PATH' macro. + + On GNU/Linux and Solaris systems, GDB uses a "helper" + 'libthread_db' library to obtain information about threads in the + inferior process. GDB will use 'libthread-db-search-path' to find + 'libthread_db'. GDB also consults first if inferior specific + thread debugging library loading is enabled by 'set auto-load + libthread-db' (*note libthread_db.so.1 file::). + + A special entry '$sdir' for 'libthread-db-search-path' refers to + the default system directories that are normally searched for + loading shared libraries. The '$sdir' entry is the only kind not + needing to be enabled by 'set auto-load libthread-db' (*note + libthread_db.so.1 file::). + + A special entry '$pdir' for 'libthread-db-search-path' refers to + the directory from which 'libpthread' was loaded in the inferior + process. + + For any 'libthread_db' library GDB finds in above directories, GDB + attempts to initialize it with the current inferior process. If + this initialization fails (which could happen because of a version + mismatch between 'libthread_db' and 'libpthread'), GDB will unload + 'libthread_db', and continue with the next directory. If none of + 'libthread_db' libraries initialize successfully, GDB will issue a + warning and thread debugging will be disabled. + + Setting 'libthread-db-search-path' is currently implemented only on + some platforms. + +'show libthread-db-search-path' + Display current libthread_db search path. + +'set debug libthread-db' +'show debug libthread-db' + Turns on or off display of 'libthread_db'-related events. Use '1' + to enable, '0' to disable. + +'set debug threads [on|off]' +'show debug threads' + When 'on' GDB will print additional messages when threads are + created and deleted. + + +File: gdb.info, Node: Forks, Next: Checkpoint/Restart, Prev: Threads, Up: Running + +4.11 Debugging Forks +==================== + +On most systems, GDB has no special support for debugging programs which +create additional processes using the 'fork' function. When a program +forks, GDB will continue to debug the parent process and the child +process will run unimpeded. If you have set a breakpoint in any code +which the child then executes, the child will get a 'SIGTRAP' signal +which (unless it catches the signal) will cause it to terminate. + + However, if you want to debug the child process there is a workaround +which isn't too painful. Put a call to 'sleep' in the code which the +child process executes after the fork. It may be useful to sleep only +if a certain environment variable is set, or a certain file exists, so +that the delay need not occur when you don't want to run GDB on the +child. While the child is sleeping, use the 'ps' program to get its +process ID. Then tell GDB (a new invocation of GDB if you are also +debugging the parent process) to attach to the child process (*note +Attach::). From that point on you can debug the child process just like +any other process which you attached to. + + On some systems, GDB provides support for debugging programs that +create additional processes using the 'fork' or 'vfork' functions. On +GNU/Linux platforms, this feature is supported with kernel version +2.5.46 and later. + + The fork debugging commands are supported in native mode and when +connected to 'gdbserver' in either 'target remote' mode or 'target +extended-remote' mode. + + By default, when a program forks, GDB will continue to debug the +parent process and the child process will run unimpeded. + + If you want to follow the child process instead of the parent +process, use the command 'set follow-fork-mode'. + +'set follow-fork-mode MODE' + Set the debugger response to a program call of 'fork' or 'vfork'. + A call to 'fork' or 'vfork' creates a new process. The MODE + argument can be: + + 'parent' + The original process is debugged after a fork. The child + process runs unimpeded. This is the default. + + 'child' + The new process is debugged after a fork. The parent process + runs unimpeded. + +'show follow-fork-mode' + Display the current debugger response to a 'fork' or 'vfork' call. + + On Linux, if you want to debug both the parent and child processes, +use the command 'set detach-on-fork'. + +'set detach-on-fork MODE' + Tells gdb whether to detach one of the processes after a fork, or + retain debugger control over them both. + + 'on' + The child process (or parent process, depending on the value + of 'follow-fork-mode') will be detached and allowed to run + independently. This is the default. + + 'off' + Both processes will be held under the control of GDB. One + process (child or parent, depending on the value of + 'follow-fork-mode') is debugged as usual, while the other is + held suspended. + +'show detach-on-fork' + Show whether detach-on-fork mode is on/off. + + If you choose to set 'detach-on-fork' mode off, then GDB will retain +control of all forked processes (including nested forks). You can list +the forked processes under the control of GDB by using the +'info inferiors' command, and switch from one fork to another by using +the 'inferior' command (*note Debugging Multiple Inferiors Connections +and Programs: Inferiors Connections and Programs.). + + To quit debugging one of the forked processes, you can either detach +from it by using the 'detach inferiors' command (allowing it to run +independently), or kill it using the 'kill inferiors' command. *Note +Debugging Multiple Inferiors Connections and Programs: Inferiors +Connections and Programs. + + If you ask to debug a child process and a 'vfork' is followed by an +'exec', GDB executes the new target up to the first breakpoint in the +new target. If you have a breakpoint set on 'main' in your original +program, the breakpoint will also be set on the child process's 'main'. + + On some systems, when a child process is spawned by 'vfork', you +cannot debug the child or parent until an 'exec' call completes. + + If you issue a 'run' command to GDB after an 'exec' call executes, +the new target restarts. To restart the parent process, use the 'file' +command with the parent executable name as its argument. By default, +after an 'exec' call executes, GDB discards the symbols of the previous +executable image. You can change this behavior with the +'set follow-exec-mode' command. + +'set follow-exec-mode MODE' + + Set debugger response to a program call of 'exec'. An 'exec' call + replaces the program image of a process. + + 'follow-exec-mode' can be: + + 'new' + GDB creates a new inferior and rebinds the process to this new + inferior. The program the process was running before the + 'exec' call can be restarted afterwards by restarting the + original inferior. + + For example: + + (gdb) info inferiors + (gdb) info inferior + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + 1 prog1 + * 2 prog2 + + 'same' + GDB keeps the process bound to the same inferior. The new + executable image replaces the previous executable loaded in + the inferior. Restarting the inferior after the 'exec' call, + with e.g., the 'run' command, restarts the executable the + process was running after the 'exec' call. This is the + default mode. + + For example: + + (gdb) info inferiors + Id Description Executable + * 1 prog1 + (gdb) run + process 12020 is executing new program: prog2 + Program exited normally. + (gdb) info inferiors + Id Description Executable + * 1 prog2 + + 'follow-exec-mode' is supported in native mode and 'target +extended-remote' mode. + + You can use the 'catch' command to make GDB stop whenever a 'fork', +'vfork', or 'exec' call is made. *Note Setting Catchpoints: Set +Catchpoints. + + +File: gdb.info, Node: Checkpoint/Restart, Prev: Forks, Up: Running + +4.12 Setting a _Bookmark_ to Return to Later +============================================ + +On certain operating systems(1), GDB is able to save a "snapshot" of a +program's state, called a "checkpoint", and come back to it later. + + Returning to a checkpoint effectively undoes everything that has +happened in the program since the 'checkpoint' was saved. This includes +changes in memory, registers, and even (within some limits) system +state. Effectively, it is like going back in time to the moment when +the checkpoint was saved. + + Thus, if you're stepping through a program and you think you're +getting close to the point where things go wrong, you can save a +checkpoint. Then, if you accidentally go too far and miss the critical +statement, instead of having to restart your program from the beginning, +you can just go back to the checkpoint and start again from there. + + This can be especially useful if it takes a lot of time or steps to +reach the point where you think the bug occurs. + + To use the 'checkpoint'/'restart' method of debugging: + +'checkpoint' + Save a snapshot of the debugged program's current execution state. + The 'checkpoint' command takes no arguments, but each checkpoint is + assigned a small integer id, similar to a breakpoint id. + +'info checkpoints' + List the checkpoints that have been saved in the current debugging + session. For each checkpoint, the following information will be + listed: + + 'Checkpoint ID' + 'Process ID' + 'Code Address' + 'Source line, or label' + +'restart CHECKPOINT-ID' + Restore the program state that was saved as checkpoint number + CHECKPOINT-ID. All program variables, registers, stack frames etc. + will be returned to the values that they had when the checkpoint + was saved. In essence, gdb will "wind back the clock" to the point + in time when the checkpoint was saved. + + Note that breakpoints, GDB variables, command history etc. are not + affected by restoring a checkpoint. In general, a checkpoint only + restores things that reside in the program being debugged, not in + the debugger. + +'delete checkpoint CHECKPOINT-ID' + Delete the previously-saved checkpoint identified by CHECKPOINT-ID. + + Returning to a previously saved checkpoint will restore the user +state of the program being debugged, plus a significant subset of the +system (OS) state, including file pointers. It won't "un-write" data +from a file, but it will rewind the file pointer to the previous +location, so that the previously written data can be overwritten. For +files opened in read mode, the pointer will also be restored so that the +previously read data can be read again. + + Of course, characters that have been sent to a printer (or other +external device) cannot be "snatched back", and characters received from +eg. a serial device can be removed from internal program buffers, but +they cannot be "pushed back" into the serial pipeline, ready to be +received again. Similarly, the actual contents of files that have been +changed cannot be restored (at this time). + + However, within those constraints, you actually can "rewind" your +program to a previously saved point in time, and begin debugging it +again -- and you can change the course of events so as to debug a +different execution path this time. + + Finally, there is one bit of internal program state that will be +different when you return to a checkpoint -- the program's process id. +Each checkpoint will have a unique process id (or PID), and each will be +different from the program's original PID. If your program has saved a +local copy of its process id, this could potentially pose a problem. + +4.12.1 A Non-obvious Benefit of Using Checkpoints +------------------------------------------------- + +On some systems such as GNU/Linux, address space randomization is +performed on new processes for security reasons. This makes it +difficult or impossible to set a breakpoint, or watchpoint, on an +absolute address if you have to restart the program, since the absolute +location of a symbol will change from one execution to the next. + + A checkpoint, however, is an _identical_ copy of a process. +Therefore if you create a checkpoint at (eg.) the start of main, and +simply return to that checkpoint instead of restarting the process, you +can avoid the effects of address randomization and your symbols will all +stay in the same place. + + ---------- Footnotes ---------- + + (1) Currently, only GNU/Linux. + + +File: gdb.info, Node: Stopping, Next: Reverse Execution, Prev: Running, Up: Top + +5 Stopping and Continuing +************************* + +The principal purposes of using a debugger are so that you can stop your +program before it terminates; or so that, if your program runs into +trouble, you can investigate and find out why. + + Inside GDB, your program may stop for any of several reasons, such as +a signal, a breakpoint, or reaching a new line after a GDB command such +as 'step'. You may then examine and change variables, set new +breakpoints or remove old ones, and then continue execution. Usually, +the messages shown by GDB provide ample explanation of the status of +your program--but you can also explicitly request this information at +any time. + +'info program' + Display information about the status of your program: whether it is + running or not, what process it is, and why it stopped. + +* Menu: + +* Breakpoints:: Breakpoints, watchpoints, tracepoints, + and catchpoints +* Continuing and Stepping:: Resuming execution +* Skipping Over Functions and Files:: + Skipping over functions and files +* Signals:: Signals +* Thread Stops:: Stopping and starting multi-thread programs + + +File: gdb.info, Node: Breakpoints, Next: Continuing and Stepping, Up: Stopping + +5.1 Breakpoints, Watchpoints, and Catchpoints +============================================= + +A "breakpoint" makes your program stop whenever a certain point in the +program is reached. For each breakpoint, you can add conditions to +control in finer detail whether your program stops. You can set +breakpoints with the 'break' command and its variants (*note Setting +Breakpoints: Set Breaks.), to specify the place where your program +should stop by line number, function name or exact address in the +program. + + On some systems, you can set breakpoints in shared libraries before +the executable is run. + + A "watchpoint" is a special breakpoint that stops your program when +the value of an expression changes. The expression may be a value of a +variable, or it could involve values of one or more variables combined +by operators, such as 'a + b'. This is sometimes called "data +breakpoints". You must use a different command to set watchpoints +(*note Setting Watchpoints: Set Watchpoints.), but aside from that, you +can manage a watchpoint like any other breakpoint: you enable, disable, +and delete both breakpoints and watchpoints using the same commands. + + You can arrange to have values from your program displayed +automatically whenever GDB stops at a breakpoint. *Note Automatic +Display: Auto Display. + + A "catchpoint" is another special breakpoint that stops your program +when a certain kind of event occurs, such as the throwing of a C++ +exception or the loading of a library. As with watchpoints, you use a +different command to set a catchpoint (*note Setting Catchpoints: Set +Catchpoints.), but aside from that, you can manage a catchpoint like any +other breakpoint. (To stop when your program receives a signal, use the +'handle' command; see *note Signals: Signals.) + + GDB assigns a number to each breakpoint, watchpoint, or catchpoint +when you create it; these numbers are successive integers starting with +one. In many of the commands for controlling various features of +breakpoints you use the breakpoint number to say which breakpoint you +want to change. Each breakpoint may be "enabled" or "disabled"; if +disabled, it has no effect on your program until you enable it again. + + Some GDB commands accept a space-separated list of breakpoints on +which to operate. A list element can be either a single breakpoint +number, like '5', or a range of such numbers, like '5-7'. When a +breakpoint list is given to a command, all breakpoints in that list are +operated on. + +* Menu: + +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists +* Dynamic Printf:: Dynamic printf +* Save Breakpoints:: How to save breakpoints in a file +* Static Probe Points:: Listing static probe points +* Error in Breakpoints:: "Cannot insert breakpoints" +* Breakpoint-related Warnings:: "Breakpoint address adjusted..." + + +File: gdb.info, Node: Set Breaks, Next: Set Watchpoints, Up: Breakpoints + +5.1.1 Setting Breakpoints +------------------------- + +Breakpoints are set with the 'break' command (abbreviated 'b'). The +debugger convenience variable '$bpnum' records the number of the +breakpoint you've set most recently: + (gdb) b main + Breakpoint 1 at 0x11c6: file zeoes.c, line 24. + (gdb) p $bpnum + $1 = 1 + + A breakpoint may be mapped to multiple code locations for example +with inlined functions, Ada generics, C++ templates or overloaded +function names. GDB then indicates the number of code locations in the +breakpoint command output: + (gdb) b some_func + Breakpoint 2 at 0x1179: some_func. (3 locations) + (gdb) p $bpnum + $2 = 2 + (gdb) + + When your program stops on a breakpoint, the convenience variables +'$_hit_bpnum' and '$_hit_locno' are respectively set to the number of +the encountered breakpoint and the number of the breakpoint's code +location: + Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8 + 8 printf("some func\n"); + (gdb) p $_hit_bpnum + $5 = 2 + (gdb) p $_hit_locno + $6 = 1 + (gdb) + + Note that '$_hit_bpnum' and '$bpnum' are not equivalent: +'$_hit_bpnum' is set to the breakpoint number last hit, while '$bpnum' +is set to the breakpoint number last set. + + If the encountered breakpoint has only one code location, +'$_hit_locno' is set to 1: + Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24 + 24 if (argc > 1) + (gdb) p $_hit_bpnum + $3 = 1 + (gdb) p $_hit_locno + $4 = 1 + (gdb) + + The '$_hit_bpnum' and '$_hit_locno' variables can typically be used +in a breakpoint command list. (*note Breakpoint Command Lists: Break +Commands.). For example, as part of the breakpoint command list, you +can disable completely the encountered breakpoint using 'disable +$_hit_bpnum' or disable the specific encountered breakpoint location +using 'disable $_hit_bpnum.$_hit_locno'. If a breakpoint has only one +location, '$_hit_locno' is set to 1 and the commands 'disable +$_hit_bpnum' and 'disable $_hit_bpnum.$_hit_locno' both disable the +breakpoint. + + You can also define aliases to easily disable the last hit location +or last hit breakpoint: + (gdb) alias lld = disable $_hit_bpnum.$_hit_locno + (gdb) alias lbd = disable $_hit_bpnum + +'break LOCSPEC' + Set a breakpoint at all the code locations in your program that + result from resolving the given LOCSPEC. LOCSPEC can specify a + function name, a line number, an address of an instruction, and + more. *Note Location Specifications::, for the various forms of + LOCSPEC. The breakpoint will stop your program just before it + executes the instruction at the address of any of the breakpoint's + code locations. + + When using source languages that permit overloading of symbols, + such as C++, a function name may refer to more than one symbol, and + thus more than one place to break. *Note Ambiguous Expressions: + Ambiguous Expressions, for a discussion of that situation. + + It is also possible to insert a breakpoint that will stop the + program only if a specific thread (*note Thread-Specific + Breakpoints::), specific inferior (*note Inferior-Specific + Breakpoints::), or a specific task (*note Ada Tasks::) hits that + breakpoint. + +'break' + When called without any arguments, 'break' sets a breakpoint at the + next instruction to be executed in the selected stack frame (*note + Examining the Stack: Stack.). In any selected frame but the + innermost, this makes your program stop as soon as control returns + to that frame. This is similar to the effect of a 'finish' command + in the frame inside the selected frame--except that 'finish' does + not leave an active breakpoint. If you use 'break' without an + argument in the innermost frame, GDB stops the next time it reaches + the current location; this may be useful inside loops. + + GDB normally ignores breakpoints when it resumes execution, until + at least one instruction has been executed. If it did not do this, + you would be unable to proceed past a breakpoint without first + disabling the breakpoint. This rule applies whether or not the + breakpoint already existed when your program stopped. + +'break ... if COND' + Set a breakpoint with condition COND; evaluate the expression COND + each time the breakpoint is reached, and stop only if the value is + nonzero--that is, if COND evaluates as true. '...' stands for one + of the possible arguments described above (or no argument) + specifying where to break. *Note Break Conditions: Conditions, for + more information on breakpoint conditions. + + The breakpoint may be mapped to multiple locations. If the + breakpoint condition COND is invalid at some but not all of the + locations, the locations for which the condition is invalid are + disabled. For example, GDB reports below that two of the three + locations are disabled. + + (gdb) break func if a == 10 + warning: failed to validate condition at location 0x11ce, disabling: + No symbol "a" in current context. + warning: failed to validate condition at location 0x11b6, disabling: + No symbol "a" in current context. + Breakpoint 1 at 0x11b6: func. (3 locations) + + Locations that are disabled because of the condition are denoted by + an uppercase 'N' in the output of the 'info breakpoints' command: + + (gdb) info breakpoints + Num Type Disp Enb Address What + 1 breakpoint keep y + stop only if a == 10 + 1.1 N* 0x00000000000011b6 in ... + 1.2 y 0x00000000000011c2 in ... + 1.3 N* 0x00000000000011ce in ... + (*): Breakpoint condition is invalid at this location. + + If the breakpoint condition COND is invalid in the context of _all_ + the locations of the breakpoint, GDB refuses to define the + breakpoint. For example, if variable 'foo' is an undefined + variable: + + (gdb) break func if foo + No symbol "foo" in current context. + +'break ... -force-condition if COND' + There may be cases where the condition COND is invalid at all the + current locations, but the user knows that it will be valid at a + future location; for example, because of a library load. In such + cases, by using the '-force-condition' keyword before 'if', GDB can + be forced to define the breakpoint with the given condition + expression instead of refusing it. + + (gdb) break func -force-condition if foo + warning: failed to validate condition at location 1, disabling: + No symbol "foo" in current context. + warning: failed to validate condition at location 2, disabling: + No symbol "foo" in current context. + warning: failed to validate condition at location 3, disabling: + No symbol "foo" in current context. + Breakpoint 1 at 0x1158: test.c:18. (3 locations) + + This causes all the present locations where the breakpoint would + otherwise be inserted, to be disabled, as seen in the example + above. However, if there exist locations at which the condition is + valid, the '-force-condition' keyword has no effect. + +'tbreak ARGS' + Set a breakpoint enabled only for one stop. The ARGS are the same + as for the 'break' command, and the breakpoint is set in the same + way, but the breakpoint is automatically deleted after the first + time your program stops there. *Note Disabling Breakpoints: + Disabling. + +'hbreak ARGS' + Set a hardware-assisted breakpoint. The ARGS are the same as for + the 'break' command and the breakpoint is set in the same way, but + the breakpoint requires hardware support and some target hardware + may not have this support. The main purpose of this is EPROM/ROM + code debugging, so you can set a breakpoint at an instruction + without changing the instruction. This can be used with the new + trap-generation provided by SPARClite DSU and most x86-based + targets. These targets will generate traps when a program accesses + some data or instruction address that is assigned to the debug + registers. However the hardware breakpoint registers can take a + limited number of breakpoints. For example, on the DSU, only two + data breakpoints can be set at a time, and GDB will reject this + command if more than two are used. Delete or disable unused + hardware breakpoints before setting new ones (*note Disabling + Breakpoints: Disabling.). *Note Break Conditions: Conditions. For + remote targets, you can restrict the number of hardware breakpoints + GDB will use, see *note set remote hardware-breakpoint-limit::. + +'thbreak ARGS' + Set a hardware-assisted breakpoint enabled only for one stop. The + ARGS are the same as for the 'hbreak' command and the breakpoint is + set in the same way. However, like the 'tbreak' command, the + breakpoint is automatically deleted after the first time your + program stops there. Also, like the 'hbreak' command, the + breakpoint requires hardware support and some target hardware may + not have this support. *Note Disabling Breakpoints: Disabling. + See also *note Break Conditions: Conditions. + +'rbreak REGEX' + Set breakpoints on all functions matching the regular expression + REGEX. This command sets an unconditional breakpoint on all + matches, printing a list of all breakpoints it set. Once these + breakpoints are set, they are treated just like the breakpoints set + with the 'break' command. You can delete them, disable them, or + make them conditional the same way as any other breakpoint. + + In programs using different languages, GDB chooses the syntax to + print the list of all breakpoints it sets according to the 'set + language' value: using 'set language auto' (see *note Set Language + Automatically: Automatically.) means to use the language of the + breakpoint's function, other values mean to use the manually + specified language (see *note Set Language Manually: Manually.). + + The syntax of the regular expression is the standard one used with + tools like 'grep'. Note that this is different from the syntax + used by shells, so for instance 'foo*' matches all functions that + include an 'fo' followed by zero or more 'o's. There is an + implicit '.*' leading and trailing the regular expression you + supply, so to match only functions that begin with 'foo', use + '^foo'. + + When debugging C++ programs, 'rbreak' is useful for setting + breakpoints on overloaded functions that are not members of any + special classes. + + The 'rbreak' command can be used to set breakpoints in *all* the + functions in a program, like this: + + (gdb) rbreak . + +'rbreak FILE:REGEX' + If 'rbreak' is called with a filename qualification, it limits the + search for functions matching the given regular expression to the + specified FILE. This can be used, for example, to set breakpoints + on every function in a given file: + + (gdb) rbreak file.c:. + + The colon separating the filename qualifier from the regex may + optionally be surrounded by spaces. + +'info breakpoints [LIST...]' +'info break [LIST...]' + Print a table of all breakpoints, watchpoints, tracepoints, and + catchpoints set and not deleted. Optional argument N means print + information only about the specified breakpoint(s) (or + watchpoint(s) or tracepoint(s) or catchpoint(s)). For each + breakpoint, following columns are printed: + + _Breakpoint Numbers_ + _Type_ + Breakpoint, watchpoint, tracepoint, or catchpoint. + _Disposition_ + Whether the breakpoint is marked to be disabled or deleted + when hit. + _Enabled or Disabled_ + Enabled breakpoints are marked with 'y'. 'n' marks + breakpoints that are not enabled. + _Address_ + Where the breakpoint is in your program, as a memory address. + For a pending breakpoint whose address is not yet known, this + field will contain ''. Such breakpoint won't fire + until a shared library that has the symbol or line referred by + breakpoint is loaded. See below for details. A breakpoint + with several locations will have '' in this + field--see below for details. + _What_ + Where the breakpoint is in the source for your program, as a + file and line number. For a pending breakpoint, the original + string passed to the breakpoint command will be listed as it + cannot be resolved until the appropriate shared library is + loaded in the future. + + If a breakpoint is conditional, there are two evaluation modes: + "host" and "target". If mode is "host", breakpoint condition + evaluation is done by GDB on the host's side. If it is "target", + then the condition is evaluated by the target. The 'info break' + command shows the condition on the line following the affected + breakpoint, together with its condition evaluation mode in between + parentheses. + + Breakpoint commands, if any, are listed after that. A pending + breakpoint is allowed to have a condition specified for it. The + condition is not parsed for validity until a shared library is + loaded that allows the pending breakpoint to resolve to a valid + location. + + 'info break' with a breakpoint number N as argument lists only that + breakpoint. The convenience variable '$_' and the default + examining-address for the 'x' command are set to the address of the + last breakpoint listed (*note Examining Memory: Memory.). + + 'info break' displays a count of the number of times the breakpoint + has been hit. This is especially useful in conjunction with the + 'ignore' command. You can ignore a large number of breakpoint + hits, look at the breakpoint info to see how many times the + breakpoint was hit, and then run again, ignoring one less than that + number. This will get you quickly to the last hit of that + breakpoint. + + For a breakpoints with an enable count (xref) greater than 1, 'info + break' also displays that count. + + GDB allows you to set any number of breakpoints at the same place in +your program. There is nothing silly or meaningless about this. When +the breakpoints are conditional, this is even useful (*note Break +Conditions: Conditions.). + + It is possible that a single logical breakpoint is set at several +code locations in your program. *Note Location Specifications::, for +examples. + + A breakpoint with multiple code locations is displayed in the +breakpoint table using several rows--one header row, followed by one row +for each code location. The header row has '' in the address +column. Each code location row contains the actual address, source +file, source line and function of its code location. The number column +for a code location is of the form BREAKPOINT-NUMBER.LOCATION-NUMBER. + + For example: + + Num Type Disp Enb Address What + 1 breakpoint keep y + stop only if i==1 + breakpoint already hit 1 time + 1.1 y 0x080486a2 in void foo() at t.cc:8 + 1.2 y 0x080486ca in void foo() at t.cc:8 + + You cannot delete the individual locations from a breakpoint. +However, each location can be individually enabled or disabled by +passing BREAKPOINT-NUMBER.LOCATION-NUMBER as argument to the 'enable' +and 'disable' commands. It's also possible to 'enable' and 'disable' a +range of LOCATION-NUMBER locations using a BREAKPOINT-NUMBER and two +LOCATION-NUMBERs, in increasing order, separated by a hyphen, like +'BREAKPOINT-NUMBER.LOCATION-NUMBER1-LOCATION-NUMBER2', in which case GDB +acts on all the locations in the range (inclusive). Disabling or +enabling the parent breakpoint (*note Disabling::) affects all of the +locations that belong to that breakpoint. + + Locations that are enabled while their parent breakpoint is disabled +won't trigger a break, and are denoted by 'y-' in the 'Enb' column. For +example: + + (gdb) info breakpoints + Num Type Disp Enb Address What + 1 breakpoint keep n + 1.1 y- 0x00000000000011b6 in ... + 1.2 y- 0x00000000000011c2 in ... + 1.3 n 0x00000000000011ce in ... + + It's quite common to have a breakpoint inside a shared library. +Shared libraries can be loaded and unloaded explicitly, and possibly +repeatedly, as the program is executed. To support this use case, GDB +updates breakpoint locations whenever any shared library is loaded or +unloaded. Typically, you would set a breakpoint in a shared library at +the beginning of your debugging session, when the library is not loaded, +and when the symbols from the library are not available. When you try +to set breakpoint, GDB will ask you if you want to set a so called +"pending breakpoint"--breakpoint whose address is not yet resolved. + + After the program is run, whenever a new shared library is loaded, +GDB reevaluates all the breakpoints. When a newly loaded shared library +contains the symbol or line referred to by some pending breakpoint, that +breakpoint is resolved and becomes an ordinary breakpoint. When a +library is unloaded, all breakpoints that refer to its symbols or source +lines become pending again. + + This logic works for breakpoints with multiple locations, too. For +example, if you have a breakpoint in a C++ template function, and a +newly loaded shared library has an instantiation of that template, a new +location is added to the list of locations for the breakpoint. + + Except for having unresolved address, pending breakpoints do not +differ from regular breakpoints. You can set conditions or commands, +enable and disable them and perform other breakpoint operations. + + GDB provides some additional commands for controlling what happens +when the 'break' command cannot resolve the location spec to any code +location in your program (*note Location Specifications::): + +'set breakpoint pending auto' + This is the default behavior. When GDB cannot resolve the location + spec, it queries you whether a pending breakpoint should be + created. + +'set breakpoint pending on' + This indicates that when GDB cannot resolve the location spec, it + should create a pending breakpoint without confirmation. + +'set breakpoint pending off' + This indicates that pending breakpoints are not to be created. If + GDB cannot resolve the location spec, it aborts the breakpoint + creation with an error. This setting does not affect any pending + breakpoints previously created. + +'show breakpoint pending' + Show the current behavior setting for creating pending breakpoints. + + The settings above only affect the 'break' command and its variants. +Once a breakpoint is set, it will be automatically updated as shared +libraries are loaded and unloaded. + + For some targets, GDB can automatically decide if hardware or +software breakpoints should be used, depending on whether the breakpoint +address is read-only or read-write. This applies to breakpoints set +with the 'break' command as well as to internal breakpoints set by +commands like 'next' and 'finish'. For breakpoints set with 'hbreak', +GDB will always use hardware breakpoints. + + You can control this automatic behavior with the following commands: + +'set breakpoint auto-hw on' + This is the default behavior. When GDB sets a breakpoint, it will + try to use the target memory map to decide if software or hardware + breakpoint must be used. + +'set breakpoint auto-hw off' + This indicates GDB should not automatically select breakpoint type. + If the target provides a memory map, GDB will warn when trying to + set software breakpoint at a read-only address. + + GDB normally implements breakpoints by replacing the program code at +the breakpoint address with a special instruction, which, when executed, +given control to the debugger. By default, the program code is so +modified only when the program is resumed. As soon as the program +stops, GDB restores the original instructions. This behavior guards +against leaving breakpoints inserted in the target should gdb abrubptly +disconnect. However, with slow remote targets, inserting and removing +breakpoint can reduce the performance. This behavior can be controlled +with the following commands:: + +'set breakpoint always-inserted off' + All breakpoints, including newly added by the user, are inserted in + the target only when the target is resumed. All breakpoints are + removed from the target when it stops. This is the default mode. + +'set breakpoint always-inserted on' + Causes all breakpoints to be inserted in the target at all times. + If the user adds a new breakpoint, or changes an existing + breakpoint, the breakpoints in the target are updated immediately. + A breakpoint is removed from the target only when breakpoint itself + is deleted. + + GDB handles conditional breakpoints by evaluating these conditions +when a breakpoint breaks. If the condition is true, then the process +being debugged stops, otherwise the process is resumed. + + If the target supports evaluating conditions on its end, GDB may +download the breakpoint, together with its conditions, to it. + + This feature can be controlled via the following commands: + +'set breakpoint condition-evaluation host' + This option commands GDB to evaluate the breakpoint conditions on + the host's side. Unconditional breakpoints are sent to the target + which in turn receives the triggers and reports them back to GDB + for condition evaluation. This is the standard evaluation mode. + +'set breakpoint condition-evaluation target' + This option commands GDB to download breakpoint conditions to the + target at the moment of their insertion. The target is responsible + for evaluating the conditional expression and reporting breakpoint + stop events back to GDB whenever the condition is true. Due to + limitations of target-side evaluation, some conditions cannot be + evaluated there, e.g., conditions that depend on local data that is + only known to the host. Examples include conditional expressions + involving convenience variables, complex types that cannot be + handled by the agent expression parser and expressions that are too + long to be sent over to the target, specially when the target is a + remote system. In these cases, the conditions will be evaluated by + GDB. + +'set breakpoint condition-evaluation auto' + This is the default mode. If the target supports evaluating + breakpoint conditions on its end, GDB will download breakpoint + conditions to the target (limitations mentioned previously apply). + If the target does not support breakpoint condition evaluation, + then GDB will fallback to evaluating all these conditions on the + host's side. + + GDB itself sometimes sets breakpoints in your program for special +purposes, such as proper handling of 'longjmp' (in C programs). These +internal breakpoints are assigned negative numbers, starting with '-1'; +'info breakpoints' does not display them. You can see these breakpoints +with the GDB maintenance command 'maint info breakpoints' (*note maint +info breakpoints::). + + +File: gdb.info, Node: Set Watchpoints, Next: Set Catchpoints, Prev: Set Breaks, Up: Breakpoints + +5.1.2 Setting Watchpoints +------------------------- + +You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. (This is sometimes called a "data breakpoint".) The +expression may be as simple as the value of a single variable, or as +complex as many variables combined by operators. Examples include: + + * A reference to the value of a single variable. + + * An address cast to an appropriate data type. For example, '*(int + *)0x12345678' will watch a 4-byte region at the specified address + (assuming an 'int' occupies 4 bytes). + + * An arbitrarily complex expression, such as 'a*b + c/d'. The + expression can use any operators valid in the program's native + language (*note Languages::). + + You can set a watchpoint on an expression even if the expression can +not be evaluated yet. For instance, you can set a watchpoint on +'*global_ptr' before 'global_ptr' is initialized. GDB will stop when +your program sets 'global_ptr' and the expression produces a valid +value. If the expression becomes valid in some other way than changing +a variable (e.g. if the memory pointed to by '*global_ptr' becomes +readable as the result of a 'malloc' call), GDB may not stop until the +next time the expression changes. + + Depending on your system, watchpoints may be implemented in software +or hardware. GDB does software watchpointing by single-stepping your +program and testing the variable's value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) + + On some systems, such as most PowerPC or x86-based targets, GDB +includes support for hardware watchpoints, which do not slow down the +running of your program. + +'watch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE] [task TASK-ID]' + Set a watchpoint for an expression. GDB will break when the + expression EXPR is written into by the program and its value + changes. The simplest (and the most popular) use of this command + is to watch the value of a single variable: + + (gdb) watch foo + + If the command includes a '[thread THREAD-ID]' argument, GDB breaks + only when the thread identified by THREAD-ID changes the value of + EXPR. If any other threads change the value of EXPR, GDB will not + break. Note that watchpoints restricted to a single thread in this + way only work with Hardware Watchpoints. + + Similarly, if the 'task' argument is given, then the watchpoint + will be specific to the indicated Ada task (*note Ada Tasks::). + + Ordinarily a watchpoint respects the scope of variables in EXPR + (see below). The '-location' argument tells GDB to instead watch + the memory referred to by EXPR. In this case, GDB will evaluate + EXPR, take the address of the result, and watch the memory at that + address. The type of the result is used to determine the size of + the watched memory. If the expression's result does not have an + address, then GDB will print an error. + + The '[mask MASKVALUE]' argument allows creation of masked + watchpoints, if the current architecture supports this feature + (e.g., PowerPC Embedded architecture, see *note PowerPC + Embedded::.) A "masked watchpoint" specifies a mask in addition to + an address to watch. The mask specifies that some bits of an + address (the bits which are reset in the mask) should be ignored + when matching the address accessed by the inferior against the + watchpoint address. Thus, a masked watchpoint watches many + addresses simultaneously--those addresses whose unmasked bits are + identical to the unmasked bits in the watchpoint address. The + 'mask' argument implies '-location'. Examples: + + (gdb) watch foo mask 0xffff00ff + (gdb) watch *0xdeadbeef mask 0xffffff00 + +'rwatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]' + Set a watchpoint that will break when the value of EXPR is read by + the program. + +'awatch [-l|-location] EXPR [thread THREAD-ID] [mask MASKVALUE]' + Set a watchpoint that will break when EXPR is either read from or + written into by the program. + +'info watchpoints [LIST...]' + This command prints a list of watchpoints, using the same format as + 'info break' (*note Set Breaks::). + + If you watch for a change in a numerically entered address you need +to dereference it, as the address itself is just a constant number which +will never change. GDB refuses to create a watchpoint that watches a +never-changing value: + + (gdb) watch 0x600850 + Cannot watch constant value 0x600850. + (gdb) watch *(int *) 0x600850 + Watchpoint 1: *(int *) 6293584 + + GDB sets a "hardware watchpoint" if possible. Hardware watchpoints +execute very quickly, and the debugger reports a change in value at the +exact instruction where the change occurs. If GDB cannot set a hardware +watchpoint, it sets a software watchpoint, which executes more slowly +and reports the change in value at the next _statement_, not the +instruction, after the change occurs. + + You can force GDB to use only software watchpoints with the 'set +can-use-hw-watchpoints 0' command. With this variable set to zero, GDB +will never try to use hardware watchpoints, even if the underlying +system supports them. (Note that hardware-assisted watchpoints that +were set _before_ setting 'can-use-hw-watchpoints' to zero will still +use the hardware mechanism of watching expression values.) + +'set can-use-hw-watchpoints' + Set whether or not to use hardware watchpoints. + +'show can-use-hw-watchpoints' + Show the current mode of using hardware watchpoints. + + For remote targets, you can restrict the number of hardware +watchpoints GDB will use, see *note set remote +hardware-breakpoint-limit::. + + When you issue the 'watch' command, GDB reports + + Hardware watchpoint NUM: EXPR + +if it was able to set a hardware watchpoint. + + Currently, the 'awatch' and 'rwatch' commands can only set hardware +watchpoints, because accesses to data that don't change the value of the +watched expression cannot be detected without examining every +instruction as it is being executed, and GDB does not do that currently. +If GDB finds that it is unable to set a hardware breakpoint with the +'awatch' or 'rwatch' command, it will print a message like this: + + Expression cannot be implemented with read/access watchpoint. + + Sometimes, GDB cannot set a hardware watchpoint because the data type +of the watched expression is wider than what a hardware watchpoint on +the target machine can handle. For example, some systems can only watch +regions that are up to 4 bytes wide; on such systems you cannot set +hardware watchpoints for an expression that yields a double-precision +floating-point number (which is typically 8 bytes wide). As a +work-around, it might be possible to break the large region into a +series of smaller ones and watch them with separate watchpoints. + + If you set too many hardware watchpoints, GDB might be unable to +insert all of them when you resume the execution of your program. Since +the precise number of active watchpoints is unknown until such time as +the program is about to be resumed, GDB might not be able to warn you +about this when you set the watchpoints, and the warning will be printed +only when the program is resumed: + + Hardware watchpoint NUM: Could not insert watchpoint + +If this happens, delete or disable some of the watchpoints. + + Watching complex expressions that reference many variables can also +exhaust the resources available for hardware-assisted watchpoints. +That's because GDB needs to watch every variable in the expression with +separately allocated resources. + + If you call a function interactively using 'print' or 'call', any +watchpoints you have set will be inactive until GDB reaches another kind +of breakpoint or the call completes. + + GDB automatically deletes watchpoints that watch local (automatic) +variables, or expressions that involve such variables, when they go out +of scope, that is, when the execution leaves the block in which these +variables were defined. In particular, when the program being debugged +terminates, _all_ local variables go out of scope, and so only +watchpoints that watch global variables remain set. If you rerun the +program, you will need to set all such watchpoints again. One way of +doing that would be to set a code breakpoint at the entry to the 'main' +function and when it breaks, set all the watchpoints. + + In multi-threaded programs, watchpoints will detect changes to the +watched expression from every thread. + + _Warning:_ In multi-threaded programs, software watchpoints have + only limited usefulness. If GDB creates a software watchpoint, it + can only watch the value of an expression _in a single thread_. If + you are confident that the expression can only change due to the + current thread's activity (and if you are also confident that no + other thread can become current), then you can use software + watchpoints as usual. However, GDB may not notice when a + non-current thread's activity changes the expression. (Hardware + watchpoints, in contrast, watch an expression in all threads.) + + *Note set remote hardware-watchpoint-limit::. + + +File: gdb.info, Node: Set Catchpoints, Next: Delete Breaks, Prev: Set Watchpoints, Up: Breakpoints + +5.1.3 Setting Catchpoints +------------------------- + +You can use "catchpoints" to cause the debugger to stop for certain +kinds of program events, such as C++ exceptions or the loading of a +shared library. Use the 'catch' command to set a catchpoint. + +'catch EVENT' + Stop when EVENT occurs. The EVENT can be any of the following: + + 'throw [REGEXP]' + 'rethrow [REGEXP]' + 'catch [REGEXP]' + The throwing, re-throwing, or catching of a C++ exception. + + If REGEXP is given, then only exceptions whose type matches + the regular expression will be caught. + + The convenience variable '$_exception' is available at an + exception-related catchpoint, on some systems. This holds the + exception being thrown. + + There are currently some limitations to C++ exception handling + in GDB: + + * The support for these commands is system-dependent. + Currently, only systems using the 'gnu-v3' C++ ABI (*note + ABI::) are supported. + + * The regular expression feature and the '$_exception' + convenience variable rely on the presence of some SDT + probes in 'libstdc++'. If these probes are not present, + then these features cannot be used. These probes were + first available in the GCC 4.8 release, but whether or + not they are available in your GCC also depends on how it + was built. + + * The '$_exception' convenience variable is only valid at + the instruction at which an exception-related catchpoint + is set. + + * When an exception-related catchpoint is hit, GDB stops at + a location in the system library which implements runtime + exception support for C++, usually 'libstdc++'. You can + use 'up' (*note Selection::) to get to your code. + + * If you call a function interactively, GDB normally + returns control to you when the function has finished + executing. If the call raises an exception, however, the + call may bypass the mechanism that returns control to you + and cause your program either to abort or to simply + continue running until it hits a breakpoint, catches a + signal that GDB is listening for, or exits. This is the + case even if you set a catchpoint for the exception; + catchpoints on exceptions are disabled within interactive + calls. *Note Calling::, for information on controlling + this with 'set unwind-on-terminating-exception'. + + * You cannot raise an exception interactively. + + * You cannot install an exception handler interactively. + + 'exception [NAME]' + An Ada exception being raised. If an exception name is + specified at the end of the command (eg 'catch exception + Program_Error'), the debugger will stop only when this + specific exception is raised. Otherwise, the debugger stops + execution when any Ada exception is raised. + + When inserting an exception catchpoint on a user-defined + exception whose name is identical to one of the exceptions + defined by the language, the fully qualified name must be used + as the exception name. Otherwise, GDB will assume that it + should stop on the pre-defined exception rather than the + user-defined one. For instance, assuming an exception called + 'Constraint_Error' is defined in package 'Pck', then the + command to use to catch such exceptions is 'catch exception + Pck.Constraint_Error'. + + The convenience variable '$_ada_exception' holds the address + of the exception being thrown. This can be useful when + setting a condition for such a catchpoint. + + 'exception unhandled' + An exception that was raised but is not handled by the + program. The convenience variable '$_ada_exception' is set as + for 'catch exception'. + + 'handlers [NAME]' + An Ada exception being handled. If an exception name is + specified at the end of the command (eg 'catch handlers + Program_Error'), the debugger will stop only when this + specific exception is handled. Otherwise, the debugger stops + execution when any Ada exception is handled. + + When inserting a handlers catchpoint on a user-defined + exception whose name is identical to one of the exceptions + defined by the language, the fully qualified name must be used + as the exception name. Otherwise, GDB will assume that it + should stop on the pre-defined exception rather than the + user-defined one. For instance, assuming an exception called + 'Constraint_Error' is defined in package 'Pck', then the + command to use to catch such exceptions handling is 'catch + handlers Pck.Constraint_Error'. + + The convenience variable '$_ada_exception' is set as for + 'catch exception'. + + 'assert' + A failed Ada assertion. Note that the convenience variable + '$_ada_exception' is _not_ set by this catchpoint. + + 'exec' + A call to 'exec'. + + 'syscall' + 'syscall [NAME | NUMBER | group:GROUPNAME | g:GROUPNAME] ...' + A call to or return from a system call, a.k.a. "syscall". A + syscall is a mechanism for application programs to request a + service from the operating system (OS) or one of the OS system + services. GDB can catch some or all of the syscalls issued by + the debuggee, and show the related information for each + syscall. If no argument is specified, calls to and returns + from all system calls will be caught. + + NAME can be any system call name that is valid for the + underlying OS. Just what syscalls are valid depends on the OS. + On GNU and Unix systems, you can find the full list of valid + syscall names on '/usr/include/asm/unistd.h'. + + Normally, GDB knows in advance which syscalls are valid for + each OS, so you can use the GDB command-line completion + facilities (*note command completion: Completion.) to list the + available choices. + + You may also specify the system call numerically. A syscall's + number is the value passed to the OS's syscall dispatcher to + identify the requested service. When you specify the syscall + by its name, GDB uses its database of syscalls to convert the + name into the corresponding numeric code, but using the number + directly may be useful if GDB's database does not have the + complete list of syscalls on your system (e.g., because GDB + lags behind the OS upgrades). + + You may specify a group of related syscalls to be caught at + once using the 'group:' syntax ('g:' is a shorter equivalent). + For instance, on some platforms GDB allows you to catch all + network related syscalls, by passing the argument + 'group:network' to 'catch syscall'. Note that not all syscall + groups are available in every system. You can use the command + completion facilities (*note command completion: Completion.) + to list the syscall groups available on your environment. + + The example below illustrates how this command works if you + don't provide arguments to it: + + (gdb) catch syscall + Catchpoint 1 (syscall) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + Here is an example of catching a system call by name: + + (gdb) catch syscall chroot + Catchpoint 1 (syscall 'chroot' [61]) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Catchpoint 1 (returned from syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) + + An example of specifying a system call numerically. In the + case below, the syscall number has a corresponding entry in + the XML file, so GDB finds its name and prints it: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 'exit_group') + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall 'exit_group'), \ + 0xffffe424 in __kernel_vsyscall () + (gdb) c + Continuing. + + Program exited normally. + (gdb) + + Here is an example of catching a syscall group: + + (gdb) catch syscall group:process + Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] + 'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] + 'exit_group' [252] 'waitid' [284] 'unshare' [310]) + (gdb) r + Starting program: /tmp/catch-syscall + + Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () + from /lib64/ld-linux-x86-64.so.2 + + (gdb) c + Continuing. + + However, there can be situations when there is no + corresponding name in XML file for that syscall number. In + this case, GDB prints a warning message saying that it was not + able to find the syscall name, but the catchpoint will be set + anyway. See the example below: + + (gdb) catch syscall 764 + warning: The number '764' does not represent a known syscall. + Catchpoint 2 (syscall 764) + (gdb) + + If you configure GDB using the '--without-expat' option, it + will not be able to display syscall names. Also, if your + architecture does not have an XML file describing its system + calls, you will not be able to see the syscall names. It is + important to notice that these two features are used for + accessing the syscall name database. In either case, you will + see a warning like this: + + (gdb) catch syscall + warning: Could not open "syscalls/i386-linux.xml" + warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. + GDB will not be able to display syscall names. + Catchpoint 1 (syscall) + (gdb) + + Of course, the file name will change depending on your + architecture and system. + + Still using the example above, you can also try to catch a + syscall by its number. In this case, you would see something + like: + + (gdb) catch syscall 252 + Catchpoint 1 (syscall(s) 252) + + Again, in this case GDB would not be able to display syscall's + names. + + 'fork' + A call to 'fork'. + + 'vfork' + A call to 'vfork'. + + 'load [REGEXP]' + 'unload [REGEXP]' + The loading or unloading of a shared library. If REGEXP is + given, then the catchpoint will stop only if the regular + expression matches one of the affected libraries. + + 'signal [SIGNAL... | 'all']' + The delivery of a signal. + + With no arguments, this catchpoint will catch any signal that + is not used internally by GDB, specifically, all signals + except 'SIGTRAP' and 'SIGINT'. + + With the argument 'all', all signals, including those used by + GDB, will be caught. This argument cannot be used with other + signal names. + + Otherwise, the arguments are a list of signal names as given + to 'handle' (*note Signals::). Only signals specified in this + list will be caught. + + One reason that 'catch signal' can be more useful than + 'handle' is that you can attach commands and conditions to the + catchpoint. + + When a signal is caught by a catchpoint, the signal's 'stop' + and 'print' settings, as specified by 'handle', are ignored. + However, whether the signal is still delivered to the inferior + depends on the 'pass' setting; this can be changed in the + catchpoint's commands. + +'tcatch EVENT' + Set a catchpoint that is enabled only for one stop. The catchpoint + is automatically deleted after the first time the event is caught. + + Use the 'info break' command to list the current catchpoints. + + +File: gdb.info, Node: Delete Breaks, Next: Disabling, Prev: Set Catchpoints, Up: Breakpoints + +5.1.4 Deleting Breakpoints +-------------------------- + +It is often necessary to eliminate a breakpoint, watchpoint, or +catchpoint once it has done its job and you no longer want your program +to stop there. This is called "deleting" the breakpoint. A breakpoint +that has been deleted no longer exists; it is forgotten. + + With the 'clear' command you can delete breakpoints according to +where they are in your program. With the 'delete' command you can +delete individual breakpoints, watchpoints, or catchpoints by specifying +their breakpoint numbers. + + It is not necessary to delete a breakpoint to proceed past it. GDB +automatically ignores breakpoints on the first instruction to be +executed when you continue execution without changing the execution +address. + +'clear' + Delete any breakpoints at the next instruction to be executed in + the selected stack frame (*note Selecting a Frame: Selection.). + When the innermost frame is selected, this is a good way to delete + a breakpoint where your program just stopped. + +'clear LOCSPEC' + Delete any breakpoint with a code location that corresponds to + LOCSPEC. *Note Location Specifications::, for the various forms of + LOCSPEC. Which code locations correspond to LOCSPEC depends on the + form used in the location specification LOCSPEC: + + 'LINENUM' + 'FILENAME:LINENUM' + '-line LINENUM' + '-source FILENAME -line LINENUM' + If LOCSPEC specifies a line number, with or without a file + name, the command deletes any breakpoint with a code location + that is at or within the specified line LINENUM in files that + match the specified FILENAME. If FILENAME is omitted, it + defaults to the current source file. + + '*ADDRESS' + If LOCSPEC specifies an address, the command deletes any + breakpoint with a code location that is at the given ADDRESS. + + 'FUNCTION' + '-function FUNCTION' + If LOCSPEC specifies a function, the command deletes any + breakpoint with a code location that is at the entry to any + function whose name matches FUNCTION. + + Ambiguity in names of files and functions can be resolved as + described in *note Location Specifications::. + +'delete [breakpoints] [LIST...]' + Delete the breakpoints, watchpoints, tracepoints, or catchpoints of + the breakpoint list specified as argument. If no argument is + specified, delete all breakpoints, watchpoints, tracepoints, and + catchpoints (GDB asks confirmation, unless you have 'set confirm + off'). You can abbreviate this command as 'd'. + + +File: gdb.info, Node: Disabling, Next: Conditions, Prev: Delete Breaks, Up: Breakpoints + +5.1.5 Disabling Breakpoints +--------------------------- + +Rather than deleting a breakpoint, watchpoint, or catchpoint, you might +prefer to "disable" it. This makes the breakpoint inoperative as if it +had been deleted, but remembers the information on the breakpoint so +that you can "enable" it again later. + + You disable and enable breakpoints, watchpoints, tracepoints, and +catchpoints with the 'enable' and 'disable' commands, optionally +specifying one or more breakpoint numbers as arguments. Use 'info +break' to print a list of all breakpoints, watchpoints, tracepoints, and +catchpoints if you do not know which numbers to use. + + Disabling and enabling a breakpoint that has multiple locations +affects all of its locations. + + A breakpoint, watchpoint, or catchpoint can have any of several +different states of enablement: + + * Enabled. The breakpoint stops your program. A breakpoint set with + the 'break' command starts out in this state. + * Disabled. The breakpoint has no effect on your program. + * Enabled once. The breakpoint stops your program, but then becomes + disabled. + * Enabled for a count. The breakpoint stops your program for the + next N times, then becomes disabled. + * Enabled for deletion. The breakpoint stops your program, but + immediately after it does so it is deleted permanently. A + breakpoint set with the 'tbreak' command starts out in this state. + + You can use the following commands to enable or disable breakpoints, +watchpoints, tracepoints, and catchpoints: + +'disable [breakpoints] [LIST...]' + Disable the specified breakpoints--or all breakpoints, if none are + listed. A disabled breakpoint has no effect but is not forgotten. + All options such as ignore-counts, conditions and commands are + remembered in case the breakpoint is enabled again later. You may + abbreviate 'disable' as 'dis'. + +'enable [breakpoints] [LIST...]' + Enable the specified breakpoints (or all defined breakpoints). + They become effective once again in stopping your program. + +'enable [breakpoints] once LIST...' + Enable the specified breakpoints temporarily. GDB disables any of + these breakpoints immediately after stopping your program. + +'enable [breakpoints] count COUNT LIST...' + Enable the specified breakpoints temporarily. GDB records COUNT + with each of the specified breakpoints, and decrements a + breakpoint's count when it is hit. When any count reaches 0, GDB + disables that breakpoint. If a breakpoint has an ignore count + (*note Break Conditions: Conditions.), that will be decremented to + 0 before COUNT is affected. + +'enable [breakpoints] delete LIST...' + Enable the specified breakpoints to work once, then die. GDB + deletes any of these breakpoints as soon as your program stops + there. Breakpoints set by the 'tbreak' command start out in this + state. + + Except for a breakpoint set with 'tbreak' (*note Setting Breakpoints: +Set Breaks.), breakpoints that you set are initially enabled; +subsequently, they become disabled or enabled only when you use one of +the commands above. (The command 'until' can set and delete a +breakpoint of its own, but it does not change the state of your other +breakpoints; see *note Continuing and Stepping: Continuing and +Stepping.) + + +File: gdb.info, Node: Conditions, Next: Break Commands, Prev: Disabling, Up: Breakpoints + +5.1.6 Break Conditions +---------------------- + +The simplest sort of breakpoint breaks every time your program reaches a +specified place. You can also specify a "condition" for a breakpoint. +A condition is just a Boolean expression in your programming language +(*note Expressions: Expressions.). A breakpoint with a condition +evaluates the expression each time your program reaches it, and your +program stops only if the condition is _true_. + + This is the converse of using assertions for program validation; in +that situation, you want to stop when the assertion is violated--that +is, when the condition is false. In C, if you want to test an assertion +expressed by the condition ASSERT, you should set the condition '! +ASSERT' on the appropriate breakpoint. + + Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow--but +it might be simpler, say, to just set a watchpoint on a variable name, +and specify a condition that tests whether the new value is an +interesting one. + + Break conditions can have side effects, and may even call functions +in your program. This can be useful, for example, to activate functions +that log program progress, or to use your own print functions to format +special data structures. The effects are completely predictable unless +there is another enabled breakpoint at the same address. (In that case, +GDB might see the other breakpoint first and stop your program without +checking the condition of this one.) Note that breakpoint commands are +usually more convenient and flexible than break conditions for the +purpose of performing side effects when a breakpoint is reached (*note +Breakpoint Command Lists: Break Commands.). + + Breakpoint conditions can also be evaluated on the target's side if +the target supports it. Instead of evaluating the conditions locally, +GDB encodes the expression into an agent expression (*note Agent +Expressions::) suitable for execution on the target, independently of +GDB. Global variables become raw memory locations, locals become stack +accesses, and so forth. + + In this case, GDB will only be notified of a breakpoint trigger when +its condition evaluates to true. This mechanism may provide faster +response times depending on the performance characteristics of the +target since it does not need to keep GDB informed about every +breakpoint trigger, even those with false conditions. + + Break conditions can be specified when a breakpoint is set, by using +'if' in the arguments to the 'break' command. *Note Setting +Breakpoints: Set Breaks. They can also be changed at any time with the +'condition' command. + + You can also use the 'if' keyword with the 'watch' command. The +'catch' command does not recognize the 'if' keyword; 'condition' is the +only way to impose a further condition on a catchpoint. + +'condition BNUM EXPRESSION' + Specify EXPRESSION as the break condition for breakpoint, + watchpoint, or catchpoint number BNUM. After you set a condition, + breakpoint BNUM stops your program only if the value of EXPRESSION + is true (nonzero, in C). When you use 'condition', GDB checks + EXPRESSION immediately for syntactic correctness, and to determine + whether symbols in it have referents in the context of your + breakpoint. If EXPRESSION uses symbols not referenced in the + context of the breakpoint, GDB prints an error message: + + No symbol "foo" in current context. + + GDB does not actually evaluate EXPRESSION at the time the + 'condition' command (or a command that sets a breakpoint with a + condition, like 'break if ...') is given, however. *Note + Expressions: Expressions. + +'condition -force BNUM EXPRESSION' + When the '-force' flag is used, define the condition even if + EXPRESSION is invalid at all the current locations of breakpoint + BNUM. This is similar to the '-force-condition' option of the + 'break' command. + +'condition BNUM' + Remove the condition from breakpoint number BNUM. It becomes an + ordinary unconditional breakpoint. + + A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the "ignore count" of +the breakpoint. Every breakpoint has an ignore count, which is an +integer. Most of the time, the ignore count is zero, and therefore has +no effect. But if your program reaches a breakpoint whose ignore count +is positive, then instead of stopping, it just decrements the ignore +count by one and continues. As a result, if the ignore count value is +N, the breakpoint does not stop the next N times your program reaches +it. + +'ignore BNUM COUNT' + Set the ignore count of breakpoint number BNUM to COUNT. The next + COUNT times the breakpoint is reached, your program's execution + does not stop; other than to decrement the ignore count, GDB takes + no action. + + To make the breakpoint stop the next time it is reached, specify a + count of zero. + + When you use 'continue' to resume execution of your program from a + breakpoint, you can specify an ignore count directly as an argument + to 'continue', rather than using 'ignore'. *Note Continuing and + Stepping: Continuing and Stepping. + + If a breakpoint has a positive ignore count and a condition, the + condition is not checked. Once the ignore count reaches zero, GDB + resumes checking the condition. + + You could achieve the effect of the ignore count with a condition + such as '$foo-- <= 0' using a debugger convenience variable that is + decremented each time. *Note Convenience Variables: Convenience + Vars. + + Ignore counts apply to breakpoints, watchpoints, tracepoints, and +catchpoints. + + +File: gdb.info, Node: Break Commands, Next: Dynamic Printf, Prev: Conditions, Up: Breakpoints + +5.1.7 Breakpoint Command Lists +------------------------------ + +You can give any breakpoint (or watchpoint or catchpoint) a series of +commands to execute when your program stops due to that breakpoint. For +example, you might want to print the values of certain expressions, or +enable other breakpoints. + +'commands [LIST...]' +'... COMMAND-LIST ...' +'end' + Specify a list of commands for the given breakpoints. The commands + themselves appear on the following lines. Type a line containing + just 'end' to terminate the commands. + + To remove all commands from a breakpoint, type 'commands' and + follow it immediately with 'end'; that is, give no commands. + + With no argument, 'commands' refers to the last breakpoint, + watchpoint, or catchpoint set (not to the breakpoint most recently + encountered). If the most recent breakpoints were set with a + single command, then the 'commands' will apply to all the + breakpoints set by that command. This applies to breakpoints set + by 'rbreak', and also applies when a single 'break' command creates + multiple breakpoints (*note Ambiguous Expressions: Ambiguous + Expressions.). + + Pressing as a means of repeating the last GDB command is +disabled within a COMMAND-LIST. + + Inside a command list, you can use the command 'disable $_hit_bpnum' +to disable the encountered breakpoint. + + If your breakpoint has several code locations, the command 'disable +$_hit_bpnum.$_hit_locno' will disable the specific breakpoint code +location encountered. If the breakpoint has only one location, this +command will disable the encountered breakpoint. + + You can use breakpoint commands to start your program up again. +Simply use the 'continue' command, or 'step', or any other command that +resumes execution. + + Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple 'next' or 'step'), you may encounter another +breakpoint--which could have its own command list, leading to +ambiguities about which list to execute. + + If the first command you specify in a command list is 'silent', the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +see no sign that the breakpoint was reached. 'silent' is meaningful +only at the beginning of a breakpoint command list. + + The commands 'echo', 'output', and 'printf' allow you to print +precisely controlled output, and are often useful in silent breakpoints. +*Note Commands for Controlled Output: Output. + + For example, here is how you could use breakpoint commands to print +the value of 'x' at entry to 'foo' whenever 'x' is positive. + + break foo if x>0 + commands + silent + printf "x is %d\n",x + cont + end + + One application for breakpoint commands is to compensate for one bug +so you can test for another. Put a breakpoint just after the erroneous +line of code, give it a condition to detect the case in which something +erroneous has been done, and give it commands to assign correct values +to any variables that need them. End with the 'continue' command so +that your program does not stop, and start with the 'silent' command so +that no output is produced. Here is an example: + + break 403 + commands + silent + set x = y + 4 + cont + end + + +File: gdb.info, Node: Dynamic Printf, Next: Save Breakpoints, Prev: Break Commands, Up: Breakpoints + +5.1.8 Dynamic Printf +-------------------- + +The dynamic printf command 'dprintf' combines a breakpoint with +formatted printing of your program's data to give you the effect of +inserting 'printf' calls into your program on-the-fly, without having to +recompile it. + + In its most basic form, the output goes to the GDB console. However, +you can set the variable 'dprintf-style' for alternate handling. For +instance, you can ask to format the output by calling your program's +'printf' function. This has the advantage that the characters go to the +program's output device, so they can recorded in redirects to files and +so forth. + + If you are doing remote debugging with a stub or agent, you can also +ask to have the printf handled by the remote agent. In addition to +ensuring that the output goes to the remote program's device along with +any other output the program might produce, you can also ask that the +dprintf remain active even after disconnecting from the remote target. +Using the stub/agent is also more efficient, as it can do everything +without needing to communicate with GDB. + +'dprintf LOCSPEC,TEMPLATE,EXPRESSION[,EXPRESSION...]' + Whenever execution reaches a code location that results from + resolving LOCSPEC, print the values of one or more EXPRESSIONS + under the control of the string TEMPLATE. To print several values, + separate them with commas. + +'set dprintf-style STYLE' + Set the dprintf output to be handled in one of several different + styles enumerated below. A change of style affects all existing + dynamic printfs immediately. (If you need individual control over + the print commands, simply define normal breakpoints with + explicitly-supplied command lists.) + + 'gdb' + Handle the output using the GDB 'printf' command. When using + this style, it is possible to use the '%V' format specifier + (*note %V Format Specifier::). + + 'call' + Handle the output by calling a function in your program + (normally 'printf'). When using this style the supported + format specifiers depend entirely on the function being + called. + + Most of GDB's format specifiers align with those supported by + the 'printf' function, however, GDB's '%V' format specifier + extension is not supported by 'printf'. When using 'call' + style dprintf, care should be taken to ensure that only format + specifiers supported by the output function are used, + otherwise the results will be undefined. + + 'agent' + Have the remote debugging agent (such as 'gdbserver') handle + the output itself. This style is only available for agents + that support running commands on the target. This style does + not support the '%V' format specifier. + +'set dprintf-function FUNCTION' + Set the function to call if the dprintf style is 'call'. By + default its value is 'printf'. You may set it to any expression + that GDB can evaluate to a function, as per the 'call' command. + +'set dprintf-channel CHANNEL' + Set a "channel" for dprintf. If set to a non-empty value, GDB will + evaluate it as an expression and pass the result as a first + argument to the 'dprintf-function', in the manner of 'fprintf' and + similar functions. Otherwise, the dprintf format string will be + the first argument, in the manner of 'printf'. + + As an example, if you wanted 'dprintf' output to go to a logfile + that is a standard I/O stream assigned to the variable 'mylog', you + could do the following: + + (gdb) set dprintf-style call + (gdb) set dprintf-function fprintf + (gdb) set dprintf-channel mylog + (gdb) dprintf 25,"at line 25, glob=%d\n",glob + Dprintf 1 at 0x123456: file main.c, line 25. + (gdb) info break + 1 dprintf keep y 0x00123456 in main at main.c:25 + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) + continue + (gdb) + + Note that the 'info break' displays the dynamic printf commands as + normal breakpoint commands; you can thus easily see the effect of + the variable settings. + +'set disconnected-dprintf on' +'set disconnected-dprintf off' + Choose whether 'dprintf' commands should continue to run if GDB has + disconnected from the target. This only applies if the + 'dprintf-style' is 'agent'. + +'show disconnected-dprintf off' + Show the current choice for disconnected 'dprintf'. + + GDB does not check the validity of function and channel, relying on +you to supply values that are meaningful for the contexts in which they +are being used. For instance, the function and channel may be the +values of local variables, but if that is the case, then all enabled +dynamic prints must be at locations within the scope of those locals. +If evaluation fails, GDB will report an error. + + +File: gdb.info, Node: Save Breakpoints, Next: Static Probe Points, Prev: Dynamic Printf, Up: Breakpoints + +5.1.9 How to save breakpoints to a file +--------------------------------------- + +To save breakpoint definitions to a file use the 'save breakpoints' +command. + +'save breakpoints [FILENAME]' + This command saves all current breakpoint definitions together with + their commands and ignore counts, into a file 'FILENAME' suitable + for use in a later debugging session. This includes all types of + breakpoints (breakpoints, watchpoints, catchpoints, tracepoints). + To read the saved breakpoint definitions, use the 'source' command + (*note Command Files::). Note that watchpoints with expressions + involving local variables may fail to be recreated because it may + not be possible to access the context where the watchpoint is valid + anymore. Because the saved breakpoint definitions are simply a + sequence of GDB commands that recreate the breakpoints, you can + edit the file in your favorite editing program, and remove the + breakpoint definitions you're not interested in, or that can no + longer be recreated. + + +File: gdb.info, Node: Static Probe Points, Next: Error in Breakpoints, Prev: Save Breakpoints, Up: Breakpoints + +5.1.10 Static Probe Points +-------------------------- + +GDB supports "SDT" probes in the code. SDT stands for Statically +Defined Tracing, and the probes are designed to have a tiny runtime code +and data footprint, and no dynamic relocations. + + Currently, the following types of probes are supported on +ELF-compatible systems: + + * 'SystemTap' () SDT probes(1). + 'SystemTap' probes are usable from assembly, C and C++ + languages(2). + + * 'DTrace' () USDT probes. + 'DTrace' probes are usable from C and C++ languages. + + Some 'SystemTap' probes have an associated semaphore variable; for +instance, this happens automatically if you defined your probe using a +DTrace-style '.d' file. If your probe has a semaphore, GDB will +automatically enable it when you specify a breakpoint using the +'-probe-stap' notation. But, if you put a breakpoint at a probe's +location by some other method (e.g., 'break file:line'), then GDB will +not automatically set the semaphore. 'DTrace' probes do not support +semaphores. + + You can examine the available static static probes using 'info +probes', with optional arguments: + +'info probes [TYPE] [PROVIDER [NAME [OBJFILE]]]' + If given, TYPE is either 'stap' for listing 'SystemTap' probes or + 'dtrace' for listing 'DTrace' probes. If omitted all probes are + listed regardless of their types. + + If given, PROVIDER is a regular expression used to match against + provider names when selecting which probes to list. If omitted, + probes by all probes from all providers are listed. + + If given, NAME is a regular expression to match against probe names + when selecting which probes to list. If omitted, probe names are + not considered when deciding whether to display them. + + If given, OBJFILE is a regular expression used to select which + object files (executable or shared libraries) to examine. If not + given, all object files are considered. + +'info probes all' + List the available static probes, from all types. + + Some probe points can be enabled and/or disabled. The effect of +enabling or disabling a probe depends on the type of probe being +handled. Some 'DTrace' probes can be enabled or disabled, but +'SystemTap' probes cannot be disabled. + + You can enable (or disable) one or more probes using the following +commands, with optional arguments: + +'enable probes [PROVIDER [NAME [OBJFILE]]]' + If given, PROVIDER is a regular expression used to match against + provider names when selecting which probes to enable. If omitted, + all probes from all providers are enabled. + + If given, NAME is a regular expression to match against probe names + when selecting which probes to enable. If omitted, probe names are + not considered when deciding whether to enable them. + + If given, OBJFILE is a regular expression used to select which + object files (executable or shared libraries) to examine. If not + given, all object files are considered. + +'disable probes [PROVIDER [NAME [OBJFILE]]]' + See the 'enable probes' command above for a description of the + optional arguments accepted by this command. + + A probe may specify up to twelve arguments. These are available at +the point at which the probe is defined--that is, when the current PC is +at the probe's location. The arguments are available using the +convenience variables (*note Convenience Vars::) +'$_probe_arg0'...'$_probe_arg11'. In 'SystemTap' probes each probe +argument is an integer of the appropriate size; types are not preserved. +In 'DTrace' probes types are preserved provided that they are recognized +as such by GDB; otherwise the value of the probe argument will be a long +integer. The convenience variable '$_probe_argc' holds the number of +arguments at the current probe point. + + These variables are always available, but attempts to access them at +any location other than a probe point will cause GDB to give an error +message. + + ---------- Footnotes ---------- + + (1) See + for +more information on how to add 'SystemTap' SDT probes in your +applications. + + (2) See + for +a good reference on how the SDT probes are implemented. + + +File: gdb.info, Node: Error in Breakpoints, Next: Breakpoint-related Warnings, Prev: Static Probe Points, Up: Breakpoints + +5.1.11 "Cannot insert breakpoints" +---------------------------------- + +If you request too many active hardware-assisted breakpoints and +watchpoints, you will see this error message: + + Stopped; cannot insert breakpoints. + You may have requested too many hardware breakpoints and watchpoints. + +This message is printed when you attempt to resume the program, since +only then GDB knows exactly how many hardware breakpoints and +watchpoints it needs to insert. + + When this message is printed, you need to disable or remove some of +the hardware-assisted breakpoints and watchpoints, and then continue. + + +File: gdb.info, Node: Breakpoint-related Warnings, Prev: Error in Breakpoints, Up: Breakpoints + +5.1.12 "Breakpoint address adjusted..." +--------------------------------------- + +Some processor architectures place constraints on the addresses at which +breakpoints may be placed. For architectures thus constrained, GDB will +attempt to adjust the breakpoint's address to comply with the +constraints dictated by the architecture. + + One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a bundle +to the instruction with the lowest address. GDB honors this constraint +by adjusting a breakpoint's address to the first in the bundle. + + It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that a +breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter GDB's breakpoint +related behavior from what the user expects, a warning is printed when +the breakpoint is first set and also when the breakpoint is hit. + + A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + + warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. + + Such warnings are printed both for user settable and GDB's internal +breakpoints. If you see one of these warnings, you should verify that a +breakpoint set at the adjusted address will have the desired affect. If +not, the breakpoint in question may be removed and other breakpoints may +be set which will have the desired behavior. E.g., it may be sufficient +to place the breakpoint at a later instruction. A conditional +breakpoint may also be useful in some cases to prevent the breakpoint +from triggering too often. + + GDB will also issue a warning when stopping at one of these adjusted +breakpoints: + + warning: Breakpoint 1 address previously adjusted from 0x00010414 + to 0x00010410. + + When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. + + +File: gdb.info, Node: Continuing and Stepping, Next: Skipping Over Functions and Files, Prev: Breakpoints, Up: Stopping + +5.2 Continuing and Stepping +=========================== + +"Continuing" means resuming program execution until your program +completes normally. In contrast, "stepping" means executing just one +more "step" of your program, where "step" may mean either one line of +source code, or one machine instruction (depending on what particular +command you use). Either when continuing or when stepping, your program +may stop even sooner, due to a breakpoint or a signal. (If it stops due +to a signal, you may want to use 'handle', or use 'signal 0' to resume +execution (*note Signals: Signals.), or you may step into the signal's +handler (*note stepping and signal handlers::).) + +'continue [IGNORE-COUNT]' +'c [IGNORE-COUNT]' +'fg [IGNORE-COUNT]' + Resume program execution, at the address where your program last + stopped; any breakpoints set at that address are bypassed. The + optional argument IGNORE-COUNT allows you to specify a further + number of times to ignore a breakpoint at this location; its effect + is like that of 'ignore' (*note Break Conditions: Conditions.). + + The argument IGNORE-COUNT is meaningful only when your program + stopped due to a breakpoint. At other times, the argument to + 'continue' is ignored. + + The synonyms 'c' and 'fg' (for "foreground", as the debugged + program is deemed to be the foreground program) are provided purely + for convenience, and have exactly the same behavior as 'continue'. + + To resume execution at a different place, you can use 'return' (*note +Returning from a Function: Returning.) to go back to the calling +function; or 'jump' (*note Continuing at a Different Address: Jumping.) +to go to an arbitrary location in your program. + + A typical technique for using stepping is to set a breakpoint (*note +Breakpoints; Watchpoints; and Catchpoints: Breakpoints.) at the +beginning of the function or the section of your program where a problem +is believed to lie, run your program until it stops at that breakpoint, +and then step through the suspect area, examining the variables that are +interesting, until you see the problem happen. + +'step' + Continue running your program until control reaches a different + source line, then stop it and return control to GDB. This command + is abbreviated 's'. + + _Warning:_ If you use the 'step' command while control is + within a function that was compiled without debugging + information, execution proceeds until control reaches a + function that does have debugging information. Likewise, it + will not step into a function which is compiled without + debugging information. To step through functions without + debugging information, use the 'stepi' command, described + below. + + The 'step' command only stops at the first instruction of a source + line. This prevents the multiple stops that could otherwise occur + in 'switch' statements, 'for' loops, etc. 'step' continues to stop + if a function that has debugging information is called within the + line. In other words, 'step' _steps inside_ any functions called + within the line. + + Also, the 'step' command only enters a function if there is line + number information for the function. Otherwise it acts like the + 'next' command. This avoids problems when using 'cc -gl' on MIPS + machines. Previously, 'step' entered subroutines if there was any + debugging information about the routine. + +'step COUNT' + Continue running as in 'step', but do so COUNT times. If a + breakpoint is reached, or a signal not related to stepping occurs + before COUNT steps, stepping stops right away. + +'next [COUNT]' + Continue to the next source line in the current (innermost) stack + frame. This is similar to 'step', but function calls that appear + within the line of code are executed without stopping. Execution + stops when control reaches a different line of code at the original + stack level that was executing when you gave the 'next' command. + This command is abbreviated 'n'. + + An argument COUNT is a repeat count, as for 'step'. + + The 'next' command only stops at the first instruction of a source + line. This prevents multiple stops that could otherwise occur in + 'switch' statements, 'for' loops, etc. + +'set step-mode' +'set step-mode on' + The 'set step-mode on' command causes the 'step' command to stop at + the first instruction of a function which contains no debug line + information rather than stepping over it. + + This is useful in cases where you may be interested in inspecting + the machine instructions of a function which has no symbolic info + and do not want GDB to automatically skip over this function. + +'set step-mode off' + Causes the 'step' command to step over any functions which contains + no debug information. This is the default. + +'show step-mode' + Show whether GDB will stop in or step over functions without source + line debug information. + +'finish' + Continue running until just after function in the selected stack + frame returns. Print the returned value (if any). This command + can be abbreviated as 'fin'. + + Contrast this with the 'return' command (*note Returning from a + Function: Returning.). + +'set print finish [on|off]' +'show print finish' + By default the 'finish' command will show the value that is + returned by the function. This can be disabled using 'set print + finish off'. When disabled, the value is still entered into the + value history (*note Value History::), but not displayed. + +'until' +'u' + Continue running until a source line past the current line, in the + current stack frame, is reached. This command is used to avoid + single stepping through a loop more than once. It is like the + 'next' command, except that when 'until' encounters a jump, it + automatically continues execution until the program counter is + greater than the address of the jump. + + This means that when you reach the end of a loop after single + stepping though it, 'until' makes your program continue execution + until it exits the loop. In contrast, a 'next' command at the end + of a loop simply steps back to the beginning of the loop, which + forces you to step through the next iteration. + + 'until' always stops your program if it attempts to exit the + current stack frame. + + 'until' may produce somewhat counterintuitive results if the order + of machine code does not match the order of the source lines. For + example, in the following excerpt from a debugging session, the 'f' + ('frame') command shows that execution is stopped at line '206'; + yet when we use 'until', we get to line '195': + + (gdb) f + #0 main (argc=4, argv=0xf7fffae8) at m4.c:206 + 206 expand_input(); + (gdb) until + 195 for ( ; argc > 0; NEXTARG) { + + This happened because, for execution efficiency, the compiler had + generated code for the loop closure test at the end, rather than + the start, of the loop--even though the test in a C 'for'-loop is + written before the body of the loop. The 'until' command appeared + to step back to the beginning of the loop when it advanced to this + expression; however, it has not really gone to an earlier + statement--not in terms of the actual machine code. + + 'until' with no argument works by means of single instruction + stepping, and hence is slower than 'until' with an argument. + +'until LOCSPEC' +'u LOCSPEC' + Continue running your program until either it reaches a code + location that results from resolving LOCSPEC, or the current stack + frame returns. LOCSPEC is any of the forms described in *note + Location Specifications::. This form of the command uses temporary + breakpoints, and hence is quicker than 'until' without an argument. + The specified location is actually reached only if it is in the + current frame. This implies that 'until' can be used to skip over + recursive function invocations. For instance in the code below, if + the current location is line '96', issuing 'until 99' will execute + the program up to line '99' in the same invocation of factorial, + i.e., after the inner invocations have returned. + + 94 int factorial (int value) + 95 { + 96 if (value > 1) { + 97 value *= factorial (value - 1); + 98 } + 99 return (value); + 100 } + +'advance LOCSPEC' + Continue running your program until either it reaches a code + location that results from resolving LOCSPEC, or the current stack + frame returns. LOCSPEC is any of the forms described in *note + Location Specifications::. This command is similar to 'until', but + 'advance' will not skip over recursive function calls, and the + target code location doesn't have to be in the same frame as the + current one. + +'stepi' +'stepi ARG' +'si' + Execute one machine instruction, then stop and return to the + debugger. + + It is often useful to do 'display/i $pc' when stepping by machine + instructions. This makes GDB automatically display the next + instruction to be executed, each time your program stops. *Note + Automatic Display: Auto Display. + + An argument is a repeat count, as in 'step'. + +'nexti' +'nexti ARG' +'ni' + Execute one machine instruction, but if it is a function call, + proceed until the function returns. + + An argument is a repeat count, as in 'next'. + + By default, and if available, GDB makes use of target-assisted "range +stepping". In other words, whenever you use a stepping command (e.g., +'step', 'next'), GDB tells the target to step the corresponding range of +instruction addresses instead of issuing multiple single-steps. This +speeds up line stepping, particularly for remote targets. Ideally, +there should be no reason you would want to turn range stepping off. +However, it's possible that a bug in the debug info, a bug in the remote +stub (for remote targets), or even a bug in GDB could make line stepping +behave incorrectly when target-assisted range stepping is enabled. You +can use the following command to turn off range stepping if necessary: + +'set range-stepping' +'show range-stepping' + Control whether range stepping is enabled. + + If 'on', and the target supports it, GDB tells the target to step a + range of addresses itself, instead of issuing multiple + single-steps. If 'off', GDB always issues single-steps, even if + range stepping is supported by the target. The default is 'on'. + + +File: gdb.info, Node: Skipping Over Functions and Files, Next: Signals, Prev: Continuing and Stepping, Up: Stopping + +5.3 Skipping Over Functions and Files +===================================== + +The program you are debugging may contain some functions which are +uninteresting to debug. The 'skip' command lets you tell GDB to skip a +function, all functions in a file or a particular function in a +particular file when stepping. + + For example, consider the following C function: + + 101 int func() + 102 { + 103 foo(boring()); + 104 bar(boring()); + 105 } + +Suppose you wish to step into the functions 'foo' and 'bar', but you are +not interested in stepping through 'boring'. If you run 'step' at line +103, you'll enter 'boring()', but if you run 'next', you'll step over +both 'foo' and 'boring'! + + One solution is to 'step' into 'boring' and use the 'finish' command +to immediately exit it. But this can become tedious if 'boring' is +called from many places. + + A more flexible solution is to execute 'skip boring'. This instructs +GDB never to step into 'boring'. Now when you execute 'step' at line +103, you'll step over 'boring' and directly into 'foo'. + + Functions may be skipped by providing either a function name, +linespec (*note Location Specifications::), regular expression that +matches the function's name, file name or a 'glob'-style pattern that +matches the file name. + + On Posix systems the form of the regular expression is "Extended +Regular Expressions". See for example 'man 7 regex' on GNU/Linux +systems. On non-Posix systems the form of the regular expression is +whatever is provided by the 'regcomp' function of the underlying system. +See for example 'man 7 glob' on GNU/Linux systems for a description of +'glob'-style patterns. + +'skip [OPTIONS]' + The basic form of the 'skip' command takes zero or more options + that specify what to skip. The OPTIONS argument is any useful + combination of the following: + + '-file FILE' + '-fi FILE' + Functions in FILE will be skipped over when stepping. + + '-gfile FILE-GLOB-PATTERN' + '-gfi FILE-GLOB-PATTERN' + Functions in files matching FILE-GLOB-PATTERN will be skipped + over when stepping. + + (gdb) skip -gfi utils/*.c + + '-function LINESPEC' + '-fu LINESPEC' + Functions named by LINESPEC or the function containing the + line named by LINESPEC will be skipped over when stepping. + *Note Location Specifications::. + + '-rfunction REGEXP' + '-rfu REGEXP' + Functions whose name matches REGEXP will be skipped over when + stepping. + + This form is useful for complex function names. For example, + there is generally no need to step into C++ 'std::string' + constructors or destructors. Plus with C++ templates it can + be hard to write out the full name of the function, and often + it doesn't matter what the template arguments are. Specifying + the function to be skipped as a regular expression makes this + easier. + + (gdb) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( + + If you want to skip every templated C++ constructor and + destructor in the 'std' namespace you can do: + + (gdb) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( + + If no options are specified, the function you're currently + debugging will be skipped. + +'skip function [LINESPEC]' + After running this command, the function named by LINESPEC or the + function containing the line named by LINESPEC will be skipped over + when stepping. *Note Location Specifications::. + + If you do not specify LINESPEC, the function you're currently + debugging will be skipped. + + (If you have a function called 'file' that you want to skip, use + 'skip function file'.) + +'skip file [FILENAME]' + After running this command, any function whose source lives in + FILENAME will be skipped over when stepping. + + (gdb) skip file boring.c + File boring.c will be skipped when stepping. + + If you do not specify FILENAME, functions whose source lives in the + file you're currently debugging will be skipped. + + Skips can be listed, deleted, disabled, and enabled, much like +breakpoints. These are the commands for managing your list of skips: + +'info skip [RANGE]' + Print details about the specified skip(s). If RANGE is not + specified, print a table with details about all functions and files + marked for skipping. 'info skip' prints the following information + about each skip: + + _Identifier_ + A number identifying this skip. + _Enabled or Disabled_ + Enabled skips are marked with 'y'. Disabled skips are marked + with 'n'. + _Glob_ + If the file name is a 'glob' pattern this is 'y'. Otherwise + it is 'n'. + _File_ + The name or 'glob' pattern of the file to be skipped. If no + file is specified this is ''. + _RE_ + If the function name is a 'regular expression' this is 'y'. + Otherwise it is 'n'. + _Function_ + The name or regular expression of the function to skip. If no + function is specified this is ''. + +'skip delete [RANGE]' + Delete the specified skip(s). If RANGE is not specified, delete + all skips. + +'skip enable [RANGE]' + Enable the specified skip(s). If RANGE is not specified, enable + all skips. + +'skip disable [RANGE]' + Disable the specified skip(s). If RANGE is not specified, disable + all skips. + +'set debug skip [on|off]' + Set whether to print the debug output about skipping files and + functions. + +'show debug skip' + Show whether the debug output about skipping files and functions is + printed. + + +File: gdb.info, Node: Signals, Next: Thread Stops, Prev: Skipping Over Functions and Files, Up: Stopping + +5.4 Signals +=========== + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix 'SIGINT' is the signal a +program gets when you type an interrupt character (often 'Ctrl-c'); +'SIGSEGV' is the signal a program gets from referencing a place in +memory far away from all the areas in use; 'SIGALRM' occurs when the +alarm clock timer goes off (which happens only if your program has +requested an alarm). + + Some signals, including 'SIGALRM', are a normal part of the +functioning of your program. Others, such as 'SIGSEGV', indicate +errors; these signals are "fatal" (they kill your program immediately) +if the program has not specified in advance some other way to handle the +signal. 'SIGINT' does not indicate an error in your program, but it is +normally fatal so it can carry out the purpose of the interrupt: to kill +the program. + + GDB has the ability to detect any occurrence of a signal in your +program. You can tell GDB in advance what to do for each kind of +signal. + + Normally, GDB is set up to let the non-erroneous signals like +'SIGALRM' be silently passed to your program (so as not to interfere +with their role in the program's functioning) but to stop your program +immediately whenever an error signal happens. You can change these +settings with the 'handle' command. + +'info signals' +'info handle' + Print a table of all the kinds of signals and how GDB has been told + to handle each one. You can use this to see the signal numbers of + all the defined types of signals. + +'info signals SIG' + Similar, but print information only about the specified signal + number. + + 'info handle' is an alias for 'info signals'. + +'catch signal [SIGNAL... | 'all']' + Set a catchpoint for the indicated signals. *Note Set + Catchpoints::, for details about this command. + +'handle SIGNAL [ SIGNAL ... ] [KEYWORDS...]' + Change the way GDB handles each SIGNAL. Each SIGNAL can be the + number of a signal or its name (with or without the 'SIG' at the + beginning); a list of signal numbers of the form 'LOW-HIGH'; or the + word 'all', meaning all the known signals, except 'SIGINT' and + 'SIGTRAP', which are used by GDB. Optional argument KEYWORDS, + described below, say what changes to make to all of the specified + signals. + + The keywords allowed by the 'handle' command can be abbreviated. +Their full names are: + +'nostop' + GDB should not stop your program when this signal happens. It may + still print a message telling you that the signal has come in. + +'stop' + GDB should stop your program when this signal happens. This + implies the 'print' keyword as well. + +'print' + GDB should print a message when this signal happens. + +'noprint' + GDB should not mention the occurrence of the signal at all. This + implies the 'nostop' keyword as well. + +'pass' +'noignore' + GDB should allow your program to see this signal; your program can + handle the signal, or else it may terminate if the signal is fatal + and not handled. 'pass' and 'noignore' are synonyms. + +'nopass' +'ignore' + GDB should not allow your program to see this signal. 'nopass' and + 'ignore' are synonyms. + + When a signal stops your program, the signal is not visible to the +program until you continue. Your program sees the signal then, if +'pass' is in effect for the signal in question _at that time_. In other +words, after GDB reports a signal, you can use the 'handle' command with +'pass' or 'nopass' to control whether your program sees that signal when +you continue. + + The default is set to 'nostop', 'noprint', 'pass' for non-erroneous +signals such as 'SIGALRM', 'SIGWINCH' and 'SIGCHLD', and to 'stop', +'print', 'pass' for the erroneous signals. + + You can also use the 'signal' command to prevent your program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. For example, if your program +stopped due to some sort of memory reference error, you might store +correct values into the erroneous variables and continue, hoping to see +more execution; but your program would probably terminate immediately as +a result of the fatal signal once it saw the signal. To prevent this, +you can continue with 'signal 0'. *Note Giving your Program a Signal: +Signaling. + + GDB optimizes for stepping the mainline code. If a signal that has +'handle nostop' and 'handle pass' set arrives while a stepping command +(e.g., 'stepi', 'step', 'next') is in progress, GDB lets the signal +handler run and then resumes stepping the mainline code once the signal +handler returns. In other words, GDB steps over the signal handler. +This prevents signals that you've specified as not interesting (with +'handle nostop') from changing the focus of debugging unexpectedly. +Note that the signal handler itself may still hit a breakpoint, stop for +another signal that has 'handle stop' in effect, or for any other event +that normally results in stopping the stepping command sooner. Also +note that GDB still informs you that the program received a signal if +'handle print' is set. + + If you set 'handle pass' for a signal, and your program sets up a +handler for it, then issuing a stepping command, such as 'step' or +'stepi', when your program is stopped due to the signal will step _into_ +the signal handler (if the target supports that). + + Likewise, if you use the 'queue-signal' command to queue a signal to +be delivered to the current thread when execution of the thread resumes +(*note Giving your Program a Signal: Signaling.), then a stepping +command will step into the signal handler. + + Here's an example, using 'stepi' to step to the first instruction of +'SIGUSR1''s handler: + + (gdb) handle SIGUSR1 + Signal Stop Print Pass to program Description + SIGUSR1 Yes Yes Yes User defined signal 1 + (gdb) c + Continuing. + + Program received signal SIGUSR1, User defined signal 1. + main () sigusr1.c:28 + 28 p = 0; + (gdb) si + sigusr1_handler () at sigusr1.c:9 + 9 { + + The same, but using 'queue-signal' instead of waiting for the program +to receive the signal first: + + (gdb) n + 28 p = 0; + (gdb) queue-signal SIGUSR1 + (gdb) si + sigusr1_handler () at sigusr1.c:9 + 9 { + (gdb) + + On some targets, GDB can inspect extra signal information associated +with the intercepted signal, before it is actually delivered to the +program being debugged. This information is exported by the convenience +variable '$_siginfo', and consists of data that is passed by the kernel +to the signal handler at the time of the receipt of a signal. The data +type of the information itself is target dependent. You can see the +data type using the 'ptype $_siginfo' command. On Unix systems, it +typically corresponds to the standard 'siginfo_t' type, as defined in +the 'signal.h' system header. + + Here's an example, on a GNU/Linux system, printing the stray +referenced address that raised a segmentation fault. + + (gdb) continue + Program received signal SIGSEGV, Segmentation fault. + 0x0000000000400766 in main () + 69 *(int *)p = 0; + (gdb) ptype $_siginfo + type = struct { + int si_signo; + int si_errno; + int si_code; + union { + int _pad[28]; + struct {...} _kill; + struct {...} _timer; + struct {...} _rt; + struct {...} _sigchld; + struct {...} _sigfault; + struct {...} _sigpoll; + } _sifields; + } + (gdb) ptype $_siginfo._sifields._sigfault + type = struct { + void *si_addr; + } + (gdb) p $_siginfo._sifields._sigfault.si_addr + $1 = (void *) 0x7ffff7ff7000 + + Depending on target support, '$_siginfo' may also be writable. + + +File: gdb.info, Node: Thread Stops, Prev: Signals, Up: Stopping + +5.5 Stopping and Starting Multi-thread Programs +=============================================== + +GDB supports debugging programs with multiple threads (*note Debugging +Programs with Multiple Threads: Threads.). There are two modes of +controlling execution of your program within the debugger. In the +default mode, referred to as "all-stop mode", when any thread in your +program stops (for example, at a breakpoint or while being stepped), all +other threads in the program are also stopped by GDB. On some targets, +GDB also supports "non-stop mode", in which other threads can continue +to run freely while you examine the stopped thread in the debugger. + +* Menu: + +* All-Stop Mode:: All threads stop when GDB takes control +* Non-Stop Mode:: Other threads continue to execute +* Background Execution:: Running your program asynchronously +* Thread-Specific Breakpoints:: Controlling breakpoints +* Interrupted System Calls:: GDB may interfere with system calls +* Observer Mode:: GDB does not alter program behavior + + +File: gdb.info, Node: All-Stop Mode, Next: Non-Stop Mode, Up: Thread Stops + +5.5.1 All-Stop Mode +------------------- + +In all-stop mode, whenever your program stops under GDB for any reason, +_all_ threads of execution stop, not just the current thread. This +allows you to examine the overall state of the program, including +switching between threads, without worrying that things may change +underfoot. + + Conversely, whenever you restart the program, _all_ threads start +executing. _This is true even when single-stepping_ with commands like +'step' or 'next'. + + In particular, GDB cannot single-step all threads in lockstep. Since +thread scheduling is up to your debugging target's operating system (not +controlled by GDB), other threads may execute more than one statement +while the current thread completes a single step. Moreover, in general +other threads stop in the middle of a statement, rather than at a clean +statement boundary, when the program stops. + + You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. + + Whenever GDB stops your program, due to a breakpoint or a signal, it +automatically selects the thread where that breakpoint or signal +happened. GDB alerts you to the context switch with a message such as +'[Switching to Thread N]' to identify the thread. + + On some OSes, you can modify GDB's default behavior by locking the OS +scheduler to allow only a single thread to run. + +'set scheduler-locking MODE' + Set the scheduler locking mode. It applies to normal execution, + record mode, and replay mode. MODE can be one of the following: + + 'off' + There is no locking and any thread may run at any time. + + 'on' + Only the current thread may run when the inferior is resumed. + New threads created by the resumed thread are held stopped at + their entry point, before they execute any instruction. + + 'step' + Behaves like 'on' when stepping, and 'off' otherwise. Threads + other than the current never get a chance to run when you + step, and they are completely free to run when you use + commands like 'continue', 'until', or 'finish'. + + This mode optimizes for single-stepping; it prevents other + threads from preempting the current thread while you are + stepping, so that the focus of debugging does not change + unexpectedly. However, unless another thread hits a + breakpoint during its timeslice, GDB does not change the + current thread away from the thread that you are debugging. + + 'replay' + Behaves like 'on' in replay mode, and 'off' in either record + mode or during normal execution. This is the default mode. + +'show scheduler-locking' + Display the current scheduler locking mode. + + By default, when you issue one of the execution commands such as +'continue', 'next' or 'step', GDB allows only threads of the current +inferior to run. For example, if GDB is attached to two inferiors, each +with two threads, the 'continue' command resumes only the two threads of +the current inferior. This is useful, for example, when you debug a +program that forks and you want to hold the parent stopped (so that, for +instance, it doesn't run to exit), while you debug the child. In other +situations, you may not be interested in inspecting the current state of +any of the processes GDB is attached to, and you may want to resume them +all until some breakpoint is hit. In the latter case, you can instruct +GDB to allow all threads of all the inferiors to run with the +'set schedule-multiple' command. + +'set schedule-multiple' + Set the mode for allowing threads of multiple processes to be + resumed when an execution command is issued. When 'on', all + threads of all processes are allowed to run. When 'off', only the + threads of the current process are resumed. The default is 'off'. + The 'scheduler-locking' mode takes precedence when set to 'on', or + while you are stepping and set to 'step'. + +'show schedule-multiple' + Display the current mode for resuming the execution of threads of + multiple processes. + + +File: gdb.info, Node: Non-Stop Mode, Next: Background Execution, Prev: All-Stop Mode, Up: Thread Stops + +5.5.2 Non-Stop Mode +------------------- + +For some multi-threaded targets, GDB supports an optional mode of +operation in which you can examine stopped program threads in the +debugger while other threads continue to execute freely. This minimizes +intrusion when debugging live systems, such as programs where some +threads have real-time constraints or must continue to respond to +external events. This is referred to as "non-stop" mode. + + In non-stop mode, when a thread stops to report a debugging event, +_only_ that thread is stopped; GDB does not stop other threads as well, +in contrast to the all-stop mode behavior. Additionally, execution +commands such as 'continue' and 'step' apply by default only to the +current thread in non-stop mode, rather than all threads as in all-stop +mode. This allows you to control threads explicitly in ways that are +not possible in all-stop mode -- for example, stepping one thread while +allowing others to run freely, stepping one thread while holding all +others stopped, or stepping several threads independently and +simultaneously. + + To enter non-stop mode, use this sequence of commands before you run +or attach to your program: + + # If using the CLI, pagination breaks non-stop. + set pagination off + + # Finally, turn it on! + set non-stop on + + You can use these commands to manipulate the non-stop mode setting: + +'set non-stop on' + Enable selection of non-stop mode. +'set non-stop off' + Disable selection of non-stop mode. +'show non-stop' + Show the current non-stop enablement setting. + + Note these commands only reflect whether non-stop mode is enabled, +not whether the currently-executing program is being run in non-stop +mode. In particular, the 'set non-stop' preference is only consulted +when GDB starts or connects to the target program, and it is generally +not possible to switch modes once debugging has started. Furthermore, +since not all targets support non-stop mode, even when you have enabled +non-stop mode, GDB may still fall back to all-stop operation by default. + + In non-stop mode, all execution commands apply only to the current +thread by default. That is, 'continue' only continues one thread. To +continue all threads, issue 'continue -a' or 'c -a'. + + You can use GDB's background execution commands (*note Background +Execution::) to run some threads in the background while you continue to +examine or step others from GDB. The MI execution commands (*note +GDB/MI Program Execution::) are always executed asynchronously in +non-stop mode. + + Suspending execution is done with the 'interrupt' command when +running in the background, or 'Ctrl-c' during foreground execution. In +all-stop mode, this stops the whole process; but in non-stop mode the +interrupt applies only to the current thread. To stop the whole +program, use 'interrupt -a'. + + Other execution commands do not currently support the '-a' option. + + In non-stop mode, when a thread stops, GDB doesn't automatically make +that thread current, as it does in all-stop mode. This is because the +thread stop notifications are asynchronous with respect to GDB's command +interpreter, and it would be confusing if GDB unexpectedly changed to a +different thread just as you entered a command to operate on the +previously current thread. + + +File: gdb.info, Node: Background Execution, Next: Thread-Specific Breakpoints, Prev: Non-Stop Mode, Up: Thread Stops + +5.5.3 Background Execution +-------------------------- + +GDB's execution commands have two variants: the normal foreground +(synchronous) behavior, and a background (asynchronous) behavior. In +foreground execution, GDB waits for the program to report that some +thread has stopped before prompting for another command. In background +execution, GDB immediately gives a command prompt so that you can issue +other commands while your program runs. + + If the target doesn't support async mode, GDB issues an error message +if you attempt to use the background execution commands. + + To specify background execution, add a '&' to the command. For +example, the background form of the 'continue' command is 'continue&', +or just 'c&'. The execution commands that accept background execution +are: + +'run' + *Note Starting your Program: Starting. + +'attach' + *Note Debugging an Already-running Process: Attach. + +'step' + *Note step: Continuing and Stepping. + +'stepi' + *Note stepi: Continuing and Stepping. + +'next' + *Note next: Continuing and Stepping. + +'nexti' + *Note nexti: Continuing and Stepping. + +'continue' + *Note continue: Continuing and Stepping. + +'finish' + *Note finish: Continuing and Stepping. + +'until' + *Note until: Continuing and Stepping. + + Background execution is especially useful in conjunction with +non-stop mode for debugging programs with multiple threads; see *note +Non-Stop Mode::. However, you can also use these commands in the normal +all-stop mode with the restriction that you cannot issue another +execution command until the previous one finishes. Examples of commands +that are valid in all-stop mode while the program is running include +'help' and 'info break'. + + You can interrupt your program while it is running in the background +by using the 'interrupt' command. + +'interrupt' +'interrupt -a' + + Suspend execution of the running program. In all-stop mode, + 'interrupt' stops the whole process, but in non-stop mode, it stops + only the current thread. To stop the whole program in non-stop + mode, use 'interrupt -a'. + + +File: gdb.info, Node: Thread-Specific Breakpoints, Next: Interrupted System Calls, Prev: Background Execution, Up: Thread Stops + +5.5.4 Thread-Specific Breakpoints +--------------------------------- + +When your program has multiple threads (*note Debugging Programs with +Multiple Threads: Threads.), you can choose whether to set breakpoints +on all threads, or on a particular thread. + +'break LOCSPEC thread THREAD-ID' +'break LOCSPEC thread THREAD-ID if ...' + LOCSPEC specifies a code location or locations in your program. + *Note Location Specifications::, for details. + + Use the qualifier 'thread THREAD-ID' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular thread reaches this breakpoint. The THREAD-ID specifier + is one of the thread identifiers assigned by GDB, shown in the + first column of the 'info threads' display. + + If you do not specify 'thread THREAD-ID' when you set a breakpoint, + the breakpoint applies to _all_ threads of your program. + + You can use the 'thread' qualifier on conditional breakpoints as + well; in this case, place 'thread THREAD-ID' before or after the + breakpoint condition, like this: + + (gdb) break frik.c:13 thread 28 if bartab > lim + + Thread-specific breakpoints are automatically deleted when GDB +detects the corresponding thread is no longer in the thread list. For +example: + + (gdb) c + Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. + + There are several ways for a thread to disappear, such as a regular +thread exit, but also when you detach from the process with the 'detach' +command (*note Debugging an Already-running Process: Attach.), or if GDB +loses the remote connection (*note Remote Debugging::), etc. Note that +with some targets, GDB is only able to detect a thread has exited when +the user explicitly asks for the thread list with the 'info threads' +command. + + A breakpoint can't be both thread-specific and inferior-specific +(*note Inferior-Specific Breakpoints::), or task-specific (*note Ada +Tasks::); using more than one of the 'thread', 'inferior', or 'task' +keywords when creating a breakpoint will give an error. + + +File: gdb.info, Node: Interrupted System Calls, Next: Observer Mode, Prev: Thread-Specific Breakpoints, Up: Thread Stops + +5.5.5 Interrupted System Calls +------------------------------ + +There is an unfortunate side effect when using GDB to debug +multi-threaded programs. If one thread stops for a breakpoint, or for +some other reason, and another thread is blocked in a system call, then +the system call may return prematurely. This is a consequence of the +interaction between multiple threads and the signals that GDB uses to +implement breakpoints and other events that stop execution. + + To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + + For example, do not write code like this: + + sleep (10); + + The call to 'sleep' will return early if a different thread stops at +a breakpoint or for some other reason. + + Instead, write this: + + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); + + A system call is allowed to return early, so the system is still +conforming to its specification. But GDB does cause your multi-threaded +program to behave differently than it would without GDB. + + Also, GDB uses internal breakpoints in the thread library to monitor +certain events such as thread creation and thread destruction. When +such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + + +File: gdb.info, Node: Observer Mode, Prev: Interrupted System Calls, Up: Thread Stops + +5.5.6 Observer Mode +------------------- + +If you want to build on non-stop mode and observe program behavior +without any chance of disruption by GDB, you can set variables to +disable all of the debugger's attempts to modify state, whether by +writing memory, inserting breakpoints, etc. These operate at a low +level, intercepting operations from all commands. + + When all of these are set to 'off', then GDB is said to be "observer +mode". As a convenience, the variable 'observer' can be set to disable +these, plus enable non-stop mode. + + Note that GDB will not prevent you from making nonsensical +combinations of these settings. For instance, if you have enabled +'may-insert-breakpoints' but disabled 'may-write-memory', then +breakpoints that work by writing trap instructions into the code stream +will still not be able to be placed. + +'set observer on' +'set observer off' + When set to 'on', this disables all the permission variables below + (except for 'insert-fast-tracepoints'), plus enables non-stop + debugging. Setting this to 'off' switches back to normal + debugging, though remaining in non-stop mode. + +'show observer' + Show whether observer mode is on or off. + +'set may-write-registers on' +'set may-write-registers off' + This controls whether GDB will attempt to alter the values of + registers, such as with assignment expressions in 'print', or the + 'jump' command. It defaults to 'on'. + +'show may-write-registers' + Show the current permission to write registers. + +'set may-write-memory on' +'set may-write-memory off' + This controls whether GDB will attempt to alter the contents of + memory, such as with assignment expressions in 'print'. It + defaults to 'on'. + +'show may-write-memory' + Show the current permission to write memory. + +'set may-insert-breakpoints on' +'set may-insert-breakpoints off' + This controls whether GDB will attempt to insert breakpoints. This + affects all breakpoints, including internal breakpoints defined by + GDB. It defaults to 'on'. + +'show may-insert-breakpoints' + Show the current permission to insert breakpoints. + +'set may-insert-tracepoints on' +'set may-insert-tracepoints off' + This controls whether GDB will attempt to insert (regular) + tracepoints at the beginning of a tracing experiment. It affects + only non-fast tracepoints, fast tracepoints being under the control + of 'may-insert-fast-tracepoints'. It defaults to 'on'. + +'show may-insert-tracepoints' + Show the current permission to insert tracepoints. + +'set may-insert-fast-tracepoints on' +'set may-insert-fast-tracepoints off' + This controls whether GDB will attempt to insert fast tracepoints + at the beginning of a tracing experiment. It affects only fast + tracepoints, regular (non-fast) tracepoints being under the control + of 'may-insert-tracepoints'. It defaults to 'on'. + +'show may-insert-fast-tracepoints' + Show the current permission to insert fast tracepoints. + +'set may-interrupt on' +'set may-interrupt off' + This controls whether GDB will attempt to interrupt or stop program + execution. When this variable is 'off', the 'interrupt' command + will have no effect, nor will 'Ctrl-c'. It defaults to 'on'. + +'show may-interrupt' + Show the current permission to interrupt or stop the program. + + +File: gdb.info, Node: Reverse Execution, Next: Process Record and Replay, Prev: Stopping, Up: Top + +6 Running programs backward +*************************** + +When you are debugging a program, it is not unusual to realize that you +have gone too far, and some event of interest has already happened. If +the target environment supports it, GDB can allow you to "rewind" the +program by running it backward. + + A target environment that supports reverse execution should be able +to "undo" the changes in machine state that have taken place as the +program was executing normally. Variables, registers etc. should revert +to their previous values. Obviously this requires a great deal of +sophistication on the part of the target environment; not all target +environments can support reverse execution. + + When a program is executed in reverse, the instructions that have +most recently been executed are "un-executed", in reverse order. The +program counter runs backward, following the previous thread of +execution in reverse. As each instruction is "un-executed", the values +of memory and/or registers that were changed by that instruction are +reverted to their previous states. After executing a piece of source +code in reverse, all side effects of that code should be "undone", and +all variables should be returned to their prior values(1). + + On some platforms, GDB has built-in support for reverse execution, +activated with the 'record' or 'record btrace' commands. *Note Process +Record and Replay::. Some remote targets, typically full system +emulators, support reverse execution directly without requiring any +special command. + + If you are debugging in a target environment that supports reverse +execution, GDB provides the following commands. + +'reverse-continue [IGNORE-COUNT]' +'rc [IGNORE-COUNT]' + Beginning at the point where your program last stopped, start + executing in reverse. Reverse execution will stop for breakpoints + and synchronous exceptions (signals), just like normal execution. + Behavior of asynchronous signals depends on the target environment. + +'reverse-step [COUNT]' + Run the program backward until control reaches the start of a + different source line; then stop it, and return control to GDB. + + Like the 'step' command, 'reverse-step' will only stop at the + beginning of a source line. It "un-executes" the previously + executed source line. If the previous source line included calls + to debuggable functions, 'reverse-step' will step (backward) into + the called function, stopping at the beginning of the _last_ + statement in the called function (typically a return statement). + + Also, as with the 'step' command, if non-debuggable functions are + called, 'reverse-step' will run through them backward without + stopping. + +'reverse-stepi [COUNT]' + Reverse-execute one machine instruction. Note that the instruction + to be reverse-executed is _not_ the one pointed to by the program + counter, but the instruction executed prior to that one. For + instance, if the last instruction was a jump, 'reverse-stepi' will + take you back from the destination of the jump to the jump + instruction itself. + +'reverse-next [COUNT]' + Run backward to the beginning of the previous line executed in the + current (innermost) stack frame. If the line contains function + calls, they will be "un-executed" without stopping. Starting from + the first line of a function, 'reverse-next' will take you back to + the caller of that function, _before_ the function was called, just + as the normal 'next' command would take you from the last line of a + function back to its return to its caller (2). + +'reverse-nexti [COUNT]' + Like 'nexti', 'reverse-nexti' executes a single instruction in + reverse, except that called functions are "un-executed" atomically. + That is, if the previously executed instruction was a return from + another function, 'reverse-nexti' will continue to execute in + reverse until the call to that function (from the current stack + frame) is reached. + +'reverse-finish' + Just as the 'finish' command takes you to the point where the + current function returns, 'reverse-finish' takes you to the point + where it was called. Instead of ending up at the end of the + current function invocation, you end up at the beginning. + +'set exec-direction' + Set the direction of target execution. +'set exec-direction reverse' + GDB will perform all execution commands in reverse, until the + exec-direction mode is changed to "forward". Affected commands + include 'step, stepi, next, nexti, continue, and finish'. The + 'return' command cannot be used in reverse mode. +'set exec-direction forward' + GDB will perform all execution commands in the normal fashion. + This is the default. + + ---------- Footnotes ---------- + + (1) Note that some side effects are easier to undo than others. For +instance, memory and registers are relatively easy, but device I/O is +hard. Some targets may be able undo things like device I/O, and some +may not. + + The contract between GDB and the reverse executing target requires +only that the target do something reasonable when GDB tells it to +execute backwards, and then report the results back to GDB. Whatever +the target reports back to GDB, GDB will report back to the user. GDB +assumes that the memory and registers that the target reports are in a +consistent state, but GDB accepts whatever it is given. + + (2) Unless the code is too heavily optimized. + + +File: gdb.info, Node: Process Record and Replay, Next: Stack, Prev: Reverse Execution, Up: Top + +7 Recording Inferior's Execution and Replaying It +************************************************* + +On some platforms, GDB provides a special "process record and replay" +target that can record a log of the process execution, and replay it +later with both forward and reverse execution commands. + + When this target is in use, if the execution log includes the record +for the next instruction, GDB will debug in "replay mode". In the +replay mode, the inferior does not really execute code instructions. +Instead, all the events that normally happen during code execution are +taken from the execution log. While code is not really executed in +replay mode, the values of registers (including the program counter +register) and the memory of the inferior are still changed as they +normally would. Their contents are taken from the execution log. + + If the record for the next instruction is not in the execution log, +GDB will debug in "record mode". In this mode, the inferior executes +normally, and GDB records the execution log for future replay. + + The process record and replay target supports reverse execution +(*note Reverse Execution::), even if the platform on which the inferior +runs does not. However, the reverse execution is limited in this case +by the range of the instructions recorded in the execution log. In +other words, reverse execution on platforms that don't support it +directly can only be done in the replay mode. + + When debugging in the reverse direction, GDB will work in replay mode +as long as the execution log includes the record for the previous +instruction; otherwise, it will work in record mode, if the platform +supports reverse execution, or stop if not. + + Currently, process record and replay is supported on ARM, Aarch64, +LoongArch, Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) +running GNU/Linux. Process record and replay can be used both when +native debugging, and when remote debugging via 'gdbserver'. + + When recording an inferior, GDB may print auxiliary information +during stepping commands and commands displaying the execution history. + + For architecture environments that support process record and replay, +GDB provides the following commands: + +'record METHOD' + This command starts the process record and replay target. The + recording method can be specified as parameter. Without a + parameter the command uses the 'full' recording method. The + following recording methods are available: + + 'full' + Full record/replay recording using GDB's software record and + replay implementation. This method allows replaying and + reverse execution. + + 'btrace FORMAT' + Hardware-supported instruction recording, supported on Intel + processors. This method does not record data. Further, the + data is collected in a ring buffer so old data will be + overwritten when the buffer is full. It allows limited + reverse execution. Variables and registers are not available + during reverse execution. In remote debugging, recording + continues on disconnect. Recorded data can be inspected after + reconnecting. The recording may be stopped using 'record + stop'. + + The recording format can be specified as parameter. Without a + parameter the command chooses the recording format. The + following recording formats are available: + + 'bts' + Use the "Branch Trace Store" (BTS) recording format. In + this format, the processor stores a from/to record for + each executed branch in the btrace ring buffer. + + 'pt' + Use the "Intel Processor Trace" recording format. In + this format, the processor stores the execution trace in + a compressed form that is afterwards decoded by GDB. + + The trace can be recorded with very low overhead. The + compressed trace format also allows small trace buffers + to already contain a big number of instructions compared + to BTS. + + Decoding the recorded execution trace, on the other hand, + is more expensive than decoding BTS trace. This is + mostly due to the increased number of instructions to + process. You should increase the buffer-size with care. + + Not all recording formats may be available on all processors. + + The process record and replay target can only debug a process that + is already running. Therefore, you need first to start the process + with the 'run' or 'start' commands, and then start the recording + with the 'record METHOD' command. + + Displaced stepping (*note displaced stepping: Maintenance + Commands.) will be automatically disabled when process record and + replay target is started. That's because the process record and + replay target doesn't support displaced stepping. + + If the inferior is in the non-stop mode (*note Non-Stop Mode::) or + in the asynchronous execution mode (*note Background Execution::), + not all recording methods are available. The 'full' recording + method does not support these two modes. + +'record stop' + Stop the process record and replay target. When process record and + replay target stops, the entire execution log will be deleted and + the inferior will either be terminated, or will remain in its final + state. + + When you stop the process record and replay target in record mode + (at the end of the execution log), the inferior will be stopped at + the next instruction that would have been recorded. In other + words, if you record for a while and then stop recording, the + inferior process will be left in the same state as if the recording + never happened. + + On the other hand, if the process record and replay target is + stopped while in replay mode (that is, not at the end of the + execution log, but at some earlier point), the inferior process + will become "live" at that earlier state, and it will then be + possible to continue the usual "live" debugging of the process from + that state. + + When the inferior process exits, or GDB detaches from it, process + record and replay target will automatically stop itself. + +'record goto' + Go to a specific location in the execution log. There are several + ways to specify the location to go to: + + 'record goto begin' + 'record goto start' + Go to the beginning of the execution log. + + 'record goto end' + Go to the end of the execution log. + + 'record goto N' + Go to instruction number N in the execution log. + +'record save FILENAME' + Save the execution log to a file 'FILENAME'. Default filename is + 'gdb_record.PROCESS_ID', where PROCESS_ID is the process ID of the + inferior. + + This command may not be available for all recording methods. + +'record restore FILENAME' + Restore the execution log from a file 'FILENAME'. File must have + been created with 'record save'. + +'set record full insn-number-max LIMIT' +'set record full insn-number-max unlimited' + Set the limit of instructions to be recorded for the 'full' + recording method. Default value is 200000. + + If LIMIT is a positive number, then GDB will start deleting + instructions from the log once the number of the record + instructions becomes greater than LIMIT. For every new recorded + instruction, GDB will delete the earliest recorded instruction to + keep the number of recorded instructions at the limit. (Since + deleting recorded instructions loses information, GDB lets you + control what happens when the limit is reached, by means of the + 'stop-at-limit' option, described below.) + + If LIMIT is 'unlimited' or zero, GDB will never delete recorded + instructions from the execution log. The number of recorded + instructions is limited only by the available memory. + +'show record full insn-number-max' + Show the limit of instructions to be recorded with the 'full' + recording method. + +'set record full stop-at-limit' + Control the behavior of the 'full' recording method when the number + of recorded instructions reaches the limit. If ON (the default), + GDB will stop when the limit is reached for the first time and ask + you whether you want to stop the inferior or continue running it + and recording the execution log. If you decide to continue + recording, each new recorded instruction will cause the oldest one + to be deleted. + + If this option is OFF, GDB will automatically delete the oldest + record to make room for each new one, without asking. + +'show record full stop-at-limit' + Show the current setting of 'stop-at-limit'. + +'set record full memory-query' + Control the behavior when GDB is unable to record memory changes + caused by an instruction for the 'full' recording method. If ON, + GDB will query whether to stop the inferior in that case. + + If this option is OFF (the default), GDB will automatically ignore + the effect of such instructions on memory. Later, when GDB replays + this execution log, it will mark the log of this instruction as not + accessible, and it will not affect the replay results. + +'show record full memory-query' + Show the current setting of 'memory-query'. + + The 'btrace' record target does not trace data. As a convenience, + when replaying, GDB reads read-only memory off the live program + directly, assuming that the addresses of the read-only areas don't + change. This for example makes it possible to disassemble code + while replaying, but not to print variables. In some cases, being + able to inspect variables might be useful. You can use the + following command for that: + +'set record btrace replay-memory-access' + Control the behavior of the 'btrace' recording method when + accessing memory during replay. If 'read-only' (the default), GDB + will only allow accesses to read-only memory. If 'read-write', GDB + will allow accesses to read-only and to read-write memory. Beware + that the accessed memory corresponds to the live target and not + necessarily to the current replay position. + +'set record btrace cpu IDENTIFIER' + Set the processor to be used for enabling workarounds for processor + errata when decoding the trace. + + Processor errata are defects in processor operation, caused by its + design or manufacture. They can cause a trace not to match the + specification. This, in turn, may cause trace decode to fail. GDB + can detect erroneous trace packets and correct them, thus avoiding + the decoding failures. These corrections are known as "errata + workarounds", and are enabled based on the processor on which the + trace was recorded. + + By default, GDB attempts to detect the processor automatically, and + apply the necessary workarounds for it. However, you may need to + specify the processor if GDB does not yet support it. This command + allows you to do that, and also allows to disable the workarounds. + + The argument IDENTIFIER identifies the CPU and is of the form: + 'VENDOR:PROCESSOR IDENTIFIER'. In addition, there are two special + identifiers, 'none' and 'auto' (default). + + The following vendor identifiers and corresponding processor + identifiers are currently supported: + + 'intel' FAMILY/MODEL[/STEPPING] + + + On GNU/Linux systems, the processor FAMILY, MODEL, and STEPPING can + be obtained from '/proc/cpuinfo'. + + If IDENTIFIER is 'auto', enable errata workarounds for the + processor on which the trace was recorded. If IDENTIFIER is + 'none', errata workarounds are disabled. + + For example, when using an old GDB on a new system, decode may fail + because GDB does not support the new processor. It often suffices + to specify an older processor that GDB supports. + + (gdb) info record + Active record target: record-btrace + Recording format: Intel Processor Trace. + Buffer size: 16kB. + Failed to configure the Intel Processor Trace decoder: unknown cpu. + (gdb) set record btrace cpu intel:6/158 + (gdb) info record + Active record target: record-btrace + Recording format: Intel Processor Trace. + Buffer size: 16kB. + Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...). + +'show record btrace replay-memory-access' + Show the current setting of 'replay-memory-access'. + +'show record btrace cpu' + Show the processor to be used for enabling trace decode errata + workarounds. + +'set record btrace bts buffer-size SIZE' +'set record btrace bts buffer-size unlimited' + Set the requested ring buffer size for branch tracing in BTS + format. Default is 64KB. + + If SIZE is a positive number, then GDB will try to allocate a + buffer of at least SIZE bytes for each new thread that uses the + btrace recording method and the BTS format. The actually obtained + buffer size may differ from the requested SIZE. Use the 'info + record' command to see the actual buffer size for each thread that + uses the btrace recording method and the BTS format. + + If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer + of 4MB. + + Bigger buffers mean longer traces. On the other hand, GDB will + also need longer to process the branch trace data before it can be + used. + +'show record btrace bts buffer-size SIZE' + Show the current setting of the requested ring buffer size for + branch tracing in BTS format. + +'set record btrace pt buffer-size SIZE' +'set record btrace pt buffer-size unlimited' + Set the requested ring buffer size for branch tracing in Intel + Processor Trace format. Default is 16KB. + + If SIZE is a positive number, then GDB will try to allocate a + buffer of at least SIZE bytes for each new thread that uses the + btrace recording method and the Intel Processor Trace format. The + actually obtained buffer size may differ from the requested SIZE. + Use the 'info record' command to see the actual buffer size for + each thread. + + If LIMIT is 'unlimited' or zero, GDB will try to allocate a buffer + of 4MB. + + Bigger buffers mean longer traces. On the other hand, GDB will + also need longer to process the branch trace data before it can be + used. + +'show record btrace pt buffer-size SIZE' + Show the current setting of the requested ring buffer size for + branch tracing in Intel Processor Trace format. + +'set record btrace pt event-tracing' + Enable or disable event tracing for branch tracing in Intel + Processor Trace format. When enabled, events are recorded during + execution as auxiliary information and will be printed during + stepping commands and commands displaying the execution history. + Changing this setting has no effect on an active recording. The + default is off. + +'show record btrace pt event-tracing' + Show the current setting of Intel Processor Trace event tracing. + +'info record' + Show various statistics about the recording depending on the + recording method: + + 'full' + For the 'full' recording method, it shows the state of process + record and its in-memory execution log buffer, including: + + * Whether in record mode or replay mode. + * Lowest recorded instruction number (counting from when + the current execution log started recording + instructions). + * Highest recorded instruction number. + * Current instruction about to be replayed (if in replay + mode). + * Number of instructions contained in the execution log. + * Maximum number of instructions that may be contained in + the execution log. + + 'btrace' + For the 'btrace' recording method, it shows: + + * Recording format. + * Number of instructions that have been recorded. + * Number of blocks of sequential control-flow formed by the + recorded instructions. + * Whether in record mode or replay mode. + + For the 'bts' recording format, it also shows: + * Size of the perf ring buffer. + + For the 'pt' recording format, it also shows: + * Size of the perf ring buffer. + +'record delete' + When record target runs in replay mode ("in the past"), delete the + subsequent execution log and begin to record a new execution log + starting from the current address. This means you will abandon the + previously recorded "future" and begin recording a new "future". + +'record instruction-history' + Disassembles instructions from the recorded execution log. By + default, ten instructions are disassembled. This can be changed + using the 'set record instruction-history-size' command. + Instructions are printed in execution order. + + It can also print mixed source+disassembly if you specify the the + '/m' or '/s' modifier, and print the raw instructions in hex as + well as in symbolic form by specifying the '/r' or '/b' modifier. + The behavior of the '/m', '/s', '/r', and '/b' modifiers are the + same as for the 'disassemble' command (*note 'disassemble': + disassemble.). + + The current position marker is printed for the instruction at the + current program counter value. This instruction can appear + multiple times in the trace and the current position marker will be + printed every time. To omit the current position marker, specify + the '/p' modifier. + + To better align the printed instructions when the trace contains + instructions from more than one function, the function name may be + omitted by specifying the '/f' modifier. + + Printing auxiliary information is enabled by default and can be + omitted with the '/a' modifier. + + Speculatively executed instructions are prefixed with '?'. This + feature is not available for all recording formats. + + There are several ways to specify what part of the execution log to + disassemble: + + 'record instruction-history INSN' + Disassembles ten instructions starting from instruction number + INSN. + + 'record instruction-history INSN, +/-N' + Disassembles N instructions around instruction number INSN. + If N is preceded with '+', disassembles N instructions after + instruction number INSN. If N is preceded with '-', + disassembles N instructions before instruction number INSN. + + 'record instruction-history' + Disassembles ten more instructions after the last disassembly. + + 'record instruction-history -' + Disassembles ten more instructions before the last + disassembly. + + 'record instruction-history BEGIN, END' + Disassembles instructions beginning with instruction number + BEGIN until instruction number END. The instruction number + END is included. + + This command may not be available for all recording methods. + +'set record instruction-history-size SIZE' +'set record instruction-history-size unlimited' + Define how many instructions to disassemble in the 'record + instruction-history' command. The default value is 10. A SIZE of + 'unlimited' means unlimited instructions. + +'show record instruction-history-size' + Show how many instructions to disassemble in the 'record + instruction-history' command. + +'record function-call-history' + Prints the execution history at function granularity. For each + sequence of instructions that belong to the same function, it + prints the name of that function, the source lines for this + instruction sequence (if the '/l' modifier is specified), and the + instructions numbers that form the sequence (if the '/i' modifier + is specified). The function names are indented to reflect the call + stack depth if the '/c' modifier is specified. Printing auxiliary + information is enabled by default and can be omitted with the '/a' + modifier. The '/l', '/i', '/a', and '/c' modifiers can be given + together. + + (gdb) list 1, 10 + 1 void foo (void) + 2 { + 3 } + 4 + 5 void bar (void) + 6 { + 7 ... + 8 foo (); + 9 ... + 10 } + (gdb) record function-call-history /ilc + 1 bar inst 1,4 at foo.c:6,8 + 2 foo inst 5,10 at foo.c:2,3 + 3 bar inst 11,13 at foo.c:9,10 + + By default, ten functions are printed. This can be changed using + the 'set record function-call-history-size' command. Functions are + printed in execution order. There are several ways to specify what + to print: + + 'record function-call-history FUNC' + Prints ten functions starting from function number FUNC. + + 'record function-call-history FUNC, +/-N' + Prints N functions around function number FUNC. If N is + preceded with '+', prints N functions after function number + FUNC. If N is preceded with '-', prints N functions before + function number FUNC. + + 'record function-call-history' + Prints ten more functions after the last ten-function print. + + 'record function-call-history -' + Prints ten more functions before the last ten-function print. + + 'record function-call-history BEGIN, END' + Prints functions beginning with function number BEGIN until + function number END. The function number END is included. + + This command may not be available for all recording methods. + +'set record function-call-history-size SIZE' +'set record function-call-history-size unlimited' + Define how many functions to print in the 'record + function-call-history' command. The default value is 10. A size + of 'unlimited' means unlimited functions. + +'show record function-call-history-size' + Show how many functions to print in the 'record + function-call-history' command. + diff -pruN 16.3-5/gdb/doc/gdb.info-2 16.3-5ubuntu1/gdb/doc/gdb.info-2 --- 16.3-5/gdb/doc/gdb.info-2 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-2 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,7141 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Stack, Next: Source, Prev: Process Record and Replay, Up: Top + +8 Examining the Stack +********************* + +When your program has stopped, the first thing you need to know is where +it stopped and how it got there. + + Each time your program performs a function call, information about +the call is generated. That information includes the location of the +call in your program, the arguments of the call, and the local variables +of the function being called. The information is saved in a block of +data called a "stack frame". The stack frames are allocated in a region +of memory called the "call stack". + + When your program stops, the GDB commands for examining the stack +allow you to see all of this information. + + One of the stack frames is "selected" by GDB and many GDB commands +refer implicitly to the selected frame. In particular, whenever you ask +GDB for the value of a variable in your program, the value is found in +the selected frame. There are special GDB commands to select whichever +frame you are interested in. *Note Selecting a Frame: Selection. + + When your program stops, GDB automatically selects the currently +executing frame and describes it briefly, similar to the 'frame' command +(*note Information about a Frame: Frame Info.). + +* Menu: + +* Frames:: Stack frames +* Backtrace:: Backtraces +* Selection:: Selecting a frame +* Frame Info:: Information on a frame +* Frame Apply:: Applying a command to several frames +* Frame Filter Management:: Managing frame filters + + +File: gdb.info, Node: Frames, Next: Backtrace, Up: Stack + +8.1 Stack Frames +================ + +The call stack is divided up into contiguous pieces called "stack +frames", or "frames" for short; each frame is the data associated with +one call to one function. The frame contains the arguments given to the +function, the function's local variables, and the address at which the +function is executing. + + When your program is started, the stack has only one frame, that of +the function 'main'. This is called the "initial" frame or the +"outermost" frame. Each time a function is called, a new frame is made. +Each time a function returns, the frame for that function invocation is +eliminated. If a function is recursive, there can be many frames for +the same function. The frame for the function in which execution is +actually occurring is called the "innermost" frame. This is the most +recently created of all the stack frames that still exist. + + Inside your program, stack frames are identified by their addresses. +A stack frame consists of many bytes, each of which has its own address; +each kind of computer has a convention for choosing one byte whose +address serves as the address of the frame. Usually this address is +kept in a register called the "frame pointer register" (*note $fp: +Registers.) while execution is going on in that frame. + + GDB labels each existing stack frame with a "level", a number that is +zero for the innermost frame, one for the frame that called it, and so +on upward. These level numbers give you a way of designating stack +frames in GDB commands. The terms "frame number" and "frame level" can +be used interchangeably to describe this number. + + Some compilers provide a way to compile functions so that they +operate without stack frames. (For example, the GCC option + '-fomit-frame-pointer' + generates functions without a frame.) This is occasionally done with +heavily used library functions to save the frame setup time. GDB has +limited facilities for dealing with these function invocations. If the +innermost function invocation has no stack frame, GDB nevertheless +regards it as though it had a separate frame, which is numbered zero as +usual, allowing correct tracing of the function call chain. However, +GDB has no provision for frameless functions elsewhere in the stack. + + +File: gdb.info, Node: Backtrace, Next: Selection, Prev: Frames, Up: Stack + +8.2 Backtraces +============== + +A backtrace is a summary of how your program got where it is. It shows +one line per frame, for many frames, starting with the currently +executing frame (frame zero), followed by its caller (frame one), and on +up the stack. + + To print a backtrace of the entire stack, use the 'backtrace' +command, or its alias 'bt'. This command will print one line per frame +for frames in the stack. By default, all stack frames are printed. You +can stop the backtrace at any time by typing the system interrupt +character, normally 'Ctrl-c'. + +'backtrace [OPTION]... [QUALIFIER]... [COUNT]' +'bt [OPTION]... [QUALIFIER]... [COUNT]' + Print the backtrace of the entire stack. + + The optional COUNT can be one of the following: + + 'N' + 'N' + Print only the innermost N frames, where N is a positive + number. + + '-N' + '-N' + Print only the outermost N frames, where N is a positive + number. + + Options: + + '-full' + Print the values of the local variables also. This can be + combined with the optional COUNT to limit the number of frames + shown. + + '-no-filters' + Do not run Python frame filters on this backtrace. *Note + Frame Filter API::, for more information. Additionally use + *note disable frame-filter all:: to turn off all frame + filters. This is only relevant when GDB has been configured + with 'Python' support. + + '-hide' + A Python frame filter might decide to "elide" some frames. + Normally such elided frames are still printed, but they are + indented relative to the filtered frames that cause them to be + elided. The '-hide' option causes elided frames to not be + printed at all. + + The 'backtrace' command also supports a number of options that + allow overriding relevant global print settings as set by 'set + backtrace' and 'set print' subcommands: + + '-past-main [on|off]' + Set whether backtraces should continue past 'main'. Related + setting: *note set backtrace past-main::. + + '-past-entry [on|off]' + Set whether backtraces should continue past the entry point of + a program. Related setting: *note set backtrace past-entry::. + + '-entry-values no|only|preferred|if-needed|both|compact|default' + Set printing of function arguments at function entry. Related + setting: *note set print entry-values::. + + '-frame-arguments all|scalars|none' + Set printing of non-scalar frame arguments. Related setting: + *note set print frame-arguments::. + + '-raw-frame-arguments [on|off]' + Set whether to print frame arguments in raw form. Related + setting: *note set print raw-frame-arguments::. + + '-frame-info auto|source-line|location|source-and-location|location-and-address|short-location' + Set printing of frame information. Related setting: *note set + print frame-info::. + + The optional QUALIFIER is maintained for backward compatibility. + It can be one of the following: + + 'full' + Equivalent to the '-full' option. + + 'no-filters' + Equivalent to the '-no-filters' option. + + 'hide' + Equivalent to the '-hide' option. + + The names 'where' and 'info stack' (abbreviated 'info s') are +additional aliases for 'backtrace'. + + In a multi-threaded program, GDB by default shows the backtrace only +for the current thread. To display the backtrace for several or all of +the threads, use the command 'thread apply' (*note thread apply: +Threads.). For example, if you type 'thread apply all backtrace', GDB +will display the backtrace for all the threads; this is handy when you +debug a core dump of a multi-threaded program. + + Each line in the backtrace shows the frame number and the function +name. The program counter value is also shown--unless you use 'set +print address off'. The backtrace also shows the source file name and +line number, as well as the arguments to the function. The program +counter value is omitted if it is at the beginning of the code for that +line number. + + Here is an example of a backtrace. It was made with the command 'bt +3', so it shows the innermost three frames. + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The display for frame zero does not begin with a program counter value, +indicating that your program has stopped at the beginning of the code +for line '993' of 'builtin.c'. + +The value of parameter 'data' in frame 1 has been replaced by '...'. By +default, GDB prints the value of a parameter only if it is a scalar +(integer, pointer, enumeration, etc). See command 'set print +frame-arguments' in *note Print Settings:: for more details on how to +configure the way function parameter values are printed. The command +'set print frame-info' (*note Print Settings::) controls what frame +information is printed. + + If your program was compiled with optimizations, some compilers will +optimize away arguments passed to functions if those arguments are never +used after the call. Such optimizations generate code that passes +arguments through registers, but doesn't store those arguments in the +stack frame. GDB has no way of displaying such arguments in stack +frames other than the innermost one. Here's what such a backtrace might +look like: + + #0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 + #1 0x6e38 in expand_macro (sym=) at macro.c:242 + #2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08) + at macro.c:71 + (More stack frames follow...) + +The values of arguments that were not saved in their stack frames are +shown as ''. + + If you need to display the values of such optimized-out arguments, +either deduce that from other variables whose values depend on the one +you are interested in, or recompile without optimizations. + + Most programs have a standard user entry point--a place where system +libraries and startup code transition into user code. For C this is +'main'(1). When GDB finds the entry function in a backtrace it will +terminate the backtrace, to avoid tracing into highly system-specific +(and generally uninteresting) code. + + If you need to examine the startup code, or limit the number of +levels in a backtrace, you can change this behavior: + +'set backtrace past-main' +'set backtrace past-main on' + Backtraces will continue past the user entry point. + +'set backtrace past-main off' + Backtraces will stop when they encounter the user entry point. + This is the default. + +'show backtrace past-main' + Display the current user entry point backtrace policy. + +'set backtrace past-entry' +'set backtrace past-entry on' + Backtraces will continue past the internal entry point of an + application. This entry point is encoded by the linker when the + application is built, and is likely before the user entry point + 'main' (or equivalent) is called. + +'set backtrace past-entry off' + Backtraces will stop when they encounter the internal entry point + of an application. This is the default. + +'show backtrace past-entry' + Display the current internal entry point backtrace policy. + +'set backtrace limit N' +'set backtrace limit 0' +'set backtrace limit unlimited' + Limit the backtrace to N levels. A value of 'unlimited' or zero + means unlimited levels. + +'show backtrace limit' + Display the current limit on backtrace levels. + + You can control how file names are displayed. + +'set filename-display' +'set filename-display relative' + Display file names relative to the compilation directory. This is + the default. + +'set filename-display basename' + Display only basename of a filename. + +'set filename-display absolute' + Display an absolute filename. + +'show filename-display' + Show the current way to display filenames. + + ---------- Footnotes ---------- + + (1) Note that embedded programs (the so-called "free-standing" +environment) are not required to have a 'main' function as the entry +point. They could even have multiple entry points. + + +File: gdb.info, Node: Selection, Next: Frame Info, Prev: Backtrace, Up: Stack + +8.3 Selecting a Frame +===================== + +Most commands for examining the stack and other data in your program +work on whichever stack frame is selected at the moment. Here are the +commands for selecting a stack frame; all of them finish by printing a +brief description of the stack frame just selected. + +'frame [ FRAME-SELECTION-SPEC ]' +'f [ FRAME-SELECTION-SPEC ]' + The 'frame' command allows different stack frames to be selected. + The FRAME-SELECTION-SPEC can be any of the following: + + 'NUM' + 'level NUM' + Select frame level NUM. Recall that frame zero is the + innermost (currently executing) frame, frame one is the frame + that called the innermost one, and so on. The highest level + frame is usually the one for 'main'. + + As this is the most common method of navigating the frame + stack, the string 'level' can be omitted. For example, the + following two commands are equivalent: + + (gdb) frame 3 + (gdb) frame level 3 + + 'address STACK-ADDRESS' + Select the frame with stack address STACK-ADDRESS. The + STACK-ADDRESS for a frame can be seen in the output of 'info + frame', for example: + + (gdb) info frame + Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 + + The STACK-ADDRESS for this frame is '0x7fffffffda30' as + indicated by the line: + + Stack level 1, frame at 0x7fffffffda30: + + 'function FUNCTION-NAME' + Select the stack frame for function FUNCTION-NAME. If there + are multiple stack frames for function FUNCTION-NAME then the + inner most stack frame is selected. + + 'view STACK-ADDRESS [ PC-ADDR ]' + View a frame that is not part of GDB's backtrace. The frame + viewed has stack address STACK-ADDR, and optionally, a program + counter address of PC-ADDR. + + This is useful mainly if the chaining of stack frames has been + damaged by a bug, making it impossible for GDB to assign + numbers properly to all frames. In addition, this can be + useful when your program has multiple stacks and switches + between them. + + When viewing a frame outside the current backtrace using + 'frame view' then you can always return to the original stack + using one of the previous stack frame selection instructions, + for example 'frame level 0'. + +'up N' + Move N frames up the stack; N defaults to 1. For positive numbers + N, this advances toward the outermost frame, to higher frame + numbers, to frames that have existed longer. + +'down N' + Move N frames down the stack; N defaults to 1. For positive + numbers N, this advances toward the innermost frame, to lower frame + numbers, to frames that were created more recently. You may + abbreviate 'down' as 'do'. + + All of these commands end by printing two lines of output describing +the frame. The first line shows the frame number, the function name, +the arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + + For example: + + (gdb) up + #1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 + 10 read_input_file (argv[i]); + + After such a printout, the 'list' command with no arguments prints +ten lines centered on the point of execution in the frame. You can also +edit the program at the point of execution with your favorite editing +program by typing 'edit'. *Note Printing Source Lines: List, for +details. + +'select-frame [ FRAME-SELECTION-SPEC ]' + The 'select-frame' command is a variant of 'frame' that does not + display the new frame after selecting it. This command is intended + primarily for use in GDB command scripts, where the output might be + unnecessary and distracting. The FRAME-SELECTION-SPEC is as for + the 'frame' command described in *note Selecting a Frame: + Selection. + +'up-silently N' +'down-silently N' + These two commands are variants of 'up' and 'down', respectively; + they differ in that they do their work silently, without causing + display of the new frame. They are intended primarily for use in + GDB command scripts, where the output might be unnecessary and + distracting. + + +File: gdb.info, Node: Frame Info, Next: Frame Apply, Prev: Selection, Up: Stack + +8.4 Information About a Frame +============================= + +There are several other commands to print information about the selected +stack frame. + +'frame' +'f' + When used without any argument, this command does not change which + frame is selected, but prints a brief description of the currently + selected stack frame. It can be abbreviated 'f'. With an + argument, this command is used to select a stack frame. *Note + Selecting a Frame: Selection. + +'info frame' +'info f' + This command prints a verbose description of the selected stack + frame, including: + + * the address of the frame + * the address of the next frame down (called by this frame) + * the address of the next frame up (caller of this frame) + * the language in which the source code corresponding to this + frame is written + * the address of the frame's arguments + * the address of the frame's local variables + * the program counter saved in it (the address of execution in + the caller frame) + * which registers were saved in the frame + + The verbose description is useful when something has gone wrong + that has made the stack format fail to fit the usual conventions. + +'info frame [ FRAME-SELECTION-SPEC ]' +'info f [ FRAME-SELECTION-SPEC ]' + Print a verbose description of the frame selected by + FRAME-SELECTION-SPEC. The FRAME-SELECTION-SPEC is the same as for + the 'frame' command (*note Selecting a Frame: Selection.). The + selected frame remains unchanged by this command. + +'info args [-q]' + Print the arguments of the selected frame, each on a separate line. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no argument have + been printed. + +'info args [-q] [-t TYPE_REGEXP] [REGEXP]' + Like 'info args', but only print the arguments selected with the + provided regexp(s). + + If REGEXP is provided, print only the arguments whose names match + the regular expression REGEXP. + + If TYPE_REGEXP is provided, print only the arguments whose types, + as printed by the 'whatis' command, match the regular expression + TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be + enclosed in quote characters. If needed, use backslash to escape + the meaning of special characters or quotes. + + If both REGEXP and TYPE_REGEXP are provided, an argument is printed + only if its name matches REGEXP and its type matches TYPE_REGEXP. + +'info locals [-q]' + Print the local variables of the selected frame, each on a separate + line. These are all variables (declared either static or + automatic) accessible at the point of execution of the selected + frame. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no local variables + have been printed. + +'info locals [-q] [-t TYPE_REGEXP] [REGEXP]' + Like 'info locals', but only print the local variables selected + with the provided regexp(s). + + If REGEXP is provided, print only the local variables whose names + match the regular expression REGEXP. + + If TYPE_REGEXP is provided, print only the local variables whose + types, as printed by the 'whatis' command, match the regular + expression TYPE_REGEXP. If TYPE_REGEXP contains space(s), it + should be enclosed in quote characters. If needed, use backslash + to escape the meaning of special characters or quotes. + + If both REGEXP and TYPE_REGEXP are provided, a local variable is + printed only if its name matches REGEXP and its type matches + TYPE_REGEXP. + + The command 'info locals -q -t TYPE_REGEXP' can usefully be + combined with the commands 'frame apply' and 'thread apply'. For + example, your program might use Resource Acquisition Is + Initialization types (RAII) such as 'lock_something_t': each local + variable of type 'lock_something_t' automatically places a lock + that is destroyed when the variable goes out of scope. You can + then list all acquired locks in your program by doing + thread apply all -s frame apply all -s info locals -q -t lock_something_t + or the equivalent shorter form + tfaas i lo -q -t lock_something_t + + +File: gdb.info, Node: Frame Apply, Next: Frame Filter Management, Prev: Frame Info, Up: Stack + +8.5 Applying a Command to Several Frames. +========================================= + +'frame apply [all | COUNT | -COUNT | level LEVEL...] [OPTION]... COMMAND' + The 'frame apply' command allows you to apply the named COMMAND to + one or more frames. + + 'all' + Specify 'all' to apply COMMAND to all frames. + + 'COUNT' + Use COUNT to apply COMMAND to the innermost COUNT frames, + where COUNT is a positive number. + + '-COUNT' + Use -COUNT to apply COMMAND to the outermost COUNT frames, + where COUNT is a positive number. + + 'level' + Use 'level' to apply COMMAND to the set of frames identified + by the LEVEL list. LEVEL is a frame level or a range of frame + levels as LEVEL1-LEVEL2. The frame level is the number shown + in the first field of the 'backtrace' command output. E.g., + '2-4 6-8 3' indicates to apply COMMAND for the frames at + levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3. + + Note that the frames on which 'frame apply' applies a command are + also influenced by the 'set backtrace' settings such as 'set + backtrace past-main' and 'set backtrace limit N'. *Note + Backtraces: Backtrace. + + The 'frame apply' command also supports a number of options that + allow overriding relevant 'set backtrace' settings: + + '-past-main [on|off]' + Whether backtraces should continue past 'main'. Related + setting: *note set backtrace past-main::. + + '-past-entry [on|off]' + Whether backtraces should continue past the entry point of a + program. Related setting: *note set backtrace past-entry::. + + By default, GDB displays some frame information before the output + produced by COMMAND, and an error raised during the execution of a + COMMAND will abort 'frame apply'. The following options can be + used to fine-tune these behaviors: + + '-c' + The flag '-c', which stands for 'continue', causes any errors + in COMMAND to be displayed, and the execution of 'frame apply' + then continues. + '-s' + The flag '-s', which stands for 'silent', causes any errors or + empty output produced by a COMMAND to be silently ignored. + That is, the execution continues, but the frame information + and errors are not printed. + '-q' + The flag '-q' ('quiet') disables printing the frame + information. + + The following example shows how the flags '-c' and '-s' are working + when applying the command 'p j' to all frames, where variable 'j' + can only be successfully printed in the outermost '#1 main' frame. + + (gdb) frame apply all p j + #0 some_function (i=5) at fun.c:4 + No symbol "j" in current context. + (gdb) frame apply all -c p j + #0 some_function (i=5) at fun.c:4 + No symbol "j" in current context. + #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 + $1 = 5 + (gdb) frame apply all -s p j + #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 + $2 = 5 + (gdb) + + By default, 'frame apply', prints the frame location information + before the command output: + + (gdb) frame apply all p $sp + #0 some_function (i=5) at fun.c:4 + $4 = (void *) 0xffffd1e0 + #1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 + $5 = (void *) 0xffffd1f0 + (gdb) + + If the flag '-q' is given, no frame information is printed: + (gdb) frame apply all -q p $sp + $12 = (void *) 0xffffd1e0 + $13 = (void *) 0xffffd1f0 + (gdb) + +'faas COMMAND' + Shortcut for 'frame apply all -s COMMAND'. Applies COMMAND on all + frames, ignoring errors and empty output. + + It can for example be used to print a local variable or a function + argument without knowing the frame where this variable or argument + is, using: + (gdb) faas p some_local_var_i_do_not_remember_where_it_is + + The 'faas' command accepts the same options as the 'frame apply' + command. *Note frame apply: Frame Apply. + + Note that the command 'tfaas COMMAND' applies COMMAND on all frames + of all threads. See *Note Threads: Threads. + + +File: gdb.info, Node: Frame Filter Management, Prev: Frame Apply, Up: Stack + +8.6 Management of Frame Filters. +================================ + +Frame filters are Python based utilities to manage and decorate the +output of frames. *Note Frame Filter API::, for further information. + + Managing frame filters is performed by several commands available +within GDB, detailed here. + +'info frame-filter' + Print a list of installed frame filters from all dictionaries, + showing their name, priority and enabled status. + +'disable frame-filter FILTER-DICTIONARY FILTER-NAME' + Disable a frame filter in the dictionary matching FILTER-DICTIONARY + and FILTER-NAME. The FILTER-DICTIONARY may be 'all', 'global', + 'progspace', or the name of the object file where the frame filter + dictionary resides. When 'all' is specified, all frame filters + across all dictionaries are disabled. The FILTER-NAME is the name + of the frame filter and is used when 'all' is not the option for + FILTER-DICTIONARY. A disabled frame-filter is not deleted, it may + be enabled again later. + +'enable frame-filter FILTER-DICTIONARY FILTER-NAME' + Enable a frame filter in the dictionary matching FILTER-DICTIONARY + and FILTER-NAME. The FILTER-DICTIONARY may be 'all', 'global', + 'progspace' or the name of the object file where the frame filter + dictionary resides. When 'all' is specified, all frame filters + across all dictionaries are enabled. The FILTER-NAME is the name + of the frame filter and is used when 'all' is not the option for + FILTER-DICTIONARY. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 Yes BuildProgramFilter + + (gdb) disable frame-filter /build/test BuildProgramFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) enable frame-filter global PrimaryFunctionFilter + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +'set frame-filter priority FILTER-DICTIONARY FILTER-NAME PRIORITY' + Set the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + The FILTER-DICTIONARY may be 'global', 'progspace' or the name of + the object file where the frame filter dictionary resides. The + PRIORITY is an integer. + +'show frame-filter priority FILTER-DICTIONARY FILTER-NAME' + Show the PRIORITY of a frame filter in the dictionary matching + FILTER-DICTIONARY, and the frame filter name matching FILTER-NAME. + The FILTER-DICTIONARY may be 'global', 'progspace' or the name of + the object file where the frame filter dictionary resides. + + Example: + + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + (gdb) set frame-filter priority global Reverse 50 + (gdb) info frame-filter + + global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 50 Yes Reverse + + progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + + objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + + +File: gdb.info, Node: Source, Next: Data, Prev: Stack, Up: Top + +9 Examining Source Files +************************ + +GDB can print parts of your program's source, since the debugging +information recorded in the program tells GDB what source files were +used to build it. When your program stops, GDB spontaneously prints the +line where it stopped. Likewise, when you select a stack frame (*note +Selecting a Frame: Selection.), GDB prints the line where execution in +that frame has stopped. You can print other portions of source files by +explicit command. + + If you use GDB through its GNU Emacs interface, you may prefer to use +Emacs facilities to view source; see *note Using GDB under GNU Emacs: +Emacs. + +* Menu: + +* List:: Printing source lines +* Location Specifications:: How to specify code locations +* Edit:: Editing source files +* Search:: Searching source files +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code +* Disable Reading Source:: Disable Reading Source Code + + +File: gdb.info, Node: List, Next: Location Specifications, Up: Source + +9.1 Printing Source Lines +========================= + +To print lines from a source file, use the 'list' command (abbreviated +'l'). By default, ten lines are printed. There are several ways to +specify what part of the file you want to print; see *note Location +Specifications::, for the full list. + + Here are the forms of the 'list' command most commonly used: + +'list LINENUM' + Print lines centered around line number LINENUM in the current + source file. + +'list FUNCTION' + Print lines centered around the beginning of function FUNCTION. + +'list' + Print more lines. If the last lines printed were printed with a + 'list' command, this prints lines following the last lines printed; + however, if the last line printed was a solitary line printed as + part of displaying a stack frame (*note Examining the Stack: + Stack.), this prints lines centered around that line. If no 'list' + command has been used and no solitary line was printed, it prints + the lines around the function 'main'. + +'list +' + Same as using with no arguments. + +'list -' + Print lines just before the lines last printed. + +'list .' + Print the lines surrounding the point of execution within the + currently selected frame. If the inferior is not running, print + lines around the start of the main function instead. + + By default, GDB prints ten source lines with any of these forms of +the 'list' command. You can change this using 'set listsize': + +'set listsize COUNT' +'set listsize unlimited' + Make the 'list' command display COUNT source lines (unless the + 'list' argument explicitly specifies some other number). Setting + COUNT to 'unlimited' or 0 means there's no limit. + +'show listsize' + Display the number of lines that 'list' prints. + + Repeating a 'list' command with discards the argument, so it is +equivalent to typing just 'list'. This is more useful than listing the +same lines again. An exception is made for an argument of '-'; that +argument is preserved in repetition so that each repetition moves up in +the source file. + + In general, the 'list' command expects you to supply zero, one or two +location specs. These location specs are interpreted to resolve to +source code lines; there are several ways of writing them (*note +Location Specifications::), but the effect is always to resolve to some +source lines to display. + + Here is a complete description of the possible arguments for 'list': + +'list LOCSPEC' + Print lines centered around the line or lines of all the code + locations that result from resolving LOCSPEC. + +'list FIRST,LAST' + Print lines from FIRST to LAST. Both arguments are location specs. + When a 'list' command has two location specs, and the source file + of the second location spec is omitted, this refers to the same + source file as the first location spec. If either FIRST or LAST + resolve to more than one source line in the program, then the list + command shows the list of resolved source lines and does not + proceed with the source code listing. + +'list ,LAST' + Print lines ending with LAST. + + Likewise, if LAST resolves to more than one source line in the + program, then the list command prints the list of resolved source + lines and does not proceed with the source code listing. + +'list FIRST,' + Print lines starting with FIRST. + +'list +' + Print lines just after the lines last printed. + +'list -' + Print lines just before the lines last printed. + +'list' + As described in the preceding table. + + +File: gdb.info, Node: Location Specifications, Next: Edit, Prev: List, Up: Source + +9.2 Location Specifications +=========================== + +Several GDB commands accept arguments that specify a location or +locations of your program's code. Many times locations are specified +using a source line number, but they can also be specified by a function +name, an address, a label, etc. The different forms of specifying a +location that GDB recognizes are collectively known as forms of +"location specification", or "location spec". This section documents +the forms of specifying locations that GDB recognizes. + + When you specify a location, GDB needs to find the place in your +program, known as "code location", that corresponds to the given +location spec. We call this process of finding actual code locations +corresponding to a location spec "location resolution". + + A concrete code location in your program is uniquely identifiable by +a set of several attributes: its source line number, the name of its +source file, the fully-qualified and prototyped function in which it is +defined, and an instruction address. Because each inferior has its own +address space, the inferior number is also a necessary part of these +attributes. + + By contrast, location specs you type will many times omit some of +these attributes. For example, it is customary to specify just the +source line number to mean a line in the current source file, or specify +just the basename of the file, omitting its directories. In other +words, a location spec is usually incomplete, a kind of blueprint, and +GDB needs to complete the missing attributes by using the implied +defaults, and by considering the source code and the debug information +available to it. This is what location resolution is about. + + The resolution of an incomplete location spec can produce more than a +single code location, if the spec doesn't allow distinguishing between +them. Here are some examples of situations that result in a location +spec matching multiple code locations in your program: + + * The location spec specifies a function name, and there are several + functions in the program which have that name. (To distinguish + between them, you can specify a fully-qualified and prototyped + function name, such as 'A::func(int)' instead of just 'func'.) + + * The location spec specifies a source file name, and there are + several source files in the program that share the same name, for + example several files with the same basename in different + subdirectories. (To distinguish between them, specify enough + leading directories with the file name.) + + * For a C++ constructor, the GCC compiler generates several instances + of the function body, used in different cases, but their + source-level names are identical. + + * For a C++ template function, a given line in the function can + correspond to any number of instantiations. + + * For an inlined function, a given source line can correspond to + several actual code locations with that function's inlined code. + + Resolution of a location spec can also fail to produce a complete +code location, or even fail to produce any code location. Here are some +examples of such situations: + + * Some parts of the program lack detailed enough debug info, so the + resolved code location lacks some attributes, like source file name + and line number, leaving just the instruction address and perhaps + also a function name. Such an incomplete code location is only + usable in contexts that work with addresses and/or function names. + Some commands can only work with complete code locations. + + * The location spec specifies a function name, and there are no + functions in the program by that name, or they only exist in a + yet-unloaded shared library. + + * The location spec specifies a source file name, and there are no + source files in the program by that name, or they only exist in a + yet-unloaded shared library. + + * The location spec specifies both a source file name and a source + line number, and even though there are source files in the program + that match the file name, none of those files has the specified + line number. + + Locations may be specified using three different formats: linespec +locations, explicit locations, or address locations. The following +subsections describe these formats. + +* Menu: + +* Linespec Locations:: Linespec locations +* Explicit Locations:: Explicit locations +* Address Locations:: Address locations + + +File: gdb.info, Node: Linespec Locations, Next: Explicit Locations, Up: Location Specifications + +9.2.1 Linespec Locations +------------------------ + +A "linespec" is a colon-separated list of source location parameters +such as file name, function name, etc. Here are all the different ways +of specifying a linespec: + +'LINENUM' + Specifies the line number LINENUM of the current source file. + +'-OFFSET' +'+OFFSET' + Specifies the line OFFSET lines before or after the "current line". + For the 'list' command, the current line is the last one printed; + for the breakpoint commands, this is the line at which execution + stopped in the currently selected "stack frame" (*note Frames: + Frames, for a description of stack frames.) When used as the + second of the two linespecs in a 'list' command, this specifies the + line OFFSET lines up or down from the first linespec. + +'FILENAME:LINENUM' + Specifies the line LINENUM in the source file FILENAME. If + FILENAME is a relative file name, then it will match any source + file name with the same trailing components. For example, if + FILENAME is 'gcc/expr.c', then it will match source file name of + '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or + '/build/trunk/gcc/x-expr.c'. + +'FUNCTION' + Specifies the line that begins the body of the function FUNCTION. + For example, in C, this is the line with the open brace. + + By default, in C++ and Ada, FUNCTION is interpreted as specifying + all functions named FUNCTION in all scopes. For C++, this means in + all namespaces and classes. For Ada, this means in all packages. + + For example, assuming a program with C++ symbols named 'A::B::func' + and 'B::func', both commands 'break func' and 'break B::func' set a + breakpoint on both symbols. + + Commands that accept a linespec let you override this with the + '-qualified' option. For example, 'break -qualified func' sets a + breakpoint on a free-function named 'func' ignoring any C++ class + methods and namespace functions called 'func'. + + *Note Explicit Locations::. + +'FUNCTION:LABEL' + Specifies the line where LABEL appears in FUNCTION. + +'FILENAME:FUNCTION' + Specifies the line that begins the body of the function FUNCTION in + the file FILENAME. You only need the file name with a function + name to avoid ambiguity when there are identically named functions + in different source files. + +'LABEL' + Specifies the line at which the label named LABEL appears in the + function corresponding to the currently selected stack frame. If + there is no current selected stack frame (for instance, if the + inferior is not running), then GDB will not search for a label. + +'-pstap|-probe-stap [OBJFILE:[PROVIDER:]]NAME' + The GNU/Linux tool 'SystemTap' provides a way for applications to + embed static probes. *Note Static Probe Points::, for more + information on finding and using static probes. This form of + linespec specifies the location of such a static probe. + + If OBJFILE is given, only probes coming from that shared library or + executable matching OBJFILE as a regular expression are considered. + If PROVIDER is given, then only probes from that provider are + considered. If several probes match the spec, GDB will insert a + breakpoint at each one of those probes. + + +File: gdb.info, Node: Explicit Locations, Next: Address Locations, Prev: Linespec Locations, Up: Location Specifications + +9.2.2 Explicit Locations +------------------------ + +"Explicit locations" allow the user to directly specify the source +location's parameters using option-value pairs. + + Explicit locations are useful when several functions, labels, or file +names have the same name (base name for files) in the program's sources. +In these cases, explicit locations point to the source line you meant +more accurately and unambiguously. Also, using explicit locations might +be faster in large programs. + + For example, the linespec 'foo:bar' may refer to a function 'bar' +defined in the file named 'foo' or the label 'bar' in a function named +'foo'. GDB must search either the file system or the symbol table to +know. + + The list of valid explicit location options is summarized in the +following table: + +'-source FILENAME' + The value specifies the source file name. To differentiate between + files with the same base name, prepend as many directories as is + necessary to uniquely identify the desired file, e.g., + 'foo/bar/baz.c'. Otherwise GDB will use the first file it finds + with the given base name. This option requires the use of either + '-function' or '-line'. + +'-function FUNCTION' + The value specifies the name of a function. Operations on function + locations unmodified by other options (such as '-label' or '-line') + refer to the line that begins the body of the function. In C, for + example, this is the line with the open brace. + + By default, in C++ and Ada, FUNCTION is interpreted as specifying + all functions named FUNCTION in all scopes. For C++, this means in + all namespaces and classes. For Ada, this means in all packages. + + For example, assuming a program with C++ symbols named 'A::B::func' + and 'B::func', both commands 'break -function func' and + 'break -function B::func' set a breakpoint on both symbols. + + You can use the '-qualified' flag to override this (see below). + +'-qualified' + + This flag makes GDB interpret a function name specified with + '-function' as a complete fully-qualified name. + + For example, assuming a C++ program with symbols named 'A::B::func' + and 'B::func', the 'break -qualified -function B::func' command + sets a breakpoint on 'B::func', only. + + (Note: the '-qualified' option can precede a linespec as well + (*note Linespec Locations::), so the particular example above could + be simplified as 'break -qualified B::func'.) + +'-label LABEL' + The value specifies the name of a label. When the function name is + not specified, the label is searched in the function of the + currently selected stack frame. + +'-line NUMBER' + The value specifies a line offset for the location. The offset may + either be absolute ('-line 3') or relative ('-line +3'), depending + on the command. When specified without any other options, the line + offset is relative to the current line. + + Explicit location options may be abbreviated by omitting any +non-unique trailing characters from the option name, e.g., +'break -s main.c -li 3'. + + +File: gdb.info, Node: Address Locations, Prev: Explicit Locations, Up: Location Specifications + +9.2.3 Address Locations +----------------------- + +"Address locations" indicate a specific program address. They have the +generalized form *ADDRESS. + + For line-oriented commands, such as 'list' and 'edit', this specifies +a source line that contains ADDRESS. For 'break' and other +breakpoint-oriented commands, this can be used to set breakpoints in +parts of your program which do not have debugging information or source +files. + + Here ADDRESS may be any expression valid in the current working +language (*note working language: Languages.) that specifies a code +address. In addition, as a convenience, GDB extends the semantics of +expressions used in locations to cover several situations that +frequently occur during debugging. Here are the various forms of +ADDRESS: + +'EXPRESSION' + Any expression valid in the current working language. + +'FUNCADDR' + An address of a function or procedure derived from its name. In C, + C++, Objective-C, Fortran, minimal, and assembly, this is simply + the function's name FUNCTION (and actually a special case of a + valid expression). In Pascal and Modula-2, this is '&FUNCTION'. + In Ada, this is 'FUNCTION'Address' (although the Pascal form also + works). + + This form specifies the address of the function's first + instruction, before the stack frame and arguments have been set up. + +''FILENAME':FUNCADDR' + Like FUNCADDR above, but also specifies the name of the source file + explicitly. This is useful if the name of the function does not + specify the function unambiguously, e.g., if there are several + functions with identical names in different source files. + + +File: gdb.info, Node: Edit, Next: Search, Prev: Location Specifications, Up: Source + +9.3 Editing Source Files +======================== + +To edit the lines in a source file, use the 'edit' command. The editing +program of your choice is invoked with the current line set to the +active line in the program. Alternatively, there are several ways to +specify what part of the file you want to print if you want to see other +parts of the program: + +'edit LOCSPEC' + Edit the source file of the code location that results from + resolving 'locspec'. Editing starts at the source file and source + line 'locspec' resolves to. *Note Location Specifications::, for + all the possible forms of the LOCSPEC argument. + + If 'locspec' resolves to more than one source line in your program, + then the command prints the list of resolved source lines and does + not proceed with the editing. + + Here are the forms of the 'edit' command most commonly used: + + 'edit NUMBER' + Edit the current source file with NUMBER as the active line + number. + + 'edit FUNCTION' + Edit the file containing FUNCTION at the beginning of its + definition. + +9.3.1 Choosing your Editor +-------------------------- + +You can customize GDB to use any editor you want (1). By default, it is +'/bin/ex', but you can change this by setting the environment variable +'EDITOR' before using GDB. For example, to configure GDB to use the +'vi' editor, you could use these commands with the 'sh' shell: + EDITOR=/usr/bin/vi + export EDITOR + gdb ... + or in the 'csh' shell, + setenv EDITOR /usr/bin/vi + gdb ... + + ---------- Footnotes ---------- + + (1) The only restriction is that your editor (say 'ex'), recognizes +the following command-line syntax: + ex +NUMBER file + The optional numeric value +NUMBER specifies the number of the line +in the file where to start editing. + + +File: gdb.info, Node: Search, Next: Source Path, Prev: Edit, Up: Source + +9.4 Searching Source Files +========================== + +There are two commands for searching through the current source file for +a regular expression. + +'forward-search REGEXP' +'search REGEXP' + The command 'forward-search REGEXP' checks each line, starting with + the one following the last line listed, for a match for REGEXP. It + lists the line that is found. You can use the synonym 'search + REGEXP' or abbreviate the command name as 'fo'. + +'reverse-search REGEXP' + The command 'reverse-search REGEXP' checks each line, starting with + the one before the last line listed and going backward, for a match + for REGEXP. It lists the line that is found. You can abbreviate + this command as 'rev'. + + +File: gdb.info, Node: Source Path, Next: Machine Code, Prev: Search, Up: Source + +9.5 Specifying Source Directories +================================= + +Executable programs sometimes do not record the directories of the +source files from which they were compiled, just the names. Even when +they do, the directories could be moved between the compilation and your +debugging session. GDB has a list of directories to search for source +files; this is called the "source path". Each time GDB wants a source +file, it tries all the directories in the list, in the order they are +present in the list, until it finds a file with the desired name. + + For example, suppose an executable references the file +'/usr/src/foo-1.0/lib/foo.c', does not record a compilation directory, +and the "source path" is '/mnt/cross'. GDB would look for the source +file in the following locations: + + 1. '/usr/src/foo-1.0/lib/foo.c' + 2. '/mnt/cross/usr/src/foo-1.0/lib/foo.c' + 3. '/mnt/cross/foo.c' + + If the source file is not present at any of the above locations then +an error is printed. GDB does not look up the parts of the source file +name, such as '/mnt/cross/src/foo-1.0/lib/foo.c'. Likewise, the +subdirectories of the source path are not searched: if the source path +is '/mnt/cross', and the binary refers to 'foo.c', GDB would not find it +under '/mnt/cross/usr/src/foo-1.0/lib'. + + Plain file names, relative file names with leading directories, file +names containing dots, etc. are all treated as described above, except +that non-absolute file names are not looked up literally. If the +"source path" is '/mnt/cross', the source file is recorded as +'../lib/foo.c', and no compilation directory is recorded, then GDB will +search in the following locations: + + 1. '/mnt/cross/../lib/foo.c' + 2. '/mnt/cross/foo.c' + + The "source path" will always include two special entries '$cdir' and +'$cwd', these refer to the compilation directory (if one is recorded) +and the current working directory respectively. + + '$cdir' causes GDB to search within the compilation directory, if one +is recorded in the debug information. If no compilation directory is +recorded in the debug information then '$cdir' is ignored. + + '$cwd' is not the same as '.'--the former tracks the current working +directory as it changes during your GDB session, while the latter is +immediately expanded to the current directory at the time you add an +entry to the source path. + + If a compilation directory is recorded in the debug information, and +GDB has not found the source file after the first search using "source +path", then GDB will combine the compilation directory and the filename, +and then search for the source file again using the "source path". + + For example, if the executable records the source file as +'/usr/src/foo-1.0/lib/foo.c', the compilation directory is recorded as +'/project/build', and the "source path" is '/mnt/cross:$cdir:$cwd' while +the current working directory of the GDB session is '/home/user', then +GDB will search for the source file in the following locations: + + 1. '/usr/src/foo-1.0/lib/foo.c' + 2. '/mnt/cross/usr/src/foo-1.0/lib/foo.c' + 3. '/project/build/usr/src/foo-1.0/lib/foo.c' + 4. '/home/user/usr/src/foo-1.0/lib/foo.c' + 5. '/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c' + 6. '/project/build/project/build/usr/src/foo-1.0/lib/foo.c' + 7. '/home/user/project/build/usr/src/foo-1.0/lib/foo.c' + 8. '/mnt/cross/foo.c' + 9. '/project/build/foo.c' + 10. '/home/user/foo.c' + + If the file name in the previous example had been recorded in the +executable as a relative path rather than an absolute path, then the +first look up would not have occurred, but all of the remaining steps +would be similar. + + When searching for source files on MS-DOS and MS-Windows, where +absolute paths start with a drive letter (e.g. 'C:/project/foo.c'), GDB +will remove the drive letter from the file name before appending it to a +search directory from "source path"; for instance if the executable +references the source file 'C:/project/foo.c' and "source path" is set +to 'D:/mnt/cross', then GDB will search in the following locations for +the source file: + + 1. 'C:/project/foo.c' + 2. 'D:/mnt/cross/project/foo.c' + 3. 'D:/mnt/cross/foo.c' + + Note that the executable search path is _not_ used to locate the +source files. + + Whenever you reset or rearrange the source path, GDB clears out any +information it has cached about where source files are found and where +each line is in the file. + + When you start GDB, its source path includes only '$cdir' and '$cwd', +in that order. To add other directories, use the 'directory' command. + + The search path is used to find both program source files and GDB +script files (read using the '-command' option and 'source' command). + + In addition to the source path, GDB provides a set of commands that +manage a list of source path substitution rules. A "substitution rule" +specifies how to rewrite source directories stored in the program's +debug information in case the sources were moved to a different +directory between compilation and debugging. A rule is made of two +strings, the first specifying what needs to be rewritten in the path, +and the second specifying how it should be rewritten. In *note set +substitute-path::, we name these two parts FROM and TO respectively. +GDB does a simple string replacement of FROM with TO at the start of the +directory part of the source file name, and uses that result instead of +the original file name to look up the sources. + + Using the previous example, suppose the 'foo-1.0' tree has been moved +from '/usr/src' to '/mnt/cross', then you can tell GDB to replace +'/usr/src' in all source path names with '/mnt/cross'. The first lookup +will then be '/mnt/cross/foo-1.0/lib/foo.c' in place of the original +location of '/usr/src/foo-1.0/lib/foo.c'. To define a source path +substitution rule, use the 'set substitute-path' command (*note set +substitute-path::). + + To avoid unexpected substitution results, a rule is applied only if +the FROM part of the directory name ends at a directory separator. For +instance, a rule substituting '/usr/source' into '/mnt/cross' will be +applied to '/usr/source/foo-1.0' but not to '/usr/sourceware/foo-2.0'. +And because the substitution is applied only at the beginning of the +directory name, this rule will not be applied to +'/root/usr/source/baz.c' either. + + In many cases, you can achieve the same result using the 'directory' +command. However, 'set substitute-path' can be more efficient in the +case where the sources are organized in a complex tree with multiple +subdirectories. With the 'directory' command, you need to add each +subdirectory of your project. If you moved the entire tree while +preserving its internal organization, then 'set substitute-path' allows +you to direct the debugger to all the sources with one single command. + + 'set substitute-path' is also more than just a shortcut command. The +source path is only used if the file at the original location no longer +exists. On the other hand, 'set substitute-path' modifies the debugger +behavior to look at the rewritten location instead. So, if for any +reason a source file that is not relevant to your executable is located +at the original location, a substitution rule is the only method +available to point GDB at the new location. + + You can configure a default source path substitution rule by +configuring GDB with the '--with-relocated-sources=DIR' option. The DIR +should be the name of a directory under GDB's configured prefix (set +with '--prefix' or '--exec-prefix'), and directory names in debug +information under DIR will be adjusted automatically if the installed +GDB is moved to a new location. This is useful if GDB, libraries or +executables with debug information and corresponding source code are +being moved together. + +'directory DIRNAME ...' +'dir DIRNAME ...' + Add directory DIRNAME to the front of the source path. Several + directory names may be given to this command, separated by ':' (';' + on MS-DOS and MS-Windows, where ':' usually appears as part of + absolute file names) or whitespace. You may specify a directory + that is already in the source path; this moves it forward, so GDB + searches it sooner. + + The special strings '$cdir' (to refer to the compilation directory, + if one is recorded), and '$cwd' (to refer to the current working + directory) can also be included in the list of directories DIRNAME. + Though these will already be in the source path they will be moved + forward in the list so GDB searches them sooner. + +'directory' + Reset the source path to its default value ('$cdir:$cwd' on Unix + systems). This requires confirmation. + +'set directories PATH-LIST' + Set the source path to PATH-LIST. '$cdir:$cwd' are added if + missing. + +'show directories' + Print the source path: show which directories it contains. + +'set substitute-path FROM TO' + Define a source path substitution rule, and add it at the end of + the current list of existing substitution rules. If a rule with + the same FROM was already defined, then the old rule is also + deleted. + + For example, if the file '/foo/bar/baz.c' was moved to + '/mnt/cross/baz.c', then the command + + (gdb) set substitute-path /foo/bar /mnt/cross + + will tell GDB to replace '/foo/bar' with '/mnt/cross', which will + allow GDB to find the file 'baz.c' even though it was moved. + + In the case when more than one substitution rule have been defined, + the rules are evaluated one by one in the order where they have + been defined. The first one matching, if any, is selected to + perform the substitution. + + For instance, if we had entered the following commands: + + (gdb) set substitute-path /usr/src/include /mnt/include + (gdb) set substitute-path /usr/src /mnt/src + + GDB would then rewrite '/usr/src/include/defs.h' into + '/mnt/include/defs.h' by using the first rule. However, it would + use the second rule to rewrite '/usr/src/lib/foo.c' into + '/mnt/src/lib/foo.c'. + +'unset substitute-path [path]' + If a path is specified, search the current list of substitution + rules for a rule that would rewrite that path. Delete that rule if + found. A warning is emitted by the debugger if no rule could be + found. + + If no path is specified, then all substitution rules are deleted. + +'show substitute-path [path]' + If a path is specified, then print the source path substitution + rule which would rewrite that path, if any. + + If no path is specified, then print all existing source path + substitution rules. + + If your source path is cluttered with directories that are no longer +of interest, GDB may sometimes cause confusion by finding the wrong +versions of source. You can correct the situation as follows: + + 1. Use 'directory' with no argument to reset the source path to its + default value. + + 2. Use 'directory' with suitable arguments to reinstall the + directories you want in the source path. You can add all the + directories in one command. + + +File: gdb.info, Node: Machine Code, Next: Disable Reading Source, Prev: Source Path, Up: Source + +9.6 Source and Machine Code +=========================== + +You can use the command 'info line' to map source lines to program +addresses (and vice versa), and the command 'disassemble' to display a +range of addresses as machine instructions. You can use the command +'set disassemble-next-line' to set whether to disassemble next source +line when execution stops. When run under GNU Emacs mode, the 'info +line' command causes the arrow to point to the line specified. Also, +'info line' prints addresses in symbolic form as well as hex. + +'info line' +'info line LOCSPEC' + Print the starting and ending addresses of the compiled code for + the source lines of the code locations that result from resolving + LOCSPEC. *Note Location Specifications::, for the various forms of + LOCSPEC. With no LOCSPEC, information about the current source + line is printed. + + For example, we can use 'info line' to discover the location of the +object code for the first line of function 'm4_changequote': + + (gdb) info line m4_changequote + Line 895 of "builtin.c" starts at pc 0x634c and \ + ends at 0x6350 . + +We can also inquire, using '*ADDR' as the form for LOCSPEC, what source +line covers a particular address ADDR: + (gdb) info line *0x63ff + Line 926 of "builtin.c" starts at pc 0x63e4 and \ + ends at 0x6404 . + + After 'info line', the default address for the 'x' command is changed +to the starting address of the line, so that 'x/i' is sufficient to +begin examining the machine code (*note Examining Memory: Memory.). +Also, this address is saved as the value of the convenience variable +'$_' (*note Convenience Variables: Convenience Vars.). + + After 'info line', using 'info line' again without specifying a +location will display information about the next source line. + +'disassemble' +'disassemble /m' +'disassemble /s' +'disassemble /r' +'disassemble /b' + This specialized command dumps a range of memory as machine + instructions. It can also print mixed source+disassembly by + specifying the '/m' or '/s' modifier and print the raw instructions + in hex as well as in symbolic form by specifying the '/r' or '/b' + modifier. + + Only one of '/m' and '/s' can be used, attempting to use both flag + will give an error. + + Only one of '/r' and '/b' can be used, attempting to use both flag + will give an error. + + The default memory range is the function surrounding the program + counter of the selected frame. A single argument to this command + is a program counter value; GDB dumps the function surrounding this + value. When two arguments are given, they should be separated by a + comma, possibly surrounded by whitespace. The arguments specify a + range of addresses to dump, in one of two forms: + + 'START,END' + the addresses from START (inclusive) to END (exclusive) + 'START,+LENGTH' + the addresses from START (inclusive) to 'START+LENGTH' + (exclusive). + + When 2 arguments are specified, the name of the function is also + printed (since there could be several functions in the given + range). + + The argument(s) can be any expression yielding a numeric value, + such as '0x32c4', '&main+10' or '$pc - 8'. + + If the range of memory being disassembled contains current program + counter, the instruction at that location is shown with a '=>' + marker. + + The following example shows the disassembly of a range of addresses +of HP PA-RISC 2.0 code: + + (gdb) disas 0x32c4, 0x32e4 + Dump of assembler code from 0x32c4 to 0x32e4: + 0x32c4 : addil 0,dp + 0x32c8 : ldw 0x22c(sr0,r1),r26 + 0x32cc : ldil 0x3000,r31 + 0x32d0 : ble 0x3f8(sr4,r31) + 0x32d4 : ldo 0(r31),rp + 0x32d8 : addil -0x800,dp + 0x32dc : ldo 0x588(r1),r26 + 0x32e0 : ldil 0x3000,r31 + End of assembler dump. + + The following two examples are for RISC-V, and demonstrates the +difference between the '/r' and '/b' modifiers. First with '/b', the +bytes of the instruction are printed, in hex, in memory order: + + (gdb) disassemble /b 0x00010150,0x0001015c + Dump of assembler code from 0x10150 to 0x1015c: + 0x00010150 : 22 dc sw s0,56(sp) + 0x00010152 : 80 00 addi s0,sp,64 + 0x00010154 : 23 26 a4 fe sw a0,-20(s0) + 0x00010158 : 23 24 b4 fe sw a1,-24(s0) + End of assembler dump. + + In contrast, with '/r' the bytes of the instruction are displayed in +the instruction order, for RISC-V this means that the bytes have been +swapped to little-endian order: + + (gdb) disassemble /r 0x00010150,0x0001015c + Dump of assembler code from 0x10150 to 0x1015c: + 0x00010150 : dc22 sw s0,56(sp) + 0x00010152 : 0080 addi s0,sp,64 + 0x00010154 : fea42623 sw a0,-20(s0) + 0x00010158 : feb42423 sw a1,-24(s0) + End of assembler dump. + + Here is an example showing mixed source+assembly for Intel x86 with +'/m' or '/s', when the program is stopped just after function prologue +in a non-optimized function with no inline code. + + (gdb) disas /m main + Dump of assembler code for function main: + 5 { + 0x08048330 <+0>: push %ebp + 0x08048331 <+1>: mov %esp,%ebp + 0x08048333 <+3>: sub $0x8,%esp + 0x08048336 <+6>: and $0xfffffff0,%esp + 0x08048339 <+9>: sub $0x10,%esp + + 6 printf ("Hello.\n"); + => 0x0804833c <+12>: movl $0x8048440,(%esp) + 0x08048343 <+19>: call 0x8048284 + + 7 return 0; + 8 } + 0x08048348 <+24>: mov $0x0,%eax + 0x0804834d <+29>: leave + 0x0804834e <+30>: ret + + End of assembler dump. + + The '/m' option is deprecated as its output is not useful when there +is either inlined code or re-ordered code. The '/s' option is the +preferred choice. Here is an example for AMD x86-64 showing the +difference between '/m' output and '/s' output. This example has one +inline function defined in a header file, and the code is compiled with +'-O2' optimization. Note how the '/m' output is missing the disassembly +of several instructions that are present in the '/s' output. + + 'foo.h': + + int + foo (int a) + { + if (a < 0) + return a * 2; + if (a == 0) + return 1; + return a + 10; + } + + 'foo.c': + + #include "foo.h" + volatile int x, y; + int + main () + { + x = foo (y); + return 0; + } + + (gdb) disas /m main + Dump of assembler code for function main: + 5 { + + 6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + + 7 return 0; + 8 } + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 + + End of assembler dump. + (gdb) disas /s main + Dump of assembler code for function main: + foo.c: + 5 { + 6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + + foo.h: + 4 if (a < 0) + 0x0000000000400406 <+6>: test %eax,%eax + 0x0000000000400408 <+8>: js 0x400420 + + 6 if (a == 0) + 7 return 1; + 8 return a + 10; + 0x000000000040040a <+10>: lea 0xa(%rax),%edx + 0x000000000040040d <+13>: test %eax,%eax + 0x000000000040040f <+15>: mov $0x1,%eax + 0x0000000000400414 <+20>: cmovne %edx,%eax + + foo.c: + 6 x = foo (y); + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + + 7 return 0; + 8 } + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + + foo.h: + 5 return a * 2; + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 + End of assembler dump. + + Here is another example showing raw instructions in hex for AMD +x86-64, + + (gdb) disas /r 0x400281,+10 + Dump of assembler code from 0x400281 to 0x40028b: + 0x0000000000400281: 38 36 cmp %dh,(%rsi) + 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax + 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) + 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al + End of assembler dump. + + Note that the 'disassemble' command's address arguments are specified +using expressions in your programming language (*note Expressions: +Expressions.), not location specs (*note Location Specifications::). +So, for example, if you want to disassemble function 'bar' in file +'foo.c', you must type 'disassemble 'foo.c'::bar' and not 'disassemble +foo.c:bar'. + + Some architectures have more than one commonly-used set of +instruction mnemonics or other syntax. + + For programs that were dynamically linked and use shared libraries, +instructions that call functions or branch to locations in the shared +libraries might show a seemingly bogus location--it's actually a +location of the relocation table. On some architectures, GDB might be +able to resolve these to actual function names. + +'set disassembler-options OPTION1[,OPTION2...]' + This command controls the passing of target specific information to + the disassembler. For a list of valid options, please refer to the + '-M'/'--disassembler-options' section of the 'objdump' manual + and/or the output of 'objdump --help' (*note objdump: + (binutils)objdump.). The default value is the empty string. + + If it is necessary to specify more than one disassembler option, + then multiple options can be placed together into a comma separated + list. Currently this command is only supported on targets ARC, + ARM, MIPS, PowerPC and S/390. + +'show disassembler-options' + Show the current setting of the disassembler options. + +'set disassembly-flavor INSTRUCTION-SET' + Select the instruction set to use when disassembling the program + via the 'disassemble' or 'x/i' commands. + + Currently this command is only defined for the Intel x86 family. + You can set INSTRUCTION-SET to either 'intel' or 'att'. The + default is 'att', the AT&T flavor used by default by Unix + assemblers for x86-based targets. + +'show disassembly-flavor' + Show the current setting of the disassembly flavor. + +'set disassemble-next-line' +'show disassemble-next-line' + Control whether or not GDB will disassemble the next source line or + instruction when execution stops. If ON, GDB will display + disassembly of the next source line when execution of the program + being debugged stops. This is _in addition_ to displaying the + source line itself, which GDB always does if possible. If the next + source line cannot be displayed for some reason (e.g., if GDB + cannot find the source file, or there's no line info in the debug + info), GDB will display disassembly of the next _instruction_ + instead of showing the next source line. If AUTO, GDB will display + disassembly of next instruction only if the source line cannot be + displayed. This setting causes GDB to display some feedback when + you step through a function with no line info or whose source file + is unavailable. The default is OFF, which means never display the + disassembly of the next line or instruction. + + +File: gdb.info, Node: Disable Reading Source, Prev: Machine Code, Up: Source + +9.7 Disable Reading Source Code +=============================== + +In some cases it can be desirable to prevent GDB from accessing source +code files. One case where this might be desirable is if the source +code files are located over a slow network connection. + + The following command can be used to control whether GDB should +access source code files or not: + +'set source open [on|off]' +'show source open' + When this option is 'on', which is the default, GDB will access + source code files when needed, for example to print source lines + when GDB stops, or in response to the 'list' command. + + When this option is 'off', GDB will not access source code files. + + +File: gdb.info, Node: Data, Next: Optimized Code, Prev: Source, Up: Top + +10 Examining Data +***************** + +The usual way to examine data in your program is with the 'print' +command (abbreviated 'p'), or its synonym 'inspect'. It evaluates and +prints the value of an expression of the language your program is +written in (*note Using GDB with Different Languages: Languages.). It +may also print the expression using a Python-based pretty-printer (*note +Pretty Printing::). + +'print [[OPTIONS] --] EXPR' +'print [[OPTIONS] --] /F EXPR' + EXPR is an expression (in the source language). By default the + value of EXPR is printed in a format appropriate to its data type; + you can choose a different format by specifying '/F', where F is a + letter specifying the format; see *note Output Formats: Output + Formats. + + The 'print' command supports a number of options that allow + overriding relevant global print settings as set by 'set print' + subcommands: + + '-address [on|off]' + Set printing of addresses. Related setting: *note set print + address::. + + '-array [on|off]' + Pretty formatting of arrays. Related setting: *note set print + array::. + + '-array-indexes [on|off]' + Set printing of array indexes. Related setting: *note set + print array-indexes::. + + '-characters NUMBER-OF-CHARACTERS|elements|unlimited' + Set limit on string characters to print. The value 'elements' + causes the limit on array elements to print to be used. The + value 'unlimited' causes there to be no limit. Related + setting: *note set print characters::. + + '-elements NUMBER-OF-ELEMENTS|unlimited' + Set limit on array elements and optionally string characters + to print. See *note set print characters::, and the + '-characters' option above for when this option applies to + strings. The value 'unlimited' causes there to be no limit. + *Note set print elements::, for a related CLI command. + + '-max-depth DEPTH|unlimited' + Set the threshold after which nested structures are replaced + with ellipsis. Related setting: *note set print max-depth::. + + '-nibbles [on|off]' + Set whether to print binary values in groups of four bits, + known as "nibbles". *Note set print nibbles::. + + '-memory-tag-violations [on|off]' + Set printing of additional information about memory tag + violations. *Note set print memory-tag-violations::. + + '-null-stop [on|off]' + Set printing of char arrays to stop at first null char. + Related setting: *note set print null-stop::. + + '-object [on|off]' + Set printing C++ virtual function tables. Related setting: + *note set print object::. + + '-pretty [on|off]' + Set pretty formatting of structures. Related setting: *note + set print pretty::. + + '-raw-values [on|off]' + Set whether to print values in raw form, bypassing any + pretty-printers for that value. Related setting: *note set + print raw-values::. + + '-repeats NUMBER-OF-REPEATS|unlimited' + Set threshold for repeated print elements. 'unlimited' causes + all elements to be individually printed. Related setting: + *note set print repeats::. + + '-static-members [on|off]' + Set printing C++ static members. Related setting: *note set + print static-members::. + + '-symbol [on|off]' + Set printing of symbol names when printing pointers. Related + setting: *note set print symbol::. + + '-union [on|off]' + Set printing of unions interior to structures. Related + setting: *note set print union::. + + '-vtbl [on|off]' + Set printing of C++ virtual function tables. Related setting: + *note set print vtbl::. + + Because the 'print' command accepts arbitrary expressions which may + look like options (including abbreviations), if you specify any + command option, then you must use a double dash ('--') to mark the + end of option processing. + + For example, this prints the value of the '-p' expression: + + (gdb) print -p + + While this repeats the last value in the value history (see below) + with the '-pretty' option in effect: + + (gdb) print -p -- + + Here is an example including both on option and an expression: + + (gdb) print -pretty -- *myptr + $1 = { + next = 0x0, + flags = { + sweet = 1, + sour = 1 + }, + meat = 0x54 "Pork" + } + +'print [OPTIONS]' +'print [OPTIONS] /F' + If you omit EXPR, GDB displays the last value again (from the + "value history"; *note Value History: Value History.). This allows + you to conveniently inspect the same value in an alternative + format. + + If the architecture supports memory tagging, the 'print' command will +display pointer/memory tag mismatches if what is being printed is a +pointer or reference type. *Note Memory Tagging::. + + A more low-level way of examining data is with the 'x' command. It +examines data in memory at a specified address and prints it in a +specified format. *Note Examining Memory: Memory. + + If you are interested in information about types, or about how the +fields of a struct or a class are declared, use the 'ptype EXPR' command +rather than 'print'. *Note Examining the Symbol Table: Symbols. + + Another way of examining values of expressions and type information +is through the Python extension command 'explore' (available only if the +GDB build is configured with '--with-python'). It offers an interactive +way to start at the highest level (or, the most abstract level) of the +data type of an expression (or, the data type itself) and explore all +the way down to leaf scalar values/fields embedded in the higher level +data types. + +'explore ARG' + ARG is either an expression (in the source language), or a type + visible in the current context of the program being debugged. + + The working of the 'explore' command can be illustrated with an +example. If a data type 'struct ComplexStruct' is defined in your C +program as + + struct SimpleStruct + { + int i; + double d; + }; + + struct ComplexStruct + { + struct SimpleStruct *ss_p; + int arr[10]; + }; + +followed by variable declarations as + + struct SimpleStruct ss = { 10, 1.11 }; + struct ComplexStruct cs = { &ss, { 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 } }; + +then, the value of the variable 'cs' can be explored using the 'explore' +command as follows. + + (gdb) explore cs + The value of `cs' is a struct/class of type `struct ComplexStruct' with + the following fields: + + ss_p = + arr = + + Enter the field number of choice: + +Since the fields of 'cs' are not scalar values, you are being prompted +to chose the field you want to explore. Let's say you choose the field +'ss_p' by entering '0'. Then, since this field is a pointer, you will +be asked if it is pointing to a single value. From the declaration of +'cs' above, it is indeed pointing to a single value, hence you enter +'y'. If you enter 'n', then you will be asked if it were pointing to an +array of values, in which case this field will be explored as if it were +an array. + + `cs.ss_p' is a pointer to a value of type `struct SimpleStruct' + Continue exploring it as a pointer to a single value [y/n]: y + The value of `*(cs.ss_p)' is a struct/class of type `struct + SimpleStruct' with the following fields: + + i = 10 .. (Value of type `int') + d = 1.1100000000000001 .. (Value of type `double') + + Press enter to return to parent value: + +If the field 'arr' of 'cs' was chosen for exploration by entering '1' +earlier, then since it is as array, you will be prompted to enter the +index of the element in the array that you want to explore. + + `cs.arr' is an array of `int'. + Enter the index of the element you want to explore in `cs.arr': 5 + + `(cs.arr)[5]' is a scalar value of type `int'. + + (cs.arr)[5] = 4 + + Press enter to return to parent value: + + In general, at any stage of exploration, you can go deeper towards +the leaf values by responding to the prompts appropriately, or hit the +return key to return to the enclosing data structure (the higher level +data structure). + + Similar to exploring values, you can use the 'explore' command to +explore types. Instead of specifying a value (which is typically a +variable name or an expression valid in the current context of the +program being debugged), you specify a type name. If you consider the +same example as above, your can explore the type 'struct ComplexStruct' +by passing the argument 'struct ComplexStruct' to the 'explore' command. + + (gdb) explore struct ComplexStruct + +By responding to the prompts appropriately in the subsequent interactive +session, you can explore the type 'struct ComplexStruct' in a manner +similar to how the value 'cs' was explored in the above example. + + The 'explore' command also has two sub-commands, 'explore value' and +'explore type'. The former sub-command is a way to explicitly specify +that value exploration of the argument is being invoked, while the +latter is a way to explicitly specify that type exploration of the +argument is being invoked. + +'explore value EXPR' + This sub-command of 'explore' explores the value of the expression + EXPR (if EXPR is an expression valid in the current context of the + program being debugged). The behavior of this command is identical + to that of the behavior of the 'explore' command being passed the + argument EXPR. + +'explore type ARG' + This sub-command of 'explore' explores the type of ARG (if ARG is a + type visible in the current context of program being debugged), or + the type of the value/expression ARG (if ARG is an expression valid + in the current context of the program being debugged). If ARG is a + type, then the behavior of this command is identical to that of the + 'explore' command being passed the argument ARG. If ARG is an + expression, then the behavior of this command will be identical to + that of the 'explore' command being passed the type of ARG as the + argument. + +* Menu: + +* Expressions:: Expressions +* Ambiguous Expressions:: Ambiguous Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Memory Tagging:: Memory Tagging +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Pretty Printing:: Python pretty printing +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Convenience Funs:: Convenience functions +* Registers:: Registers +* Floating Point Hardware:: Floating point hardware +* Vector Unit:: Vector Unit +* OS Information:: Auxiliary data provided by operating system +* Memory Region Attributes:: Memory region attributes +* Dump/Restore Files:: Copy between memory and a file +* Core File Generation:: Cause a program dump its core +* Character Sets:: Debugging programs that use a different + character set than GDB does +* Caching Target Data:: Data caching for targets +* Searching Memory:: Searching memory for a sequence of bytes +* Value Sizes:: Managing memory allocated for values + + +File: gdb.info, Node: Expressions, Next: Ambiguous Expressions, Up: Data + +10.1 Expressions +================ + +'print' and many other GDB commands accept an expression and compute its +value. Any kind of constant, variable or operator defined by the +programming language you are using is valid in an expression in GDB. +This includes conditional expressions, function calls, casts, and string +constants. It also includes preprocessor macros, if you compiled your +program to include this information; see *note Compilation::. + + GDB supports array constants in expressions input by the user. The +syntax is {ELEMENT, ELEMENT...}. For example, you can use the command +'print {1, 2, 3}' to create an array of three integers. If you pass an +array to a function or assign it to a program variable, GDB copies the +array to memory that is 'malloc'ed in the target program. + + Because C is so widespread, most of the expressions shown in examples +in this manual are in C. *Note Using GDB with Different Languages: +Languages, for information on how to use expressions in other languages. + + In this section, we discuss operators that you can use in GDB +expressions regardless of your programming language. + + Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer in order to examine a structure +at that address in memory. + + GDB supports these operators, in addition to those common to +programming languages: + +'@' + '@' is a binary operator for treating parts of memory as arrays. + *Note Artificial Arrays: Arrays, for more information. + +'::' + '::' allows you to specify a variable in terms of the file or + function where it is defined. *Note Program Variables: Variables. + +'{TYPE} ADDR' + Refers to an object of type TYPE stored at address ADDR in memory. + The address ADDR may be any expression whose value is an integer or + pointer (but parentheses are required around binary operators, just + as in a cast). This construct is allowed regardless of what kind + of data is normally supposed to reside at ADDR. + + +File: gdb.info, Node: Ambiguous Expressions, Next: Variables, Prev: Expressions, Up: Data + +10.2 Ambiguous Expressions +========================== + +Expressions can sometimes contain some ambiguous elements. For +instance, some programming languages (notably Ada, C++ and Objective-C) +permit a single function name to be defined several times, for +application in different contexts. This is called "overloading". +Another example involving Ada is generics. A "generic package" is +similar to C++ templates and is typically instantiated several times, +resulting in the same function name being defined in different contexts. + + In some cases and depending on the language, it is possible to adjust +the expression to remove the ambiguity. For instance in C++, you can +specify the signature of the function you want to break on, as in 'break +FUNCTION(TYPES)'. In Ada, using the fully qualified name of your +function often makes the expression unambiguous as well. + + When an ambiguity that needs to be resolved is detected, the debugger +has the capability to display a menu of numbered choices for each +possibility, and then waits for the selection with the prompt '>'. The +first option is always '[0] cancel', and typing '0 ' aborts the +current command. If the command in which the expression was used allows +more than one choice to be selected, the next option in the menu is '[1] +all', and typing '1 ' selects all possible choices. + + For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol 'String::after'. We choose three +particular definitions of that function name: + + (gdb) b String::after + [0] cancel + [1] all + [2] file:String.cc; line number:867 + [3] file:String.cc; line number:860 + [4] file:String.cc; line number:875 + [5] file:String.cc; line number:853 + [6] file:String.cc; line number:846 + [7] file:String.cc; line number:735 + > 2 4 6 + Breakpoint 1 at 0xb26c: file String.cc, line 867. + Breakpoint 2 at 0xb344: file String.cc, line 875. + Breakpoint 3 at 0xafcc: file String.cc, line 846. + Multiple breakpoints were set. + Use the "delete" command to delete unwanted + breakpoints. + (gdb) + +'set multiple-symbols MODE' + + This option allows you to adjust the debugger behavior when an + expression is ambiguous. + + By default, MODE is set to 'all'. If the command with which the + expression is used allows more than one choice, then GDB + automatically selects all possible choices. For instance, + inserting a breakpoint on a function using an ambiguous name + results in a breakpoint inserted on each possible match. However, + if a unique choice must be made, then GDB uses the menu to help you + disambiguate the expression. For instance, printing the address of + an overloaded function will result in the use of the menu. + + When MODE is set to 'ask', the debugger always uses the menu when + an ambiguity is detected. + + Finally, when MODE is set to 'cancel', the debugger reports an + error due to the ambiguity and the command is aborted. + +'show multiple-symbols' + Show the current value of the 'multiple-symbols' setting. + + +File: gdb.info, Node: Variables, Next: Arrays, Prev: Ambiguous Expressions, Up: Data + +10.3 Program Variables +====================== + +The most common kind of expression to use is the name of a variable in +your program. + + Variables in expressions are understood in the selected stack frame +(*note Selecting a Frame: Selection.); they must be either: + + * global (or file-static) + +or + + * visible according to the scope rules of the programming language + from the point of execution in that frame + +This means that in the function + + foo (a) + int a; + { + bar (a); + { + int b = test (); + bar (b); + } + } + +you can examine and use the variable 'a' whenever your program is +executing within the function 'foo', but you can only use or examine the +variable 'b' while your program is executing inside the block where 'b' +is declared. + + There is an exception: you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable or +function with the same name (in different source files). If that +happens, referring to that name has unpredictable effects. If you wish, +you can specify a static variable in a particular function or file by +using the colon-colon ('::') notation: + + FILE::VARIABLE + FUNCTION::VARIABLE + +Here FILE or FUNCTION is the name of the context for the static +VARIABLE. In the case of file names, you can use quotes to make sure +GDB parses the file name as a single word--for example, to print a +global value of 'x' defined in 'f2.c': + + (gdb) p 'f2.c'::x + + The '::' notation is normally used for referring to static variables, +since you typically disambiguate uses of local variables in functions by +selecting the appropriate frame and using the simple name of the +variable. However, you may also use this notation to refer to local +variables in frames enclosing the selected frame: + + void + foo (int a) + { + if (a < 10) + bar (a); + else + process (a); /* Stop here */ + } + + int + bar (int a) + { + foo (a + 5); + } + +For example, if there is a breakpoint at the commented line, here is +what you might see when the program stops after executing the call +'bar(0)': + + (gdb) p a + $1 = 10 + (gdb) p bar::a + $2 = 5 + (gdb) up 2 + #2 0x080483d0 in foo (a=5) at foobar.c:12 + (gdb) p a + $3 = 5 + (gdb) p bar::a + $4 = 0 + + These uses of '::' are very rarely in conflict with the very similar +use of the same notation in C++. When they are in conflict, the C++ +meaning takes precedence; however, this can be overridden by quoting the +file or function name with single quotes. + + For example, suppose the program is stopped in a method of a class +that has a field named 'includefile', and there is also an include file +named 'includefile' that defines a variable, 'some_global'. + + (gdb) p includefile + $1 = 23 + (gdb) p includefile::some_global + A syntax error in expression, near `'. + (gdb) p 'includefile'::some_global + $2 = 27 + + _Warning:_ Occasionally, a local variable may appear to have the + wrong value at certain points in a function--just after entry to a + new scope, and just before exit. + You may see this problem when you are stepping by machine +instructions. This is because, on most machines, it takes more than one +instruction to set up a stack frame (including local variable +definitions); if you are stepping by machine instructions, variables may +appear to have the wrong values until the stack frame is completely +built. On exit, it usually also takes more than one machine instruction +to destroy a stack frame; after you begin stepping through that group of +instructions, local variable definitions may be gone. + + This may also happen when the compiler does significant +optimizations. To be sure of always seeing accurate values, turn off +all optimization when compiling. + + Another possible effect of compiler optimizations is to optimize +unused variables out of existence, or assign variables to registers (as +opposed to memory addresses). Depending on the support for such cases +offered by the debug info format used by the compiler, GDB might not be +able to display values for such local variables. If that happens, GDB +will print a message like this: + + No symbol "foo" in current context. + + To solve such problems, either recompile without optimizations, or +use a different debug info format, if the compiler supports several such +formats. *Note Compilation::, for more information on choosing compiler +options. *Note C and C++: C, for more information about debug info +formats that are best suited to C++ programs. + + If you ask to print an object whose contents are unknown to GDB, +e.g., because its data type is not completely specified by the debug +information, GDB will say ''. *Note incomplete type: +Symbols, for more about this. + + If you try to examine or use the value of a (global) variable for +which GDB has no type information, e.g., because the program includes no +debug information, GDB displays an error message. *Note unknown type: +Symbols, for more about unknown types. If you cast the variable to its +declared type, GDB gets the variable's value using the cast-to type as +the variable's type. For example, in a C program: + + (gdb) p var + 'var' has unknown type; cast it to its declared type + (gdb) p (float) var + $1 = 3.14 + + If you append '@entry' string to a function parameter name you get +its value at the time the function got called. If the value is not +available an error message is printed. Entry values are available only +with some compilers. Entry values are normally also printed at the +function parameter list according to *note set print entry-values::. + + Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 + 29 i++; + (gdb) next + 30 e (i); + (gdb) print i + $1 = 31 + (gdb) print i@entry + $2 = 30 + + Strings are identified as arrays of 'char' values without specified +signedness. Arrays of either 'signed char' or 'unsigned char' get +printed as arrays of 1 byte sized integers. '-fsigned-char' or +'-funsigned-char' GCC options have no effect as GDB defines literal +string type '"char"' as 'char' without a sign. For program code + + char var0[] = "A"; + signed char var1[] = "A"; + + You get during debugging + (gdb) print var0 + $1 = "A" + (gdb) print var1 + $2 = {65 'A', 0 '\0'} + + +File: gdb.info, Node: Arrays, Next: Output Formats, Prev: Variables, Up: Data + +10.4 Artificial Arrays +====================== + +It is often useful to print out several successive objects of the same +type in memory; a section of an array, or an array of dynamically +determined size for which only a pointer exists in the program. + + You can do this by referring to a contiguous span of memory as an +"artificial array", using the binary operator '@'. The left operand of +'@' should be the first element of the desired array and be an +individual object. The right operand should be the desired length of +the array. The result is an array value whose elements are all of the +type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says + + int *array = (int *) malloc (len * sizeof (int)); + +you can print the contents of 'array' with + + p *array@len + + The left operand of '@' must reside in memory. Array values made +with '@' in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +Artificial arrays most often appear in expressions via the value history +(*note Value History: Value History.), after printing one out. + + Another way to create an artificial array is to use a cast. This +re-interprets a value as if it were an array. The value need not be in +memory: + (gdb) p/x (short[2])0x12345678 + $1 = {0x1234, 0x5678} + + As a convenience, if you leave the array length out (as in +'(TYPE[])VALUE') GDB calculates the size to fill the value (as +'sizeof(VALUE)/sizeof(TYPE)': + (gdb) p/x (short[])0x12345678 + $2 = {0x1234, 0x5678} + + Sometimes the artificial array mechanism is not quite enough; in +moderately complex data structures, the elements of interest may not +actually be adjacent--for example, if you are interested in the values +of pointers in an array. One useful work-around in this situation is to +use a convenience variable (*note Convenience Variables: Convenience +Vars.) as a counter in an expression that prints the first interesting +value, and then repeat that expression via . For instance, suppose +you have an array 'dtab' of pointers to structures, and you are +interested in the values of a field 'fv' in each structure. Here is an +example of what you might type: + + set $i = 0 + p dtab[$i++]->fv + + + ... + + +File: gdb.info, Node: Output Formats, Next: Memory, Prev: Arrays, Up: Data + +10.5 Output Formats +=================== + +By default, GDB prints a value according to its data type. Sometimes +this is not what you want. For example, you might want to print a +number in hex, or a pointer in decimal. Or you might want to view data +in memory at a certain address as a character string or as an +instruction. To do these things, specify an "output format" when you +print a value. + + The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the 'print' +command with a slash and a format letter. The format letters supported +are: + +'x' + Print the binary representation of the value in hexadecimal. + +'d' + Print the binary representation of the value in decimal. + +'u' + Print the binary representation of the value as an decimal, as if + it were unsigned. + +'o' + Print the binary representation of the value in octal. + +'t' + Print the binary representation of the value in binary. The letter + 't' stands for "two". (1) + +'a' + Print as an address, both absolute in hexadecimal and as an offset + from the nearest preceding symbol. You can use this format used to + discover where (in what function) an unknown address is located: + + (gdb) p/a 0x54320 + $3 = 0x54320 <_initialize_vx+396> + + The command 'info symbol 0x54320' yields similar results. *Note + info symbol: Symbols. + +'c' + Cast the value to an integer (unlike other formats, this does not + just reinterpret the underlying bits) and print it as a character + constant. This prints both the numerical value and its character + representation. The character representation is replaced with the + octal escape '\nnn' for characters outside the 7-bit ASCII range. + + Without this format, GDB displays 'char', 'unsigned char', and + 'signed char' data as character constants. Single-byte members of + vectors are displayed as integer data. + +'f' + Regard the bits of the value as a floating point number and print + using typical floating point syntax. + +'s' + Regard as a string, if possible. With this format, pointers to + single-byte data are displayed as null-terminated strings and + arrays of single-byte data are displayed as fixed-length strings. + Other values are displayed in their natural types. + + Without this format, GDB displays pointers to and arrays of 'char', + 'unsigned char', and 'signed char' as strings. Single-byte members + of a vector are displayed as an integer array. + +'z' + Like 'x' formatting, the value is treated as an integer and printed + as hexadecimal, but leading zeros are printed to pad the value to + the size of the integer type. + +'r' + Print using the 'raw' formatting. By default, GDB will use a + Python-based pretty-printer, if one is available (*note Pretty + Printing::). This typically results in a higher-level display of + the value's contents. The 'r' format bypasses any Python + pretty-printer which might exist. + + For example, to print the program counter in hex (*note Registers::), +type + + p/x $pc + +Note that no space is required before the slash; this is because command +names in GDB cannot contain a slash. + + To reprint the last value in the value history with a different +format, you can use the 'print' command with just a format and no +expression. For example, 'p/x' reprints the last value in hex. + + ---------- Footnotes ---------- + + (1) 'b' cannot be used because these format letters are also used +with the 'x' command, where 'b' stands for "byte"; see *note Examining +Memory: Memory. + + +File: gdb.info, Node: Memory, Next: Memory Tagging, Prev: Output Formats, Up: Data + +10.6 Examining Memory +===================== + +You can use the command 'x' (for "examine") to examine memory in any of +several formats, independently of your program's data types. + +'x/NFU ADDR' +'x ADDR' +'x' + Use the 'x' command to examine memory. + + N, F, and U are all optional parameters that specify how much memory +to display and how to format it; ADDR is an expression giving the +address where you want to start displaying memory. If you use defaults +for NFU, you need not type the slash '/'. Several commands set +convenient defaults for ADDR. + +N, the repeat count + The repeat count is a decimal integer; the default is 1. It + specifies how much memory (counting by units U) to display. If a + negative number is specified, memory is examined backward from + ADDR. + +F, the display format + The display format is one of the formats used by 'print' ('x', 'd', + 'u', 'o', 't', 'a', 'c', 'f', 's'), 'i' (for machine instructions) + and 'm' (for displaying memory tags). The default is 'x' + (hexadecimal) initially. The default changes each time you use + either 'x' or 'print'. + +U, the unit size + The unit size is any of + + 'b' + Bytes. + 'h' + Halfwords (two bytes). + 'w' + Words (four bytes). This is the initial default. + 'g' + Giant words (eight bytes). + + Each time you specify a unit size with 'x', that size becomes the + default unit the next time you use 'x'. For the 'i' format, the + unit size is ignored and is normally not written. For the 's' + format, the unit size defaults to 'b', unless it is explicitly + given. Use 'x /hs' to display 16-bit char strings and 'x /ws' to + display 32-bit strings. The next use of 'x /s' will again display + 8-bit strings. Note that the results depend on the programming + language of the current compilation unit. If the language is C, + the 's' modifier will use the UTF-16 encoding while 'w' will use + UTF-32. The encoding is set by the programming language and cannot + be altered. + +ADDR, starting display address + ADDR is the address where you want GDB to begin displaying memory. + The expression need not have a pointer value (though it may); it is + always interpreted as an integer address of a byte of memory. + *Note Expressions: Expressions, for more information on + expressions. The default for ADDR is usually just after the last + address examined--but several other commands also set the default + address: 'info breakpoints' (to the address of the last breakpoint + listed), 'info line' (to the starting address of a line), and + 'print' (if you use it to display a value from memory). + + For example, 'x/3uh 0x54320' is a request to display three halfwords +('h') of memory, formatted as unsigned decimal integers ('u'), starting +at address '0x54320'. 'x/4xw $sp' prints the four words ('w') of memory +above the stack pointer (here, '$sp'; *note Registers: Registers.) in +hexadecimal ('x'). + + You can also specify a negative repeat count to examine memory +backward from the given address. For example, 'x/-3uh 0x54320' prints +three halfwords ('h') at '0x5431a', '0x5431c', and '0x5431e'. + + Since the letters indicating unit sizes are all distinct from the +letters specifying output formats, you do not have to remember whether +unit size or format comes first; either order works. The output +specifications '4xw' and '4wx' mean exactly the same thing. (However, +the count N must come first; 'wx4' does not work.) + + Even though the unit size U is ignored for the formats 's' and 'i', +you might still want to use a count N; for example, '3i' specifies that +you want to see three machine instructions, including any operands. For +convenience, especially when used with the 'display' command, the 'i' +format also prints branch delay slot instructions, if any, beyond the +count specified, which immediately follow the last instruction that is +within the count. The command 'disassemble' gives an alternative way of +inspecting machine instructions; see *note Source and Machine Code: +Machine Code. + + If a negative repeat count is specified for the formats 's' or 'i', +the command displays null-terminated strings or instructions before the +given address as many as the absolute value of the given number. For +the 'i' format, we use line number information in the debug info to +accurately locate instruction boundaries while disassembling backward. +If line info is not available, the command stops examining memory with +an error message. + + All the defaults for the arguments to 'x' are designed to make it +easy to continue scanning memory with minimal specifications each time +you use 'x'. For example, after you have inspected three machine +instructions with 'x/3i ADDR', you can inspect the next seven with just +'x/7'. If you use to repeat the 'x' command, the repeat count N +is used again; the other arguments default as for successive uses of +'x'. + + When examining machine instructions, the instruction at current +program counter is shown with a '=>' marker. For example: + + (gdb) x/5i $pc-6 + 0x804837f : mov %esp,%ebp + 0x8048381 : push %ecx + 0x8048382 : sub $0x4,%esp + => 0x8048385 : movl $0x8048460,(%esp) + 0x804838c : call 0x80482d4 + + If the architecture supports memory tagging, the tags can be +displayed by using 'm'. *Note Memory Tagging::. + + The information will be displayed once per granule size (the amount +of bytes a particular memory tag covers). For example, AArch64 has a +granule size of 16 bytes, so it will display a tag every 16 bytes. + + Due to the way GDB prints information with the 'x' command (not +aligned to a particular boundary), the tag information will refer to the +initial address displayed on a particular line. If a memory tag +boundary is crossed in the middle of a line displayed by the 'x' +command, it will be displayed on the next line. + + The 'm' format doesn't affect any other specified formats that were +passed to the 'x' command. + + The addresses and contents printed by the 'x' command are not saved +in the value history because there is often too much of them and they +would get in the way. Instead, GDB makes these values available for +subsequent use in expressions as values of the convenience variables +'$_' and '$__'. After an 'x' command, the last address examined is +available for use in expressions in the convenience variable '$_'. The +contents of that address, as examined, are available in the convenience +variable '$__'. + + If the 'x' command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of +output. + + Most targets have an addressable memory unit size of 8 bits. This +means that to each memory address are associated 8 bits of data. Some +targets, however, have other addressable memory unit sizes. Within GDB +and this document, the term "addressable memory unit" (or "memory unit" +for short) is used when explicitly referring to a chunk of data of that +size. The word "byte" is used to refer to a chunk of data of 8 bits, +regardless of the addressable memory unit size of the target. For most +systems, addressable memory unit is a synonym of byte. + + When you are debugging a program running on a remote target machine +(*note Remote Debugging::), you may wish to verify the program's image +in the remote machine's memory against the executable file you +downloaded to the target. Or, on any target, you may want to check +whether the program has corrupted its own read-only sections. The +'compare-sections' command is provided for such situations. + +'compare-sections [SECTION-NAME|-r]' + Compare the data of a loadable section SECTION-NAME in the + executable file of the program being debugged with the same section + in the target machine's memory, and report any mismatches. With no + arguments, compares all loadable sections. With an argument of + '-r', compares all loadable read-only sections. + + Note: for remote targets, this command can be accelerated if the + target supports computing the CRC checksum of a block of memory + (*note qCRC packet::). + + +File: gdb.info, Node: Memory Tagging, Next: Auto Display, Prev: Memory, Up: Data + +10.7 Memory Tagging +=================== + +Memory tagging is a memory protection technology that uses a pair of +tags to validate memory accesses through pointers. The tags are integer +values usually comprised of a few bits, depending on the architecture. + + There are two types of tags that are used in this setup: logical and +allocation. A logical tag is stored in the pointers themselves, usually +at the higher bits of the pointers. An allocation tag is the tag +associated with particular ranges of memory in the physical address +space, against which the logical tags from pointers are compared. + + The pointer tag (logical tag) must match the memory tag (allocation +tag) for the memory access to be valid. If the logical tag does not +match the allocation tag, that will raise a memory violation. + + Allocation tags cover multiple contiguous bytes of physical memory. +This range of bytes is called a memory tag granule and is +architecture-specific. For example, AArch64 has a tag granule of 16 +bytes, meaning each allocation tag spans 16 bytes of memory. + + If the underlying architecture supports memory tagging, like AArch64 +MTE or SPARC ADI do, GDB can make use of it to validate pointers against +memory allocation tags. + + The 'print' (*note Data::) and 'x' (*note Memory::) commands will +display tag information when appropriate, and a command prefix of +'memory-tag' gives access to the various memory tagging commands. + + The 'memory-tag' commands are the following: + +'memory-tag print-logical-tag POINTER_EXPRESSION' + Print the logical tag stored in POINTER_EXPRESSION. +'memory-tag with-logical-tag POINTER_EXPRESSION TAG_BYTES' + Print the pointer given by POINTER_EXPRESSION, augmented with a + logical tag of TAG_BYTES. +'memory-tag print-allocation-tag ADDRESS_EXPRESSION' + Print the allocation tag associated with the memory address given + by ADDRESS_EXPRESSION. +'memory-tag setatag STARTING_ADDRESS LENGTH TAG_BYTES' + Set the allocation tag(s) for memory range [STARTING_ADDRESS, + STARTING_ADDRESS + LENGTH) to TAG_BYTES. +'memory-tag check POINTER_EXPRESSION' + Check if the logical tag in the pointer given by POINTER_EXPRESSION + matches the allocation tag for the memory referenced by the + pointer. + + This essentially emulates the hardware validation that is done when + tagged memory is accessed through a pointer, but does not cause a + memory fault as it would during hardware validation. + + It can be used to inspect potential memory tagging violations in + the running process, before any faults get triggered. + + +File: gdb.info, Node: Auto Display, Next: Print Settings, Prev: Memory Tagging, Up: Data + +10.8 Automatic Display +====================== + +If you find that you want to print the value of an expression frequently +(to see how it changes), you might want to add it to the "automatic +display list" so that GDB prints its value each time your program stops. +Each expression added to the list is given a number to identify it; to +remove an expression from the list, you specify that number. The +automatic display looks like this: + + 2: foo = 38 + 3: bar[5] = (struct hack *) 0x3804 + +This display shows item numbers, expressions and their current values. +As with displays you request manually using 'x' or 'print', you can +specify the output format you prefer; in fact, 'display' decides whether +to use 'print' or 'x' depending your format specification--it uses 'x' +if you specify either the 'i' or 's' format, or a unit size; otherwise +it uses 'print'. + +'display EXPR' + Add the expression EXPR to the list of expressions to display each + time your program stops. *Note Expressions: Expressions. + + 'display' does not repeat if you press again after using it. + +'display/FMT EXPR' + For FMT specifying only a display format and not a size or count, + add the expression EXPR to the auto-display list but arrange to + display it each time in the specified format FMT. *Note Output + Formats: Output Formats. + +'display/FMT ADDR' + For FMT 'i' or 's', or including a unit-size or a number of units, + add the expression ADDR as a memory address to be examined each + time your program stops. Examining means in effect doing 'x/FMT + ADDR'. *Note Examining Memory: Memory. + + For example, 'display/i $pc' can be helpful, to see the machine +instruction about to be executed each time execution stops ('$pc' is a +common name for the program counter; *note Registers: Registers.). + +'undisplay DNUMS...' +'delete display DNUMS...' + Remove items from the list of expressions to display. Specify the + numbers of the displays that you want affected with the command + argument DNUMS. It can be a single display number, one of the + numbers shown in the first field of the 'info display' display; or + it could be a range of display numbers, as in '2-4'. + + 'undisplay' does not repeat if you press after using it. + (Otherwise you would just get the error 'No display number ...'.) + +'disable display DNUMS...' + Disable the display of item numbers DNUMS. A disabled display item + is not printed automatically, but is not forgotten. It may be + enabled again later. Specify the numbers of the displays that you + want affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'enable display DNUMS...' + Enable display of item numbers DNUMS. It becomes effective once + again in auto display of its expression, until you specify + otherwise. Specify the numbers of the displays that you want + affected with the command argument DNUMS. It can be a single + display number, one of the numbers shown in the first field of the + 'info display' display; or it could be a range of display numbers, + as in '2-4'. + +'display' + Display the current values of the expressions on the list, just as + is done when your program stops. + +'info display' + Print the list of expressions previously set up to display + automatically, each one with its item number, but without showing + the values. This includes disabled expressions, which are marked + as such. It also includes expressions which would not be displayed + right now because they refer to automatic variables not currently + available. + + If a display expression refers to local variables, then it does not +make sense outside the lexical context for which it was set up. Such an +expression is disabled when execution enters a context where one of its +variables is not defined. For example, if you give the command 'display +last_char' while inside a function with an argument 'last_char', GDB +displays this argument while your program continues to stop inside that +function. When it stops elsewhere--where there is no variable +'last_char'--the display is disabled automatically. The next time your +program stops where 'last_char' is meaningful, you can enable the +display expression once again. + + +File: gdb.info, Node: Print Settings, Next: Pretty Printing, Prev: Auto Display, Up: Data + +10.9 Print Settings +=================== + +GDB provides the following ways to control how arrays, structures, and +symbols are printed. + +These settings are useful for debugging programs in any language: + +'set print address' +'set print address on' + GDB prints memory addresses showing the location of stack traces, + structure values, pointer values, breakpoints, and so forth, even + when it also displays the contents of those addresses. The default + is 'on'. For example, this is what a stack frame display looks + like with 'set print address on': + + (gdb) f + #0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") + at input.c:530 + 530 if (lquote != def_lquote) + +'set print address off' + Do not print addresses when displaying their contents. For + example, this is the same stack frame displayed with 'set print + address off': + + (gdb) set print addr off + (gdb) f + #0 set_quotes (lq="<<", rq=">>") at input.c:530 + 530 if (lquote != def_lquote) + + You can use 'set print address off' to eliminate all machine + dependent displays from the GDB interface. For example, with + 'print address off', you should get the same text for backtraces on + all machines--whether or not they involve pointer arguments. + +'show print address' + Show whether or not addresses are to be printed. + + When GDB prints a symbolic address, it normally prints the closest +earlier symbol plus an offset. If that symbol does not uniquely +identify the address (for example, it is a name whose scope is a single +source file), you may need to clarify. One way to do this is with 'info +line', for example 'info line *0x4537'. Alternately, you can set GDB to +print the source file and line number when it prints a symbolic address: + +'set print symbol-filename on' + Tell GDB to print the source file name and line number of a symbol + in the symbolic form of an address. + +'set print symbol-filename off' + Do not print source file name and line number of a symbol. This is + the default. + +'show print symbol-filename' + Show whether or not GDB will print the source file name and line + number of a symbol in the symbolic form of an address. + + Another situation where it is helpful to show symbol filenames and +line numbers is when disassembling code; GDB shows you the line number +and source file that corresponds to each instruction. + + Also, you may wish to see the symbolic form only if the address being +printed is reasonably close to the closest earlier symbol: + +'set print max-symbolic-offset MAX-OFFSET' +'set print max-symbolic-offset unlimited' + Tell GDB to only display the symbolic form of an address if the + offset between the closest earlier symbol and the address is less + than MAX-OFFSET. The default is 'unlimited', which tells GDB to + always print the symbolic form of an address if any symbol precedes + it. Zero is equivalent to 'unlimited'. + +'show print max-symbolic-offset' + Ask how large the maximum offset is that GDB prints in a symbolic + address. + + If you have a pointer and you are not sure where it points, try 'set +print symbol-filename on'. Then you can determine the name and source +file location of the variable where it points, using 'p/a POINTER'. +This interprets the address in symbolic form. For example, here GDB +shows that a variable 'ptt' points at another variable 't', defined in +'hi2.c': + + (gdb) set print symbol-filename on + (gdb) p/a ptt + $4 = 0xe008 + + _Warning:_ For pointers that point to a local variable, 'p/a' does + not show the symbol name and filename of the referent, even with + the appropriate 'set print' options turned on. + + You can also enable '/a'-like formatting all the time using 'set +print symbol on': + +'set print symbol on' + Tell GDB to print the symbol corresponding to an address, if one + exists. + +'set print symbol off' + Tell GDB not to print the symbol corresponding to an address. In + this mode, GDB will still print the symbol corresponding to + pointers to functions. This is the default. + +'show print symbol' + Show whether GDB will display the symbol corresponding to an + address. + + Other settings control how different kinds of objects are printed: + +'set print array' +'set print array on' + Pretty print arrays. This format is more convenient to read, but + uses more space. The default is off. + +'set print array off' + Return to compressed format for arrays. + +'show print array' + Show whether compressed or pretty format is selected for displaying + arrays. + +'set print array-indexes' +'set print array-indexes on' + Print the index of each element when displaying arrays. May be + more convenient to locate a given element in the array or quickly + find the index of a given element in that printed array. The + default is off. + +'set print array-indexes off' + Stop printing element indexes when displaying arrays. + +'show print array-indexes' + Show whether the index of each element is printed when displaying + arrays. + +'set print nibbles' +'set print nibbles on' + Print binary values in groups of four bits, known as "nibbles", + when using the print command of GDB with the option '/t'. For + example, this is what it looks like with 'set print nibbles on': + + (gdb) print val_flags + $1 = 1230 + (gdb) print/t val_flags + $2 = 0100 1100 1110 + +'set print nibbles off' + Don't printing binary values in groups. This is the default. + +'show print nibbles' + Show whether to print binary values in groups of four bits. + +'set print characters NUMBER-OF-CHARACTERS' +'set print characters elements' +'set print characters unlimited' + Set a limit on how many characters of a string GDB will print. If + GDB is printing a large string, it stops printing after it has + printed the number of characters set by the 'set print characters' + command. This equally applies to multi-byte and wide character + strings, that is for strings whose character type is 'wchar_t', + 'char16_t', or 'char32_t' it is the number of actual characters + rather than underlying bytes the encoding uses that this setting + controls. Setting NUMBER-OF-CHARACTERS to 'elements' means that + the limit on the number of characters to print follows one for + array elements; see *note set print elements::. Setting + NUMBER-OF-CHARACTERS to 'unlimited' means that the number of + characters to print is unlimited. When GDB starts, this limit is + set to 'elements'. + +'show print characters' + Display the number of characters of a large string that GDB will + print. + +'set print elements NUMBER-OF-ELEMENTS' +'set print elements unlimited' + Set a limit on how many elements of an array GDB will print. If + GDB is printing a large array, it stops printing after it has + printed the number of elements set by the 'set print elements' + command. By default this limit also applies to the display of + strings; see *note set print characters::. When GDB starts, this + limit is set to 200. Setting NUMBER-OF-ELEMENTS to 'unlimited' or + zero means that the number of elements to print is unlimited. + + When printing very large arrays, whose size is greater than + 'max-value-size' (*note max-value-size: set max-value-size.), if + the 'print elements' is set such that the size of the elements + being printed is less than or equal to 'max-value-size', then GDB + will print the array (up to the 'print elements' limit), and only + 'max-value-size' worth of data will be added into the value history + (*note Value History: Value History.). + +'show print elements' + Display the number of elements of a large array that GDB will + print. + +'set print frame-arguments VALUE' + This command allows to control how the values of arguments are + printed when the debugger prints a frame (*note Frames::). The + possible values are: + + 'all' + The values of all arguments are printed. + + 'scalars' + Print the value of an argument only if it is a scalar. The + value of more complex arguments such as arrays, structures, + unions, etc, is replaced by '...'. This is the default. Here + is an example where only scalar arguments are shown: + + #1 0x08048361 in call_me (i=3, s=..., ss=0xbf8d508c, u=..., e=green) + at frame-args.c:23 + + 'none' + None of the argument values are printed. Instead, the value + of each argument is replaced by '...'. In this case, the + example above now becomes: + + #1 0x08048361 in call_me (i=..., s=..., ss=..., u=..., e=...) + at frame-args.c:23 + + 'presence' + Only the presence of arguments is indicated by '...'. The + '...' are not printed for function without any arguments. + None of the argument names and values are printed. In this + case, the example above now becomes: + + #1 0x08048361 in call_me (...) at frame-args.c:23 + + By default, only scalar arguments are printed. This command can be + used to configure the debugger to print the value of all arguments, + regardless of their type. However, it is often advantageous to not + print the value of more complex parameters. For instance, it + reduces the amount of information printed in each frame, making the + backtrace more readable. Also, it improves performance when + displaying Ada frames, because the computation of large arguments + can sometimes be CPU-intensive, especially in large applications. + Setting 'print frame-arguments' to 'scalars' (the default), 'none' + or 'presence' avoids this computation, thus speeding up the display + of each Ada frame. + +'show print frame-arguments' + Show how the value of arguments should be displayed when printing a + frame. + +'set print raw-frame-arguments on' + Print frame arguments in raw, non pretty-printed, form. + +'set print raw-frame-arguments off' + Print frame arguments in pretty-printed form, if there is a + pretty-printer for the value (*note Pretty Printing::), otherwise + print the value in raw form. This is the default. + +'show print raw-frame-arguments' + Show whether to print frame arguments in raw form. + +'set print entry-values VALUE' + Set printing of frame argument values at function entry. In some + cases GDB can determine the value of function argument which was + passed by the function caller, even if the value was modified + inside the called function and therefore is different. With + optimized code, the current value could be unavailable, but the + entry value may still be known. + + The default value is 'default' (see below for its description). + Older GDB behaved as with the setting 'no'. Compilers not + supporting this feature will behave in the 'default' setting the + same way as with the 'no' setting. + + This functionality is currently supported only by DWARF 2 debugging + format and the compiler has to produce 'DW_TAG_call_site' tags. + With GCC, you need to specify '-O -g' during compilation, to get + this information. + + The VALUE parameter can be one of the following: + + 'no' + Print only actual parameter values, never print values from + function entry point. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val=) + #0 born (val=10) + #0 invalid (val=) + + 'only' + Print only parameter values from function entry point. The + actual parameter values are never printed. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val@entry=) + #0 invalid (val@entry=) + + 'preferred' + Print only parameter values from function entry point. If + value from function entry point is not known while the actual + value is known, print the actual value for such parameter. + #0 equal (val@entry=5) + #0 different (val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val@entry=) + + 'if-needed' + Print actual parameter values. If actual parameter value is + not known while value from function entry point is known, + print the entry point value for such parameter. + #0 equal (val=5) + #0 different (val=6) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'both' + Always print both the actual parameter value and its value + from function entry point, even if values of one or both are + not available due to compiler optimizations. + #0 equal (val=5, val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10, val@entry=) + #0 invalid (val=, val@entry=) + + 'compact' + Print the actual parameter value if it is known and also its + value from function entry point if it is known. If neither is + known, print for the actual value ''. If not + in MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + 'default' + Always print the actual parameter value. Print also its value + from function entry point, but only if it is known. If not in + MI mode (*note GDB/MI::) and if both values are known and + identical, print the shortened 'param=param@entry=VALUE' + notation. + #0 equal (val=val@entry=5) + #0 different (val=6, val@entry=5) + #0 lost (val=, val@entry=5) + #0 born (val=10) + #0 invalid (val=) + + For analysis messages on possible failures of frame argument values + at function entry resolution see *note set debug entry-values::. + +'show print entry-values' + Show the method being used for printing of frame argument values at + function entry. + +'set print frame-info VALUE' + This command allows to control the information printed when the + debugger prints a frame. See *note Frames::, *note Backtrace::, + for a general explanation about frames and frame information. Note + that some other settings (such as 'set print frame-arguments' and + 'set print address') are also influencing if and how some frame + information is displayed. In particular, the frame program counter + is never printed if 'set print address' is off. + + The possible values for 'set print frame-info' are: + 'short-location' + Print the frame level, the program counter (if not at the + beginning of the location source line), the function, the + function arguments. + 'location' + Same as 'short-location' but also print the source file and + source line number. + 'location-and-address' + Same as 'location' but print the program counter even if + located at the beginning of the location source line. + 'source-line' + Print the program counter (if not at the beginning of the + location source line), the line number and the source line. + 'source-and-location' + Print what 'location' and 'source-line' are printing. + 'auto' + The information printed for a frame is decided automatically + by the GDB command that prints a frame. For example, 'frame' + prints the information printed by 'source-and-location' while + 'stepi' will switch between 'source-line' and + 'source-and-location' depending on the program counter. The + default value is 'auto'. + +'set print repeats NUMBER-OF-REPEATS' +'set print repeats unlimited' + Set the threshold for suppressing display of repeated array + elements. When the number of consecutive identical elements of an + array exceeds the threshold, GDB prints the string '""', where N is the number of identical repetitions, instead + of displaying the identical elements themselves. Setting the + threshold to 'unlimited' or zero will cause all elements to be + individually printed. The default threshold is 10. + +'show print repeats' + Display the current threshold for printing repeated identical + elements. + +'set print max-depth DEPTH' +'set print max-depth unlimited' + Set the threshold after which nested structures are replaced with + ellipsis, this can make visualising deeply nested structures + easier. + + For example, given this C code + + typedef struct s1 { int a; } s1; + typedef struct s2 { s1 b; } s2; + typedef struct s3 { s2 c; } s3; + typedef struct s4 { s3 d; } s4; + + s4 var = { { { { 3 } } } }; + + The following table shows how different values of DEPTH will effect + how 'var' is printed by GDB: + + DEPTH setting Result of 'p var' + -------------------------------------------------------------------------- + unlimited '$1 = {d = {c = {b = {a = 3}}}}' + '0' '$1 = {...}' + '1' '$1 = {d = {...}}' + '2' '$1 = {d = {c = {...}}}' + '3' '$1 = {d = {c = {b = {...}}}}' + '4' '$1 = {d = {c = {b = {a = 3}}}}' + + To see the contents of structures that have been hidden the user + can either increase the print max-depth, or they can print the + elements of the structure that are visible, for example + + (gdb) set print max-depth 2 + (gdb) p var + $1 = {d = {c = {...}}} + (gdb) p var.d + $2 = {c = {b = {...}}} + (gdb) p var.d.c + $3 = {b = {a = 3}} + + The pattern used to replace nested structures varies based on + language, for most languages '{...}' is used, but Fortran uses + '(...)'. + +'show print max-depth' + Display the current threshold after which nested structures are + replaces with ellipsis. + +'set print memory-tag-violations' +'set print memory-tag-violations on' + Cause GDB to display additional information about memory tag + violations when printing pointers and addresses. + +'set print memory-tag-violations off' + Stop printing memory tag violation information. + +'show print memory-tag-violations' + Show whether memory tag violation information is displayed when + printing pointers and addresses. + +'set print null-stop' + Cause GDB to stop printing the characters of an array when the + first NULL is encountered. This is useful when large arrays + actually contain only short strings. The default is off. + +'show print null-stop' + Show whether GDB stops printing an array on the first NULL + character. + +'set print pretty on' + Cause GDB to print structures in an indented format with one member + per line, like this: + + $1 = { + next = 0x0, + flags = { + sweet = 1, + sour = 1 + }, + meat = 0x54 "Pork" + } + +'set print pretty off' + Cause GDB to print structures in a compact format, like this: + + $1 = {next = 0x0, flags = {sweet = 1, sour = 1}, \ + meat = 0x54 "Pork"} + + This is the default format. + +'show print pretty' + Show which format GDB is using to print structures. + +'set print raw-values on' + Print values in raw form, without applying the pretty printers for + the value. + +'set print raw-values off' + Print values in pretty-printed form, if there is a pretty-printer + for the value (*note Pretty Printing::), otherwise print the value + in raw form. + + The default setting is "off". + +'show print raw-values' + Show whether to print values in raw form. + +'set print sevenbit-strings on' + Print using only seven-bit characters; if this option is set, GDB + displays any eight-bit characters (in strings or character values) + using the notation '\'NNN. This setting is best if you are working + in English (ASCII) and you use the high-order bit of characters as + a marker or "meta" bit. + +'set print sevenbit-strings off' + Print full eight-bit characters. This allows the use of more + international character sets, and is the default. + +'show print sevenbit-strings' + Show whether or not GDB is printing only seven-bit characters. + +'set print union on' + Tell GDB to print unions which are contained in structures and + other unions. This is the default setting. + +'set print union off' + Tell GDB not to print unions which are contained in structures and + other unions. GDB will print '"{...}"' instead. + +'show print union' + Ask GDB whether or not it will print unions which are contained in + structures and other unions. + + For example, given the declarations + + typedef enum {Tree, Bug} Species; + typedef enum {Big_tree, Acorn, Seedling} Tree_forms; + typedef enum {Caterpillar, Cocoon, Butterfly} + Bug_forms; + + struct thing { + Species it; + union { + Tree_forms tree; + Bug_forms bug; + } form; + }; + + struct thing foo = {Tree, {Acorn}}; + + with 'set print union on' in effect 'p foo' would print + + $1 = {it = Tree, form = {tree = Acorn, bug = Cocoon}} + + and with 'set print union off' in effect it would print + + $1 = {it = Tree, form = {...}} + + 'set print union' affects programs written in C-like languages and + in Pascal. + +These settings are of interest when debugging C++ programs: + +'set print demangle' +'set print demangle on' + Print C++ names in their source form rather than in the encoded + ("mangled") form passed to the assembler and linker for type-safe + linkage. The default is on. + +'show print demangle' + Show whether C++ names are printed in mangled or demangled form. + +'set print asm-demangle' +'set print asm-demangle on' + Print C++ names in their source form rather than their mangled + form, even in assembler code printouts such as instruction + disassemblies. The default is off. + +'show print asm-demangle' + Show whether C++ names in assembly listings are printed in mangled + or demangled form. + +'set demangle-style STYLE' + Choose among several encoding schemes used by different compilers + to represent C++ names. If you omit STYLE, you will see a list of + possible formats. The default value is AUTO, which lets GDB choose + a decoding style by inspecting your program. + +'show demangle-style' + Display the encoding style currently in use for decoding C++ + symbols. + +'set print object' +'set print object on' + When displaying a pointer to an object, identify the _actual_ + (derived) type of the object rather than the _declared_ type, using + the virtual function table. Note that the virtual function table + is required--this feature can only work for objects that have + run-time type identification; a single virtual method in the + object's declared type is sufficient. Note that this setting is + also taken into account when working with variable objects via MI + (*note GDB/MI::). + +'set print object off' + Display only the declared type of objects, without reference to the + virtual function table. This is the default setting. + +'show print object' + Show whether actual, or declared, object types are displayed. + +'set print static-members' +'set print static-members on' + Print static members when displaying a C++ object. The default is + on. + +'set print static-members off' + Do not print static members when displaying a C++ object. + +'show print static-members' + Show whether C++ static members are printed or not. + +'set print pascal_static-members' +'set print pascal_static-members on' + Print static members when displaying a Pascal object. The default + is on. + +'set print pascal_static-members off' + Do not print static members when displaying a Pascal object. + +'show print pascal_static-members' + Show whether Pascal static members are printed or not. + +'set print vtbl' +'set print vtbl on' + Pretty print C++ virtual function tables. The default is off. + (The 'vtbl' commands do not work on programs compiled with the HP + ANSI C++ compiler ('aCC').) + +'set print vtbl off' + Do not pretty print C++ virtual function tables. + +'show print vtbl' + Show whether C++ virtual function tables are pretty printed, or + not. + + +File: gdb.info, Node: Pretty Printing, Next: Value History, Prev: Print Settings, Up: Data + +10.10 Pretty Printing +===================== + +GDB provides a mechanism to allow pretty-printing of values using Python +code. It greatly simplifies the display of complex objects. This +mechanism works for both MI and the CLI. + +* Menu: + +* Pretty-Printer Introduction:: Introduction to pretty-printers +* Pretty-Printer Example:: An example pretty-printer +* Pretty-Printer Commands:: Pretty-printer commands + + +File: gdb.info, Node: Pretty-Printer Introduction, Next: Pretty-Printer Example, Up: Pretty Printing + +10.10.1 Pretty-Printer Introduction +----------------------------------- + +When GDB prints a value, it first sees if there is a pretty-printer +registered for the value. If there is then GDB invokes the +pretty-printer to print the value. Otherwise the value is printed +normally. + + Pretty-printers are normally named. This makes them easy to manage. +The 'info pretty-printer' command will list all the installed +pretty-printers with their names. If a pretty-printer can handle +multiple data types, then its "subprinters" are the printers for the +individual data types. Each such subprinter has its own name. The +format of the name is PRINTER-NAME;SUBPRINTER-NAME. + + Pretty-printers are installed by "registering" them with GDB. +Typically they are automatically loaded and registered when the +corresponding debug information is loaded, thus making them available +without having to do anything special. + + There are three places where a pretty-printer can be registered. + + * Pretty-printers registered globally are available when debugging + all inferiors. + + * Pretty-printers registered with a program space are available only + when debugging that program. *Note Progspaces In Python::, for + more details on program spaces in Python. + + * Pretty-printers registered with an objfile are loaded and unloaded + with the corresponding objfile (e.g., shared library). *Note + Objfiles In Python::, for more details on objfiles in Python. + + *Note Selecting Pretty-Printers::, for further information on how +pretty-printers are selected, + + *Note Writing a Pretty-Printer::, for implementing pretty printers +for new types. + + +File: gdb.info, Node: Pretty-Printer Example, Next: Pretty-Printer Commands, Prev: Pretty-Printer Introduction, Up: Pretty Printing + +10.10.2 Pretty-Printer Example +------------------------------ + +Here is how a C++ 'std::string' looks without a pretty-printer: + + (gdb) print s + $1 = { + static npos = 4294967295, + _M_dataplus = { + > = { + <__gnu_cxx::new_allocator> = { + }, + }, + members of std::basic_string, + std::allocator >::_Alloc_hider: + _M_p = 0x804a014 "abcd" + } + } + + With a pretty-printer for 'std::string' only the contents are +printed: + + (gdb) print s + $2 = "abcd" + + +File: gdb.info, Node: Pretty-Printer Commands, Prev: Pretty-Printer Example, Up: Pretty Printing + +10.10.3 Pretty-Printer Commands +------------------------------- + +'info pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Print the list of installed pretty-printers. This includes + disabled pretty-printers, which are marked as such. + + OBJECT-REGEXP is a regular expression matching the objects whose + pretty-printers to list. Objects can be 'global', the program + space's file (*note Progspaces In Python::), and the object files + within that program space (*note Objfiles In Python::). *Note + Selecting Pretty-Printers::, for details on how GDB looks up a + printer from these three objects. + + NAME-REGEXP is a regular expression matching the name of the + printers to list. + +'disable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Disable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. A + disabled pretty-printer is not forgotten, it may be enabled again + later. + +'enable pretty-printer [OBJECT-REGEXP [NAME-REGEXP]]' + Enable pretty-printers matching OBJECT-REGEXP and NAME-REGEXP. + + Example: + + Suppose we have three pretty-printers installed: one from library1.so +named 'foo' that prints objects of type 'foo', and another from +library2.so named 'bar' that prints two types of objects, 'bar1' and +'bar2'. + + (gdb) info pretty-printer + library1.so: + foo + library2.so: + bar + bar1 + bar2 + (gdb) info pretty-printer library2 + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library1 + 1 printer disabled + 2 of 3 printers enabled + (gdb) info pretty-printer + library1.so: + foo [disabled] + library2.so: + bar + bar1 + bar2 + (gdb) disable pretty-printer library2 bar;bar1 + 1 printer disabled + 1 of 3 printers enabled + (gdb) info pretty-printer library2 + library2.so: + bar + bar1 [disabled] + bar2 + (gdb) disable pretty-printer library2 bar + 1 printer disabled + 0 of 3 printers enabled + (gdb) info pretty-printer + library1.so: + foo [disabled] + library2.so: + bar [disabled] + bar1 [disabled] + bar2 + + Note that for 'bar' the entire printer can be disabled, as can each +individual subprinter. + + Printing values and frame arguments is done by default using the +enabled pretty printers. + + The print option '-raw-values' and GDB setting 'set print raw-values' +(*note set print raw-values::) can be used to print values without +applying the enabled pretty printers. + + Similarly, the backtrace option '-raw-frame-arguments' and GDB +setting 'set print raw-frame-arguments' (*note set print +raw-frame-arguments::) can be used to ignore the enabled pretty printers +when printing frame argument values. + + +File: gdb.info, Node: Value History, Next: Convenience Vars, Prev: Pretty Printing, Up: Data + +10.11 Value History +=================== + +Values printed by the 'print' command are saved in the GDB "value +history". This allows you to refer to them in other expressions. +Values are kept until the symbol table is re-read or discarded (for +example with the 'file' or 'symbol-file' commands). When the symbol +table changes, the value history is discarded, since the values may +contain pointers back to the types defined in the symbol table. + + The values printed are given "history numbers" by which you can refer +to them. These are successive integers starting with one. 'print' +shows you the history number assigned to a value by printing '$NUM = ' +before the value; here NUM is the history number. + + To refer to any previous value, use '$' followed by the value's +history number. The way 'print' labels its output is designed to remind +you of this. Just '$' refers to the most recent value in the history, +and '$$' refers to the value before that. '$$N' refers to the Nth value +from the end; '$$2' is the value just prior to '$$', '$$1' is equivalent +to '$$', and '$$0' is equivalent to '$'. + + For example, suppose you have just printed a pointer to a structure +and want to see the contents of the structure. It suffices to type + + p *$ + + If you have a chain of structures where the component 'next' points +to the next one, you can print the contents of the next one with this: + + p *$.next + +You can print successive links in the chain by repeating this +command--which you can do by just typing . + + Note that the history records values, not expressions. If the value +of 'x' is 4 and you type these commands: + + print x + set x=5 + +then the value recorded in the value history by the 'print' command +remains 4 even though the value of 'x' has changed. + +'show values' + Print the last ten values in the value history, with their item + numbers. This is like 'p $$9' repeated ten times, except that + 'show values' does not change the history. + +'show values N' + Print ten history values centered on history item number N. + +'show values +' + Print ten history values just after the values last printed. If no + more values are available, 'show values +' produces no display. + + Pressing to repeat 'show values N' has exactly the same effect +as 'show values +'. + + +File: gdb.info, Node: Convenience Vars, Next: Convenience Funs, Prev: Value History, Up: Data + +10.12 Convenience Variables +=========================== + +GDB provides "convenience variables" that you can use within GDB to hold +on to a value and refer to it later. These variables exist entirely +within GDB; they are not part of your program, and setting a convenience +variable has no direct effect on further execution of your program. +That is why you can use them freely. + + Convenience variables are prefixed with '$'. Any name preceded by +'$' can be used for a convenience variable, unless it is one of the +predefined machine-specific register names (*note Registers: +Registers.). (Value history references, in contrast, are _numbers_ +preceded by '$'. *Note Value History: Value History.) + + You can save a value in a convenience variable with an assignment +expression, just as you would set a variable in your program. For +example: + + set $foo = *object_ptr + +would save in '$foo' the value contained in the object pointed to by +'object_ptr'. + + Using a convenience variable for the first time creates it, but its +value is 'void' until you assign a new value. You can alter the value +with another assignment at any time. + + Convenience variables have no fixed types. You can assign a +convenience variable any type of value, including structures and arrays, +even if that variable already has a value of a different type. The +convenience variable, when used as an expression, has the type of its +current value. + +'show convenience' + Print a list of convenience variables used so far, and their + values, as well as a list of the convenience functions. + Abbreviated 'show conv'. + +'init-if-undefined $VARIABLE = EXPRESSION' + Set a convenience variable if it has not already been set. This is + useful for user-defined commands that keep some state. It is + similar, in concept, to using local static variables with + initializers in C (except that convenience variables are global). + It can also be used to allow users to override default values used + in a command script. + + If the variable is already defined then the expression is not + evaluated so any side-effects do not occur. + + One of the ways to use a convenience variable is as a counter to be +incremented or a pointer to be advanced. For example, to print a field +from successive elements of an array of structures: + + set $i = 0 + print bar[$i++]->contents + +Repeat that command by typing . + + Some convenience variables are created automatically by GDB and given +values likely to be useful. + +'$_' + The variable '$_' is automatically set by the 'x' command to the + last address examined (*note Examining Memory: Memory.). Other + commands which provide a default address for 'x' to examine also + set '$_' to that address; these commands include 'info line' and + 'info breakpoint'. The type of '$_' is 'void *' except when set by + the 'x' command, in which case it is a pointer to the type of + '$__'. + +'$__' + The variable '$__' is automatically set by the 'x' command to the + value found in the last address examined. Its type is chosen to + match the format in which the data was printed. + +'$_exitcode' + When the program being debugged terminates normally, GDB + automatically sets this variable to the exit code of the program, + and resets '$_exitsignal' to 'void'. + +'$_exitsignal' + When the program being debugged dies due to an uncaught signal, GDB + automatically sets this variable to that signal's number, and + resets '$_exitcode' to 'void'. + + To distinguish between whether the program being debugged has + exited (i.e., '$_exitcode' is not 'void') or signalled (i.e., + '$_exitsignal' is not 'void'), the convenience function '$_isvoid' + can be used (*note Convenience Functions: Convenience Funs.). For + example, considering the following source code: + + #include + + int + main (int argc, char *argv[]) + { + raise (SIGALRM); + return 0; + } + + A valid way of telling whether the program being debugged has + exited or signalled would be: + + (gdb) define has_exited_or_signalled + Type commands for definition of ``has_exited_or_signalled''. + End with a line saying just ``end''. + >if $_isvoid ($_exitsignal) + >echo The program has exited\n + >else + >echo The program has signalled\n + >end + >end + (gdb) run + Starting program: + + Program terminated with signal SIGALRM, Alarm clock. + The program no longer exists. + (gdb) has_exited_or_signalled + The program has signalled + + As can be seen, GDB correctly informs that the program being + debugged has signalled, since it calls 'raise' and raises a + 'SIGALRM' signal. If the program being debugged had not called + 'raise', then GDB would report a normal exit: + + (gdb) has_exited_or_signalled + The program has exited + +'$_exception' + The variable '$_exception' is set to the exception object being + thrown at an exception-related catchpoint. *Note Set + Catchpoints::. + +'$_ada_exception' + The variable '$_ada_exception' is set to the address of the + exception being caught or thrown at an Ada exception-related + catchpoint. *Note Set Catchpoints::. + +'$_probe_argc' +'$_probe_arg0...$_probe_arg11' + Arguments to a static probe. *Note Static Probe Points::. + +'$_sdata' + The variable '$_sdata' contains extra collected static tracepoint + data. *Note Tracepoint Action Lists: Tracepoint Actions. Note + that '$_sdata' could be empty, if not inspecting a trace buffer, or + if extra static tracepoint data has not been collected. + +'$_siginfo' + The variable '$_siginfo' contains extra signal information (*note + extra signal information::). Note that '$_siginfo' could be empty, + if the application has not yet received any signals. For example, + it will be empty before you execute the 'run' command. + +'$_tlb' + The variable '$_tlb' is automatically set when debugging + applications running on MS-Windows in native mode or connected to + gdbserver that supports the 'qGetTIBAddr' request. *Note General + Query Packets::. This variable contains the address of the thread + information block. + +'$_inferior' + The number of the current inferior. *Note Debugging Multiple + Inferiors Connections and Programs: Inferiors Connections and + Programs. + +'$_thread' + The thread number of the current thread. *Note thread numbers::. + +'$_gthread' + The global number of the current thread. *Note global thread + numbers::. + +'$_inferior_thread_count' + The number of live threads in the current inferior. *Note + Threads::. + +'$_gdb_major' +'$_gdb_minor' + The major and minor version numbers of the running GDB. + Development snapshots and pretest versions have their minor version + incremented by one; thus, GDB pretest 9.11.90 will produce the + value 12 for '$_gdb_minor'. These variables allow you to write + scripts that work with different versions of GDB without errors + caused by features unavailable in some of those versions. + +'$_shell_exitcode' +'$_shell_exitsignal' + GDB commands such as 'shell' and '|' are launching shell commands. + When a launched command terminates, GDB automatically maintains the + variables '$_shell_exitcode' and '$_shell_exitsignal' according to + the exit status of the last launched command. These variables are + set and used similarly to the variables '$_exitcode' and + '$_exitsignal'. + + +File: gdb.info, Node: Convenience Funs, Next: Registers, Prev: Convenience Vars, Up: Data + +10.13 Convenience Functions +=========================== + +GDB also supplies some "convenience functions". These have a syntax +similar to convenience variables. A convenience function can be used in +an expression just like an ordinary function; however, a convenience +function is implemented internally to GDB. + + These functions do not require GDB to be configured with 'Python' +support, which means that they are always available. + +'$_isvoid (EXPR)' + Return one if the expression EXPR is 'void'. Otherwise it returns + zero. + + A 'void' expression is an expression where the type of the result + is 'void'. For example, you can examine a convenience variable + (see *note Convenience Variables: Convenience Vars.) to check + whether it is 'void': + + (gdb) print $_exitcode + $1 = void + (gdb) print $_isvoid ($_exitcode) + $2 = 1 + (gdb) run + Starting program: ./a.out + [Inferior 1 (process 29572) exited normally] + (gdb) print $_exitcode + $3 = 0 + (gdb) print $_isvoid ($_exitcode) + $4 = 0 + + In the example above, we used '$_isvoid' to check whether + '$_exitcode' is 'void' before and after the execution of the + program being debugged. Before the execution there is no exit code + to be examined, therefore '$_exitcode' is 'void'. After the + execution the program being debugged returned zero, therefore + '$_exitcode' is zero, which means that it is not 'void' anymore. + + The 'void' expression can also be a call of a function from the + program being debugged. For example, given the following function: + + void + foo (void) + { + } + + The result of calling it inside GDB is 'void': + + (gdb) print foo () + $1 = void + (gdb) print $_isvoid (foo ()) + $2 = 1 + (gdb) set $v = foo () + (gdb) print $v + $3 = void + (gdb) print $_isvoid ($v) + $4 = 1 + +'$_gdb_setting_str (SETTING)' + Return the value of the GDB SETTING as a string. SETTING is any + setting that can be used in a 'set' or 'show' command (*note + Controlling GDB::). + + (gdb) show print frame-arguments + Printing of non-scalar frame arguments is "scalars". + (gdb) p $_gdb_setting_str("print frame-arguments") + $1 = "scalars" + (gdb) p $_gdb_setting_str("height") + $2 = "30" + (gdb) + +'$_gdb_setting (SETTING)' + Return the value of the GDB SETTING. The type of the returned + value depends on the setting. + + The value type for boolean and auto boolean settings is 'int'. The + boolean values 'off' and 'on' are converted to the integer values + '0' and '1'. The value 'auto' is converted to the value '-1'. + + The value type for integer settings is either 'unsigned int' or + 'int', depending on the setting. + + Some integer settings accept an 'unlimited' value. Depending on + the setting, the 'set' command also accepts the value '0' or the + value '-1' as a synonym for 'unlimited'. For example, 'set height + unlimited' is equivalent to 'set height 0'. + + Some other settings that accept the 'unlimited' value use the value + '0' to literally mean zero. For example, 'set history size 0' + indicates to not record any GDB commands in the command history. + For such settings, '-1' is the synonym for 'unlimited'. + + See the documentation of the corresponding 'set' command for the + numerical value equivalent to 'unlimited'. + + The '$_gdb_setting' function converts the unlimited value to a '0' + or a '-1' value according to what the 'set' command uses. + + (gdb) p $_gdb_setting_str("height") + $1 = "30" + (gdb) p $_gdb_setting("height") + $2 = 30 + (gdb) set height unlimited + (gdb) p $_gdb_setting_str("height") + $3 = "unlimited" + (gdb) p $_gdb_setting("height") + $4 = 0 + (gdb) p $_gdb_setting_str("history size") + $5 = "unlimited" + (gdb) p $_gdb_setting("history size") + $6 = -1 + (gdb) p $_gdb_setting_str("disassemble-next-line") + $7 = "auto" + (gdb) p $_gdb_setting("disassemble-next-line") + $8 = -1 + (gdb) + + Other setting types (enum, filename, optional filename, string, + string noescape) are returned as string values. + +'$_gdb_maint_setting_str (SETTING)' + Like the '$_gdb_setting_str' function, but works with 'maintenance + set' variables. + +'$_gdb_maint_setting (SETTING)' + Like the '$_gdb_setting' function, but works with 'maintenance set' + variables. + +'$_shell (COMMAND-STRING)' + + Invoke a shell to execute COMMAND-STRING. COMMAND-STRING must be a + string. The shell runs on the host machine, the machine GDB is + running on. Returns the command's exit status. On Unix systems, a + command which exits with a zero exit status has succeeded, and + non-zero exit status indicates failure. When a command terminates + on a fatal signal whose number is N, GDB uses the value 128+N as + the exit status, as is standard in Unix shells. Note that N is a + host signal number, not a target signal number. If you're native + debugging, they will be the same, but if cross debugging, the host + vs target signal numbers may be completely unrelated. Please + consult your host operating system's documentation for the mapping + between host signal numbers and signal names. The shell to run is + determined in the same way as for the 'shell' command. *Note Shell + Commands: Shell Commands. + + (gdb) print $_shell("true") + $1 = 0 + (gdb) print $_shell("false") + $2 = 1 + (gdb) p $_shell("echo hello") + hello + $3 = 0 + (gdb) p $_shell("foobar") + bash: line 1: foobar: command not found + $4 = 127 + + This may also be useful in breakpoint conditions. For example: + + (gdb) break function if $_shell("some command") == 0 + + In this scenario, you'll want to make sure that the shell command + you run in the breakpoint condition takes the least amount of time + possible. For example, avoid running a command that may block + indefinitely, or that sleeps for a while before exiting. Prefer a + command or script which analyzes some state and exits immediately. + This is important because the debugged program stops for the + breakpoint every time, and then GDB evaluates the breakpoint + condition. If the condition is false, the program is re-resumed + transparently, without informing you of the stop. A quick shell + command thus avoids significantly slowing down the debugged program + unnecessarily. + + Note: unlike the 'shell' command, the '$_shell' convenience + function does not affect the '$_shell_exitcode' and + '$_shell_exitsignal' convenience variables. + + The following functions require GDB to be configured with 'Python' +support. + +'$_memeq(BUF1, BUF2, LENGTH)' + Returns one if the LENGTH bytes at the addresses given by BUF1 and + BUF2 are equal. Otherwise it returns zero. + +'$_regex(STR, REGEX)' + Returns one if the string STR matches the regular expression REGEX. + Otherwise it returns zero. The syntax of the regular expression is + that specified by 'Python''s regular expression support. + +'$_streq(STR1, STR2)' + Returns one if the strings STR1 and STR2 are equal. Otherwise it + returns zero. + +'$_strlen(STR)' + Returns the length of string STR. + +'$_caller_is(NAME[, NUMBER_OF_FRAMES])' + Returns one if the calling function's name is equal to NAME. + Otherwise it returns zero. + + If the optional argument NUMBER_OF_FRAMES is provided, it is the + number of frames up in the stack to look. The default is 1. + + Example: + + (gdb) backtrace + #0 bottom_func () + at testsuite/gdb.python/py-caller-is.c:21 + #1 0x00000000004005a0 in middle_func () + at testsuite/gdb.python/py-caller-is.c:27 + #2 0x00000000004005ab in top_func () + at testsuite/gdb.python/py-caller-is.c:33 + #3 0x00000000004005b6 in main () + at testsuite/gdb.python/py-caller-is.c:39 + (gdb) print $_caller_is ("middle_func") + $1 = 1 + (gdb) print $_caller_is ("top_func", 2) + $1 = 1 + +'$_caller_matches(REGEXP[, NUMBER_OF_FRAMES])' + Returns one if the calling function's name matches the regular + expression REGEXP. Otherwise it returns zero. + + If the optional argument NUMBER_OF_FRAMES is provided, it is the + number of frames up in the stack to look. The default is 1. + +'$_any_caller_is(NAME[, NUMBER_OF_FRAMES])' + Returns one if any calling function's name is equal to NAME. + Otherwise it returns zero. + + If the optional argument NUMBER_OF_FRAMES is provided, it is the + number of frames up in the stack to look. The default is 1. + + This function differs from '$_caller_is' in that this function + checks all stack frames from the immediate caller to the frame + specified by NUMBER_OF_FRAMES, whereas '$_caller_is' only checks + the frame specified by NUMBER_OF_FRAMES. + +'$_any_caller_matches(REGEXP[, NUMBER_OF_FRAMES])' + Returns one if any calling function's name matches the regular + expression REGEXP. Otherwise it returns zero. + + If the optional argument NUMBER_OF_FRAMES is provided, it is the + number of frames up in the stack to look. The default is 1. + + This function differs from '$_caller_matches' in that this function + checks all stack frames from the immediate caller to the frame + specified by NUMBER_OF_FRAMES, whereas '$_caller_matches' only + checks the frame specified by NUMBER_OF_FRAMES. + +'$_as_string(VALUE)' + This convenience function is considered deprecated, and could be + removed from future versions of GDB. Use the '%V' format specifier + instead (*note %V Format Specifier::). + + Return the string representation of VALUE. + + This function is useful to obtain the textual label (enumerator) of + an enumeration value. For example, assuming the variable NODE is + of an enumerated type: + + (gdb) printf "Visiting node of type %s\n", $_as_string(node) + Visiting node of type NODE_INTEGER + +'$_cimag(VALUE)' +'$_creal(VALUE)' + Return the imaginary ('$_cimag') or real ('$_creal') part of the + complex number VALUE. + + The type of the imaginary or real part depends on the type of the + complex number, e.g., using '$_cimag' on a 'float complex' will + return an imaginary part of type 'float'. + + GDB provides the ability to list and get help on convenience +functions. + +'help function' + Print a list of all convenience functions. + + +File: gdb.info, Node: Registers, Next: Floating Point Hardware, Prev: Convenience Funs, Up: Data + +10.14 Registers +=============== + +You can refer to machine register contents, in expressions, as variables +with names starting with '$'. The names of registers are different for +each machine; use 'info registers' to see the names used on your +machine. + +'info registers' + Print the names and values of all registers except floating-point + and vector registers (in the selected stack frame). + +'info all-registers' + Print the names and values of all registers, including + floating-point and vector registers (in the selected stack frame). + +'info registers REGGROUP ...' + Print the name and value of the registers in each of the specified + REGGROUPs. The REGGROUP can be any of those returned by 'maint + print reggroups' (*note Maintenance Commands::). + +'info registers REGNAME ...' + Print the "relativized" value of each specified register REGNAME. + As discussed in detail below, register values are normally relative + to the selected stack frame. The REGNAME may be any register name + valid on the machine you are using, with or without the initial + '$'. + + GDB has four "standard" register names that are available (in +expressions) on most machines--whenever they do not conflict with an +architecture's canonical mnemonics for registers. The register names +'$pc' and '$sp' are used for the program counter register and the stack +pointer. '$fp' is used for a register that contains a pointer to the +current stack frame, and '$ps' is used for a register that contains the +processor status. For example, you could print the program counter in +hex with + + p/x $pc + +or print the instruction to be executed next with + + x/i $pc + +or add four to the stack pointer(1) with + + set $sp += 4 + + Whenever possible, these four standard register names are available +on your machine even though the machine has different canonical +mnemonics, so long as there is no conflict. The 'info registers' +command shows the canonical names. For example, on the SPARC, 'info +registers' displays the processor status register as '$psr' but you can +also refer to it as '$ps'; and on x86-based machines '$ps' is an alias +for the EFLAGS register. + + GDB always considers the contents of an ordinary register as an +integer when the register is examined in this way. Some machines have +special registers which can hold nothing but floating point; these +registers are considered to have floating point values. There is no way +to refer to the contents of an ordinary register as floating point value +(although you can _print_ it as a floating point value with 'print/f +$REGNAME'). + + Some registers have distinct "raw" and "virtual" data formats. This +means that the data format in which the register contents are saved by +the operating system is not the same one that your program normally +sees. For example, the registers of the 68881 floating point +coprocessor are always saved in "extended" (raw) format, but all C +programs expect to work with "double" (virtual) format. In such cases, +GDB normally works with the virtual format only (the format that makes +sense for your program), but the 'info registers' command prints the +data in both formats. + + Some machines have special registers whose contents can be +interpreted in several different ways. For example, modern x86-based +machines have SSE and MMX registers that can hold several values packed +together in several different formats. GDB refers to such registers in +'struct' notation: + + (gdb) print $xmm1 + $1 = { + v4_float = {0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044}, + v2_double = {9.92129282474342e-303, 2.7585945287983262e-313}, + v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", + v8_int16 = {0, 0, 14072, 315, 11, 0, 13, 0}, + v4_int32 = {0, 20657912, 11, 13}, + v2_int64 = {88725056443645952, 55834574859}, + uint128 = 0x0000000d0000000b013b36f800000000 + } + +To set values of such registers, you need to tell GDB which view of the +register you wish to change, as if you were assigning value to a +'struct' member: + + (gdb) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF + + Normally, register values are relative to the selected stack frame +(*note Selecting a Frame: Selection.). This means that you get the +value that the register would contain if all stack frames farther in +were exited and their saved registers restored. In order to see the +true contents of hardware registers, you must select the innermost frame +(with 'frame 0'). + + Usually ABIs reserve some registers as not needed to be saved by the +callee (a.k.a.: "caller-saved", "call-clobbered" or "volatile" +registers). It may therefore not be possible for GDB to know the value +a register had before the call (in other words, in the outer frame), if +the register value has since been changed by the callee. GDB tries to +deduce where the inner frame saved ("callee-saved") registers, from the +debug info, unwind info, or the machine code generated by your compiler. +If some register is not saved, and GDB knows the register is +"caller-saved" (via its own knowledge of the ABI, or because the +debug/unwind info explicitly says the register's value is undefined), +GDB displays '' as the register's value. With targets that +GDB has no knowledge of the register saving convention, if a register +was not saved by the callee, then its value and location in the outer +frame are assumed to be the same of the inner frame. This is usually +harmless, because if the register is call-clobbered, the caller either +does not care what is in the register after the call, or has code to +restore the value that it does care about. Note, however, that if you +change such a register in the outer frame, you may also be affecting the +inner frame. Also, the more "outer" the frame is you're looking at, the +more likely a call-clobbered register's value is to be wrong, in the +sense that it doesn't actually represent the value the register had just +before the call. + + ---------- Footnotes ---------- + + (1) This is a way of removing one word from the stack, on machines +where stacks grow downward in memory (most machines, nowadays). This +assumes that the innermost stack frame is selected; setting '$sp' is not +allowed when other stack frames are selected. To pop entire frames off +the stack, regardless of machine architecture, use 'return'; see *note +Returning from a Function: Returning. + + +File: gdb.info, Node: Floating Point Hardware, Next: Vector Unit, Prev: Registers, Up: Data + +10.15 Floating Point Hardware +============================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the floating point hardware. + +'info float' + Display hardware-dependent information about the floating point + unit. The exact contents and layout vary depending on the floating + point chip. Currently, 'info float' is supported on the ARM and + x86 machines. + + +File: gdb.info, Node: Vector Unit, Next: OS Information, Prev: Floating Point Hardware, Up: Data + +10.16 Vector Unit +================= + +Depending on the configuration, GDB may be able to give you more +information about the status of the vector unit. + +'info vector' + Display information about the vector unit. The exact contents and + layout vary depending on the hardware. + + +File: gdb.info, Node: OS Information, Next: Memory Region Attributes, Prev: Vector Unit, Up: Data + +10.17 Operating System Auxiliary Information +============================================ + +GDB provides interfaces to useful OS facilities that can help you debug +your program. + + Some operating systems supply an "auxiliary vector" to programs at +startup. This is akin to the arguments and environment that you specify +for a program, but contains a system-dependent variety of binary values +that tell system libraries important details about the hardware, +operating system, and process. Each value's purpose is identified by an +integer tag; the meanings are well-known but system-specific. Depending +on the configuration and operating system facilities, GDB may be able to +show you this information. For remote targets, this functionality may +further depend on the remote stub's support of the 'qXfer:auxv:read' +packet, see *note qXfer auxiliary vector read::. + +'info auxv' + Display the auxiliary vector of the inferior, which can be either a + live process or a core dump file. GDB prints each tag value + numerically, and also shows names and text descriptions for + recognized tags. Some values in the vector are numbers, some bit + masks, and some pointers to strings or other data. GDB displays + each value in the most appropriate form for a recognized tag, and + in hexadecimal for an unrecognized tag. + + On some targets, GDB can access operating system-specific information +and show it to you. The types of information available will differ +depending on the type of operating system running on the target. The +mechanism used to fetch the data is described in *note Operating System +Information::. For remote targets, this functionality depends on the +remote stub's support of the 'qXfer:osdata:read' packet, see *note qXfer +osdata read::. + +'info os INFOTYPE' + + Display OS information of the requested type. + + On GNU/Linux, the following values of INFOTYPE are valid: + + 'cpus' + Display the list of all CPUs/cores. For each CPU/core, GDB + prints the available fields from /proc/cpuinfo. For each + supported architecture different fields are available. Two + common entries are processor which gives CPU number and + bogomips; a system constant that is calculated during kernel + initialization. + + 'files' + Display the list of open file descriptors on the target. For + each file descriptor, GDB prints the identifier of the process + owning the descriptor, the command of the owning process, the + value of the descriptor, and the target of the descriptor. + + 'modules' + Display the list of all loaded kernel modules on the target. + For each module, GDB prints the module name, the size of the + module in bytes, the number of times the module is used, the + dependencies of the module, the status of the module, and the + address of the loaded module in memory. + + 'msg' + Display the list of all System V message queues on the target. + For each message queue, GDB prints the message queue key, the + message queue identifier, the access permissions, the current + number of bytes on the queue, the current number of messages + on the queue, the processes that last sent and received a + message on the queue, the user and group of the owner and + creator of the message queue, the times at which a message was + last sent and received on the queue, and the time at which the + message queue was last changed. + + 'processes' + Display the list of processes on the target. For each + process, GDB prints the process identifier, the name of the + user, the command corresponding to the process, and the list + of processor cores that the process is currently running on. + (To understand what these properties mean, for this and the + following info types, please consult the general GNU/Linux + documentation.) + + 'procgroups' + Display the list of process groups on the target. For each + process, GDB prints the identifier of the process group that + it belongs to, the command corresponding to the process group + leader, the process identifier, and the command line of the + process. The list is sorted first by the process group + identifier, then by the process identifier, so that processes + belonging to the same process group are grouped together and + the process group leader is listed first. + + 'semaphores' + Display the list of all System V semaphore sets on the target. + For each semaphore set, GDB prints the semaphore set key, the + semaphore set identifier, the access permissions, the number + of semaphores in the set, the user and group of the owner and + creator of the semaphore set, and the times at which the + semaphore set was operated upon and changed. + + 'shm' + Display the list of all System V shared-memory regions on the + target. For each shared-memory region, GDB prints the region + key, the shared-memory identifier, the access permissions, the + size of the region, the process that created the region, the + process that last attached to or detached from the region, the + current number of live attaches to the region, and the times + at which the region was last attached to, detach from, and + changed. + + 'sockets' + Display the list of Internet-domain sockets on the target. + For each socket, GDB prints the address and port of the local + and remote endpoints, the current state of the connection, the + creator of the socket, the IP address family of the socket, + and the type of the connection. + + 'threads' + Display the list of threads running on the target. For each + thread, GDB prints the identifier of the process that the + thread belongs to, the command of the process, the thread + identifier, and the processor core that it is currently + running on. The main thread of a process is not listed. + +'info os' + If INFOTYPE is omitted, then list the possible values for INFOTYPE + and the kind of OS information available for each INFOTYPE. If the + target does not return a list of possible types, this command will + report an error. + + +File: gdb.info, Node: Memory Region Attributes, Next: Dump/Restore Files, Prev: OS Information, Up: Data + +10.18 Memory Region Attributes +============================== + +"Memory region attributes" allow you to describe special handling +required by regions of your target's memory. GDB uses attributes to +determine whether to allow certain types of memory accesses; whether to +use specific width accesses; and whether to cache target memory. By +default the description of memory regions is fetched from the target (if +the current target supports this), but the user can override the fetched +regions. + + Defined memory regions can be individually enabled and disabled. +When a memory region is disabled, GDB uses the default attributes when +accessing memory in that region. Similarly, if no memory regions have +been defined, GDB uses the default attributes when accessing all memory. + + When a memory region is defined, it is given a number to identify it; +to enable, disable, or remove a memory region, you specify that number. + +'mem LOWER UPPER ATTRIBUTES...' + Define a memory region bounded by LOWER and UPPER with attributes + ATTRIBUTES..., and add it to the list of regions monitored by GDB. + Note that UPPER == 0 is a special case: it is treated as the + target's maximum memory address. (0xffff on 16 bit targets, + 0xffffffff on 32 bit targets, etc.) + +'mem auto' + Discard any user changes to the memory regions and use + target-supplied regions, if available, or no regions if the target + does not support. + +'delete mem NUMS...' + Remove memory regions NUMS... from the list of regions monitored by + GDB. + +'disable mem NUMS...' + Disable monitoring of memory regions NUMS.... A disabled memory + region is not forgotten. It may be enabled again later. + +'enable mem NUMS...' + Enable monitoring of memory regions NUMS.... + +'info mem' + Print a table of all defined memory regions, with the following + columns for each region: + + _Memory Region Number_ + _Enabled or Disabled._ + Enabled memory regions are marked with 'y'. Disabled memory + regions are marked with 'n'. + + _Lo Address_ + The address defining the inclusive lower bound of the memory + region. + + _Hi Address_ + The address defining the exclusive upper bound of the memory + region. + + _Attributes_ + The list of attributes set for this memory region. + +10.18.1 Attributes +------------------ + +10.18.1.1 Memory Access Mode +............................ + +The access mode attributes set whether GDB may make read or write +accesses to a memory region. + + While these attributes prevent GDB from performing invalid memory +accesses, they do nothing to prevent the target system, I/O DMA, etc. +from accessing memory. + +'ro' + Memory is read only. +'wo' + Memory is write only. +'rw' + Memory is read/write. This is the default. + +10.18.1.2 Memory Access Size +............................ + +The access size attribute tells GDB to use specific sized accesses in +the memory region. Often memory mapped device registers require +specific sized accesses. If no access size attribute is specified, GDB +may use accesses of any size. + +'8' + Use 8 bit memory accesses. +'16' + Use 16 bit memory accesses. +'32' + Use 32 bit memory accesses. +'64' + Use 64 bit memory accesses. + +10.18.1.3 Data Cache +.................... + +The data cache attributes set whether GDB will cache target memory. +While this generally improves performance by reducing debug protocol +overhead, it can lead to incorrect results because GDB does not know +about volatile variables or memory mapped device registers. + +'cache' + Enable GDB to cache target memory. +'nocache' + Disable GDB from caching target memory. This is the default. + +10.18.2 Memory Access Checking +------------------------------ + +GDB can be instructed to refuse accesses to memory that is not +explicitly described. This can be useful if accessing such regions has +undesired effects for a specific target, or to provide better error +checking. The following commands control this behavior. + +'set mem inaccessible-by-default [on|off]' + If 'on' is specified, make GDB treat memory not explicitly + described by the memory ranges as non-existent and refuse accesses + to such memory. The checks are only performed if there's at least + one memory range defined. If 'off' is specified, make GDB treat + the memory not explicitly described by the memory ranges as RAM. + The default value is 'on'. +'show mem inaccessible-by-default' + Show the current handling of accesses to unknown memory. + + +File: gdb.info, Node: Dump/Restore Files, Next: Core File Generation, Prev: Memory Region Attributes, Up: Data + +10.19 Copy Between Memory and a File +==================================== + +You can use the commands 'dump', 'append', and 'restore' to copy data +between target memory and a file. The 'dump' and 'append' commands +write data to a file, and the 'restore' command reads data from a file +back into the inferior's memory. Files may be in binary, Motorola +S-record, Intel hex, Tektronix Hex, or Verilog Hex format; however, GDB +can only append to binary files, and cannot read from Verilog Hex files. + +'dump [FORMAT] memory FILENAME START_ADDR END_ADDR' +'dump [FORMAT] value FILENAME EXPR' + Dump the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to FILENAME in the given format. + + The FORMAT parameter may be any one of: + 'binary' + Raw binary form. + 'ihex' + Intel hex format. + 'srec' + Motorola S-record format. + 'tekhex' + Tektronix Hex format. + 'verilog' + Verilog Hex format. + + GDB uses the same definitions of these formats as the GNU binary + utilities, like 'objdump' and 'objcopy'. If FORMAT is omitted, GDB + dumps the data in raw binary form. + +'append [binary] memory FILENAME START_ADDR END_ADDR' +'append [binary] value FILENAME EXPR' + Append the contents of memory from START_ADDR to END_ADDR, or the + value of EXPR, to the file FILENAME, in raw binary form. (GDB can + only append data to files in raw binary form.) + +'restore FILENAME [binary] BIAS START END' + Restore the contents of file FILENAME into memory. The 'restore' + command can automatically recognize any known BFD file format, + except for raw binary. To restore a raw binary file you must + specify the optional keyword 'binary' after the filename. + + If BIAS is non-zero, its value will be added to the addresses + contained in the file. Binary files always start at address zero, + so they will be restored at address BIAS. Other bfd files have a + built-in location; they will be restored at offset BIAS from that + location. + + If START and/or END are non-zero, then only data between file + offset START and file offset END will be restored. These offsets + are relative to the addresses in the file, before the BIAS argument + is applied. + + +File: gdb.info, Node: Core File Generation, Next: Character Sets, Prev: Dump/Restore Files, Up: Data + +10.20 How to Produce a Core File from Your Program +================================================== + +A "core file" or "core dump" is a file that records the memory image of +a running process and its process status (register values etc.). Its +primary use is post-mortem debugging of a program that crashed while it +ran outside a debugger. A program that crashes automatically produces a +core file, unless this feature is disabled by the user. *Note Files::, +for information on invoking GDB in the post-mortem debugging mode. + + Occasionally, you may wish to produce a core file of the program you +are debugging in order to preserve a snapshot of its state. GDB has a +special command for that. + +'generate-core-file [FILE]' +'gcore [FILE]' + Produce a core dump of the inferior process. The optional argument + FILE specifies the file name where to put the core dump. If not + specified, the file name defaults to 'core.PID', where PID is the + inferior process ID. + + If supported by the filesystem where the core is written to, GDB + generates a sparse core dump file. + + Note that this command is implemented only for some systems (as of + this writing, GNU/Linux, FreeBSD, Solaris, and S390). + + On GNU/Linux, this command can take into account the value of the + file '/proc/PID/coredump_filter' when generating the core dump + (*note set use-coredump-filter::), and by default honors the + 'VM_DONTDUMP' flag for mappings where it is present in the file + '/proc/PID/smaps' (*note set dump-excluded-mappings::). + +'set use-coredump-filter on' +'set use-coredump-filter off' + Enable or disable the use of the file '/proc/PID/coredump_filter' + when generating core dump files. This file is used by the Linux + kernel to decide what types of memory mappings will be dumped or + ignored when generating a core dump file. PID is the process ID of + a currently running process. + + To make use of this feature, you have to write in the + '/proc/PID/coredump_filter' file a value, in hexadecimal, which is + a bit mask representing the memory mapping types. If a bit is set + in the bit mask, then the memory mappings of the corresponding + types will be dumped; otherwise, they will be ignored. This + configuration is inherited by child processes. For more + information about the bits that can be set in the + '/proc/PID/coredump_filter' file, please refer to the manpage of + 'core(5)'. + + By default, this option is 'on'. If this option is turned 'off', + GDB does not read the 'coredump_filter' file and instead uses the + same default value as the Linux kernel in order to decide which + pages will be dumped in the core dump file. This value is + currently '0x33', which means that bits '0' (anonymous private + mappings), '1' (anonymous shared mappings), '4' (ELF headers) and + '5' (private huge pages) are active. This will cause these memory + mappings to be dumped automatically. + +'set dump-excluded-mappings on' +'set dump-excluded-mappings off' + If 'on' is specified, GDB will dump memory mappings marked with the + 'VM_DONTDUMP' flag. This flag is represented in the file + '/proc/PID/smaps' with the acronym 'dd'. + + The default value is 'off'. + + +File: gdb.info, Node: Character Sets, Next: Caching Target Data, Prev: Core File Generation, Up: Data + +10.21 Character Sets +==================== + +If the program you are debugging uses a different character set to +represent characters and strings than the one GDB uses itself, GDB can +automatically translate between the character sets for you. The +character set GDB uses we call the "host character set"; the one the +inferior program uses we call the "target character set". + + For example, if you are running GDB on a GNU/Linux system, which uses +the ISO Latin 1 character set, but you are using GDB's remote protocol +(*note Remote Debugging::) to debug a program running on an IBM +mainframe, which uses the EBCDIC character set, then the host character +set is Latin-1, and the target character set is EBCDIC. If you give GDB +the command 'set target-charset EBCDIC-US', then GDB translates between +EBCDIC and Latin 1 as you print character or string values, or use +character and string literals in expressions. + + GDB has no way to automatically recognize which character set the +inferior program uses; you must tell it, using the 'set target-charset' +command, described below. + + Here are the commands for controlling GDB's character set support: + +'set target-charset CHARSET' + Set the current target character set to CHARSET. To display the + list of supported target character sets, type + 'set target-charset '. + +'set host-charset CHARSET' + Set the current host character set to CHARSET. + + By default, GDB uses a host character set appropriate to the system + it is running on; you can override that default using the 'set + host-charset' command. On some systems, GDB cannot automatically + determine the appropriate host character set. In this case, GDB + uses 'UTF-8'. + + GDB can only use certain character sets as its host character set. + If you type 'set host-charset ', GDB will list the host + character sets it supports. + +'set charset CHARSET' + Set the current host and target character sets to CHARSET. As + above, if you type 'set charset ', GDB will list the + names of the character sets that can be used for both host and + target. + +'show charset' + Show the names of the current host and target character sets. + +'show host-charset' + Show the name of the current host character set. + +'show target-charset' + Show the name of the current target character set. + +'set target-wide-charset CHARSET' + Set the current target's wide character set to CHARSET. This is + the character set used by the target's 'wchar_t' type. To display + the list of supported wide character sets, type + 'set target-wide-charset '. + +'show target-wide-charset' + Show the name of the current target's wide character set. + + Here is an example of GDB's character set support in action. Assume +that the following source code has been placed in the file +'charset-test.c': + + #include + + char ascii_hello[] + = {72, 101, 108, 108, 111, 44, 32, 119, + 111, 114, 108, 100, 33, 10, 0}; + char ibm1047_hello[] + = {200, 133, 147, 147, 150, 107, 64, 166, + 150, 153, 147, 132, 90, 37, 0}; + + main () + { + printf ("Hello, world!\n"); + } + + In this program, 'ascii_hello' and 'ibm1047_hello' are arrays +containing the string 'Hello, world!' followed by a newline, encoded in +the ASCII and IBM1047 character sets. + + We compile the program, and invoke the debugger on it: + + $ gcc -g charset-test.c -o charset-test + $ gdb -nw charset-test + GNU gdb 2001-12-19-cvs + Copyright 2001 Free Software Foundation, Inc. + ... + (gdb) + + We can use the 'show charset' command to see what character sets GDB +is currently using to interpret and display characters and strings: + + (gdb) show charset + The current host and target character set is `ISO-8859-1'. + (gdb) + + For the sake of printing this manual, let's use ASCII as our initial +character set: + (gdb) set charset ASCII + (gdb) show charset + The current host and target character set is `ASCII'. + (gdb) + + Let's assume that ASCII is indeed the correct character set for our +host system -- in other words, let's assume that if GDB prints +characters using the ASCII character set, our terminal will display them +properly. Since our current target character set is also ASCII, the +contents of 'ascii_hello' print legibly: + + (gdb) print ascii_hello + $1 = 0x401698 "Hello, world!\n" + (gdb) print ascii_hello[0] + $2 = 72 'H' + (gdb) + + GDB uses the target character set for character and string literals +you use in expressions: + + (gdb) print '+' + $3 = 43 '+' + (gdb) + + The ASCII character set uses the number 43 to encode the '+' +character. + + GDB relies on the user to tell it which character set the target +program uses. If we print 'ibm1047_hello' while our target character +set is still ASCII, we get jibberish: + + (gdb) print ibm1047_hello + $4 = 0x4016a8 "\310\205\223\223\226k@\246\226\231\223\204Z%" + (gdb) print ibm1047_hello[0] + $5 = 200 '\310' + (gdb) + + If we invoke the 'set target-charset' followed by , GDB +tells us the character sets it supports: + + (gdb) set target-charset + ASCII EBCDIC-US IBM1047 ISO-8859-1 + (gdb) set target-charset + + We can select IBM1047 as our target character set, and examine the +program's strings again. Now the ASCII string is wrong, but GDB +translates the contents of 'ibm1047_hello' from the target character +set, IBM1047, to the host character set, ASCII, and they display +correctly: + + (gdb) set target-charset IBM1047 + (gdb) show charset + The current host character set is `ASCII'. + The current target character set is `IBM1047'. + (gdb) print ascii_hello + $6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" + (gdb) print ascii_hello[0] + $7 = 72 '\110' + (gdb) print ibm1047_hello + $8 = 0x4016a8 "Hello, world!\n" + (gdb) print ibm1047_hello[0] + $9 = 200 'H' + (gdb) + + As above, GDB uses the target character set for character and string +literals you use in expressions: + + (gdb) print '+' + $10 = 78 '+' + (gdb) + + The IBM1047 character set uses the number 78 to encode the '+' +character. + + +File: gdb.info, Node: Caching Target Data, Next: Searching Memory, Prev: Character Sets, Up: Data + +10.22 Caching Data of Targets +============================= + +GDB caches data exchanged between the debugger and a target. Each cache +is associated with the address space of the inferior. *Note Inferiors +Connections and Programs::, about inferior and address space. Such +caching generally improves performance in remote debugging (*note Remote +Debugging::), because it reduces the overhead of the remote protocol by +bundling memory reads and writes into large chunks. Unfortunately, +simply caching everything would lead to incorrect results, since GDB +does not necessarily know anything about volatile values, memory-mapped +I/O addresses, etc. Furthermore, in non-stop mode (*note Non-Stop +Mode::) memory can be changed _while_ a gdb command is executing. +Therefore, by default, GDB only caches data known to be on the stack(1) +or in the code segment. Other regions of memory can be explicitly +marked as cacheable; *note Memory Region Attributes::. + +'set remotecache on' +'set remotecache off' + This option no longer does anything; it exists for compatibility + with old scripts. + +'show remotecache' + Show the current state of the obsolete remotecache flag. + +'set stack-cache on' +'set stack-cache off' + Enable or disable caching of stack accesses. When 'on', use + caching. By default, this option is 'on'. + +'show stack-cache' + Show the current state of data caching for memory accesses. + +'set code-cache on' +'set code-cache off' + Enable or disable caching of code segment accesses. When 'on', use + caching. By default, this option is 'on'. This improves + performance of disassembly in remote debugging. + +'show code-cache' + Show the current state of target memory cache for code segment + accesses. + +'info dcache [line]' + Print the information about the performance of data cache of the + current inferior's address space. The information displayed + includes the dcache width and depth, and for each cache line, its + number, address, and how many times it was referenced. This + command is useful for debugging the data cache operation. + + If a line number is specified, the contents of that line will be + printed in hex. + +'set dcache size SIZE' + Set maximum number of entries in dcache (dcache depth above). + +'set dcache line-size LINE-SIZE' + Set number of bytes each dcache entry caches (dcache width above). + Must be a power of 2. + +'show dcache size' + Show maximum number of dcache entries. *Note info dcache: Caching + Target Data. + +'show dcache line-size' + Show default size of dcache lines. + +'maint flush dcache' + Flush the contents (if any) of the dcache. This maintainer command + is useful when debugging the dcache implementation. + + ---------- Footnotes ---------- + + (1) In non-stop mode, it is moderately rare for a running thread to +modify the stack of a stopped thread in a way that would interfere with +a backtrace, and caching of stack reads provides a significant speed up +of remote backtraces. + + +File: gdb.info, Node: Searching Memory, Next: Value Sizes, Prev: Caching Target Data, Up: Data + +10.23 Search Memory +=================== + +Memory can be searched for a particular sequence of bytes with the +'find' command. + +'find [/SN] START_ADDR, +LEN, VAL1 [, VAL2, ...]' +'find [/SN] START_ADDR, END_ADDR, VAL1 [, VAL2, ...]' + Search memory for the sequence of bytes specified by VAL1, VAL2, + etc. The search begins at address START_ADDR and continues for + either LEN bytes or through to END_ADDR inclusive. + + S and N are optional parameters. They may be specified in either +order, apart or together. + +S, search query size + The size of each search query value. + + 'b' + bytes + 'h' + halfwords (two bytes) + 'w' + words (four bytes) + 'g' + giant words (eight bytes) + + All values are interpreted in the current language. This means, + for example, that if the current source language is C/C++ then + searching for the string "hello" includes the trailing '\0'. The + null terminator can be removed from searching by using casts, e.g.: + '{char[5]}"hello"'. + + If the value size is not specified, it is taken from the value's + type in the current language. This is useful when one wants to + specify the search pattern as a mixture of types. Note that this + means, for example, that in the case of C-like languages a search + for an untyped 0x42 will search for '(int) 0x42' which is typically + four bytes. + +N, maximum number of finds + The maximum number of matches to print. The default is to print + all finds. + + You can use strings as search values. Quote them with double-quotes +('"'). The string value is copied into the search pattern byte by byte, +regardless of the endianness of the target and the size specification. + + The address of each match found is printed as well as a count of the +number of matches found. + + The address of the last value found is stored in convenience variable +'$_'. A count of the number of matches is stored in '$numfound'. + + For example, if stopped at the 'printf' in this function: + + void + hello () + { + static char hello[] = "hello-hello"; + static struct { char c; short s; int i; } + __attribute__ ((packed)) mixed + = { 'c', 0x1234, 0x87654321 }; + printf ("%s\n", hello); + } + +you get during debugging: + + (gdb) find &hello[0], +sizeof(hello), "hello" + 0x804956d + 1 pattern found + (gdb) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' + 0x8049567 + 0x804956d + 2 patterns found. + (gdb) find &hello[0], +sizeof(hello), {char[5]}"hello" + 0x8049567 + 0x804956d + 2 patterns found. + (gdb) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' + 0x8049567 + 1 pattern found + (gdb) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 + 0x8049560 + 1 pattern found + (gdb) print $numfound + $1 = 1 + (gdb) print $_ + $2 = (void *) 0x8049560 + + +File: gdb.info, Node: Value Sizes, Prev: Searching Memory, Up: Data + +10.24 Value Sizes +================= + +Whenever GDB prints a value memory will be allocated within GDB to hold +the contents of the value. It is possible in some languages with +dynamic typing systems, that an invalid program may indicate a value +that is incorrectly large, this in turn may cause GDB to try and +allocate an overly large amount of memory. + +'set max-value-size BYTES' +'set max-value-size unlimited' + Set the maximum size of memory that GDB will allocate for the + contents of a value to BYTES, trying to display a value that + requires more memory than that will result in an error. + + Setting this variable does not effect values that have already been + allocated within GDB, only future allocations. + + There's a minimum size that 'max-value-size' can be set to in order + that GDB can still operate correctly, this minimum is currently 16 + bytes. + + The limit applies to the results of some subexpressions as well as + to complete expressions. For example, an expression denoting a + simple integer component, such as 'x.y.z', may fail if the size of + X.Y is dynamic and exceeds BYTES. On the other hand, GDB is + sometimes clever; the expression 'A[i]', where A is an array + variable with non-constant size, will generally succeed regardless + of the bounds on A, as long as the component size is less than + BYTES. + + The default value of 'max-value-size' is currently 64k. + +'show max-value-size' + Show the maximum size of memory, in bytes, that GDB will allocate + for the contents of a value. + + +File: gdb.info, Node: Optimized Code, Next: Macros, Prev: Data, Up: Top + +11 Debugging Optimized Code +*************************** + +Almost all compilers support optimization. With optimization disabled, +the compiler generates assembly code that corresponds directly to your +source code, in a simplistic way. As the compiler applies more powerful +optimizations, the generated assembly code diverges from your original +source code. With help from debugging information generated by the +compiler, GDB can map from the running program back to constructs from +your original source. + + GDB is more accurate with optimization disabled. If you can +recompile without optimization, it is easier to follow the progress of +your program during debugging. But, there are many cases where you may +need to debug an optimized version. + + When you debug a program compiled with '-g -O', remember that the +optimizer has rearranged your code; the debugger shows you what is +really there. Do not be too surprised when the execution path does not +exactly match your source file! An extreme example: if you define a +variable, but never use it, GDB never sees that variable--because the +compiler optimizes it out of existence. + + Some things do not work as well with '-g -O' as with just '-g', +particularly on machines with instruction scheduling. If in doubt, +recompile with '-g' alone, and if this fixes the problem, please report +it to us as a bug (including a test case!). *Note Variables::, for more +information about debugging optimized code. + +* Menu: + +* Inline Functions:: How GDB presents inlining +* Tail Call Frames:: GDB analysis of jumps to functions + + +File: gdb.info, Node: Inline Functions, Next: Tail Call Frames, Up: Optimized Code + +11.1 Inline Functions +===================== + +"Inlining" is an optimization that inserts a copy of the function body +directly at each call site, instead of jumping to a shared routine. GDB +displays inlined functions just like non-inlined functions. They appear +in backtraces. You can view their arguments and local variables, step +into them with 'step', skip them with 'next', and escape from them with +'finish'. You can check whether a function was inlined by using the +'info frame' command. + + For GDB to support inlined functions, the compiler must record +information about inlining in the debug information -- GCC using the +DWARF 2 format does this, and several other compilers do also. GDB only +supports inlined functions when using DWARF 2. Versions of GCC before +4.1 do not emit two required attributes ('DW_AT_call_file' and +'DW_AT_call_line'); GDB does not display inlined function calls with +earlier versions of GCC. It instead displays the arguments and local +variables of inlined functions as local variables in the caller. + + The body of an inlined function is directly included at its call +site; unlike a non-inlined function, there are no instructions devoted +to the call. GDB still pretends that the call site and the start of the +inlined function are different instructions. Stepping to the call site +shows the call site, and then stepping again shows the first line of the +inlined function, even though no additional instructions are executed. + + This makes source-level debugging much clearer; you can see both the +context of the call and then the effect of the call. Only stepping by a +single instruction using 'stepi' or 'nexti' does not do this; single +instruction steps always show the inlined body. + + There are some ways that GDB does not pretend that inlined function +calls are the same as normal calls: + + * Setting breakpoints at the call site of an inlined function may not + work, because the call site does not contain any code. GDB may + incorrectly move the breakpoint to the next line of the enclosing + function, after the call. This limitation will be removed in a + future version of GDB; until then, set a breakpoint on an earlier + line or inside the inlined function instead. + + * GDB cannot locate the return value of inlined calls after using the + 'finish' command. This is a limitation of compiler-generated + debugging information; after 'finish', you can step to the next + line and print a variable where your program stored the return + value. + + +File: gdb.info, Node: Tail Call Frames, Prev: Inline Functions, Up: Optimized Code + +11.2 Tail Call Frames +===================== + +Function 'B' can call function 'C' in its very last statement. In +unoptimized compilation the call of 'C' is immediately followed by +return instruction at the end of 'B' code. Optimizing compiler may +replace the call and return in function 'B' into one jump to function +'C' instead. Such use of a jump instruction is called "tail call". + + During execution of function 'C', there will be no indication in the +function call stack frames that it was tail-called from 'B'. If +function 'A' regularly calls function 'B' which tail-calls function 'C', +then GDB will see 'A' as the caller of 'C'. However, in some cases GDB +can determine that 'C' was tail-called from 'B', and it will then create +fictitious call frame for that, with the return address set up as if 'B' +called 'C' normally. + + This functionality is currently supported only by DWARF 2 debugging +format and the compiler has to produce 'DW_TAG_call_site' tags. With +GCC, you need to specify '-O -g' during compilation, to get this +information. + + 'info frame' command (*note Frame Info::) will indicate the tail call +frame kind by text 'tail call frame' such as in this sample GDB output: + + (gdb) x/i $pc - 2 + 0x40066b : jmp 0x400640 + (gdb) info frame + Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 + + The detection of all the possible code path executions can find them +ambiguous. There is no execution history stored (possible *note Reverse +Execution:: is never used for this purpose) and the last known caller +could have reached the known callee by multiple different jump +sequences. In such case GDB still tries to show at least all the +unambiguous top tail callers and all the unambiguous bottom tail +callees, if any. + +'set debug entry-values' + When set to on, enables printing of analysis messages for both + frame argument values at function entry and tail calls. It will + show all the possible valid tail calls code paths it has + considered. It will also print the intersection of them with the + final unambiguous (possibly partial or even empty) code path + result. + +'show debug entry-values' + Show the current state of analysis messages printing for both frame + argument values at function entry and tail calls. + + The analysis messages for tail calls can for example show why the +virtual tail call frame for function 'c' has not been recognized (due to +the indirect reference by variable 'x'): + + static void __attribute__((noinline, noclone)) c (void); + void (*x) (void) = c; + static void __attribute__((noinline, noclone)) a (void) { x++; } + static void __attribute__((noinline, noclone)) c (void) { a (); } + int main (void) { x (); return 0; } + + Breakpoint 1, DW_OP_entry_value resolving cannot find + DW_TAG_call_site 0x40039a in main + a () at t.c:3 + 3 static void __attribute__((noinline, noclone)) a (void) { x++; } + (gdb) bt + #0 a () at t.c:3 + #1 0x000000000040039a in main () at t.c:5 + + Another possibility is an ambiguous virtual tail call frames +resolution: + + int i; + static void __attribute__((noinline, noclone)) f (void) { i++; } + static void __attribute__((noinline, noclone)) e (void) { f (); } + static void __attribute__((noinline, noclone)) d (void) { f (); } + static void __attribute__((noinline, noclone)) c (void) { d (); } + static void __attribute__((noinline, noclone)) b (void) + { if (i) c (); else e (); } + static void __attribute__((noinline, noclone)) a (void) { b (); } + int main (void) { a (); return 0; } + + tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) + tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) + tailcall: reduced: 0x4004d2(a) | + (gdb) bt + #0 f () at t.c:2 + #1 0x00000000004004d2 in a () at t.c:8 + #2 0x0000000000400395 in main () at t.c:9 + + Frames #0 and #2 are real, #1 is a virtual tail call frame. The code +can have possible execution paths 'main->a->b->c->d->f' or +'main->a->b->e->f', GDB cannot find which one from the inferior state. + + 'initial:' state shows some random possible calling sequence GDB has +found. It then finds another possible calling sequence - that one is +prefixed by 'compare:'. The non-ambiguous intersection of these two is +printed as the 'reduced:' calling sequence. That one could have many +further 'compare:' and 'reduced:' statements as long as there remain any +non-ambiguous sequence entries. + + For the frame of function 'b' in both cases there are different +possible '$pc' values ('0x4004cc' or '0x4004ce'), therefore this frame +is also ambiguous. The only non-ambiguous frame is the one for function +'a', therefore this one is displayed to the user while the ambiguous +frames are omitted. + + There can be also reasons why printing of frame argument values at +function entry may fail: + + int v; + static void __attribute__((noinline, noclone)) c (int i) { v++; } + static void __attribute__((noinline, noclone)) a (int i); + static void __attribute__((noinline, noclone)) b (int i) { a (i); } + static void __attribute__((noinline, noclone)) a (int i) + { if (i) b (i - 1); else c (0); } + int main (void) { a (5); return 0; } + + (gdb) bt + #0 c (i=i@entry=0) at t.c:2 + #1 0x0000000000400428 in a (DW_OP_entry_value resolving has found + function "a" at 0x400420 can call itself via tail calls + i=) at t.c:6 + #2 0x000000000040036e in main () at t.c:7 + + GDB cannot find out from the inferior state if and how many times did +function 'a' call itself (via function 'b') as these calls would be tail +calls. Such tail calls would modify the 'i' variable, therefore GDB +cannot be sure the value it knows would be right - GDB prints +'' instead. + + +File: gdb.info, Node: Macros, Next: Tracepoints, Prev: Optimized Code, Up: Top + +12 C Preprocessor Macros +************************ + +Some languages, such as C and C++, provide a way to define and invoke +"preprocessor macros" which expand into strings of tokens. GDB can +evaluate expressions containing macro invocations, show the result of +macro expansion, and show a macro's definition, including where it was +defined. + + You may need to compile your program specially to provide GDB with +information about preprocessor macros. Most compilers do not include +macros in their debugging information, even when you compile with the +'-g' flag. *Note Compilation::. + + A program may define a macro at one point, remove that definition +later, and then provide a different definition after that. Thus, at +different points in the program, a macro may have different definitions, +or have no definition at all. If there is a current stack frame, GDB +uses the macros in scope at that frame's source code line. Otherwise, +GDB uses the macros in scope at the current listing location; see *note +List::. + + Whenever GDB evaluates an expression, it always expands any macro +invocations present in the expression. GDB also provides the following +commands for working with macros explicitly. + +'macro expand EXPRESSION' +'macro exp EXPRESSION' + Show the results of expanding all preprocessor macro invocations in + EXPRESSION. Since GDB simply expands macros, but does not parse + the result, EXPRESSION need not be a valid expression; it can be + any string of tokens. + +'macro expand-once EXPRESSION' +'macro exp1 EXPRESSION' + (This command is not yet implemented.) Show the results of + expanding those preprocessor macro invocations that appear + explicitly in EXPRESSION. Macro invocations appearing in that + expansion are left unchanged. This command allows you to see the + effect of a particular macro more clearly, without being confused + by further expansions. Since GDB simply expands macros, but does + not parse the result, EXPRESSION need not be a valid expression; it + can be any string of tokens. + +'info macro [-a|-all] [--] MACRO' + Show the current definition or all definitions of the named MACRO, + and describe the source location or compiler command-line where + that definition was established. The optional double dash is to + signify the end of argument processing and the beginning of MACRO + for non C-like macros where the macro may begin with a hyphen. + +'info macros LOCSPEC' + Show all macro definitions that are in effect at the source line of + the code location that results from resolving LOCSPEC, and describe + the source location or compiler command-line where those + definitions were established. + +'macro define MACRO REPLACEMENT-LIST' +'macro define MACRO(ARGLIST) REPLACEMENT-LIST' + Introduce a definition for a preprocessor macro named MACRO, + invocations of which are replaced by the tokens given in + REPLACEMENT-LIST. The first form of this command defines an + "object-like" macro, which takes no arguments; the second form + defines a "function-like" macro, which takes the arguments given in + ARGLIST. + + A definition introduced by this command is in scope in every + expression evaluated in GDB, until it is removed with the 'macro + undef' command, described below. The definition overrides all + definitions for MACRO present in the program being debugged, as + well as any previous user-supplied definition. + +'macro undef MACRO' + Remove any user-supplied definition for the macro named MACRO. + This command only affects definitions provided with the 'macro + define' command, described above; it cannot remove definitions + present in the program being debugged. + +'macro list' + List all the macros defined using the 'macro define' command. + + Here is a transcript showing the above commands in action. First, we +show our source files: + + $ cat sample.c + #include + #include "sample.h" + + #define M 42 + #define ADD(x) (M + x) + + main () + { + #define N 28 + printf ("Hello, world!\n"); + #undef N + printf ("We're so creative.\n"); + #define N 1729 + printf ("Goodbye, world!\n"); + } + $ cat sample.h + #define Q < + $ + + Now, we compile the program using the GNU C compiler, GCC. We pass +the '-gdwarf-2'(1) _and_ '-g3' flags to ensure the compiler includes +information about preprocessor macros in the debugging information. + + $ gcc -gdwarf-2 -g3 sample.c -o sample + $ + + Now, we start GDB on our sample program: + + $ gdb -nw sample + GNU gdb 2002-05-06-cvs + Copyright 2002 Free Software Foundation, Inc. + GDB is free software, ... + (gdb) + + We can expand macros and examine their definitions, even when the +program is not running. GDB uses the current listing position to decide +which macro definitions are in scope: + + (gdb) list main + 3 + 4 #define M 42 + 5 #define ADD(x) (M + x) + 6 + 7 main () + 8 { + 9 #define N 28 + 10 printf ("Hello, world!\n"); + 11 #undef N + 12 printf ("We're so creative.\n"); + (gdb) info macro ADD + Defined at /home/jimb/gdb/macros/play/sample.c:5 + #define ADD(x) (M + x) + (gdb) info macro Q + Defined at /home/jimb/gdb/macros/play/sample.h:1 + included at /home/jimb/gdb/macros/play/sample.c:2 + #define Q < + (gdb) macro expand ADD(1) + expands to: (42 + 1) + (gdb) macro expand-once ADD(1) + expands to: once (M + 1) + (gdb) + + In the example above, note that 'macro expand-once' expands only the +macro invocation explicit in the original text -- the invocation of +'ADD' -- but does not expand the invocation of the macro 'M', which was +introduced by 'ADD'. + + Once the program is running, GDB uses the macro definitions in force +at the source line of the current stack frame: + + (gdb) break main + Breakpoint 1 at 0x8048370: file sample.c, line 10. + (gdb) run + Starting program: /home/jimb/gdb/macros/play/sample + + Breakpoint 1, main () at sample.c:10 + 10 printf ("Hello, world!\n"); + (gdb) + + At line 10, the definition of the macro 'N' at line 9 is in force: + + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:9 + #define N 28 + (gdb) macro expand N Q M + expands to: 28 < 42 + (gdb) print N Q M + $1 = 1 + (gdb) + + As we step over directives that remove 'N''s definition, and then +give it a new definition, GDB finds the definition (or lack thereof) in +force at each point: + + (gdb) next + Hello, world! + 12 printf ("We're so creative.\n"); + (gdb) info macro N + The symbol `N' has no definition as a C/C++ preprocessor macro + at /home/jimb/gdb/macros/play/sample.c:12 + (gdb) next + We're so creative. + 14 printf ("Goodbye, world!\n"); + (gdb) info macro N + Defined at /home/jimb/gdb/macros/play/sample.c:13 + #define N 1729 + (gdb) macro expand N Q M + expands to: 1729 < 42 + (gdb) print N Q M + $2 = 0 + (gdb) + + In addition to source files, macros can be defined on the compilation +command line using the '-DNAME=VALUE' syntax. For macros defined in +such a way, GDB displays the location of their definition as line zero +of the source file submitted to the compiler. + + (gdb) info macro __STDC__ + Defined at /home/jimb/gdb/macros/play/sample.c:0 + -D__STDC__=1 + (gdb) + + ---------- Footnotes ---------- + + (1) This is the minimum. Recent versions of GCC support '-gdwarf-3' +and '-gdwarf-4'; we recommend always choosing the most recent version of +DWARF. + + +File: gdb.info, Node: Tracepoints, Next: Overlays, Prev: Macros, Up: Top + +13 Tracepoints +************** + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to change its behavior drastically, or perhaps fail, even when +the code itself is correct. It is useful to be able to observe the +program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, you can specify locations +in the program, called "tracepoints", and arbitrary expressions to +evaluate when those tracepoints are reached. Later, using the 'tfind' +command, you can examine the values those expressions had when the +program hit the tracepoints. The expressions may also denote objects in +memory--structures or arrays, for example--whose values GDB should +record; while visiting a particular tracepoint, you may inspect those +objects as if they were in memory at that moment. However, because GDB +records these values without interacting with you, it can do so quickly +and unobtrusively, hopefully not disturbing the program's behavior. + + The tracepoint facility is currently available only for remote +targets. *Note Targets::. In addition, your remote target must know +how to collect trace data. This functionality is implemented in the +remote stub; however, none of the stubs distributed with GDB support +tracepoints as of this writing. The format of the remote packets used +to implement tracepoints are described in *note Tracepoint Packets::. + + It is also possible to get trace data from a file, in a manner +reminiscent of corefiles; you specify the filename, and use 'tfind' to +search through the file. *Note Trace Files::, for more details. + + This chapter describes the tracepoint commands and features. + +* Menu: + +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: +* Trace Files:: + + +File: gdb.info, Node: Set Tracepoints, Next: Analyze Collected Data, Up: Tracepoints + +13.1 Commands to Set Tracepoints +================================ + +Before running such a "trace experiment", an arbitrary number of +tracepoints can be set. A tracepoint is actually a special type of +breakpoint (*note Set Breaks::), so you can manipulate it using standard +breakpoint commands. For instance, as with breakpoints, tracepoint +numbers are successive integers starting from one, and many of the +commands associated with tracepoints take the tracepoint number as their +argument, to identify which tracepoint to work on. + + For each tracepoint, you can specify, in advance, some arbitrary set +of data that you want the target to collect in the trace buffer when it +hits that tracepoint. The collected data can include registers, local +variables, or global data. Later, you can use GDB commands to examine +the values these data had at the time the tracepoint was hit. + + Tracepoints do not support every breakpoint feature. Ignore counts +on tracepoints have no effect, and tracepoints cannot run GDB commands +when they are hit. Tracepoints may not be thread-specific either. + + Some targets may support "fast tracepoints", which are inserted in a +different way (such as with a jump instead of a trap), that is faster +but possibly restricted in where they may be installed. + + Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location in +the target. Some targets may also support controlling "static +tracepoints" from GDB. With static tracing, a set of instrumentation +points, also known as "markers", are embedded in the target program, and +can be activated or deactivated by name or address. These are usually +placed at locations which facilitate investigating what the target is +actually doing. GDB's support for static tracing includes being able to +list instrumentation points, and attach them with GDB defined high level +tracepoints that expose the whole range of convenience of GDB's +tracepoints support. Namely, support for collecting registers values +and values of global or local (to the instrumentation point) variables; +tracepoint conditions and trace state variables. The act of installing +a GDB static tracepoint on an instrumentation point, or marker, is +referred to as "probing" a static tracepoint marker. + + 'gdbserver' supports tracepoints on some target systems. *Note +Tracepoints support in 'gdbserver': Server. + + This section describes commands to set tracepoints and associated +conditions and actions. + +* Menu: + +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Conditions:: +* Trace State Variables:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Listing Static Tracepoint Markers:: +* Starting and Stopping Trace Experiments:: +* Tracepoint Restrictions:: + + +File: gdb.info, Node: Create and Delete Tracepoints, Next: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.1 Create and Delete Tracepoints +------------------------------------ + +'trace LOCSPEC' + The 'trace' command is very similar to the 'break' command. Its + argument LOCSPEC can be any valid location specification. *Note + Location Specifications::. The 'trace' command defines a + tracepoint, which is a point in the target program where the + debugger will briefly stop, collect some data, and then allow the + program to continue. Setting a tracepoint or changing its actions + takes effect immediately if the remote stub supports the + 'InstallInTrace' feature (*note install tracepoint in tracing::). + If remote stub doesn't support the 'InstallInTrace' feature, all + these changes don't take effect until the next 'tstart' command, + and once a trace experiment is running, further changes will not + have any effect until the next trace experiment starts. In + addition, GDB supports "pending tracepoints"--tracepoints whose + address is not yet resolved. (This is similar to pending + breakpoints.) Pending tracepoints are not downloaded to the target + and not installed until they are resolved. The resolution of + pending tracepoints requires GDB support--when debugging with the + remote target, and GDB disconnects from the remote stub (*note + disconnected tracing::), pending tracepoints can not be resolved + (and downloaded to the remote stub) while GDB is disconnected. + + Here are some examples of using the 'trace' command: + + (gdb) trace foo.c:121 // a source file and line number + + (gdb) trace +2 // 2 lines forward + + (gdb) trace my_function // first source line of function + + (gdb) trace *my_function // EXACT start address of function + + (gdb) trace *0x2117c4 // an address + + You can abbreviate 'trace' as 'tr'. + +'trace LOCSPEC if COND' + Set a tracepoint with condition COND; evaluate the expression COND + each time the tracepoint is reached, and collect data only if the + value is nonzero--that is, if COND evaluates as true. *Note + Tracepoint Conditions: Tracepoint Conditions, for more information + on tracepoint conditions. + +'ftrace LOCSPEC [ if COND ]' + The 'ftrace' command sets a fast tracepoint. For targets that + support them, fast tracepoints will use a more efficient but + possibly less general technique to trigger data collection, such as + a jump instruction instead of a trap, or some sort of hardware + support. It may not be possible to create a fast tracepoint at the + desired location, in which case the command will exit with an + explanatory message. + + GDB handles arguments to 'ftrace' exactly as for 'trace'. + + On 32-bit x86-architecture systems, fast tracepoints normally need + to be placed at an instruction that is 5 bytes or longer, but can + be placed at 4-byte instructions if the low 64K of memory of the + target program is available to install trampolines. Some Unix-type + systems, such as GNU/Linux, exclude low addresses from the + program's address space; but for instance with the Linux kernel it + is possible to let GDB use this area by doing a 'sysctl' command to + set the 'mmap_min_addr' kernel parameter, as in + + sudo sysctl -w vm.mmap_min_addr=32768 + + which sets the low address to 32K, which leaves plenty of room for + trampolines. The minimum address should be set to a page boundary. + +'strace [LOCSPEC | -m MARKER] [ if COND ]' + The 'strace' command sets a static tracepoint. For targets that + support it, setting a static tracepoint probes a static + instrumentation point, or marker, found at the code locations that + result from resolving LOCSPEC. It may not be possible to set a + static tracepoint at the desired code location, in which case the + command will exit with an explanatory message. + + GDB handles arguments to 'strace' exactly as for 'trace', with the + addition that the user can also specify '-m MARKER' instead of a + location spec. This probes the marker identified by the MARKER + string identifier. This identifier depends on the static + tracepoint backend library your program is using. You can find all + the marker identifiers in the 'ID' field of the 'info + static-tracepoint-markers' command output. *Note Listing Static + Tracepoint Markers: Listing Static Tracepoint Markers. For + example, in the following small program using the UST tracing + engine: + + main () + { + trace_mark(ust, bar33, "str %s", "FOOBAZ"); + } + + the marker id is composed of joining the first two arguments to the + 'trace_mark' call with a slash, which translates to: + + (gdb) info static-tracepoint-markers + Cnt Enb ID Address What + 1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" + [etc...] + + so you may probe the marker above with: + + (gdb) strace -m ust/bar33 + + Static tracepoints accept an extra collect action -- 'collect + $_sdata'. This collects arbitrary user data passed in the probe + point call to the tracing library. In the UST example above, + you'll see that the third argument to 'trace_mark' is a printf-like + format string. The user data is then the result of running that + formatting string against the following arguments. Note that 'info + static-tracepoint-markers' command output lists that format string + in the 'Data:' field. + + You can inspect this data when analyzing the trace buffer, by + printing the $_sdata variable like any other variable available to + GDB. *Note Tracepoint Action Lists: Tracepoint Actions. + + The convenience variable '$tpnum' records the tracepoint number of + the most recently set tracepoint. + +'delete tracepoint [NUM]' + Permanently delete one or more tracepoints. With no argument, the + default is to delete all tracepoints. Note that the regular + 'delete' command can remove tracepoints also. + + Examples: + + (gdb) delete trace 1 2 3 // remove three tracepoints + + (gdb) delete trace // remove all tracepoints + + You can abbreviate this command as 'del tr'. + + +File: gdb.info, Node: Enable and Disable Tracepoints, Next: Tracepoint Passcounts, Prev: Create and Delete Tracepoints, Up: Set Tracepoints + +13.1.2 Enable and Disable Tracepoints +------------------------------------- + +These commands are deprecated; they are equivalent to plain 'disable' +and 'enable'. + +'disable tracepoint [NUM]' + Disable tracepoint NUM, or all tracepoints if no argument NUM is + given. A disabled tracepoint will have no effect during a trace + experiment, but it is not forgotten. You can re-enable a disabled + tracepoint using the 'enable tracepoint' command. If the command + is issued during a trace experiment and the debug target has + support for disabling tracepoints during a trace experiment, then + the change will be effective immediately. Otherwise, it will be + applied to the next trace experiment. + +'enable tracepoint [NUM]' + Enable tracepoint NUM, or all tracepoints. If this command is + issued during a trace experiment and the debug target supports + enabling tracepoints during a trace experiment, then the enabled + tracepoints will become effective immediately. Otherwise, they + will become effective the next time a trace experiment is run. + + +File: gdb.info, Node: Tracepoint Passcounts, Next: Tracepoint Conditions, Prev: Enable and Disable Tracepoints, Up: Set Tracepoints + +13.1.3 Tracepoint Passcounts +---------------------------- + +'passcount [N [NUM]]' + Set the "passcount" of a tracepoint. The passcount is a way to + automatically stop a trace experiment. If a tracepoint's passcount + is N, then the trace experiment will be automatically stopped on + the N'th time that tracepoint is hit. If the tracepoint number NUM + is not specified, the 'passcount' command sets the passcount of the + most recently defined tracepoint. If no passcount is given, the + trace experiment will run until stopped explicitly by the user. + + Examples: + + (gdb) passcount 5 2 // Stop on the 5th execution of + // tracepoint 2 + + (gdb) passcount 12 // Stop on the 12th execution of the + // most recently defined tracepoint. + (gdb) trace foo + (gdb) pass 3 + (gdb) trace bar + (gdb) pass 2 + (gdb) trace baz + (gdb) pass 1 // Stop tracing when foo has been + // executed 3 times OR when bar has + // been executed 2 times + // OR when baz has been executed 1 time. + + +File: gdb.info, Node: Tracepoint Conditions, Next: Trace State Variables, Prev: Tracepoint Passcounts, Up: Set Tracepoints + +13.1.4 Tracepoint Conditions +---------------------------- + +The simplest sort of tracepoint collects data every time your program +reaches a specified place. You can also specify a "condition" for a +tracepoint. A condition is just a Boolean expression in your +programming language (*note Expressions: Expressions.). A tracepoint +with a condition evaluates the expression each time your program reaches +it, and data collection happens only if the condition is true. + + Tracepoint conditions can be specified when a tracepoint is set, by +using 'if' in the arguments to the 'trace' command. *Note Setting +Tracepoints: Create and Delete Tracepoints. They can also be set or +changed at any time with the 'condition' command, just as with +breakpoints. + + Unlike breakpoint conditions, GDB does not actually evaluate the +conditional expression itself. Instead, GDB encodes the expression into +an agent expression (*note Agent Expressions::) suitable for execution +on the target, independently of GDB. Global variables become raw memory +locations, locals become stack accesses, and so forth. + + For instance, suppose you have a function that is usually called +frequently, but should not be called after an error has occurred. You +could use the following tracepoint command to collect data about calls +of that function that happen while the error code is propagating through +the program; an unconditional tracepoint could end up collecting +thousands of useless trace frames that you would have to search through. + + (gdb) trace normal_operation if errcode > 0 + + +File: gdb.info, Node: Trace State Variables, Next: Tracepoint Actions, Prev: Tracepoint Conditions, Up: Set Tracepoints + +13.1.5 Trace State Variables +---------------------------- + +A "trace state variable" is a special type of variable that is created +and managed by target-side code. The syntax is the same as that for +GDB's convenience variables (a string prefixed with "$"), but they are +stored on the target. They must be created explicitly, using a +'tvariable' command. They are always 64-bit signed integers. + + Trace state variables are remembered by GDB, and downloaded to the +target along with tracepoint information when the trace experiment +starts. There are no intrinsic limits on the number of trace state +variables, beyond memory limitations of the target. + + Although trace state variables are managed by the target, you can use +them in print commands and expressions as if they were convenience +variables; GDB will get the current value from the target while the +trace experiment is running. Trace state variables share the same +namespace as other "$" variables, which means that you cannot have trace +state variables with names like '$23' or '$pc', nor can you have a trace +state variable and a convenience variable with the same name. + +'tvariable $NAME [ = EXPRESSION ]' + The 'tvariable' command creates a new trace state variable named + '$NAME', and optionally gives it an initial value of EXPRESSION. + The EXPRESSION is evaluated when this command is entered; the + result will be converted to an integer if possible, otherwise GDB + will report an error. A subsequent 'tvariable' command specifying + the same name does not create a variable, but instead assigns the + supplied initial value to the existing variable of that name, + overwriting any previous initial value. The default initial value + is 0. + +'info tvariables' + List all the trace state variables along with their initial values. + Their current values may also be displayed, if the trace experiment + is currently running. + +'delete tvariable [ $NAME ... ]' + Delete the given trace state variables, or all of them if no + arguments are specified. + + +File: gdb.info, Node: Tracepoint Actions, Next: Listing Tracepoints, Prev: Trace State Variables, Up: Set Tracepoints + +13.1.6 Tracepoint Action Lists +------------------------------ + +'actions [NUM]' + This command will prompt for a list of actions to be taken when the + tracepoint is hit. If the tracepoint number NUM is not specified, + this command sets the actions for the one that was most recently + defined (so that you can define a tracepoint and then say 'actions' + without bothering about its number). You specify the actions + themselves on the following lines, one action at a time, and + terminate the actions list with a line containing just 'end'. So + far, the only defined actions are 'collect', 'teval', and + 'while-stepping'. + + 'actions' is actually equivalent to 'commands' (*note Breakpoint + Command Lists: Break Commands.), except that only the defined + actions are allowed; any other GDB command is rejected. + + To remove all actions from a tracepoint, type 'actions NUM' and + follow it immediately with 'end'. + + (gdb) collect DATA // collect some data + + (gdb) while-stepping 5 // single-step 5 times, collect data + + (gdb) end // signals the end of actions. + + In the following example, the action list begins with 'collect' + commands indicating the things to be collected when the tracepoint + is hit. Then, in order to single-step and collect additional data + following the tracepoint, a 'while-stepping' command is used, + followed by the list of things to be collected after each step in a + sequence of single steps. The 'while-stepping' command is + terminated by its own separate 'end' command. Lastly, the action + list is terminated by an 'end' command. + + (gdb) trace foo + (gdb) actions + Enter actions for tracepoint 1, one per line: + > collect bar,baz + > collect $regs + > while-stepping 12 + > collect $pc, arr[i] + > end + end + +'collect[/MODS] EXPR1, EXPR2, ...' + Collect values of the given expressions when the tracepoint is hit. + This command accepts a comma-separated list of any valid + expressions. In addition to global, static, or local variables, + the following special arguments are supported: + + '$regs' + Collect all registers. + + '$args' + Collect all function arguments. + + '$locals' + Collect all local variables. + + '$_ret' + Collect the return address. This is helpful if you want to + see more of a backtrace. + + _Note:_ The return address location can not always be reliably + determined up front, and the wrong address / registers may end + up collected instead. On some architectures the reliability + is higher for tracepoints at function entry, while on others + it's the opposite. When this happens, backtracing will stop + because the return address is found unavailable (unless + another collect rule happened to match it). + + '$_probe_argc' + Collects the number of arguments from the static probe at + which the tracepoint is located. *Note Static Probe Points::. + + '$_probe_argN' + N is an integer between 0 and 11. Collects the Nth argument + from the static probe at which the tracepoint is located. + *Note Static Probe Points::. + + '$_sdata' + Collect static tracepoint marker specific data. Only + available for static tracepoints. *Note Tracepoint Action + Lists: Tracepoint Actions. On the UST static tracepoints + library backend, an instrumentation point resembles a 'printf' + function call. The tracing library is able to collect user + specified data formatted to a character string using the + format provided by the programmer that instrumented the + program. Other backends have similar mechanisms. Here's an + example of a UST marker call: + + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) + + In this case, collecting '$_sdata' collects the string 'hello + $yourname'. When analyzing the trace buffer, you can inspect + '$_sdata' like any other variable available to GDB. + + You can give several consecutive 'collect' commands, each one with + a single argument, or one 'collect' command with several arguments + separated by commas; the effect is the same. + + The optional MODS changes the usual handling of the arguments. 's' + requests that pointers to chars be handled as strings, in + particular collecting the contents of the memory being pointed at, + up to the first zero. The upper bound is by default the value of + the 'print characters' variable; if 's' is followed by a decimal + number, that is the upper bound instead. So for instance + 'collect/s25 mystr' collects as many as 25 characters at 'mystr'. + + The command 'info scope' (*note info scope: Symbols.) is + particularly useful for figuring out what data to collect. + +'teval EXPR1, EXPR2, ...' + Evaluate the given expressions when the tracepoint is hit. This + command accepts a comma-separated list of expressions. The results + are discarded, so this is mainly useful for assigning values to + trace state variables (*note Trace State Variables::) without + adding those values to the trace buffer, as would be the case if + the 'collect' action were used. + +'while-stepping N' + Perform N single-step instruction traces after the tracepoint, + collecting new data after each step. The 'while-stepping' command + is followed by the list of what to collect while stepping (followed + by its own 'end' command): + + > while-stepping 12 + > collect $regs, myglobal + > end + > + + Note that '$pc' is not automatically collected by 'while-stepping'; + you need to explicitly collect that register if you need it. You + may abbreviate 'while-stepping' as 'ws' or 'stepping'. + +'set default-collect EXPR1, EXPR2, ...' + This variable is a list of expressions to collect at each + tracepoint hit. It is effectively an additional 'collect' action + prepended to every tracepoint action list. The expressions are + parsed individually for each tracepoint, so for instance a variable + named 'xyz' may be interpreted as a global for one tracepoint, and + a local for another, as appropriate to the tracepoint's location. + +'show default-collect' + Show the list of expressions that are collected by default at each + tracepoint hit. + + +File: gdb.info, Node: Listing Tracepoints, Next: Listing Static Tracepoint Markers, Prev: Tracepoint Actions, Up: Set Tracepoints + +13.1.7 Listing Tracepoints +-------------------------- + +'info tracepoints [NUM...]' + Display information about the tracepoint NUM. If you don't specify + a tracepoint number, displays information about all the tracepoints + defined so far. The format is similar to that used for 'info + breakpoints'; in fact, 'info tracepoints' is the same command, + simply restricting itself to tracepoints. + + A tracepoint's listing may include additional information specific + to tracing: + + * its passcount as given by the 'passcount N' command + + * the state about installed on target of each location + + (gdb) info trace + Num Type Disp Enb Address What + 1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 + while-stepping 20 + collect globfoo, $regs + end + collect globfoo2 + end + pass count 1200 + 2 tracepoint keep y + collect $eip + 2.1 y 0x0804859c in func4 at change-loc.h:35 + installed on target + 2.2 y 0xb7ffc480 in func4 at change-loc.h:35 + installed on target + 2.3 y set_tracepoint + 3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 + not installed on target + (gdb) + + This command can be abbreviated 'info tp'. + + +File: gdb.info, Node: Listing Static Tracepoint Markers, Next: Starting and Stopping Trace Experiments, Prev: Listing Tracepoints, Up: Set Tracepoints + +13.1.8 Listing Static Tracepoint Markers +---------------------------------------- + +'info static-tracepoint-markers' + Display information about all static tracepoint markers defined in + the program. + + For each marker, the following columns are printed: + + _Count_ + An incrementing counter, output to help readability. This is + not a stable identifier. + _ID_ + The marker ID, as reported by the target. + _Enabled or Disabled_ + Probed markers are tagged with 'y'. 'n' identifies marks that + are not enabled. + _Address_ + Where the marker is in your program, as a memory address. + _What_ + Where the marker is in the source for your program, as a file + and line number. If the debug information included in the + program does not allow GDB to locate the source of the marker, + this column will be left blank. + + In addition, the following information may be printed for each + marker: + + _Data_ + User data passed to the tracing library by the marker call. + In the UST backend, this is the format string passed as + argument to the marker call. + _Static tracepoints probing the marker_ + The list of static tracepoints attached to the marker. + + (gdb) info static-tracepoint-markers + Cnt ID Enb Address What + 1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 + 2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s + (gdb) + + +File: gdb.info, Node: Starting and Stopping Trace Experiments, Next: Tracepoint Restrictions, Prev: Listing Static Tracepoint Markers, Up: Set Tracepoints + +13.1.9 Starting and Stopping Trace Experiments +---------------------------------------------- + +'tstart' + This command starts the trace experiment, and begins collecting + data. It has the side effect of discarding all the data collected + in the trace buffer during the previous trace experiment. If any + arguments are supplied, they are taken as a note and stored with + the trace experiment's state. The notes may be arbitrary text, and + are especially useful with disconnected tracing in a multi-user + context; the notes can explain what the trace is doing, supply user + contact information, and so forth. + +'tstop' + This command stops the trace experiment. If any arguments are + supplied, they are recorded with the experiment as a note. This is + useful if you are stopping a trace started by someone else, for + instance if the trace is interfering with the system's behavior and + needs to be stopped quickly. + + *Note*: a trace experiment and data collection may stop + automatically if any tracepoint's passcount is reached (*note + Tracepoint Passcounts::), or if the trace buffer becomes full. + +'tstatus' + This command displays the status of the current trace data + collection. + + Here is an example of the commands we described so far: + + (gdb) trace gdb_c_test + (gdb) actions + Enter actions for tracepoint #1, one per line. + > collect $regs,$locals,$args + > while-stepping 11 + > collect $regs + > end + > end + (gdb) tstart + [time passes ...] + (gdb) tstop + + You can choose to continue running the trace experiment even if GDB +disconnects from the target, voluntarily or involuntarily. For commands +such as 'detach', the debugger will ask what you want to do with the +trace. But for unexpected terminations (GDB crash, network outage), it +would be unfortunate to lose hard-won trace data, so the variable +'disconnected-tracing' lets you decide whether the trace should continue +running without GDB. + +'set disconnected-tracing on' +'set disconnected-tracing off' + Choose whether a tracing run should continue to run if GDB has + disconnected from the target. Note that 'detach' or 'quit' will + ask you directly what to do about a running trace no matter what + this variable's setting, so the variable is mainly useful for + handling unexpected situations, such as loss of the network. + +'show disconnected-tracing' + Show the current choice for disconnected tracing. + + When you reconnect to the target, the trace experiment may or may not +still be running; it might have filled the trace buffer in the meantime, +or stopped for one of the other reasons. If it is running, it will +continue after reconnection. + + Upon reconnection, the target will upload information about the +tracepoints in effect. GDB will then compare that information to the +set of tracepoints currently defined, and attempt to match them up, +allowing for the possibility that the numbers may have changed due to +creation and deletion in the meantime. If one of the target's +tracepoints does not match any in GDB, the debugger will create a new +tracepoint, so that you have a number with which to specify that +tracepoint. This matching-up process is necessarily heuristic, and it +may result in useless tracepoints being created; you may simply delete +them if they are of no use. + + If your target agent supports a "circular trace buffer", then you can +run a trace experiment indefinitely without filling the trace buffer; +when space runs out, the agent deletes already-collected trace frames, +oldest first, until there is enough room to continue collecting. This +is especially useful if your tracepoints are being hit too often, and +your trace gets terminated prematurely because the buffer is full. To +ask for a circular trace buffer, simply set 'circular-trace-buffer' to +on. You can set this at any time, including during tracing; if the +agent can do it, it will change buffer handling on the fly, otherwise it +will not take effect until the next run. + +'set circular-trace-buffer on' +'set circular-trace-buffer off' + Choose whether a tracing run should use a linear or circular buffer + for trace data. A linear buffer will not lose any trace data, but + may fill up prematurely, while a circular buffer will discard old + trace data, but it will have always room for the latest tracepoint + hits. + +'show circular-trace-buffer' + Show the current choice for the trace buffer. Note that this may + not match the agent's current buffer handling, nor is it guaranteed + to match the setting that might have been in effect during a past + run, for instance if you are looking at frames from a trace file. + +'set trace-buffer-size N' +'set trace-buffer-size unlimited' + Request that the target use a trace buffer of N bytes. Not all + targets will honor the request; they may have a compiled-in size + for the trace buffer, or some other limitation. Set to a value of + 'unlimited' or '-1' to let the target use whatever size it likes. + This is also the default. + +'show trace-buffer-size' + Show the current requested size for the trace buffer. Note that + this will only match the actual size if the target supports + size-setting, and was able to handle the requested size. For + instance, if the target can only change buffer size between runs, + this variable will not reflect the change until the next run + starts. Use 'tstatus' to get a report of the actual buffer size. + +'set trace-user TEXT' + +'show trace-user' + +'set trace-notes TEXT' + Set the trace run's notes. + +'show trace-notes' + Show the trace run's notes. + +'set trace-stop-notes TEXT' + Set the trace run's stop notes. The handling of the note is as for + 'tstop' arguments; the set command is convenient way to fix a stop + note that is mistaken or incomplete. + +'show trace-stop-notes' + Show the trace run's stop notes. + + +File: gdb.info, Node: Tracepoint Restrictions, Prev: Starting and Stopping Trace Experiments, Up: Set Tracepoints + +13.1.10 Tracepoint Restrictions +------------------------------- + +There are a number of restrictions on the use of tracepoints. As +described above, tracepoint data gathering occurs on the target without +interaction from GDB. Thus the full capabilities of the debugger are +not available during data gathering, and then at data examination time, +you will be limited by only having what was collected. The following +items describe some common problems, but it is not exhaustive, and you +may run into additional difficulties not mentioned here. + + * Tracepoint expressions are intended to gather objects (lvalues). + Thus the full flexibility of GDB's expression evaluator is not + available. You cannot call functions, cast objects to aggregate + types, access convenience variables or modify values (except by + assignment to trace state variables). Some language features may + implicitly call functions (for instance Objective-C fields with + accessors), and therefore cannot be collected either. + + * Collection of local variables, either individually or in bulk with + '$locals' or '$args', during 'while-stepping' may behave + erratically. The stepping action may enter a new scope (for + instance by stepping into a function), or the location of the + variable may change (for instance it is loaded into a register). + The tracepoint data recorded uses the location information for the + variables that is correct for the tracepoint location. When the + tracepoint is created, it is not possible, in general, to determine + where the steps of a 'while-stepping' sequence will advance the + program--particularly if a conditional branch is stepped. + + * Collection of an incompletely-initialized or partially-destroyed + object may result in something that GDB cannot display, or displays + in a misleading way. + + * When GDB displays a pointer to character it automatically + dereferences the pointer to also display characters of the string + being pointed to. However, collecting the pointer during tracing + does not automatically collect the string. You need to explicitly + dereference the pointer and provide size information if you want to + collect not only the pointer, but the memory pointed to. For + example, '*ptr@50' can be used to collect the 50 element array + pointed to by 'ptr'. + + * It is not possible to collect a complete stack backtrace at a + tracepoint. Instead, you may collect the registers and a few + hundred bytes from the stack pointer with something like + '*(unsigned char *)$esp@300' (adjust to use the name of the actual + stack pointer register on your target architecture, and the amount + of stack you wish to capture). Then the 'backtrace' command will + show a partial backtrace when using a trace frame. The number of + stack frames that can be examined depends on the sizes of the + frames in the collected stack. Note that if you ask for a block so + large that it goes past the bottom of the stack, the target agent + may report an error trying to read from an invalid address. + + * If you do not collect registers at a tracepoint, GDB can infer that + the value of '$pc' must be the same as the address of the + tracepoint and use that when you are looking at a trace frame for + that tracepoint. However, this cannot work if the tracepoint has + multiple locations (for instance if it was set in a function that + was inlined), or if it has a 'while-stepping' loop. In those cases + GDB will warn you that it can't infer '$pc', and default it to + zero. + + +File: gdb.info, Node: Analyze Collected Data, Next: Tracepoint Variables, Prev: Set Tracepoints, Up: Tracepoints + +13.2 Using the Collected Data +============================= + +After the tracepoint experiment ends, you use GDB commands for examining +the trace data. The basic idea is that each tracepoint collects a trace +"snapshot" every time it is hit and another snapshot every time it +single-steps. All these snapshots are consecutively numbered from zero +and go into a buffer, and you can examine them later. The way you +examine them is to "focus" on a specific trace snapshot. When the +remote stub is focused on a trace snapshot, it will respond to all GDB +requests for memory and registers by reading from the buffer which +belongs to that snapshot, rather than from _real_ memory or registers of +the program being debugged. This means that *all* GDB commands +('print', 'info registers', 'backtrace', etc.) will behave as if we +were currently debugging the program state as it was when the tracepoint +occurred. Any requests for data that are not in the buffer will fail. + +* Menu: + +* tfind:: How to select a trace snapshot +* tdump:: How to display all data for a snapshot +* save tracepoints:: How to save tracepoints for a future run + + +File: gdb.info, Node: tfind, Next: tdump, Up: Analyze Collected Data + +13.2.1 'tfind N' +---------------- + +The basic command for selecting a trace snapshot from the buffer is +'tfind N', which finds trace snapshot number N, counting from zero. If +no argument N is given, the next snapshot is selected. + + Here are the various forms of using the 'tfind' command. + +'tfind start' + Find the first snapshot in the buffer. This is a synonym for + 'tfind 0' (since 0 is the number of the first snapshot). + +'tfind none' + Stop debugging trace snapshots, resume _live_ debugging. + +'tfind end' + Same as 'tfind none'. + +'tfind' + No argument means find the next trace snapshot or find the first + one if no trace snapshot is selected. + +'tfind -' + Find the previous trace snapshot before the current one. This + permits retracing earlier steps. + +'tfind tracepoint NUM' + Find the next snapshot associated with tracepoint NUM. Search + proceeds forward from the last examined trace snapshot. If no + argument NUM is given, it means find the next snapshot collected + for the same tracepoint as the current snapshot. + +'tfind pc ADDR' + Find the next snapshot associated with the value ADDR of the + program counter. Search proceeds forward from the last examined + trace snapshot. If no argument ADDR is given, it means find the + next snapshot with the same value of PC as the current snapshot. + +'tfind outside ADDR1, ADDR2' + Find the next snapshot whose PC is outside the given range of + addresses (exclusive). + +'tfind range ADDR1, ADDR2' + Find the next snapshot whose PC is between ADDR1 and ADDR2 + (inclusive). + +'tfind line [FILE:]N' + Find the next snapshot associated with the source line N. If the + optional argument FILE is given, refer to line N in that source + file. Search proceeds forward from the last examined trace + snapshot. If no argument N is given, it means find the next line + other than the one currently being examined; thus saying 'tfind + line' repeatedly can appear to have the same effect as stepping + from line to line in a _live_ debugging session. + + The default arguments for the 'tfind' commands are specifically +designed to make it easy to scan through the trace buffer. For +instance, 'tfind' with no argument selects the next trace snapshot, and +'tfind -' with no argument selects the previous trace snapshot. So, by +giving one 'tfind' command, and then simply hitting repeatedly you +can examine all the trace snapshots in order. Or, by saying 'tfind -' +and then hitting repeatedly you can examine the snapshots in +reverse order. The 'tfind line' command with no argument selects the +snapshot for the next source line executed. The 'tfind pc' command with +no argument selects the next snapshot with the same program counter (PC) +as the current frame. The 'tfind tracepoint' command with no argument +selects the next trace snapshot collected by the same tracepoint as the +current one. + + In addition to letting you scan through the trace buffer manually, +these commands make it easy to construct GDB scripts that scan through +the trace buffer and print out whatever collected data you are +interested in. Thus, if we want to examine the PC, FP, and SP registers +from each trace frame in the buffer, we can say this: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ + $trace_frame, $pc, $sp, $fp + > tfind + > end + + Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 + Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 + Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 + Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 + Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 + Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 + Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 + Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 + Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 + Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 + Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 + + Or, if we want to examine the variable 'X' at each source line in the +buffer: + + (gdb) tfind start + (gdb) while ($trace_frame != -1) + > printf "Frame %d, X == %d\n", $trace_frame, X + > tfind line + > end + + Frame 0, X = 1 + Frame 7, X = 2 + Frame 13, X = 255 + + +File: gdb.info, Node: tdump, Next: save tracepoints, Prev: tfind, Up: Analyze Collected Data + +13.2.2 'tdump' +-------------- + +This command takes no arguments. It prints all the data collected at +the current trace snapshot. + + (gdb) trace 444 + (gdb) actions + Enter actions for tracepoint #2, one per line: + > collect $regs, $locals, $args, gdb_long_test + > end + + (gdb) tstart + + (gdb) tfind line 444 + #0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) + at gdb_test.c:444 + 444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) + + (gdb) tdump + Data collected at tracepoint 2, trace frame 1: + d0 0xc4aa0085 -995491707 + d1 0x18 24 + d2 0x80 128 + d3 0x33 51 + d4 0x71aea3d 119204413 + d5 0x22 34 + d6 0xe0 224 + d7 0x380035 3670069 + a0 0x19e24a 1696330 + a1 0x3000668 50333288 + a2 0x100 256 + a3 0x322000 3284992 + a4 0x3000698 50333336 + a5 0x1ad3cc 1758156 + fp 0x30bf3c 0x30bf3c + sp 0x30bf34 0x30bf34 + ps 0x0 0 + pc 0x20b2c8 0x20b2c8 + fpcontrol 0x0 0 + fpstatus 0x0 0 + fpiaddr 0x0 0 + p = 0x20e5b4 "gdb-test" + p1 = (void *) 0x11 + p2 = (void *) 0x22 + p3 = (void *) 0x33 + p4 = (void *) 0x44 + p5 = (void *) 0x55 + p6 = (void *) 0x66 + gdb_long_test = 17 '\021' + + (gdb) + + 'tdump' works by scanning the tracepoint's current collection actions +and printing the value of each expression listed. So 'tdump' can fail, +if after a run, you change the tracepoint's actions to mention variables +that were not collected during the run. + + Also, for tracepoints with 'while-stepping' loops, 'tdump' uses the +collected value of '$pc' to distinguish between trace frames that were +collected at the tracepoint hit, and frames that were collected while +stepping. This allows it to correctly choose whether to display the +basic list of collections, or the collections from the body of the +while-stepping loop. However, if '$pc' was not collected, then 'tdump' +will always attempt to dump using the basic collection list, and may +fail if a while-stepping frame does not include all the same data that +is collected at the tracepoint hit. + + +File: gdb.info, Node: save tracepoints, Prev: tdump, Up: Analyze Collected Data + +13.2.3 'save tracepoints FILENAME' +---------------------------------- + +This command saves all current tracepoint definitions together with +their actions and passcounts, into a file 'FILENAME' suitable for use in +a later debugging session. To read the saved tracepoint definitions, +use the 'source' command (*note Command Files::). The +'save-tracepoints' command is a deprecated alias for 'save tracepoints' + + +File: gdb.info, Node: Tracepoint Variables, Next: Trace Files, Prev: Analyze Collected Data, Up: Tracepoints + +13.3 Convenience Variables for Tracepoints +========================================== + +'(int) $trace_frame' + The current trace snapshot (a.k.a. "frame") number, or -1 if no + snapshot is selected. + +'(int) $tracepoint' + The tracepoint for the current trace snapshot. + +'(int) $trace_line' + The line number for the current trace snapshot. + +'(char []) $trace_file' + The source file for the current trace snapshot. + +'(char []) $trace_func' + The name of the function containing '$tracepoint'. + + Note: '$trace_file' is not suitable for use in 'printf', use 'output' +instead. + + Here's a simple example of using these convenience variables for +stepping through all the trace snapshots and printing some of their +data. Note that these are not the same as trace state variables, which +are managed by the target. + + (gdb) tfind start + + (gdb) while $trace_frame != -1 + > output $trace_file + > printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint + > tfind + > end + + +File: gdb.info, Node: Trace Files, Prev: Tracepoint Variables, Up: Tracepoints + +13.4 Using Trace Files +====================== + +In some situations, the target running a trace experiment may no longer +be available; perhaps it crashed, or the hardware was needed for a +different activity. To handle these cases, you can arrange to dump the +trace data into a file, and later use that file as a source of trace +data, via the 'target tfile' command. + +'tsave [ -r ] FILENAME' +'tsave [-ctf] DIRNAME' + Save the trace data to FILENAME. By default, this command assumes + that FILENAME refers to the host filesystem, so if necessary GDB + will copy raw trace data up from the target and then save it. If + the target supports it, you can also supply the optional argument + '-r' ("remote") to direct the target to save the data directly into + FILENAME in its own filesystem, which may be more efficient if the + trace buffer is very large. (Note, however, that 'target tfile' + can only read from files accessible to the host.) By default, this + command will save trace frame in tfile format. You can supply the + optional argument '-ctf' to save data in CTF format. The "Common + Trace Format" (CTF) is proposed as a trace format that can be + shared by multiple debugging and tracing tools. Please go to + 'http://www.efficios.com/ctf' to get more information. + +'target tfile FILENAME' +'target ctf DIRNAME' + Use the file named FILENAME or directory named DIRNAME as a source + of trace data. Commands that examine data work as they do with a + live target, but it is not possible to run any new trace + experiments. 'tstatus' will report the state of the trace run at + the moment the data was saved, as well as the current trace frame + you are examining. Both FILENAME and DIRNAME must be on a + filesystem accessible to the host. + + The FILENAME and DIRNAME arguments supports escaping and quoting, + see *note Filenames As Command Arguments: Filename Arguments. + + (gdb) target ctf ctf.ctf + (gdb) tfind + Found trace frame 0, tracepoint 2 + 39 ++a; /* set tracepoint 1 here */ + (gdb) tdump + Data collected at tracepoint 2, trace frame 0: + i = 0 + a = 0 + b = 1 '\001' + c = {"123", "456", "789", "123", "456", "789"} + d = {{{a = 1, b = 2}, {a = 3, b = 4}}, {{a = 5, b = 6}, {a = 7, b = 8}}} + (gdb) p b + $1 = 1 + + +File: gdb.info, Node: Overlays, Next: Languages, Prev: Tracepoints, Up: Top + +14 Debugging Programs That Use Overlays +*************************************** + +If your program is too large to fit completely in your target system's +memory, you can sometimes use "overlays" to work around this problem. +GDB provides some support for debugging programs that use overlays. + +* Menu: + +* How Overlays Work:: A general explanation of overlays. +* Overlay Commands:: Managing overlays in GDB. +* Automatic Overlay Debugging:: GDB can find out which overlays are + mapped by asking the inferior. +* Overlay Sample Program:: A sample program using overlays. + + +File: gdb.info, Node: How Overlays Work, Next: Overlay Commands, Up: Overlays + +14.1 How Overlays Work +====================== + +Suppose you have a computer whose instruction address space is only 64 +kilobytes long, but which has much more memory which can be accessed by +other means: special instructions, segment registers, or memory +management hardware, for example. Suppose further that you want to +adapt a program which is larger than 64 kilobytes to run on this system. + + One solution is to identify modules of your program which are +relatively independent, and need not call each other directly; call +these modules "overlays". Separate the overlays from the main program, +and place their machine code in the larger memory. Place your main +program in instruction memory, but leave at least enough space there to +hold the largest overlay as well. + + Now, to call a function located in an overlay, you must first copy +that overlay's machine code from the large memory into the space set +aside for it in the instruction memory, and then jump to its entry point +there. + + Data Instruction Larger + Address Space Address Space Address Space + +-----------+ +-----------+ +-----------+ + | | | | | | + +-----------+ +-----------+ +-----------+<-- overlay 1 + | program | | main | .----| overlay 1 | load address + | variables | | program | | +-----------+ + | and heap | | | | | | + +-----------+ | | | +-----------+<-- overlay 2 + | | +-----------+ | | | load address + +-----------+ | | | .-| overlay 2 | + | | | | | | + mapped --->+-----------+ | | +-----------+ + address | | | | | | + | overlay | <-' | | | + | area | <---' +-----------+<-- overlay 3 + | | <---. | | load address + +-----------+ `--| overlay 3 | + | | | | + +-----------+ | | + +-----------+ + | | + +-----------+ + + A code overlay + + The diagram (*note A code overlay::) shows a system with separate +data and instruction address spaces. To map an overlay, the program +copies its code from the larger address space to the instruction address +space. Since the overlays shown here all use the same mapped address, +only one may be mapped at a time. For a system with a single address +space for data and instructions, the diagram would be similar, except +that the program variables and heap would share an address space with +the main program and the overlay area. + + An overlay loaded into instruction memory and ready for use is called +a "mapped" overlay; its "mapped address" is its address in the +instruction memory. An overlay not present (or only partially present) +in instruction memory is called "unmapped"; its "load address" is its +address in the larger memory. The mapped address is also called the +"virtual memory address", or "VMA"; the load address is also called the +"load memory address", or "LMA". + + Unfortunately, overlays are not a completely transparent way to adapt +a program to limited instruction memory. They introduce a new set of +global constraints you must keep in mind as you design your program: + + * Before calling or returning to a function in an overlay, your + program must make sure that overlay is actually mapped. Otherwise, + the call or return will transfer control to the right address, but + in the wrong overlay, and your program will probably crash. + + * If the process of mapping an overlay is expensive on your system, + you will need to choose your overlays carefully to minimize their + effect on your program's performance. + + * The executable file you load onto your system must contain each + overlay's instructions, appearing at the overlay's load address, + not its mapped address. However, each overlay's instructions must + be relocated and its symbols defined as if the overlay were at its + mapped address. You can use GNU linker scripts to specify + different load and relocation addresses for pieces of your program; + see *note (ld.info)Overlay Description::. + + * The procedure for loading executable files onto your system must be + able to load their contents into the larger address space as well + as the instruction and data spaces. + + The overlay system described above is rather simple, and could be +improved in many ways: + + * If your system has suitable bank switch registers or memory + management hardware, you could use those facilities to make an + overlay's load area contents simply appear at their mapped address + in instruction space. This would probably be faster than copying + the overlay to its mapped area in the usual way. + + * If your overlays are small enough, you could set aside more than + one overlay area, and have more than one overlay mapped at a time. + + * You can use overlays to manage data, as well as instructions. In + general, data overlays are even less transparent to your design + than code overlays: whereas code overlays only require care when + you call or return to functions, data overlays require care every + time you access the data. Also, if you change the contents of a + data overlay, you must copy its contents back out to its load + address before you can copy a different data overlay into the same + mapped area. + + +File: gdb.info, Node: Overlay Commands, Next: Automatic Overlay Debugging, Prev: How Overlays Work, Up: Overlays + +14.2 Overlay Commands +===================== + +To use GDB's overlay support, each overlay in your program must +correspond to a separate section of the executable file. The section's +virtual memory address and load memory address must be the overlay's +mapped and load addresses. Identifying overlays with sections allows +GDB to determine the appropriate address of a function or variable, +depending on whether the overlay is mapped or not. + + GDB's overlay commands all start with the word 'overlay'; you can +abbreviate this as 'ov' or 'ovly'. The commands are: + +'overlay off' + Disable GDB's overlay support. When overlay support is disabled, + GDB assumes that all functions and variables are always present at + their mapped addresses. By default, GDB's overlay support is + disabled. + +'overlay manual' + Enable "manual" overlay debugging. In this mode, GDB relies on you + to tell it which overlays are mapped, and which are not, using the + 'overlay map-overlay' and 'overlay unmap-overlay' commands + described below. + +'overlay map-overlay OVERLAY' +'overlay map OVERLAY' + Tell GDB that OVERLAY is now mapped; OVERLAY must be the name of + the object file section containing the overlay. When an overlay is + mapped, GDB assumes it can find the overlay's functions and + variables at their mapped addresses. GDB assumes that any other + overlays whose mapped ranges overlap that of OVERLAY are now + unmapped. + +'overlay unmap-overlay OVERLAY' +'overlay unmap OVERLAY' + Tell GDB that OVERLAY is no longer mapped; OVERLAY must be the name + of the object file section containing the overlay. When an overlay + is unmapped, GDB assumes it can find the overlay's functions and + variables at their load addresses. + +'overlay auto' + Enable "automatic" overlay debugging. In this mode, GDB consults a + data structure the overlay manager maintains in the inferior to see + which overlays are mapped. For details, see *note Automatic + Overlay Debugging::. + +'overlay load-target' +'overlay load' + Re-read the overlay table from the inferior. Normally, GDB + re-reads the table GDB automatically each time the inferior stops, + so this command should only be necessary if you have changed the + overlay mapping yourself using GDB. This command is only useful + when using automatic overlay debugging. + +'overlay list-overlays' +'overlay list' + Display a list of the overlays currently mapped, along with their + mapped addresses, load addresses, and sizes. + + Normally, when GDB prints a code address, it includes the name of the +function the address falls in: + + (gdb) print main + $3 = {int ()} 0x11a0
+When overlay debugging is enabled, GDB recognizes code in unmapped +overlays, and prints the names of unmapped functions with asterisks +around them. For example, if 'foo' is a function in an unmapped +overlay, GDB prints it this way: + + (gdb) overlay list + No sections are mapped. + (gdb) print foo + $5 = {int (int)} 0x100000 <*foo*> +When 'foo''s overlay is mapped, GDB prints the function's name normally: + + (gdb) overlay list + Section .ov.foo.text, loaded at 0x100000 - 0x100034, + mapped at 0x1016 - 0x104a + (gdb) print foo + $6 = {int (int)} 0x1016 + + When overlay debugging is enabled, GDB can find the correct address +for functions and variables in an overlay, whether or not the overlay is +mapped. This allows most GDB commands, like 'break' and 'disassemble', +to work normally, even on unmapped code. However, GDB's breakpoint +support has some limitations: + + * You can set breakpoints in functions in unmapped overlays, as long + as GDB can write to the overlay at its load address. + * GDB can not set hardware or simulator-based breakpoints in unmapped + overlays. However, if you set a breakpoint at the end of your + overlay manager (and tell GDB which overlays are now mapped, if you + are using manual overlay management), GDB will re-set its + breakpoints properly. + + +File: gdb.info, Node: Automatic Overlay Debugging, Next: Overlay Sample Program, Prev: Overlay Commands, Up: Overlays + +14.3 Automatic Overlay Debugging +================================ + +GDB can automatically track which overlays are mapped and which are not, +given some simple co-operation from the overlay manager in the inferior. +If you enable automatic overlay debugging with the 'overlay auto' +command (*note Overlay Commands::), GDB looks in the inferior's memory +for certain variables describing the current state of the overlays. + + Here are the variables your overlay manager must define to support +GDB's automatic overlay debugging: + +'_ovly_table': + This variable must be an array of the following structures: + + struct + { + /* The overlay's mapped address. */ + unsigned long vma; + + /* The size of the overlay, in bytes. */ + unsigned long size; + + /* The overlay's load address. */ + unsigned long lma; + + /* Non-zero if the overlay is currently mapped; + zero otherwise. */ + unsigned long mapped; + } + +'_novlys': + This variable must be a four-byte signed integer, holding the total + number of elements in '_ovly_table'. + + To decide whether a particular overlay is mapped or not, GDB looks +for an entry in '_ovly_table' whose 'vma' and 'lma' members equal the +VMA and LMA of the overlay's section in the executable file. When GDB +finds a matching entry, it consults the entry's 'mapped' member to +determine whether the overlay is currently mapped. + + In addition, your overlay manager may define a function called +'_ovly_debug_event'. If this function is defined, GDB will silently set +a breakpoint there. If the overlay manager then calls this function +whenever it has changed the overlay table, this will enable GDB to +accurately keep track of which overlays are in program memory, and +update any breakpoints that may be set in overlays. This will allow +breakpoints to work even if the overlays are kept in ROM or other +non-writable memory while they are not being executed. + diff -pruN 16.3-5/gdb/doc/gdb.info-3 16.3-5ubuntu1/gdb/doc/gdb.info-3 --- 16.3-5/gdb/doc/gdb.info-3 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-3 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,7143 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Overlay Sample Program, Prev: Automatic Overlay Debugging, Up: Overlays + +14.4 Overlay Sample Program +=========================== + +When linking a program which uses overlays, you must place the overlays +at their load addresses, while relocating them to run at their mapped +addresses. To do this, you must write a linker script (*note +(ld.info)Overlay Description::). Unfortunately, since linker scripts +are specific to a particular host system, target architecture, and +target memory layout, this manual cannot provide portable sample code +demonstrating GDB's overlay support. + + However, the GDB source distribution does contain an overlaid +program, with linker scripts for a few systems, as part of its test +suite. The program consists of the following files from +'gdb/testsuite/gdb.base': + +'overlays.c' + The main program file. +'ovlymgr.c' + A simple overlay manager, used by 'overlays.c'. +'foo.c' +'bar.c' +'baz.c' +'grbx.c' + Overlay modules, loaded and used by 'overlays.c'. +'d10v.ld' +'m32r.ld' + Linker scripts for linking the test program on the 'd10v-elf' and + 'm32r-elf' targets. + + You can build the test program using the 'd10v-elf' GCC +cross-compiler like this: + + $ d10v-elf-gcc -g -c overlays.c + $ d10v-elf-gcc -g -c ovlymgr.c + $ d10v-elf-gcc -g -c foo.c + $ d10v-elf-gcc -g -c bar.c + $ d10v-elf-gcc -g -c baz.c + $ d10v-elf-gcc -g -c grbx.c + $ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ + baz.o grbx.o -Wl,-Td10v.ld -o overlays + + The build process is identical for any other architecture, except +that you must substitute the appropriate compiler and linker script for +the target system for 'd10v-elf-gcc' and 'd10v.ld'. + + +File: gdb.info, Node: Languages, Next: Symbols, Prev: Overlays, Up: Top + +15 Using GDB with Different Languages +************************************* + +Although programming languages generally have common aspects, they are +rarely expressed in the same manner. For instance, in ANSI C, +dereferencing a pointer 'p' is accomplished by '*p', but in Modula-2, it +is accomplished by 'p^'. Values can also be represented (and displayed) +differently. Hex numbers in C appear as '0x1ae', while in Modula-2 they +appear as '1AEH'. + + Language-specific information is built into GDB for some languages, +allowing you to express operations like the above in your program's +native language, and allowing GDB to output values in a manner +consistent with the syntax of your program's native language. The +language you use to build expressions is called the "working language". + +* Menu: + +* Setting:: Switching between source languages +* Show:: Displaying the language +* Checks:: Type and range checks +* Supported Languages:: Supported languages +* Unsupported Languages:: Unsupported languages + + +File: gdb.info, Node: Setting, Next: Show, Up: Languages + +15.1 Switching Between Source Languages +======================================= + +There are two ways to control the working language--either have GDB set +it automatically, or select it manually yourself. You can use the 'set +language' command for either purpose. On startup, GDB defaults to +setting the language automatically. The working language is used to +determine how expressions you type are interpreted, how values are +printed, etc. + + In addition to the working language, every source file that GDB knows +about has its own working language. For some object file formats, the +compiler might indicate which language a particular source file is in. +However, most of the time GDB infers the language from the name of the +file. The language of a source file controls whether C++ names are +demangled--this way 'backtrace' can show each frame appropriately for +its own language. There is no way to set the language of a source file +from within GDB, but you can set the language associated with a filename +extension. *Note Displaying the Language: Show. + + This is most commonly a problem when you use a program, such as +'cfront' or 'f2c', that generates C but is written in another language. +In that case, make the program use '#line' directives in its C output; +that way GDB will know the correct language of the source code of the +original program, and will display that source code, not the generated C +code. + +* Menu: + +* Filenames:: Filename extensions and languages. +* Manually:: Setting the working language manually +* Automatically:: Having GDB infer the source language + + +File: gdb.info, Node: Filenames, Next: Manually, Up: Setting + +15.1.1 List of Filename Extensions and Languages +------------------------------------------------ + +If a source file name ends in one of the following extensions, then GDB +infers that its language is the one indicated. + +'.ada' +'.ads' +'.adb' +'.a' + Ada source file. + +'.c' + C source file + +'.C' +'.cc' +'.cp' +'.cpp' +'.cxx' +'.c++' + C++ source file + +'.d' + D source file + +'.m' + Objective-C source file + +'.f' +'.F' + Fortran source file + +'.mod' + Modula-2 source file + +'.s' +'.S' + Assembler source file. This actually behaves almost like C, but + GDB does not skip over function prologues when stepping. + + In addition, you may set the language associated with a filename +extension. *Note Displaying the Language: Show. + + +File: gdb.info, Node: Manually, Next: Automatically, Prev: Filenames, Up: Setting + +15.1.2 Setting the Working Language +----------------------------------- + +If you allow GDB to set the language automatically, expressions are +interpreted the same way in your debugging session and your program. + + If you wish, you may set the language manually. To do this, issue +the command 'set language LANG', where LANG is the name of a language, +such as 'c' or 'modula-2'. For a list of the supported languages, type +'set language'. + + Setting the language manually prevents GDB from updating the working +language automatically. This can lead to confusion if you try to debug +a program when the working language is not the same as the source +language, when an expression is acceptable to both languages--but means +different things. For instance, if the current source file were written +in C, and GDB was parsing Modula-2, a command such as: + + print a = b + c + +might not have the effect you intended. In C, this means to add 'b' and +'c' and place the result in 'a'. The result printed would be the value +of 'a'. In Modula-2, this means to compare 'a' to the result of 'b+c', +yielding a 'BOOLEAN' value. + + +File: gdb.info, Node: Automatically, Prev: Manually, Up: Setting + +15.1.3 Having GDB Infer the Source Language +------------------------------------------- + +To have GDB set the working language automatically, use 'set language +local' or 'set language auto'. GDB then infers the working language. +That is, when your program stops in a frame (usually by encountering a +breakpoint), GDB sets the working language to the language recorded for +the function in that frame. If the language for a frame is unknown +(that is, if the function or block corresponding to the frame was +defined in a source file that does not have a recognized extension), the +current working language is not changed, and GDB issues a warning. + + This may not seem necessary for most programs, which are written +entirely in one source language. However, program modules and libraries +written in one source language can be used by a main program written in +a different source language. Using 'set language auto' in this case +frees you from having to set the working language manually. + + The warning is enabled by default, but it can be controlled via a +setting: + +'set warn-language-frame-mismatch [on|off]' + Enable or disable the warning that is issued when the current + language is set to a value that does not match the current frame. + +'show warn-language-frame-mismatch' + Show whether the frame-mismatch warning will be issued. + + +File: gdb.info, Node: Show, Next: Checks, Prev: Setting, Up: Languages + +15.2 Displaying the Language +============================ + +The following commands help you find out which language is the working +language, and also what language source files were written in. + +'show language' + Display the current working language. This is the language you can + use with commands such as 'print' to build and compute expressions + that may involve variables in your program. + +'info frame' + Display the source language for this frame. This language becomes + the working language if you use an identifier from this frame. + *Note Information about a Frame: Frame Info, to identify the other + information listed here. + +'info source' + Display the source language of this source file. *Note Examining + the Symbol Table: Symbols, to identify the other information listed + here. + + In unusual circumstances, you may have source files with extensions +not in the standard list. You can then set the extension associated +with a language explicitly: + +'set extension-language EXT LANGUAGE' + Tell GDB that source files with extension EXT are to be assumed as + written in the source language LANGUAGE. + +'info extensions' + List all the filename extensions and the associated languages. + + +File: gdb.info, Node: Checks, Next: Supported Languages, Prev: Show, Up: Languages + +15.3 Type and Range Checking +============================ + +Some languages are designed to guard you against making seemingly common +errors through a series of compile- and run-time checks. These include +checking the type of arguments to functions and operators and making +sure mathematical overflows are caught at run time. Checks such as +these help to ensure a program's correctness once it has been compiled +by eliminating type mismatches and providing active checks for range +errors when your program is running. + + By default GDB checks for these errors according to the rules of the +current source language. Although GDB does not check the statements in +your program, it can check expressions entered directly into GDB for +evaluation via the 'print' command, for example. + +* Menu: + +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking + + +File: gdb.info, Node: Type Checking, Next: Range Checking, Up: Checks + +15.3.1 An Overview of Type Checking +----------------------------------- + +Some languages, such as C and C++, are strongly typed, meaning that the +arguments to operators and functions have to be of the correct type, +otherwise an error occurs. These checks prevent type mismatch errors +from ever causing any run-time problems. For example, + + int klass::my_method(char *b) { return b ? 1 : 2; } + + (gdb) print obj.my_method (0) + $1 = 2 +but + (gdb) print obj.my_method (0x1234) + Cannot resolve method klass::my_method to any overloaded instance + + The second example fails because in C++ the integer constant '0x1234' +is not type-compatible with the pointer parameter type. + + For the expressions you use in GDB commands, you can tell GDB to not +enforce strict type checking or to treat any mismatches as errors and +abandon the expression; When type checking is disabled, GDB successfully +evaluates expressions like the second example above. + + Even if type checking is off, there may be other reasons related to +type that prevent GDB from evaluating an expression. For instance, GDB +does not know how to add an 'int' and a 'struct foo'. These particular +type errors have nothing to do with the language in use and usually +arise from expressions which make little sense to evaluate anyway. + + GDB provides some additional commands for controlling type checking: + +'set check type on' +'set check type off' + Set strict type checking on or off. If any type mismatches occur + in evaluating an expression while type checking is on, GDB prints a + message and aborts evaluation of the expression. + +'show check type' + Show the current setting of type checking and whether GDB is + enforcing strict type checking rules. + + +File: gdb.info, Node: Range Checking, Prev: Type Checking, Up: Checks + +15.3.2 An Overview of Range Checking +------------------------------------ + +In some languages (such as Modula-2), it is an error to exceed the +bounds of a type; this is enforced with run-time checks. Such range +checking is meant to ensure program correctness by making sure +computations do not overflow, or indices on an array element access do +not exceed the bounds of the array. + + For expressions you use in GDB commands, you can tell GDB to treat +range errors in one of three ways: ignore them, always treat them as +errors and abandon the expression, or issue warnings but evaluate the +expression anyway. + + A range error can result from numerical overflow, from exceeding an +array index bound, or when you type a constant that is not a member of +any type. Some languages, however, do not treat overflows as an error. +In many implementations of C, mathematical overflow causes the result to +"wrap around" to lower values--for example, if M is the largest integer +value, and S is the smallest, then + + M + 1 => S + + This, too, is specific to individual languages, and in some cases +specific to individual compilers or machines. *Note Supported +Languages: Supported Languages, for further details on specific +languages. + + GDB provides some additional commands for controlling the range +checker: + +'set check range auto' + Set range checking on or off based on the current working language. + *Note Supported Languages: Supported Languages, for the default + settings for each language. + +'set check range on' +'set check range off' + Set range checking on or off, overriding the default setting for + the current working language. A warning is issued if the setting + does not match the language default. If a range error occurs and + range checking is on, then a message is printed and evaluation of + the expression is aborted. + +'set check range warn' + Output messages when the GDB range checker detects a range error, + but attempt to evaluate the expression anyway. Evaluating the + expression may still be impossible for other reasons, such as + accessing memory that the process does not own (a typical example + from many Unix systems). + +'show check range' + Show the current setting of the range checker, and whether or not + it is being set automatically by GDB. + + +File: gdb.info, Node: Supported Languages, Next: Unsupported Languages, Prev: Checks, Up: Languages + +15.4 Supported Languages +======================== + +GDB supports C, C++, D, Go, Objective-C, Fortran, OpenCL C, Pascal, +Rust, assembly, Modula-2, and Ada. Some GDB features may be used in +expressions regardless of the language you use: the GDB '@' and '::' +operators, and the '{type}addr' construct (*note Expressions: +Expressions.) can be used with the constructs of any supported language. + + The following sections detail to what degree each source language is +supported by GDB. These sections are not meant to be language tutorials +or references, but serve only as a reference guide to what the GDB +expression parser accepts, and what input and output formats should look +like for different languages. There are many good books written on each +of these languages; please look to these for a language reference or +tutorial. + +* Menu: + +* C:: C and C++ +* D:: D +* Go:: Go +* Objective-C:: Objective-C +* OpenCL C:: OpenCL C +* Fortran:: Fortran +* Pascal:: Pascal +* Rust:: Rust +* Modula-2:: Modula-2 +* Ada:: Ada + + +File: gdb.info, Node: C, Next: D, Up: Supported Languages + +15.4.1 C and C++ +---------------- + +Since C and C++ are so closely related, many features of GDB apply to +both languages. Whenever this is the case, we discuss those languages +together. + + The C++ debugging facilities are jointly implemented by the C++ +compiler and GDB. Therefore, to debug your C++ code effectively, you +must compile your C++ programs with a supported C++ compiler, such as +GNU 'g++', or the HP ANSI C++ compiler ('aCC'). + +* Menu: + +* C Operators:: C and C++ operators +* C Constants:: C and C++ constants +* C Plus Plus Expressions:: C++ expressions +* C Defaults:: Default settings for C and C++ +* C Checks:: C and C++ type and range checks +* Debugging C:: GDB and C +* Debugging C Plus Plus:: GDB features for C++ +* Decimal Floating Point:: Numbers in Decimal Floating Point format + + +File: gdb.info, Node: C Operators, Next: C Constants, Up: C + +15.4.1.1 C and C++ Operators +............................ + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. + + For the purposes of C and C++, the following definitions hold: + + * _Integral types_ include 'int' with any of its storage-class + specifiers; 'char'; 'enum'; and, for C++, 'bool'. + + * _Floating-point types_ include 'float', 'double', and 'long double' + (if supported by the target platform). + + * _Pointer types_ include all types defined as '(TYPE *)'. + + * _Scalar types_ include all of the above. + +The following operators are supported. They are listed here in order of +increasing precedence: + +',' + The comma or sequencing operator. Expressions in a comma-separated + list are evaluated from left to right, with the result of the + entire expression being the last expression evaluated. + +'=' + Assignment. The value of an assignment expression is the value + assigned. Defined on scalar types. + +'OP=' + Used in an expression of the form 'A OP= B', and translated to + 'A = A OP B'. 'OP=' and '=' have the same precedence. The + operator OP is any one of the operators '|', '^', '&', '<<', '>>', + '+', '-', '*', '/', '%'. + +'?:' + The ternary operator. 'A ? B : C' can be thought of as: if A then + B else C. The argument A should be of an integral type. + +'||' + Logical OR. Defined on integral types. + +'&&' + Logical AND. Defined on integral types. + +'|' + Bitwise OR. Defined on integral types. + +'^' + Bitwise exclusive-OR. Defined on integral types. + +'&' + Bitwise AND. Defined on integral types. + +'==, !=' + Equality and inequality. Defined on scalar types. The value of + these expressions is 0 for false and non-zero for true. + +'<, >, <=, >=' + Less than, greater than, less than or equal, greater than or equal. + Defined on scalar types. The value of these expressions is 0 for + false and non-zero for true. + +'<<, >>' + left shift, and right shift. Defined on integral types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction. Defined on integral types, + floating-point types and pointer types. + +'*, /, %' + Multiplication, division, and modulus. Multiplication and division + are defined on integral and floating-point types. Modulus is + defined on integral types. + +'++, --' + Increment and decrement. When appearing before a variable, the + operation is performed before the variable is used in an + expression; when appearing after it, the variable's value is used + before the operation takes place. + +'*' + Pointer dereferencing. Defined on pointer types. Same precedence + as '++'. + +'&' + Address operator. Defined on variables. Same precedence as '++'. + + For debugging C++, GDB implements a use of '&' beyond what is + allowed in the C++ language itself: you can use '&(&REF)' to + examine the address where a C++ reference variable (declared with + '&REF') is stored. + +'-' + Negative. Defined on integral and floating-point types. Same + precedence as '++'. + +'!' + Logical negation. Defined on integral types. Same precedence as + '++'. + +'~' + Bitwise complement operator. Defined on integral types. Same + precedence as '++'. + +'., ->' + Structure member, and pointer-to-structure member. For + convenience, GDB regards the two as equivalent, choosing whether to + dereference a pointer based on the stored type information. + Defined on 'struct' and 'union' data. + +'.*, ->*' + Dereferences of pointers to members. + +'[]' + Array indexing. 'A[I]' is defined as '*(A+I)'. Same precedence as + '->'. + +'()' + Function parameter list. Same precedence as '->'. + +'::' + C++ scope resolution operator. Defined on 'struct', 'union', and + 'class' types. + +'::' + Doubled colons also represent the GDB scope operator (*note + Expressions: Expressions.). Same precedence as '::', above. + + If an operator is redefined in the user code, GDB usually attempts to +invoke the redefined version instead of using the operator's predefined +meaning. + + +File: gdb.info, Node: C Constants, Next: C Plus Plus Expressions, Prev: C Operators, Up: C + +15.4.1.2 C and C++ Constants +............................ + +GDB allows you to express the constants of C and C++ in the following +ways: + + * Integer constants are a sequence of digits. Octal constants are + specified by a leading '0' (i.e. zero), and hexadecimal constants + by a leading '0x' or '0X'. Constants may also end with a letter + 'l', specifying that the constant should be treated as a 'long' + value. + + * Floating point constants are a sequence of digits, followed by a + decimal point, followed by a sequence of digits, and optionally + followed by an exponent. An exponent is of the form: + 'e[[+]|-]NNN', where NNN is another sequence of digits. The '+' is + optional for positive exponents. A floating-point constant may + also end with a letter 'f' or 'F', specifying that the constant + should be treated as being of the 'float' (as opposed to the + default 'double') type; or with a letter 'l' or 'L', which + specifies a 'long double' constant. + + * Enumerated constants consist of enumerated identifiers, or their + integral equivalents. + + * Character constants are a single character surrounded by single + quotes ('''), or a number--the ordinal value of the corresponding + character (usually its ASCII value). Within quotes, the single + character may be represented by a letter or by "escape sequences", + which are of the form '\NNN', where NNN is the octal representation + of the character's ordinal value; or of the form '\X', where 'X' is + a predefined special character--for example, '\n' for newline. + + Wide character constants can be written by prefixing a character + constant with 'L', as in C. For example, 'L'x'' is the wide form of + 'x'. The target wide character set is used when computing the + value of this constant (*note Character Sets::). + + * String constants are a sequence of character constants surrounded + by double quotes ('"'). Any valid character constant (as described + above) may appear. Double quotes within the string must be + preceded by a backslash, so for instance '"a\"b'c"' is a string of + five characters. + + Wide string constants can be written by prefixing a string constant + with 'L', as in C. The target wide character set is used when + computing the value of this constant (*note Character Sets::). + + * Pointer constants are an integral value. You can also write + pointers to constants using the C operator '&'. + + * Array constants are comma-separated lists surrounded by braces '{' + and '}'; for example, '{1,2,3}' is a three-element array of + integers, '{{1,2}, {3,4}, {5,6}}' is a three-by-two array, and + '{&"hi", &"there", &"fred"}' is a three-element array of pointers. + + +File: gdb.info, Node: C Plus Plus Expressions, Next: C Defaults, Prev: C Constants, Up: C + +15.4.1.3 C++ Expressions +........................ + +GDB expression handling can interpret most C++ expressions. + + _Warning:_ GDB can only debug C++ code if you use the proper + compiler and the proper debug format. Currently, GDB works best + when debugging C++ code that is compiled with the most recent + version of GCC possible. The DWARF debugging format is preferred; + GCC defaults to this on most popular platforms. Other compilers + and/or debug formats are likely to work badly or not at all when + using GDB to debug C++ code. *Note Compilation::. + + 1. Member function calls are allowed; you can use expressions like + + count = aml->GetOriginal(x, y) + + 2. While a member function is active (in the selected stack frame), + your expressions have the same namespace available as the member + function; that is, GDB allows implicit references to the class + instance pointer 'this' following the same rules as C++. 'using' + declarations in the current scope are also respected by GDB. + + 3. You can call overloaded functions; GDB resolves the function call + to the right definition, with some restrictions. GDB does not + perform overload resolution involving user-defined type + conversions, calls to constructors, or instantiations of templates + that do not exist in the program. It also cannot handle ellipsis + argument lists or default arguments. + + It does perform integral conversions and promotions, floating-point + promotions, arithmetic conversions, pointer conversions, + conversions of class objects to base classes, and standard + conversions such as those of functions or arrays to pointers; it + requires an exact match on the number of function arguments. + + Overload resolution is always performed, unless you have specified + 'set overload-resolution off'. *Note GDB Features for C++: + Debugging C Plus Plus. + + You must specify 'set overload-resolution off' in order to use an + explicit function signature to call an overloaded function, as in + p 'foo(char,int)'('x', 13) + + The GDB command-completion facility can simplify this; see *note + Command Completion: Completion. + + 4. GDB understands variables declared as C++ lvalue or rvalue + references; you can use them in expressions just as you do in C++ + source--they are automatically dereferenced. + + In the parameter list shown when GDB displays a frame, the values + of reference variables are not displayed (unlike other variables); + this avoids clutter, since references are often used for large + structures. The _address_ of a reference variable is always shown, + unless you have specified 'set print address off'. + + 5. GDB supports the C++ name resolution operator '::'--your + expressions can use it just as expressions in your program do. + Since one scope may be defined in another, you can use '::' + repeatedly if necessary, for example in an expression like + 'SCOPE1::SCOPE2::NAME'. GDB also allows resolving name scope by + reference to source files, in both C and C++ debugging (*note + Program Variables: Variables.). + + 6. GDB performs argument-dependent lookup, following the C++ + specification. + + +File: gdb.info, Node: C Defaults, Next: C Checks, Prev: C Plus Plus Expressions, Up: C + +15.4.1.4 C and C++ Defaults +........................... + +If you allow GDB to set range checking automatically, it defaults to +'off' whenever the working language changes to C or C++. This happens +regardless of whether you or GDB selects the working language. + + If you allow GDB to set the language automatically, it recognizes +source files whose names end with '.c', '.C', or '.cc', etc, and when +GDB enters code compiled from one of these files, it sets the working +language to C or C++. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: C Checks, Next: Debugging C, Prev: C Defaults, Up: C + +15.4.1.5 C and C++ Type and Range Checks +........................................ + +By default, when GDB parses C or C++ expressions, strict type checking +is used. However, if you turn type checking off, GDB will allow certain +non-standard conversions, such as promoting integer constants to +pointers. + + Range checking, if turned on, is done on mathematical operations. +Array indices are not checked, since they are often used to index a +pointer that is not itself an array. + + +File: gdb.info, Node: Debugging C, Next: Debugging C Plus Plus, Prev: C Checks, Up: C + +15.4.1.6 GDB and C +.................. + +The 'set print union' and 'show print union' commands apply to the +'union' type. When set to 'on', any 'union' that is inside a 'struct' +or 'class' is also printed. Otherwise, it appears as '{...}'. + + The '@' operator aids in the debugging of dynamic arrays, formed with +pointers and a memory allocation function. *Note Expressions: +Expressions. + + +File: gdb.info, Node: Debugging C Plus Plus, Next: Decimal Floating Point, Prev: Debugging C, Up: C + +15.4.1.7 GDB Features for C++ +............................. + +Some GDB commands are particularly useful with C++, and some are +designed specifically for use with C++. Here is a summary: + +'breakpoint menus' + When you want a breakpoint in a function whose name is overloaded, + GDB has the capability to display a menu of possible breakpoint + locations to help you specify which function definition you want. + *Note Ambiguous Expressions: Ambiguous Expressions. + +'rbreak REGEX' + Setting breakpoints using regular expressions is helpful for + setting breakpoints on overloaded functions that are not members of + any special classes. *Note Setting Breakpoints: Set Breaks. + +'catch throw' +'catch rethrow' +'catch catch' + Debug C++ exception handling using these commands. *Note Setting + Catchpoints: Set Catchpoints. + +'ptype TYPENAME' + Print inheritance relationships as well as other information for + type TYPENAME. *Note Examining the Symbol Table: Symbols. + +'info vtbl EXPRESSION.' + The 'info vtbl' command can be used to display the virtual method + tables of the object computed by EXPRESSION. This shows one entry + per virtual table; there may be multiple virtual tables when + multiple inheritance is in use. + +'demangle NAME' + Demangle NAME. *Note Symbols::, for a more complete description of + the 'demangle' command. + +'set print demangle' +'show print demangle' +'set print asm-demangle' +'show print asm-demangle' + Control whether C++ symbols display in their source form, both when + displaying code as C++ source and when displaying disassemblies. + *Note Print Settings: Print Settings. + +'set print object' +'show print object' + Choose whether to print derived (actual) or declared types of + objects. *Note Print Settings: Print Settings. + +'set print vtbl' +'show print vtbl' + Control the format for printing virtual function tables. *Note + Print Settings: Print Settings. (The 'vtbl' commands do not work + on programs compiled with the HP ANSI C++ compiler ('aCC').) + +'set overload-resolution on' + Enable overload resolution for C++ expression evaluation. The + default is on. For overloaded functions, GDB evaluates the + arguments and searches for a function whose signature matches the + argument types, using the standard C++ conversion rules (see *note + C++ Expressions: C Plus Plus Expressions, for details). If it + cannot find a match, it emits a message. + +'set overload-resolution off' + Disable overload resolution for C++ expression evaluation. For + overloaded functions that are not class member functions, GDB + chooses the first function of the specified name that it finds in + the symbol table, whether or not its arguments are of the correct + type. For overloaded functions that are class member functions, + GDB searches for a function whose signature _exactly_ matches the + argument types. + +'show overload-resolution' + Show the current setting of overload resolution. + +'Overloaded symbol names' + You can specify a particular definition of an overloaded symbol, + using the same notation that is used to declare such symbols in + C++: type 'SYMBOL(TYPES)' rather than just SYMBOL. You can also + use the GDB command-line word completion facilities to list the + available choices, or to finish the type list for you. *Note + Command Completion: Completion, for details on how to do this. + +'Breakpoints in template functions' + + Similar to how overloaded symbols are handled, GDB will ignore + template parameter lists when it encounters a symbol which includes + a C++ template. This permits setting breakpoints on families of + template functions or functions whose parameters include template + types. + + The '-qualified' flag may be used to override this behavior, + causing GDB to search for a specific function or type. + + The GDB command-line word completion facility also understands + template parameters and may be used to list available choices or + finish template parameter lists for you. *Note Command Completion: + Completion, for details on how to do this. + +'Breakpoints in functions with ABI tags' + + The GNU C++ compiler introduced the notion of ABI "tags", which + correspond to changes in the ABI of a type, function, or variable + that would not otherwise be reflected in a mangled name. See + + for more detail. + + The ABI tags are visible in C++ demangled names. For example, a + function that returns a std::string: + + std::string function(int); + + when compiled for the C++11 ABI is marked with the 'cxx11' ABI tag, + and GDB displays the symbol like this: + + function[abi:cxx11](int) + + You can set a breakpoint on such functions simply as if they had no + tag. For example: + + (gdb) b function(int) + Breakpoint 2 at 0x40060d: file main.cc, line 10. + (gdb) info breakpoints + Num Type Disp Enb Address What + 1 breakpoint keep y 0x0040060d in function[abi:cxx11](int) + at main.cc:10 + + On the rare occasion you need to disambiguate between different ABI + tags, you can do so by simply including the ABI tag in the function + name, like: + + (gdb) b ambiguous[abi:other_tag](int) + + +File: gdb.info, Node: Decimal Floating Point, Prev: Debugging C Plus Plus, Up: C + +15.4.1.8 Decimal Floating Point format +...................................... + +GDB can examine, set and perform computations with numbers in decimal +floating point format, which in the C language correspond to the +'_Decimal32', '_Decimal64' and '_Decimal128' types as specified by the +extension to support decimal floating-point arithmetic. + + There are two encodings in use, depending on the architecture: BID +(Binary Integer Decimal) for x86 and x86-64, and DPD (Densely Packed +Decimal) for PowerPC and S/390. GDB will use the appropriate encoding +for the configured target. + + Because of a limitation in 'libdecnumber', the library used by GDB to +manipulate decimal floating point numbers, it is not possible to convert +(using a cast, for example) integers wider than 32-bit to decimal float. + + In addition, in order to imitate GDB's behavior with binary floating +point computations, error checking in decimal float operations ignores +underflow, overflow and divide by zero exceptions. + + In the PowerPC architecture, GDB provides a set of pseudo-registers +to inspect '_Decimal128' values stored in floating point registers. See +*note PowerPC: PowerPC. for more details. + + +File: gdb.info, Node: D, Next: Go, Prev: C, Up: Supported Languages + +15.4.2 D +-------- + +GDB can be used to debug programs written in D and compiled with GDC, +LDC or DMD compilers. Currently GDB supports only one D specific +feature -- dynamic arrays. + + +File: gdb.info, Node: Go, Next: Objective-C, Prev: D, Up: Supported Languages + +15.4.3 Go +--------- + +GDB can be used to debug programs written in Go and compiled with +'gccgo' or '6g' compilers. + + Here is a summary of the Go-specific features and restrictions: + +'The current Go package' + The name of the current package does not need to be specified when + specifying global variables and functions. + + For example, given the program: + + package main + var myglob = "Shall we?" + func main () { + // ... + } + + When stopped inside 'main' either of these work: + + (gdb) p myglob + (gdb) p main.myglob + +'Builtin Go types' + The 'string' type is recognized by GDB and is printed as a string. + +'Builtin Go functions' + The GDB expression parser recognizes the 'unsafe.Sizeof' function + and handles it internally. + +'Restrictions on Go expressions' + All Go operators are supported except '&^'. The Go '_' "blank + identifier" is not supported. Automatic dereferencing of pointers + is not supported. + + +File: gdb.info, Node: Objective-C, Next: OpenCL C, Prev: Go, Up: Supported Languages + +15.4.4 Objective-C +------------------ + +This section provides information about some commands and command +options that are useful for debugging Objective-C code. See also *note +info classes: Symbols, and *note info selectors: Symbols, for a few more +commands specific to Objective-C support. + +* Menu: + +* Method Names in Commands:: +* The Print Command with Objective-C:: + + +File: gdb.info, Node: Method Names in Commands, Next: The Print Command with Objective-C, Up: Objective-C + +15.4.4.1 Method Names in Commands +................................. + +The following commands have been extended to accept Objective-C method +names as line specifications: + + * 'clear' + * 'break' + * 'info line' + * 'jump' + * 'list' + + A fully qualified Objective-C method name is specified as + + -[CLASS METHODNAME] + + where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name CLASS and method name METHODNAME are enclosed in brackets, similar +to the way messages are specified in Objective-C source code. For +example, to set a breakpoint at the 'create' instance method of class +'Fruit' in the program currently being debugged, enter: + + break -[Fruit create] + + To list ten program lines around the 'initialize' class method, +enter: + + list +[NSText initialize] + + In the current version of GDB, the plus or minus sign is required. +In future versions of GDB, the plus or minus sign will be optional, but +you can use it to narrow the search. It is also possible to specify +just a method name: + + break create + + You must specify the complete method name, including any colons. If +your program's source files contain more than one 'create' method, +you'll be presented with a numbered list of classes that implement that +method. Indicate your choice by number, or type '0' to exit if none +apply. + + As another example, to clear a breakpoint established at the +'makeKeyAndOrderFront:' method of the 'NSWindow' class, enter: + + clear -[NSWindow makeKeyAndOrderFront:] + + +File: gdb.info, Node: The Print Command with Objective-C, Prev: Method Names in Commands, Up: Objective-C + +15.4.4.2 The Print Command With Objective-C +........................................... + +The print command has also been extended to accept methods. For +example: + + print -[OBJECT hash] + +will tell GDB to send the 'hash' message to OBJECT and print the result. +Also, an additional command has been added, 'print-object' or 'po' for +short, which is meant to print the description of an object. However, +this command may only work with certain Objective-C libraries that have +a particular hook function, '_NSPrintForDebugger', defined. + + +File: gdb.info, Node: OpenCL C, Next: Fortran, Prev: Objective-C, Up: Supported Languages + +15.4.5 OpenCL C +--------------- + +This section provides information about GDBs OpenCL C support. + +* Menu: + +* OpenCL C Datatypes:: +* OpenCL C Expressions:: +* OpenCL C Operators:: + + +File: gdb.info, Node: OpenCL C Datatypes, Next: OpenCL C Expressions, Up: OpenCL C + +15.4.5.1 OpenCL C Datatypes +........................... + +GDB supports the builtin scalar and vector datatypes specified by OpenCL +1.1. In addition the half- and double-precision floating point data +types of the 'cl_khr_fp16' and 'cl_khr_fp64' OpenCL extensions are also +known to GDB. + + +File: gdb.info, Node: OpenCL C Expressions, Next: OpenCL C Operators, Prev: OpenCL C Datatypes, Up: OpenCL C + +15.4.5.2 OpenCL C Expressions +............................. + +GDB supports accesses to vector components including the access as +lvalue where possible. Since OpenCL C is based on C99 most C +expressions supported by GDB can be used as well. + + +File: gdb.info, Node: OpenCL C Operators, Prev: OpenCL C Expressions, Up: OpenCL C + +15.4.5.3 OpenCL C Operators +........................... + +GDB supports the operators specified by OpenCL 1.1 for scalar and vector +data types. + + +File: gdb.info, Node: Fortran, Next: Pascal, Prev: OpenCL C, Up: Supported Languages + +15.4.6 Fortran +-------------- + +GDB can be used to debug programs written in Fortran. Note, that not +all Fortran language features are available yet. + + Some Fortran compilers (GNU Fortran 77 and Fortran 95 compilers among +them) append an underscore to the names of variables and functions. +When you debug programs compiled by those compilers, you will need to +refer to variables and functions with a trailing underscore. + + Fortran symbols are usually case-insensitive, so GDB by default uses +case-insensitive matching for Fortran symbols. You can change that with +the 'set case-insensitive' command, see *note Symbols::, for the +details. + +* Menu: + +* Fortran Types:: Fortran builtin types +* Fortran Operators:: Fortran operators and expressions +* Fortran Intrinsics:: Fortran intrinsic functions +* Special Fortran Commands:: Special GDB commands for Fortran + + +File: gdb.info, Node: Fortran Types, Next: Fortran Operators, Up: Fortran + +15.4.6.1 Fortran Types +...................... + +In Fortran the primitive data-types have an associated 'KIND' type +parameter, written as 'TYPE*KINDPARAM', 'TYPE*KINDPARAM', or in the +GDB-only dialect 'TYPE_KINDPARAM'. A concrete example would be +''Real*4'', ''Real(kind=4)'', and ''Real_4''. The kind of a type can be +retrieved by using the intrinsic function 'KIND', see *note Fortran +Intrinsics::. + + Generally, the actual implementation of the 'KIND' type parameter is +compiler specific. In GDB the kind parameter is implemented in +accordance with its use in the GNU 'gfortran' compiler. Here, the kind +parameter for a given TYPE specifies its size in memory -- a Fortran +'Integer*4' or 'Integer(kind=4)' would be an integer type occupying 4 +bytes of memory. An exception to this rule is the 'Complex' type for +which the kind of the type does not specify its entire size, but the +size of each of the two 'Real''s it is composed of. A 'Complex*4' would +thus consist of two 'Real*4's and occupy 8 bytes of memory. + + For every type there is also a default kind associated with it, +e.g. 'Integer' in GDB will internally be an 'Integer*4' (see the table +below for default types). The default types are the same as in GNU +compilers but note, that the GNU default types can actually be changed +by compiler flags such as '-fdefault-integer-8' and '-fdefault-real-8'. + + Not every kind parameter is valid for every type and in GDB the +following type kinds are available. + +'Integer' + 'Integer*1', 'Integer*2', 'Integer*4', 'Integer*8', and 'Integer' = + 'Integer*4'. + +'Logical' + 'Logical*1', 'Logical*2', 'Logical*4', 'Logical*8', and 'Logical' = + 'Logical*4'. + +'Real' + 'Real*4', 'Real*8', 'Real*16', and 'Real' = 'Real*4'. + +'Complex' + 'Complex*4', 'Complex*8', 'Complex*16', and 'Complex' = + 'Complex*4'. + + +File: gdb.info, Node: Fortran Operators, Next: Fortran Intrinsics, Prev: Fortran Types, Up: Fortran + +15.4.6.2 Fortran Operators and Expressions +.......................................... + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on characters or other non- +arithmetic types. Operators are often defined on groups of types. + +'**' + The exponentiation operator. It raises the first operand to the + power of the second one. + +':' + The range operator. Normally used in the form of array(low:high) + to represent a section of array. + +'%' + The access component operator. Normally used to access elements in + derived types. Also suitable for unions. As unions aren't part of + regular Fortran, this can only happen when accessing a register + that uses a gdbarch-defined union type. +'::' + The scope operator. Normally used to access variables in modules + or to set breakpoints on subroutines nested in modules or in other + subroutines (internal subroutines). + + +File: gdb.info, Node: Fortran Intrinsics, Next: Special Fortran Commands, Prev: Fortran Operators, Up: Fortran + +15.4.6.3 Fortran Intrinsics +........................... + +Fortran provides a large set of intrinsic procedures. GDB implements an +incomplete subset of those procedures and their overloads. Some of +these procedures take an optional 'KIND' parameter, see *note Fortran +Types::. + +'ABS(A)' + Computes the absolute value of its argument A. Currently not + supported for 'Complex' arguments. + +'ALLOCATE(ARRAY)' + Returns whether ARRAY is allocated or not. + +'ASSOCIATED(POINTER [, TARGET])' + Returns the association status of the pointer POINTER or, if TARGET + is present, whether POINTER is associated with the target TARGET. + +'CEILING(A [, KIND])' + Computes the least integer greater than or equal to A. The + optional parameter KIND specifies the kind of the return type + 'Integer(KIND)'. + +'CMPLX(X [, Y [, KIND]])' + Returns a complex number where X is converted to the real + component. If Y is present it is converted to the imaginary + component. If Y is not present then the imaginary component is set + to '0.0' except if X itself is of 'Complex' type. The optional + parameter KIND specifies the kind of the return type + 'Complex(KIND)'. + +'FLOOR(A [, KIND])' + Computes the greatest integer less than or equal to A. The + optional parameter KIND specifies the kind of the return type + 'Integer(KIND)'. + +'KIND(A)' + Returns the kind value of the argument A, see *note Fortran + Types::. + +'LBOUND(ARRAY [, DIM [, KIND]])' + Returns the lower bounds of an ARRAY, or a single lower bound along + the DIM dimension if present. The optional parameter KIND + specifies the kind of the return type 'Integer(KIND)'. + +'LOC(X)' + Returns the address of X as an 'Integer'. + +'MOD(A, P)' + Computes the remainder of the division of A by P. + +'MODULO(A, P)' + Computes the A modulo P. + +'RANK(A)' + Returns the rank of a scalar or array (scalars have rank '0'). + +'SHAPE(A)' + Returns the shape of a scalar or array (scalars have shape '()'). + +'SIZE(ARRAY[, DIM [, KIND]])' + Returns the extent of ARRAY along a specified dimension DIM, or the + total number of elements in ARRAY if DIM is absent. The optional + parameter KIND specifies the kind of the return type + 'Integer(KIND)'. + +'UBOUND(ARRAY [, DIM [, KIND]])' + Returns the upper bounds of an ARRAY, or a single upper bound along + the DIM dimension if present. The optional parameter KIND + specifies the kind of the return type 'Integer(KIND)'. + + +File: gdb.info, Node: Special Fortran Commands, Prev: Fortran Intrinsics, Up: Fortran + +15.4.6.4 Special Fortran Commands +................................. + +GDB has some commands to support Fortran-specific features, such as +displaying common blocks. + +'info common [COMMON-NAME]' + This command prints the values contained in the Fortran 'COMMON' + block whose name is COMMON-NAME. With no argument, the names of + all 'COMMON' blocks visible at the current program location are + printed. +'set fortran repack-array-slices [on|off]' +'show fortran repack-array-slices' + When taking a slice from an array, a Fortran compiler can choose to + either produce an array descriptor that describes the slice in + place, or it may repack the slice, copying the elements of the + slice into a new region of memory. + + When this setting is on, then GDB will also repack array slices in + some situations. When this setting is off, then GDB will create + array descriptors for slices that reference the original data in + place. + + GDB will never repack an array slice if the data for the slice is + contiguous within the original array. + + GDB will always repack string slices if the data for the slice is + non-contiguous within the original string as GDB does not support + printing non-contiguous strings. + + The default for this setting is 'off'. + + +File: gdb.info, Node: Pascal, Next: Rust, Prev: Fortran, Up: Supported Languages + +15.4.7 Pascal +------------- + +Debugging Pascal programs which use sets, subranges, file variables, or +nested functions does not currently work. GDB does not support entering +expressions, printing values, or similar features using Pascal syntax. + + The Pascal-specific command 'set print pascal_static-members' +controls whether static members of Pascal objects are displayed. *Note +pascal_static-members: Print Settings. + + +File: gdb.info, Node: Rust, Next: Modula-2, Prev: Pascal, Up: Supported Languages + +15.4.8 Rust +----------- + +GDB supports the Rust Programming Language (https://www.rust-lang.org/). +Type- and value-printing, and expression parsing, are reasonably +complete. However, there are a few peculiarities and holes to be aware +of. + + * Linespecs (*note Location Specifications::) are never relative to + the current crate. Instead, they act as if there were a global + namespace of crates, somewhat similar to the way 'extern crate' + behaves. + + That is, if GDB is stopped at a breakpoint in a function in crate + 'A', module 'B', then 'break B::f' will attempt to set a breakpoint + in a function named 'f' in a crate named 'B'. + + As a consequence of this approach, linespecs also cannot refer to + items using 'self::' or 'super::'. + + * Because GDB implements Rust name-lookup semantics in expressions, + it will sometimes prepend the current crate to a name. For + example, if GDB is stopped at a breakpoint in the crate 'K', then + 'print ::x::y' will try to find the symbol 'K::x::y'. + + However, since it is useful to be able to refer to other crates + when debugging, GDB provides the 'extern' extension to circumvent + this. To use the extension, just put 'extern' before a path + expression to refer to the otherwise unavailable "global" scope. + + In the above example, if you wanted to refer to the symbol 'y' in + the crate 'x', you would use 'print extern x::y'. + + * The Rust expression evaluator does not support "statement-like" + expressions such as 'if' or 'match', or lambda expressions. + + * Tuple expressions are not implemented. + + * The Rust expression evaluator does not currently implement the + 'Drop' trait. Objects that may be created by the evaluator will + never be destroyed. + + * GDB does not implement type inference for generics. In order to + call generic functions or otherwise refer to generic items, you + will have to specify the type parameters manually. + + * GDB currently uses the C++ demangler for Rust. In most cases this + does not cause any problems. However, in an expression context, + completing a generic function name will give syntactically invalid + results. This happens because Rust requires the '::' operator + between the function name and its generic arguments. For example, + GDB might provide a completion like 'crate::f', where the + parser would require 'crate::f::'. + + * As of this writing, the Rust compiler (version 1.8) has a few holes + in the debugging information it generates. These holes prevent + certain features from being implemented by GDB: + + * Method calls cannot be made via traits. + + * Operator overloading is not implemented. + + * When debugging in a monomorphized function, you cannot use the + generic type names. + + * The type 'Self' is not available. + + * 'use' statements are not available, so some names may not be + available in the crate. + + +File: gdb.info, Node: Modula-2, Next: Ada, Prev: Rust, Up: Supported Languages + +15.4.9 Modula-2 +--------------- + +The extensions made to GDB to support Modula-2 only support output from +the GNU Modula-2 compiler (which is currently being developed). Other +Modula-2 compilers are not currently supported, and attempting to debug +executables produced by them is most likely to give an error as GDB +reads in the executable's symbol table. + +* Menu: + +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Types:: Modula-2 types +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators '::' and '.' +* GDB/M2:: GDB and Modula-2 + + +File: gdb.info, Node: M2 Operators, Next: Built-In Func/Proc, Up: Modula-2 + +15.4.9.1 Operators +.................. + +Operators must be defined on values of specific types. For instance, +'+' is defined on numbers, but not on structures. Operators are often +defined on groups of types. For the purposes of Modula-2, the following +definitions hold: + + * _Integral types_ consist of 'INTEGER', 'CARDINAL', and their + subranges. + + * _Character types_ consist of 'CHAR' and its subranges. + + * _Floating-point types_ consist of 'REAL'. + + * _Pointer types_ consist of anything declared as 'POINTER TO TYPE'. + + * _Scalar types_ consist of all of the above. + + * _Set types_ consist of 'SET' and 'BITSET' types. + + * _Boolean types_ consist of 'BOOLEAN'. + +The following operators are supported, and appear in order of increasing +precedence: + +',' + Function argument or array index separator. + +':=' + Assignment. The value of VAR ':=' VALUE is VALUE. + +'<, >' + Less than, greater than on integral, floating-point, or enumerated + types. + +'<=, >=' + Less than or equal to, greater than or equal to on integral, + floating-point and enumerated types, or set inclusion on set types. + Same precedence as '<'. + +'=, <>, #' + Equality and two ways of expressing inequality, valid on scalar + types. Same precedence as '<'. In GDB scripts, only '<>' is + available for inequality, since '#' conflicts with the script + comment character. + +'IN' + Set membership. Defined on set types and the types of their + members. Same precedence as '<'. + +'OR' + Boolean disjunction. Defined on boolean types. + +'AND, &' + Boolean conjunction. Defined on boolean types. + +'@' + The GDB "artificial array" operator (*note Expressions: + Expressions.). + +'+, -' + Addition and subtraction on integral and floating-point types, or + union and difference on set types. + +'*' + Multiplication on integral and floating-point types, or set + intersection on set types. + +'/' + Division on floating-point types, or symmetric set difference on + set types. Same precedence as '*'. + +'DIV, MOD' + Integer division and remainder. Defined on integral types. Same + precedence as '*'. + +'-' + Negative. Defined on 'INTEGER' and 'REAL' data. + +'^' + Pointer dereferencing. Defined on pointer types. + +'NOT' + Boolean negation. Defined on boolean types. Same precedence as + '^'. + +'.' + 'RECORD' field selector. Defined on 'RECORD' data. Same + precedence as '^'. + +'[]' + Array indexing. Defined on 'ARRAY' data. Same precedence as '^'. + +'()' + Procedure argument list. Defined on 'PROCEDURE' objects. Same + precedence as '^'. + +'::, .' + GDB and Modula-2 scope operators. + + _Warning:_ Set expressions and their operations are not yet + supported, so GDB treats the use of the operator 'IN', or the use + of operators '+', '-', '*', '/', '=', , '<>', '#', '<=', and '>=' + on sets as an error. + + +File: gdb.info, Node: Built-In Func/Proc, Next: M2 Constants, Prev: M2 Operators, Up: Modula-2 + +15.4.9.2 Built-in Functions and Procedures +.......................................... + +Modula-2 also makes available several built-in procedures and functions. +In describing these, the following metavariables are used: + +A + represents an 'ARRAY' variable. + +C + represents a 'CHAR' constant or variable. + +I + represents a variable or constant of integral type. + +M + represents an identifier that belongs to a set. Generally used in + the same function with the metavariable S. The type of S should be + 'SET OF MTYPE' (where MTYPE is the type of M). + +N + represents a variable or constant of integral or floating-point + type. + +R + represents a variable or constant of floating-point type. + +T + represents a type. + +V + represents a variable. + +X + represents a variable or constant of one of many types. See the + explanation of the function for details. + + All Modula-2 built-in procedures also return a result, described +below. + +'ABS(N)' + Returns the absolute value of N. + +'ADR(N)' + Returns the memory address of N. + +'CAP(C)' + If C is a lower case letter, it returns its upper case equivalent, + otherwise it returns its argument. + +'CHR(I)' + Returns the character whose ordinal value is I. + +'DEC(V)' + Decrements the value in the variable V by one. Returns the new + value. + +'DEC(V,I)' + Decrements the value in the variable V by I. Returns the new + value. + +'EXCL(M,S)' + Removes the element M from the set S. Returns the new set. + +'FLOAT(I)' + Returns the floating point equivalent of the integer I. + +'HIGH(A)' + Returns the index of the last member of A. + +'INC(V)' + Increments the value in the variable V by one. Returns the new + value. + +'INC(V,I)' + Increments the value in the variable V by I. Returns the new + value. + +'INCL(M,S)' + Adds the element M to the set S if it is not already there. + Returns the new set. + +'MAX(T)' + Returns the maximum value of the type T. + +'MIN(T)' + Returns the minimum value of the type T. + +'ODD(I)' + Returns boolean TRUE if I is an odd number. + +'ORD(X)' + Returns the ordinal value of its argument. For example, the + ordinal value of a character is its ASCII value (on machines + supporting the ASCII character set). The argument X must be of an + ordered type, which include integral, character and enumerated + types. + +'SIZE(X)' + Returns the size of its argument. The argument X can be a variable + or a type. + +'TRUNC(R)' + Returns the integral part of R. + +'TSIZE(X)' + Returns the size of its argument. The argument X can be a variable + or a type. + +'VAL(T,I)' + Returns the member of the type T whose ordinal value is I. + + _Warning:_ Sets and their operations are not yet supported, so GDB + treats the use of procedures 'INCL' and 'EXCL' as an error. + + +File: gdb.info, Node: M2 Constants, Next: M2 Types, Prev: Built-In Func/Proc, Up: Modula-2 + +15.4.9.3 Constants +.................. + +GDB allows you to express the constants of Modula-2 in the following +ways: + + * Integer constants are simply a sequence of digits. When used in an + expression, a constant is interpreted to be type-compatible with + the rest of the expression. Hexadecimal integers are specified by + a trailing 'H', and octal integers by a trailing 'B'. + + * Floating point constants appear as a sequence of digits, followed + by a decimal point and another sequence of digits. An optional + exponent can then be specified, in the form 'E[+|-]NNN', where + '[+|-]NNN' is the desired exponent. All of the digits of the + floating point constant must be valid decimal (base 10) digits. + + * Character constants consist of a single character enclosed by a + pair of like quotes, either single (''') or double ('"'). They may + also be expressed by their ordinal value (their ASCII value, + usually) followed by a 'C'. + + * String constants consist of a sequence of characters enclosed by a + pair of like quotes, either single (''') or double ('"'). Escape + sequences in the style of C are also allowed. *Note C and C++ + Constants: C Constants, for a brief explanation of escape + sequences. + + * Enumerated constants consist of an enumerated identifier. + + * Boolean constants consist of the identifiers 'TRUE' and 'FALSE'. + + * Pointer constants consist of integral values only. + + * Set constants are not yet supported. + + +File: gdb.info, Node: M2 Types, Next: M2 Defaults, Prev: M2 Constants, Up: Modula-2 + +15.4.9.4 Modula-2 Types +....................... + +Currently GDB can print the following data types in Modula-2 syntax: +array types, record types, set types, pointer types, procedure types, +enumerated types, subrange types and base types. You can also print the +contents of variables declared using these type. This section gives a +number of simple source code examples together with sample GDB sessions. + + The first example contains the following section of code: + + VAR + s: SET OF CHAR ; + r: [20..40] ; + +and you can request GDB to interrogate the type and value of 'r' and +'s'. + + (gdb) print s + {'A'..'C', 'Z'} + (gdb) ptype s + SET OF CHAR + (gdb) print r + 21 + (gdb) ptype r + [20..40] + +Likewise if your source code declares 's' as: + + VAR + s: SET ['A'..'Z'] ; + +then you may query the type of 's' by: + + (gdb) ptype s + type = SET ['A'..'Z'] + +Note that at present you cannot interactively manipulate set expressions +using the debugger. + + The following example shows how you might declare an array in +Modula-2 and how you can interact with GDB to print its type and +contents: + + VAR + s: ARRAY [-10..10] OF CHAR ; + + (gdb) ptype s + ARRAY [-10..10] OF CHAR + + Note that the array handling is not yet complete and although the +type is printed correctly, expression handling still assumes that all +arrays have a lower bound of zero and not '-10' as in the example above. + + Here are some more type related Modula-2 examples: + + TYPE + colour = (blue, red, yellow, green) ; + t = [blue..yellow] ; + VAR + s: t ; + BEGIN + s := blue ; + +The GDB interaction shows how you can query the data type and value of a +variable. + + (gdb) print s + $1 = blue + (gdb) ptype t + type = [blue..yellow] + +In this example a Modula-2 array is declared and its contents displayed. +Observe that the contents are written in the same way as their 'C' +counterparts. + + VAR + s: ARRAY [1..5] OF CARDINAL ; + BEGIN + s[1] := 1 ; + + (gdb) print s + $1 = {1, 0, 0, 0, 0} + (gdb) ptype s + type = ARRAY [1..5] OF CARDINAL + + The Modula-2 language interface to GDB also understands pointer types +as shown in this example: + + VAR + s: POINTER TO ARRAY [1..5] OF CARDINAL ; + BEGIN + NEW(s) ; + s^[1] := 1 ; + +and you can request that GDB describes the type of 's'. + + (gdb) ptype s + type = POINTER TO ARRAY [1..5] OF CARDINAL + + GDB handles compound types as we can see in this example. Here we +combine array types, record types, pointer types and subrange types: + + TYPE + foo = RECORD + f1: CARDINAL ; + f2: CHAR ; + f3: myarray ; + END ; + + myarray = ARRAY myrange OF CARDINAL ; + myrange = [-2..2] ; + VAR + s: POINTER TO ARRAY myrange OF foo ; + +and you can ask GDB to describe the type of 's' as shown below. + + (gdb) ptype s + type = POINTER TO ARRAY [-2..2] OF foo = RECORD + f1 : CARDINAL; + f2 : CHAR; + f3 : ARRAY [-2..2] OF CARDINAL; + END + + +File: gdb.info, Node: M2 Defaults, Next: Deviations, Prev: M2 Types, Up: Modula-2 + +15.4.9.5 Modula-2 Defaults +.......................... + +If type and range checking are set automatically by GDB, they both +default to 'on' whenever the working language changes to Modula-2. This +happens regardless of whether you or GDB selected the working language. + + If you allow GDB to set the language automatically, then entering +code compiled from a file whose name ends with '.mod' sets the working +language to Modula-2. *Note Having GDB Infer the Source Language: +Automatically, for further details. + + +File: gdb.info, Node: Deviations, Next: M2 Checks, Prev: M2 Defaults, Up: Modula-2 + +15.4.9.6 Deviations from Standard Modula-2 +.......................................... + +A few changes have been made to make Modula-2 programs easier to debug. +This is done primarily via loosening its type strictness: + + * Unlike in standard Modula-2, pointer constants can be formed by + integers. This allows you to modify pointer variables during + debugging. (In standard Modula-2, the actual address contained in + a pointer variable is hidden from you; it can only be modified + through direct assignment to another pointer variable or expression + that returned a pointer.) + + * C escape sequences can be used in strings and characters to + represent non-printable characters. GDB prints out strings with + these escape sequences embedded. Single non-printable characters + are printed using the 'CHR(NNN)' format. + + * The assignment operator (':=') returns the value of its right-hand + argument. + + * All built-in procedures both modify _and_ return their argument. + + +File: gdb.info, Node: M2 Checks, Next: M2 Scope, Prev: Deviations, Up: Modula-2 + +15.4.9.7 Modula-2 Type and Range Checks +....................................... + + _Warning:_ in this release, GDB does not yet perform type or range + checking. + + GDB considers two Modula-2 variables type equivalent if: + + * They are of types that have been declared equivalent via a 'TYPE T1 + = T2' statement + + * They have been declared on the same line. (Note: This is true of + the GNU Modula-2 compiler, but it may not be true of other + compilers.) + + As long as type checking is enabled, any attempt to combine variables +whose types are not equivalent is an error. + + Range checking is done on all mathematical operations, assignment, +array index bounds, and all built-in functions and procedures. + + +File: gdb.info, Node: M2 Scope, Next: GDB/M2, Prev: M2 Checks, Up: Modula-2 + +15.4.9.8 The Scope Operators '::' and '.' +......................................... + +There are a few subtle differences between the Modula-2 scope operator +('.') and the GDB scope operator ('::'). The two have similar syntax: + + + MODULE . ID + SCOPE :: ID + +where SCOPE is the name of a module or a procedure, MODULE the name of a +module, and ID is any declared identifier within your program, except +another module. + + Using the '::' operator makes GDB search the scope specified by SCOPE +for the identifier ID. If it is not found in the specified scope, then +GDB searches all scopes enclosing the one specified by SCOPE. + + Using the '.' operator makes GDB search the current scope for the +identifier specified by ID that was imported from the definition module +specified by MODULE. With this operator, it is an error if the +identifier ID was not imported from definition module MODULE, or if ID +is not an identifier in MODULE. + + +File: gdb.info, Node: GDB/M2, Prev: M2 Scope, Up: Modula-2 + +15.4.9.9 GDB and Modula-2 +......................... + +Some GDB commands have little use when debugging Modula-2 programs. +Five subcommands of 'set print' and 'show print' apply specifically to C +and C++: 'vtbl', 'demangle', 'asm-demangle', 'object', and 'union'. The +first four apply to C++, and the last to the C 'union' type, which has +no direct analogue in Modula-2. + + The '@' operator (*note Expressions: Expressions.), while available +with any language, is not useful with Modula-2. Its intent is to aid +the debugging of "dynamic arrays", which cannot be created in Modula-2 +as they can in C or C++. However, because an address can be specified +by an integral constant, the construct '{TYPE}ADREXP' is still useful. + + In GDB scripts, the Modula-2 inequality operator '#' is interpreted +as the beginning of a comment. Use '<>' instead. + + +File: gdb.info, Node: Ada, Prev: Modula-2, Up: Supported Languages + +15.4.10 Ada +----------- + +The extensions made to GDB for Ada only support output from the GNU Ada +(GNAT) compiler. Other Ada compilers are not currently supported, and +attempting to debug executables produced by them is most likely to be +difficult. + +* Menu: + +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode + in GDB. +* Omissions from Ada:: Restrictions on the Ada expression syntax. +* Additions to Ada:: Extensions of the Ada expression syntax. +* Overloading support for Ada:: Support for expressions involving overloaded + subprograms. +* Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Exceptions:: Ada Exceptions +* Ada Tasks:: Listing and setting breakpoints in tasks. +* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files +* Ravenscar Profile:: Tasking Support when using the Ravenscar + Profile +* Ada Source Character Set:: Character set of Ada source files. +* Ada Glitches:: Known peculiarities of Ada mode. + + +File: gdb.info, Node: Ada Mode Intro, Next: Omissions from Ada, Up: Ada + +15.4.10.1 Introduction +...................... + +The Ada mode of GDB supports a fairly large subset of Ada expression +syntax, with some extensions. The philosophy behind the design of this +subset is + + * That GDB should provide basic literals and access to operations for + arithmetic, dereferencing, field selection, indexing, and + subprogram calls, leaving more sophisticated computations to + subprograms written into the program (which therefore may be called + from GDB). + + * That type safety and strict adherence to Ada language restrictions + are not particularly important to the GDB user. + + * That brevity is important to the GDB user. + + Thus, for brevity, the debugger acts as if all names declared in +user-written packages are directly visible, even if they are not visible +according to Ada rules, thus making it unnecessary to fully qualify most +names with their packages, regardless of context. Where this causes +ambiguity, GDB asks the user's intent. + + The debugger will start in Ada mode if it detects an Ada main +program. As for other languages, it will enter Ada mode when stopped in +a program that was translated from an Ada source file. + + While in Ada mode, you may use '--' for comments. This is useful +mostly for documenting command files. The standard GDB comment ('#') +still works at the beginning of a line in Ada mode, but not in the +middle (to allow based literals). + + +File: gdb.info, Node: Omissions from Ada, Next: Additions to Ada, Prev: Ada Mode Intro, Up: Ada + +15.4.10.2 Omissions from Ada +............................ + +Here are the notable omissions from the subset: + + * Only a subset of the attributes are supported: + + - 'First, 'Last, and 'Length on array objects (not on types and + subtypes). + + - 'Min and 'Max. + + - 'Pos and 'Val. + + - 'Tag. + + - 'Range on array objects (not subtypes), but only as the right + operand of the membership ('in') operator. + + - 'Access, 'Unchecked_Access, and 'Unrestricted_Access (a GNAT + extension). + + - 'Address. + + - 'Size is available for objects (not types). + + - 'Object_Size is available, but not for indefinite types. + + * The names in 'Characters.Latin_1' are not available. + + * Equality tests ('=' and '/=') on arrays test for bitwise equality + of representations. They will generally work correctly for strings + and arrays whose elements have integer or enumeration types. They + may not work correctly for arrays whose element types have + user-defined equality, for arrays of real values (in particular, + IEEE-conformant floating point, because of negative zeroes and + NaNs), and for arrays whose elements contain unused bits with + indeterminate values. + + * The other component-by-component array operations ('and', 'or', + 'xor', 'not', and relational tests other than equality) are not + implemented. + + * There is limited support for array and record aggregates. They are + permitted only on the right sides of assignments, as in these + examples: + + (gdb) set An_Array := (1, 2, 3, 4, 5, 6) + (gdb) set An_Array := (1, others => 0) + (gdb) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) + (gdb) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) + (gdb) set A_Record := (1, "Peter", True); + (gdb) set A_Record := (Name => "Peter", Id => 1, Alive => True) + + Changing a discriminant's value by assigning an aggregate has an + undefined effect if that discriminant is used within the record. + However, you can first modify discriminants by directly assigning + to them (which normally would not be allowed in Ada), and then + performing an aggregate assignment. For example, given a variable + 'A_Rec' declared to have a type such as: + + type Rec (Len : Small_Integer := 0) is record + Id : Integer; + Vals : IntArray (1 .. Len); + end record; + + you can assign a value with a different size of 'Vals' with two + assignments: + + (gdb) set A_Rec.Len := 4 + (gdb) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) + + As this example also illustrates, GDB is very loose about the usual + rules concerning aggregates. You may leave out some of the + components of an array or record aggregate (such as the 'Len' + component in the assignment to 'A_Rec' above); they will retain + their original values upon assignment. You may freely use dynamic + values as indices in component associations. You may even use + overlapping or redundant component associations, although which + component values are assigned in such cases is not defined. + + * Calls to dispatching subprograms are not implemented. + + * The overloading algorithm is much more limited (i.e., less + selective) than that of real Ada. It makes only limited use of the + context in which a subexpression appears to resolve its meaning, + and it is much looser in its rules for allowing type matches. As a + result, some function calls will be ambiguous, and the user will be + asked to choose the proper resolution. + + * The 'new' operator is not implemented. + + * Entry calls are not implemented. + + * Aside from printing, arithmetic operations on the native VAX + floating-point formats are not supported. + + * It is not possible to slice a packed array. + + * The names 'True' and 'False', when not part of a qualified name, + are interpreted as if implicitly prefixed by 'Standard', regardless + of context. Should your program redefine these names in a package + or procedure (at best a dubious practice), you will have to use + fully qualified names to access their new definitions. + + * Based real literals are not implemented. + + +File: gdb.info, Node: Additions to Ada, Next: Overloading support for Ada, Prev: Omissions from Ada, Up: Ada + +15.4.10.3 Additions to Ada +.......................... + +As it does for other languages, GDB makes certain generic extensions to +Ada (*note Expressions::): + + * If the expression E is a variable residing in memory (typically a + local variable or array element) and N is a positive integer, then + 'E@N' displays the values of E and the N-1 adjacent variables + following it in memory as an array. In Ada, this operator is + generally not necessary, since its prime use is in displaying parts + of an array, and slicing will usually do this in Ada. However, + there are occasional uses when debugging programs in which certain + debugging information has been optimized away. + + * 'B::VAR' means "the variable named VAR that appears in function or + file B." When B is a file name, you must typically surround it in + single quotes. + + * The expression '{TYPE} ADDR' means "the variable of type TYPE that + appears at address ADDR." + + * A name starting with '$' is a convenience variable (*note + Convenience Vars::) or a machine register (*note Registers::). + + In addition, GDB provides a few other shortcuts and outright +additions specific to Ada: + + * The assignment statement is allowed as an expression, returning its + right-hand operand as its value. Thus, you may enter + + (gdb) set x := y + 3 + (gdb) print A(tmp := y + 1) + + * The semicolon is allowed as an "operator," returning as its value + the value of its right-hand operand. This allows, for example, + complex conditional breaks: + + (gdb) break f + (gdb) condition 1 (report(i); k += 1; A(k) > 100) + + * An extension to based literals can be used to specify the exact + byte contents of a floating-point literal. After the base, you can + use from zero to two 'l' characters, followed by an 'f'. The + number of 'l' characters controls the width of the resulting real + constant: zero means 'Float' is used, one means 'Long_Float', and + two means 'Long_Long_Float'. + + (gdb) print 16f#41b80000# + $1 = 23.0 + + * Rather than use catenation and symbolic character names to + introduce special characters into strings, one may instead use a + special bracket notation, which is also used to print strings. A + sequence of characters of the form '["XX"]' within a string or + character literal denotes the (single) character whose numeric + encoding is XX in hexadecimal. The sequence of characters '["""]' + also denotes a single quotation mark in strings. For example, + "One line.["0a"]Next line.["0a"]" + contains an ASCII newline character ('Ada.Characters.Latin_1.LF') + after each period. + + * The subtype used as a prefix for the attributes 'Pos, 'Min, and + 'Max is optional (and is ignored in any case). For example, it is + valid to write + + (gdb) print 'max(x, y) + + * When printing arrays, GDB uses positional notation when the array + has a lower bound of 1, and uses a modified named notation + otherwise. For example, a one-dimensional array of three integers + with a lower bound of 3 might print as + + (3 => 10, 17, 1) + + That is, in contrast to valid Ada, only the first component has a + '=>' clause. + + * You may abbreviate attributes in expressions with any unique, + multi-character subsequence of their names (an exact match gets + preference). For example, you may use a'len, a'gth, or a'lh in + place of a'length. + + * Since Ada is case-insensitive, the debugger normally maps + identifiers you type to lower case. The GNAT compiler uses + upper-case characters for some of its internal identifiers, which + are normally of no interest to users. For the rare occasions when + you actually have to look at them, enclose them in angle brackets + to avoid the lower-case mapping. For example, + (gdb) print [0] + + * Printing an object of class-wide type or dereferencing an + access-to-class-wide value will display all the components of the + object's specific type (as indicated by its run-time tag). + Likewise, component selection on such a value will operate on the + specific type of the object. + + +File: gdb.info, Node: Overloading support for Ada, Next: Stopping Before Main Program, Prev: Additions to Ada, Up: Ada + +15.4.10.4 Overloading support for Ada +..................................... + +The debugger supports limited overloading. Given a subprogram call in +which the function symbol has multiple definitions, it will use the +number of actual parameters and some information about their types to +attempt to narrow the set of definitions. It also makes very limited +use of context, preferring procedures to functions in the context of the +'call' command, and functions to procedures elsewhere. + + If, after narrowing, the set of matching definitions still contains +more than one definition, GDB will display a menu to query which one it +should use, for instance: + + (gdb) print f(1) + Multiple matches for f + [0] cancel + [1] foo.f (integer) return boolean at foo.adb:23 + [2] foo.f (foo.new_integer) return boolean at foo.adb:28 + > + + In this case, just select one menu entry either to cancel expression +evaluation (type '0' and press ) or to continue evaluation with a +specific instance (type the corresponding number and press ). + + Here are a couple of commands to customize GDB's behavior in this +case: + +'set ada print-signatures' + Control whether parameter types and return types are displayed in + overloads selection menus. It is 'on' by default. *Note + Overloading support for Ada::. + +'show ada print-signatures' + Show the current setting for displaying parameter types and return + types in overloads selection menu. *Note Overloading support for + Ada::. + + +File: gdb.info, Node: Stopping Before Main Program, Next: Ada Exceptions, Prev: Overloading support for Ada, Up: Ada + +15.4.10.5 Stopping at the Very Beginning +........................................ + +It is sometimes necessary to debug the program during elaboration, and +before reaching the main procedure. As defined in the Ada Reference +Manual, the elaboration code is invoked from a procedure called +'adainit'. To run your program up to the beginning of elaboration, +simply use the following two commands: 'tbreak adainit' and 'run'. + + +File: gdb.info, Node: Ada Exceptions, Next: Ada Tasks, Prev: Stopping Before Main Program, Up: Ada + +15.4.10.6 Ada Exceptions +........................ + +A command is provided to list all Ada exceptions: + +'info exceptions' +'info exceptions REGEXP' + The 'info exceptions' command allows you to list all Ada exceptions + defined within the program being debugged, as well as their + addresses. With a regular expression, REGEXP, as argument, only + those exceptions whose names match REGEXP are listed. + + Below is a small example, showing how the command can be used, first +without argument, and next with a regular expression passed as an +argument. + + (gdb) info exceptions + All defined Ada exceptions: + constraint_error: 0x613da0 + program_error: 0x613d20 + storage_error: 0x613ce0 + tasking_error: 0x613ca0 + const.aint_global_e: 0x613b00 + (gdb) info exceptions const.aint + All Ada exceptions matching regular expression "const.aint": + constraint_error: 0x613da0 + const.aint_global_e: 0x613b00 + + It is also possible to ask GDB to stop your program's execution when +an exception is raised. For more details, see *note Set Catchpoints::. + + +File: gdb.info, Node: Ada Tasks, Next: Ada Tasks and Core Files, Prev: Ada Exceptions, Up: Ada + +15.4.10.7 Extensions for Ada Tasks +.................................. + +Support for Ada tasks is analogous to that for threads (*note +Threads::). GDB provides the following task-related commands: + +'info tasks' + This command shows a list of current Ada tasks, as in the following + example: + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8088000 0 15 Child Activation Wait main_task + 2 80a4000 1 15 Accept Statement b + 3 809a800 1 15 Child Activation Wait a + * 4 80ae800 3 15 Runnable c + + + In this listing, the asterisk before the last task indicates it to + be the task currently being inspected. + + ID + Represents GDB's internal task number. + + TID + The Ada task ID. + + P-ID + The parent's task ID (GDB's internal task number). + + Pri + The base priority of the task. + + State + Current state of the task. + + 'Unactivated' + The task has been created but has not been activated. It + cannot be executing. + + 'Runnable' + The task is not blocked for any reason known to Ada. (It + may be waiting for a mutex, though.) It is conceptually + "executing" in normal mode. + + 'Terminated' + The task is terminated, in the sense of ARM 9.3 (5). Any + dependents that were waiting on terminate alternatives + have been awakened and have terminated themselves. + + 'Child Activation Wait' + The task is waiting for created tasks to complete + activation. + + 'Accept or Select Term' + The task is waiting on an accept or selective wait + statement. + + 'Waiting on entry call' + The task is waiting on an entry call. + + 'Async Select Wait' + The task is waiting to start the abortable part of an + asynchronous select statement. + + 'Delay Sleep' + The task is waiting on a select statement with only a + delay alternative open. + + 'Child Termination Wait' + The task is sleeping having completed a master within + itself, and is waiting for the tasks dependent on that + master to become terminated or waiting on a terminate + Phase. + + 'Wait Child in Term Alt' + The task is sleeping waiting for tasks on terminate + alternatives to finish terminating. + + 'Asynchronous Hold' + The task has been held by + 'Ada.Asynchronous_Task_Control.Hold_Task'. + + 'Activating' + The task has been created and is being made runnable. + + 'Selective Wait' + The task is waiting in a selective wait statement. + + 'Accepting RV with TASKNO' + The task is accepting a rendez-vous with the task TASKNO. + + 'Waiting on RV with TASKNO' + The task is waiting for a rendez-vous with the task + TASKNO. + + Name + Name of the task in the program. + +'info task TASKNO' + This command shows detailed information on the specified task, as + in the following example: + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077880 0 15 Child Activation Wait main_task + * 2 807c468 1 15 Runnable task_1 + (gdb) info task 2 + Ada Task: 0x807c468 + Name: "task_1" + Thread: 0 + LWP: 0x1fac + Parent: 1 ("main_task") + Base Priority: 15 + State: Runnable + +'task' + This command prints the ID and name of the current task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable some_task + (gdb) task + [Current task is 2 "some_task"] + +'task TASKNO' + This command is like the 'thread THREAD-ID' command (*note + Threads::). It switches the context of debugging from the current + task to the given task. + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task + * 2 807c458 1 15 Runnable some_task + (gdb) task 1 + [Switching to task 1 "main_task"] + #0 0x8067726 in pthread_cond_wait () + (gdb) bt + #0 0x8067726 in pthread_cond_wait () + #1 0x8056714 in system.os_interface.pthread_cond_wait () + #2 0x805cb63 in system.task_primitives.operations.sleep () + #3 0x806153e in system.tasking.stages.activate_tasks () + #4 0x804aacc in un () at un.adb:5 + +'task apply [TASK-ID-LIST | all] [FLAG]... COMMAND' + The 'task apply' command is the Ada tasking analogue of 'thread + apply' (*note Threads::). It allows you to apply the named COMMAND + to one or more tasks. Specify the tasks that you want affected + using a list of task IDs, or specify 'all' to apply to all tasks. + + The FLAG arguments control what output to produce and how to handle + errors raised when applying COMMAND to a task. FLAG must start + with a '-' directly followed by one letter in 'qcs'. If several + flags are provided, they must be given individually, such as '-c + -q'. + + By default, GDB displays some task information before the output + produced by COMMAND, and an error raised during the execution of a + COMMAND will abort 'task apply'. The following flags can be used + to fine-tune this behavior: + + '-c' + The flag '-c', which stands for 'continue', causes any errors + in COMMAND to be displayed, and the execution of 'task apply' + then continues. + '-s' + The flag '-s', which stands for 'silent', causes any errors or + empty output produced by a COMMAND to be silently ignored. + That is, the execution continues, but the task information and + errors are not printed. + '-q' + The flag '-q' ('quiet') disables printing the task + information. + + Flags '-c' and '-s' cannot be used together. + +'break LOCSPEC task TASKNO' +'break LOCSPEC task TASKNO if ...' + These commands are like the 'break ... thread ...' command (*note + Thread Stops::). *Note Location Specifications::, for the various + forms of LOCSPEC. + + Use the qualifier 'task TASKNO' with a breakpoint command to + specify that you only want GDB to stop the program when a + particular Ada task reaches this breakpoint. The TASKNO is one of + the numeric task identifiers assigned by GDB, shown in the first + column of the 'info tasks' display. + + If you do not specify 'task TASKNO' when you set a breakpoint, the + breakpoint applies to _all_ tasks of your program. + + You can use the 'task' qualifier on conditional breakpoints as + well; in this case, place 'task TASKNO' before the breakpoint + condition (before the 'if'). + + For example, + + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + 2 140045060 1 15 Accept/Select Wait t2 + 3 140044840 1 15 Runnable t1 + * 4 140056040 1 15 Runnable t3 + (gdb) b 15 task 2 + Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. + (gdb) cont + Continuing. + task # 1 running + task # 2 running + + Breakpoint 5, test_task_debug () at test_task_debug.adb:15 + 15 flush; + (gdb) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + * 2 140045060 1 15 Runnable t2 + 3 140044840 1 15 Runnable t1 + 4 140056040 1 15 Delay Sleep t3 + + +File: gdb.info, Node: Ada Tasks and Core Files, Next: Ravenscar Profile, Prev: Ada Tasks, Up: Ada + +15.4.10.8 Tasking Support when Debugging Core Files +................................................... + +When inspecting a core file, as opposed to debugging a live program, +tasking support may be limited or even unavailable, depending on the +platform being used. For instance, on x86-linux, the list of tasks is +available, but task switching is not supported. + + On certain platforms, the debugger needs to perform some memory +writes in order to provide Ada tasking support. When inspecting a core +file, this means that the core file must be opened with read-write +privileges, using the command '"set write on"' (*note Patching::). +Under these circumstances, you should make a backup copy of the core +file before inspecting it with GDB. + + +File: gdb.info, Node: Ravenscar Profile, Next: Ada Source Character Set, Prev: Ada Tasks and Core Files, Up: Ada + +15.4.10.9 Tasking Support when using the Ravenscar Profile +.......................................................... + +The "Ravenscar Profile" is a subset of the Ada tasking features, +specifically designed for systems with safety-critical real-time +requirements. + +'set ravenscar task-switching on' + Allows task switching when debugging a program that uses the + Ravenscar Profile. This is the default. + +'set ravenscar task-switching off' + Turn off task switching when debugging a program that uses the + Ravenscar Profile. This is mostly intended to disable the code + that adds support for the Ravenscar Profile, in case a bug in + either GDB or in the Ravenscar runtime is preventing GDB from + working properly. To be effective, this command should be run + before the program is started. + +'show ravenscar task-switching' + Show whether it is possible to switch from task to task in a + program using the Ravenscar Profile. + + When Ravenscar task-switching is enabled, Ravenscar tasks are +announced by GDB as if they were threads: + + (gdb) continue + [New Ravenscar Thread 0x2b8f0] + + Both Ravenscar tasks and the underlying CPU threads will show up in +the output of 'info threads': + + (gdb) info threads + Id Target Id Frame + 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10 + 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices () + 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices () + 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle () + * 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10 + 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle () + + One known limitation of the Ravenscar support in GDB is that it isn't +currently possible to single-step through the runtime initialization +sequence. If you need to debug this code, you should use 'set ravenscar +task-switching off'. + + +File: gdb.info, Node: Ada Source Character Set, Next: Ada Glitches, Prev: Ravenscar Profile, Up: Ada + +15.4.10.10 Ada Source Character Set +................................... + +The GNAT compiler supports a number of character sets for source files. +*Note Character Set Control: (gnat_ugn)Character Set Control. GDB +includes support for this as well. + +'set ada source-charset CHARSET' + Set the source character set for Ada. The character set must be + supported by GNAT. Because this setting affects the decoding of + symbols coming from the debug information in your program, the + setting should be set as early as possible. The default is + 'ISO-8859-1', because that is also GNAT's default. + +'show ada source-charset' + Show the current source character set for Ada. + + +File: gdb.info, Node: Ada Glitches, Prev: Ada Source Character Set, Up: Ada + +15.4.10.11 Known Peculiarities of Ada Mode +.......................................... + +Besides the omissions listed previously (*note Omissions from Ada::), we +know of several problems with and limitations of Ada mode in GDB, some +of which will be fixed with planned future releases of the debugger and +the GNU Ada compiler. + + * Static constants that the compiler chooses not to materialize as + objects in storage are invisible to the debugger. + + * Named parameter associations in function argument lists are ignored + (the argument lists are treated as positional). + + * Many useful library packages are currently invisible to the + debugger. + + * Fixed-point arithmetic, conversions, input, and output is carried + out using floating-point arithmetic, and may give results that only + approximate those on the host machine. + + * The GNAT compiler never generates the prefix 'Standard' for any of + the standard symbols defined by the Ada language. GDB knows about + this: it will strip the prefix from names when you use it, and will + never look for a name you have so qualified among local symbols, + nor match against symbols in other packages or subprograms. If you + have defined entities anywhere in your program other than + parameters and local variables whose simple names match names in + 'Standard', GNAT's lack of qualification here can cause confusion. + When this happens, you can usually resolve the confusion by + qualifying the problematic names with package 'Standard' + explicitly. + + Older versions of the compiler sometimes generate erroneous debugging +information, resulting in the debugger incorrectly printing the value of +affected entities. In some cases, the debugger is able to work around +an issue automatically. In other cases, the debugger is able to work +around the issue, but the work-around has to be specifically enabled. + +'set ada trust-PAD-over-XVS on' + Configure GDB to strictly follow the GNAT encoding when computing + the value of Ada entities, particularly when 'PAD' and 'PAD___XVS' + types are involved (see 'ada/exp_dbug.ads' in the GCC sources for a + complete description of the encoding used by the GNAT compiler). + This is the default. + +'set ada trust-PAD-over-XVS off' + This is related to the encoding using by the GNAT compiler. If GDB + sometimes prints the wrong value for certain entities, changing + 'ada trust-PAD-over-XVS' to 'off' activates a work-around which may + fix the issue. It is always safe to set 'ada trust-PAD-over-XVS' + to 'off', but this incurs a slight performance penalty, so it is + recommended to leave this setting to 'on' unless necessary. + + Internally, the debugger also relies on the compiler following a +number of conventions known as the 'GNAT Encoding', all documented in +'gcc/ada/exp_dbug.ads' in the GCC sources. This encoding describes how +the debugging information should be generated for certain types. In +particular, this convention makes use of "descriptive types", which are +artificial types generated purely to help the debugger. + + These encodings were defined at a time when the debugging information +format used was not powerful enough to describe some of the more complex +types available in Ada. Since DWARF allows us to express nearly all Ada +features, the long-term goal is to slowly replace these descriptive +types by their pure DWARF equivalent. To facilitate that transition, a +new maintenance option is available to force the debugger to ignore +those descriptive types. It allows the user to quickly evaluate how +well GDB works without them. + +'maintenance ada set ignore-descriptive-types [on|off]' + Control whether the debugger should ignore descriptive types. The + default is not to ignore descriptives types ('off'). + +'maintenance ada show ignore-descriptive-types' + Show if descriptive types are ignored by GDB. + + +File: gdb.info, Node: Unsupported Languages, Prev: Supported Languages, Up: Languages + +15.5 Unsupported Languages +========================== + +In addition to the other fully-supported programming languages, GDB also +provides a pseudo-language, called 'minimal'. It does not represent a +real programming language, but provides a set of capabilities close to +what the C or assembly languages provide. This should allow most simple +operations to be performed while debugging an application that uses a +language currently not supported by GDB. + + If the language is set to 'auto', GDB will automatically select this +language if the current frame corresponds to an unsupported language. + + +File: gdb.info, Node: Symbols, Next: Altering, Prev: Languages, Up: Top + +16 Examining the Symbol Table +***************************** + +The commands described in this chapter allow you to inquire about the +symbols (names of variables, functions and types) defined in your +program. This information is inherent in the text of your program and +does not change as your program executes. GDB finds it in your +program's symbol table, in the file indicated when you started GDB +(*note Choosing Files: File Options.), or by one of the file-management +commands (*note Commands to Specify Files: Files.). + + Occasionally, you may need to refer to symbols that contain unusual +characters, which GDB ordinarily treats as word delimiters. The most +frequent case is in referring to static variables in other source files +(*note Program Variables: Variables.). File names are recorded in +object files as debugging symbols, but GDB would ordinarily parse a +typical file name, like 'foo.c', as the three words 'foo' '.' 'c'. To +allow GDB to recognize 'foo.c' as a single symbol, enclose it in single +quotes; for example, + + p 'foo.c'::x + +looks up the value of 'x' in the scope of the file 'foo.c'. + +'set case-sensitive on' +'set case-sensitive off' +'set case-sensitive auto' + Normally, when GDB looks up symbols, it matches their names with + case sensitivity determined by the current source language. + Occasionally, you may wish to control that. The command 'set + case-sensitive' lets you do that by specifying 'on' for + case-sensitive matches or 'off' for case-insensitive ones. If you + specify 'auto', case sensitivity is reset to the default suitable + for the source language. The default is case-sensitive matches for + all languages except for Fortran, for which the default is + case-insensitive matches. + +'show case-sensitive' + This command shows the current setting of case sensitivity for + symbols lookups. + +'set print type methods' +'set print type methods on' +'set print type methods off' + Normally, when GDB prints a class, it displays any methods declared + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type methods'. + Specifying 'on' will cause GDB to display the methods; this is the + default. Specifying 'off' will cause GDB to omit the methods. + +'show print type methods' + This command shows the current setting of method display when + printing classes. + +'set print type nested-type-limit LIMIT' +'set print type nested-type-limit unlimited' + Set the limit of displayed nested types that the type printer will + show. A LIMIT of 'unlimited' or '-1' will show all nested + definitions. By default, the type printer will not show any nested + types defined in classes. + +'show print type nested-type-limit' + This command shows the current display limit of nested types when + printing classes. + +'set print type typedefs' +'set print type typedefs on' +'set print type typedefs off' + + Normally, when GDB prints a class, it displays any typedefs defined + in that class. You can control this behavior either by passing the + appropriate flag to 'ptype', or using 'set print type typedefs'. + Specifying 'on' will cause GDB to display the typedef definitions; + this is the default. Specifying 'off' will cause GDB to omit the + typedef definitions. Note that this controls whether the typedef + definition itself is printed, not whether typedef names are + substituted when printing other types. + +'show print type typedefs' + This command shows the current setting of typedef display when + printing classes. + +'set print type hex' +'set print type hex on' +'set print type hex off' + + When GDB prints sizes and offsets of struct members, it can use + either the decimal or hexadecimal notation. You can select one or + the other either by passing the appropriate flag to 'ptype', or by + using the 'set print type hex' command. + +'show print type hex' + This command shows whether the sizes and offsets of struct members + are printed in decimal or hexadecimal notation. + +'info address SYMBOL' + Describe where the data for SYMBOL is stored. For a register + variable, this says which register it is kept in. For a + non-register local variable, this prints the stack-frame offset at + which the variable is always stored. + + Note the contrast with 'print &SYMBOL', which does not work at all + for a register variable, and for a stack local variable prints the + exact address of the current instantiation of the variable. + +'info symbol ADDR' + Print the name of a symbol which is stored at the address ADDR. If + no symbol is stored exactly at ADDR, GDB prints the nearest symbol + and an offset from it: + + (gdb) info symbol 0x54320 + _initialize_vx + 396 in section .text + + This is the opposite of the 'info address' command. You can use it + to find out the name of a variable or a function given its address. + + For dynamically linked executables, the name of executable or + shared library containing the symbol is also printed: + + (gdb) info symbol 0x400225 + _start + 5 in section .text of /tmp/a.out + (gdb) info symbol 0x2aaaac2811cf + __read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 + +'demangle [-l LANGUAGE] [--] NAME' + Demangle NAME. If LANGUAGE is provided it is the name of the + language to demangle NAME in. Otherwise NAME is demangled in the + current language. + + The '--' option specifies the end of options, and is useful when + NAME begins with a dash. + + The parameter 'demangle-style' specifies how to interpret the kind + of mangling used. *Note Print Settings::. + +'whatis[/FLAGS] [ARG]' + Print the data type of ARG, which can be either an expression or a + name of a data type. With no argument, print the data type of '$', + the last value in the value history. + + If ARG is an expression (*note Expressions: Expressions.), it is + not actually evaluated, and any side-effecting operations (such as + assignments or function calls) inside it do not take place. + + If ARG is a variable or an expression, 'whatis' prints its literal + type as it is used in the source code. If the type was defined + using a 'typedef', 'whatis' will _not_ print the data type + underlying the 'typedef'. If the type of the variable or the + expression is a compound data type, such as 'struct' or 'class', + 'whatis' never prints their fields or methods. It just prints the + 'struct'/'class' name (a.k.a. its "tag"). If you want to see the + members of such a compound data type, use 'ptype'. + + If ARG is a type name that was defined using 'typedef', 'whatis' + "unrolls" only one level of that 'typedef'. Unrolling means that + 'whatis' will show the underlying type used in the 'typedef' + declaration of ARG. However, if that underlying type is also a + 'typedef', 'whatis' will not unroll it. + + For C code, the type names may also have the form 'class + CLASS-NAME', 'struct STRUCT-TAG', 'union UNION-TAG' or 'enum + ENUM-TAG'. + + FLAGS can be used to modify how the type is displayed. Available + flags are: + + 'r' + Display in "raw" form. Normally, GDB substitutes template + parameters and typedefs defined in a class when printing the + class' members. The '/r' flag disables this. + + 'm' + Do not print methods defined in the class. + + 'M' + Print methods defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type methods'. + + 't' + Do not print typedefs defined in the class. Note that this + controls whether the typedef definition itself is printed, not + whether typedef names are substituted when printing other + types. + + 'T' + Print typedefs defined in the class. This is the default, but + the flag exists in case you change the default with 'set print + type typedefs'. + + 'o' + Print the offsets and sizes of fields in a struct, similar to + what the 'pahole' tool does. This option implies the '/tm' + flags. + + 'x' + Use hexadecimal notation when printing offsets and sizes of + fields in a struct. + + 'd' + Use decimal notation when printing offsets and sizes of fields + in a struct. + + For example, given the following declarations: + + struct tuv + { + int a1; + char *a2; + int a3; + }; + + struct xyz + { + int f1; + char f2; + void *f3; + struct tuv f4; + }; + + union qwe + { + struct tuv fff1; + struct xyz fff2; + }; + + struct tyu + { + int a1 : 1; + int a2 : 3; + int a3 : 23; + char a4 : 2; + int64_t a5; + int a6 : 5; + int64_t a7 : 3; + }; + + Issuing a 'ptype /o struct tuv' command would print: + + (gdb) ptype /o struct tuv + /* offset | size */ type = struct tuv { + /* 0 | 4 */ int a1; + /* XXX 4-byte hole */ + /* 8 | 8 */ char *a2; + /* 16 | 4 */ int a3; + + /* total size (bytes): 24 */ + } + + Notice the format of the first column of comments. There, you + can find two parts separated by the '|' character: the + _offset_, which indicates where the field is located inside + the struct, in bytes, and the _size_ of the field. Another + interesting line is the marker of a _hole_ in the struct, + indicating that it may be possible to pack the struct and make + it use less space by reorganizing its fields. + + It is also possible to print offsets inside an union: + + (gdb) ptype /o union qwe + /* offset | size */ type = union qwe { + /* 24 */ struct tuv { + /* 0 | 4 */ int a1; + /* XXX 4-byte hole */ + /* 8 | 8 */ char *a2; + /* 16 | 4 */ int a3; + + /* total size (bytes): 24 */ + } fff1; + /* 40 */ struct xyz { + /* 0 | 4 */ int f1; + /* 4 | 1 */ char f2; + /* XXX 3-byte hole */ + /* 8 | 8 */ void *f3; + /* 16 | 24 */ struct tuv { + /* 16 | 4 */ int a1; + /* XXX 4-byte hole */ + /* 24 | 8 */ char *a2; + /* 32 | 4 */ int a3; + + /* total size (bytes): 24 */ + } f4; + + /* total size (bytes): 40 */ + } fff2; + + /* total size (bytes): 40 */ + } + + In this case, since 'struct tuv' and 'struct xyz' occupy the + same space (because we are dealing with an union), the offset + is not printed for them. However, you can still examine the + offset of each of these structures' fields. + + Another useful scenario is printing the offsets of a struct + containing bitfields: + + (gdb) ptype /o struct tyu + /* offset | size */ type = struct tyu { + /* 0:31 | 4 */ int a1 : 1; + /* 0:28 | 4 */ int a2 : 3; + /* 0: 5 | 4 */ int a3 : 23; + /* 3: 3 | 1 */ signed char a4 : 2; + /* XXX 3-bit hole */ + /* XXX 4-byte hole */ + /* 8 | 8 */ int64_t a5; + /* 16: 0 | 4 */ int a6 : 5; + /* 16: 5 | 8 */ int64_t a7 : 3; + /* XXX 7-byte padding */ + + /* total size (bytes): 24 */ + } + + Note how the offset information is now extended to also + include the first bit of the bitfield. + +'ptype[/FLAGS] [ARG]' + 'ptype' accepts the same arguments as 'whatis', but prints a + detailed description of the type, instead of just the name of the + type. *Note Expressions: Expressions. + + Contrary to 'whatis', 'ptype' always unrolls any 'typedef's in its + argument declaration, whether the argument is a variable, + expression, or a data type. This means that 'ptype' of a variable + or an expression will not print literally its type as present in + the source code--use 'whatis' for that. 'typedef's at the pointer + or reference targets are also unrolled. Only 'typedef's of fields, + methods and inner 'class typedef's of 'struct's, 'class'es and + 'union's are not unrolled even with 'ptype'. + + For example, for this variable declaration: + + typedef double real_t; + struct complex { real_t real; double imag; }; + typedef struct complex complex_t; + complex_t var; + real_t *real_pointer_var; + + the two commands give this output: + + (gdb) whatis var + type = complex_t + (gdb) ptype var + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis complex_t + type = struct complex + (gdb) whatis struct complex + type = struct complex + (gdb) ptype struct complex + type = struct complex { + real_t real; + double imag; + } + (gdb) whatis real_pointer_var + type = real_t * + (gdb) ptype real_pointer_var + type = double * + + As with 'whatis', using 'ptype' without an argument refers to the + type of '$', the last value in the value history. + + Sometimes, programs use opaque data types or incomplete + specifications of complex data structure. If the debug information + included in the program does not allow GDB to display a full + declaration of the data type, it will say ''. For + example, given these declarations: + + struct foo; + struct foo *fooptr; + + but no definition for 'struct foo' itself, GDB will say: + + (gdb) ptype foo + $1 = + + "Incomplete type" is C terminology for data types that are not + completely specified. + + Othertimes, information about a variable's type is completely + absent from the debug information included in the program. This + most often happens when the program or library where the variable + is defined includes no debug information at all. GDB knows the + variable exists from inspecting the linker/loader symbol table + (e.g., the ELF dynamic symbol table), but such symbols do not + contain type information. Inspecting the type of a (global) + variable for which GDB has no type information shows: + + (gdb) ptype var + type = + + *Note no debug info variables: Variables, for how to print the + values of such variables. + +'info types [-q] [REGEXP]' + Print a brief description of all types whose names match the + regular expression REGEXP (or all types in your program, if you + supply no argument). Each complete typename is matched as though + it were a complete line; thus, 'i type value' gives information on + all types in your program whose names include the string 'value', + but 'i type ^value$' gives information only on types whose complete + name is 'value'. + + In programs using different languages, GDB chooses the syntax to + print the type description according to the 'set language' value: + using 'set language auto' (see *note Set Language Automatically: + Automatically.) means to use the language of the type, other values + mean to use the manually specified language (see *note Set Language + Manually: Manually.). + + This command differs from 'ptype' in two ways: first, like + 'whatis', it does not print a detailed description; second, it + lists all source files and line numbers where a type is defined. + + The output from 'into types' is proceeded with a header line + describing what types are being listed. The optional flag '-q', + which stands for 'quiet', disables printing this header + information. + +'info type-printers' + Versions of GDB that ship with Python scripting enabled may have + "type printers" available. When using 'ptype' or 'whatis', these + printers are consulted when the name of a type is needed. *Note + Type Printing API::, for more information on writing type printers. + + 'info type-printers' displays all the available type printers. + +'enable type-printer NAME...' +'disable type-printer NAME...' + These commands can be used to enable or disable type printers. + +'info scope LOCSPEC' + List all the variables local to the lexical scope of the code + location that results from resolving LOCSPEC. *Note Location + Specifications::, for details about supported forms of LOCSPEC. + For example: + + (gdb) info scope command_line_handler + Scope for command_line_handler: + Symbol rl is an argument at stack/frame offset 8, length 4. + Symbol linebuffer is in static storage at address 0x150a18, length 4. + Symbol linelength is in static storage at address 0x150a1c, length 4. + Symbol p is a local variable in register $esi, length 4. + Symbol p1 is a local variable in register $ebx, length 4. + Symbol nline is a local variable in register $edx, length 4. + Symbol repeat is a local variable at frame offset -8, length 4. + + This command is especially useful for determining what data to + collect during a "trace experiment", see *note collect: Tracepoint + Actions. + +'info source' + Show information about the current source file--that is, the source + file for the function containing the current point of execution: + * the name of the source file, and the directory containing it, + * the directory it was compiled in, + * its length, in lines, + * which programming language it is written in, + * if the debug information provides it, the program that + compiled the file (which may include, e.g., the compiler + version and command line arguments), + * whether the executable includes debugging information for that + file, and if so, what format the information is in (e.g., + STABS, Dwarf 2, etc.), and + * whether the debugging information includes information about + preprocessor macros. + +'info sources [-dirname | -basename] [--] [REGEXP]' + + With no options 'info sources' prints the names of all source files + in your program for which there is debugging information. The + source files are presented based on a list of object files + (executables and libraries) currently loaded into GDB. For each + object file all of the associated source files are listed. + + Each source file will only be printed once for each object file, + but a single source file can be repeated in the output if it is + part of multiple object files. + + If the optional REGEXP is provided, then only source files that + match the regular expression will be printed. The matching is + case-sensitive, except on operating systems that have + case-insensitive filesystem (e.g., MS-Windows). '--' can be used + before REGEXP to prevent GDB interpreting REGEXP as a command + option (e.g. if REGEXP starts with '-'). + + By default, the REGEXP is used to match anywhere in the filename. + If '-dirname', only files having a dirname matching REGEXP are + shown. If '-basename', only files having a basename matching + REGEXP are shown. + + It is possible that an object file may be printed in the list with + no associated source files. This can happen when either no source + files match REGEXP, or, the object file was compiled without debug + information and so GDB is unable to find any source file names. + +'info functions [-q] [-n]' + Print the names and data types of all defined functions. Similarly + to 'info types', this command groups its output by source files and + annotates each function definition with its source line number. + + In programs using different languages, GDB chooses the syntax to + print the function name and type according to the 'set language' + value: using 'set language auto' (see *note Set Language + Automatically: Automatically.) means to use the language of the + function, other values mean to use the manually specified language + (see *note Set Language Manually: Manually.). + + The '-n' flag excludes "non-debugging symbols" from the results. A + non-debugging symbol is a symbol that comes from the executable's + symbol table, not from the debug information (for example, DWARF) + associated with the executable. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no functions have + been printed. + +'info functions [-q] [-n] [-t TYPE_REGEXP] [REGEXP]' + Like 'info functions', but only print the names and data types of + the functions selected with the provided regexp(s). + + If REGEXP is provided, print only the functions whose names match + the regular expression REGEXP. Thus, 'info fun step' finds all + functions whose names include 'step'; 'info fun ^step' finds those + whose names start with 'step'. If a function name contains + characters that conflict with the regular expression language (e.g. + 'operator*()'), they may be quoted with a backslash. + + If TYPE_REGEXP is provided, print only the functions whose types, + as printed by the 'whatis' command, match the regular expression + TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be + enclosed in quote characters. If needed, use backslash to escape + the meaning of special characters or quotes. Thus, 'info fun -t + '^int ('' finds the functions that return an integer; 'info fun -t + '(.*int.*'' finds the functions that have an argument type + containing int; 'info fun -t '^int (' ^step' finds the functions + whose names start with 'step' and that return int. + + If both REGEXP and TYPE_REGEXP are provided, a function is printed + only if its name matches REGEXP and its type matches TYPE_REGEXP. + +'info variables [-q] [-n]' + Print the names and data types of all variables that are defined + outside of functions (i.e. excluding local variables). The printed + variables are grouped by source files and annotated with their + respective source line numbers. + + In programs using different languages, GDB chooses the syntax to + print the variable name and type according to the 'set language' + value: using 'set language auto' (see *note Set Language + Automatically: Automatically.) means to use the language of the + variable, other values mean to use the manually specified language + (see *note Set Language Manually: Manually.). + + The '-n' flag excludes non-debugging symbols from the results. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no variables have + been printed. + +'info variables [-q] [-n] [-t TYPE_REGEXP] [REGEXP]' + Like 'info variables', but only print the variables selected with + the provided regexp(s). + + If REGEXP is provided, print only the variables whose names match + the regular expression REGEXP. + + If TYPE_REGEXP is provided, print only the variables whose types, + as printed by the 'whatis' command, match the regular expression + TYPE_REGEXP. If TYPE_REGEXP contains space(s), it should be + enclosed in quote characters. If needed, use backslash to escape + the meaning of special characters or quotes. + + If both REGEXP and TYPE_REGEXP are provided, an argument is printed + only if its name matches REGEXP and its type matches TYPE_REGEXP. + +'info modules [-q] [REGEXP]' + List all Fortran modules in the program, or all modules matching + the optional regular expression REGEXP. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no modules have been + printed. + +'info module functions [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]' +'info module variables [-q] [-m MODULE-REGEXP] [-t TYPE-REGEXP] [REGEXP]' + List all functions or variables within all Fortran modules. The + set of functions or variables listed can be limited by providing + some or all of the optional regular expressions. If MODULE-REGEXP + is provided, then only Fortran modules matching MODULE-REGEXP will + be searched. Only functions or variables whose type matches the + optional regular expression TYPE-REGEXP will be listed. And only + functions or variables whose name matches the optional regular + expression REGEXP will be listed. + + The optional flag '-q', which stands for 'quiet', disables printing + header information and messages explaining why no functions or + variables have been printed. + +'info main' + Print the name of the starting function of the program. This + serves primarily Fortran programs, which have a user-supplied name + for the main subroutine. + +'info classes' +'info classes REGEXP' + Display all Objective-C classes in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'info selectors' +'info selectors REGEXP' + Display all Objective-C selectors in your program, or (with the + REGEXP argument) all those matching a particular regular + expression. + +'set opaque-type-resolution on' + Tell GDB to resolve opaque types. An opaque type is a type + declared as a pointer to a 'struct', 'class', or 'union'--for + example, 'struct MyType *'--that is used in one source file + although the full declaration of 'struct MyType' is in another + source file. The default is on. + + A change in the setting of this subcommand will not take effect + until the next time symbols for a file are loaded. + +'set opaque-type-resolution off' + Tell GDB not to resolve opaque types. In this case, the type is + printed as follows: + {} + +'show opaque-type-resolution' + Show whether opaque types are resolved or not. + +'set print symbol-loading' +'set print symbol-loading full' +'set print symbol-loading brief' +'set print symbol-loading off' + The 'set print symbol-loading' command allows you to control the + printing of messages when GDB loads symbol information. By default + a message is printed for the executable and one for each shared + library, and normally this is what you want. However, when + debugging apps with large numbers of shared libraries these + messages can be annoying. When set to 'brief' a message is printed + for each executable, and when GDB loads a collection of shared + libraries at once it will only print one message regardless of the + number of shared libraries. When set to 'off' no messages are + printed. + +'show print symbol-loading' + Show whether messages will be printed when a GDB command entered + from the keyboard causes symbol information to be loaded. + +'maint print symbols [-pc ADDRESS] [FILENAME]' +'maint print symbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]' +'maint print psymbols [-objfile OBJFILE] [-pc ADDRESS] [--] [FILENAME]' +'maint print psymbols [-objfile OBJFILE] [-source SOURCE] [--] [FILENAME]' +'maint print msymbols [-objfile OBJFILE] [--] [FILENAME]' + Write a dump of debugging symbol data into the file FILENAME or the + terminal if FILENAME is unspecified. If '-objfile OBJFILE' is + specified, only dump symbols for that objfile. If '-pc ADDRESS' is + specified, only dump symbols for the file with code at that + address. Note that ADDRESS may be a symbol like 'main'. If + '-source SOURCE' is specified, only dump symbols for that source + file. + + These commands are used to debug the GDB symbol-reading code. + These commands do not modify internal GDB state, therefore 'maint + print symbols' will only print symbols for already expanded symbol + tables. You can use the command 'info sources' to find out which + files these are. If you use 'maint print psymbols' instead, the + dump shows information about symbols that GDB only knows + partially--that is, symbols defined in files that GDB has skimmed, + but not yet read completely. Finally, 'maint print msymbols' just + dumps "minimal symbols", e.g., "ELF symbols". + + *Note Commands to Specify Files: Files, for a discussion of how GDB + reads symbols (in the description of 'symbol-file'). + +'maint info symtabs [ REGEXP ]' +'maint info psymtabs [ REGEXP ]' + + List the 'struct symtab' or 'struct partial_symtab' structures + whose names match REGEXP. If REGEXP is not given, list them all. + The output includes expressions which you can copy into a GDB + debugging this one to examine a particular structure in more + detail. For example: + + (gdb) maint info psymtabs dwarf2read + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { psymtab /home/gnu/src/gdb/dwarf2read.c + ((struct partial_symtab *) 0x8474b10) + readin no + fullname (null) + text addresses 0x814d3c8 -- 0x8158074 + globals (* (struct partial_symbol **) 0x8507a08 @ 9) + statics (* (struct partial_symbol **) 0x40e95b78 @ 2882) + dependencies (none) + } + } + (gdb) maint info symtabs + (gdb) + We see that there is one partial symbol table whose filename + contains the string 'dwarf2read', belonging to the 'gdb' + executable; and we see that GDB has not read in any symtabs yet at + all. If we set a breakpoint on a function, that will cause GDB to + read the symtab for the compilation unit containing that function: + + (gdb) break dwarf2_psymtab_to_symtab + Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, + line 1574. + (gdb) maint info symtabs + { objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + { symtab /home/gnu/src/gdb/dwarf2read.c + ((struct symtab *) 0x86c1f38) + dirname (null) + fullname (null) + blockvector ((struct blockvector *) 0x86c1bd0) (primary) + linetable ((struct linetable *) 0x8370fa0) + debugformat DWARF 2 + } + } + (gdb) + +'maint info line-table [ REGEXP ]' + + List the 'struct linetable' from all 'struct symtab' instances + whose name matches REGEXP. If REGEXP is not given, list the + 'struct linetable' from all 'struct symtab'. For example: + + (gdb) maint info line-table + objfile: /home/gnu/build/a.out ((struct objfile *) 0x6120000e0d40) + compunit_symtab: simple.cpp ((struct compunit_symtab *) 0x6210000ff450) + symtab: /home/gnu/src/simple.cpp ((struct symtab *) 0x6210000ff4d0) + linetable: ((struct linetable *) 0x62100012b760): + INDEX LINE ADDRESS IS-STMT PROLOGUE-END EPILOGUE-BEGIN + 0 3 0x0000000000401110 Y + 1 4 0x0000000000401114 Y Y Y + 2 9 0x0000000000401120 Y + 3 10 0x0000000000401124 Y Y + 4 10 0x0000000000401129 Y Y + 5 15 0x0000000000401130 Y + 6 16 0x0000000000401134 Y Y + 7 16 0x0000000000401139 + 8 21 0x0000000000401140 Y Y + 9 22 0x000000000040114f Y Y + 10 22 0x0000000000401154 Y + 11 END 0x000000000040115a Y + The 'IS-STMT' column indicates if the address is a recommended + breakpoint location to represent a line or a statement. The + 'PROLOGUE-END' column indicates that a given address is an adequate + place to set a breakpoint at the first instruction following a + function prologue. The 'EPILOGUE-BEGIN' column indicates that a + given address marks the point where a block's frame is destroyed, + making local variables hard or impossible to find. + +'set always-read-ctf [on|off]' +'show always-read-ctf' + + When off, CTF debug info is only read if DWARF debug info is not + present. When on, CTF debug info is read regardless of whether + DWARF debug info is present. The default value is off. + +'maint set symbol-cache-size SIZE' + Set the size of the symbol cache to SIZE. The default size is + intended to be good enough for debugging most applications. This + option exists to allow for experimenting with different sizes. + +'maint show symbol-cache-size' + Show the size of the symbol cache. + +'maint print symbol-cache' + Print the contents of the symbol cache. This is useful when + debugging symbol cache issues. + +'maint print symbol-cache-statistics' + Print symbol cache usage statistics. This helps determine how well + the cache is being utilized. + +'maint flush symbol-cache' +'maint flush-symbol-cache' + Flush the contents of the symbol cache, all entries are removed. + This command is useful when debugging the symbol cache. It is also + useful when collecting performance data. The command 'maint + flush-symbol-cache' is deprecated in favor of 'maint flush + symbol-cache'.. + +'maint set ignore-prologue-end-flag [on|off]' + Enable or disable the use of the 'PROLOGUE-END' flag from the + line-table. When 'off' (the default), GDB uses the 'PROLOGUE-END' + flag to place breakpoints past the end of a function prologue. + When 'on', GDB ignores the flag and relies on prologue analyzers to + skip function prologues. + +'maint show ignore-prologue-end-flag' + Show whether GDB will ignore the 'PROLOGUE-END' flag. + + +File: gdb.info, Node: Altering, Next: GDB Files, Prev: Symbols, Up: Top + +17 Altering Execution +********************* + +Once you think you have found an error in your program, you might want +to find out for certain whether correcting the apparent error would lead +to correct results in the rest of the run. You can find the answer by +experiment, using the GDB features for altering execution of the +program. + + For example, you can store new values into variables or memory +locations, give your program a signal, restart it at a different +address, or even return prematurely from a function. + +* Menu: + +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address +* Signaling:: Giving your program a signal +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program +* Compiling and Injecting Code:: Compiling and injecting code in GDB + + +File: gdb.info, Node: Assignment, Next: Jumping, Up: Altering + +17.1 Assignment to Variables +============================ + +To alter the value of a variable, evaluate an assignment expression. +*Note Expressions: Expressions. For example, + + print x=4 + +stores the value 4 into the variable 'x', and then prints the value of +the assignment expression (which is 4). *Note Using GDB with Different +Languages: Languages, for more information on operators in supported +languages. + + If you are not interested in seeing the value of the assignment, use +the 'set' command instead of the 'print' command. 'set' is really the +same as 'print' except that the expression's value is not printed and is +not put in the value history (*note Value History: Value History.). The +expression is evaluated only for its effects. + + If the beginning of the argument string of the 'set' command appears +identical to a 'set' subcommand, use the 'set variable' command instead +of just 'set'. This command is identical to 'set' except for its lack +of subcommands. For example, if your program has a variable 'width', +you get an error if you try to set a new value with just 'set width=13', +because GDB has the command 'set width': + + (gdb) whatis width + type = double + (gdb) p width + $4 = 13 + (gdb) set width=47 + Invalid syntax in expression. + +The invalid expression, of course, is '=47'. In order to actually set +the program's variable 'width', use + + (gdb) set var width=47 + + Because the 'set' command has many subcommands that can conflict with +the names of program variables, it is a good idea to use the 'set +variable' command instead of just 'set'. For example, if your program +has a variable 'g', you run into problems if you try to set a new value +with just 'set g=4', because GDB has the command 'set gnutarget', +abbreviated 'set g': + + (gdb) whatis g + type = double + (gdb) p g + $1 = 1 + (gdb) set g=4 + (gdb) p g + $2 = 1 + (gdb) r + The program being debugged has been started already. + Start it from the beginning? (y or n) y + Starting program: /home/smith/cc_progs/a.out + "/home/smith/cc_progs/a.out": can't open to read symbols: + Invalid bfd target. + (gdb) show g + The current BFD target is "=4". + +The program variable 'g' did not change, and you silently set the +'gnutarget' to an invalid value. In order to set the variable 'g', use + + (gdb) set var g=4 + + GDB allows more implicit conversions in assignments than C; you can +freely store an integer value into a pointer variable or vice versa, and +you can convert any structure to any other structure that is the same +length or shorter. + + To store values into arbitrary places in memory, use the '{...}' +construct to generate a value of specified type at a specified address +(*note Expressions: Expressions.). For example, '{int}0x83040' refers +to memory location '0x83040' as an integer (which implies a certain size +and representation in memory), and + + set {int}0x83040 = 4 + +stores the value 4 into that memory location. + + +File: gdb.info, Node: Jumping, Next: Signaling, Prev: Assignment, Up: Altering + +17.2 Continuing at a Different Address +====================================== + +Ordinarily, when you continue your program, you do so at the place where +it stopped, with the 'continue' command. You can instead continue at an +address of your own choosing, with the following commands: + +'jump LOCSPEC' +'j LOCSPEC' + Resume execution at the address of the code location that results + from resolving LOCSPEC. *Note Location Specifications::, for a + description of the different forms of LOCSPEC. If LOCSPEC resolves + to more than one address, those outside the current compilation + unit are ignored. If considering just the addresses in the current + compilation unit still doesn't yield a unique address, the command + aborts before jumping. Execution stops again immediately if there + is a breakpoint there. It is common practice to use the 'tbreak' + command in conjunction with 'jump'. *Note Setting Breakpoints: Set + Breaks. + + The 'jump' command does not change the current stack frame, or the + stack pointer, or the contents of any memory location or any + register other than the program counter. If LOCSPEC resolves to an + address in a different function from the one currently executing, + the results may be bizarre if the two functions expect different + patterns of arguments or of local variables. For this reason, the + 'jump' command requests confirmation if the jump address is not in + the function currently executing. However, even bizarre results + are predictable if you are well acquainted with the + machine-language code of your program. + + On many systems, you can get much the same effect as the 'jump' +command by storing a new value into the register '$pc'. The difference +is that this does not start your program running; it only changes the +address of where it _will_ run when you continue. For example, + + set $pc = 0x485 + +makes the next 'continue' command or stepping command execute at address +'0x485', rather than at the address where your program stopped. *Note +Continuing and Stepping: Continuing and Stepping. + + However, writing directly to '$pc' will only change the value of the +program-counter register, while using 'jump' will ensure that any +additional auxiliary state is also updated. For example, on SPARC, +'jump' will update both '$pc' and '$npc' registers prior to resuming +execution. When using the approach of writing directly to '$pc' it is +your job to also update the '$npc' register. + + The most common occasion to use the 'jump' command is to back +up--perhaps with more breakpoints set--over a portion of a program that +has already executed, in order to examine its execution in more detail. + + +File: gdb.info, Node: Signaling, Next: Returning, Prev: Jumping, Up: Altering + +17.3 Giving your Program a Signal +================================= + +'signal SIGNAL' + Resume execution where your program is stopped, but immediately + give it the signal SIGNAL. The SIGNAL can be the name or the + number of a signal. For example, on many systems 'signal 2' and + 'signal SIGINT' are both ways of sending an interrupt signal. + + Alternatively, if SIGNAL is zero, continue execution without giving + a signal. This is useful when your program stopped on account of a + signal and would ordinarily see the signal when resumed with the + 'continue' command; 'signal 0' causes it to resume without a + signal. + + _Note:_ When resuming a multi-threaded program, SIGNAL is delivered + to the currently selected thread, not the thread that last reported + a stop. This includes the situation where a thread was stopped due + to a signal. So if you want to continue execution suppressing the + signal that stopped a thread, you should select that same thread + before issuing the 'signal 0' command. If you issue the 'signal 0' + command with another thread as the selected one, GDB detects that + and asks for confirmation. + + Invoking the 'signal' command is not the same as invoking the + 'kill' utility from the shell. Sending a signal with 'kill' causes + GDB to decide what to do with the signal depending on the signal + handling tables (*note Signals::). The 'signal' command passes the + signal directly to your program. + + 'signal' does not repeat when you press a second time after + executing the command. + +'queue-signal SIGNAL' + Queue SIGNAL to be delivered immediately to the current thread when + execution of the thread resumes. The SIGNAL can be the name or the + number of a signal. For example, on many systems 'signal 2' and + 'signal SIGINT' are both ways of sending an interrupt signal. The + handling of the signal must be set to pass the signal to the + program, otherwise GDB will report an error. You can control the + handling of signals from GDB with the 'handle' command (*note + Signals::). + + Alternatively, if SIGNAL is zero, any currently queued signal for + the current thread is discarded and when execution resumes no + signal will be delivered. This is useful when your program stopped + on account of a signal and would ordinarily see the signal when + resumed with the 'continue' command. + + This command differs from the 'signal' command in that the signal + is just queued, execution is not resumed. And 'queue-signal' + cannot be used to pass a signal whose handling state has been set + to 'nopass' (*note Signals::). + + *Note stepping into signal handlers::, for information on how +stepping commands behave when the thread has a signal queued. + + +File: gdb.info, Node: Returning, Next: Calling, Prev: Signaling, Up: Altering + +17.4 Returning from a Function +============================== + +'return' +'return EXPRESSION' + You can cancel execution of a function call with the 'return' + command. If you give an EXPRESSION argument, its value is used as + the function's return value. + + When you use 'return', GDB discards the selected stack frame (and all +frames within it). You can think of this as making the discarded frame +return prematurely. If you wish to specify a value to be returned, give +that value as the argument to 'return'. + + This pops the selected stack frame (*note Selecting a Frame: +Selection.), and any other frames inside of it, leaving its caller as +the innermost remaining frame. That frame becomes selected. The +specified value is stored in the registers used for returning values of +functions. + + The 'return' command does not resume execution; it leaves the program +stopped in the state that would exist if the function had just returned. +In contrast, the 'finish' command (*note Continuing and Stepping: +Continuing and Stepping.) resumes execution until the selected stack +frame returns naturally. + + GDB needs to know how the EXPRESSION argument should be set for the +inferior. The concrete registers assignment depends on the OS ABI and +the type being returned by the selected stack frame. For example it is +common for OS ABI to return floating point values in FPU registers while +integer values in CPU registers. Still some ABIs return even floating +point values in CPU registers. Larger integer widths (such as 'long +long int') also have specific placement rules. GDB already knows the OS +ABI from its current target so it needs to find out also the type being +returned to make the assignment into the right register(s). + + Normally, the selected stack frame has debug info. GDB will always +use the debug info instead of the implicit type of EXPRESSION when the +debug info is available. For example, if you type 'return -1', and the +function in the current stack frame is declared to return a 'long long +int', GDB transparently converts the implicit 'int' value of -1 into a +'long long int': + + Breakpoint 1, func () at gdb.base/return-nodebug.c:29 + 29 return 31; + (gdb) return -1 + Make func return now? (y or n) y + #0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 + 43 printf ("result=%lld\n", func ()); + (gdb) + + However, if the selected stack frame does not have a debug info, +e.g., if the function was compiled without debug info, GDB has to find +out the type to return from user. Specifying a different type by +mistake may set the value in different inferior registers than the +caller code expects. For example, typing 'return -1' with its implicit +type 'int' would set only a part of a 'long long int' result for a debug +info less function (on 32-bit architectures). Therefore the user is +required to specify the return type by an appropriate cast explicitly: + + Breakpoint 2, 0x0040050b in func () + (gdb) return -1 + Return value type not available for selected stack frame. + Please use an explicit cast of the value to return. + (gdb) return (long long int) -1 + Make selected stack frame return now? (y or n) y + #0 0x00400526 in main () + (gdb) + + +File: gdb.info, Node: Calling, Next: Patching, Prev: Returning, Up: Altering + +17.5 Calling Program Functions +============================== + +'print EXPR' + Evaluate the expression EXPR and display the resulting value. The + expression may include calls to functions in the program being + debugged. + +'call EXPR' + Evaluate the expression EXPR without displaying 'void' returned + values. + + You can use this variant of the 'print' command if you want to + execute a function from your program that does not return anything + (a.k.a. "a void function"), but without cluttering the output with + 'void' returned values that GDB will otherwise print. If the + result is not void, it is printed and saved in the value history. + + It is possible for the function you call via the 'print' or 'call' +command to generate a signal (e.g., if there's a bug in the function, or +if you passed it incorrect arguments). What happens in that case is +controlled by the 'set unwind-on-signal' command. + + Similarly, with a C++ program it is possible for the function you +call via the 'print' or 'call' command to generate an exception that is +not handled due to the constraints of the dummy frame. In this case, +any exception that is raised in the frame, but has an out-of-frame +exception handler will not be found. GDB builds a dummy-frame for the +inferior function call, and the unwinder cannot seek for exception +handlers outside of this dummy-frame. What happens in that case is +controlled by the 'set unwind-on-terminating-exception' command. + +'set unwind-on-signal' + Set unwinding of the stack if a signal is received while in a + function that GDB called in the program being debugged. If set to + on, GDB unwinds the stack it created for the call and restores the + context to what it was before the call. If set to off (the + default), GDB stops in the frame where the signal was received. + + The command 'set unwindonsignal' is an alias for this command, and + is maintained for backward compatibility. + +'show unwind-on-signal' + Show the current setting of stack unwinding in the functions called + by GDB. + + The command 'show unwindonsignal' is an alias for this command, and + is maintained for backward compatibility. + +'set unwind-on-terminating-exception' + Set unwinding of the stack if a C++ exception is raised, but left + unhandled while in a function that GDB called in the program being + debugged. If set to on (the default), GDB unwinds the stack it + created for the call and restores the context to what it was before + the call. If set to off, GDB the exception is delivered to the + default C++ exception handler and the inferior terminated. + +'show unwind-on-terminating-exception' + Show the current setting of stack unwinding in the functions called + by GDB. + +'set unwind-on-timeout' + Set unwinding of the stack if a function called from GDB times out. + If set to 'off' (the default), GDB stops in the frame where the + timeout occurred. If set to 'on', GDB unwinds the stack it created + for the call and restores the context to what it was before the + call. + +'show unwind-on-timeout' + Show whether GDB will unwind the stack if a function called from + GDB times out. + +'set may-call-functions' + Set permission to call functions in the program. This controls + whether GDB will attempt to call functions in the program, such as + with expressions in the 'print' command. It defaults to 'on'. + + To call a function in the program, GDB has to temporarily modify + the state of the inferior. This has potentially undesired side + effects. Also, having GDB call nested functions is likely to be + erroneous and may even crash the program being debugged. You can + avoid such hazards by forbidding GDB from calling functions in the + program being debugged. If calling functions in the program is + forbidden, GDB will throw an error when a command (such as printing + an expression) starts a function call in the program. + +'show may-call-functions' + Show permission to call functions in the program. + + When calling a function within a program, it is possible that the +program could enter a state from which the called function may never +return. If this happens then it is possible to interrupt the function +call by typing the interrupt character (often 'Ctrl-c'). + + If a called function is interrupted for any reason, including hitting +a breakpoint, or triggering a watchpoint, and the stack is not unwound +due to 'set unwind-on-terminating-exception on', 'set unwind-on-timeout +on', or 'set unwind-on-signal on' (*note stack unwind settings::), then +the dummy-frame, created by GDB to facilitate the call to the program +function, will be visible in the backtrace, for example frame '#3' in +the following backtrace: + + (gdb) backtrace + #0 0x00007ffff7b3d1e7 in nanosleep () from /lib64/libc.so.6 + #1 0x00007ffff7b3d11e in sleep () from /lib64/libc.so.6 + #2 0x000000000040113f in deadlock () at test.cc:13 + #3 + #4 breakpt () at test.cc:20 + #5 0x0000000000401151 in main () at test.cc:25 + + At this point it is possible to examine the state of the inferior +just like any other stop. + + Depending on why the function was interrupted then it may be possible +to resume the inferior (using commands like 'continue', 'step', etc). +In this case, when the inferior finally returns to the dummy-frame, GDB +will once again halt the inferior. + + On targets that support asynchronous execution (*note Background +Execution::) GDB can place a timeout on any functions called from GDB. +If the timeout expires and the function call is still ongoing, then GDB +will interrupt the program. + + If a function called from GDB is interrupted by a timeout, then by +default the inferior is left in the frame where the timeout occurred, +this behavior can be adjusted with 'set unwind-on-timeout' (*note set +unwind-on-timeout::). + + For targets that don't support asynchronous execution (*note +Background Execution::) then timeouts for functions called from GDB are +not supported, the timeout settings described below will be treated as +'unlimited', meaning GDB will wait indefinitely for function call to +complete, unless interrupted by the user using 'Ctrl-C'. + +'set direct-call-timeout SECONDS' + Set the timeout used when calling functions in the program to + SECONDS, which should be an integer greater than zero, or the + special value 'unlimited', which indicates no timeout should be + used. The default for this setting is 'unlimited'. + + This setting is used when the user calls a function directly from + the command prompt, for example with a 'call' or 'print' command. + + This setting only works for targets that support asynchronous + execution (*note Background Execution::), for any other target the + setting is treated as 'unlimited'. + +'show direct-call-timeout' + Show the timeout used when calling functions in the program with a + 'call' or 'print' command. + + It is also possible to call functions within the program from the +condition of a conditional breakpoint (*note Break Conditions: +Conditions.). A different setting controls the timeout used for +function calls made from a breakpoint condition. + +'set indirect-call-timeout SECONDS' + Set the timeout used when calling functions in the program from a + breakpoint or watchpoint condition to SECONDS, which should be an + integer greater than zero, or the special value 'unlimited', which + indicates no timeout should be used. The default for this setting + is '30' seconds. + + This setting only works for targets that support asynchronous + execution (*note Background Execution::), for any other target the + setting is treated as 'unlimited'. + + If a function called from a breakpoint or watchpoint condition + times out, then GDB will stop at the point where the timeout + occurred. The breakpoint condition evaluation will be abandoned. + +'show indirect-call-timeout' + Show the timeout used when calling functions in the program from a + breakpoint or watchpoint condition. + +17.5.1 Calling functions with no debug info +------------------------------------------- + +Sometimes, a function you wish to call is missing debug information. In +such case, GDB does not know the type of the function, including the +types of the function's parameters. To avoid calling the inferior +function incorrectly, which could result in the called function +functioning erroneously and even crash, GDB refuses to call the function +unless you tell it the type of the function. + + For prototyped (i.e. ANSI/ISO style) functions, there are two ways to +do that. The simplest is to cast the call to the function's declared +return type. For example: + + (gdb) p getenv ("PATH") + 'getenv' has unknown return type; cast the call to its declared return type + (gdb) p (char *) getenv ("PATH") + $1 = 0x7fffffffe7ba "/usr/local/bin:/"... + + Casting the return type of a no-debug function is equivalent to +casting the function to a pointer to a prototyped function that has a +prototype that matches the types of the passed-in arguments, and calling +that. I.e., the call above is equivalent to: + + (gdb) p ((char * (*) (const char *)) getenv) ("PATH") + +and given this prototyped C or C++ function with float parameters: + + float multiply (float v1, float v2) { return v1 * v2; } + +these calls are equivalent: + + (gdb) p (float) multiply (2.0f, 3.0f) + (gdb) p ((float (*) (float, float)) multiply) (2.0f, 3.0f) + + If the function you wish to call is declared as unprototyped (i.e. +old K&R style), you must use the cast-to-function-pointer syntax, so +that GDB knows that it needs to apply default argument promotions +(promote float arguments to double). *Note float promotion: ABI. For +example, given this unprototyped C function with float parameters, and +no debug info: + + float + multiply_noproto (v1, v2) + float v1, v2; + { + return v1 * v2; + } + +you call it like this: + + (gdb) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f) + + +File: gdb.info, Node: Patching, Next: Compiling and Injecting Code, Prev: Calling, Up: Altering + +17.6 Patching Programs +====================== + +By default, GDB opens the file containing your program's executable code +(or the corefile) read-only. This prevents accidental alterations to +machine code; but it also prevents you from intentionally patching your +program's binary. + + If you'd like to be able to patch the binary, you can specify that +explicitly with the 'set write' command. For example, you might want to +turn on internal debugging flags, or even to make emergency repairs. + +'set write on' +'set write off' + If you specify 'set write on', GDB opens executable and core files + for both reading and writing; if you specify 'set write off' (the + default), GDB opens them read-only. + + If you have already loaded a file, you must load it again (using + the 'exec-file' or 'core-file' command) after changing 'set write', + for your new setting to take effect. + +'show write' + Display whether executable files and core files are opened for + writing as well as reading. + + +File: gdb.info, Node: Compiling and Injecting Code, Prev: Patching, Up: Altering + +17.7 Compiling and injecting code in GDB +======================================== + +GDB supports on-demand compilation and code injection into programs +running under GDB. GCC 5.0 or higher built with 'libcc1.so' must be +installed for this functionality to be enabled. This functionality is +implemented with the following commands. + +'compile code SOURCE-CODE' +'compile code -raw -- SOURCE-CODE' + Compile SOURCE-CODE with the compiler language found as the current + language in GDB (*note Languages::). If compilation and injection + is not supported with the current language specified in GDB, or the + compiler does not support this feature, an error message will be + printed. If SOURCE-CODE compiles and links successfully, GDB will + load the object-code emitted, and execute it within the context of + the currently selected inferior. It is important to note that the + compiled code is executed immediately. After execution, the + compiled code is removed from GDB and any new types or variables + you have defined will be deleted. + + The command allows you to specify SOURCE-CODE in two ways. The + simplest method is to provide a single line of code to the command. + E.g.: + + compile code printf ("hello world\n"); + + If you specify options on the command line as well as source code, + they may conflict. The '--' delimiter can be used to separate + options from actual source code. E.g.: + + compile code -r -- printf ("hello world\n"); + + Alternatively you can enter source code as multiple lines of text. + To enter this mode, invoke the 'compile code' command without any + text following the command. This will start the multiple-line + editor and allow you to type as many lines of source code as + required. When you have completed typing, enter 'end' on its own + line to exit the editor. + + compile code + >printf ("hello\n"); + >printf ("world\n"); + >end + + Specifying '-raw', prohibits GDB from wrapping the provided + SOURCE-CODE in a callable scope. In this case, you must specify + the entry point of the code by defining a function named + '_gdb_expr_'. The '-raw' code cannot access variables of the + inferior. Using '-raw' option may be needed for example when + SOURCE-CODE requires '#include' lines which may conflict with + inferior symbols otherwise. + +'compile file FILENAME' +'compile file -raw FILENAME' + Like 'compile code', but take the source code from FILENAME. + + compile file /home/user/example.c + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'compile print [[OPTIONS] --] EXPR' +'compile print [[OPTIONS] --] /F EXPR' + Compile and execute EXPR with the compiler language found as the + current language in GDB (*note Languages::). By default the value + of EXPR is printed in a format appropriate to its data type; you + can choose a different format by specifying '/F', where F is a + letter specifying the format; see *note Output Formats: Output + Formats. The 'compile print' command accepts the same options as + the 'print' command; see *note print options::. + +'compile print [[OPTIONS] --]' +'compile print [[OPTIONS] --] /F' + Alternatively you can enter the expression (source code producing + it) as multiple lines of text. To enter this mode, invoke the + 'compile print' command without any text following the command. + This will start the multiple-line editor. + +The process of compiling and injecting the code can be inspected using: + +'set debug compile' + Turns on or off display of GDB process of compiling and injecting + the code. The default is off. + +'show debug compile' + Displays the current state of displaying GDB process of compiling + and injecting the code. + +'set debug compile-cplus-types' + Turns on or off the display of C++ type conversion debugging + information. The default is off. + +'show debug compile-cplus-types' + Displays the current state of displaying debugging information for + C++ type conversion. + +17.7.1 Compilation options for the 'compile' command +---------------------------------------------------- + +GDB needs to specify the right compilation options for the code to be +injected, in part to make its ABI compatible with the inferior and in +part to make the injected code compatible with GDB's injecting process. + +The options used, in increasing precedence: + +target architecture and OS options ('gdbarch') + These options depend on target processor type and target operating + system, usually they specify at least 32-bit ('-m32') or 64-bit + ('-m64') compilation option. + +compilation options recorded in the target + GCC (since version 4.7) stores the options used for compilation + into 'DW_AT_producer' part of DWARF debugging information according + to the GCC option '-grecord-gcc-switches'. One has to explicitly + specify '-g' during inferior compilation otherwise GCC produces no + DWARF. This feature is only relevant for platforms where '-g' + produces DWARF by default, otherwise one may try to enforce DWARF + by using '-gdwarf-4'. + +compilation options set by 'set compile-args' + +You can override compilation options using the following command: + +'set compile-args' + Set compilation options used for compiling and injecting code with + the 'compile' commands. These options override any conflicting + ones from the target architecture and/or options stored during + inferior compilation. + +'show compile-args' + Displays the current state of compilation options override. This + does not show all the options actually used during compilation, use + *note set debug compile:: for that. + +17.7.2 Caveats when using the 'compile' command +----------------------------------------------- + +There are a few caveats to keep in mind when using the 'compile' +command. As the caveats are different per language, the table below +highlights specific issues on a per language basis. + +C code examples and caveats + When the language in GDB is set to 'C', the compiler will attempt + to compile the source code with a 'C' compiler. The source code + provided to the 'compile' command will have much the same access to + variables and types as it normally would if it were part of the + program currently being debugged in GDB. + + Below is a sample program that forms the basis of the examples that + follow. This program has been compiled and loaded into GDB, much + like any other normal debugging session. + + void function1 (void) + { + int i = 42; + printf ("function 1\n"); + } + + void function2 (void) + { + int j = 12; + function1 (); + } + + int main(void) + { + int k = 6; + int *p; + function2 (); + return 0; + } + + For the purposes of the examples in this section, the program above + has been compiled, loaded into GDB, stopped at the function 'main', + and GDB is awaiting input from the user. + + To access variables and types for any program in GDB, the program + must be compiled and packaged with debug information. The + 'compile' command is not an exception to this rule. Without debug + information, you can still use the 'compile' command, but you will + be very limited in what variables and types you can access. + + So with that in mind, the example above has been compiled with + debug information enabled. The 'compile' command will have access + to all variables and types (except those that may have been + optimized out). Currently, as GDB has stopped the program in the + 'main' function, the 'compile' command would have access to the + variable 'k'. You could invoke the 'compile' command and type some + source code to set the value of 'k'. You can also read it, or do + anything with that variable you would normally do in 'C'. Be aware + that changes to inferior variables in the 'compile' command are + persistent. In the following example: + + compile code k = 3; + + the variable 'k' is now 3. It will retain that value until + something else in the example program changes it, or another + 'compile' command changes it. + + Normal scope and access rules apply to source code compiled and + injected by the 'compile' command. In the example, the variables + 'j' and 'k' are not accessible yet, because the program is + currently stopped in the 'main' function, where these variables are + not in scope. Therefore, the following command + + compile code j = 3; + + will result in a compilation error message. + + Once the program is continued, execution will bring these variables + in scope, and they will become accessible; then the code you + specify via the 'compile' command will be able to access them. + + You can create variables and types with the 'compile' command as + part of your source code. Variables and types that are created as + part of the 'compile' command are not visible to the rest of the + program for the duration of its run. This example is valid: + + compile code int ff = 5; printf ("ff is %d\n", ff); + + However, if you were to type the following into GDB after that + command has completed: + + compile code printf ("ff is %d\n'', ff); + + a compiler error would be raised as the variable 'ff' no longer + exists. Object code generated and injected by the 'compile' + command is removed when its execution ends. Caution is advised + when assigning to program variables values of variables created by + the code submitted to the 'compile' command. This example is + valid: + + compile code int ff = 5; k = ff; + + The value of the variable 'ff' is assigned to 'k'. The variable + 'k' does not require the existence of 'ff' to maintain the value it + has been assigned. However, pointers require particular care in + assignment. If the source code compiled with the 'compile' command + changed the address of a pointer in the example program, perhaps to + a variable created in the 'compile' command, that pointer would + point to an invalid location when the command exits. The following + example would likely cause issues with your debugged program: + + compile code int ff = 5; p = &ff; + + In this example, 'p' would point to 'ff' when the 'compile' command + is executing the source code provided to it. However, as variables + in the (example) program persist with their assigned values, the + variable 'p' would point to an invalid location when the command + exists. A general rule should be followed in that you should + either assign 'NULL' to any assigned pointers, or restore a valid + location to the pointer before the command exits. + + Similar caution must be exercised with any structs, unions, and + typedefs defined in 'compile' command. Types defined in the + 'compile' command will no longer be available in the next 'compile' + command. Therefore, if you cast a variable to a type defined in + the 'compile' command, care must be taken to ensure that any future + need to resolve the type can be achieved. + + (gdb) compile code static struct a { int a; } v = { 42 }; argv = &v; + (gdb) compile code printf ("%d\n", ((struct a *) argv)->a); + gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ + Compilation failed. + (gdb) compile code struct a { int a; }; printf ("%d\n", ((struct a *) argv)->a); + 42 + + Variables that have been optimized away by the compiler are not + accessible to the code submitted to the 'compile' command. Access + to those variables will generate a compiler error which GDB will + print to the console. + +17.7.3 Compiler search for the 'compile' command +------------------------------------------------ + +GDB needs to find GCC for the inferior being debugged which may not be +obvious for remote targets of different architecture than where GDB is +running. Environment variable 'PATH' on GDB host is searched for GCC +binary matching the target architecture and operating system. This +search can be overridden by 'set compile-gcc' GDB command below. 'PATH' +is taken from shell that executed GDB, it is not the value set by GDB +command 'set environment'). *Note Environment::. + + Specifically 'PATH' is searched for binaries matching regular +expression 'ARCH(-[^-]*)?-OS-gcc' according to the inferior target being +debugged. ARCH is processor name -- multiarch is supported, so for +example both 'i386' and 'x86_64' targets look for pattern +'(x86_64|i.86)' and both 's390' and 's390x' targets look for pattern +'s390x?'. OS is currently supported only for pattern 'linux(-gnu)?'. + + On Posix hosts the compiler driver GDB needs to find also shared +library 'libcc1.so' from the compiler. It is searched in default shared +library search path (overridable with usual environment variable +'LD_LIBRARY_PATH'), unrelated to 'PATH' or 'set compile-gcc' settings. +Contrary to it 'libcc1plugin.so' is found according to the installation +of the found compiler -- as possibly specified by the 'set compile-gcc' +command. + +'set compile-gcc' + Set compilation command used for compiling and injecting code with + the 'compile' commands. If this option is not set (it is set to an + empty string), the search described above will occur -- that is the + default. + +'show compile-gcc' + Displays the current compile command GCC driver filename. If set, + it is the main command 'gcc', found usually for example under name + 'x86_64-linux-gnu-gcc'. + + +File: gdb.info, Node: GDB Files, Next: Targets, Prev: Altering, Up: Top + +18 GDB Files +************ + +GDB needs to know the file name of the program to be debugged, both in +order to read its symbol table and in order to start your program. To +debug a core dump of a previous run, you must also tell GDB the name of +the core dump file. + +* Menu: + +* Files:: Commands to specify files +* File Caching:: Information about GDB's file caching +* Separate Debug Files:: Debugging information in separate files +* MiniDebugInfo:: Debugging information in a special section +* Index Files:: Index files speed up GDB +* Debug Names:: Extensions to .debug_names +* Symbol Errors:: Errors reading symbol files +* Data Files:: GDB data files + + +File: gdb.info, Node: Files, Next: File Caching, Up: GDB Files + +18.1 Commands to Specify Files +============================== + +You may want to specify executable and core dump file names. The usual +way to do this is at start-up time, using the arguments to GDB's +start-up commands (*note Getting In and Out of GDB: Invocation.). + + Occasionally it is necessary to change to a different file during a +GDB session. Or you may run GDB and forget to specify a file you want +to use. Or you are debugging a remote target via 'gdbserver' (*note +file: Server.). In these situations the GDB commands to specify new +files are useful. + +'file FILENAME' + Use FILENAME as the program to be debugged. It is read for its + symbols and for the contents of pure memory. It is also the + program executed when you use the 'run' command. If you do not + specify a directory and the file is not found in the GDB working + directory, GDB uses the environment variable 'PATH' as a list of + directories to search, just as the shell does when looking for a + program to run. You can change the value of this variable, for + both GDB and your program, using the 'path' command. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + + You can load unlinked object '.o' files into GDB using the 'file' + command. You will not be able to "run" an object file, but you can + disassemble functions and inspect variables. Also, if the + underlying BFD functionality supports it, you could use 'gdb + -write' to patch object files using this technique. Note that GDB + can neither interpret nor modify relocations in this case, so + branches and some initialized variables will appear to go to the + wrong place. But this feature is still handy from time to time. + +'file' + 'file' with no argument makes GDB discard any information it has on + both executable file and the symbol table. + +'exec-file [ FILENAME ]' + Specify that the program to be run (but not the symbol table) is + found in FILENAME. GDB searches the environment variable 'PATH' if + necessary to locate your program. Omitting FILENAME means to + discard information on the executable file. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'symbol-file [ FILENAME [ -o OFFSET ]]' + Read symbol table information from file FILENAME. 'PATH' is + searched when necessary. Use the 'file' command to get both symbol + table and program to run from the same file. + + If an optional OFFSET is specified, it is added to the start + address of each section in the symbol file. This is useful if the + program is relocated at runtime, such as the Linux kernel with + kASLR enabled. + + 'symbol-file' with no argument clears out GDB information on your + program's symbol table. + + The 'symbol-file' command causes GDB to forget the contents of some + breakpoints and auto-display expressions. This is because they may + contain pointers to the internal data recording symbols and data + types, which are part of the old symbol table data being discarded + inside GDB. + + 'symbol-file' does not repeat if you press again after + executing it once. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + + When GDB is configured for a particular environment, it understands + debugging information in whatever format is the standard generated + for that environment; you may use either a GNU compiler, or other + compilers that adhere to the local conventions. Best results are + usually obtained from GNU compilers; for example, using 'GCC' you + can generate debugging information for optimized code. + + For most kinds of object files, with the exception of old SVR3 + systems using COFF, the 'symbol-file' command does not normally + read the symbol table in full right away. Instead, it scans the + symbol table quickly to find which source files and which symbols + are present. The details are read later, one source file at a + time, as they are needed. + + The purpose of this two-stage reading strategy is to make GDB start + up faster. For the most part, it is invisible except for + occasional pauses while the symbol table details for a particular + source file are being read. (The 'set verbose' command can turn + these pauses into messages if desired. *Note Optional Warnings and + Messages: Messages/Warnings.) + + We have not implemented the two-stage strategy for COFF yet. When + the symbol table is stored in COFF format, 'symbol-file' reads the + symbol table data in full right away. Note that "stabs-in-COFF" + still does the two-stage strategy, since the debug info is actually + in stabs format. + +'symbol-file [ -readnow ] FILENAME' +'file [ -readnow ] FILENAME' + You can override the GDB two-stage strategy for reading symbol + tables by using the '-readnow' option with any of the commands that + load symbol table information, if you want to be sure GDB has the + entire symbol table available. + +'symbol-file [ -readnever ] FILENAME' +'file [ -readnever ] FILENAME' + You can instruct GDB to never read the symbolic information + contained in FILENAME by using the '-readnever' option. *Note + --readnever::. + +'core-file [FILENAME]' +'core' + Specify the whereabouts of a core dump file to be used as the + "contents of memory". Traditionally, core files contain only some + parts of the address space of the process that generated them; GDB + can access the executable file itself for other parts. + + 'core-file' with no argument specifies that no core file is to be + used. + + Note that the core file is ignored when your program is actually + running under GDB. So, if you have been running your program and + you wish to debug a core file instead, you must kill the subprocess + in which the program is running. To do this, use the 'kill' + command (*note Killing the Child Process: Kill Process.). + +'add-symbol-file FILENAME [ -readnow | -readnever ] [ -o OFFSET ] [ TEXTADDRESS ] [ -s SECTION ADDRESS ... ]' + The 'add-symbol-file' command reads additional symbol table + information from the file FILENAME. You would use this command + when FILENAME has been dynamically loaded (by some other means) + into the program that is running. The TEXTADDRESS parameter gives + the memory address at which the file's text section has been + loaded. You can additionally specify the base address of other + sections using an arbitrary number of '-s SECTION ADDRESS' pairs. + If a section is omitted, GDB will use its default addresses as + found in FILENAME. Any ADDRESS or TEXTADDRESS can be given as an + expression. + + If an optional OFFSET is specified, it is added to the start + address of each section, except those for which the address was + specified explicitly. + + The symbol table of the file FILENAME is added to the symbol table + originally read with the 'symbol-file' command. You can use the + 'add-symbol-file' command any number of times; the new symbol data + thus read is kept in addition to the old. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + + Changes can be reverted using the command 'remove-symbol-file'. + + Although FILENAME is typically a shared library file, an executable + file, or some other object file which has been fully relocated for + loading into a process, you can also load symbolic information from + relocatable '.o' files, as long as: + + * the file's symbolic information refers only to linker symbols + defined in that file, not to symbols defined by other object + files, + * every section the file's symbolic information refers to has + actually been loaded into the inferior, as it appears in the + file, and + * you can determine the address at which every section was + loaded, and provide these to the 'add-symbol-file' command. + + Some embedded operating systems, like Sun Chorus and VxWorks, can + load relocatable files into an already running program; such + systems typically make the requirements above easy to meet. + However, it's important to recognize that many native systems use + complex link procedures ('.linkonce' section factoring and C++ + constructor table assembly, for example) that make the requirements + difficult to meet. In general, one cannot assume that using + 'add-symbol-file' to read a relocatable object file's symbolic + information will have the same effect as linking the relocatable + object file into the program in the normal way. + + 'add-symbol-file' does not repeat if you press after using + it. + +'remove-symbol-file FILENAME' +'remove-symbol-file -a ADDRESS' + Remove a symbol file added via the 'add-symbol-file' command. The + file to remove can be identified by its FILENAME or by an ADDRESS + that lies within the boundaries of this symbol file in memory. + Example: + + (gdb) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 + add symbol table from file "/home/user/gdb/mylib.so" at + .text_addr = 0x7ffff7ff9480 + (y or n) y + Reading symbols from /home/user/gdb/mylib.so... + (gdb) remove-symbol-file -a 0x7ffff7ff9480 + Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y + (gdb) + + The ADDRESS can be any expression which evaluates to an address. + + 'remove-symbol-file' does not repeat if you press after using + it. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'add-symbol-file-from-memory ADDRESS' + Load symbols from the given ADDRESS in a dynamically loaded object + file whose image is mapped directly into the inferior's memory. + For example, the Linux kernel maps a 'syscall DSO' into each + process's address space; this DSO provides kernel-specific code for + some system calls. The argument can be any expression whose + evaluation yields the address of the file's shared object file + header. For this command to work, you must have used 'symbol-file' + or 'exec-file' commands in advance. + +'section SECTION ADDR' + The 'section' command changes the base address of the named SECTION + of the exec file to ADDR. This can be used if the exec file does + not contain section addresses, (such as in the 'a.out' format), or + when the addresses specified in the file itself are wrong. Each + section must be changed separately. The 'info files' command, + described below, lists all the sections and their addresses. + +'info files' +'info target' + 'info files' and 'info target' are synonymous; both print the + current target (*note Specifying a Debugging Target: Targets.), + including the names of the executable and core dump files currently + in use by GDB, and the files from which symbols were loaded. The + command 'help target' lists all possible targets rather than + current ones. + +'maint info sections [-all-objects] [FILTER-LIST]' + Another command that can give you extra information about program + sections is 'maint info sections'. In addition to the section + information displayed by 'info files', this command displays the + flags and file offset of each section in the executable and core + dump files. + + When '-all-objects' is passed then sections from all loaded object + files, including shared libraries, are printed. + + The optional FILTER-LIST is a space separated list of filter + keywords. Sections that match any one of the filter criteria will + be printed. There are two types of filter: + + 'SECTION-NAME' + Display information about any section named SECTION-NAME. + 'SECTION-FLAG' + Display information for any section with SECTION-FLAG. The + section flags that GDB currently knows about are: + 'ALLOC' + Section will have space allocated in the process when + loaded. Set for all sections except those containing + debug information. + 'LOAD' + Section will be loaded from the file into the child + process memory. Set for pre-initialized code and data, + clear for '.bss' sections. + 'RELOC' + Section needs to be relocated before loading. + 'READONLY' + Section cannot be modified by the child process. + 'CODE' + Section contains executable code only. + 'DATA' + Section contains data only (no executable code). + 'ROM' + Section will reside in ROM. + 'CONSTRUCTOR' + Section contains data for constructor/destructor lists. + 'HAS_CONTENTS' + Section is not empty. + 'NEVER_LOAD' + An instruction to the linker to not output the section. + 'COFF_SHARED_LIBRARY' + A notification to the linker that the section contains + COFF shared library information. + 'IS_COMMON' + Section contains common symbols. + +'maint info target-sections' + This command prints GDB's internal section table. For each target + GDB maintains a table containing the allocatable sections from all + currently mapped objects, along with information about where the + section is mapped. + +'set trust-readonly-sections on' + Tell GDB that readonly sections in your object file really are + read-only (i.e. that their contents will not change). In that + case, GDB can fetch values from these sections out of the object + file, rather than from the target program. For some targets + (notably embedded ones), this can be a significant enhancement to + debugging performance. + + The default is off. + +'set trust-readonly-sections off' + Tell GDB not to trust readonly sections. This means that the + contents of the section might change while the program is running, + and must therefore be fetched from the target when needed. + +'show trust-readonly-sections' + Show the current setting of trusting readonly sections. + + All file-specifying commands allow both absolute and relative file +names as arguments. GDB always converts the file name to an absolute +file name and remembers it that way. + + GDB supports GNU/Linux, MS-Windows, SunOS, Darwin/Mach-O, SVr4, IBM +RS/6000 AIX, FDPIC (FR-V), and DSBT (TIC6X) shared libraries. + + On MS-Windows GDB must be linked with the Expat library to support +shared libraries. *Note Expat::. + + GDB automatically loads symbol definitions from shared libraries when +you use the 'run' command, or when you examine a core file. (Before you +issue the 'run' command, GDB does not understand references to a +function in a shared library, however--unless you are debugging a core +file). + + There are times, however, when you may wish to not automatically load +symbol definitions from shared libraries, such as when they are +particularly large or there are many of them. + + To control the automatic loading of shared library symbols, use the +commands: + +'set auto-solib-add MODE' + If MODE is 'on', symbols from all shared object libraries will be + loaded automatically when the inferior begins execution, you attach + to an independently started inferior, or when the dynamic linker + informs GDB that a new library has been loaded. If MODE is 'off', + symbols must be loaded manually, using the 'sharedlibrary' command. + The default value is 'on'. + + If your program uses lots of shared libraries with debug info that + takes large amounts of memory, you can decrease the GDB memory + footprint by preventing it from automatically loading the symbols + from shared libraries. To that end, type 'set auto-solib-add off' + before running the inferior, then load each library whose debug + symbols you do need with 'sharedlibrary REGEXP', where REGEXP is a + regular expression that matches the libraries whose symbols you + want to be loaded. + +'show auto-solib-add' + Display the current autoloading mode. + + To explicitly load shared library symbols, use the 'sharedlibrary' +command: + +'info share REGEX' +'info sharedlibrary REGEX' + Print the names of the shared libraries which are currently loaded + that match REGEX. If REGEX is omitted then print all shared + libraries that are loaded. + +'info dll REGEX' + This is an alias of 'info sharedlibrary'. + +'sharedlibrary REGEX' +'share REGEX' + Load shared object library symbols for files matching a Unix + regular expression. As with files loaded automatically, it only + loads shared libraries required by your program for a core file or + after typing 'run'. If REGEX is omitted all shared libraries + required by your program are loaded. + +'nosharedlibrary' + Unload all shared object library symbols. This discards all + symbols that have been loaded from all shared libraries. Symbols + from shared libraries that were loaded by explicit user requests + are not discarded. + + Sometimes you may wish that GDB stops and gives you control when any +of shared library events happen. The best way to do this is to use +'catch load' and 'catch unload' (*note Set Catchpoints::). + + GDB also supports the 'set stop-on-solib-events' command for this. +This command exists for historical reasons. It is less useful than +setting a catchpoint, because it does not allow for conditions or +commands as a catchpoint does. + +'set stop-on-solib-events' + This command controls whether GDB should give you control when the + dynamic linker notifies it about some shared library event. The + most common event of interest is loading or unloading of a new + shared library. + +'show stop-on-solib-events' + Show whether GDB stops and gives you control when shared library + events happen. + + Shared libraries are also supported in many cross or remote debugging +configurations. GDB needs to have access to the target's libraries; +this can be accomplished either by providing copies of the libraries on +the host system, or by asking GDB to automatically retrieve the +libraries from the target. If copies of the target libraries are +provided, they need to be the same as the target libraries, although the +copies on the target can be stripped as long as the copies on the host +are not. + + For remote debugging, you need to tell GDB where the target libraries +are, so that it can load the correct copies--otherwise, it may try to +load the host's libraries. GDB has two variables to specify the search +directories for target libraries. + +'set sysroot PATH' + Use PATH as the system root for the program being debugged. Any + absolute shared library paths will be prefixed with PATH; many + runtime loaders store the absolute paths to the shared library in + the target program's memory. When starting processes remotely, and + when attaching to already-running processes (local or remote), + their executable filenames will be prefixed with PATH if reported + to GDB as absolute by the operating system. If you use 'set + sysroot' to find executables and shared libraries, they need to be + laid out in the same way that they are on the target, with e.g. a + '/bin', '/lib' and '/usr/lib' hierarchy under PATH. + + If PATH starts with the sequence 'target:' and the target system is + remote then GDB will retrieve the target binaries from the remote + system. This is only supported when using a remote target that + supports the 'remote get' command (*note Sending files to a remote + system: File Transfer.). The part of PATH following the initial + 'target:' (if present) is used as system root prefix on the remote + file system. If PATH starts with the sequence 'remote:' this is + converted to the sequence 'target:' by 'set sysroot'(1). If you + want to specify a local system root using a directory that happens + to be named 'target:' or 'remote:', you need to use some equivalent + variant of the name like './target:'. + + For targets with an MS-DOS based filesystem, such as MS-Windows, + GDB tries prefixing a few variants of the target absolute file name + with PATH. But first, on Unix hosts, GDB converts all backslash + directory separators into forward slashes, because the backslash is + not a directory separator on Unix: + + c:\foo\bar.dll => c:/foo/bar.dll + + Then, GDB attempts prefixing the target file name with PATH, and + looks for the resulting file name in the host file system: + + c:/foo/bar.dll => /path/to/sysroot/c:/foo/bar.dll + + If that does not find the binary, GDB tries removing the ':' + character from the drive spec, both for convenience, and, for the + case of the host file system not supporting file names with colons: + + c:/foo/bar.dll => /path/to/sysroot/c/foo/bar.dll + + This makes it possible to have a system root that mirrors a target + with more than one drive. E.g., you may want to setup your local + copies of the target system shared libraries like so (note 'c' vs + 'z'): + + /path/to/sysroot/c/sys/bin/foo.dll + /path/to/sysroot/c/sys/bin/bar.dll + /path/to/sysroot/z/sys/bin/bar.dll + + and point the system root at '/path/to/sysroot', so that GDB can + find the correct copies of both 'c:\sys\bin\foo.dll', and + 'z:\sys\bin\bar.dll'. + + If that still does not find the binary, GDB tries removing the + whole drive spec from the target file name: + + c:/foo/bar.dll => /path/to/sysroot/foo/bar.dll + + This last lookup makes it possible to not care about the drive + name, if you don't want or need to. + + The 'set solib-absolute-prefix' command is an alias for 'set + sysroot'. + + You can set the default system root by using the configure-time + '--with-sysroot' option. If the system root is inside GDB's + configured binary prefix (set with '--prefix' or '--exec-prefix'), + then the default system root will be updated automatically if the + installed GDB is moved to a new location. + +'show sysroot' + Display the current executable and shared library prefix. + +'set solib-search-path PATH' + If this variable is set, PATH is a colon-separated list of + directories to search for shared libraries. 'solib-search-path' is + used after 'sysroot' fails to locate the library, or if the path to + the library is relative instead of absolute. If you want to use + 'solib-search-path' instead of 'sysroot', be sure to set 'sysroot' + to a nonexistent directory to prevent GDB from finding your host's + libraries. 'sysroot' is preferred; setting it to a nonexistent + directory may interfere with automatic loading of shared library + symbols. + +'show solib-search-path' + Display the current shared library search path. + +'set target-file-system-kind KIND' + Set assumed file system kind for target reported file names. + + Shared library file names as reported by the target system may not + make sense as is on the system GDB is running on. For example, + when remote debugging a target that has MS-DOS based file system + semantics, from a Unix host, the target may be reporting to GDB a + list of loaded shared libraries with file names such as + 'c:\Windows\kernel32.dll'. On Unix hosts, there's no concept of + drive letters, so the 'c:\' prefix is not normally understood as + indicating an absolute file name, and neither is the backslash + normally considered a directory separator character. In that case, + the native file system would interpret this whole absolute file + name as a relative file name with no directory components. This + would make it impossible to point GDB at a copy of the remote + target's shared libraries on the host using 'set sysroot', and + impractical with 'set solib-search-path'. Setting + 'target-file-system-kind' to 'dos-based' tells GDB to interpret + such file names similarly to how the target would, and to map them + to file names valid on GDB's native file system semantics. The + value of KIND can be '"auto"', in addition to one of the supported + file system kinds. In that case, GDB tries to determine the + appropriate file system variant based on the current target's + operating system (*note Configuring the Current ABI: ABI.). The + supported file system settings are: + + 'unix' + Instruct GDB to assume the target file system is of Unix kind. + Only file names starting the forward slash ('/') character are + considered absolute, and the directory separator character is + also the forward slash. + + 'dos-based' + Instruct GDB to assume the target file system is DOS based. + File names starting with either a forward slash, or a drive + letter followed by a colon (e.g., 'c:'), are considered + absolute, and both the slash ('/') and the backslash ('\\') + characters are considered directory separators. + + 'auto' + Instruct GDB to use the file system kind associated with the + target operating system (*note Configuring the Current ABI: + ABI.). This is the default. + + When processing file names provided by the user, GDB frequently needs +to compare them to the file names recorded in the program's debug info. +Normally, GDB compares just the "base names" of the files as strings, +which is reasonably fast even for very large programs. (The base name +of a file is the last portion of its name, after stripping all the +leading directories.) This shortcut in comparison is based upon the +assumption that files cannot have more than one base name. This is +usually true, but references to files that use symlinks or similar +filesystem facilities violate that assumption. If your program records +files using such facilities, or if you provide file names to GDB using +symlinks etc., you can set 'basenames-may-differ' to 'true' to instruct +GDB to completely canonicalize each pair of file names it needs to +compare. This will make file-name comparisons accurate, but at a price +of a significant slowdown. + +'set basenames-may-differ' + Set whether a source file may have multiple base names. + +'show basenames-may-differ' + Show whether a source file may have multiple base names. + + ---------- Footnotes ---------- + + (1) Historically the functionality to retrieve binaries from the +remote system was provided by prefixing PATH with 'remote:' + + +File: gdb.info, Node: File Caching, Next: Separate Debug Files, Prev: Files, Up: GDB Files + +18.2 File Caching +================= + +To speed up file loading, and reduce memory usage, GDB will reuse the +'bfd' objects used to track open files. *Note BFD: (bfd)Top. The +following commands allow visibility and control of the caching behavior. + +'maint info bfds' + This prints information about each 'bfd' object that is known to + GDB. + +'maint set bfd-sharing' +'maint show bfd-sharing' + Control whether 'bfd' objects can be shared. When sharing is + enabled GDB reuses already open 'bfd' objects rather than reopening + the same file. Turning sharing off does not cause already shared + 'bfd' objects to be unshared, but all future files that are opened + will create a new 'bfd' object. Similarly, re-enabling sharing + does not cause multiple existing 'bfd' objects to be collapsed into + a single shared 'bfd' object. + +'set debug bfd-cache LEVEL' + Turns on debugging of the bfd cache, setting the level to LEVEL. + +'show debug bfd-cache' + Show the current debugging level of the bfd cache. + + +File: gdb.info, Node: Separate Debug Files, Next: MiniDebugInfo, Prev: File Caching, Up: GDB Files + +18.3 Debugging Information in Separate Files +============================================ + +GDB allows you to put a program's debugging information in a file +separate from the executable itself, in a way that allows GDB to find +and load the debugging information automatically. Since debugging +information can be very large--sometimes larger than the executable code +itself--some systems distribute debugging information for their +executables in separate files, which users can install only when they +need to debug a problem. + + GDB supports two ways of specifying the separate debug info file: + + * The executable contains a "debug link" that specifies the name of + the separate debug info file. The separate debug file's name is + usually 'EXECUTABLE.debug', where EXECUTABLE is the name of the + corresponding executable file without leading directories (e.g., + 'ls.debug' for '/usr/bin/ls'). In addition, the debug link + specifies a 32-bit "Cyclic Redundancy Check" (CRC) checksum for the + debug file, which GDB uses to validate that the executable and the + debug file came from the same build. + + * The executable contains a "build ID", a unique bit string that is + also present in the corresponding debug info file. (This is + supported only on some operating systems, when using the ELF or PE + file formats for binary files and the GNU Binutils.) For more + details about this feature, see the description of the '--build-id' + command-line option in *note Command Line Options: (ld)Options. + The debug info file's name is not specified explicitly by the build + ID, but can be computed from the build ID, see below. + + Depending on the way the debug info file is specified, GDB uses two +different methods of looking for the debug file: + + * For the "debug link" method, GDB looks up the named file in the + directory of the executable file, then in a subdirectory of that + directory named '.debug', and finally under each one of the global + debug directories, in a subdirectory whose name is identical to the + leading directories of the executable's absolute file name. (On + MS-Windows/MS-DOS, the drive letter of the executable's leading + directories is converted to a one-letter subdirectory, i.e. + 'd:/usr/bin/' is converted to '/d/usr/bin/', because Windows + filesystems disallow colons in file names.) + + * For the "build ID" method, GDB looks in the '.build-id' + subdirectory of each one of the global debug directories for a file + named 'NN/NNNNNNNN.debug', where NN are the first 2 hex characters + of the build ID bit string, and NNNNNNNN are the rest of the bit + string. (Real build ID strings are 32 or more hex characters, not + 10.) GDB can automatically query 'debuginfod' servers using build + IDs in order to download separate debug files that cannot be found + locally. For more information see *note Debuginfod::. + + So, for example, suppose you ask GDB to debug '/usr/bin/ls', which +has a debug link that specifies the file 'ls.debug', and a build ID +whose value in hex is 'abcdef1234'. If the list of the global debug +directories includes '/usr/lib/debug', then GDB will look for the +following debug information files, in the indicated order: + + - '/usr/lib/debug/.build-id/ab/cdef1234.debug' + - '/usr/bin/ls.debug' + - '/usr/bin/.debug/ls.debug' + - '/usr/lib/debug/usr/bin/ls.debug'. + + If the debug file still has not been found and 'debuginfod' (*note +Debuginfod::) is enabled, GDB will attempt to download the file from +'debuginfod' servers. + + Global debugging info directories default to what is set by GDB +configure option '--with-separate-debug-dir' and augmented by the +colon-separated list of directories provided via GDB configure option +'--additional-debug-dirs'. During GDB run you can also set the global +debugging info directories, and view the list GDB is currently using. + +'set debug-file-directory DIRECTORIES' + Set the directories which GDB searches for separate debugging + information files to DIRECTORY. Multiple path components can be + set concatenating them by a path separator. + +'show debug-file-directory' + Show the directories GDB searches for separate debugging + information files. + + A debug link is a special section of the executable file named +'.gnu_debuglink'. The section must contain: + + * A filename, with any leading directory components removed, followed + by a zero byte, + * zero to three bytes of padding, as needed to reach the next + four-byte boundary within the section, and + * a four-byte CRC checksum, stored in the same endianness used for + the executable file itself. The checksum is computed on the + debugging information file's full contents by the function given + below, passing zero as the CRC argument. + + Any executable file format can carry a debug link, as long as it can +contain a section named '.gnu_debuglink' with the contents described +above. + + The build ID is a special section in the executable file (and in +other ELF binary files that GDB may consider). This section is often +named '.note.gnu.build-id', but that name is not mandatory. It contains +unique identification for the built files--the ID remains the same +across multiple builds of the same build tree. The default algorithm +SHA1 produces 160 bits (40 hexadecimal characters) of the content for +the build ID string. The same section with an identical value is +present in the original built binary with symbols, in its stripped +variant, and in the separate debugging information file. + + The debugging information file itself should be an ordinary +executable, containing a full set of linker symbols, sections, and +debugging information. The sections of the debugging information file +should have the same names, addresses, and sizes as the original file, +but they need not contain any data--much like a '.bss' section in an +ordinary executable. + + The GNU binary utilities (Binutils) package includes the 'objcopy' +utility that can produce the separated executable / debugging +information file pairs using the following commands: + + objcopy --only-keep-debug foo foo.debug + strip -g foo + +These commands remove the debugging information from the executable file +'foo' and place it in the file 'foo.debug'. You can use the first, +second or both methods to link the two files: + + * The debug link method needs the following additional command to + also leave behind a debug link in 'foo': + + objcopy --add-gnu-debuglink=foo.debug foo + + Ulrich Drepper's 'elfutils' package, starting with version 0.53, + contains a version of the 'strip' command such that the command + 'strip foo -f foo.debug' has the same functionality as the two + 'objcopy' commands and the 'ln -s' command above, together. + + * Build ID gets embedded into the main executable using 'ld + --build-id' or the GCC counterpart 'gcc -Wl,--build-id'. Build ID + support plus compatibility fixes for debug files separation are + present in GNU binary utilities (Binutils) package since version + 2.18. + + + The CRC used in '.gnu_debuglink' is the CRC-32 defined in IEEE 802.3 +using the polynomial: + + x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11} + + x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1 + + The function is computed byte at a time, taking the least significant +bit of each byte first. The initial pattern '0xffffffff' is used, to +ensure leading zeros affect the CRC and the final result is inverted to +ensure trailing zeros also affect the CRC. + + _Note:_ This is the same CRC polynomial as used in handling the +"Remote Serial Protocol" 'qCRC' packet (*note qCRC packet::). However +in the case of the Remote Serial Protocol, the CRC is computed _most_ +significant bit first, and the result is not inverted, so trailing zeros +have no effect on the CRC value. + + To complete the description, we show below the code of the function +which produces the CRC used in '.gnu_debuglink'. Inverting the +initially supplied 'crc' argument means that an initial call to this +function passing in zero will start computing the CRC using +'0xffffffff'. + + unsigned long + gnu_debuglink_crc32 (unsigned long crc, + unsigned char *buf, size_t len) + { + static const unsigned long crc32_table[256] = + { + 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, + 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, + 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, + 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, + 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, + 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, + 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, + 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, + 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, + 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, + 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, + 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, + 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, + 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, + 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, + 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, + 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, + 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, + 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, + 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, + 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, + 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, + 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, + 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, + 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, + 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, + 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, + 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, + 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, + 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, + 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, + 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, + 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, + 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, + 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, + 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, + 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, + 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, + 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, + 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, + 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, + 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, + 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, + 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, + 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, + 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, + 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, + 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, + 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, + 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, + 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, + 0x2d02ef8d + }; + unsigned char *end; + + crc = ~crc & 0xffffffff; + for (end = buf + len; buf < end; ++buf) + crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); + return ~crc & 0xffffffff; + } + +This computation does not apply to the "build ID" method. + + +File: gdb.info, Node: MiniDebugInfo, Next: Index Files, Prev: Separate Debug Files, Up: GDB Files + +18.4 Debugging information in a special section +=============================================== + +Some systems ship pre-built executables and libraries that have a +special '.gnu_debugdata' section. This feature is called +"MiniDebugInfo". This section holds an LZMA-compressed object and is +used to supply extra symbols for backtraces. + + The intent of this section is to provide extra minimal debugging +information for use in simple backtraces. It is not intended to be a +replacement for full separate debugging information (*note Separate +Debug Files::). The example below shows the intended use; however, GDB +does not currently put restrictions on what sort of debugging +information might be included in the section. + + GDB has support for this extension. If the section exists, then it +is used provided that no other source of debugging information can be +found, and that GDB was configured with LZMA support. + + This section can be easily created using 'objcopy' and other standard +utilities: + + # Extract the dynamic symbols from the main binary, there is no need + # to also have these in the normal symbol table. + nm -D BINARY --format=posix --defined-only \ + | awk '{ print $1 }' | sort > dynsyms + + # Extract all the text (i.e. function) symbols from the debuginfo. + # (Note that we actually also accept "D" symbols, for the benefit + # of platforms like PowerPC64 that use function descriptors.) + nm BINARY --format=posix --defined-only \ + | awk '{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 }' \ + | sort > funcsyms + + # Keep all the function symbols not already in the dynamic symbol + # table. + comm -13 dynsyms funcsyms > keep_symbols + + # Separate full debug info into debug binary. + objcopy --only-keep-debug BINARY debug + + # Copy the full debuginfo, keeping only a minimal set of symbols and + # removing some unnecessary sections. + objcopy -S --remove-section .gdb_index --remove-section .comment \ + --keep-symbols=keep_symbols debug mini_debuginfo + + # Drop the full debug info from the original binary. + strip --strip-all -R .comment BINARY + + # Inject the compressed data into the .gnu_debugdata section of the + # original binary. + xz mini_debuginfo + objcopy --add-section .gnu_debugdata=mini_debuginfo.xz BINARY + + +File: gdb.info, Node: Index Files, Next: Debug Names, Prev: MiniDebugInfo, Up: GDB Files + +18.5 Index Files Speed Up GDB +============================= + +When GDB finds a symbol file, it scans the symbols in the file in order +to construct an internal symbol table. This lets most GDB operations +work quickly--at the cost of a delay early on. For large programs, this +delay can be quite lengthy, so GDB provides a way to build an index, +which speeds up startup. + + For convenience, GDB comes with a program, 'gdb-add-index', which can +be used to add the index to a symbol file. It takes the symbol file as +its only argument: + + $ gdb-add-index symfile + + *Note gdb-add-index::. + + It is also possible to do the work manually. Here is what +'gdb-add-index' does behind the curtains. + + The index is stored as a section in the symbol file. GDB can write +the index to a file, then you can put it into the symbol file using +'objcopy'. + + To create an index file, use the 'save gdb-index' command: + +'save gdb-index [-dwarf-5] DIRECTORY' + Create index files for all symbol files currently known by GDB. + For each known SYMBOL-FILE, this command by default creates it + produces a single file 'SYMBOL-FILE.gdb-index'. If you invoke this + command with the '-dwarf-5' option, it produces 2 files: + 'SYMBOL-FILE.debug_names' and 'SYMBOL-FILE.debug_str'. The files + are created in the given DIRECTORY. + + The DIRECTORY argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + + Once you have created an index file you can merge it into your symbol +file, here named 'symfile', using 'objcopy': + + $ objcopy --add-section .gdb_index=symfile.gdb-index \ + --set-section-flags .gdb_index=readonly symfile symfile + + Or for '-dwarf-5': + + $ objcopy --dump-section .debug_str=symfile.debug_str.new symfile + $ cat symfile.debug_str >>symfile.debug_str.new + $ objcopy --add-section .debug_names=symfile.gdb-index \ + --set-section-flags .debug_names=readonly \ + --update-section .debug_str=symfile.debug_str.new symfile symfile + + GDB will normally ignore older versions of '.gdb_index' sections that +have been deprecated. Usually they are deprecated because they are +missing a new feature or have performance issues. To tell GDB to use a +deprecated index section anyway specify 'set +use-deprecated-index-sections on'. The default is 'off'. This can +speed up startup, but may result in some functionality being lost. +*Note Index Section Format::. + + _Warning:_ Setting 'use-deprecated-index-sections' to 'on' must be +done before gdb reads the file. The following will not work: + + $ gdb -ex "set use-deprecated-index-sections on" + + Instead you must do, for example, + + $ gdb -iex "set use-deprecated-index-sections on" + + Indices only work when using DWARF debugging information, not stabs. + +18.5.1 Automatic symbol index cache +----------------------------------- + +It is possible for GDB to automatically save a copy of this index in a +cache on disk and retrieve it from there when loading the same binary in +the future. This feature can be turned on with 'set index-cache enabled +on'. The following commands can be used to tweak the behavior of the +index cache. + +'set index-cache enabled on' +'set index-cache enabled off' + Enable or disable the use of the symbol index cache. + +'set index-cache directory DIRECTORY' +'show index-cache directory' + Set/show the directory where index files will be saved. + + The default value for this directory depends on the host platform. + On most systems, the index is cached in the 'gdb' subdirectory of + the directory pointed to by the 'XDG_CACHE_HOME' environment + variable, if it is defined, else in the '.cache/gdb' subdirectory + of your home directory. However, on some systems, the default may + differ according to local convention. + + There is no limit on the disk space used by index cache. It is + perfectly safe to delete the content of that directory to free up + disk space. + +'show index-cache stats' + Print the number of cache hits and misses since the launch of GDB. + +18.5.2 Building the index with GNU 'gold' +----------------------------------------- + +The GNU 'gold' linker can write the index at link time into the +resulting ELF file, by passing the '--gdb-index' flag to 'gold'. + + This is especially helpful if you intend to build a program and +immediately run it under GDB. You may find that it is faster overall +for the linker to write the index while it has the relevant information +in memory anyways, rather than re-reloading the data from disk with +'gdb-add-index', or debugging the program without an index at all, +especially for large programs. + + +File: gdb.info, Node: Debug Names, Next: Symbol Errors, Prev: Index Files, Up: GDB Files + +18.6 Extensions to '.debug_names' +================================= + +The DWARF specification documents an optional index section called +'.debug_names'. GDB can both read and create this section. However, in +order to work with GDB, some extensions were necessary. + + GDB uses the augmentation string 'GDB2'. Earlier versions used the +string 'GDB', but these versions of the index are no longer supported. + + GDB does not use the specified hash table. Therefore, because this +hash table is optional, GDB also does not write it. + + GDB also generates and uses some extra index attributes: +'DW_IDX_GNU_internal' + This has the value '0x2000'. It is a flag that, when set, + indicates that the associated entry has 'static' linkage. + +'DW_IDX_GNU_main' + This has the value '0x2002'. It is a flag that, when set, + indicates that the associated entry is the program's 'main'. + +'DW_IDX_GNU_language' + This has the value '0x2003'. It is 'DW_LANG_' constant, indicating + the language of the associated entry. + +'DW_IDX_GNU_linkage_name' + This has the value '0x2004'. It is a flag that, when set, + indicates that the associated entry is a linkage name, and not a + source name. + + +File: gdb.info, Node: Symbol Errors, Next: Data Files, Prev: Debug Names, Up: GDB Files + +18.7 Errors Reading Symbol Files +================================ + +While reading a symbol file, GDB occasionally encounters problems, such +as symbol types it does not recognize, or known bugs in compiler output. +By default, GDB does not notify you of such problems, since they are +relatively common and primarily of interest to people debugging +compilers. If you are interested in seeing information about +ill-constructed symbol tables, you can either ask GDB to print only one +message about each such type of problem, no matter how many times the +problem occurs; or you can ask GDB to print more messages, to see how +many times the problems occur, with the 'set complaints' command (*note +Optional Warnings and Messages: Messages/Warnings.). + + The messages currently printed, and their meanings, include: + +'inner block not inside outer block in SYMBOL' + + The symbol information shows where symbol scopes begin and end + (such as at the start of a function or a block of statements). + This error indicates that an inner scope block is not fully + contained in its outer scope blocks. + + GDB circumvents the problem by treating the inner block as if it + had the same scope as the outer block. In the error message, + SYMBOL may be shown as "'(don't know)'" if the outer block is not a + function. + +'block at ADDRESS out of order' + + The symbol information for symbol scope blocks should occur in + order of increasing addresses. This error indicates that it does + not do so. + + GDB does not circumvent this problem, and has trouble locating + symbols in the source file whose symbols it is reading. (You can + often determine what source file is affected by specifying 'set + verbose on'. *Note Optional Warnings and Messages: + Messages/Warnings.) + +'bad block start address patched' + + The symbol information for a symbol scope block has a start address + smaller than the address of the preceding source line. This is + known to occur in the SunOS 4.1.1 (and earlier) C compiler. + + GDB circumvents the problem by treating the symbol scope block as + starting on the previous source line. + +'bad string table offset in symbol N' + + Symbol number N contains a pointer into the string table which is + larger than the size of the string table. + + GDB circumvents the problem by considering the symbol to have the + name 'foo', which may cause other problems if many symbols end up + with this name. + +'unknown symbol type 0xNN' + + The symbol information contains new data types that GDB does not + yet know how to read. '0xNN' is the symbol type of the + uncomprehended information, in hexadecimal. + + GDB circumvents the error by ignoring this symbol information. + This usually allows you to debug your program, though certain + symbols are not accessible. If you encounter such a problem and + feel like debugging it, you can debug 'gdb' with itself, breakpoint + on 'complain', then go up to the function 'read_dbx_symtab' and + examine '*bufp' to see the symbol. + +'stub type has NULL name' + + GDB could not find the full definition for a struct or class. + +'const/volatile indicator missing (ok if using g++ v1.x), got...' + The symbol information for a C++ member function is missing some + information that recent versions of the compiler should have output + for it. + +'info mismatch between compiler and debugger' + + GDB could not parse a type specification output by the compiler. + + +File: gdb.info, Node: Data Files, Prev: Symbol Errors, Up: GDB Files + +18.8 GDB Data Files +=================== + +GDB will sometimes read an auxiliary data file. These files are kept in +a directory known as the "data directory". + + You can set the data directory's name, and view the name GDB is +currently using. + +'set data-directory DIRECTORY' + Set the directory which GDB searches for auxiliary data files to + DIRECTORY. + +'show data-directory' + Show the directory GDB searches for auxiliary data files. + + You can set the default data directory by using the configure-time +'--with-gdb-datadir' option. If the data directory is inside GDB's +configured binary prefix (set with '--prefix' or '--exec-prefix'), then +the default data directory will be updated automatically if the +installed GDB is moved to a new location. + + The data directory may also be specified with the '--data-directory' +command line option. *Note Mode Options::. + + +File: gdb.info, Node: Targets, Next: Remote Debugging, Prev: GDB Files, Up: Top + +19 Specifying a Debugging Target +******************************** + +A "target" is the execution environment occupied by your program. + + Often, GDB runs in the same host environment as your program; in that +case, the debugging target is specified as a side effect when you use +the 'file' or 'core' commands. When you need more flexibility--for +example, running GDB on a physically separate host, or controlling a +standalone system over a serial port or a realtime system over a TCP/IP +connection--you can use the 'target' command to specify one of the +target types configured for GDB (*note Commands for Managing Targets: +Target Commands.). + + It is possible to build GDB for several different "target +architectures". When GDB is built like that, you can choose one of the +available architectures with the 'set architecture' command. + +'set architecture ARCH' + This command sets the current target architecture to ARCH. The + value of ARCH can be '"auto"', in addition to one of the supported + architectures. + +'show architecture' + Show the current target architecture. + +'set processor' +'processor' + These are alias commands for, respectively, 'set architecture' and + 'show architecture'. + +* Menu: + +* Active Targets:: Active targets +* Target Commands:: Commands for managing targets +* Byte Order:: Choosing target byte order + + +File: gdb.info, Node: Active Targets, Next: Target Commands, Up: Targets + +19.1 Active Targets +=================== + +There are multiple classes of targets such as: processes, executable +files or recording sessions. Core files belong to the process class, +making core file and process mutually exclusive. Otherwise, GDB can +work concurrently on multiple active targets, one in each class. This +allows you to (for example) start a process and inspect its activity, +while still having access to the executable file after the process +finishes. Or if you start process recording (*note Reverse Execution::) +and 'reverse-step' there, you are presented a virtual layer of the +recording target, while the process target remains stopped at the +chronologically last point of the process execution. + + Use the 'core-file' and 'exec-file' commands to select a new core +file or executable target (*note Commands to Specify Files: Files.). To +specify as a target a process that is already running, use the 'attach' +command (*note Debugging an Already-running Process: Attach.). + + +File: gdb.info, Node: Target Commands, Next: Byte Order, Prev: Active Targets, Up: Targets + +19.2 Commands for Managing Targets +================================== + +'target TYPE PARAMETERS' + Connects the GDB host environment to a target machine or process. + A target is typically a protocol for talking to debugging + facilities. You use the argument TYPE to specify the type or + protocol of the target machine. + + Further PARAMETERS are interpreted by the target protocol, but + typically include things like device names or host names to connect + with, process numbers, and baud rates. + + The 'target' command does not repeat if you press again after + executing the command. + +'help target' + Displays the names of all targets available. To display targets + currently selected, use either 'info target' or 'info files' (*note + Commands to Specify Files: Files.). + +'help target NAME' + Describe a particular target, including any parameters necessary to + select it. + +'set gnutarget ARGS' + GDB uses its own library BFD to read your files. GDB knows whether + it is reading an "executable", a "core", or a ".o" file; however, + you can specify the file format with the 'set gnutarget' command. + Unlike most 'target' commands, with 'gnutarget' the 'target' refers + to a program, not a machine. + + _Warning:_ To specify a file format with 'set gnutarget', you + must know the actual BFD name. + + *Note Commands to Specify Files: Files. + +'show gnutarget' + Use the 'show gnutarget' command to display what file format + 'gnutarget' is set to read. If you have not set 'gnutarget', GDB + will determine the file format for each file automatically, and + 'show gnutarget' displays 'The current BFD target is "auto"'. + + Here are some common targets (available, or not, depending on the GDB +configuration): + +'target exec PROGRAM' + An executable file. 'target exec PROGRAM' is the same as + 'exec-file PROGRAM'. + + The PROGRAM argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'target core FILENAME' + A core dump file. 'target core FILENAME' is the same as 'core-file + FILENAME'. + + The FILENAME argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'target remote MEDIUM' + A remote system connected to GDB via a serial line or network + connection. This command tells GDB to use its own remote protocol + over MEDIUM for debugging. *Note Remote Debugging::. + + For example, if you have a board connected to '/dev/ttya' on the + machine running GDB, you could say: + + target remote /dev/ttya + + 'target remote' supports the 'load' command. This is only useful + if you have some other way of getting the stub to the target + system, and you can put it somewhere in memory where it won't get + clobbered by the download. + +'target sim [SIMARGS] ...' + Builtin CPU simulator. GDB includes simulators for most + architectures. In general, + target sim + load + run + works; however, you cannot assume that a specific memory map, + device drivers, or even basic I/O is available, although some + simulators do provide these. For info about any processor-specific + simulator details, see the appropriate section in *note Embedded + Processors: Embedded Processors. + +'target native' + Setup for local/native process debugging. Useful to make the 'run' + command spawn native processes (likewise 'attach', etc.) even when + 'set auto-connect-native-target' is 'off' (*note set + auto-connect-native-target::). + + Different targets are available on different configurations of GDB; +your configuration may have more or fewer targets. + + Many remote targets require you to download the executable's code +once you've successfully established a connection. You may wish to +control various aspects of this process. + +'set hash' + This command controls whether a hash mark '#' is displayed while + downloading a file to the remote monitor. If on, a hash mark is + displayed after each S-record is successfully downloaded to the + monitor. + +'show hash' + Show the current status of displaying the hash mark. + +'set debug monitor' + Enable or disable display of communications messages between GDB + and the remote monitor. + +'show debug monitor' + Show the current status of displaying communications between GDB + and the remote monitor. + +'load FILENAME OFFSET' + Depending on what remote debugging facilities are configured into + GDB, the 'load' command may be available. Where it exists, it is + meant to make FILENAME (an executable) available for debugging on + the remote system--by downloading, or dynamic linking, for example. + 'load' also records the FILENAME symbol table in GDB, like the + 'add-symbol-file' command. + + If your GDB does not have a 'load' command, attempting to execute + it gets the error message "'You can't do that when your target is + ...'" + + The file is loaded at whatever address is specified in the + executable. For some object file formats, you can specify the load + address when you link the program; for other formats, like a.out, + the object file format specifies a fixed address. + + It is also possible to tell GDB to load the executable file at a + specific offset described by the optional argument OFFSET. When + OFFSET is provided, FILENAME must also be provided. + + Depending on the remote side capabilities, GDB may be able to load + programs into flash memory. + + 'load' does not repeat if you press again after using it. + +'flash-erase' + + Erases all known flash memory regions on the target. + + +File: gdb.info, Node: Byte Order, Prev: Target Commands, Up: Targets + +19.3 Choosing Target Byte Order +=============================== + +Some types of processors, such as the MIPS, PowerPC, and Renesas SH, +offer the ability to run either big-endian or little-endian byte orders. +Usually the executable or symbol will include a bit to designate the +endian-ness, and you will not need to worry about which to use. +However, you may still find it useful to adjust GDB's idea of processor +endian-ness manually. + +'set endian big' + Instruct GDB to assume the target is big-endian. + +'set endian little' + Instruct GDB to assume the target is little-endian. + +'set endian auto' + Instruct GDB to use the byte order associated with the executable. + +'show endian' + Display GDB's current idea of the target byte order. + + If the 'set endian auto' mode is in effect and no executable has been +selected, then the endianness used is the last one chosen either by one +of the 'set endian big' and 'set endian little' commands or by inferring +from the last executable used. If no endianness has been previously +chosen, then the default for this mode is inferred from the target GDB +has been built for, and is 'little' if the name of the target CPU has an +'el' suffix and 'big' otherwise. + + Note that these commands merely adjust interpretation of symbolic +data on the host, and that they have absolutely no effect on the target +system. + + +File: gdb.info, Node: Remote Debugging, Next: Configurations, Prev: Targets, Up: Top + +20 Debugging Remote Programs +**************************** + +If you are trying to debug a program running on a machine that cannot +run GDB in the usual way, it is often useful to use remote debugging. +For example, you might use remote debugging on an operating system +kernel, or on a small system which does not have a general purpose +operating system powerful enough to run a full-featured debugger. + + Some configurations of GDB have special serial or TCP/IP interfaces +to make this work with particular debugging targets. In addition, GDB +comes with a generic serial protocol (specific to GDB, but not specific +to any particular target system) which you can use if you write the +remote stubs--the code that runs on the remote system to communicate +with GDB. + + Other remote targets may be available in your configuration of GDB; +use 'help target' to list them. + +* Menu: + +* Connecting:: Connecting to a remote target +* File Transfer:: Sending files to a remote system +* Server:: Using the gdbserver program +* Remote Configuration:: Remote configuration +* Remote Stub:: Implementing a remote stub + + +File: gdb.info, Node: Connecting, Next: File Transfer, Up: Remote Debugging + +20.1 Connecting to a Remote Target +================================== + +This section describes how to connect to a remote target, including the +types of connections and their differences, how to set up executable and +symbol files on the host and target, and the commands used for +connecting to and disconnecting from the remote target. + +20.1.1 Types of Remote Connections +---------------------------------- + +GDB supports two types of remote connections, 'target remote' mode and +'target extended-remote' mode. Note that many remote targets support +only 'target remote' mode. There are several major differences between +the two types of connections, enumerated here: + +Result of detach or program exit + *With target remote mode:* When the debugged program exits or you + detach from it, GDB disconnects from the target. When using + 'gdbserver', 'gdbserver' will exit. + + *With target extended-remote mode:* When the debugged program exits + or you detach from it, GDB remains connected to the target, even + though no program is running. You can rerun the program, attach to + a running program, or use 'monitor' commands specific to the + target. + + When using 'gdbserver' in this case, it does not exit unless it was + invoked using the '--once' option. If the '--once' option was not + used, you can ask 'gdbserver' to exit using the 'monitor exit' + command (*note Monitor Commands for gdbserver::). + +Specifying the program to debug + For both connection types you use the 'file' command to specify the + program on the host system. If you are using 'gdbserver' there are + some differences in how to specify the location of the program on + the target. + + *With target remote mode:* You must either specify the program to + debug on the 'gdbserver' command line or use the '--attach' option + (*note Attaching to a Running Program: Attaching to a program.). + + *With target extended-remote mode:* You may specify the program to + debug on the 'gdbserver' command line, or you can load the program + or attach to it using GDB commands after connecting to 'gdbserver'. + + You can start 'gdbserver' without supplying an initial command to + run or process ID to attach. To do this, use the '--multi' command + line option. Then you can connect using 'target extended-remote' + and start the program you want to debug (see below for details on + using the 'run' command in this scenario). Note that the + conditions under which 'gdbserver' terminates depend on how GDB + connects to it ('target remote' or 'target extended-remote'). The + '--multi' option to 'gdbserver' has no influence on that. + +The 'run' command + *With target remote mode:* The 'run' command is not supported. + Once a connection has been established, you can use all the usual + GDB commands to examine and change data. The remote program is + already running, so you can use commands like 'step' and + 'continue'. + + *With target extended-remote mode:* The 'run' command is supported. + The 'run' command uses the value set by 'set remote exec-file' + (*note set remote exec-file::) to select the program to run. + Command line arguments are supported, except for wildcard expansion + and I/O redirection (*note Arguments::). + + If you specify the program to debug on the command line, then the + 'run' command is not required to start execution, and you can + resume using commands like 'step' and 'continue' as with 'target + remote' mode. + +Attaching + *With target remote mode:* The GDB command 'attach' is not + supported. To attach to a running program using 'gdbserver', you + must use the '--attach' option (*note Running gdbserver::). + + *With target extended-remote mode:* To attach to a running program, + you may use the 'attach' command after the connection has been + established. If you are using 'gdbserver', you may also invoke + 'gdbserver' using the '--attach' option (*note Running + gdbserver::). + + Some remote targets allow GDB to determine the executable file + running in the process the debugger is attaching to. In such a + case, GDB uses the value of 'exec-file-mismatch' to handle a + possible mismatch between the executable file name running in the + process and the name of the current exec-file loaded by GDB (*note + set exec-file-mismatch::). + +20.1.2 Host and Target Files +---------------------------- + +GDB, running on the host, needs access to symbol and debugging +information for your program running on the target. This requires +access to an unstripped copy of your program, and possibly any +associated symbol files. Note that this section applies equally to both +'target remote' mode and 'target extended-remote' mode. + + Some remote targets (*note qXfer executable filename read::, and +*note Host I/O Packets::) allow GDB to access program files over the +same connection used to communicate with GDB. With such a target, if +the remote program is unstripped, the only command you need is 'target +remote' (or 'target extended-remote'). + + If the remote program is stripped, or the target does not support +remote program file access, start up GDB using the name of the local +unstripped copy of your program as the first argument, or use the 'file' +command. Use 'set sysroot' to specify the location (on the host) of +target libraries (unless your GDB was compiled with the correct sysroot +using '--with-sysroot'). Alternatively, you may use 'set +solib-search-path' to specify how GDB locates target libraries. + + The symbol file and target libraries must exactly match the +executable and libraries on the target, with one exception: the files on +the host system should not be stripped, even if the files on the target +system are. Mismatched or missing files will lead to confusing results +during debugging. On GNU/Linux targets, mismatched or missing files may +also prevent 'gdbserver' from debugging multi-threaded programs. + +20.1.3 Remote Connection Commands +--------------------------------- + +GDB can communicate with the target over a serial line, a local Unix +domain socket, or over an IP network using TCP or UDP. In each case, +GDB uses the same protocol for debugging your program; only the medium +carrying the debugging packets varies. The 'target remote' and 'target +extended-remote' commands establish a connection to the target. Both +commands accept the same arguments, which indicate the medium to use: + +'target remote SERIAL-DEVICE' +'target extended-remote SERIAL-DEVICE' + Use SERIAL-DEVICE to communicate with the target. For example, to + use a serial line connected to the device named '/dev/ttyb': + + target remote /dev/ttyb + + If you're using a serial line, you may want to give GDB the + '--baud' option, or use the 'set serial baud' command (*note set + serial baud: Remote Configuration.) before the 'target' command. + +'target remote LOCAL-SOCKET' +'target extended-remote LOCAL-SOCKET' + Use LOCAL-SOCKET to communicate with the target. For example, to + use a local Unix domain socket bound to the file system entry + '/tmp/gdb-socket0': + + target remote /tmp/gdb-socket0 + + Note that this command has the same form as the command to connect + to a serial line. GDB will automatically determine which kind of + file you have specified and will make the appropriate kind of + connection. This feature is not available if the host system does + not support Unix domain sockets. + +'target remote HOST:PORT' +'target remote [HOST]:PORT' +'target remote tcp:HOST:PORT' +'target remote tcp:[HOST]:PORT' +'target remote tcp4:HOST:PORT' +'target remote tcp6:HOST:PORT' +'target remote tcp6:[HOST]:PORT' +'target extended-remote HOST:PORT' +'target extended-remote [HOST]:PORT' +'target extended-remote tcp:HOST:PORT' +'target extended-remote tcp:[HOST]:PORT' +'target extended-remote tcp4:HOST:PORT' +'target extended-remote tcp6:HOST:PORT' +'target extended-remote tcp6:[HOST]:PORT' + Debug using a TCP connection to PORT on HOST. The HOST may be + either a host name, a numeric IPv4 address, or a numeric IPv6 + address (with or without the square brackets to separate the + address from the port); PORT must be a decimal number. The HOST + could be the target machine itself, if it is directly connected to + the net, or it might be a terminal server which in turn has a + serial line to the target. + + For example, to connect to port 2828 on a terminal server named + 'manyfarms': + + target remote manyfarms:2828 + + To connect to port 2828 on a terminal server whose address is + '2001:0db8:85a3:0000:0000:8a2e:0370:7334', you can either use the + square bracket syntax: + + target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 + + or explicitly specify the IPv6 protocol: + + target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 + + This last example may be confusing to the reader, because there is + no visible separation between the hostname and the port number. + Therefore, we recommend the user to provide IPv6 addresses using + square brackets for clarity. However, it is important to mention + that for GDB there is no ambiguity: the number after the last colon + is considered to be the port number. + + If your remote target is actually running on the same machine as + your debugger session (e.g. a simulator for your target running on + the same host), you can omit the hostname. For example, to connect + to port 1234 on your local machine: + + target remote :1234 + + Note that the colon is still required here. + +'target remote udp:HOST:PORT' +'target remote udp:[HOST]:PORT' +'target remote udp4:HOST:PORT' +'target remote udp6:[HOST]:PORT' +'target extended-remote udp:HOST:PORT' +'target extended-remote udp:HOST:PORT' +'target extended-remote udp:[HOST]:PORT' +'target extended-remote udp4:HOST:PORT' +'target extended-remote udp6:HOST:PORT' +'target extended-remote udp6:[HOST]:PORT' + Debug using UDP packets to PORT on HOST. For example, to connect + to UDP port 2828 on a terminal server named 'manyfarms': + + target remote udp:manyfarms:2828 + + When using a UDP connection for remote debugging, you should keep + in mind that the 'U' stands for "Unreliable". UDP can silently + drop packets on busy or unreliable networks, which will cause havoc + with your debugging session. + +'target remote | COMMAND' +'target extended-remote | COMMAND' + Run COMMAND in the background and communicate with it using a pipe. + The COMMAND is a shell command, to be parsed and expanded by the + system's command shell, '/bin/sh'; it should expect remote protocol + packets on its standard input, and send replies on its standard + output. You could use this to run a stand-alone simulator that + speaks the remote debugging protocol, to make net connections using + programs like 'ssh', or for other similar tricks. + + If COMMAND closes its standard output (perhaps by exiting), GDB + will try to send it a 'SIGTERM' signal. (If the program has + already exited, this will have no effect.) + + Whenever GDB is waiting for the remote program, if you type the +interrupt character (often 'Ctrl-c'), GDB attempts to stop the program. +This may or may not succeed, depending in part on the hardware and the +serial drivers the remote system uses. If you type the interrupt +character once again, GDB displays this prompt: + + Interrupted while waiting for the program. + Give up (and stop debugging it)? (y or n) + + In 'target remote' mode, if you type 'y', GDB abandons the remote +debugging session. (If you decide you want to try again later, you can +use 'target remote' again to connect once more.) If you type 'n', GDB +goes back to waiting. + + In 'target extended-remote' mode, typing 'n' will leave GDB connected +to the target. + +'detach' + When you have finished debugging the remote program, you can use + the 'detach' command to release it from GDB control. Detaching + from the target normally resumes its execution, but the results + will depend on your particular remote stub. After the 'detach' + command in 'target remote' mode, GDB is free to connect to another + target. In 'target extended-remote' mode, GDB is still connected + to the target. + +'disconnect' + The 'disconnect' command closes the connection to the target, and + the target is generally not resumed. It will wait for GDB (this + instance or another one) to connect and continue debugging. After + the 'disconnect' command, GDB is again free to connect to another + target. + +'monitor CMD' + This command allows you to send arbitrary commands directly to the + remote monitor. Since GDB doesn't care about the commands it sends + like this, this command is the way to extend GDB--you can add new + commands that only the external monitor will understand and + implement. + + +File: gdb.info, Node: File Transfer, Next: Server, Prev: Connecting, Up: Remote Debugging + +20.2 Sending files to a remote system +===================================== + +Some remote targets offer the ability to transfer files over the same +connection used to communicate with GDB. This is convenient for targets +accessible through other means, e.g. GNU/Linux systems running +'gdbserver' over a network interface. For other targets, e.g. embedded +devices with only a single serial port, this may be the only way to +upload or download files. + + Not all remote targets support these commands. + +'remote put HOSTFILE TARGETFILE' + Copy file HOSTFILE from the host system (the machine running GDB) + to TARGETFILE on the target system. + +'remote get TARGETFILE HOSTFILE' + Copy file TARGETFILE from the target system to HOSTFILE on the host + system. + +'remote delete TARGETFILE' + Delete TARGETFILE from the target system. + + +File: gdb.info, Node: Server, Next: Remote Configuration, Prev: File Transfer, Up: Remote Debugging + +20.3 Using the 'gdbserver' Program +================================== + +'gdbserver' is a control program for Unix-like systems, which allows you +to connect your program with a remote GDB via 'target remote' or 'target +extended-remote'--but without linking in the usual debugging stub. + + 'gdbserver' is not a complete replacement for the debugging stubs, +because it requires essentially the same operating-system facilities +that GDB itself does. In fact, a system that can run 'gdbserver' to +connect to a remote GDB could also run GDB locally! 'gdbserver' is +sometimes useful nevertheless, because it is a much smaller program than +GDB itself. It is also easier to port than all of GDB, so you may be +able to get started more quickly on a new system by using 'gdbserver'. +Finally, if you develop code for real-time systems, you may find that +the tradeoffs involved in real-time operation make it more convenient to +do as much development work as possible on another system, for example +by cross-compiling. You can use 'gdbserver' to make a similar choice +for debugging. + + GDB and 'gdbserver' communicate via either a serial line or a TCP +connection, using the standard GDB remote serial protocol. + + _Warning:_ 'gdbserver' does not have any built-in security. Do not + run 'gdbserver' connected to any public network; a GDB connection + to 'gdbserver' provides access to the target system with the same + privileges as the user running 'gdbserver'. + +20.3.1 Running 'gdbserver' +-------------------------- + +Run 'gdbserver' on the target system. You need a copy of the program +you want to debug, including any libraries it requires. 'gdbserver' +does not need your program's symbol table, so you can strip the program +if necessary to save space. GDB on the host system does all the symbol +handling. + + To use the server, you must tell it how to communicate with GDB; the +name of your program; and the arguments for your program. The usual +syntax is: + + target> gdbserver COMM PROGRAM [ ARGS ... ] + + COMM is either a device name (to use a serial line), or a TCP +hostname and portnumber, or '-' or 'stdio' to use stdin/stdout of +'gdbserver'. For example, to debug Emacs with the argument 'foo.txt' +and communicate with GDB over the serial port '/dev/com1': + + target> gdbserver /dev/com1 emacs foo.txt + + 'gdbserver' waits passively for the host GDB to communicate with it. + + To use a TCP connection instead of a serial line: + + target> gdbserver host:2345 emacs foo.txt + + The only difference from the previous example is the first argument, +specifying that you are communicating with the host GDB via TCP. The +'host:2345' argument means that 'gdbserver' is to expect a TCP +connection from machine 'host' to local TCP port 2345. (Currently, the +'host' part is ignored.) You can choose any number you want for the +port number as long as it does not conflict with any TCP ports already +in use on the target system (for example, '23' is reserved for +'telnet').(1) You must use the same port number with the host GDB +'target remote' command. + + The 'stdio' connection is useful when starting 'gdbserver' with ssh: + + (gdb) target remote | ssh -T hostname gdbserver - hello + + The '-T' option to ssh is provided because we don't need a remote +pty, and we don't want escape-character handling. Ssh does this by +default when a command is provided, the flag is provided to make it +explicit. You could elide it if you want to. + + Programs started with stdio-connected gdbserver have '/dev/null' for +'stdin', and 'stdout','stderr' are sent back to gdb for display through +a pipe connected to gdbserver. Both 'stdout' and 'stderr' use the same +pipe. + +20.3.1.1 Attaching to a Running Program +....................................... + +On some targets, 'gdbserver' can also attach to running programs. This +is accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + In 'target extended-remote' mode, you can also attach using the GDB +attach command (*note Attaching in Types of Remote Connections::). + + You can debug processes by name instead of process ID if your target +has the 'pidof' utility: + + target> gdbserver --attach COMM `pidof PROGRAM` + + In case more than one copy of PROGRAM is running, or PROGRAM has +multiple threads, most versions of 'pidof' support the '-s' option to +only return the first process ID. + +20.3.1.2 TCP port allocation lifecycle of 'gdbserver' +..................................................... + +This section applies only when 'gdbserver' is run to listen on a TCP +port. + + 'gdbserver' normally terminates after all of its debugged processes +have terminated in 'target remote' mode. On the other hand, for 'target +extended-remote', 'gdbserver' stays running even with no processes left. +GDB normally terminates the spawned debugged process on its exit, which +normally also terminates 'gdbserver' in the 'target remote' mode. +Therefore, when the connection drops unexpectedly, and GDB cannot ask +'gdbserver' to kill its debugged processes, 'gdbserver' stays running +even in the 'target remote' mode. + + When 'gdbserver' stays running, GDB can connect to it again later. +Such reconnecting is useful for features like *note disconnected +tracing::. For completeness, at most one GDB can be connected at a +time. + + By default, 'gdbserver' keeps the listening TCP port open, so that +subsequent connections are possible. However, if you start 'gdbserver' +with the '--once' option, it will stop listening for any further +connection attempts after connecting to the first GDB session. This +means no further connections to 'gdbserver' will be possible after the +first one. It also means 'gdbserver' will terminate after the first +connection with remote GDB has closed, even for unexpectedly closed +connections and even in the 'target extended-remote' mode. The '--once' +option allows reusing the same port number for connecting to multiple +instances of 'gdbserver' running on the same host, since each instance +closes its port after the first connection. + +20.3.1.3 Other Command-Line Arguments for 'gdbserver' +..................................................... + +You can use the '--multi' option to start 'gdbserver' without specifying +a program to debug or a process to attach to. Then you can attach in +'target extended-remote' mode and run or attach to a program. For more +information, *note --multi Option in Types of Remote Connnections::. + + The '--debug[=option1,option2,...]' option tells 'gdbserver' to +display extra diagnostic information about the debugging process. The +options (OPTION1, OPTION2, etc) control for which areas of 'gdbserver' +additional information will be displayed, possible values are: + +'all' + This enables all available diagnostic output. +'threads' + This enables diagnostic output related to threading. Currently + other general diagnostic output is included in this category, but + this could change in future releases of 'gdbserver'. +'event-loop' + This enables event-loop specific diagnostic output. +'remote' + This enables diagnostic output related to the transfer of remote + protocol packets too and from the debugger. + +If no options are passed to '--debug' then this is treated as equivalent +to '--debug=threads'. This could change in future releases of +'gdbserver'. The options passed to '--debug' are processed left to +right, and individual options can be prefixed with the '-' (minus) +character to disable diagnostic output from this area, so it is possible +to use: + + target> gdbserver --debug=all,-event-loop + +In order to enable all diagnostic output except that for the event-loop. + + The '--debug-file=FILENAME' option tells 'gdbserver' to write any +debug output to the given FILENAME. These options are intended for +'gdbserver' development and for bug reports to the developers. + + The '--debug-format=option1[,option2,...]' option tells 'gdbserver' +to include additional information in each output. Possible options are: + +'none' + Turn off all extra information in debugging output. +'all' + Turn on all extra information in debugging output. +'timestamps' + Include a timestamp in each line of debugging output. + + Options are processed in order. Thus, for example, if 'none' appears +last then no additional information is added to debugging output. + + The '--wrapper' option specifies a wrapper to launch programs for +debugging. The option should be followed by the name of the wrapper, +then any command-line arguments to pass to the wrapper, then '--' +indicating the end of the wrapper arguments. + + 'gdbserver' runs the specified wrapper program with a combined +command line including the wrapper arguments, then the name of the +program to debug, then any arguments to the program. The wrapper runs +until it executes your program, and then GDB gains control. + + You can use any program that eventually calls 'execve' with its +arguments as a wrapper. Several standard Unix utilities do this, e.g. +'env' and 'nohup'. Any Unix shell script ending with 'exec "$@"' will +also work. + + For example, you can use 'env' to pass an environment variable to the +debugged program, without setting the variable in 'gdbserver''s +environment: + + $ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog + + The '--selftest' option runs the self tests in 'gdbserver': + + $ gdbserver --selftest + Ran 2 unit tests, 0 failed + + These tests are disabled in release. + +20.3.2 Connecting to 'gdbserver' +-------------------------------- + +The basic procedure for connecting to the remote target is: + + * Run GDB on the host system. + + * Make sure you have the necessary symbol files (*note Host and + target files::). Load symbols for your application using the + 'file' command before you connect. Use 'set sysroot' to locate + target libraries (unless your GDB was compiled with the correct + sysroot using '--with-sysroot'). + + * Connect to your target (*note Connecting to a Remote Target: + Connecting.). For TCP connections, you must start up 'gdbserver' + prior to using the 'target' command. Otherwise you may get an + error whose text depends on the host system, but which usually + looks something like 'Connection refused'. Don't use the 'load' + command in GDB when using 'target remote' mode, since the program + is already on the target. + +20.3.3 Monitor Commands for 'gdbserver' +--------------------------------------- + +During a GDB session using 'gdbserver', you can use the 'monitor' +command to send special requests to 'gdbserver'. Here are the available +commands. + +'monitor help' + List the available monitor commands. + +'monitor set debug off' + Disable all internal logging from gdbserver. + +'monitor set debug on' + Enable some general logging from within gdbserver. Currently this + is equivalent to 'monitor set debug threads on', but this might + change in future releases of gdbserver. + +'monitor set debug threads off' +'monitor set debug threads on' + Disable or enable specific logging messages associated with thread + handling in gdbserver. Currently this category also includes + additional output not specifically related to thread handling, this + could change in future releases of gdbserver. + +'monitor set debug remote off' +'monitor set debug remote on' + Disable or enable specific logging messages associated with the + remote protocol (*note Remote Protocol::). + +'monitor set debug event-loop off' +'monitor set debug event-loop on' + Disable or enable specific logging messages associated with + gdbserver's event-loop. + +'monitor set debug-file filename' +'monitor set debug-file' + Send any debug output to the given file, or to stderr. + +'monitor set debug-format option1[,option2,...]' + Specify additional text to add to debugging messages. Possible + options are: + + 'none' + Turn off all extra information in debugging output. + 'all' + Turn on all extra information in debugging output. + 'timestamps' + Include a timestamp in each line of debugging output. + + Options are processed in order. Thus, for example, if 'none' + appears last then no additional information is added to debugging + output. + +'monitor set libthread-db-search-path [PATH]' + When this command is issued, PATH is a colon-separated list of + directories to search for 'libthread_db' (*note set + libthread-db-search-path: Threads.). If you omit PATH, + 'libthread-db-search-path' will be reset to its default value. + + The special entry '$pdir' for 'libthread-db-search-path' is not + supported in 'gdbserver'. + +'monitor exit' + Tell gdbserver to exit immediately. This command should be + followed by 'disconnect' to close the debugging session. + 'gdbserver' will detach from any attached processes and kill any + processes it created. Use 'monitor exit' to terminate 'gdbserver' + at the end of a multi-process mode debug session. + +20.3.4 Tracepoints support in 'gdbserver' +----------------------------------------- + +On some targets, 'gdbserver' supports tracepoints, fast tracepoints and +static tracepoints. + + For fast or static tracepoints to work, a special library called the +"in-process agent" (IPA), must be loaded in the inferior process. This +library is built and distributed as an integral part of 'gdbserver'. In +addition, support for static tracepoints requires building the +in-process agent library with static tracepoints support. At present, +the UST (LTTng Userspace Tracer, ) tracing engine +is supported. This support is automatically available if UST +development headers are found in the standard include path when +'gdbserver' is built, or if 'gdbserver' was explicitly configured using +'--with-ust' to point at such headers. You can explicitly disable the +support using '--with-ust=no'. + + There are several ways to load the in-process agent in your program: + +'Specifying it as dependency at link time' + + You can link your program dynamically with the in-process agent + library. On most systems, this is accomplished by adding + '-linproctrace' to the link command. + +'Using the system's preloading mechanisms' + + You can force loading the in-process agent at startup time by using + your system's support for preloading shared libraries. Many Unixes + support the concept of preloading user defined libraries. In most + cases, you do that by specifying 'LD_PRELOAD=libinproctrace.so' in + the environment. See also the description of 'gdbserver''s + '--wrapper' command line option. + +'Using GDB to force loading the agent at run time' + + On some systems, you can force the inferior to load a shared + library, by calling a dynamic loader function in the inferior that + takes care of dynamically looking up and loading a shared library. + On most Unix systems, the function is 'dlopen'. You'll use the + 'call' command for that. For example: + + (gdb) call dlopen ("libinproctrace.so", ...) + + Note that on most Unix systems, for the 'dlopen' function to be + available, the program needs to be linked with '-ldl'. + + On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to 'gdbserver' using 'target remote', you'll +find that the program is stopped at the dynamic loader's entry point, +and no shared library has been loaded in the program's address space +yet, including the in-process agent. In that case, before being able to +use any of the fast or static tracepoints features, you need to let the +loader run and load the shared libraries. The simplest way to do that +is to run the program to the main procedure. E.g., if debugging a C or +C++ program, start 'gdbserver' like so: + + $ gdbserver :9999 myprogram + + Start GDB and connect to 'gdbserver' like so, and run to main: + + $ gdb myprogram + (gdb) target remote myhost:9999 + 0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 + (gdb) b main + (gdb) continue + + The in-process tracing agent library should now be loaded into the +process; you can confirm it with the 'info sharedlibrary' command, which +will list 'libinproctrace.so' as loaded in the process. You are now +ready to install fast tracepoints, list static tracepoint markers, probe +static tracepoints markers, and start tracing. + + ---------- Footnotes ---------- + + (1) If you choose a port number that conflicts with another service, +'gdbserver' prints an error message and exits. + + +File: gdb.info, Node: Remote Configuration, Next: Remote Stub, Prev: Server, Up: Remote Debugging + +20.4 Remote Configuration +========================= + +This section documents the configuration options available when +debugging remote programs. For the options related to the File I/O +extensions of the remote protocol, see *note system-call-allowed: +system. + +'set remoteaddresssize BITS' + Set the maximum size of address in a memory packet to the specified + number of bits. GDB will mask off the address bits above that + number, when it passes addresses to the remote target. The default + value is the number of bits in the target's address. + +'show remoteaddresssize' + Show the current value of remote address size in bits. + +'set serial baud N' + Set the baud rate for the remote serial I/O to N baud. The value + is used to set the speed of the serial port used for debugging + remote targets. + +'show serial baud' + Show the current speed of the remote connection. + +'set serial parity PARITY' + Set the parity for the remote serial I/O. Supported values of + PARITY are: 'even', 'none', and 'odd'. The default is 'none'. + +'show serial parity' + Show the current parity of the serial port. + +'set remotebreak' + If set to on, GDB sends a 'BREAK' signal to the remote when you + type 'Ctrl-c' to interrupt the program running on the remote. If + set to off, GDB sends the 'Ctrl-C' character instead. The default + is off, since most remote systems expect to see 'Ctrl-C' as the + interrupt signal. + +'show remotebreak' + Show whether GDB sends 'BREAK' or 'Ctrl-C' to interrupt the remote + program. + +'set remoteflow on' +'set remoteflow off' + Enable or disable hardware flow control ('RTS'/'CTS') on the serial + port used to communicate to the remote target. + +'show remoteflow' + Show the current setting of hardware flow control. + +'set remotelogbase BASE' + Set the base (a.k.a. radix) of logging serial protocol + communications to BASE. Supported values of BASE are: 'ascii', + 'octal', and 'hex'. The default is 'ascii'. + +'show remotelogbase' + Show the current setting of the radix for logging remote serial + protocol. + +'set remotelogfile FILE' + Record remote serial communications on the named FILE. The default + is not to record at all. + +'show remotelogfile' + Show the current setting of the file name on which to record the + serial communications. + +'set remotetimeout NUM' + Set the timeout limit to wait for the remote target to respond to + NUM seconds. The default is 2 seconds. + +'show remotetimeout' + Show the current number of seconds to wait for the remote target + responses. + +'set remote hardware-watchpoint-limit LIMIT' +'set remote hardware-breakpoint-limit LIMIT' + Restrict GDB to using LIMIT remote hardware watchpoints or + breakpoints. The LIMIT can be set to 0 to disable hardware + watchpoints or breakpoints, and 'unlimited' for unlimited + watchpoints or breakpoints. + +'show remote hardware-watchpoint-limit' +'show remote hardware-breakpoint-limit' + Show the current limit for the number of hardware watchpoints or + breakpoints that GDB can use. + +'set remote hardware-watchpoint-length-limit LIMIT' + Restrict GDB to using LIMIT bytes for the maximum length of a + remote hardware watchpoint. A LIMIT of 0 disables hardware + watchpoints and 'unlimited' allows watchpoints of any length. + +'show remote hardware-watchpoint-length-limit' + Show the current limit (in bytes) of the maximum length of a remote + hardware watchpoint. + +'set remote exec-file FILENAME' +'show remote exec-file' + Select the file used for 'run' with 'target extended-remote'. This + should be set to a filename valid on the target system. If it is + not set, the target will use a default filename (e.g. the last + program run). + +'set remote interrupt-sequence' + Allow the user to select one of 'Ctrl-C', a 'BREAK' or 'BREAK-g' as + the sequence to the remote target in order to interrupt the + execution. 'Ctrl-C' is a default. Some system prefers 'BREAK' + which is high level of serial line for some certain time. Linux + kernel prefers 'BREAK-g', a.k.a Magic SysRq g. It is 'BREAK' + signal followed by character 'g'. + +'show remote interrupt-sequence' + Show which of 'Ctrl-C', 'BREAK' or 'BREAK-g' is sent by GDB to + interrupt the remote program. 'BREAK-g' is BREAK signal followed + by 'g' and also known as Magic SysRq g. + +'set remote interrupt-on-connect' + Specify whether interrupt-sequence is sent to remote target when + GDB connects to it. This is mostly needed when you debug Linux + kernel. Linux kernel expects 'BREAK' followed by 'g' which is + known as Magic SysRq g in order to connect GDB. + +'show remote interrupt-on-connect' + Show whether interrupt-sequence is sent to remote target when GDB + connects to it. + +'set tcp auto-retry on' + Enable auto-retry for remote TCP connections. This is useful if + the remote debugging agent is launched in parallel with GDB; there + is a race condition because the agent may not become ready to + accept the connection before GDB attempts to connect. When + auto-retry is enabled, if the initial attempt to connect fails, GDB + reattempts to establish the connection using the timeout specified + by 'set tcp connect-timeout'. + +'set tcp auto-retry off' + Do not auto-retry failed TCP connections. + +'show tcp auto-retry' + Show the current auto-retry setting. + +'set tcp connect-timeout SECONDS' +'set tcp connect-timeout unlimited' + Set the timeout for establishing a TCP connection to the remote + target to SECONDS. The timeout affects both polling to retry + failed connections (enabled by 'set tcp auto-retry on') and waiting + for connections that are merely slow to complete, and represents an + approximate cumulative value. If SECONDS is 'unlimited', there is + no timeout and GDB will keep attempting to establish a connection + forever, unless interrupted with 'Ctrl-c'. The default is 15 + seconds. + +'show tcp connect-timeout' + Show the current connection timeout setting. + + The GDB remote protocol autodetects the packets supported by your +debugging stub. If you need to override the autodetection, you can use +these commands to enable or disable individual packets. Each packet can +be set to 'on' (the remote target supports this packet), 'off' (the +remote target does not support this packet), or 'auto' (detect remote +target support for this packet). They all default to 'auto'. For more +information about each packet, see *note Remote Protocol::. + + During normal use, you should not have to use any of these commands. +If you do, that may be a bug in your remote debugging stub, or a bug in +GDB. You may want to report the problem to the GDB developers. + + For each packet NAME, the command to enable or disable the packet is +'set remote NAME-packet'. If you configure a packet, the configuration +will apply for all future remote targets if no target is selected. In +case there is a target selected, only the configuration of the current +target is changed. All other existing remote targets' features are not +affected. The command to print the current configuration of a packet is +'show remote NAME-packet'. It displays the current remote target's +configuration. If no remote target is selected, the default +configuration for future connections is shown. The available settings +are: + +Command Name Remote Packet Related Features + +'fetch-register' 'p' 'info registers' + +'set-register' 'P' 'set' + +'binary-download' 'X' 'load', 'set' + +'read-aux-vector' 'qXfer:auxv:read' 'info auxv' + +'symbol-lookup' 'qSymbol' Detecting + multiple threads + +'attach' 'vAttach' 'attach' + +'verbose-resume' 'vCont' Stepping or + resuming + multiple threads + +'run' 'vRun' 'run' + +'software-breakpoint''Z0' 'break' + +'hardware-breakpoint''Z1' 'hbreak' + +'write-watchpoint' 'Z2' 'watch' + +'read-watchpoint' 'Z3' 'rwatch' + +'access-watchpoint' 'Z4' 'awatch' + +'pid-to-exec-file' 'qXfer:exec-file:read' 'attach', 'run' + +'target-features' 'qXfer:features:read' 'set + architecture' + +'library-info' 'qXfer:libraries:read' 'info + sharedlibrary' + +'memory-map' 'qXfer:memory-map:read' 'info mem' + +'read-sdata-object' 'qXfer:sdata:read' 'print $_sdata' + +'read-siginfo-object''qXfer:siginfo:read' 'print + $_siginfo' + +'write-siginfo-object''qXfer:siginfo:write' 'set $_siginfo' + +'threads' 'qXfer:threads:read' 'info threads' + +'get-thread-local- 'qGetTLSAddr' Displaying +storage-address' '__thread' + variables + +'get-thread-information-block-address''qGetTIBAddr'Display + MS-Windows + Thread + Information + Block. + +'search-memory' 'qSearch:memory' 'find' + +'supported-packets' 'qSupported' Remote + communications + parameters + +'catch-syscalls' 'QCatchSyscalls' 'catch syscall' + +'pass-signals' 'QPassSignals' 'handle SIGNAL' + +'program-signals' 'QProgramSignals' 'handle SIGNAL' + +'hostio-close-packet''vFile:close' 'remote get', + 'remote put' + +'hostio-open-packet' 'vFile:open' 'remote get', + 'remote put' + +'hostio-pread-packet''vFile:pread' 'remote get', + 'remote put' + +'hostio-pwrite-packet''vFile:pwrite' 'remote get', + 'remote put' + +'hostio-unlink-packet''vFile:unlink' 'remote delete' + +'hostio-readlink-packet''vFile:readlink' Host I/O + +'hostio-fstat-packet''vFile:fstat' Host I/O + +'hostio-stat-packet' 'vFile:stat' Host I/O + +'hostio-setfs-packet''vFile:setfs' Host I/O + +'noack-packet' 'QStartNoAckMode' Packet + acknowledgment + +'osdata' 'qXfer:osdata:read' 'info os' + +'query-attached' 'qAttached' Querying remote + process attach + state. + +'trace-buffer-size' 'QTBuffer:size' 'set + trace-buffer-size' + +'trace-status' 'qTStatus' 'tstatus' + +'traceframe-info' 'qXfer:traceframe-info:read'Traceframe info + +'install-in-trace' 'InstallInTrace' Install + tracepoint in + tracing + +'disable-randomization''QDisableRandomization''set + disable-randomization' + +'startup-with-shell' 'QStartupWithShell' 'set + startup-with-shell' + +'environment-hex-encoded''QEnvironmentHexEncoded''set + environment' + +'environment-unset' 'QEnvironmentUnset' 'unset + environment' + +'environment-reset' 'QEnvironmentReset' 'Reset the + inferior + environment + (i.e., unset + user-set + variables)' + +'set-working-dir' 'QSetWorkingDir' 'set cwd' + +'conditional-breakpoints-packet''Z0 and Z1' 'Support for + target-side + breakpoint + condition + evaluation' + +'multiprocess-extensions''multiprocess Debug multiple + extensions' processes and + remote process + PID awareness + +'swbreak-feature' 'swbreak stop reason' 'break' + +'hwbreak-feature' 'hwbreak stop reason' 'hbreak' + +'fork-event-feature' 'fork stop reason' 'fork' + +'vfork-event-feature''vfork stop reason' 'vfork' + +'exec-event-feature' 'exec stop reason' 'exec' + +'thread-events' 'QThreadEvents' Tracking thread + lifetime. + +'thread-options' 'QThreadOptions' Set thread event + reporting + options. + +'no-resumed-stop-reply''no resumed thread Tracking thread + left stop reply' lifetime. + + + The number of bytes per memory-read or memory-write packet for a +remote target can be configured using the commands +'set remote memory-read-packet-size' and +'set remote memory-write-packet-size'. If set to '0' (zero) the default +packet size will be used. The actual limit is further reduced depending +on the target. Specify 'fixed' to disable the target-dependent +restriction and 'limit' to enable it. Similar to the enabling and +disabling of remote packets, the command applies to the currently +selected target (if available). If no remote target is selected, it +applies to all future remote connections. The configuration of the +selected target can be displayed using the commands +'show remote memory-read-packet-size' and +'show remote memory-write-packet-size'. If no remote target is +selected, the default configuration for future connections is shown. + + +File: gdb.info, Node: Remote Stub, Prev: Remote Configuration, Up: Remote Debugging + +20.5 Implementing a Remote Stub +=============================== + +The stub files provided with GDB implement the target side of the +communication protocol, and the GDB side is implemented in the GDB +source file 'remote.c'. Normally, you can simply allow these +subroutines to communicate, and ignore the details. (If you're +implementing your own stub file, you can still ignore the details: start +with one of the existing stub files. 'sparc-stub.c' is the best +organized, and therefore the easiest to read.) + + To debug a program running on another machine (the debugging "target" +machine), you must first arrange for all the usual prerequisites for the +program to run by itself. For example, for a C program, you need: + + 1. A startup routine to set up the C runtime environment; these + usually have a name like 'crt0'. The startup routine may be + supplied by your hardware supplier, or you may have to write your + own. + + 2. A C subroutine library to support your program's subroutine calls, + notably managing input and output. + + 3. A way of getting your program to the other machine--for example, a + download program. These are often supplied by the hardware + manufacturer, but you may have to write your own from hardware + documentation. + + The next step is to arrange for your program to use a serial port to +communicate with the machine where GDB is running (the "host" machine). +In general terms, the scheme looks like this: + +_On the host,_ + GDB already understands how to use this protocol; when everything + else is set up, you can simply use the 'target remote' command + (*note Specifying a Debugging Target: Targets.). + +_On the target,_ + you must link with your program a few special-purpose subroutines + that implement the GDB remote serial protocol. The file containing + these subroutines is called a "debugging stub". + + On certain remote targets, you can use an auxiliary program + 'gdbserver' instead of linking a stub into your program. *Note + Using the 'gdbserver' Program: Server, for details. + + The debugging stub is specific to the architecture of the remote +machine; for example, use 'sparc-stub.c' to debug programs on SPARC +boards. + + These working remote stubs are distributed with GDB: + +'i386-stub.c' + For Intel 386 and compatible architectures. + +'m68k-stub.c' + For Motorola 680x0 architectures. + +'sh-stub.c' + For Renesas SH architectures. + +'sparc-stub.c' + For SPARC architectures. + +'sparcl-stub.c' + For Fujitsu SPARCLITE architectures. + + The 'README' file in the GDB distribution may list other recently +added stubs. + +* Menu: + +* Stub Contents:: What the stub can do for you +* Bootstrapping:: What you must do for the stub +* Debug Session:: Putting it all together + + +File: gdb.info, Node: Stub Contents, Next: Bootstrapping, Up: Remote Stub + +20.5.1 What the Stub Can Do for You +----------------------------------- + +The debugging stub for your architecture supplies these three +subroutines: + +'set_debug_traps' + This routine arranges for 'handle_exception' to run when your + program stops. You must call this subroutine explicitly in your + program's startup code. + +'handle_exception' + This is the central workhorse, but your program never calls it + explicitly--the setup code arranges for 'handle_exception' to run + when a trap is triggered. + + 'handle_exception' takes control when your program stops during + execution (for example, on a breakpoint), and mediates + communications with GDB on the host machine. This is where the + communications protocol is implemented; 'handle_exception' acts as + the GDB representative on the target machine. It begins by sending + summary information on the state of your program, then continues to + execute, retrieving and transmitting any information GDB needs, + until you execute a GDB command that makes your program resume; at + that point, 'handle_exception' returns control to your own code on + the target machine. + +'breakpoint' + Use this auxiliary subroutine to make your program contain a + breakpoint. Depending on the particular situation, this may be the + only way for GDB to get control. For instance, if your target + machine has some sort of interrupt button, you won't need to call + this; pressing the interrupt button transfers control to + 'handle_exception'--in effect, to GDB. On some machines, simply + receiving characters on the serial port may also trigger a trap; + again, in that situation, you don't need to call 'breakpoint' from + your own program--simply running 'target remote' from the host GDB + session gets control. + + Call 'breakpoint' if none of these is true, or if you simply want + to make certain your program stops at a predetermined point for the + start of your debugging session. + + +File: gdb.info, Node: Bootstrapping, Next: Debug Session, Prev: Stub Contents, Up: Remote Stub + +20.5.2 What You Must Do for the Stub +------------------------------------ + +The debugging stubs that come with GDB are set up for a particular chip +architecture, but they have no information about the rest of your +debugging target machine. + + First of all you need to tell the stub how to communicate with the +serial port. + +'int getDebugChar()' + Write this subroutine to read a single character from the serial + port. It may be identical to 'getchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + +'void putDebugChar(int)' + Write this subroutine to write a single character to the serial + port. It may be identical to 'putchar' for your target system; a + different name is used to allow you to distinguish the two if you + wish. + + If you want GDB to be able to stop your program while it is running, +you need to use an interrupt-driven serial driver, and arrange for it to +stop when it receives a '^C' ('\003', the control-C character). That is +the character which GDB uses to tell the remote system to stop. + + Getting the debugging target to return the proper status to GDB +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the "dirty" part is that +GDB reports a 'SIGTRAP' instead of a 'SIGINT'). + + Other routines you need to supply are: + +'void exceptionHandler (int EXCEPTION_NUMBER, void *EXCEPTION_ADDRESS)' + Write this function to install EXCEPTION_ADDRESS in the exception + handling tables. You need to do this because the stub does not + have any way of knowing what the exception handling tables on your + target system are like (for example, the processor's table might be + in ROM, containing entries which point to a table in RAM). The + EXCEPTION_NUMBER specifies the exception which should be changed; + its meaning is architecture-dependent (for example, different + numbers might represent divide by zero, misaligned access, etc). + When this exception occurs, control should be transferred directly + to EXCEPTION_ADDRESS, and the processor state (stack, registers, + and so on) should be just as it is when a processor exception + occurs. So if you want to use a jump instruction to reach + EXCEPTION_ADDRESS, it should be a simple jump, not a jump to + subroutine. + + For the 386, EXCEPTION_ADDRESS should be installed as an interrupt + gate so that interrupts are masked while the handler runs. The + gate should be at privilege level 0 (the most privileged level). + The SPARC and 68k stubs are able to mask interrupts themselves + without help from 'exceptionHandler'. + +'void flush_i_cache()' + On SPARC and SPARCLITE only, write this subroutine to flush the + instruction cache, if any, on your target machine. If there is no + instruction cache, this subroutine may be a no-op. + + On target machines that have instruction caches, GDB requires this + function to make certain that the state of your program is stable. + +You must also make sure this library routine is available: + +'void *memset(void *, int, int)' + This is the standard library function 'memset' that sets an area of + memory to a known value. If you have one of the free versions of + 'libc.a', 'memset' can be found there; otherwise, you must either + obtain it from your hardware manufacturer, or write your own. + + If you do not use the GNU C compiler, you may need other standard +library subroutines as well; this varies from one stub to another, but +in general the stubs are likely to use any of the common library +subroutines which 'GCC' generates as inline code. + diff -pruN 16.3-5/gdb/doc/gdb.info-4 16.3-5ubuntu1/gdb/doc/gdb.info-4 --- 16.3-5/gdb/doc/gdb.info-4 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-4 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,7420 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Debug Session, Prev: Bootstrapping, Up: Remote Stub + +20.5.3 Putting it All Together +------------------------------ + +In summary, when your program is ready to debug, you must follow these +steps. + + 1. Make sure you have defined the supporting low-level routines (*note + What You Must Do for the Stub: Bootstrapping.): + 'getDebugChar', 'putDebugChar', + 'flush_i_cache', 'memset', 'exceptionHandler'. + + 2. Insert these lines in your program's startup code, before the main + procedure is called: + + set_debug_traps(); + breakpoint(); + + On some machines, when a breakpoint trap is raised, the hardware + automatically makes the PC point to the instruction after the + breakpoint. If your machine doesn't do that, you may need to + adjust 'handle_exception' to arrange for it to return to the + instruction after the breakpoint on this first invocation, so that + your program doesn't keep hitting the initial breakpoint instead of + making progress. + + 3. For the 680x0 stub only, you need to provide a variable called + 'exceptionHook'. Normally you just use: + + void (*exceptionHook)() = 0; + + but if before calling 'set_debug_traps', you set it to point to a + function in your program, that function is called when 'GDB' + continues after stopping on a trap (for example, bus error). The + function indicated by 'exceptionHook' is called with one parameter: + an 'int' which is the exception number. + + 4. Compile and link together: your program, the GDB debugging stub for + your target architecture, and the supporting subroutines. + + 5. Make sure you have a serial connection between your target machine + and the GDB host, and identify the serial port on the host. + + 6. Download your program to your target machine (or get it there by + whatever means the manufacturer provides), and start it. + + 7. Start GDB on the host, and connect to the target (*note Connecting + to a Remote Target: Connecting.). + + +File: gdb.info, Node: Configurations, Next: Controlling GDB, Prev: Remote Debugging, Up: Top + +21 Configuration-Specific Information +************************************* + +While nearly all GDB commands are available for all native and cross +versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. + + There are three major categories of configurations: native +configurations, where the host and target are the same, embedded +operating system configurations, which are usually the same for several +different processor architectures, and bare embedded processors, which +are quite different from each other. + +* Menu: + +* Native:: +* Embedded OS:: +* Embedded Processors:: +* Architectures:: + + +File: gdb.info, Node: Native, Next: Embedded OS, Up: Configurations + +21.1 Native +=========== + +This section describes details specific to particular native +configurations. + +* Menu: + +* BSD libkvm Interface:: Debugging BSD kernel memory images +* Process Information:: Process information +* DJGPP Native:: Features specific to the DJGPP port +* Cygwin Native:: Features specific to the Cygwin port +* Hurd Native:: Features specific to GNU Hurd +* Darwin:: Features specific to Darwin +* FreeBSD:: Features specific to FreeBSD + + +File: gdb.info, Node: BSD libkvm Interface, Next: Process Information, Up: Native + +21.1.1 BSD libkvm Interface +--------------------------- + +BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory +interface that provides a uniform interface for accessing kernel virtual +memory images, including live systems and crash dumps. GDB uses this +interface to allow you to debug live kernels and kernel crash dumps on +many native BSD configurations. This is implemented as a special 'kvm' +debugging target. For debugging a live system, load the currently +running kernel into GDB and connect to the 'kvm' target: + + (gdb) target kvm + + For debugging crash dumps, provide the file name of the crash dump as +an argument: + + (gdb) target kvm /var/crash/bsd.0 + + Once connected to the 'kvm' target, the following commands are +available: + +'kvm pcb' + Set current context from the "Process Control Block" (PCB) address. + +'kvm proc' + Set current context from proc address. This command isn't + available on modern FreeBSD systems. + + +File: gdb.info, Node: Process Information, Next: DJGPP Native, Prev: BSD libkvm Interface, Up: Native + +21.1.2 Process Information +-------------------------- + +Some operating systems provide interfaces to fetch additional +information about running processes beyond memory and per-thread +register state. If GDB is configured for an operating system with a +supported interface, the command 'info proc' is available to report +information about the process running your program, or about any process +running on your system. + + One supported interface is a facility called '/proc' that can be used +to examine the image of a running process using file-system subroutines. +This facility is supported on GNU/Linux and Solaris systems. + + On FreeBSD and NetBSD systems, system control nodes are used to query +process information. + + In addition, some systems may provide additional process information +in core files. Note that a core file may include a subset of the +information available from a live process. Process information is +currently available from cores created on GNU/Linux and FreeBSD systems. + +'info proc' +'info proc PROCESS-ID' + Summarize available information about a process. If a process ID + is specified by PROCESS-ID, display information about that process; + otherwise display information about the program being debugged. + The summary includes the debugged process ID, the command line used + to invoke it, its current working directory, and its executable + file's absolute file name. + + On some systems, PROCESS-ID can be of the form '[PID]/TID' which + specifies a certain thread ID within a process. If the optional + PID part is missing, it means a thread from the process being + debugged (the leading '/' still needs to be present, or else GDB + will interpret the number as a process ID rather than a thread ID). + +'info proc cmdline' + Show the original command line of the process. This command is + supported on GNU/Linux, FreeBSD and NetBSD. + +'info proc cwd' + Show the current working directory of the process. This command is + supported on GNU/Linux, FreeBSD and NetBSD. + +'info proc exe' + Show the name of executable of the process. This command is + supported on GNU/Linux, FreeBSD and NetBSD. + +'info proc files' + Show the file descriptors open by the process. For each open file + descriptor, GDB shows its number, type (file, directory, character + device, socket), file pointer offset, and the name of the resource + open on the descriptor. The resource name can be a file name (for + files, directories, and devices) or a protocol followed by socket + address (for network connections). This command is supported on + FreeBSD. + + This example shows the open file descriptors for a process using a + tty for standard input and output as well as two network sockets: + + (gdb) info proc files 22136 + process 22136 + Open files: + + FD Type Offset Flags Name + text file - r-------- /usr/bin/ssh + ctty chr - rw------- /dev/pts/20 + cwd dir - r-------- /usr/home/john + root dir - r-------- / + 0 chr 0x32933a4 rw------- /dev/pts/20 + 1 chr 0x32933a4 rw------- /dev/pts/20 + 2 chr 0x32933a4 rw------- /dev/pts/20 + 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22 + 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456 + +'info proc mappings' + Report the memory address space ranges accessible in a process. On + Solaris, FreeBSD and NetBSD systems, each memory range includes + information on whether the process has read, write, or execute + access rights to each range. On GNU/Linux, FreeBSD and NetBSD + systems, each memory range includes the object file which is mapped + to that range. + +'info proc stat' +'info proc status' + Show additional process-related information, including the user ID + and group ID; virtual memory usage; the signals that are pending, + blocked, and ignored; its TTY; its consumption of system and user + time; its stack size; its 'nice' value; etc. These commands are + supported on GNU/Linux, FreeBSD and NetBSD. + + For GNU/Linux systems, see the 'proc' man page for more information + (type 'man 5 proc' from your shell prompt). + + For FreeBSD and NetBSD systems, 'info proc stat' is an alias for + 'info proc status'. + +'info proc all' + Show all the information about the process described under all of + the above 'info proc' subcommands. + +'set procfs-trace' + This command enables and disables tracing of 'procfs' API calls. + +'show procfs-trace' + Show the current state of 'procfs' API call tracing. + +'set procfs-file FILE' + Tell GDB to write 'procfs' API trace to the named FILE. GDB + appends the trace info to the previous contents of the file. The + default is to display the trace on the standard output. + +'show procfs-file' + Show the file to which 'procfs' API trace is written. + +'proc-trace-entry' +'proc-trace-exit' +'proc-untrace-entry' +'proc-untrace-exit' + These commands enable and disable tracing of entries into and exits + from the 'syscall' interface. + + +File: gdb.info, Node: DJGPP Native, Next: Cygwin Native, Prev: Process Information, Up: Native + +21.1.3 Features for Debugging DJGPP Programs +-------------------------------------------- + +DJGPP is a port of the GNU development tools to MS-DOS and MS-Windows. +DJGPP programs are 32-bit protected-mode programs that use the "DPMI" +(DOS Protected-Mode Interface) API to run on top of real-mode DOS +systems and their emulations. + + GDB supports native debugging of DJGPP programs, and defines a few +commands specific to the DJGPP port. This subsection describes those +commands. + +'info dos' + This is a prefix of DJGPP-specific commands which print information + about the target system and important OS structures. + +'info dos sysinfo' + This command displays assorted information about the underlying + platform: the CPU type and features, the OS version and flavor, the + DPMI version, and the available conventional and DPMI memory. + +'info dos gdt' +'info dos ldt' +'info dos idt' + These 3 commands display entries from, respectively, Global, Local, + and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor + tables are data structures which store a descriptor for each + segment that is currently in use. The segment's selector is an + index into a descriptor table; the table entry for that index holds + the descriptor's base address and limit, and its attributes and + access rights. + + A typical DJGPP program uses 3 segments: a code segment, a data + segment (used for both data and the stack), and a DOS segment + (which allows access to DOS/BIOS data structures and absolute + addresses in conventional memory). However, the DPMI host will + usually define additional segments in order to support the DPMI + environment. + + These commands allow to display entries from the descriptor tables. + Without an argument, all entries from the specified table are + displayed. An argument, which should be an integer expression, + means display a single entry whose index is given by the argument. + For example, here's a convenient way to display information about + the debugged program's data segment: + + (gdb) info dos ldt $ds + 0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up) + + This comes in handy when you want to see whether a pointer is + outside the data segment's limit (i.e. "garbled"). + +'info dos pde' +'info dos pte' + These two commands display entries from, respectively, the Page + Directory and the Page Tables. Page Directories and Page Tables + are data structures which control how virtual memory addresses are + mapped into physical addresses. A Page Table includes an entry for + every page of memory that is mapped into the program's address + space; there may be several Page Tables, each one holding up to + 4096 entries. A Page Directory has up to 4096 entries, one each + for every Page Table that is currently in use. + + Without an argument, 'info dos pde' displays the entire Page + Directory, and 'info dos pte' displays all the entries in all of + the Page Tables. An argument, an integer expression, given to the + 'info dos pde' command means display only that entry from the Page + Directory table. An argument given to the 'info dos pte' command + means display entries from a single Page Table, the one pointed to + by the specified entry in the Page Directory. + + These commands are useful when your program uses "DMA" (Direct + Memory Access), which needs physical addresses to program the DMA + controller. + + These commands are supported only with some DPMI servers. + +'info dos address-pte ADDR' + This command displays the Page Table entry for a specified linear + address. The argument ADDR is a linear address which should + already have the appropriate segment's base address added to it, + because this command accepts addresses which may belong to _any_ + segment. For example, here's how to display the Page Table entry + for the page where a variable 'i' is stored: + + (gdb) info dos address-pte __djgpp_base_address + (char *)&i + Page Table entry for address 0x11a00d30: + Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30 + + This says that 'i' is stored at offset '0xd30' from the page whose + physical base address is '0x02698000', and shows all the attributes + of that page. + + Note that you must cast the addresses of variables to a 'char *', + since otherwise the value of '__djgpp_base_address', the base + address of all variables and functions in a DJGPP program, will be + added using the rules of C pointer arithmetic: if 'i' is declared + an 'int', GDB will add 4 times the value of '__djgpp_base_address' + to the address of 'i'. + + Here's another example, it displays the Page Table entry for the + transfer buffer: + + (gdb) info dos address-pte *((unsigned *)&_go32_info_block + 3) + Page Table entry for address 0x29110: + Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110 + + (The '+ 3' offset is because the transfer buffer's address is the + 3rd member of the '_go32_info_block' structure.) The output + clearly shows that this DPMI server maps the addresses in + conventional memory 1:1, i.e. the physical ('0x00029000' + '0x110') + and linear ('0x29110') addresses are identical. + + This command is supported only with some DPMI servers. + + In addition to native debugging, the DJGPP port supports remote +debugging via a serial data link. The following commands are specific +to remote serial debugging in the DJGPP port of GDB. + +'set com1base ADDR' + This command sets the base I/O port address of the 'COM1' serial + port. + +'set com1irq IRQ' + This command sets the "Interrupt Request" ('IRQ') line to use for + the 'COM1' serial port. + + There are similar commands 'set com2base', 'set com3irq', etc. for + setting the port address and the 'IRQ' lines for the other 3 COM + ports. + + The related commands 'show com1base', 'show com1irq' etc. display + the current settings of the base address and the 'IRQ' lines used + by the COM ports. + +'info serial' + This command prints the status of the 4 DOS serial ports. For each + port, it prints whether it's active or not, its I/O base address + and IRQ number, whether it uses a 16550-style FIFO, its baudrate, + and the counts of various errors encountered so far. + + +File: gdb.info, Node: Cygwin Native, Next: Hurd Native, Prev: DJGPP Native, Up: Native + +21.1.4 Features for Debugging MS Windows PE Executables +------------------------------------------------------- + +GDB supports native debugging of MS Windows programs, including DLLs +with and without symbolic debugging information. + + MS-Windows programs that call 'SetConsoleMode' to switch off the +special meaning of the 'Ctrl-C' keystroke cannot be interrupted by +typing 'C-c'. For this reason, GDB on MS-Windows supports 'C-' +as an alternative interrupt key sequence, which can be used to interrupt +the debuggee even if it ignores 'C-c'. + + There are various additional Cygwin-specific commands, described in +this section. Working with DLLs that have no debugging symbols is +described in *note Non-debug DLL Symbols::. + +'info w32' + This is a prefix of MS Windows-specific commands which print + information about the target system and important OS structures. + +'info w32 selector' + This command displays information returned by the Win32 API + 'GetThreadSelectorEntry' function. It takes an optional argument + that is evaluated to a long value to give the information about + this given selector. Without argument, this command displays + information about the six segment registers. + +'info w32 thread-information-block' + This command displays thread specific information stored in the + Thread Information Block (readable on the X86 CPU family using + '$fs' selector for 32-bit programs and '$gs' for 64-bit programs). + +'signal-event ID' + This command signals an event with user-provided ID. Used to + resume crashing process when attached to it using MS-Windows JIT + debugging (AeDebug). + + To use it, create or edit the following keys in + 'HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug' and/or + 'HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows + NT\CurrentVersion\AeDebug' (for x86_64 versions): + + - 'Debugger' (REG_SZ) -- a command to launch the debugger. + Suggested command is: 'FULLY-QUALIFIED-PATH-TO-GDB.EXE -ex + "attach %ld" -ex "signal-event %ld" -ex "continue"'. + + The first '%ld' will be replaced by the process ID of the + crashing process, the second '%ld' will be replaced by the ID + of the event that blocks the crashing process, waiting for GDB + to attach. + + - 'Auto' (REG_SZ) -- either '1' or '0'. '1' will make the + system run debugger specified by the Debugger key + automatically, '0' will cause a dialog box with "OK" and + "Cancel" buttons to appear, which allows the user to either + terminate the crashing process (OK) or debug it (Cancel). + +'set cygwin-exceptions MODE' + If MODE is 'on', GDB will break on exceptions that happen inside + the Cygwin DLL. If MODE is 'off', GDB will delay recognition of + exceptions, and may ignore some exceptions which seem to be caused + by internal Cygwin DLL "bookkeeping". This option is meant + primarily for debugging the Cygwin DLL itself; the default value is + 'off' to avoid annoying GDB users with false 'SIGSEGV' signals. + +'show cygwin-exceptions' + Displays whether GDB will break on exceptions that happen inside + the Cygwin DLL itself. + +'set new-console MODE' + If MODE is 'on' the debuggee will be started in a new console on + next start. If MODE is 'off', the debuggee will be started in the + same console as the debugger. + +'show new-console' + Displays whether a new console is used when the debuggee is + started. + +'set new-group MODE' + This boolean value controls whether the debuggee should start a new + group or stay in the same group as the debugger. This affects the + way the Windows OS handles 'Ctrl-C'. + +'show new-group' + Displays current value of new-group boolean. + +'set debugevents' + This boolean value adds debug output concerning kernel events + related to the debuggee seen by the debugger. This includes events + that signal thread and process creation and exit, DLL loading and + unloading, console interrupts, and debugging messages produced by + the Windows 'OutputDebugString' API call. + +'set debugexec' + This boolean value adds debug output concerning execute events + (such as resume thread) seen by the debugger. + +'set debugexceptions' + This boolean value adds debug output concerning exceptions in the + debuggee seen by the debugger. + +'set debugmemory' + This boolean value adds debug output concerning debuggee memory + reads and writes by the debugger. + +'set shell' + This boolean values specifies whether the debuggee is called via a + shell or directly (default value is on). + +'show shell' + Displays if the debuggee will be started with a shell. + +* Menu: + +* Non-debug DLL Symbols:: Support for DLLs without debugging symbols + + +File: gdb.info, Node: Non-debug DLL Symbols, Up: Cygwin Native + +21.1.4.1 Support for DLLs without Debugging Symbols +................................................... + +Very often on windows, some of the DLLs that your program relies on do +not include symbolic debugging information (for example, +'kernel32.dll'). When GDB doesn't recognize any debugging symbols in a +DLL, it relies on the minimal amount of symbolic information contained +in the DLL's export table. This section describes working with such +symbols, known internally to GDB as "minimal symbols". + + Note that before the debugged program has started execution, no DLLs +will have been loaded. The easiest way around this problem is simply to +start the program -- either by setting a breakpoint or letting the +program run once to completion. + +21.1.4.2 DLL Name Prefixes +.......................... + +In keeping with the naming conventions used by the Microsoft debugging +tools, DLL export symbols are made available with a prefix based on the +DLL name, for instance 'KERNEL32!CreateFileA'. The plain name is also +entered into the symbol table, so 'CreateFileA' is often sufficient. In +some cases there will be name clashes within a program (particularly if +the executable itself includes full debugging symbols) necessitating the +use of the fully qualified name when referring to the contents of the +DLL. Use single-quotes around the name to avoid the exclamation mark +("!") being interpreted as a language operator. + + Note that the internal name of the DLL may be all upper-case, even +though the file name of the DLL is lower-case, or vice-versa. Since +symbols within GDB are _case-sensitive_ this may cause some confusion. +If in doubt, try the 'info functions' and 'info variables' commands or +even 'maint print msymbols' (*note Symbols::). Here's an example: + + (gdb) info function CreateFileA + All functions matching regular expression "CreateFileA": + + Non-debugging symbols: + 0x77e885f4 CreateFileA + 0x77e885f4 KERNEL32!CreateFileA + + (gdb) info function ! + All functions matching regular expression "!": + + Non-debugging symbols: + 0x6100114c cygwin1!__assert + 0x61004034 cygwin1!_dll_crt0@0 + 0x61004240 cygwin1!dll_crt0(per_process *) + [etc...] + +21.1.4.3 Working with Minimal Symbols +..................................... + +Symbols extracted from a DLL's export table do not contain very much +type information. All that GDB can do is guess whether a symbol refers +to a function or variable depending on the linker section that contains +the symbol. Also note that the actual contents of the memory contained +in a DLL are not available unless the program is running. This means +that you cannot examine the contents of a variable or disassemble a +function within a DLL without a running program. + + Variables are generally treated as pointers and dereferenced +automatically. For this reason, it is often necessary to prefix a +variable name with the address-of operator ("&") and provide explicit +type information in the command. Here's an example of the type of +problem: + + (gdb) print 'cygwin1!__argv' + 'cygwin1!__argv' has unknown type; cast it to its declared type + + (gdb) x 'cygwin1!__argv' + 'cygwin1!__argv' has unknown type; cast it to its declared type + + And two possible solutions: + + (gdb) print ((char **)'cygwin1!__argv')[0] + $2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" + + (gdb) x/2x &'cygwin1!__argv' + 0x610c0aa8 : 0x10021608 0x00000000 + (gdb) x/x 0x10021608 + 0x10021608: 0x0022fd98 + (gdb) x/s 0x0022fd98 + 0x22fd98: "/cygdrive/c/mydirectory/myprogram" + + Setting a break point within a DLL is possible even before the +program starts execution. However, under these circumstances, GDB can't +examine the initial instructions of the function in order to skip the +function's frame set-up code. You can work around this by using "*&" to +set the breakpoint at a raw memory address: + + (gdb) break *&'python22!PyOS_Readline' + Breakpoint 1 at 0x1e04eff0 + + The author of these extensions is not entirely convinced that setting +a break point within a shared DLL like 'kernel32.dll' is completely +safe. + + +File: gdb.info, Node: Hurd Native, Next: Darwin, Prev: Cygwin Native, Up: Native + +21.1.5 Commands Specific to GNU Hurd Systems +-------------------------------------------- + +This subsection describes GDB commands specific to the GNU Hurd native +debugging. + +'set signals' +'set sigs' + This command toggles the state of inferior signal interception by + GDB. Mach exceptions, such as breakpoint traps, are not affected + by this command. 'sigs' is a shorthand alias for 'signals'. + +'show signals' +'show sigs' + Show the current state of intercepting inferior's signals. + +'set signal-thread' +'set sigthread' + This command tells GDB which thread is the 'libc' signal thread. + That thread is run when a signal is delivered to a running process. + 'set sigthread' is the shorthand alias of 'set signal-thread'. + +'show signal-thread' +'show sigthread' + These two commands show which thread will run when the inferior is + delivered a signal. + +'set stopped' + This commands tells GDB that the inferior process is stopped, as + with the 'SIGSTOP' signal. The stopped process can be continued by + delivering a signal to it. + +'show stopped' + This command shows whether GDB thinks the debuggee is stopped. + +'set exceptions' + Use this command to turn off trapping of exceptions in the + inferior. When exception trapping is off, neither breakpoints nor + single-stepping will work. To restore the default, set exception + trapping on. + +'show exceptions' + Show the current state of trapping exceptions in the inferior. + +'set task pause' + This command toggles task suspension when GDB has control. Setting + it to on takes effect immediately, and the task is suspended + whenever GDB gets control. Setting it to off will take effect the + next time the inferior is continued. If this option is set to off, + you can use 'set thread default pause on' or 'set thread pause on' + (see below) to pause individual threads. + +'show task pause' + Show the current state of task suspension. + +'set task detach-suspend-count' + This command sets the suspend count the task will be left with when + GDB detaches from it. + +'show task detach-suspend-count' + Show the suspend count the task will be left with when detaching. + +'set task exception-port' +'set task excp' + This command sets the task exception port to which GDB will forward + exceptions. The argument should be the value of the "send rights" + of the task. 'set task excp' is a shorthand alias. + +'set noninvasive' + This command switches GDB to a mode that is the least invasive as + far as interfering with the inferior is concerned. This is the + same as using 'set task pause', 'set exceptions', and 'set signals' + to values opposite to the defaults. + +'info send-rights' +'info receive-rights' +'info port-rights' +'info port-sets' +'info dead-names' +'info ports' +'info psets' + These commands display information about, respectively, send + rights, receive rights, port rights, port sets, and dead names of a + task. There are also shorthand aliases: 'info ports' for 'info + port-rights' and 'info psets' for 'info port-sets'. + +'set thread pause' + This command toggles current thread suspension when GDB has + control. Setting it to on takes effect immediately, and the + current thread is suspended whenever GDB gets control. Setting it + to off will take effect the next time the inferior is continued. + Normally, this command has no effect, since when GDB has control, + the whole task is suspended. However, if you used 'set task pause + off' (see above), this command comes in handy to suspend only the + current thread. + +'show thread pause' + This command shows the state of current thread suspension. + +'set thread run' + This command sets whether the current thread is allowed to run. + +'show thread run' + Show whether the current thread is allowed to run. + +'set thread detach-suspend-count' + This command sets the suspend count GDB will leave on a thread when + detaching. This number is relative to the suspend count found by + GDB when it notices the thread; use 'set thread + takeover-suspend-count' to force it to an absolute value. + +'show thread detach-suspend-count' + Show the suspend count GDB will leave on the thread when detaching. + +'set thread exception-port' +'set thread excp' + Set the thread exception port to which to forward exceptions. This + overrides the port set by 'set task exception-port' (see above). + 'set thread excp' is the shorthand alias. + +'set thread takeover-suspend-count' + Normally, GDB's thread suspend counts are relative to the value GDB + finds when it notices each thread. This command changes the + suspend counts to be absolute instead. + +'set thread default' +'show thread default' + Each of the above 'set thread' commands has a 'set thread default' + counterpart (e.g., 'set thread default pause', 'set thread default + exception-port', etc.). The 'thread default' variety of commands + sets the default thread properties for all threads; you can then + change the properties of individual threads with the non-default + commands. + + +File: gdb.info, Node: Darwin, Next: FreeBSD, Prev: Hurd Native, Up: Native + +21.1.6 Darwin +------------- + +GDB provides the following commands specific to the Darwin target: + +'set debug darwin NUM' + When set to a non zero value, enables debugging messages specific + to the Darwin support. Higher values produce more verbose output. + +'show debug darwin' + Show the current state of Darwin messages. + +'set debug mach-o NUM' + When set to a non zero value, enables debugging messages while GDB + is reading Darwin object files. ("Mach-O" is the file format used + on Darwin for object and executable files.) Higher values produce + more verbose output. This is a command to diagnose problems + internal to GDB and should not be needed in normal usage. + +'show debug mach-o' + Show the current state of Mach-O file messages. + +'set mach-exceptions on' +'set mach-exceptions off' + On Darwin, faults are first reported as a Mach exception and are + then mapped to a Posix signal. Use this command to turn on + trapping of Mach exceptions in the inferior. This might be + sometimes useful to better understand the cause of a fault. The + default is off. + +'show mach-exceptions' + Show the current state of exceptions trapping. + + +File: gdb.info, Node: FreeBSD, Prev: Darwin, Up: Native + +21.1.7 FreeBSD +-------------- + +When the ABI of a system call is changed in the FreeBSD kernel, this is +implemented by leaving a compatibility system call using the old ABI at +the existing number and allocating a new system call number for the +version using the new ABI. As a convenience, when a system call is +caught by name (*note catch syscall::), compatibility system calls are +also caught. + + For example, FreeBSD 12 introduced a new variant of the 'kevent' +system call and catching the 'kevent' system call by name catches both +variants: + + (gdb) catch syscall kevent + Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560]) + (gdb) + + +File: gdb.info, Node: Embedded OS, Next: Embedded Processors, Prev: Native, Up: Configurations + +21.2 Embedded Operating Systems +=============================== + +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. + + GDB includes the ability to debug programs running on various +real-time operating systems. + + +File: gdb.info, Node: Embedded Processors, Next: Architectures, Prev: Embedded OS, Up: Configurations + +21.3 Embedded Processors +======================== + +This section goes into details specific to particular embedded +configurations. + + Whenever a specific embedded processor has a simulator, GDB allows to +send an arbitrary command to the simulator. + +'sim COMMAND' + Send an arbitrary COMMAND string to the simulator. Consult the + documentation for the specific simulator in use for information + about acceptable commands. + +* Menu: + +* ARC:: Synopsys ARC +* ARM:: ARM +* BPF:: eBPF +* M68K:: Motorola M68K +* MicroBlaze:: Xilinx MicroBlaze +* MIPS Embedded:: MIPS Embedded +* OpenRISC 1000:: OpenRISC 1000 (or1k) +* PowerPC Embedded:: PowerPC Embedded +* AVR:: Atmel AVR +* CRIS:: CRIS +* Super-H:: Renesas Super-H + + +File: gdb.info, Node: ARC, Next: ARM, Up: Embedded Processors + +21.3.1 Synopsys ARC +------------------- + +GDB provides the following ARC-specific commands: + +'set debug arc' + Control the level of ARC specific debug messages. Use 0 for no + messages (the default), 1 for debug messages, and 2 for even more + debug messages. + +'show debug arc' + Show the level of ARC specific debugging in operation. + +'maint print arc arc-instruction ADDRESS' + Print internal disassembler information about instruction at a + given address. + + +File: gdb.info, Node: ARM, Next: BPF, Prev: ARC, Up: Embedded Processors + +21.3.2 ARM +---------- + +GDB provides the following ARM-specific commands: + +'set arm disassembler' + This commands selects from a list of disassembly styles. The + '"std"' style is the standard style. + +'show arm disassembler' + Show the current disassembly style. + +'set arm apcs32' + This command toggles ARM operation mode between 32-bit and 26-bit. + +'show arm apcs32' + Display the current usage of the ARM 32-bit mode. + +'set arm fpu FPUTYPE' + This command sets the ARM floating-point unit (FPU) type. The + argument FPUTYPE can be one of these: + + 'auto' + Determine the FPU type by querying the OS ABI. + 'softfpa' + Software FPU, with mixed-endian doubles on little-endian ARM + processors. + 'fpa' + GCC-compiled FPA co-processor. + 'softvfp' + Software FPU with pure-endian doubles. + 'vfp' + VFP co-processor. + +'show arm fpu' + Show the current type of the FPU. + +'set arm abi' + This command forces GDB to use the specified ABI. + +'show arm abi' + Show the currently used ABI. + +'set arm fallback-mode (arm|thumb|auto)' + GDB uses the symbol table, when available, to determine whether + instructions are ARM or Thumb. This command controls GDB's default + behavior when the symbol table is not available. The default is + 'auto', which causes GDB to use the current execution mode (from + the 'T' bit in the 'CPSR' register). + +'show arm fallback-mode' + Show the current fallback instruction mode. + +'set arm force-mode (arm|thumb|auto)' + This command overrides use of the symbol table to determine whether + instructions are ARM or Thumb. The default is 'auto', which causes + GDB to use the symbol table and then the setting of 'set arm + fallback-mode'. + +'show arm force-mode' + Show the current forced instruction mode. + +'set arm unwind-secure-frames' + This command enables unwinding from Non-secure to Secure mode on + Cortex-M with Security extension. This can trigger security + exceptions when unwinding the exception stack. It is enabled by + default. + +'show arm unwind-secure-frames' + Show whether unwinding from Non-secure to Secure mode is enabled. + +'set debug arm' + Toggle whether to display ARM-specific debugging messages from the + ARM target support subsystem. + +'show debug arm' + Show whether ARM-specific debugging messages are enabled. + +'target sim [SIMARGS] ...' + The GDB ARM simulator accepts the following optional arguments. + + '--swi-support=TYPE' + Tell the simulator which SWI interfaces to support. The + argument TYPE may be a comma separated list of the following + values. The default value is 'all'. + + 'none' + 'demon' + 'angel' + 'redboot' + 'all' + + +File: gdb.info, Node: BPF, Next: M68K, Prev: ARM, Up: Embedded Processors + +21.3.3 BPF +---------- + +'target sim [SIMARGS] ...' + The GDB BPF simulator accepts the following optional arguments. + + '--skb-data-offset=OFFSET' + Tell the simulator the offset, measured in bytes, of the + 'skb_data' field in the kernel 'struct sk_buff' structure. + This offset is used by some BPF specific-purpose load/store + instructions. Defaults to 0. + + +File: gdb.info, Node: M68K, Next: MicroBlaze, Prev: BPF, Up: Embedded Processors + +21.3.4 M68k +----------- + +The Motorola m68k configuration includes ColdFire support. + + +File: gdb.info, Node: MicroBlaze, Next: MIPS Embedded, Prev: M68K, Up: Embedded Processors + +21.3.5 MicroBlaze +----------------- + +The MicroBlaze is a soft-core processor supported on various Xilinx +FPGAs, such as Spartan or Virtex series. Boards with these processors +usually have JTAG ports which connect to a host system running the +Xilinx Embedded Development Kit (EDK) or Software Development Kit (SDK). +This host system is used to download the configuration bitstream to the +target FPGA. The Xilinx Microprocessor Debugger (XMD) program +communicates with the target board using the JTAG interface and presents +a 'gdbserver' interface to the board. By default 'xmd' uses port +'1234'. (While it is possible to change this default port, it requires +the use of undocumented 'xmd' commands. Contact Xilinx support if you +need to do this.) + + Use these GDB commands to connect to the MicroBlaze target processor. + +'target remote :1234' + Use this command to connect to the target if you are running GDB on + the same system as 'xmd'. + +'target remote XMD-HOST:1234' + Use this command to connect to the target if it is connected to + 'xmd' running on a different system named XMD-HOST. + +'load' + Use this command to download a program to the MicroBlaze target. + +'set debug microblaze N' + Enable MicroBlaze-specific debugging messages if non-zero. + +'show debug microblaze N' + Show MicroBlaze-specific debugging level. + + +File: gdb.info, Node: MIPS Embedded, Next: OpenRISC 1000, Prev: MicroBlaze, Up: Embedded Processors + +21.3.6 MIPS Embedded +-------------------- + +GDB supports these special commands for MIPS targets: + +'set mipsfpu double' +'set mipsfpu single' +'set mipsfpu none' +'set mipsfpu auto' +'show mipsfpu' + If your target board does not support the MIPS floating point + coprocessor, you should use the command 'set mipsfpu none' (if you + need this, you may wish to put the command in your GDB init file). + This tells GDB how to find the return value of functions which + return floating point values. It also allows GDB to avoid saving + the floating point registers when calling functions on the board. + If you are using a floating point coprocessor with only single + precision floating point support, as on the R4650 processor, use + the command 'set mipsfpu single'. The default double precision + floating point coprocessor may be selected using 'set mipsfpu + double'. + + In previous versions the only choices were double precision or no + floating point, so 'set mipsfpu on' will select double precision + and 'set mipsfpu off' will select no floating point. + + As usual, you can inquire about the 'mipsfpu' variable with 'show + mipsfpu'. + + +File: gdb.info, Node: OpenRISC 1000, Next: PowerPC Embedded, Prev: MIPS Embedded, Up: Embedded Processors + +21.3.7 OpenRISC 1000 +-------------------- + +The OpenRISC 1000 provides a free RISC instruction set architecture. It +is mainly provided as a soft-core which can run on Xilinx, Altera and +other FPGA's. + + GDB for OpenRISC supports the below commands when connecting to a +target: + +'target sim' + + Runs the builtin CPU simulator which can run very basic programs + but does not support most hardware functions like MMU. For more + complex use cases the user is advised to run an external target, + and connect using 'target remote'. + + Example: 'target sim' + +'set debug or1k' + Toggle whether to display OpenRISC-specific debugging messages from + the OpenRISC target support subsystem. + +'show debug or1k' + Show whether OpenRISC-specific debugging messages are enabled. + + +File: gdb.info, Node: PowerPC Embedded, Next: AVR, Prev: OpenRISC 1000, Up: Embedded Processors + +21.3.8 PowerPC Embedded +----------------------- + +GDB supports using the DVC (Data Value Compare) register to implement in +hardware simple hardware watchpoint conditions of the form: + + (gdb) watch ADDRESS|VARIABLE \ + if ADDRESS|VARIABLE == CONSTANT EXPRESSION + + The DVC register will be automatically used when GDB detects such +pattern in a condition expression, and the created watchpoint uses one +debug register (either the 'exact-watchpoints' option is on and the +variable is scalar, or the variable has a length of one byte). This +feature is available in native GDB running on a Linux kernel version +2.6.34 or newer. + + When running on PowerPC embedded processors, GDB automatically uses +ranged hardware watchpoints, unless the 'exact-watchpoints' option is +on, in which case watchpoints using only one debug register are created +when watching variables of scalar types. + + You can create an artificial array to watch an arbitrary memory +region using one of the following commands (*note Expressions::): + + (gdb) watch *((char *) ADDRESS)@LENGTH + (gdb) watch {char[LENGTH]} ADDRESS + + PowerPC embedded processors support masked watchpoints. See the +discussion about the 'mask' argument in *note Set Watchpoints::. + + PowerPC embedded processors support hardware accelerated "ranged +breakpoints". A ranged breakpoint stops execution of the inferior +whenever it executes an instruction at any address within the range it +was set at. To set a ranged breakpoint in GDB, use the 'break-range' +command. + + GDB provides the following PowerPC-specific commands: + +'break-range START-LOCSPEC, END-LOCSPEC' + Set a breakpoint for an address range given by START-LOCSPEC and + END-LOCSPEC, which are location specs. *Note Location + Specifications::, for a list of all the possible forms of location + specs. GDB resolves both START-LOCSPEC and END-LOCSPEC, and uses + the addresses of the resolved code locations as start and end + addresses of the range to break at. The breakpoint will stop + execution of the inferior whenever it executes an instruction at + any address between the start and end addresses, inclusive. If + either START-LOCSPEC or END-LOCSPEC resolve to multiple code + locations in the program, then the command aborts with an error + without creating a breakpoint. + +'set powerpc soft-float' +'show powerpc soft-float' + Force GDB to use (or not use) a software floating point calling + convention. By default, GDB selects the calling convention based + on the selected architecture and the provided executable file. + +'set powerpc vector-abi' +'show powerpc vector-abi' + Force GDB to use the specified calling convention for vector + arguments and return values. The valid options are 'auto'; + 'generic', to avoid vector registers even if they are present; + 'altivec', to use AltiVec registers; and 'spe' to use SPE + registers. By default, GDB selects the calling convention based on + the selected architecture and the provided executable file. + +'set powerpc exact-watchpoints' +'show powerpc exact-watchpoints' + Allow GDB to use only one debug register when watching a variable + of scalar type, thus assuming that the variable is accessed through + the address of its first byte. + + +File: gdb.info, Node: AVR, Next: CRIS, Prev: PowerPC Embedded, Up: Embedded Processors + +21.3.9 Atmel AVR +---------------- + +When configured for debugging the Atmel AVR, GDB supports the following +AVR-specific commands: + +'info io_registers' + This command displays information about the AVR I/O registers. For + each register, GDB prints its number and value. + + +File: gdb.info, Node: CRIS, Next: Super-H, Prev: AVR, Up: Embedded Processors + +21.3.10 CRIS +------------ + +When configured for debugging CRIS, GDB provides the following +CRIS-specific commands: + +'set cris-version VER' + Set the current CRIS version to VER, either '10' or '32'. The CRIS + version affects register names and sizes. This command is useful + in case autodetection of the CRIS version fails. + +'show cris-version' + Show the current CRIS version. + +'set cris-dwarf2-cfi' + Set the usage of DWARF-2 CFI for CRIS debugging. The default is + 'on'. Change to 'off' when using 'gcc-cris' whose version is below + 'R59'. + +'show cris-dwarf2-cfi' + Show the current state of using DWARF-2 CFI. + +'set cris-mode MODE' + Set the current CRIS mode to MODE. It should only be changed when + debugging in guru mode, in which case it should be set to 'guru' + (the default is 'normal'). + +'show cris-mode' + Show the current CRIS mode. + + +File: gdb.info, Node: Super-H, Prev: CRIS, Up: Embedded Processors + +21.3.11 Renesas Super-H +----------------------- + +For the Renesas Super-H processor, GDB provides these commands: + +'set sh calling-convention CONVENTION' + Set the calling-convention used when calling functions from GDB. + Allowed values are 'gcc', which is the default setting, and + 'renesas'. With the 'gcc' setting, functions are called using the + GCC calling convention. If the DWARF-2 information of the called + function specifies that the function follows the Renesas calling + convention, the function is called using the Renesas calling + convention. If the calling convention is set to 'renesas', the + Renesas calling convention is always used, regardless of the + DWARF-2 information. This can be used to override the default of + 'gcc' if debug information is missing, or the compiler does not + emit the DWARF-2 calling convention entry for a function. + +'show sh calling-convention' + Show the current calling convention setting. + + +File: gdb.info, Node: Architectures, Prev: Embedded Processors, Up: Configurations + +21.4 Architectures +================== + +This section describes characteristics of architectures that affect all +uses of GDB with the architecture, both native and cross. + +* Menu: + +* AArch64:: +* x86:: +* Alpha:: +* MIPS:: +* HPPA:: HP PA architecture +* PowerPC:: +* Sparc64:: +* S12Z:: +* AMD GPU:: AMD GPU architectures + + +File: gdb.info, Node: AArch64, Next: x86, Up: Architectures + +21.4.1 AArch64 +-------------- + +When GDB is debugging the AArch64 architecture, it provides the +following special commands: + +'set debug aarch64' + This command determines whether AArch64 architecture-specific + debugging messages are to be displayed. + +'show debug aarch64' + Show whether AArch64 debugging messages are displayed. + +21.4.1.1 AArch64 SVE. +..................... + +When GDB is debugging the AArch64 architecture, if the Scalable Vector +Extension (SVE) is present, then GDB will provide the vector registers +'$z0' through '$z31', vector predicate registers '$p0' through '$p15', +and the '$ffr' register. In addition, the pseudo register '$vg' will be +provided. This is the vector granule for the current thread and +represents the number of 64-bit chunks in an SVE 'z' register. + + If the vector length changes, then the '$vg' register will be +updated, but the lengths of the 'z' and 'p' registers will not change. +This is a known limitation of GDB and does not affect the execution of +the target process. + + For SVE, the following definitions are used throughout GDB's source +code and in this document: + + * VL: The vector length, in bytes. It defines the size of each 'Z' + register. + + * VQ: The number of 128 bit units in VL. This is mostly used + internally by GDB and the Linux Kernel. + + * VG: The number of 64 bit units in VL. This is mostly used + internally by GDB and the Linux Kernel. + +21.4.1.2 AArch64 SME. +..................... + +The Scalable Matrix Extension (SME +(https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture)) +is an AArch64 architecture extension that expands on the concept of the +Scalable Vector Extension (SVE +(https://developer.arm.com/documentation/101726/4-0/Learn-about-the-Scalable-Vector-Extension--SVE-/What-is-the-Scalable-Vector-Extension-)) +by providing a 2-dimensional register 'ZA', which is a square matrix of +variable size, just like SVE provides a group of vector registers of +variable size. + + Similarly to SVE, where the size of each 'Z' register is directly +related to the vector length (VL for short), the SME 'ZA' matrix +register's size is directly related to the streaming vector length (SVL +for short). *Note vl::. *Note svl::. + + The 'ZA' register state can be either active or inactive, if it is +not in use. + + SME also introduces a new execution mode called streaming SVE mode +(streaming mode for short). When streaming mode is enabled, the program +supports execution of SVE2 instructions and the SVE registers will have +vector length SVL. When streaming mode is disabled, the SVE registers +have vector length VL. + + For more information about SME and SVE, please refer to official +architecture documentation +(https://developer.arm.com/documentation/ddi0487/latest). + + The following definitions are used throughout GDB's source code and +in this document: + + * SVL: The streaming vector length, in bytes. It defines the size of + each dimension of the 2-dimensional square 'ZA' matrix. The total + size of 'ZA' is therefore SVL by SVL. + + When streaming mode is enabled, it defines the size of the SVE + registers as well. + + * SVQ: The number of 128 bit units in SVL, also known as streaming + vector granule. This is mostly used internally by GDB and the + Linux Kernel. + + * SVG: The number of 64 bit units in SVL. This is mostly used + internally by GDB and the Linux Kernel. + + When GDB is debugging the AArch64 architecture, if the Scalable +Matrix Extension (SME) is present, then GDB will make the 'ZA' register +available. GDB will also make the 'SVG' register and 'SVCR' +pseudo-register available. + + The 'ZA' register is a 2-dimensional square SVL by SVL matrix of +bytes. To simplify the representation and access to the 'ZA' register +in GDB, it is defined as a vector of SVLxSVL bytes. + + If the user wants to index the 'ZA' register as a matrix, it is +possible to reference 'ZA' as 'ZA[I][J]', where I is the row number and +J is the column number. + + The 'SVG' register always contains the streaming vector granule (SVG) +for the current thread. From the value of register 'SVG' we can easily +derive the SVL value. + + The 'SVCR' pseudo-register (streaming vector control register) is a +status register that holds two state bits: SM in bit 0 and ZA in bit 1. + + If the SM bit is 1, it means the current thread is in streaming mode, +and the SVE registers will use SVL for their sizes. If the SM bit is 0, +the current thread is not in streaming mode, and the SVE registers will +use VL for their sizes. *Note vl::. + + If the ZA bit is 1, it means the 'ZA' register is being used and has +meaningful contents. If the ZA bit is 0, the 'ZA' register is +unavailable and its contents are undefined. + + For convenience and simplicity, if the ZA bit is 0, the 'ZA' register +and all of its pseudo-registers will read as zero. + + If SVL changes during the execution of a program, then the 'ZA' +register size and the bits in the 'SVCR' pseudo-register will be updated +to reflect it. + + It is possible for users to change SVL during the execution of a +program by modifying the 'SVG' register value. + + Whenever the 'SVG' register is modified with a new value, the +following will be observed: + + * The ZA and SM bits will be cleared in the 'SVCR' pseudo-register. + + * The 'ZA' register will have a new size and its state will be + cleared, forcing its contents and the contents of all of its + pseudo-registers back to zero. + + * If the SM bit was 1, the SVE registers will be reset to having + their sizes based on VL as opposed to SVL. If the SM bit was 0 + prior to modifying the 'SVG' register, there will be no observable + effect on the SVE registers. + + The possible values for the 'SVG' register are 2, 4, 8, 16, 32. +These numbers correspond to streaming vector length (SVL) values of 16 +bytes, 32 bytes, 64 bytes, 128 bytes and 256 bytes respectively. + + The minimum size of the 'ZA' register is 16 x 16 (256) bytes, and the +maximum size is 256 x 256 (65536) bytes. In streaming mode, with bit SM +set, the size of the 'ZA' register is the size of all the SVE 'Z' +registers combined. + + The 'ZA' register can also be accessed using tiles and tile slices. + + Tile pseudo-registers are square, 2-dimensional sub-arrays of +elements within the 'ZA' register. + + The tile pseudo-registers have the following naming pattern: 'ZA'. + + There is a total of 31 'ZA' tile pseudo-registers. They are 'ZA0B', +'ZA0H' through 'ZA1H', 'ZA0S' through 'ZA3S', 'ZA0D' through 'ZA7D' and +'ZA0Q' through 'ZA15Q'. + + Tile slice pseudo-registers are vectors of horizontally or vertically +contiguous elements within the 'ZA' register. + + The tile slice pseudo-registers have the following naming pattern: +'ZA '. + + There are up to 16 tiles (0 ~ 15), the direction can be either 'v' +(vertical) or 'h' (horizontal), the qualifiers can be 'b' (byte), 'h' +(halfword), 's' (word), 'd' (doubleword) and 'q' (quadword) and there +are up to 256 slices (0 ~ 255) depending on the value of SVL. The +number of slices is the same as the value of SVL. + + The number of available tile slice pseudo-registers can be large. +For a minimum SVL of 16 bytes, there are 5 (number of qualifiers) x 2 +(number of directions) x 16 (SVL) pseudo-registers. For the maximum SVL +of 256 bytes, there are 5 x 2 x 256 pseudo-registers. + + When listing all the available registers, users will see the +currently-available 'ZA' pseudo-registers. Pseudo-registers that don't +exist for a given SVL value will not be displayed. + + For more information on SME and its terminology, please refer to the +Arm Architecture Reference Manual Supplement +(https://developer.arm.com/documentation/ddi0616/aa/), The Scalable +Matrix Extension (SME), for Armv9-A. + + Some features are still under development and rely on ACLE +(https://github.com/ARM-software/acle/releases/latest) and ABI +(https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst) +definitions, so there are known limitations to the current SME support +in GDB. + + One such example is calling functions in the program being debugged +by GDB. Such calls are not SME-aware and thus don't take into account +the 'SVCR' pseudo-register bits nor the 'ZA' register contents. *Note +Calling::. + + The lazy saving scheme +(https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst#the-za-lazy-saving-scheme) +involving the 'TPIDR2' register is not yet supported by GDB, though the +'TPIDR2' register is known and supported by GDB. + + Lastly, an important limitation for 'gdbserver' is its inability to +communicate SVL changes to GDB. This means 'gdbserver', even though it +is capable of adjusting its internal caches to reflect a change in the +value of SVL mid-execution, will operate with a potentially different +SVL value compared to GDB. This can lead to GDB showing incorrect +values for the 'ZA' register and incorrect values for SVE registers +(when in streaming mode). + + This is the same limitation we have for the SVE registers, and there +are plans to address this limitation going forward. + +21.4.1.3 AArch64 SME2. +...................... + +The Scalable Matrix Extension 2 is an AArch64 architecture extension +that further expands the SME extension with the following: + + * The ability to address the 'ZA' array through groups of + one-dimensional 'ZA' array vectors, as opposed to 'ZA' tiles with 2 + dimensions. + + * Instructions to operate on groups of SVE 'Z' registers and 'ZA' + array vectors. + + * A new 512 bit 'ZT0' lookup table register, for data decompression. + + When GDB is debugging the AArch64 architecture, if the Scalable +Matrix Extension 2 (SME2) is present, then GDB will make the 'ZT0' +register available. + + The 'ZT0' register is only considered active when the 'ZA' register +state is active, therefore when the ZA bit of the 'SVCR' is 1. + + When the ZA bit of 'SVCR' is 0, that means the 'ZA' register state is +not active, which means the 'ZT0' register state is also not active. + + When 'ZT0' is not active, it is comprised of zeroes, just like 'ZA'. + + Similarly to the 'ZA' register, if the 'ZT0' state is not active and +the user attempts to modify its value such that any of its bytes is +non-zero, then GDB will initialize the 'ZA' register state as well, +which means the 'SVCR' ZA bit gets set to 1. + + For more information about SME2, please refer to the official +architecture documentation +(https://developer.arm.com/documentation/ddi0487/latest). + +21.4.1.4 AArch64 Pointer Authentication. +........................................ + +When GDB is debugging the AArch64 architecture, and the program is using +the v8.3-A feature Pointer Authentication (PAC), then whenever the link +register '$lr' is pointing to an PAC function its value will be masked. +When GDB prints a backtrace, any addresses that required unmasking will +be postfixed with the marker [PAC]. When using the MI, this is printed +as part of the 'addr_flags' field. + +21.4.1.5 AArch64 Memory Tagging Extension. +.......................................... + +When GDB is debugging the AArch64 architecture, the program is using the +v8.5-A feature Memory Tagging Extension (MTE) and there is support in +the kernel for MTE, GDB will make memory tagging functionality available +for inspection and editing of logical and allocation tags. *Note Memory +Tagging::. + + To aid debugging, GDB will output additional information when SIGSEGV +signals are generated as a result of memory tag failures. + + If the tag violation is synchronous, the following will be shown: + + Program received signal SIGSEGV, Segmentation fault + Memory tag violation while accessing address 0x0500fffff7ff8000 + Allocation tag 0x1 + Logical tag 0x5. + + If the tag violation is asynchronous, the fault address is not +available. In this case GDB will show the following: + + Program received signal SIGSEGV, Segmentation fault + Memory tag violation + Fault address unavailable. + + A special register, 'tag_ctl', is made available through the +'org.gnu.gdb.aarch64.mte' feature. This register exposes some options +that can be controlled at runtime and emulates the 'prctl' option +'PR_SET_TAGGED_ADDR_CTRL'. For further information, see the +documentation in the Linux kernel. + + GDB supports dumping memory tag data to core files through the +'gcore' command and reading memory tag data from core files generated by +the 'gcore' command or the Linux kernel. + + When a process uses memory-mapped pages protected by memory tags (for +example, AArch64 MTE), this additional information will be recorded in +the core file in the event of a crash or if GDB generates a core file +from the current process state. + + The memory tag data will be used so developers can display the memory +tags from a particular memory region (using the 'm' modifier to the 'x' +command, using the 'print' command or using the various 'memory-tag' +subcommands. + + In the case of a crash, GDB will attempt to retrieve the memory tag +information automatically from the core file, and will show one of the +above messages depending on whether the synchronous or asynchronous mode +is selected. *Note Memory Tagging::. *Note Memory::. + + +File: gdb.info, Node: x86, Next: Alpha, Prev: AArch64, Up: Architectures + +21.4.2 x86 +---------- + +'set struct-convention MODE' + Set the convention used by the inferior to return 'struct's and + 'union's from functions to MODE. Possible values of MODE are + '"pcc"', '"reg"', and '"default"' (the default). '"default"' or + '"pcc"' means that 'struct's are returned on the stack, while + '"reg"' means that a 'struct' or a 'union' whose size is 1, 2, 4, + or 8 bytes will be returned in a register. + +'show struct-convention' + Show the current setting of the convention to return 'struct's from + functions. + +21.4.2.1 x87 registers +...................... + +GDB provides access to the x87 state through the following registers: + + * '$st0' to 'st7': 'ST(0)' to 'ST(7)' floating-point registers + * '$fctrl': control word register ('FCW') + * '$fstat': status word register ('FSW') + * '$ftag': tag word ('FTW') + * '$fiseg': last instruction pointer segment + * '$fioff': last instruction pointer + * '$foseg': last data pointer segment + * '$fooff': last data pointer + * '$fop': last opcode + + +File: gdb.info, Node: Alpha, Next: MIPS, Prev: x86, Up: Architectures + +21.4.3 Alpha +------------ + +See the following section. + + +File: gdb.info, Node: MIPS, Next: HPPA, Prev: Alpha, Up: Architectures + +21.4.4 MIPS +----------- + +Alpha- and MIPS-based computers use an unusual stack frame, which +sometimes requires GDB to search backward in the object code to find the +beginning of a function. + + To improve response time (especially for embedded applications, where +GDB may be restricted to a slow serial line for this search) you may +want to limit the size of this search, using one of these commands: + +'set heuristic-fence-post LIMIT' + Restrict GDB to examining at most LIMIT bytes in its search for the + beginning of a function. A value of 0 (the default) means there is + no limit. However, except for 0, the larger the limit the more + bytes 'heuristic-fence-post' must search and therefore the longer + it takes to run. You should only need to use this command when + debugging a stripped executable. + +'show heuristic-fence-post' + Display the current limit. + +These commands are available _only_ when GDB is configured for debugging +programs on Alpha or MIPS processors. + + Several MIPS-specific commands are available when debugging MIPS +programs: + +'set mips abi ARG' + Tell GDB which MIPS ABI is used by the inferior. Possible values + of ARG are: + + 'auto' + The default ABI associated with the current binary (this is + the default). + 'o32' + 'o64' + 'n32' + 'n64' + 'eabi32' + 'eabi64' + +'show mips abi' + Show the MIPS ABI used by GDB to debug the inferior. + +'set mips compression ARG' + Tell GDB which MIPS compressed ISA (Instruction Set Architecture) + encoding is used by the inferior. GDB uses this for code + disassembly and other internal interpretation purposes. This + setting is only referred to when no executable has been associated + with the debugging session or the executable does not provide + information about the encoding it uses. Otherwise this setting is + automatically updated from information provided by the executable. + + Possible values of ARG are 'mips16' and 'micromips'. The default + compressed ISA encoding is 'mips16', as executables containing + MIPS16 code frequently are not identified as such. + + This setting is "sticky"; that is, it retains its value across + debugging sessions until reset either explicitly with this command + or implicitly from an executable. + + The compiler and/or assembler typically add symbol table + annotations to identify functions compiled for the MIPS16 or + microMIPS ISAs. If these function-scope annotations are present, + GDB uses them in preference to the global compressed ISA encoding + setting. + +'show mips compression' + Show the MIPS compressed ISA encoding used by GDB to debug the + inferior. + +'set mipsfpu' +'show mipsfpu' + *Note set mipsfpu: MIPS Embedded. + +'set mips mask-address ARG' + This command determines whether the most-significant 32 bits of + 64-bit MIPS addresses are masked off. The argument ARG can be + 'on', 'off', or 'auto'. The latter is the default setting, which + lets GDB determine the correct value. + +'show mips mask-address' + Show whether the upper 32 bits of MIPS addresses are masked off or + not. + +'set remote-mips64-transfers-32bit-regs' + This command controls compatibility with 64-bit MIPS targets that + transfer data in 32-bit quantities. If you have an old MIPS 64 + target that transfers 32 bits for some registers, like SR and FSR, + and 64 bits for other registers, set this option to 'on'. + +'show remote-mips64-transfers-32bit-regs' + Show the current setting of compatibility with older MIPS 64 + targets. + +'set debug mips' + This command turns on and off debugging messages for the + MIPS-specific target code in GDB. + +'show debug mips' + Show the current setting of MIPS debugging messages. + + +File: gdb.info, Node: HPPA, Next: PowerPC, Prev: MIPS, Up: Architectures + +21.4.5 HPPA +----------- + +When GDB is debugging the HP PA architecture, it provides the following +special commands: + +'set debug hppa' + This command determines whether HPPA architecture-specific + debugging messages are to be displayed. + +'show debug hppa' + Show whether HPPA debugging messages are displayed. + +'maint print unwind ADDRESS' + This command displays the contents of the unwind table entry at the + given ADDRESS. + + +File: gdb.info, Node: PowerPC, Next: Sparc64, Prev: HPPA, Up: Architectures + +21.4.6 PowerPC +-------------- + +When GDB is debugging the PowerPC architecture, it provides a set of +pseudo-registers to enable inspection of 128-bit wide Decimal Floating +Point numbers stored in the floating point registers. These values must +be stored in two consecutive registers, always starting at an even +register like 'f0' or 'f2'. + + The pseudo-registers go from '$dl0' through '$dl15', and are formed +by joining the even/odd register pairs 'f0' and 'f1' for '$dl0', 'f2' +and 'f3' for '$dl1' and so on. + + For POWER7 processors, GDB provides a set of pseudo-registers, the +64-bit wide Extended Floating Point Registers ('f32' through 'f63'). + + +File: gdb.info, Node: Sparc64, Next: S12Z, Prev: PowerPC, Up: Architectures + +21.4.7 Sparc64 +-------------- + +21.4.7.1 ADI Support +.................... + +The M7 processor supports an Application Data Integrity (ADI) feature +that detects invalid data accesses. When software allocates memory and +enables ADI on the allocated memory, it chooses a 4-bit version number, +sets the version in the upper 4 bits of the 64-bit pointer to that data, +and stores the 4-bit version in every cacheline of that data. Hardware +saves the latter in spare bits in the cache and memory hierarchy. On +each load and store, the processor compares the upper 4 VA (virtual +address) bits to the cacheline's version. If there is a mismatch, the +processor generates a version mismatch trap which can be either precise +or disrupting. The trap is an error condition which the kernel delivers +to the process as a SIGSEGV signal. + + Note that only 64-bit applications can use ADI and need to be built +with ADI-enabled. + + Values of the ADI version tags, which are in granularity of a +cacheline (64 bytes), can be viewed or modified. + +'adi (examine | x) [ / N ] ADDR' + + The 'adi examine' command displays the value of one ADI version tag + per cacheline. + + N is a decimal integer specifying the number in bytes; the default + is 1. It specifies how much ADI version information, at the ratio + of 1:ADI block size, to display. + + ADDR is the address in user address space where you want GDB to + begin displaying the ADI version tags. + + Below is an example of displaying ADI versions of variable + "shmaddr". + + (gdb) adi x/100 shmaddr + 0xfff800010002c000: 0 0 + +'adi (assign | a) [ / N ] ADDR = TAG' + + The 'adi assign' command is used to assign new ADI version tag to + an address. + + N is a decimal integer specifying the number in bytes; the default + is 1. It specifies how much ADI version information, at the ratio + of 1:ADI block size, to modify. + + ADDR is the address in user address space where you want GDB to + begin modifying the ADI version tags. + + TAG is the new ADI version tag. + + For example, do the following to modify then verify ADI versions of + variable "shmaddr": + + (gdb) adi a/100 shmaddr = 7 + (gdb) adi x/100 shmaddr + 0xfff800010002c000: 7 7 + + +File: gdb.info, Node: S12Z, Next: AMD GPU, Prev: Sparc64, Up: Architectures + +21.4.8 S12Z +----------- + +When GDB is debugging the S12Z architecture, it provides the following +special command: + +'maint info bdccsr' + This command displays the current value of the microprocessor's + BDCCSR register. + + +File: gdb.info, Node: AMD GPU, Prev: S12Z, Up: Architectures + +21.4.9 AMD GPU +-------------- + +GDB supports debugging programs offloaded to AMD GPU devices using the +AMD ROCm (https://docs.amd.com/) platform. GDB presents host threads +alongside GPU wavefronts, allowing debugging both the host and device +parts of the program simultaneously. + +21.4.9.1 AMD GPU Architectures +.............................. + +The list of AMD GPU architectures supported by GDB depends on the +version of the AMD Debugger API library used. See its documentation +(https://docs.amd.com/bundle/ROCDebugger_User_and_API) for more details. + +21.4.9.2 AMD GPU Device Driver and AMD ROCm Runtime +................................................... + +GDB requires a compatible AMD GPU device driver to be installed. A +warning message is displayed if either the device driver version or the +version of the debug support it implements is unsupported. GDB will +continue to function except no AMD GPU debugging will be possible. + + GDB requires each agent to have compatible firmware installed by the +device driver. A warning message is displayed if unsupported firmware +is detected. GDB will continue to function except no AMD GPU debugging +will be possible on the agent. + + GDB requires a compatible AMD ROCm runtime to be loaded in order to +detect AMD GPU code objects and wavefronts. A warning message is +displayed if an unsupported AMD ROCm runtime is detected, or there is an +error or restriction that prevents debugging. GDB will continue to +function except no AMD GPU debugging will be possible. + +21.4.9.3 AMD GPU Wavefronts +........................... + +An AMD GPU wavefront is represented in GDB as a thread. + + Note that some AMD GPU architectures may have restrictions on +providing information about AMD GPU wavefronts created when GDB is not +attached (*note AMD GPU Attaching Restrictions: AMD GPU Attaching +Restrictions.). + + When scheduler-locking is in effect (*note set scheduler-locking::), +new wavefronts created by the resumed thread (either CPU thread or GPU +wavefront) are held in the halt state. + +21.4.9.4 AMD GPU Code Objects +............................. + +The 'info sharedlibrary' command will show the AMD GPU code objects as +file or memory URIs, together with the host's shared libraries. For +example: + + (gdb) info sharedlibrary + From To Syms Read Shared Object Library + 0x1111 0x2222 Yes (*) /lib64/ld-linux-x86-64.so.2 + ... + 0x3333 0x4444 Yes (*) /opt/rocm-4.5.0/.../libamd_comgr.so + 0x5555 0x6666 Yes (*) /lib/x86_64-linux-gnu/libtinfo.so.5 + 0x7777 0x8888 Yes file:///tmp/a.out#offset=6477&size=10832 + 0x9999 0xaaaa Yes (*) memory://95557/mem#offset=0x1234&size=100 + (*): Shared library is missing debugging information. + (gdb) + + For a 'file' URI, the path portion is the file on disk containing the +code object. The OFFSET parameter is a 0-based offset in this file, to +the start of the code object. If omitted, it defaults to 0. The SIZE +parameter is the size of the code object in bytes. If omitted, it +defaults to the size of the file. + + For a 'memory' URI, the path portion is the process id of the process +owning the memory containing the code object. The OFFSET parameter is +the memory address where the code object is found, and the SIZE +parameter is its size in bytes. + + AMD GPU code objects are loaded into each AMD GPU device separately. +The 'info sharedlibrary' command may therefore show the same code object +loaded multiple times. As a consequence, setting a breakpoint in AMD +GPU code will result in multiple breakpoint locations if there are +multiple AMD GPU devices. + +21.4.9.5 AMD GPU Entity Target Identifiers and Convenience Variables +.................................................................... + +The AMD GPU entities have the following target identifier formats: + +Thread Target ID + The AMD GPU thread target identifier (SYSTAG) string has the + following format: + + AMDGPU Wave AGENT-ID:QUEUE-ID:DISPATCH-ID:WAVE-ID (WORK-GROUP-X,WORK-GROUP-Y,WORK-GROUP-Z)/WORK-GROUP-THREAD-INDEX + +21.4.9.6 AMD GPU Signals +........................ + +For AMD GPU wavefronts, GDB maps target conditions to stop signals in +the following way: + +'SIGILL' + Execution of an illegal instruction. + +'SIGTRAP' + Execution of a 'S_TRAP' instruction other than: + + * 'S_TRAP 1' which is used by GDB to insert breakpoints. + + * 'S_TRAP 2' which raises 'SIGABRT'. + +'SIGABRT' + Execution of a 'S_TRAP 2' instruction. + +'SIGFPE' + Execution of a floating point or integer instruction detects a + condition that is enabled to raise a signal. The conditions + include: + + * Floating point operation is invalid. + + * Floating point operation had subnormal input that was rounded + to zero. + + * Floating point operation performed a division by zero. + + * Floating point operation produced an overflow result. The + result was rounded to infinity. + + * Floating point operation produced an underflow result. A + subnormal result was rounded to zero. + + * Floating point operation produced an inexact result. + + * Integer operation performed a division by zero. + + By default, these conditions are not enabled to raise signals. The + 'set $mode' command can be used to change the AMD GPU wavefront's + register that has bits controlling which conditions are enabled to + raise signals. The 'print $trapsts' command can be used to inspect + which conditions have been detected even if they are not enabled to + raise a signal. + +'SIGBUS' + Execution of an instruction that accessed global memory using an + address that is outside the virtual address range. + +'SIGSEGV' + Execution of an instruction that accessed a global memory page that + is either not mapped or accessed with incompatible permissions. + + If a single instruction raises more than one signal, they will be +reported one at a time each time the wavefront is continued. + +21.4.9.7 AMD GPU Memory Violation Reporting +........................................... + +A wavefront can report memory violation events. However, the program +location at which they are reported may be after the machine instruction +that caused them. This can result in the reported source statement +being incorrect. The following commands can be used to control this +behavior: + +'set amdgpu precise-memory MODE' + Controls how AMD GPU devices detect memory violations, where MODE + can be: + + 'off' + The program location may not be immediately after the + instruction that caused the memory violation. This is the + default. + + 'on' + Requests that the program location will be immediately after + the instruction that caused a memory violation. Enabling this + mode may make the AMD GPU device execution significantly + slower as it has to wait for each memory operation to complete + before executing the next instruction. + + The 'amdgpu precise-memory' parameter is per-inferior. When an + inferior forks or execs, or the user uses the 'clone-inferior' + command, and an inferior is created as a result, the newly created + inferior inherits the parameter value of the original inferior. + +'show amdgpu precise-memory' + Displays the currently requested AMD GPU precise memory setting. + +21.4.9.8 AMD GPU Logging +........................ + +The 'set debug amd-dbgapi' command can be used to enable diagnostic +messages in the 'amd-dbgapi' target. The 'show debug amd-dbgapi' +command displays the current setting. *Note set debug amd-dbgapi::. + + The 'set debug amd-dbgapi-lib log-level LEVEL' command can be used to +enable diagnostic messages from the 'amd-dbgapi' library (which GDB uses +under the hood). The 'show debug amd-dbgapi-lib log-level' command +displays the current 'amd-dbgapi' library log level. *Note set debug +amd-dbgapi-lib::. + +21.4.9.9 AMD GPU Restrictions +............................. + + 1. When in non-stop mode, wavefronts may not hit breakpoints inserted + while not stopped, nor see memory updates made while not stopped, + until the wavefront is next stopped. Memory updated by non-stopped + wavefronts may not be visible until the wavefront is next stopped. + + 2. The HIP runtime performs deferred code object loading by default. + AMD GPU code objects are not loaded until the first kernel is + launched. Before then, all breakpoints have to be set as pending + breakpoints. + + If source line positions are used that only correspond to source + lines in unloaded code objects, then GDB may not set pending + breakpoints, and instead set breakpoints on the next following + source line that maps to host code. This can result in unexpected + breakpoint hits being reported. When the code object containing + the source lines is loaded, the incorrect breakpoints will be + removed and replaced by the correct ones. This problem can be + avoided by only setting breakpoints in unloaded code objects using + symbol or function names. + + Setting the 'HIP_ENABLE_DEFERRED_LOADING' environment variable to + '0' can be used to disable deferred code object loading by the HIP + runtime. This ensures all code objects will be loaded when the + inferior reaches the beginning of the 'main' function. + + 3. If no CPU thread is running, then 'Ctrl-C' is not able to stop AMD + GPU threads. This can happen for example if you enable + 'scheduler-locking' after the whole program stopped, and then + resume an AMD GPU thread. The only way to unblock the situation is + to kill the GDB process. + + 4. + By default, for some architectures, the AMD GPU device driver + causes all AMD GPU wavefronts created when GDB is not attached to + be unable to report the dispatch associated with the wavefront, or + the wavefront's work-group position. The 'info threads' command + will display this missing information with a '?'. + + This does not affect wavefronts created while GDB is attached which + are always capable of reporting this information. + + If the 'HSA_ENABLE_DEBUG' environment variable is set to '1' when + the AMD ROCm runtime is initialized, then this information will be + available for all architectures even for wavefronts created when + GDB was not attached. + + +File: gdb.info, Node: Controlling GDB, Next: Extending GDB, Prev: Configurations, Up: Top + +22 Controlling GDB +****************** + +You can alter the way GDB interacts with you by using the 'set' command. +For commands controlling how GDB displays data, see *note Print +Settings: Print Settings. Other settings are described here. + +* Menu: + +* Prompt:: Prompt +* Editing:: Command editing +* Command History:: Command history +* Screen Size:: Screen size +* Output Styling:: Output styling +* Numbers:: Numbers +* ABI:: Configuring the current ABI +* Auto-loading:: Automatically loading associated files +* Messages/Warnings:: Optional warnings and messages +* Debugging Output:: Optional messages about internal happenings +* Other Misc Settings:: Other Miscellaneous Settings + + +File: gdb.info, Node: Prompt, Next: Editing, Up: Controlling GDB + +22.1 Prompt +=========== + +GDB indicates its readiness to read a command by printing a string +called the "prompt". This string is normally '(gdb)'. You can change +the prompt string with the 'set prompt' command. For instance, when +debugging GDB with GDB, it is useful to change the prompt in one of the +GDB sessions so that you can always tell which one you are talking to. + + _Note:_ 'set prompt' does not add a space for you after the prompt +you set. This allows you to set a prompt which ends in a space or a +prompt that does not. + +'set prompt NEWPROMPT' + Directs GDB to use NEWPROMPT as its prompt string henceforth. + +'show prompt' + Prints a line of the form: 'Gdb's prompt is: YOUR-PROMPT' + + Versions of GDB that ship with Python scripting enabled have prompt +extensions. The commands for interacting with these extensions are: + +'set extended-prompt PROMPT' + Set an extended prompt that allows for substitutions. *Note + gdb.prompt::, for a list of escape sequences that can be used for + substitution. Any escape sequences specified as part of the prompt + string are replaced with the corresponding strings each time the + prompt is displayed. + + For example: + + set extended-prompt Current working directory: \w (gdb) + + Note that when an extended-prompt is set, it takes control of the + PROMPT_HOOK hook. *Note prompt_hook::, for further information. + +'show extended-prompt' + Prints the extended prompt. Any escape sequences specified as part + of the prompt string with 'set extended-prompt', are replaced with + the corresponding strings each time the prompt is displayed. + + +File: gdb.info, Node: Editing, Next: Command History, Prev: Prompt, Up: Controlling GDB + +22.2 Command Editing +==================== + +GDB reads its input commands via the "Readline" interface. This GNU +library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are GNU Emacs-style or +"vi"-style inline editing of commands, 'csh'-like history substitution, +and a storage and recall of command history across debugging sessions. + + You may control the behavior of command line editing in GDB with the +command 'set'. + +'set editing' +'set editing on' + Enable command line editing (enabled by default). + +'set editing off' + Disable command line editing. + +'show editing' + Show whether command line editing is enabled. + + *Note Command Line Editing::, for more details about the Readline +interface. Users unfamiliar with GNU Emacs or 'vi' are encouraged to +read that chapter. + + GDB sets the Readline application name to 'gdb'. This is useful for +conditions in '.inputrc'. + + GDB defines a bindable Readline command, 'operate-and-get-next'. +This is bound to 'C-o' by default. This command accepts the current +line for execution and fetches the next line relative to the current +line from the history for editing. Any argument is ignored. + + It is possible to discover which version of Readline GDB is using +with the 'show configuration' command (*note show configuration::). + + +File: gdb.info, Node: Command History, Next: Screen Size, Prev: Editing, Up: Controlling GDB + +22.3 Command History +==================== + +GDB can keep track of the commands you type during your debugging +sessions, so that you can be certain of precisely what happened. Use +these commands to manage the GDB command history facility. + + GDB uses the GNU History library, a part of the Readline package, to +provide the history facility. *Note Using History Interactively::, for +the detailed description of the History library. + + To issue a command to GDB without affecting certain aspects of the +state which is seen by users, prefix it with 'server ' (*note Server +Prefix::). This means that this command will not affect the command +history, nor will it affect GDB's notion of which command to repeat if + is pressed on a line by itself. + + The server prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Here is the description of GDB commands related to command history. + +'set history filename [FNAME]' + Set the name of the GDB command history file to FNAME. This is the + file where GDB reads an initial command history list, and where it + writes the command history from this session when it exits. You + can access this list through history expansion or through the + history command editing characters listed below. This file + defaults to the value of the environment variable 'GDBHISTFILE', or + to './.gdb_history' ('./_gdb_history' on MS-DOS) if this variable + is not set. + + The 'GDBHISTFILE' environment variable is read after processing any + GDB initialization files (*note Startup::) and after processing any + commands passed using command line options (for example, '-ex'). + + If the FNAME argument is not given, or if the 'GDBHISTFILE' is the + empty string then GDB will neither try to load an existing history + file, nor will it try to save the history on exit. + +'set history save' +'set history save on' + Record command history in a file, whose name may be specified with + the 'set history filename' command. By default, this option is + disabled. The command history will be recorded when GDB exits. If + 'set history filename' is set to the empty string then history + saving is disabled, even when 'set history save' is 'on'. + +'set history save off' + Don't record the command history into the file specified by 'set + history filename' when GDB exits. + +'set history size SIZE' +'set history size unlimited' + Set the number of commands which GDB keeps in its history list. + This defaults to the value of the environment variable + 'GDBHISTSIZE', or to 256 if this variable is not set. Non-numeric + values of 'GDBHISTSIZE' are ignored. If SIZE is 'unlimited' or if + 'GDBHISTSIZE' is either a negative number or the empty string, then + the number of commands GDB keeps in the history list is unlimited. + + The 'GDBHISTSIZE' environment variable is read after processing any + GDB initialization files (*note Startup::) and after processing any + commands passed using command line options (for example, '-ex'). + +'set history remove-duplicates COUNT' +'set history remove-duplicates unlimited' + Control the removal of duplicate history entries in the command + history list. If COUNT is non-zero, GDB will look back at the last + COUNT history entries and remove the first entry that is a + duplicate of the current entry being added to the command history + list. If COUNT is 'unlimited' then this lookbehind is unbounded. + If COUNT is 0, then removal of duplicate history entries is + disabled. + + Only history entries added during the current session are + considered for removal. This option is set to 0 by default. + + History expansion assigns special meaning to the character '!'. +*Note Event Designators::, for more details. + + Since '!' is also the logical not operator in C, history expansion is +off by default. If you decide to enable history expansion with the 'set +history expansion on' command, you may sometimes need to follow '!' +(when it is used as logical not, in an expression) with a space or a tab +to prevent it from being expanded. The readline history facilities do +not attempt substitution on the strings '!=' and '!(', even when history +expansion is enabled. + + The commands to control history expansion are: + +'set history expansion on' +'set history expansion' + Enable history expansion. History expansion is off by default. + +'set history expansion off' + Disable history expansion. + +'show history' +'show history filename' +'show history save' +'show history size' +'show history expansion' + These commands display the state of the GDB history parameters. + 'show history' by itself displays all four states. + +'show commands' + Display the last ten commands in the command history. + +'show commands N' + Print ten commands centered on command number N. + +'show commands +' + Print ten commands just after the commands last printed. + + +File: gdb.info, Node: Screen Size, Next: Output Styling, Prev: Command History, Up: Controlling GDB + +22.4 Screen Size +================ + +Certain commands to GDB may produce large amounts of information output +to the screen. To help you read all of it, GDB pauses and asks you for +input at the end of each page of output. Type when you want to +see one more page of output, 'q' to discard the remaining output, or 'c' +to continue without paging for the rest of the current command. Also, +the screen width setting determines when to wrap lines of output. +Depending on what is being printed, GDB tries to break the line at a +readable place, rather than simply letting it overflow onto the +following line. + + Normally GDB knows the size of the screen from the terminal driver +software. For example, on Unix GDB uses the termcap data base together +with the value of the 'TERM' environment variable and the 'stty rows' +and 'stty cols' settings. If this is not correct, you can override it +with the 'set height' and 'set width' commands: + +'set height LPP' +'set height unlimited' +'show height' +'set width CPL' +'set width unlimited' +'show width' + These 'set' commands specify a screen height of LPP lines and a + screen width of CPL characters. The associated 'show' commands + display the current settings. + + If you specify a height of either 'unlimited' or zero lines, GDB + does not pause during output no matter how long the output is. + This is useful if output is to a file or to an editor buffer. + + Likewise, you can specify 'set width unlimited' or 'set width 0' to + prevent GDB from wrapping its output. + +'set pagination on' +'set pagination off' + Turn the output pagination on or off; the default is on. Turning + pagination off is the alternative to 'set height unlimited'. Note + that running GDB with the '--batch' option (*note -batch: Mode + Options.) also automatically disables pagination. + +'show pagination' + Show the current pagination mode. + + +File: gdb.info, Node: Output Styling, Next: Numbers, Prev: Screen Size, Up: Controlling GDB + +22.5 Output Styling +=================== + +GDB can style its output on a capable terminal. This is enabled by +default on most systems, but disabled by default when in batch mode +(*note Mode Options::). Various style settings are available; and +styles can also be disabled entirely. + +'set style enabled 'on|off'' + Enable or disable all styling. The default is host-dependent, with + most hosts defaulting to 'on'. + + If the 'NO_COLOR' environment variable is set to a non-empty value, + then GDB will change this to 'off' at startup. + +'show style enabled' + Show the current state of styling. + +'set style sources 'on|off'' + Enable or disable source code styling. This affects whether source + code, such as the output of the 'list' command, is styled. The + default is 'on'. Note that source styling only works if styling in + general is enabled, and if a source highlighting library is + available to GDB. + + There are two ways that highlighting can be done. First, if GDB + was linked with the GNU Source Highlight library, then it is used. + Otherwise, if GDB was configured with Python scripting support, and + if the Python Pygments package is available, then it will be used. + +'show style sources' + Show the current state of source code styling. + +'set style tui-current-position 'on|off'' + Enable or disable styling of the source and assembly code + highlighted by the TUI's current position indicator. The default + is 'off'. *Note GDB Text User Interface: TUI. + +'show style tui-current-position' + Show whether the source and assembly code highlighted by the TUI's + current position indicator is styled. + +'set style disassembler enabled 'on|off'' + Enable or disable disassembler styling. This affects whether + disassembler output, such as the output of the 'disassemble' + command, is styled. Disassembler styling only works if styling in + general is enabled (with 'set style enabled on'), and if a source + highlighting library is available to GDB. + + The two source highlighting libraries that GDB could use to style + disassembler output are; GDB's builtin disassembler, or the Python + Pygments package. + + GDB's first choice will be to use the builtin disassembler for + styling, this usually provides better results, being able to style + different types of instruction operands differently. However, the + builtin disassembler is not able to style all architectures. + + For architectures that the builtin disassembler is unable to style, + GDB will fall back to use the Python Pygments package where + possible. In order to use the Python Pygments package, GDB must be + built with Python support, and the Pygments package must be + installed. + + If neither of these options are available then GDB will produce + unstyled disassembler output, even when this setting is 'on'. + + To discover if the current architecture supports styling using the + builtin disassembler library see *note 'maint show + libopcodes-styling enabled': maint_libopcodes_styling. + +'show style disassembler enabled' + Show the current state of disassembler styling. + + Subcommands of 'set style' control specific forms of styling. These +subcommands all follow the same pattern: each style-able object can be +styled with a foreground color, a background color, and an intensity. + + For example, the style of file names can be controlled using the 'set +style filename' group of commands: + +'set style filename background COLOR' + Set the background to COLOR. Valid colors are 'none' (meaning the + terminal's default color), 'black', 'red', 'green', 'yellow', + 'blue', 'magenta', 'cyan', and'white'. + +'set style filename foreground COLOR' + Set the foreground to COLOR. Valid colors are 'none' (meaning the + terminal's default color), 'black', 'red', 'green', 'yellow', + 'blue', 'magenta', 'cyan', and'white'. + +'set style filename intensity VALUE' + Set the intensity to VALUE. Valid intensities are 'normal' (the + default), 'bold', and 'dim'. + + The 'show style' command and its subcommands are styling a style name +in their output using its own style. So, use 'show style' to see the +complete list of styles, their characteristics and the visual aspect of +each style. + + The style-able objects are: +'command' + Control the styling of any GDB commands that are displayed by GDB. + By default, this style's intensity is bold. + +'filename' + Control the styling of file names and URLs. By default, this + style's foreground color is green. + +'function' + Control the styling of function names. These are managed with the + 'set style function' family of commands. By default, this style's + foreground color is yellow. + + This style is also used for symbol names in styled disassembler + output if GDB is using its builtin disassembler library for styling + (*note 'set style disassembler enabled': + style_disassembler_enabled.). + +'line-number' + Control the styling of line numbers. By default, this style's + intensity is dim. + +'variable' + Control the styling of variable names. These are managed with the + 'set style variable' family of commands. By default, this style's + foreground color is cyan. + +'address' + Control the styling of addresses. These are managed with the 'set + style address' family of commands. By default, this style's + foreground color is blue. + + This style is also used for addresses in styled disassembler output + if GDB is using its builtin disassembler library for styling (*note + 'set style disassembler enabled': style_disassembler_enabled.). + +'version' + Control the styling of GDB's version number text. By default, this + style's foreground color is magenta and it has bold intensity. The + version number is displayed in two places, the output of 'show + version', and when GDB starts up. + + In order to control how GDB styles the version number at startup, + add the 'set style version' family of commands to the early + initialization command file (*note Initialization Files::). + +'title' + Control the styling of titles. These are managed with the 'set + style title' family of commands. By default, this style's + intensity is bold. The title style is used when displaying the + header line of a list, for example the first line of the output of + 'info breakpoints' (*note Set Breaks::). + +'highlight' + Control the styling of highlightings. These are managed with the + 'set style highlight' family of commands. By default, this style's + foreground color is red. Commands are using the highlight style to + draw the user attention to some specific parts of their output. + For example, the command 'apropos -v REGEXP' uses the highlight + style to mark the documentation parts matching REGEXP. + +'metadata' + Control the styling of data annotations added by GDB to data it + displays. By default, this style's intensity is dim. Metadata + annotations include the 'repeats N times' annotation for suppressed + display of repeated array elements (*note Print Settings::), + '' and '' annotations for errors and + '' annotations for optimized-out values in + displaying stack frame information in backtraces (*note + Backtrace::), etc. + +'tui-border' + Control the styling of the TUI border. Note that, unlike other + styling options, only the color of the border can be controlled via + 'set style'. This was done for compatibility reasons, as TUI + controls to set the border's intensity predated the addition of + general styling to GDB. *Note TUI Configuration::. + +'tui-active-border' + Control the styling of the active TUI border; that is, the TUI + window that has the focus. + +'disassembler comment' + Control the styling of comments in the disassembler output. These + are managed with the 'set style disassembler comment' family of + commands. This style is only used when GDB is styling using its + builtin disassembler library (*note 'set style disassembler + enabled': style_disassembler_enabled.). By default, this style's + intensity is dim, and its foreground color is white. + +'disassembler immediate' + Control the styling of numeric operands in the disassembler output. + These are managed with the 'set style disassembler immediate' + family of commands. This style is not used for instruction + operands that represent addresses, in that case the 'disassembler + address' style is used. This style is only used when GDB is + styling using its builtin disassembler library. By default, this + style's foreground color is blue. + +'disassembler address' + Control the styling of address operands in the disassembler output. + This is an alias for the 'address' style. + +'disassembler symbol' + Control the styling of symbol names in the disassembler output. + This is an alias for the 'function' style. + +'disassembler mnemonic' + Control the styling of instruction mnemonics in the disassembler + output. These are managed with the 'set style disassembler + mnemonic' family of commands. This style is also used for + assembler directives, e.g. '.byte', '.word', etc. This style is + only used when GDB is styling using its builtin disassembler + library. By default, this style's foreground color is green. + +'disassembler register' + Control the styling of register operands in the disassembler + output. These are managed with the 'set style disassembler + register' family of commands. This style is only used when GDB is + styling using its builtin disassembler library. By default, this + style's foreground color is red. + + +File: gdb.info, Node: Numbers, Next: ABI, Prev: Output Styling, Up: Controlling GDB + +22.6 Numbers +============ + +You can always enter numbers in octal, decimal, or hexadecimal in GDB by +the usual conventions: octal numbers begin with '0', decimal numbers end +with '.', and hexadecimal numbers begin with '0x'. Numbers that neither +begin with '0' or '0x', nor end with a '.' are, by default, entered in +base 10; likewise, the default display for numbers--when no particular +format is specified--is base 10. You can change the default base for +both input and output with the commands described below. + +'set input-radix BASE' + Set the default base for numeric input. Supported choices for BASE + are decimal 8, 10, or 16. The base must itself be specified either + unambiguously or using the current input radix; for example, any of + + set input-radix 012 + set input-radix 10. + set input-radix 0xa + + sets the input base to decimal. On the other hand, 'set + input-radix 10' leaves the input radix unchanged, no matter what it + was, since '10', being without any leading or trailing signs of its + base, is interpreted in the current radix. Thus, if the current + radix is 16, '10' is interpreted in hex, i.e. as 16 decimal, which + doesn't change the radix. + +'set output-radix BASE' + Set the default base for numeric display. Supported choices for + BASE are decimal 8, 10, or 16. The base must itself be specified + either unambiguously or using the current input radix. + +'show input-radix' + Display the current default base for numeric input. + +'show output-radix' + Display the current default base for numeric display. + +'set radix [BASE]' +'show radix' + These commands set and show the default base for both input and + output of numbers. 'set radix' sets the radix of input and output + to the same base; without an argument, it resets the radix back to + its default value of 10. + + +File: gdb.info, Node: ABI, Next: Auto-loading, Prev: Numbers, Up: Controlling GDB + +22.7 Configuring the Current ABI +================================ + +GDB can determine the "ABI" (Application Binary Interface) of your +application automatically. However, sometimes you need to override its +conclusions. Use these commands to manage GDB's view of the current +ABI. + + One GDB configuration can debug binaries for multiple operating +system targets, either via remote debugging or native emulation. GDB +will autodetect the "OS ABI" (Operating System ABI) in use, but you can +override its conclusion using the 'set osabi' command. One example +where this is useful is in debugging of binaries which use an alternate +C library (e.g. UCLIBC for GNU/Linux) which does not have the same +identifying marks that the standard C library for your platform +provides. + + When GDB is debugging the AArch64 architecture, it provides a +"Newlib" OS ABI. This is useful for handling 'setjmp' and 'longjmp' when +debugging binaries that use the NEWLIB C library. The "Newlib" OS ABI +can be selected by 'set osabi Newlib'. + +'show osabi' + Show the OS ABI currently in use. + +'set osabi' + With no argument, show the list of registered available OS ABI's. + +'set osabi ABI' + Set the current OS ABI to ABI. + + Generally, the way that an argument of type 'float' is passed to a +function depends on whether the function is prototyped. For a +prototyped (i.e. ANSI/ISO style) function, 'float' arguments are passed +unchanged, according to the architecture's convention for 'float'. For +unprototyped (i.e. K&R style) functions, 'float' arguments are first +promoted to type 'double' and then passed. + + Unfortunately, some forms of debug information do not reliably +indicate whether a function is prototyped. If GDB calls a function that +is not marked as prototyped, it consults 'set coerce-float-to-double'. + +'set coerce-float-to-double' +'set coerce-float-to-double on' + Arguments of type 'float' will be promoted to 'double' when passed + to an unprototyped function. This is the default setting. + +'set coerce-float-to-double off' + Arguments of type 'float' will be passed directly to unprototyped + functions. + +'show coerce-float-to-double' + Show the current setting of promoting 'float' to 'double'. + + GDB needs to know the ABI used for your program's C++ objects. The +correct C++ ABI depends on which C++ compiler was used to build your +application. GDB only fully supports programs with a single C++ ABI; if +your program contains code using multiple C++ ABI's or if GDB can not +identify your program's ABI correctly, you can tell GDB which ABI to +use. Currently supported ABI's include "gnu-v2", for 'g++' versions +before 3.0, "gnu-v3", for 'g++' versions 3.0 and later, and "hpaCC" for +the HP ANSI C++ compiler. Other C++ compilers may use the "gnu-v2" or +"gnu-v3" ABI's as well. The default setting is "auto". + +'show cp-abi' + Show the C++ ABI currently in use. + +'set cp-abi' + With no argument, show the list of supported C++ ABI's. + +'set cp-abi ABI' +'set cp-abi auto' + Set the current C++ ABI to ABI, or return to automatic detection. + + +File: gdb.info, Node: Auto-loading, Next: Messages/Warnings, Prev: ABI, Up: Controlling GDB + +22.8 Automatically loading associated files +=========================================== + +GDB sometimes reads files with commands and settings automatically, +without being explicitly told so by the user. We call this feature +"auto-loading". While auto-loading is useful for automatically adapting +GDB to the needs of your project, it can sometimes produce unexpected +results or introduce security risks (e.g., if the file comes from +untrusted sources). + + There are various kinds of files GDB can automatically load. In +addition to these files, GDB supports auto-loading code written in +various extension languages. *Note Auto-loading extensions::. + + Note that loading of these associated files (including the local +'.gdbinit' file) requires accordingly configured 'auto-load safe-path' +(*note Auto-loading safe path::). + + For these reasons, GDB includes commands and options to let you +control when to auto-load files and which files should be auto-loaded. + +'set auto-load off' + Globally disable loading of all auto-loaded files. You may want to + use this command with the '-iex' option (*note Option + -init-eval-command::) such as: + $ gdb -iex "set auto-load off" untrusted-executable corefile + + Be aware that system init file (*note System-wide configuration::) + and init files from your home directory (*note Home Directory Init + File::) still get read (as they come from generally trusted + directories). To prevent GDB from auto-loading even those init + files, use the '-nx' option (*note Mode Options::), in addition to + 'set auto-load no'. + +'show auto-load' + Show whether auto-loading of each specific 'auto-load' file(s) is + enabled or disabled. + + (gdb) show auto-load + gdb-scripts: Auto-loading of canned sequences of commands scripts is on. + libthread-db: Auto-loading of inferior specific libthread_db is on. + local-gdbinit: Auto-loading of .gdbinit script from current directory + is on. + python-scripts: Auto-loading of Python scripts is on. + safe-path: List of directories from which it is safe to auto-load files + is $debugdir:$datadir/auto-load. + scripts-directory: List of directories from which to load auto-loaded scripts + is $debugdir:$datadir/auto-load. + +'info auto-load' + Print whether each specific 'auto-load' file(s) have been + auto-loaded or not. + + (gdb) info auto-load + gdb-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.gdb + libthread-db: No auto-loaded libthread-db. + local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been + loaded. + python-scripts: + Loaded Script + Yes /home/user/gdb/gdb-gdb.py + + These are GDB control commands for the auto-loading: + +*Note set auto-load off::. Disable auto-loading globally. +*Note show auto-load::. Show setting of all kinds of + files. +*Note info auto-load::. Show state of all kinds of files. +*Note set auto-load gdb-scripts::. Control for GDB command scripts. +*Note show auto-load gdb-scripts::. Show setting of GDB command + scripts. +*Note info auto-load gdb-scripts::. Show state of GDB command scripts. +*Note set auto-load python-scripts::.Control for GDB Python scripts. +*Note show auto-load python-scripts::.Show setting of GDB Python + scripts. +*Note info auto-load python-scripts::.Show state of GDB Python scripts. +*Note set auto-load guile-scripts::. Control for GDB Guile scripts. +*Note show auto-load guile-scripts::.Show setting of GDB Guile scripts. +*Note info auto-load guile-scripts::.Show state of GDB Guile scripts. +*Note set auto-load scripts-directory::.Control for GDB auto-loaded + scripts location. +*Note show auto-load scripts-directory::.Show GDB auto-loaded scripts + location. +*Note add-auto-load-scripts-directory::.Add directory for auto-loaded + scripts location list. +*Note set auto-load local-gdbinit::. Control for init file in the + current directory. +*Note show auto-load local-gdbinit::.Show setting of init file in the + current directory. +*Note info auto-load local-gdbinit::.Show state of init file in the + current directory. +*Note set auto-load libthread-db::. Control for thread debugging + library. +*Note show auto-load libthread-db::. Show setting of thread debugging + library. +*Note info auto-load libthread-db::. Show state of thread debugging + library. +*Note set auto-load safe-path::. Control directories trusted for + automatic loading. +*Note show auto-load safe-path::. Show directories trusted for + automatic loading. +*Note add-auto-load-safe-path::. Add directory trusted for + automatic loading. + +* Menu: + +* Init File in the Current Directory:: 'set/show/info auto-load local-gdbinit' +* libthread_db.so.1 file:: 'set/show/info auto-load libthread-db' + +* Auto-loading safe path:: 'set/show/info auto-load safe-path' +* Auto-loading verbose mode:: 'set/show debug auto-load' + + +File: gdb.info, Node: Init File in the Current Directory, Next: libthread_db.so.1 file, Up: Auto-loading + +22.8.1 Automatically loading init file in the current directory +--------------------------------------------------------------- + +By default, GDB reads and executes the canned sequences of commands from +init file (if any) in the current working directory, see *note Init File +in the Current Directory during Startup::. + + Note that loading of this local '.gdbinit' file also requires +accordingly configured 'auto-load safe-path' (*note Auto-loading safe +path::). + +'set auto-load local-gdbinit [on|off]' + Enable or disable the auto-loading of canned sequences of commands + (*note Sequences::) found in init file in the current directory. + +'show auto-load local-gdbinit' + Show whether auto-loading of canned sequences of commands from init + file in the current directory is enabled or disabled. + +'info auto-load local-gdbinit' + Print whether canned sequences of commands from init file in the + current directory have been auto-loaded. + + +File: gdb.info, Node: libthread_db.so.1 file, Next: Auto-loading safe path, Prev: Init File in the Current Directory, Up: Auto-loading + +22.8.2 Automatically loading thread debugging library +----------------------------------------------------- + +This feature is currently present only on GNU/Linux native hosts. + + GDB reads in some cases thread debugging library from places specific +to the inferior (*note set libthread-db-search-path::). + + The special 'libthread-db-search-path' entry '$sdir' is processed +without checking this 'set auto-load libthread-db' switch as system +libraries have to be trusted in general. In all other cases of +'libthread-db-search-path' entries GDB checks first if 'set auto-load +libthread-db' is enabled before trying to open such thread debugging +library. + + Note that loading of this debugging library also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + +'set auto-load libthread-db [on|off]' + Enable or disable the auto-loading of inferior specific thread + debugging library. + +'show auto-load libthread-db' + Show whether auto-loading of inferior specific thread debugging + library is enabled or disabled. + +'info auto-load libthread-db' + Print the list of all loaded inferior specific thread debugging + libraries and for each such library print list of inferior PIDs + using it. + + +File: gdb.info, Node: Auto-loading safe path, Next: Auto-loading verbose mode, Prev: libthread_db.so.1 file, Up: Auto-loading + +22.8.3 Security restriction for auto-loading +-------------------------------------------- + +As the files of inferior can come from untrusted source (such as +submitted by an application user) GDB does not always load any files +automatically. GDB provides the 'set auto-load safe-path' setting to +list directories trusted for loading files not explicitly requested by +user. Each directory can also be a shell wildcard pattern. + + If the path is not set properly you will see a warning and the file +will not get loaded: + + $ ./gdb -q ./gdb + Reading symbols from /home/user/gdb/gdb... + warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". + +To instruct GDB to go ahead and use the init files anyway, invoke GDB +like this: + + $ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb + + The list of trusted directories is controlled by the following +commands: + +'set auto-load safe-path [DIRECTORIES]' + Set the list of directories (and their subdirectories) trusted for + automatic loading and execution of scripts. You can also enter a + specific trusted file. Each directory can also be a shell wildcard + pattern; wildcards do not match directory separator - see + 'FNM_PATHNAME' for system function 'fnmatch' (*note fnmatch: + (libc)Wildcard Matching.). If you omit DIRECTORIES, 'auto-load + safe-path' will be reset to its default value as specified during + GDB compilation. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load safe-path' + Show the list of directories trusted for automatic loading and + execution of scripts. + +'add-auto-load-safe-path' + Add an entry (or list of entries) to the list of directories + trusted for automatic loading and execution of scripts. Multiple + entries may be delimited by the host platform path separator in + use. + + This variable defaults to what '--with-auto-load-dir' has been +configured to (*note with-auto-load-dir::). '$debugdir' and '$datadir' +substitution applies the same as for *note set auto-load +scripts-directory::. The default 'set auto-load safe-path' value can be +also overridden by GDB configuration option +'--with-auto-load-safe-path'. + + Setting this variable to '/' disables this security protection, +corresponding GDB configuration option is +'--without-auto-load-safe-path'. This variable is supposed to be set to +the system directories writable by the system superuser only. Users can +add their source directories in init files in their home directories +(*note Home Directory Init File::). See also deprecated init file in +the current directory (*note Init File in the Current Directory during +Startup::). + + To force GDB to load the files it declined to load in the previous +example, you could use one of the following ways: + +'~/.gdbinit': 'add-auto-load-safe-path ~/src/gdb' + Specify this trusted directory (or a file) as additional component + of the list. You have to specify also any existing directories + displayed by by 'show auto-load safe-path' (such as '/usr:/bin' in + this example). + +'gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" ...' + Specify this directory as in the previous case but just for a + single GDB session. + +'gdb -iex "set auto-load safe-path /" ...' + Disable auto-loading safety for a single GDB session. This assumes + all the files you debug during this GDB session will come from + trusted sources. + +'./configure --without-auto-load-safe-path' + During compilation of GDB you may disable any auto-loading safety. + This assumes all the files you will ever debug with this GDB come + from trusted sources. + + On the other hand you can also explicitly forbid automatic files +loading which also suppresses any such warning messages: + +'gdb -iex "set auto-load no" ...' + You can use GDB command-line option for a single GDB session. + +'~/.gdbinit': 'set auto-load no' + Disable auto-loading globally for the user (*note Home Directory + Init File::). While it is improbable, you could also use system + init file instead (*note System-wide configuration::). + + This setting applies to the file names as entered by user. If no +entry matches GDB tries as a last resort to also resolve all the file +names into their canonical form (typically resolving symbolic links) and +compare the entries again. GDB already canonicalizes most of the +filenames on its own before starting the comparison so a canonical form +of directories is recommended to be entered. + + +File: gdb.info, Node: Auto-loading verbose mode, Prev: Auto-loading safe path, Up: Auto-loading + +22.8.4 Displaying files tried for auto-load +------------------------------------------- + +For better visibility of all the file locations where you can place +scripts to be auto-loaded with inferior -- or to protect yourself +against accidental execution of untrusted scripts -- GDB provides a +feature for printing all the files attempted to be loaded. Both +existing and non-existing files may be printed. + + For example the list of directories from which it is safe to +auto-load files (*note Auto-loading safe path::) applies also to +canonicalized filenames which may not be too obvious while setting it +up. + + (gdb) set debug auto-load on + (gdb) file ~/src/t/true + auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" + for objfile "/tmp/true". + auto-load: Updating directories of "/usr:/opt". + auto-load: Using directory "/usr". + auto-load: Using directory "/opt". + warning: File "/tmp/true-gdb.gdb" auto-loading has been declined + by your `auto-load safe-path' set to "/usr:/opt". + +'set debug auto-load [on|off]' + Set whether to print the filenames attempted to be auto-loaded. + +'show debug auto-load' + Show whether printing of the filenames attempted to be auto-loaded + is turned on or off. + + +File: gdb.info, Node: Messages/Warnings, Next: Debugging Output, Prev: Auto-loading, Up: Controlling GDB + +22.9 Optional Warnings and Messages +=================================== + +By default, GDB is silent about its inner workings. If you are running +on a slow machine, you may want to use the 'set verbose' command. This +makes GDB tell you when it does a lengthy internal operation, so you +will not think it has crashed. + + Currently, the messages controlled by 'set verbose' are those which +announce that the symbol table for a source file is being read; see +'symbol-file' in *note Commands to Specify Files: Files. + +'set verbose on' + Enables GDB output of certain informational messages. + +'set verbose off' + Disables GDB output of certain informational messages. + +'show verbose' + Displays whether 'set verbose' is on or off. + + By default, if GDB encounters bugs in the symbol table of an object +file, it is silent; but if you are debugging a compiler, you may find +this information useful (*note Errors Reading Symbol Files: Symbol +Errors.). + +'set complaints LIMIT' + Permits GDB to output LIMIT complaints about each type of unusual + symbols before becoming silent about the problem. Set LIMIT to + zero to suppress all complaints; set it to a large number to + prevent complaints from being suppressed. + +'show complaints' + Displays how many symbol complaints GDB is permitted to produce. + + By default, GDB is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: + + (gdb) run + The program being debugged has been started already. + Start it from the beginning? (y or n) + + If you are willing to unflinchingly face the consequences of your own +commands, you can disable this "feature": + +'set confirm off' + Disables confirmation requests. Note that running GDB with the + '--batch' option (*note -batch: Mode Options.) also automatically + disables confirmation requests. + +'set confirm on' + Enables confirmation requests (the default). + +'show confirm' + Displays state of confirmation requests. + + If you need to debug user-defined commands or sourced files you may +find it useful to enable "command tracing". In this mode each command +will be printed as it is executed, prefixed with one or more '+' +symbols, the quantity denoting the call depth of each command. + +'set trace-commands on' + Enable command tracing. +'set trace-commands off' + Disable command tracing. +'show trace-commands' + Display the current state of command tracing. + + +File: gdb.info, Node: Debugging Output, Next: Other Misc Settings, Prev: Messages/Warnings, Up: Controlling GDB + +22.10 Optional Messages about Internal Happenings +================================================= + +GDB has commands that enable optional debugging messages from various +GDB subsystems; normally these commands are of interest to GDB +maintainers, or when reporting a bug. This section documents those +commands. + +'set exec-done-display' + Turns on or off the notification of asynchronous commands' + completion. When on, GDB will print a message when an asynchronous + command finishes its execution. The default is off. +'show exec-done-display' + Displays the current setting of asynchronous command completion + notification. + +'set debug aarch64' + Turns on or off display of debugging messages related to ARM + AArch64. The default is off. +'show debug aarch64' + Displays the current state of displaying debugging messages related + to ARM AArch64. + +'set debug arch' + Turns on or off display of gdbarch debugging info. The default is + off +'show debug arch' + Displays the current state of displaying gdbarch debugging info. + +'set debug aix-thread' + Display debugging messages about inner workings of the AIX thread + module. +'show debug aix-thread' + Show the current state of AIX thread debugging info display. + +'set debug amd-dbgapi-lib' +'show debug amd-dbgapi-lib' + + The 'set debug amd-dbgapi-lib log-level LEVEL' command can be used + to enable diagnostic messages from the 'amd-dbgapi' library, where + LEVEL can be: + + 'off' + no logging is enabled + + 'error' + fatal errors are reported + + 'warning' + fatal errors and warnings are reported + + 'info' + fatal errors, warnings, and info messages are reported + + 'verbose' + all messages are reported + + The 'show debug amd-dbgapi-lib log-level' command displays the + current amd-dbgapi library log level. + +'set debug amd-dbgapi' +'show debug amd-dbgapi' + + The 'set debug amd-dbgapi' command can be used to enable diagnostic + messages in the 'amd-dbgapi' target. The 'show debug amd-dbgapi' + command displays the current setting. *Note set debug + amd-dbgapi::. + +'set debug check-physname' + Check the results of the "physname" computation. When reading + DWARF debugging information for C++, GDB attempts to compute each + entity's name. GDB can do this computation in two different ways, + depending on exactly what information is present. When enabled, + this setting causes GDB to compute the names both ways and display + any discrepancies. +'show debug check-physname' + Show the current state of "physname" checking. + +'set debug coff-pe-read' + Control display of debugging messages related to reading of COFF/PE + exported symbols. The default is off. +'show debug coff-pe-read' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. + +'set debug dwarf-die' + Dump DWARF DIEs after they are read in. The value is the number of + nesting levels to print. A value of zero turns off the display. +'show debug dwarf-die' + Show the current state of DWARF DIE debugging. + +'set debug dwarf-line' + Turns on or off display of debugging messages related to reading + DWARF line tables. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug dwarf-line' + Show the current state of DWARF line table debugging. + +'set debug dwarf-read' + Turns on or off display of debugging messages related to reading + DWARF debug info. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug dwarf-read' + Show the current state of DWARF reader debugging. + +'set debug displaced' + Turns on or off display of GDB debugging info for the displaced + stepping support. The default is off. +'show debug displaced' + Displays the current state of displaying GDB debugging info related + to displaced stepping. + +'set debug event' + Turns on or off display of GDB event debugging info. The default + is off. +'show debug event' + Displays the current state of displaying GDB event debugging info. + +'set debug event-loop' + Controls output of debugging info about the event loop. The + possible values are 'off', 'all' (shows all debugging info) and + 'all-except-ui' (shows all debugging info except those about + UI-related events). +'show debug event-loop' + Shows the current state of displaying debugging info about the + event loop. + +'set debug expression' + Turns on or off display of debugging info about GDB expression + parsing. The default is off. +'show debug expression' + Displays the current state of displaying debugging info about GDB + expression parsing. + +'set debug fbsd-lwp' + Turns on or off debugging messages from the FreeBSD LWP debug + support. +'show debug fbsd-lwp' + Show the current state of FreeBSD LWP debugging messages. + +'set debug fbsd-nat' + Turns on or off debugging messages from the FreeBSD native target. +'show debug fbsd-nat' + Show the current state of FreeBSD native target debugging messages. + +'set debug fortran-array-slicing' + Turns on or off display of GDB Fortran array slicing debugging + info. The default is off. + +'show debug fortran-array-slicing' + Displays the current state of displaying GDB Fortran array slicing + debugging info. + +'set debug frame' + Turns on or off display of GDB frame debugging info. The default + is off. +'show debug frame' + Displays the current state of displaying GDB frame debugging info. + +'set debug gnu-nat' + Turn on or off debugging messages from the GNU/Hurd debug support. +'show debug gnu-nat' + Show the current state of GNU/Hurd debugging messages. + +'set debug infrun' + Turns on or off display of GDB debugging info for running the + inferior. The default is off. 'infrun.c' contains GDB's runtime + state machine used for implementing operations such as + single-stepping the inferior. +'show debug infrun' + Displays the current state of GDB inferior debugging. + +'set debug infcall' + Turns on or off display of debugging info related to inferior + function calls made by GDB. +'show debug infcall' + Displays the current state of GDB inferior function call debugging. + +'set debug jit' + Turn on or off debugging messages from JIT debug support. +'show debug jit' + Displays the current state of GDB JIT debugging. + +'set debug linux-nat [on|off]' + Turn on or off debugging messages from the Linux native target + debug support. +'show debug linux-nat' + Show the current state of Linux native target debugging messages. + +'set debug linux-namespaces' + Turn on or off debugging messages from the Linux namespaces debug + support. +'show debug linux-namespaces' + Show the current state of Linux namespaces debugging messages. + +'set debug mach-o' + Control display of debugging messages related to Mach-O symbols + processing. The default is off. +'show debug mach-o' + Displays the current state of displaying debugging messages related + to reading of COFF/PE exported symbols. + +'set debug notification' + Turn on or off debugging messages about remote async notification. + The default is off. +'show debug notification' + Displays the current state of remote async notification debugging + messages. + +'set debug observer' + Turns on or off display of GDB observer debugging. This includes + info such as the notification of observable events. +'show debug observer' + Displays the current state of observer debugging. + +'set debug overload' + Turns on or off display of GDB C++ overload debugging info. This + includes info such as ranking of functions, etc. The default is + off. +'show debug overload' + Displays the current state of displaying GDB C++ overload debugging + info. + +'set debug parser' + Turns on or off the display of expression parser debugging output. + Internally, this sets the 'yydebug' variable in the expression + parser. *Note Tracing Your Parser: (bison)Tracing, for details. + The default is off. +'show debug parser' + Show the current state of expression parser debugging. + +'set debug remote' + Turns on or off display of reports on all packets sent back and + forth across the serial line to the remote machine. The info is + printed on the GDB standard output stream. The default is off. +'show debug remote' + Displays the state of display of remote packets. + +'set debug remote-packet-max-chars' + Sets the maximum number of characters to display for each remote + packet when 'set debug remote' is on. This is useful to prevent + GDB from displaying lengthy remote packets and polluting the + console. + + The default value is '512', which means GDB will truncate each + remote packet after 512 bytes. + + Setting this option to 'unlimited' will disable truncation and will + output the full length of the remote packets. +'show debug remote-packet-max-chars' + Displays the number of bytes to output for remote packet debugging. + +'set debug separate-debug-file' + Turns on or off display of debug output about separate debug file + search. +'show debug separate-debug-file' + Displays the state of separate debug file search debug output. + +'set debug serial' + Turns on or off display of GDB serial debugging info. The default + is off. +'show debug serial' + Displays the current state of displaying GDB serial debugging info. + +'set debug solib' + Turns on or off display of debugging messages related to shared + libraries. The default is off. +'show debug solib' + Show the current state of solib debugging messages. + +'set debug symbol-lookup' + Turns on or off display of debugging messages related to symbol + lookup. The default is 0 (off). A value of 1 provides basic + information. A value greater than 1 provides more verbose + information. +'show debug symbol-lookup' + Show the current state of symbol lookup debugging messages. + +'set debug symfile' + Turns on or off display of debugging messages related to symbol + file functions. The default is off. *Note Files::. +'show debug symfile' + Show the current state of symbol file debugging messages. + +'set debug symtab-create' + Turns on or off display of debugging messages related to symbol + table creation. The default is 0 (off). A value of 1 provides + basic information. A value greater than 1 provides more verbose + information. +'show debug symtab-create' + Show the current state of symbol table creation debugging. + +'set debug target' + Turns on or off display of GDB target debugging info. This info + includes what is going on at the target level of GDB, as it + happens. The default is 0. Set it to 1 to track events, and to 2 + to also track the value of large memory transfers. +'show debug target' + Displays the current state of displaying GDB target debugging info. + +'set debug timestamp' + Turns on or off display of timestamps with GDB debugging info. + When enabled, seconds and microseconds are displayed before each + debugging message. +'show debug timestamp' + Displays the current state of displaying timestamps with GDB + debugging info. + +'set debug varobj' + Turns on or off display of GDB variable object debugging info. The + default is off. +'show debug varobj' + Displays the current state of displaying GDB variable object + debugging info. + +'set debug xml' + Turn on or off debugging messages for built-in XML parsers. +'show debug xml' + Displays the current state of XML debugging messages. + +'set debug breakpoints' + Turns on or off display of GDB debugging info for breakpoint + insertion and removal. The default is off. +'show debug breakpoints' + Displays the current state of displaying GDB debugging info for + breakpoint insertion and removal. + + +File: gdb.info, Node: Other Misc Settings, Prev: Debugging Output, Up: Controlling GDB + +22.11 Other Miscellaneous Settings +================================== + +'set interactive-mode' + If 'on', forces GDB to assume that GDB was started in a terminal. + In practice, this means that GDB should wait for the user to answer + queries generated by commands entered at the command prompt. If + 'off', forces GDB to operate in the opposite mode, and it uses the + default answers to all queries. If 'auto' (the default), GDB tries + to determine whether its standard input is a terminal, and works in + interactive-mode if it is, non-interactively otherwise. + + In the vast majority of cases, the debugger should be able to guess + correctly which mode should be used. But this setting can be + useful in certain specific cases, such as running a MinGW GDB + inside a cygwin window. + +'show interactive-mode' + Displays whether the debugger is operating in interactive mode or + not. + +'set suppress-cli-notifications' + If 'on', command-line-interface (CLI) notifications that are + printed by GDB are suppressed. If 'off', the notifications are + printed as usual. The default value is 'off'. CLI notifications + occur when you change the selected context or when the program + being debugged stops, as detailed below. + + _User-selected context changes:_ + When you change the selected context (i.e. the current + inferior, thread and/or the frame), GDB prints information + about the new context. For example, the default behavior is + below: + + (gdb) inferior 1 + [Switching to inferior 1 [process 634] (/tmp/test)] + [Switching to thread 1 (process 634)] + #0 main () at test.c:3 + 3 return 0; + (gdb) + + When the notifications are suppressed, the new context is not + printed: + + (gdb) set suppress-cli-notifications on + (gdb) inferior 1 + (gdb) + + _The program being debugged stops:_ + When the program you are debugging stops (e.g. because of + hitting a breakpoint, completing source-stepping, an + interrupt, etc.), GDB prints information about the stop event. + For example, below is a breakpoint hit: + + (gdb) break test.c:3 + Breakpoint 2 at 0x555555555155: file test.c, line 3. + (gdb) continue + Continuing. + + Breakpoint 2, main () at test.c:3 + 3 return 0; + (gdb) + + When the notifications are suppressed, the output becomes: + + (gdb) break test.c:3 + Breakpoint 2 at 0x555555555155: file test.c, line 3. + (gdb) set suppress-cli-notifications on + (gdb) continue + Continuing. + (gdb) + + Suppressing CLI notifications may be useful in scripts to + obtain a reduced output from a list of commands. + +'show suppress-cli-notifications' + Displays whether printing CLI notifications is suppressed or not. + + +File: gdb.info, Node: Extending GDB, Next: Interpreters, Prev: Controlling GDB, Up: Top + +23 Extending GDB +**************** + +GDB provides several mechanisms for extension. GDB also provides the +ability to automatically load extensions when it reads a file for +debugging. This allows the user to automatically customize GDB for the +program being debugged. + + To facilitate the use of extension languages, GDB is capable of +evaluating the contents of a file. When doing so, GDB can recognize +which extension language is being used by looking at the filename +extension. Files with an unrecognized filename extension are always +treated as a GDB Command Files. *Note Command files: Command Files. + + You can control how GDB evaluates these files with the following +setting: + +'set script-extension off' + All scripts are always evaluated as GDB Command Files. + +'set script-extension soft' + The debugger determines the scripting language based on filename + extension. If this scripting language is supported, GDB evaluates + the script using that language. Otherwise, it evaluates the file + as a GDB Command File. + +'set script-extension strict' + The debugger determines the scripting language based on filename + extension, and evaluates the script using that language. If the + language is not supported, then the evaluation fails. + +'show script-extension' + Display the current value of the 'script-extension' option. + +* Menu: + +* Sequences:: Canned Sequences of GDB Commands +* Aliases:: Command Aliases +* Python:: Extending GDB using Python +* Guile:: Extending GDB using Guile +* Auto-loading extensions:: Automatically loading extensions +* Multiple Extension Languages:: Working with multiple extension languages + + +File: gdb.info, Node: Sequences, Next: Aliases, Up: Extending GDB + +23.1 Canned Sequences of Commands +================================= + +Aside from breakpoint commands (*note Breakpoint Command Lists: Break +Commands.), GDB provides two ways to store sequences of commands for +execution as a unit: user-defined commands and command files. + +* Menu: + +* Define:: How to define your own commands +* Hooks:: Hooks for user-defined commands +* Command Files:: How to write scripts of commands to be stored in a file +* Output:: Commands for controlled output +* Auto-loading sequences:: Controlling auto-loaded command files + + +File: gdb.info, Node: Define, Next: Hooks, Up: Sequences + +23.1.1 User-defined Commands +---------------------------- + +A "user-defined command" is a sequence of GDB commands to which you +assign a new name as a command. This is done with the 'define' command. + + User commands may accept an unlimited number of arguments separated +by whitespace. Arguments are accessed within the user command via +'$arg0...$argN'. The arguments are text substitutions, so they may +reference variables, use complex expressions, or even perform inferior +functions calls. Note, however, that this textual substitution means +that working with certain arguments is difficult. For example, there is +no way for the user to pass an argument containing a space; and while +stringifying an argument can be done using an expression like '"$arg1"', +this will fail if the argument contains a quote. For more complicated +and robust commands, we recommend writing them in Python; see *note CLI +Commands In Python::. + + A trivial example: + + define adder + print $arg0 + $arg1 + $arg2 + end + +To execute the command use: + + adder 1 2 3 + +This defines the command 'adder', which prints the sum of its three +arguments. + + In addition, '$argc' may be used to find out how many arguments have +been passed. + + define adder + if $argc == 2 + print $arg0 + $arg1 + end + if $argc == 3 + print $arg0 + $arg1 + $arg2 + end + end + + Combining with the 'eval' command (*note eval::) makes it easier to +process a variable number of arguments: + + define adder + set $i = 0 + set $sum = 0 + while $i < $argc + eval "set $sum = $sum + $arg%d", $i + set $i = $i + 1 + end + print $sum + end + +'define COMMANDNAME' + Define a command named COMMANDNAME. If there is already a command + by that name, you are asked to confirm that you want to redefine + it. The argument COMMANDNAME may be a bare command name consisting + of letters, numbers, dashes, dots, and underscores. It may also + start with any predefined or user-defined prefix command. For + example, 'define target my-target' creates a user-defined 'target + my-target' command. + + The definition of the command is made up of other GDB command + lines, which are given following the 'define' command. The end of + these commands is marked by a line containing 'end'. + +'document COMMANDNAME' + Document the user-defined command COMMANDNAME, so that it can be + accessed by 'help'. The command COMMANDNAME must already be + defined. This command reads lines of documentation just as + 'define' reads the lines of the command definition, ending with + 'end'. After the 'document' command is finished, 'help' on command + COMMANDNAME displays the documentation you have written. + + You may use the 'document' command again to change the + documentation of a command. Redefining the command with 'define' + does not change the documentation. + + It is also possible to document user-defined aliases. The alias + documentation will then be used by the 'help' and 'apropos' + commands instead of the documentation of the aliased command. + Documenting a user-defined alias is particularly useful when + defining an alias as a set of nested 'with' commands (*note Command + aliases default args::). + +'define-prefix COMMANDNAME' + Define or mark the command COMMANDNAME as a user-defined prefix + command. Once marked, COMMANDNAME can be used as prefix command by + the 'define' command. Note that 'define-prefix' can be used with a + not yet defined COMMANDNAME. In such a case, COMMANDNAME is + defined as an empty user-defined command. In case you redefine a + command that was marked as a user-defined prefix command, the + subcommands of the redefined command are kept (and GDB indicates so + to the user). + + Example: + (gdb) define-prefix abc + (gdb) define-prefix abc def + (gdb) define abc def + Type commands for definition of "abc def". + End with a line saying just "end". + >echo command initial def\n + >end + (gdb) define abc def ghi + Type commands for definition of "abc def ghi". + End with a line saying just "end". + >echo command ghi\n + >end + (gdb) define abc def + Keeping subcommands of prefix command "def". + Redefine command "def"? (y or n) y + Type commands for definition of "abc def". + End with a line saying just "end". + >echo command def\n + >end + (gdb) abc def ghi + command ghi + (gdb) abc def + command def + (gdb) + +'dont-repeat' + Used inside a user-defined command, this tells GDB that this + command should not be repeated when the user hits (*note + repeat last command: Command Syntax.). + +'help user-defined' + List all user-defined commands and all python commands defined in + class COMMAND_USER. The first line of the documentation or + docstring is included (if any). + +'show user' +'show user COMMANDNAME' + Display the GDB commands used to define COMMANDNAME (but not its + documentation). If no COMMANDNAME is given, display the + definitions for all user-defined commands. This does not work for + user-defined python commands. + +'show max-user-call-depth' +'set max-user-call-depth' + The value of 'max-user-call-depth' controls how many recursion + levels are allowed in user-defined commands before GDB suspects an + infinite recursion and aborts the command. This does not apply to + user-defined python commands. + + In addition to the above commands, user-defined commands frequently +use control flow commands, described in *note Command Files::. + + When user-defined commands are executed, the commands of the +definition are not printed. An error in any command stops execution of +the user-defined command. + + If used interactively, commands that would ask for confirmation +proceed without asking when used inside a user-defined command. Many +GDB commands that normally print messages to say what they are doing +omit the messages when used in a user-defined command. + + +File: gdb.info, Node: Hooks, Next: Command Files, Prev: Define, Up: Sequences + +23.1.2 User-defined Command Hooks +--------------------------------- + +You may define "hooks", which are a special kind of user-defined +command. Whenever you run the command 'foo', if the user-defined +command 'hook-foo' exists, it is executed (with no arguments) before +that command. + + A hook may also be defined which is run after the command you +executed. Whenever you run the command 'foo', if the user-defined +command 'hookpost-foo' exists, it is executed (with no arguments) after +that command. Post-execution hooks may exist simultaneously with +pre-execution hooks, for the same command. + + It is valid for a hook to call the command which it hooks. If this +occurs, the hook is not re-executed, thereby avoiding infinite +recursion. + + In addition, a pseudo-command, 'stop' exists. Defining ('hook-stop') +makes the associated commands execute every time execution stops in your +program: before breakpoint commands are run, displays are printed, or +the stack frame is printed. + + For example, to ignore 'SIGALRM' signals while single-stepping, but +treat them normally during normal execution, you could define: + + define hook-stop + handle SIGALRM nopass + end + + define hook-run + handle SIGALRM pass + end + + define hook-continue + handle SIGALRM pass + end + + As a further example, to hook at the beginning and end of the 'echo' +command, and to add extra text to the beginning and end of the message, +you could define: + + define hook-echo + echo <<<--- + end + + define hookpost-echo + echo --->>>\n + end + + (gdb) echo Hello World + <<<---Hello World--->>> + (gdb) + + + You can define a hook for any single-word command in GDB, but not for +command aliases; you should define a hook for the basic command name, +e.g. 'backtrace' rather than 'bt'. You can hook a multi-word command by +adding 'hook-' or 'hookpost-' to the last word of the command, e.g. +'define target hook-remote' to add a hook to 'target remote'. + + If an error occurs during the execution of your hook, execution of +GDB commands stops and GDB issues a prompt (before the command that you +actually typed had a chance to run). + + If you try to define a hook which does not match any known command, +you get a warning from the 'define' command. + + +File: gdb.info, Node: Command Files, Next: Output, Prev: Hooks, Up: Sequences + +23.1.3 Command Files +-------------------- + +A command file for GDB is a text file made of lines that are GDB +commands. Comments (lines starting with '#') may also be included. An +empty line in a command file does nothing; it does not mean to repeat +the last command, as it would from the terminal. + + You can request the execution of a command file with the 'source' +command. Note that the 'source' command is also used to evaluate +scripts that are not Command Files. The exact behavior can be +configured using the 'script-extension' setting. *Note Extending GDB: +Extending GDB. + +'source [-s] [-v] FILENAME' + Execute the command file FILENAME. + + The lines in a command file are generally executed sequentially, +unless the order of execution is changed by one of the _flow-control +commands_ described below. The commands are not printed as they are +executed. An error in any command terminates execution of the command +file and control is returned to the console. + + GDB first searches for FILENAME in the current directory. If the +file is not found there, and FILENAME does not specify a directory, then +GDB also looks for the file on the source search path (specified with +the 'directory' command); except that '$cdir' is not searched because +the compilation directory is not relevant to scripts. + + If '-s' is specified, then GDB searches for FILENAME on the search +path even if FILENAME specifies a directory. The search is done by +appending FILENAME to each element of the search path. So, for example, +if FILENAME is 'mylib/myscript' and the search path contains +'/home/user' then GDB will look for the script +'/home/user/mylib/myscript'. The search is also done if FILENAME is an +absolute path. For example, if FILENAME is '/tmp/myscript' and the +search path contains '/home/user' then GDB will look for the script +'/home/user/tmp/myscript'. For DOS-like systems, if FILENAME contains a +drive specification, it is stripped before concatenation. For example, +if FILENAME is 'd:myscript' and the search path contains 'c:/tmp' then +GDB will look for the script 'c:/tmp/myscript'. + + If '-v', for verbose mode, is given then GDB displays each command as +it is executed. The option must be given before FILENAME, and is +interpreted as part of the filename anywhere else. + + Commands that would ask for confirmation if used interactively +proceed without asking when used in a command file. Many GDB commands +that normally print messages to say what they are doing omit the +messages when called from command files. + + GDB also accepts command input from standard input. In this mode, +normal output goes to standard output and error output goes to standard +error. Errors in a command file supplied on standard input do not +terminate execution of the command file--execution continues with the +next command. + + gdb < cmds > log 2>&1 + + (The syntax above will vary depending on the shell used.) This +example will execute commands from the file 'cmds'. All output and +errors would be directed to 'log'. + + Since commands stored on command files tend to be more general than +commands typed interactively, they frequently need to deal with +complicated situations, such as different or unexpected values of +variables and symbols, changes in how the program being debugged is +built, etc. GDB provides a set of flow-control commands to deal with +these complexities. Using these commands, you can write complex scripts +that loop over data structures, execute commands conditionally, etc. + +'if' +'else' + This command allows to include in your script conditionally + executed commands. The 'if' command takes a single argument, which + is an expression to evaluate. It is followed by a series of + commands that are executed only if the expression is true (its + value is nonzero). There can then optionally be an 'else' line, + followed by a series of commands that are only executed if the + expression was false. The end of the list is marked by a line + containing 'end'. + +'while' + This command allows to write loops. Its syntax is similar to 'if': + the command takes a single argument, which is an expression to + evaluate, and must be followed by the commands to execute, one per + line, terminated by an 'end'. These commands are called the "body" + of the loop. The commands in the body of 'while' are executed + repeatedly as long as the expression evaluates to true. + +'loop_break' + This command exits the 'while' loop in whose body it is included. + Execution of the script continues after that 'while's 'end' line. + +'loop_continue' + This command skips the execution of the rest of the body of + commands in the 'while' loop in whose body it is included. + Execution branches to the beginning of the 'while' loop, where it + evaluates the controlling expression. + +'end' + Terminate the block of commands that are the body of 'if', 'else', + or 'while' flow-control commands. + + +File: gdb.info, Node: Output, Next: Auto-loading sequences, Prev: Command Files, Up: Sequences + +23.1.4 Commands for Controlled Output +------------------------------------- + +During the execution of a command file or a user-defined command, normal +GDB output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. + +'echo TEXT' + Print TEXT. Nonprinting characters can be included in TEXT using C + escape sequences, such as '\n' to print a newline. *No newline is + printed unless you specify one.* In addition to the standard C + escape sequences, a backslash followed by a space stands for a + space. This is useful for displaying a string with spaces at the + beginning or the end, since leading and trailing spaces are + otherwise trimmed from all arguments. To print ' and foo = ', use + the command 'echo \ and foo = \ '. + + A backslash at the end of TEXT can be used, as in C, to continue + the command onto subsequent lines. For example, + + echo This is some text\n\ + which is continued\n\ + onto several lines.\n + + produces the same output as + + echo This is some text\n + echo which is continued\n + echo onto several lines.\n + +'output EXPRESSION' + Print the value of EXPRESSION and nothing but that value: no + newlines, no '$NN = '. The value is not entered in the value + history either. *Note Expressions: Expressions, for more + information on expressions. + +'output/FMT EXPRESSION' + Print the value of EXPRESSION in format FMT. You can use the same + formats as for 'print'. *Note Output Formats: Output Formats, for + more information. + +'printf TEMPLATE, EXPRESSIONS...' + Print the values of one or more EXPRESSIONS under the control of + the string TEMPLATE. To print several values, make EXPRESSIONS be + a comma-separated list of individual expressions, which may be + either numbers or pointers. Their values are printed as specified + by TEMPLATE, exactly as a C program would do by executing the code + below: + + printf (TEMPLATE, EXPRESSIONS...); + + As in 'C' 'printf', ordinary characters in TEMPLATE are printed + verbatim, while "conversion specification" introduced by the '%' + character cause subsequent EXPRESSIONS to be evaluated, their + values converted and formatted according to type and style + information encoded in the conversion specifications, and then + printed. + + For example, you can print two values in hex like this: + + printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo + + 'printf' supports all the standard 'C' conversion specifications, + including the flags and modifiers between the '%' character and the + conversion letter, with the following exceptions: + + * The argument-ordering modifiers, such as '2$', are not + supported. + + * The modifier '*' is not supported for specifying precision or + width. + + * The ''' flag (for separation of digits into groups according + to 'LC_NUMERIC'') is not supported. + + * The type modifiers 'hh', 'j', 't', and 'z' are not supported. + + * The conversion letter 'n' (as in '%n') is not supported. + + * The conversion letters 'a' and 'A' are not supported. + + Note that the 'll' type modifier is supported only if the + underlying 'C' implementation used to build GDB supports the 'long + long int' type, and the 'L' type modifier is supported only if + 'long double' type is available. + + As in 'C', 'printf' supports simple backslash-escape sequences, + such as '\n', '\t', '\\', '\"', '\a', and '\f', that consist of + backslash followed by a single character. Octal and hexadecimal + escape sequences are not supported. + + Additionally, 'printf' supports conversion specifications for DFP + ("Decimal Floating Point") types using the following length + modifiers together with a floating point specifier. letters: + + * 'H' for printing 'Decimal32' types. + + * 'D' for printing 'Decimal64' types. + + * 'DD' for printing 'Decimal128' types. + + If the underlying 'C' implementation used to build GDB has support + for the three length modifiers for DFP types, other modifiers such + as width and precision will also be available for GDB to use. + + In case there is no such 'C' support, no additional modifiers will + be available and the value will be printed in the standard way. + + Here's an example of printing DFP types using the above conversion + letters: + printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl + + Additionally, 'printf' supports a special '%V' output format. This + format prints the string representation of an expression just as + GDB would produce with the standard 'print' command (*note + Examining Data: Data.): + + (gdb) print array + $1 = {0, 1, 2, 3, 4, 5} + (gdb) printf "Array is: %V\n", array + Array is: {0, 1, 2, 3, 4, 5} + + It is possible to include print options with the '%V' format by + placing them in '[...]' immediately after the '%V', like this: + + (gdb) printf "Array is: %V[-array-indexes on]\n", array + Array is: {[0] = 0, [1] = 1, [2] = 2, [3] = 3, [4] = 4, [5] = 5} + + If you need to print a literal '[' directly after a '%V', then just + include an empty print options list: + + (gdb) printf "Array is: %V[][Hello]\n", array + Array is: {0, 1, 2, 3, 4, 5}[Hello] + +'eval TEMPLATE, EXPRESSIONS...' + Convert the values of one or more EXPRESSIONS under the control of + the string TEMPLATE to a command line, and call it. + + +File: gdb.info, Node: Auto-loading sequences, Prev: Output, Up: Sequences + +23.1.5 Controlling auto-loading native GDB scripts +-------------------------------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +the command file 'OBJFILE-gdb.gdb'. *Note Auto-loading extensions::. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load gdb-scripts [on|off]' + Enable or disable the auto-loading of canned sequences of commands + scripts. + +'show auto-load gdb-scripts' + Show whether auto-loading of canned sequences of commands scripts + is enabled or disabled. + +'info auto-load gdb-scripts [REGEXP]' + Print the list of all canned sequences of commands scripts that GDB + auto-loaded. + + If REGEXP is supplied only canned sequences of commands scripts with +matching names are printed. + + +File: gdb.info, Node: Aliases, Next: Python, Prev: Sequences, Up: Extending GDB + +23.2 Command Aliases +==================== + +Aliases allow you to define alternate spellings for existing commands. +For example, if a new GDB command defined in Python (*note Python::) has +a long name, it is handy to have an abbreviated version of it that +involves less typing. + + GDB itself uses aliases. For example 's' is an alias of the 'step' +command even though it is otherwise an ambiguous abbreviation of other +commands like 'set' and 'show'. + + Aliases are also used to provide shortened or more common versions of +multi-word commands. For example, GDB provides the 'tty' alias of the +'set inferior-tty' command. + + You can define a new alias with the 'alias' command. + +'alias [-a] [--] ALIAS = COMMAND [DEFAULT-ARGS]' + + ALIAS specifies the name of the new alias. Each word of ALIAS must +consist of letters, numbers, dashes and underscores. + + COMMAND specifies the name of an existing command that is being +aliased. + + COMMAND can also be the name of an existing alias. In this case, +COMMAND cannot be an alias that has default arguments. + + The '-a' option specifies that the new alias is an abbreviation of +the command. Abbreviations are not used in command completion. + + The '--' option specifies the end of options, and is useful when +ALIAS begins with a dash. + + You can specify DEFAULT-ARGS for your alias. These DEFAULT-ARGS will +be automatically added before the alias arguments typed explicitly on +the command line. + + For example, the below defines an alias 'btfullall' that shows all +local variables and all frame arguments: + (gdb) alias btfullall = backtrace -full -frame-arguments all + + For more information about DEFAULT-ARGS, see *note Default Arguments: +Command aliases default args. + + Here is a simple example showing how to make an abbreviation of a +command so that there is less to type. Suppose you were tired of typing +'disas', the current shortest unambiguous abbreviation of the +'disassemble' command and you wanted an even shorter version named 'di'. +The following will accomplish this. + + (gdb) alias -a di = disas + + Note that aliases are different from user-defined commands. With a +user-defined command, you also need to write documentation for it with +the 'document' command. An alias automatically picks up the +documentation of the existing command. + + Here is an example where we make 'elms' an abbreviation of 'elements' +in the 'set print elements' command. This is to show that you can make +an abbreviation of any part of a command. + + (gdb) alias -a set print elms = set print elements + (gdb) alias -a show print elms = show print elements + (gdb) set p elms 200 + (gdb) show p elms + Limit on string chars or array elements to print is 200. + + Note that if you are defining an alias of a 'set' command, and you +want to have an alias for the corresponding 'show' command, then you +need to define the latter separately. + + Unambiguously abbreviated commands are allowed in COMMAND and ALIAS, +just as they are normally. + + (gdb) alias -a set pr elms = set p ele + + Finally, here is an example showing the creation of a one word alias +for a more complex command. This creates alias 'spe' of the command +'set print elements'. + + (gdb) alias spe = set print elements + (gdb) spe 20 + +* Menu: + +* Command aliases default args:: Default arguments for aliases + + +File: gdb.info, Node: Command aliases default args, Up: Aliases + +23.2.1 Default Arguments +------------------------ + +You can tell GDB to always prepend some default arguments to the list of +arguments provided explicitly by the user when using a user-defined +alias. + + If you repeatedly use the same arguments or options for a command, +you can define an alias for this command and tell GDB to automatically +prepend these arguments or options to the list of arguments you type +explicitly when using the alias(1). + + For example, if you often use the command 'thread apply all' +specifying to work on the threads in ascending order and to continue in +case it encounters an error, you can tell GDB to automatically preprend +the '-ascending' and '-c' options by using: + + (gdb) alias thread apply asc-all = thread apply all -ascending -c + + Once you have defined this alias with its default args, any time you +type the 'thread apply asc-all' followed by 'some arguments', GDB will +execute 'thread apply all -ascending -c some arguments'. + + To have even less to type, you can also define a one word alias: + (gdb) alias t_a_c = thread apply all -ascending -c + + As usual, unambiguous abbreviations can be used for ALIAS and +DEFAULT-ARGS. + + The different aliases of a command do not share their default args. +For example, you define a new alias 'bt_ALL' showing all possible +information and another alias 'bt_SMALL' showing very limited +information using: + (gdb) alias bt_ALL = backtrace -entry-values both -frame-arg all \ + -past-main -past-entry -full + (gdb) alias bt_SMALL = backtrace -entry-values no -frame-arg none \ + -past-main off -past-entry off + + (For more on using the 'alias' command, see *note Aliases::.) + + Default args are not limited to the arguments and options of COMMAND, +but can specify nested commands if COMMAND accepts such a nested command +as argument. For example, the below defines 'faalocalsoftype' that +lists the frames having locals of a certain type, together with the +matching local vars: + (gdb) alias faalocalsoftype = frame apply all info locals -q -t + (gdb) faalocalsoftype int + #1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86 + i = 0 + ret = 21845 + + This is also very useful to define an alias for a set of nested +'with' commands to have a particular combination of temporary settings. +For example, the below defines the alias 'pp10' that pretty prints an +expression argument, with a maximum of 10 elements if the expression is +a string or an array: + (gdb) alias pp10 = with print pretty -- with print elements 10 -- print + This defines the alias 'pp10' as being a sequence of 3 commands. The +first part 'with print pretty --' temporarily activates the setting 'set +print pretty', then launches the command that follows the separator +'--'. The command following the first part is also a 'with' command +that temporarily changes the setting 'set print elements' to 10, then +launches the command that follows the second separator '--'. The third +part 'print' is the command the 'pp10' alias will launch, using the +temporary values of the settings and the arguments explicitly given by +the user. For more information about the 'with' command usage, see +*note Command Settings::. + + By default, asking the help for an alias shows the documentation of +the aliased command. When the alias is a set of nested commands, 'help' +of an alias shows the documentation of the first command. This help is +not particularly useful for an alias such as 'pp10'. For such an alias, +it is useful to give a specific documentation using the 'document' +command (*note document: Define.). + + ---------- Footnotes ---------- + + (1) GDB could easily accept default arguments for pre-defined +commands and aliases, but it was deemed this would be confusing, and so +is not allowed. + + +File: gdb.info, Node: Python, Next: Guile, Prev: Aliases, Up: Extending GDB + +23.3 Extending GDB using Python +=============================== + +You can extend GDB using the Python programming language +(http://www.python.org/). This feature is available only if GDB was +configured using '--with-python'. + + Python scripts used by GDB should be installed in +'DATA-DIRECTORY/python', where DATA-DIRECTORY is the data directory as +determined at GDB startup (*note Data Files::). This directory, known +as the "python directory", is automatically added to the Python Search +Path in order to allow the Python interpreter to locate all scripts +installed at this location. + + Additionally, GDB commands and convenience functions which are +written in Python and are located in the +'DATA-DIRECTORY/python/gdb/command' or +'DATA-DIRECTORY/python/gdb/function' directories are automatically +imported when GDB starts. + +* Menu: + +* Python Commands:: Accessing Python from GDB. +* Python API:: Accessing GDB from Python. +* Python Auto-loading:: Automatically loading Python code. +* Python modules:: Python modules provided by GDB. + + +File: gdb.info, Node: Python Commands, Next: Python API, Up: Python + +23.3.1 Python Commands +---------------------- + +GDB provides two commands for accessing the Python interpreter, and one +related setting: + +'python-interactive [COMMAND]' +'pi [COMMAND]' + Without an argument, the 'python-interactive' command can be used + to start an interactive Python prompt. To return to GDB, type the + 'EOF' character (e.g., 'Ctrl-D' on an empty prompt). + + Alternatively, a single-line Python command can be given as an + argument and evaluated. If the command is an expression, the + result will be printed; otherwise, nothing will be printed. For + example: + + (gdb) python-interactive 2 + 3 + 5 + +'python [COMMAND]' +'py [COMMAND]' + The 'python' command can be used to evaluate Python code. + + If given an argument, the 'python' command will evaluate the + argument as a Python command. For example: + + (gdb) python print 23 + 23 + + If you do not provide an argument to 'python', it will act as a + multi-line command, like 'define'. In this case, the Python script + is made up of subsequent command lines, given after the 'python' + command. This command list is terminated using a line containing + 'end'. For example: + + (gdb) python + >print 23 + >end + 23 + +'set python print-stack' + By default, GDB will print only the message component of a Python + exception when an error occurs in a Python script. This can be + controlled using 'set python print-stack': if 'full', then full + Python stack printing is enabled; if 'none', then Python stack and + message printing is disabled; if 'message', the default, only the + message component of the error is printed. + +'set python ignore-environment [on|off]' + By default this option is 'off', and, when GDB initializes its + internal Python interpreter, the Python interpreter will check the + environment for variables that will effect how it behaves, for + example 'PYTHONHOME', and 'PYTHONPATH'(1). + + If this option is set to 'on' before Python is initialized then + Python will ignore all such environment variables. As Python is + initialized early during GDB's startup process, then this option + must be placed into the early initialization file (*note + Initialization Files::) to have the desired effect. + + This option is equivalent to passing '-E' to the real 'python' + executable. + +'set python dont-write-bytecode [auto|on|off]' + When this option is 'off', then, once GDB has initialized the + Python interpreter, the interpreter will byte-compile any Python + modules that it imports and write the byte code to disk in '.pyc' + files. + + If this option is set to 'on' before Python is initialized then + Python will no longer write the byte code to disk. As Python is + initialized early during GDB's startup process, then this option + must be placed into the early initialization file (*note + Initialization Files::) to have the desired effect. + + By default this option is set to 'auto'. In this mode, provided + the 'python ignore-environment' setting is 'off', the environment + variable 'PYTHONDONTWRITEBYTECODE' is examined to see if it should + write out byte-code or not. 'PYTHONDONTWRITEBYTECODE' is + considered to be off/disabled either when set to the empty string + or when the environment variable doesn't exist. All other + settings, including those which don't seem to make sense, indicate + that it's on/enabled. + + This option is equivalent to passing '-B' to the real 'python' + executable. + + It is also possible to execute a Python script from the GDB +interpreter: + +'source script-name' + The script name must end with '.py' and GDB must be configured to + recognize the script language based on filename extension using the + 'script-extension' setting. *Note Extending GDB: Extending GDB. + + The following commands are intended to help debug GDB itself: + +'set debug py-breakpoint on|off' +'show debug py-breakpoint' + When 'on', GDB prints debug messages related to the Python + breakpoint API. This is 'off' by default. + +'set debug py-unwind on|off' +'show debug py-unwind' + When 'on', GDB prints debug messages related to the Python unwinder + API. This is 'off' by default. + + ---------- Footnotes ---------- + + (1) See the ENVIRONMENT VARIABLES section of 'man 1 python' for a +comprehensive list. + + +File: gdb.info, Node: Python API, Next: Python Auto-loading, Prev: Python Commands, Up: Python + +23.3.2 Python API +----------------- + +You can get quick online help for GDB's Python API by issuing the +command 'python help (gdb)'. + + Functions and methods which have two or more optional arguments allow +them to be specified using keyword syntax. This allows passing some +optional arguments while skipping others. Example: +'gdb.some_function ('foo', bar = 1, baz = 2)'. + +* Menu: + +* Basic Python:: Basic Python Functions. +* Threading in GDB:: Using Python threads in GDB. +* Exception Handling:: How Python exceptions are translated. +* Values From Inferior:: Python representation of values. +* Types In Python:: Python representation of types. +* Pretty Printing API:: Pretty-printing values. +* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. +* Writing a Pretty-Printer:: Writing a Pretty-Printer. +* Type Printing API:: Pretty-printing types. +* Frame Filter API:: Filtering Frames. +* Frame Decorator API:: Decorating Frames. +* Writing a Frame Filter:: Writing a Frame Filter. +* Unwinding Frames in Python:: Writing frame unwinder. +* Xmethods In Python:: Adding and replacing methods of C++ classes. +* Xmethod API:: Xmethod types. +* Writing an Xmethod:: Writing an xmethod. +* Inferiors In Python:: Python representation of inferiors (processes) +* Events In Python:: Listening for events from GDB. +* Threads In Python:: Accessing inferior threads from Python. +* Recordings In Python:: Accessing recordings from Python. +* CLI Commands In Python:: Implementing new CLI commands in Python. +* GDB/MI Commands In Python:: Implementing new GDB/MI commands in Python. +* GDB/MI Notifications In Python:: Implementing new GDB/MI notifications in Python. +* Parameters In Python:: Adding new GDB parameters. +* Functions In Python:: Writing new convenience functions. +* Progspaces In Python:: Program spaces. +* Objfiles In Python:: Object files. +* Frames In Python:: Accessing inferior stack frames from Python. +* Blocks In Python:: Accessing blocks from Python. +* Symbols In Python:: Python representation of symbols. +* Symbol Tables In Python:: Python representation of symbol tables. +* Line Tables In Python:: Python representation of line tables. +* Breakpoints In Python:: Manipulating breakpoints using Python. +* Finish Breakpoints in Python:: Setting Breakpoints on function return + using Python. +* Lazy Strings In Python:: Python representation of lazy strings. +* Architectures In Python:: Python representation of architectures. +* Registers In Python:: Python representation of registers. +* Connections In Python:: Python representation of connections. +* TUI Windows In Python:: Implementing new TUI windows. +* Disassembly In Python:: Instruction Disassembly In Python +* Missing Debug Info In Python:: Handle missing debug info from Python. +* Missing Objfiles In Python:: Handle objfiles from Python. + + +File: gdb.info, Node: Basic Python, Next: Threading in GDB, Up: Python API + +23.3.2.1 Basic Python +..................... + +At startup, GDB overrides Python's 'sys.stdout' and 'sys.stderr' to +print using GDB's output-paging streams. A Python program which outputs +to one of these streams may have its output interrupted by the user +(*note Screen Size::). In this situation, a Python 'KeyboardInterrupt' +exception is thrown. + + Some care must be taken when writing Python code to run in GDB. Two +things worth noting in particular: + + * GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Python code must + not override these, or even change the options using 'sigaction'. + If your program changes the handling of these signals, GDB will + most likely stop working correctly. Note that it is unfortunately + common for GUI toolkits to install a 'SIGCHLD' handler. When + creating a new Python thread, you can use 'gdb.block_signals' or + 'gdb.Thread' to handle this correctly; see *note Threading in + GDB::. + + * GDB takes care to mark its internal file descriptors as + close-on-exec. However, this cannot be done in a thread-safe way + on all platforms. Your Python programs should be aware of this and + should both create new file descriptors with the close-on-exec flag + set and arrange to close unneeded file descriptors before starting + a child process. + + GDB introduces a new Python module, named 'gdb'. All methods and +classes added by GDB are placed in this module. GDB automatically +'import's the 'gdb' module for use in all scripts evaluated by the +'python' command. + + Some types of the 'gdb' module come with a textual representation +(accessible through the 'repr' or 'str' functions). These are offered +for debugging purposes only, expect them to change over time. + + -- Variable: gdb.PYTHONDIR + A string containing the python directory (*note Python::). + + -- Function: gdb.execute (command [, from_tty [, to_string]]) + Evaluate COMMAND, a string, as a GDB CLI command. If a GDB + exception happens while COMMAND runs, it is translated as described + in *note Exception Handling: Exception Handling. + + The FROM_TTY flag specifies whether GDB ought to consider this + command as having originated from the user invoking it + interactively. It must be a boolean value. If omitted, it + defaults to 'False'. + + By default, any output produced by COMMAND is sent to GDB's + standard output (and to the log output if logging is turned on). + If the TO_STRING parameter is 'True', then output will be collected + by 'gdb.execute' and returned as a string. The default is 'False', + in which case the return value is 'None'. If TO_STRING is 'True', + the GDB virtual terminal will be temporarily set to unlimited width + and height, and its pagination will be disabled; *note Screen + Size::. + + -- Function: gdb.breakpoints () + Return a sequence holding all of GDB's breakpoints. *Note + Breakpoints In Python::, for more information. In GDB version 7.11 + and earlier, this function returned 'None' if there were no + breakpoints. This peculiarity was subsequently fixed, and now + 'gdb.breakpoints' returns an empty sequence in this case. + + -- Function: gdb.rbreak (regex [, minsyms [, throttle, [, symtabs ]]]) + Return a Python list holding a collection of newly set + 'gdb.Breakpoint' objects matching function names defined by the + REGEX pattern. If the MINSYMS keyword is 'True', all system + functions (those not explicitly defined in the inferior) will also + be included in the match. The THROTTLE keyword takes an integer + that defines the maximum number of pattern matches for functions + matched by the REGEX pattern. If the number of matches exceeds the + integer value of THROTTLE, a 'RuntimeError' will be raised and no + breakpoints will be created. If THROTTLE is not defined then there + is no imposed limit on the maximum number of matches and + breakpoints to be created. The SYMTABS keyword takes a Python + iterable that yields a collection of 'gdb.Symtab' objects and will + restrict the search to those functions only contained within the + 'gdb.Symtab' objects. + + -- Function: gdb.parameter (parameter) + Return the value of a GDB PARAMETER given by its name, a string; + the parameter name string may contain spaces if the parameter has a + multi-part name. For example, 'print object' is a valid parameter + name. + + If the named parameter does not exist, this function throws a + 'gdb.error' (*note Exception Handling::). Otherwise, the + parameter's value is converted to a Python value of the appropriate + type, and returned. + + -- Function: gdb.set_parameter (name, value) + Sets the gdb parameter NAME to VALUE. As with 'gdb.parameter', the + parameter name string may contain spaces if the parameter has a + multi-part name. + + -- Function: gdb.with_parameter (name, value) + Create a Python context manager (for use with the Python 'with' + statement) that temporarily sets the gdb parameter NAME to VALUE. + On exit from the context, the previous value will be restored. + + This uses 'gdb.parameter' in its implementation, so it can throw + the same exceptions as that function. + + For example, it's sometimes useful to evaluate some Python code + with a particular gdb language: + + with gdb.with_parameter('language', 'pascal'): + ... language-specific operations + + -- Function: gdb.history (number) + Return a value from GDB's value history (*note Value History::). + The NUMBER argument indicates which history element to return. If + NUMBER is negative, then GDB will take its absolute value and count + backward from the last element (i.e., the most recent element) to + find the value to return. If NUMBER is zero, then GDB will return + the most recent element. If the element specified by NUMBER + doesn't exist in the value history, a 'gdb.error' exception will be + raised. + + If no exception is raised, the return value is always an instance + of 'gdb.Value' (*note Values From Inferior::). + + -- Function: gdb.add_history (value) + Takes VALUE, an instance of 'gdb.Value' (*note Values From + Inferior::), and appends the value this object represents to GDB's + value history (*note Value History::), and return an integer, its + history number. If VALUE is not a 'gdb.Value', it is is converted + using the 'gdb.Value' constructor. If VALUE can't be converted to + a 'gdb.Value' then a 'TypeError' is raised. + + When a command implemented in Python prints a single 'gdb.Value' as + its result, then placing the value into the history will allow the + user convenient access to those values via CLI history facilities. + + -- Function: gdb.history_count () + Return an integer indicating the number of values in GDB's value + history (*note Value History::). + + -- Function: gdb.convenience_variable (name) + Return the value of the convenience variable (*note Convenience + Vars::) named NAME. NAME must be a string. The name should not + include the '$' that is used to mark a convenience variable in an + expression. If the convenience variable does not exist, then + 'None' is returned. + + -- Function: gdb.set_convenience_variable (name, value) + Set the value of the convenience variable (*note Convenience + Vars::) named NAME. NAME must be a string. The name should not + include the '$' that is used to mark a convenience variable in an + expression. If VALUE is 'None', then the convenience variable is + removed. Otherwise, if VALUE is not a 'gdb.Value' (*note Values + From Inferior::), it is is converted using the 'gdb.Value' + constructor. + + -- Function: gdb.parse_and_eval (expression [, global_context]) + Parse EXPRESSION, which must be a string, as an expression in the + current language, evaluate it, and return the result as a + 'gdb.Value'. + + GLOBAL_CONTEXT, if provided, is a boolean indicating whether the + parsing should be done in the global context. The default is + 'False', meaning that the current frame or current static context + should be used. + + This function can be useful when implementing a new command (*note + CLI Commands In Python::, *note GDB/MI Commands In Python::), as it + provides a way to parse the command's argument as an expression. + It is also useful simply to compute values. + + -- Function: gdb.find_pc_line (pc) + Return the 'gdb.Symtab_and_line' object corresponding to the PC + value. *Note Symbol Tables In Python::. If an invalid value of PC + is passed as an argument, then the 'symtab' and 'line' attributes + of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 + respectively. This is identical to + 'gdb.current_progspace().find_pc_line(pc)' and is included for + historical compatibility. + + -- Function: gdb.write (string [, stream]) + Print a string to GDB's paginated output stream. The optional + STREAM determines the stream to print to. The default stream is + GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Writing to 'sys.stdout' or 'sys.stderr' will automatically call + this function and will automatically direct the output to the + relevant stream. + + -- Function: gdb.flush ([, stream]) + Flush the buffer of a GDB paginated stream so that the contents are + displayed immediately. GDB will flush the contents of a stream + automatically when it encounters a newline in the buffer. The + optional STREAM determines the stream to flush. The default stream + is GDB's standard output stream. Possible stream values are: + + 'gdb.STDOUT' + GDB's standard output stream. + + 'gdb.STDERR' + GDB's standard error stream. + + 'gdb.STDLOG' + GDB's log stream (*note Logging Output::). + + Flushing 'sys.stdout' or 'sys.stderr' will automatically call this + function for the relevant stream. + + -- Function: gdb.target_charset () + Return the name of the current target character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-charset')' in that 'auto' is never returned. + + -- Function: gdb.target_wide_charset () + Return the name of the current target wide character set (*note + Character Sets::). This differs from + 'gdb.parameter('target-wide-charset')' in that 'auto' is never + returned. + + -- Function: gdb.host_charset () + Return a string, the name of the current host character set (*note + Character Sets::). This differs from + 'gdb.parameter('host-charset')' in that 'auto' is never returned. + + -- Function: gdb.solib_name (address) + Return the name of the shared library holding the given ADDRESS as + a string, or 'None'. This is identical to + 'gdb.current_progspace().solib_name(address)' and is included for + historical compatibility. + + -- Function: gdb.decode_line ([expression]) + Return locations of the line specified by EXPRESSION, or of the + current line if no argument was given. This function returns a + Python tuple containing two elements. The first element contains a + string holding any unparsed section of EXPRESSION (or 'None' if the + expression has been fully parsed). The second element contains + either 'None' or another tuple that contains all the locations that + match the expression represented as 'gdb.Symtab_and_line' objects + (*note Symbol Tables In Python::). If EXPRESSION is provided, it + is decoded the way that GDB's inbuilt 'break' or 'edit' commands do + (*note Location Specifications::). + + -- Function: gdb.prompt_hook (current_prompt) + + If PROMPT_HOOK is callable, GDB will call the method assigned to + this operation before a prompt is displayed by GDB. + + The parameter 'current_prompt' contains the current GDB prompt. + This method must return a Python string, or 'None'. If a string is + returned, the GDB prompt will be set to that string. If 'None' is + returned, GDB will continue to use the current prompt. + + Some prompts cannot be substituted in GDB. Secondary prompts such + as those used by readline for command input, and annotation related + prompts are prohibited from being changed. + + -- Function: gdb.architecture_names () + Return a list containing all of the architecture names that the + current build of GDB supports. Each architecture name is a string. + The names returned in this list are the same names as are returned + from 'gdb.Architecture.name' (*note Architecture.name: + gdbpy_architecture_name.). + + -- Function: gdb.connections + Return a list of 'gdb.TargetConnection' objects, one for each + currently active connection (*note Connections In Python::). The + connection objects are in no particular order in the returned list. + + -- Function: gdb.format_address (address [, progspace, architecture]) + Return a string in the format 'ADDR ', where ADDR is + ADDRESS formatted in hexadecimal, SYMBOL is the symbol whose + address is the nearest to ADDRESS and below it in memory, and + OFFSET is the offset from SYMBOL to ADDRESS in decimal. + + If no suitable SYMBOL was found, then the part is + not included in the returned string, instead the returned string + will just contain the ADDRESS formatted as hexadecimal. How far + GDB looks back for a suitable symbol can be controlled with 'set + print max-symbolic-offset' (*note Print Settings::). + + Additionally, the returned string can include file name and line + number information when 'set print symbol-filename on' (*note Print + Settings::), in this case the format of the returned string is + 'ADDR at FILENAME:LINE-NUMBER'. + + The PROGSPACE is the gdb.Progspace in which SYMBOL is looked up, + and ARCHITECTURE is used when formatting ADDR, e.g. in order to + determine the size of an address in bytes. + + If neither PROGSPACE or ARCHITECTURE are passed, then by default + GDB will use the program space and architecture of the currently + selected inferior, thus, the following two calls are equivalent: + + gdb.format_address(address) + gdb.format_address(address, + gdb.selected_inferior().progspace, + gdb.selected_inferior().architecture()) + + It is not valid to only pass one of PROGSPACE or ARCHITECTURE, + either they must both be provided, or neither must be provided (and + the defaults will be used). + + This method uses the same mechanism for formatting address, symbol, + and offset information as core GDB does in commands such as + 'disassemble'. + + Here are some examples of the possible string formats: + + 0x00001042 + 0x00001042 + 0x00001042 + + -- Function: gdb.current_language () + Return the name of the current language as a string. Unlike + 'gdb.parameter('language')', this function will never return + 'auto'. If a 'gdb.Frame' object is available (*note Frames In + Python::), the 'language' method might be preferable in some cases, + as that is not affected by the user's language setting. + + +File: gdb.info, Node: Threading in GDB, Next: Exception Handling, Prev: Basic Python, Up: Python API + +23.3.2.2 Threading in GDB +......................... + +GDB is not thread-safe. If your Python program uses multiple threads, +you must be careful to only call GDB-specific functions in the GDB +thread. GDB provides some functions to help with this. + + -- Function: gdb.block_signals () + As mentioned earlier (*note Basic Python::), certain signals must + be delivered to the GDB main thread. The 'block_signals' function + returns a context manager that will block these signals on entry. + This can be used when starting a new thread to ensure that the + signals are blocked there, like: + + with gdb.block_signals(): + start_new_thread() + + -- class: gdb.Thread + This is a subclass of Python's 'threading.Thread' class. It + overrides the 'start' method to call 'block_signals', making this + an easy-to-use drop-in replacement for creating threads that will + work well in GDB. + + -- Function: gdb.interrupt () + This causes GDB to react as if the user had typed a control-C + character at the terminal. That is, if the inferior is running, it + is interrupted; if a GDB command is executing, it is stopped; and + if a Python command is running, 'KeyboardInterrupt' will be raised. + + Unlike most Python APIs in GDB, 'interrupt' is thread-safe. + + -- Function: gdb.post_event (event) + Put EVENT, a callable object taking no arguments, into GDB's + internal event queue. This callable will be invoked at some later + point, during GDB's event processing. Events posted using + 'post_event' will be run in the order in which they were posted; + however, there is no way to know when they will be processed + relative to other events inside GDB. + + Unlike most Python APIs in GDB, 'post_event' is thread-safe. For + example: + + (gdb) python + >import threading + > + >class Writer(): + > def __init__(self, message): + > self.message = message; + > def __call__(self): + > gdb.write(self.message) + > + >class MyThread1 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("Hello ")) + > + >class MyThread2 (threading.Thread): + > def run (self): + > gdb.post_event(Writer("World\n")) + > + >MyThread1().start() + >MyThread2().start() + >end + (gdb) Hello World + + +File: gdb.info, Node: Exception Handling, Next: Values From Inferior, Prev: Threading in GDB, Up: Python API + +23.3.2.3 Exception Handling +........................... + +When executing the 'python' command, Python exceptions uncaught within +the Python code are translated to calls to GDB error-reporting +mechanism. If the command that called 'python' does not handle the +error, GDB will terminate it and print an error message. Exactly what +will be printed depends on 'set python print-stack' (*note Python +Commands::). Example: + + (gdb) python print foo + Traceback (most recent call last): + File "", line 1, in + NameError: name 'foo' is not defined + + GDB errors that happen in GDB commands invoked by Python code are +converted to Python exceptions. The type of the Python exception +depends on the error. + +'gdb.error' + This is the base class for most exceptions generated by GDB. It is + derived from 'RuntimeError', for compatibility with earlier + versions of GDB. + + If an error occurring in GDB does not fit into some more specific + category, then the generated exception will have this type. + +'gdb.MemoryError' + This is a subclass of 'gdb.error' which is thrown when an operation + tried to access invalid memory in the inferior. + +'KeyboardInterrupt' + User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) + is translated to a Python 'KeyboardInterrupt' exception. + + In all cases, your exception handler will see the GDB error message +as its value and the Python call stack backtrace at the Python statement +closest to where the GDB error occurred as the traceback. + + When implementing GDB commands in Python via 'gdb.Command', or +functions via 'gdb.Function', it is useful to be able to throw an +exception that doesn't cause a traceback to be printed. For example, +the user may have invoked the command incorrectly. GDB provides a +special exception class that can be used for this purpose. + +'gdb.GdbError' + When thrown from a command or function, this exception will cause + the command or function to fail, but the Python stack will not be + displayed. GDB does not throw this exception itself, but rather + recognizes it when thrown from user Python code. Example: + + (gdb) python + >class HelloWorld (gdb.Command): + > """Greet the whole world.""" + > def __init__ (self): + > super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + > def invoke (self, args, from_tty): + > argv = gdb.string_to_argv (args) + > if len (argv) != 0: + > raise gdb.GdbError ("hello-world takes no arguments") + > print ("Hello, World!") + >HelloWorld () + >end + (gdb) hello-world 42 + hello-world takes no arguments + + +File: gdb.info, Node: Values From Inferior, Next: Types In Python, Prev: Exception Handling, Up: Python API + +23.3.2.4 Values From Inferior +............................. + +GDB provides values it obtains from the inferior program in an object of +type 'gdb.Value'. GDB uses this object for its internal bookkeeping of +the inferior's values, and for fetching values when necessary. + + Inferior values that are simple scalars can be used directly in +Python expressions that are valid for the value's data type. Here's an +example for an integer or floating-point value 'some_val': + + bar = some_val + 2 + +As result of this, 'bar' will also be a 'gdb.Value' object whose values +are of the same type as those of 'some_val'. Valid Python operations +can also be performed on 'gdb.Value' objects representing a 'struct' or +'class' object. For such cases, the overloaded operator (if present), +is used to perform the operation. For example, if 'val1' and 'val2' are +'gdb.Value' objects representing instances of a 'class' which overloads +the '+' operator, then one can use the '+' operator in their Python +script as follows: + + val3 = val1 + val2 + +The result of the operation 'val3' is also a 'gdb.Value' object +corresponding to the value returned by the overloaded '+' operator. In +general, overloaded operators are invoked for the following operations: +'+' (binary addition), '-' (binary subtraction), '*' (multiplication), +'/', '%', '<<', '>>', '|', '&', '^'. + + Inferior values that are structures or instances of some class can be +accessed using the Python "dictionary syntax". For example, if +'some_val' is a 'gdb.Value' instance holding a structure, you can access +its 'foo' element with: + + bar = some_val['foo'] + + Again, 'bar' will also be a 'gdb.Value' object. Structure elements +can also be accessed by using 'gdb.Field' objects as subscripts (*note +Types In Python::, for more information on 'gdb.Field' objects). For +example, if 'foo_field' is a 'gdb.Field' object corresponding to element +'foo' of the above structure, then 'bar' can also be accessed as +follows: + + bar = some_val[foo_field] + + If a 'gdb.Value' has array or pointer type, an integer index can be +used to access elements. + + result = some_array[23] + + A 'gdb.Value' that represents a function can be executed via inferior +function call. Any arguments provided to the call must match the +function's prototype, and must be provided in the order specified by +that prototype. + + For example, 'some_val' is a 'gdb.Value' instance representing a +function that takes two integers as arguments. To execute this +function, call it like so: + + result = some_val (10,20) + + Any values returned from a function call will be stored as a +'gdb.Value'. + + The following attributes are provided: + + -- Variable: Value.address + If this object is addressable, this read-only attribute holds a + 'gdb.Value' object representing the address. Otherwise, this + attribute holds 'None'. + + -- Variable: Value.is_optimized_out + This read-only boolean attribute is true if the compiler optimized + out this value, thus it is not available for fetching from the + inferior. + + -- Variable: Value.type + The type of this 'gdb.Value'. The value of this attribute is a + 'gdb.Type' object (*note Types In Python::). + + -- Variable: Value.dynamic_type + The dynamic type of this 'gdb.Value'. This uses the object's + virtual table and the C++ run-time type information (RTTI) to + determine the dynamic type of the value. If this value is of class + type, it will return the class in which the value is embedded, if + any. If this value is of pointer or reference to a class type, it + will compute the dynamic type of the referenced object, and return + a pointer or reference to that type, respectively. In all other + cases, it will return the value's static type. + + Note that this feature will only work when debugging a C++ program + that includes RTTI for the object in question. Otherwise, it will + just return the static type of the value as in 'ptype foo' (*note + ptype: Symbols.). + + -- Variable: Value.is_lazy + The value of this read-only boolean attribute is 'True' if this + 'gdb.Value' has not yet been fetched from the inferior. GDB does + not fetch values until necessary, for efficiency. For example: + + myval = gdb.parse_and_eval ('somevar') + + The value of 'somevar' is not fetched at this time. It will be + fetched when the value is needed, or when the 'fetch_lazy' method + is invoked. + + -- Variable: Value.bytes + The value of this attribute is a 'bytes' object containing the + bytes that make up this 'Value''s complete value in little endian + order. If the complete contents of this value are not available + then accessing this attribute will raise an exception. + + This attribute can also be assigned to. The new value should be a + buffer object (e.g. a 'bytes' object), the length of the new buffer + must exactly match the length of this 'Value''s type. The bytes + values in the new buffer should be in little endian order. + + As with 'Value.assign' (*note Value.assign::), if this value cannot + be assigned to, then an exception will be thrown. + + The following methods are provided: + + -- Function: Value.__init__ (val) + Many Python values can be converted directly to a 'gdb.Value' via + this object initializer. Specifically: + + Python boolean + A Python boolean is converted to the boolean type from the + current language. + + Python integer + A Python integer is converted to the C 'long' type for the + current architecture. + + Python long + A Python long is converted to the C 'long long' type for the + current architecture. + + Python float + A Python float is converted to the C 'double' type for the + current architecture. + + Python string + A Python string is converted to a target string in the current + target language using the current target encoding. If a + character cannot be represented in the current target + encoding, then an exception is thrown. + + 'gdb.Value' + If 'val' is a 'gdb.Value', then a copy of the value is made. + + 'gdb.LazyString' + If 'val' is a 'gdb.LazyString' (*note Lazy Strings In + Python::), then the lazy string's 'value' method is called, + and its result is used. + + -- Function: Value.__init__ (val, type) + This second form of the 'gdb.Value' constructor returns a + 'gdb.Value' of type TYPE where the value contents are taken from + the Python buffer object specified by VAL. The number of bytes in + the Python buffer object must be greater than or equal to the size + of TYPE. + + If TYPE is 'None' then this version of '__init__' behaves as though + TYPE was not passed at all. + + -- Function: Value.assign (rhs) + Assign RHS to this value, and return 'None'. If this value cannot + be assigned to, or if the assignment is invalid for some reason + (for example a type-checking failure), an exception will be thrown. + + -- Function: Value.cast (type) + Return a new instance of 'gdb.Value' that is the result of casting + this instance to the type described by TYPE, which must be a + 'gdb.Type' object. If the cast cannot be performed for some + reason, this method throws an exception. + + -- Function: Value.dereference () + For pointer data types, this method returns a new 'gdb.Value' + object whose contents is the object pointed to by the pointer. For + example, if 'foo' is a C pointer to an 'int', declared in your C + program as + + int *foo; + + then you can use the corresponding 'gdb.Value' to access what 'foo' + points to like this: + + bar = foo.dereference () + + The result 'bar' will be a 'gdb.Value' object holding the value + pointed to by 'foo'. + + A similar function 'Value.referenced_value' exists which also + returns 'gdb.Value' objects corresponding to the values pointed to + by pointer values (and additionally, values referenced by reference + values). However, the behavior of 'Value.dereference' differs from + 'Value.referenced_value' by the fact that the behavior of + 'Value.dereference' is identical to applying the C unary operator + '*' on a given value. For example, consider a reference to a + pointer 'ptrref', declared in your C++ program as + + typedef int *intptr; + ... + int val = 10; + intptr ptr = &val; + intptr &ptrref = ptr; + + Though 'ptrref' is a reference value, one can apply the method + 'Value.dereference' to the 'gdb.Value' object corresponding to it + and obtain a 'gdb.Value' which is identical to that corresponding + to 'val'. However, if you apply the method + 'Value.referenced_value', the result would be a 'gdb.Value' object + identical to that corresponding to 'ptr'. + + py_ptrref = gdb.parse_and_eval ("ptrref") + py_val = py_ptrref.dereference () + py_ptr = py_ptrref.referenced_value () + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val', and 'py_ptr' is identical to that corresponding to 'ptr'. + In general, 'Value.dereference' can be applied whenever the C unary + operator '*' can be applied to the corresponding C value. For + those cases where applying both 'Value.dereference' and + 'Value.referenced_value' is allowed, the results obtained need not + be identical (as we have seen in the above example). The results + are however identical when applied on 'gdb.Value' objects + corresponding to pointers ('gdb.Value' objects with type code + 'TYPE_CODE_PTR') in a C/C++ program. + + -- Function: Value.referenced_value () + For pointer or reference data types, this method returns a new + 'gdb.Value' object corresponding to the value referenced by the + pointer/reference value. For pointer data types, + 'Value.dereference' and 'Value.referenced_value' produce identical + results. The difference between these methods is that + 'Value.dereference' cannot get the values referenced by reference + values. For example, consider a reference to an 'int', declared in + your C++ program as + + int val = 10; + int &ref = val; + + then applying 'Value.dereference' to the 'gdb.Value' object + corresponding to 'ref' will result in an error, while applying + 'Value.referenced_value' will result in a 'gdb.Value' object + identical to that corresponding to 'val'. + + py_ref = gdb.parse_and_eval ("ref") + er_ref = py_ref.dereference () # Results in error + py_val = py_ref.referenced_value () # Returns the referenced value + + The 'gdb.Value' object 'py_val' is identical to that corresponding + to 'val'. + + -- Function: Value.reference_value () + Return a 'gdb.Value' object which is a reference to the value + encapsulated by this instance. + + -- Function: Value.const_value () + Return a 'gdb.Value' object which is a 'const' version of the value + encapsulated by this instance. + + -- Function: Value.dynamic_cast (type) + Like 'Value.cast', but works as if the C++ 'dynamic_cast' operator + were used. Consult a C++ reference for details. + + -- Function: Value.reinterpret_cast (type) + Like 'Value.cast', but works as if the C++ 'reinterpret_cast' + operator were used. Consult a C++ reference for details. + + -- Function: Value.format_string (...) + Convert a 'gdb.Value' to a string, similarly to what the 'print' + command does. Invoked with no arguments, this is equivalent to + calling the 'str' function on the 'gdb.Value'. The representation + of the same value may change across different versions of GDB, so + you shouldn't, for instance, parse the strings returned by this + method. + + All the arguments are keyword only. If an argument is not + specified, the current global default setting is used. + + 'raw' + 'True' if pretty-printers (*note Pretty Printing::) should not + be used to format the value. 'False' if enabled + pretty-printers matching the type represented by the + 'gdb.Value' should be used to format it. + + 'pretty_arrays' + 'True' if arrays should be pretty printed to be more + convenient to read, 'False' if they shouldn't (see 'set print + array' in *note Print Settings::). + + 'pretty_structs' + 'True' if structs should be pretty printed to be more + convenient to read, 'False' if they shouldn't (see 'set print + pretty' in *note Print Settings::). + + 'array_indexes' + 'True' if array indexes should be included in the string + representation of arrays, 'False' if they shouldn't (see 'set + print array-indexes' in *note Print Settings::). + + 'symbols' + 'True' if the string representation of a pointer should + include the corresponding symbol name (if one exists), 'False' + if it shouldn't (see 'set print symbol' in *note Print + Settings::). + + 'unions' + 'True' if unions which are contained in other structures or + unions should be expanded, 'False' if they shouldn't (see 'set + print union' in *note Print Settings::). + + 'address' + 'True' if the string representation of a pointer should + include the address, 'False' if it shouldn't (see 'set print + address' in *note Print Settings::). + + 'nibbles' + 'True' if binary values should be displayed in groups of four + bits, known as nibbles. 'False' if it shouldn't (*note set + print nibbles: Print Settings.). + + 'deref_refs' + 'True' if C++ references should be resolved to the value they + refer to, 'False' (the default) if they shouldn't. Note that, + unlike for the 'print' command, references are not + automatically expanded when using the 'format_string' method + or the 'str' function. There is no global 'print' setting to + change the default behavior. + + 'actual_objects' + 'True' if the representation of a pointer to an object should + identify the _actual_ (derived) type of the object rather than + the _declared_ type, using the virtual function table. + 'False' if the _declared_ type should be used. (See 'set + print object' in *note Print Settings::). + + 'static_members' + 'True' if static members should be included in the string + representation of a C++ object, 'False' if they shouldn't (see + 'set print static-members' in *note Print Settings::). + + 'max_characters' + Number of string characters to print, '0' to follow + 'max_elements', or 'UINT_MAX' to print an unlimited number of + characters (see 'set print characters' in *note Print + Settings::). + + 'max_elements' + Number of array elements to print, or '0' to print an + unlimited number of elements (see 'set print elements' in + *note Print Settings::). + + 'max_depth' + The maximum depth to print for nested structs and unions, or + '-1' to print an unlimited number of elements (see 'set print + max-depth' in *note Print Settings::). + + 'repeat_threshold' + Set the threshold for suppressing display of repeated array + elements, or '0' to represent all elements, even if repeated. + (See 'set print repeats' in *note Print Settings::). + + 'format' + A string containing a single character representing the format + to use for the returned string. For instance, ''x'' is + equivalent to using the GDB command 'print' with the '/x' + option and formats the value as a hexadecimal number. + + 'styling' + 'True' if GDB should apply styling to the returned string. + When styling is applied, the returned string might contain + ANSI terminal escape sequences. Escape sequences will only be + included if styling is turned on, see *note Output Styling::. + Additionally, GDB only styles some value contents, so not + every output string will contain escape sequences. + + When 'False', which is the default, no output styling is + applied. + + 'summary' + 'True' when just a summary should be printed. In this mode, + scalar values are printed in their entirety, but aggregates + such as structures or unions are omitted. This mode is used + by 'set print frame-arguments scalars' (*note Print + Settings::). + + -- Function: Value.to_array () + If this value is array-like (*note Type.is_array_like::), then this + method converts it to an array, which is returned. If this value + is already an array, it is simply returned. Otherwise, an + exception is throw. + + -- Function: Value.string ([encoding[, errors[, length]]]) + If this 'gdb.Value' represents a string, then this method converts + the contents to a Python string. Otherwise, this method will throw + an exception. + + Values are interpreted as strings according to the rules of the + current language. If the optional length argument is given, the + string will be converted to that length, and will include any + embedded zeroes that the string may contain. Otherwise, for + languages where the string is zero-terminated, the entire string + will be converted. + + For example, in C-like languages, a value is a string if it is a + pointer to or an array of characters or ints of type 'wchar_t', + 'char16_t', or 'char32_t'. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the string in the 'gdb.Value', such as + '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same + encodings as the corresponding argument to Python's 'string.decode' + method, and the Python codec machinery will be used to convert the + string. If ENCODING is not given, or if ENCODING is the empty + string, then either the 'target-charset' (*note Character Sets::) + will be used, or a language-specific encoding will be used, if the + current language is able to supply one. + + The optional ERRORS argument is the same as the corresponding + argument to Python's 'string.decode' method. + + If the optional LENGTH argument is given, the string will be + fetched and converted to the given length. + + -- Function: Value.lazy_string ([encoding [, length]]) + This method attempts to convert this 'gdb.Value' to a + 'gdb.LazyString' (*note Lazy Strings In Python::). Values of array + or pointer type can be converted; for other types, this method will + throw an exception. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the 'gdb.LazyString'. Some examples are: + 'ascii', 'iso-8859-6' or 'utf-8'. If the ENCODING argument is an + encoding that GDB does recognize, GDB will raise an error. + + When a lazy string is printed, the GDB encoding machinery is used + to convert the string during printing. If the optional ENCODING + argument is not provided, or is an empty string, GDB will + automatically select the encoding most suitable for the string + type. For further information on encoding in GDB please see *note + Character Sets::. + + If the optional LENGTH argument is given, the string will be + fetched and encoded to the length of characters specified. If the + LENGTH argument is not provided, the string will be fetched and + encoded until a null of appropriate width is found. + + -- Function: Value.fetch_lazy () + If the 'gdb.Value' object is currently a lazy value + ('gdb.Value.is_lazy' is 'True'), then the value is fetched from the + inferior. Any errors that occur in the process will produce a + Python exception. + + If the 'gdb.Value' object is not a lazy value, this method has no + effect. + + This method does not return a value. + + +File: gdb.info, Node: Types In Python, Next: Pretty Printing API, Prev: Values From Inferior, Up: Python API + +23.3.2.5 Types In Python +........................ + +GDB represents types from the inferior using the class 'gdb.Type'. + + The following type-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_type (name [, block]) + This function looks up a type by its NAME, which must be a string. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + Ordinarily, this function will return an instance of 'gdb.Type'. + If the named type cannot be found, it will throw an exception. + + Integer types can be found without looking them up by name. *Note +Architectures In Python::, for the 'integer_type' method. + + If the type is a structure or class type, or an enum type, the fields +of that type can be accessed using the Python "dictionary syntax". For +example, if 'some_type' is a 'gdb.Type' instance holding a structure +type, you can access its 'foo' field with: + + bar = some_type['foo'] + + 'bar' will be a 'gdb.Field' object; see below under the description +of the 'Type.fields' method for a description of the 'gdb.Field' class. + + An instance of 'Type' has the following attributes: + + -- Variable: Type.alignof + The alignment of this type, in bytes. Type alignment comes from + the debugging information; if it was not specified, then GDB will + use the relevant ABI to try to determine the alignment. In some + cases, even this is not possible, and zero will be returned. + + -- Variable: Type.code + The type code for this type. The type code will be one of the + 'TYPE_CODE_' constants defined below. + + -- Variable: Type.dynamic + A boolean indicating whether this type is dynamic. In some + situations, such as Rust 'enum' types or Ada variant records, the + concrete type of a value may vary depending on its contents. That + is, the declared type of a variable, or the type returned by + 'gdb.lookup_type' may be dynamic; while the type of the variable's + value will be a concrete instance of that dynamic type. + + For example, consider this code: + int n; + int array[n]; + + Here, at least conceptually (whether your compiler actually does + this is a separate issue), examining + 'gdb.lookup_symbol("array", ...).type' could yield a 'gdb.Type' + which reports a size of 'None'. This is the dynamic type. + + However, examining 'gdb.parse_and_eval("array").type' would yield a + concrete type, whose length would be known. + + -- Variable: Type.name + The name of this type. If this type has no name, then 'None' is + returned. + + -- Variable: Type.sizeof + The size of this type, in target 'char' units. Usually, a target's + 'char' type will be an 8-bit byte. However, on some unusual + platforms, this type may have a different size. A dynamic type may + not have a fixed size; in this case, this attribute's value will be + 'None'. + + -- Variable: Type.tag + The tag name for this type. The tag name is the name after + 'struct', 'union', or 'enum' in C and C++; not all languages have + this concept. If this type has no tag name, then 'None' is + returned. + + -- Variable: Type.objfile + The 'gdb.Objfile' that this type was defined in, or 'None' if there + is no associated objfile. + + -- Variable: Type.is_scalar + This property is 'True' if the type is a scalar type, otherwise, + this property is 'False'. Examples of non-scalar types include + structures, unions, and classes. + + -- Variable: Type.is_signed + For scalar types (those for which 'Type.is_scalar' is 'True'), this + property is 'True' if the type is signed, otherwise this property + is 'False'. + + Attempting to read this property for a non-scalar type (a type for + which 'Type.is_scalar' is 'False'), will raise a 'ValueError'. + + -- Variable: Type.is_array_like + A boolean indicating whether this type is array-like. + + Some languages have array-like objects that are represented + internally as structures. For example, this is true for a Rust + slice type, or for an Ada unconstrained array. GDB may know about + these types. This determination is done based on the language from + which the type originated. + + -- Variable: Type.is_string_like + A boolean indicating whether this type is string-like. Like + 'Type.is_array_like', this is determined based on the originating + language of the type. + + The following methods are provided: + + -- Function: Type.fields () + + Return the fields of this type. The behavior depends on the type + code: + + * For structure and union types, this method returns the fields. + + * Enum types have one field per enum constant. + + * Function and method types have one field per parameter. The + base types of C++ classes are also represented as fields. + + * Array types have one field representing the array's range. + + * If the type does not fit into one of these categories, a + 'TypeError' is raised. + + Each field is a 'gdb.Field' object, with some pre-defined + attributes: + 'bitpos' + This attribute is not available for 'enum' or 'static' (as in + C++) fields. The value is the position, counting in bits, + from the start of the containing type. Note that, in a + dynamic type, the position of a field may not be constant. In + this case, the value will be 'None'. Also, a dynamic type may + have fields that do not appear in a corresponding concrete + type. + + 'enumval' + This attribute is only available for 'enum' fields, and its + value is the enumeration member's integer representation. + + 'name' + The name of the field, or 'None' for anonymous fields. + + 'artificial' + This is 'True' if the field is artificial, usually meaning + that it was provided by the compiler and not the user. This + attribute is always provided, and is 'False' if the field is + not artificial. + + 'is_base_class' + This is 'True' if the field represents a base class of a C++ + structure. This attribute is always provided, and is 'False' + if the field is not a base class of the type that is the + argument of 'fields', or if that type was not a C++ class. + + 'bitsize' + If the field is packed, or is a bitfield, then this will have + a non-zero value, which is the size of the field in bits. + Otherwise, this will be zero; in this case the field's size is + given by its type. + + 'type' + The type of the field. This is usually an instance of 'Type', + but it can be 'None' in some situations. + + 'parent_type' + The type which contains this field. This is an instance of + 'gdb.Type'. + + -- Function: Type.array (n1 [, n2]) + Return a new 'gdb.Type' object which represents an array of this + type. If one argument is given, it is the inclusive upper bound of + the array; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the array, and + the second argument is the upper bound of the array. An array's + length must not be negative, but the bounds can be. + + -- Function: Type.vector (n1 [, n2]) + Return a new 'gdb.Type' object which represents a vector of this + type. If one argument is given, it is the inclusive upper bound of + the vector; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the vector, and + the second argument is the upper bound of the vector. A vector's + length must not be negative, but the bounds can be. + + The difference between an 'array' and a 'vector' is that arrays + behave like in C: when used in expressions they decay to a pointer + to the first element whereas vectors are treated as first class + values. + + -- Function: Type.const () + Return a new 'gdb.Type' object which represents a 'const'-qualified + variant of this type. + + -- Function: Type.volatile () + Return a new 'gdb.Type' object which represents a + 'volatile'-qualified variant of this type. + + -- Function: Type.unqualified () + Return a new 'gdb.Type' object which represents an unqualified + variant of this type. That is, the result is neither 'const' nor + 'volatile'. + + -- Function: Type.range () + Return a Python 'Tuple' object that contains two elements: the low + bound of the argument type and the high bound of that type. If the + type does not have a range, GDB will raise a 'gdb.error' exception + (*note Exception Handling::). + + -- Function: Type.reference () + Return a new 'gdb.Type' object which represents a reference to this + type. + + -- Function: Type.pointer () + Return a new 'gdb.Type' object which represents a pointer to this + type. + + -- Function: Type.strip_typedefs () + Return a new 'gdb.Type' that represents the real type, after + removing all layers of typedefs. + + -- Function: Type.target () + Return a new 'gdb.Type' object which represents the target type of + this type. + + For a pointer type, the target type is the type of the pointed-to + object. For an array type (meaning C-like arrays), the target type + is the type of the elements of the array. For a function or method + type, the target type is the type of the return value. For a + complex type, the target type is the type of the elements. For a + typedef, the target type is the aliased type. + + If the type does not have a target, this method will throw an + exception. + + -- Function: Type.template_argument (n [, block]) + If this 'gdb.Type' is an instantiation of a template, this will + return a new 'gdb.Value' or 'gdb.Type' which represents the value + of the Nth template argument (indexed starting at 0). + + If this 'gdb.Type' is not a template type, or if the type has fewer + than N template arguments, this will throw an exception. + Ordinarily, only C++ code will have template types. + + If BLOCK is given, then NAME is looked up in that scope. + Otherwise, it is searched for globally. + + -- Function: Type.optimized_out () + Return 'gdb.Value' instance of this type whose value is optimized + out. This allows a frame decorator to indicate that the value of + an argument or a local variable is not known. + + Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the 'gdb' module: + +'gdb.TYPE_CODE_PTR' + The type is a pointer. + +'gdb.TYPE_CODE_ARRAY' + The type is an array. + +'gdb.TYPE_CODE_STRUCT' + The type is a structure. + +'gdb.TYPE_CODE_UNION' + The type is a union. + +'gdb.TYPE_CODE_ENUM' + The type is an enum. + +'gdb.TYPE_CODE_FLAGS' + A bit flags type, used for things such as status registers. + +'gdb.TYPE_CODE_FUNC' + The type is a function. + +'gdb.TYPE_CODE_INT' + The type is an integer type. + +'gdb.TYPE_CODE_FLT' + A floating point type. + +'gdb.TYPE_CODE_VOID' + The special type 'void'. + +'gdb.TYPE_CODE_SET' + A Pascal set type. + +'gdb.TYPE_CODE_RANGE' + A range type, that is, an integer type with bounds. + +'gdb.TYPE_CODE_STRING' + A string type. Note that this is only used for certain languages + with language-defined string types; C strings are not represented + this way. + +'gdb.TYPE_CODE_BITSTRING' + A string of bits. It is deprecated. + +'gdb.TYPE_CODE_ERROR' + An unknown or erroneous type. + +'gdb.TYPE_CODE_METHOD' + A method type, as found in C++. + +'gdb.TYPE_CODE_METHODPTR' + A pointer-to-member-function. + +'gdb.TYPE_CODE_MEMBERPTR' + A pointer-to-member. + +'gdb.TYPE_CODE_REF' + A reference type. + +'gdb.TYPE_CODE_RVALUE_REF' + A C++11 rvalue reference type. + +'gdb.TYPE_CODE_CHAR' + A character type. + +'gdb.TYPE_CODE_BOOL' + A boolean type. + +'gdb.TYPE_CODE_COMPLEX' + A complex float type. + +'gdb.TYPE_CODE_TYPEDEF' + A typedef to some other type. + +'gdb.TYPE_CODE_NAMESPACE' + A C++ namespace. + +'gdb.TYPE_CODE_DECFLOAT' + A decimal floating point type. + +'gdb.TYPE_CODE_INTERNAL_FUNCTION' + A function internal to GDB. This is the type used to represent + convenience functions. + +'gdb.TYPE_CODE_XMETHOD' + A method internal to GDB. This is the type used to represent + xmethods (*note Writing an Xmethod::). + +'gdb.TYPE_CODE_FIXED_POINT' + A fixed-point number. + +'gdb.TYPE_CODE_NAMESPACE' + A Fortran namelist. + + Further support for types is provided in the 'gdb.types' Python +module (*note gdb.types::). + + +File: gdb.info, Node: Pretty Printing API, Next: Selecting Pretty-Printers, Prev: Types In Python, Up: Python API + +23.3.2.6 Pretty Printing API +............................ + +A pretty-printer is just an object that holds a value and implements a +specific interface, defined here. An example output is provided (*note +Pretty Printing::). + + Because GDB did not document extensibility for pretty-printers, by +default GDB will assume that only the basic pretty-printer methods may +be available. The basic methods are marked as such, below. + + To allow extensibility, GDB provides the 'gdb.ValuePrinter' base +class. This class does not provide any attributes or behavior, but +instead serves as a tag that can be recognized by GDB. For such +printers, GDB reserves all attributes starting with a lower-case letter. +That is, in the future, GDB may add a new method or attribute to the +pretty-printer protocol, and 'gdb.ValuePrinter'-based printers are +expected to handle this gracefully. A simple way to do this would be to +use a leading underscore (or two, following the Python name-mangling +scheme) to any attributes local to the implementation. + + -- Function: pretty_printer.children (self) + GDB will call this method on a pretty-printer to compute the + children of the pretty-printer's value. + + This method must return an object conforming to the Python iterator + protocol. Each item returned by the iterator must be a tuple + holding two elements. The first element is the "name" of the + child; the second element is the child's value. The value can be + any Python object which is convertible to a GDB value. + + This is a basic method, and is optional. If it does not exist, GDB + will act as though the value has no children. + + For efficiency, the 'children' method should lazily compute its + results. This will let GDB read as few elements as necessary, for + example when various print settings (*note Print Settings::) or + '-var-list-children' (*note GDB/MI Variable Objects::) limit the + number of elements to be displayed. + + Children may be hidden from display based on the value of 'set + print max-depth' (*note Print Settings::). + + -- Function: pretty_printer.display_hint (self) + The CLI may call this method and use its result to change the + formatting of a value. The result will also be supplied to an MI + consumer as a 'displayhint' attribute of the variable being + printed. + + This is a basic method, and is optional. If it does exist, this + method must return a string or the special value 'None'. + + Some display hints are predefined by GDB: + + 'array' + Indicate that the object being printed is "array-like". The + CLI uses this to respect parameters such as 'set print + elements' and 'set print array'. + + 'map' + Indicate that the object being printed is "map-like", and that + the children of this value can be assumed to alternate between + keys and values. + + 'string' + Indicate that the object being printed is "string-like". If + the printer's 'to_string' method returns a Python string of + some kind, then GDB will call its internal language-specific + string-printing function to format the string. For the CLI + this means adding quotation marks, possibly escaping some + characters, respecting 'set print elements', and the like. + + The special value 'None' causes GDB to apply the default display + rules. + + -- Function: pretty_printer.to_string (self) + GDB will call this method to display the string representation of + the value passed to the object's constructor. + + This is a basic method, and is optional. + + When printing from the CLI, if the 'to_string' method exists, then + GDB will prepend its result to the values returned by 'children'. + Exactly how this formatting is done is dependent on the display + hint, and may change as more hints are added. Also, depending on + the print settings (*note Print Settings::), the CLI may print just + the result of 'to_string' in a stack trace, omitting the result of + 'children'. + + If this method returns a string, it is printed verbatim. + + Otherwise, if this method returns an instance of 'gdb.Value', then + GDB prints this value. This may result in a call to another + pretty-printer. + + If instead the method returns a Python value which is convertible + to a 'gdb.Value', then GDB performs the conversion and prints the + resulting value. Again, this may result in a call to another + pretty-printer. Python scalars (integers, floats, and booleans) + and strings are convertible to 'gdb.Value'; other types are not. + + Finally, if this method returns 'None' then no further operations + are performed in this method and nothing is printed. + + If the result is not one of these types, an exception is raised. + + -- Function: pretty_printer.num_children () + This is not a basic method, so GDB will only ever call it for + objects derived from 'gdb.ValuePrinter'. + + If available, this method should return the number of children. + 'None' may be returned if the number can't readily be computed. + + -- Function: pretty_printer.child (n) + This is not a basic method, so GDB will only ever call it for + objects derived from 'gdb.ValuePrinter'. + + If available, this method should return the child item (that is, a + tuple holding the name and value of this child) indicated by N. + Indices start at zero. + + GDB provides a function which can be used to look up the default +pretty-printer for a 'gdb.Value': + + -- Function: gdb.default_visualizer (value) + This function takes a 'gdb.Value' object as an argument. If a + pretty-printer for this value exists, then it is returned. If no + such printer exists, then this returns 'None'. + + Normally, a pretty-printer can respect the user's print settings +(including temporarily applied settings, such as '/x') simply by calling +'Value.format_string' (*note Values From Inferior::). However, these +settings can also be queried directly: + + -- Function: gdb.print_options () + Return a dictionary whose keys are the valid keywords that can be + given to 'Value.format_string', and whose values are the user's + settings. During a 'print' or other operation, the values will + reflect any flags that are temporarily in effect. + + (gdb) python print (gdb.print_options ()['max_elements']) + 200 + + +File: gdb.info, Node: Selecting Pretty-Printers, Next: Writing a Pretty-Printer, Prev: Pretty Printing API, Up: Python API + +23.3.2.7 Selecting Pretty-Printers +.................................. + +GDB provides several ways to register a pretty-printer: globally, per +program space, and per objfile. When choosing how to register your +pretty-printer, a good rule is to register it with the smallest scope +possible: that is prefer a specific objfile first, then a program space, +and only register a printer globally as a last resort. + + -- Variable: gdb.pretty_printers + The Python list 'gdb.pretty_printers' contains an array of + functions or callable objects that have been registered via + addition as a pretty-printer. Printers in this list are called + 'global' printers, they're available when debugging all inferiors. + + Each 'gdb.Progspace' contains a 'pretty_printers' attribute. Each +'gdb.Objfile' also contains a 'pretty_printers' attribute. + + Each function on these lists is passed a single 'gdb.Value' argument +and should return a pretty-printer object conforming to the interface +definition above (*note Pretty Printing API::). If a function cannot +create a pretty-printer for the value, it should return 'None'. + + GDB first checks the 'pretty_printers' attribute of each +'gdb.Objfile' in the current program space and iteratively calls each +enabled lookup routine in the list for that 'gdb.Objfile' until it +receives a pretty-printer object. If no pretty-printer is found in the +objfile lists, GDB then searches the pretty-printer list of the current +program space, calling each enabled function until an object is +returned. After these lists have been exhausted, it tries the global +'gdb.pretty_printers' list, again calling each enabled function until an +object is returned. + + The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, and +iterated over sequentially until the end of the list, or a printer +object is returned. + + For various reasons a pretty-printer may not work. For example, the +underlying data structure may have changed and the pretty-printer is out +of date. + + The consequences of a broken pretty-printer are severe enough that +GDB provides support for enabling and disabling individual printers. +For example, if 'print frame-arguments' is on, a backtrace can become +highly illegible if any argument is printed with a broken printer. + + Pretty-printers are enabled and disabled by attaching an 'enabled' +attribute to the registered function or callable object. If this +attribute is present and its value is 'False', the printer is disabled, +otherwise the printer is enabled. + + +File: gdb.info, Node: Writing a Pretty-Printer, Next: Type Printing API, Prev: Selecting Pretty-Printers, Up: Python API + +23.3.2.8 Writing a Pretty-Printer +................................. + +A pretty-printer consists of two parts: a lookup function to detect if +the type is supported, and the printer itself. + + Here is an example showing how a 'std::string' printer might be +written. *Note Pretty Printing API::, for details on the API this class +must provide. Note that this example uses the 'gdb.ValuePrinter' base +class, and is careful to use a leading underscore for its local state. + + class StdStringPrinter(gdb.ValuePrinter): + "Print a std::string" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return self.__val['_M_dataplus']['_M_p'] + + def display_hint(self): + return 'string' + + And here is an example showing how a lookup function for the printer +example above might be written. + + def str_lookup_function(val): + lookup_tag = val.type.tag + if lookup_tag is None: + return None + regex = re.compile("^std::basic_string$") + if regex.match(lookup_tag): + return StdStringPrinter(val) + return None + + The example lookup function extracts the value's type, and attempts +to match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a printer object. If not, it +returns 'None'. + + We recommend that you put your core pretty-printers into a Python +package. If your pretty-printers are for use with a library, we further +recommend embedding a version number into the package name. This +practice will enable GDB to load multiple versions of your +pretty-printers at the same time, because they will have different +names. + + You should write auto-loaded code (*note Python Auto-loading::) such +that it can be evaluated multiple times without changing its meaning. +An ideal auto-load file will consist solely of 'import's of your printer +modules, followed by a call to a register pretty-printers with the +current objfile. + + Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Python package name will ensure that +GDB is able to load both sets of printers simultaneously. Then, because +the search for pretty-printers is done by objfile, and because your +auto-loaded code took care to register your library's printers with a +specific objfile, GDB will find the correct printers for the specific +version of the library used by each inferior. + + To continue the 'std::string' example (*note Pretty Printing API::), +this code might appear in 'gdb.libstdcxx.v6': + + def register_printers(objfile): + objfile.pretty_printers.append(str_lookup_function) + +And then the corresponding contents of the auto-load file would be: + + import gdb.libstdcxx.v6 + gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) + + The previous example illustrates a basic pretty-printer. There are a +few things that can be improved on. The printer doesn't have a name, +making it hard to identify in a list of installed printers. The lookup +function has a name, but lookup functions can have arbitrary, even +identical, names. + + Second, the printer only handles one type, whereas a library +typically has several types. One could install a lookup function for +each desired type in the library, but one could also have a single +lookup function recognize several types. The latter is the conventional +way this is handled. If a pretty-printer can handle multiple data +types, then its "subprinters" are the printers for the individual data +types. + + The 'gdb.printing' module provides a formal way of solving these +problems (*note gdb.printing::). Here is another example that handles +multiple types. + + These are the types we are going to pretty-print: + + struct foo { int a, b; }; + struct bar { struct foo x, y; }; + + Here are the printers: + + class fooPrinter(gdb.ValuePrinter): + """Print a foo object.""" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return ("a=<" + str(self.__val["a"]) + + "> b=<" + str(self.__val["b"]) + ">") + + class barPrinter(gdb.ValuePrinter): + """Print a bar object.""" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return ("x=<" + str(self.__val["x"]) + + "> y=<" + str(self.__val["y"]) + ">") + + This example doesn't need a lookup function, that is handled by the +'gdb.printing' module. Instead a function is provided to build up the +object that handles the lookup. + + import gdb.printing + + def build_pretty_printer(): + pp = gdb.printing.RegexpCollectionPrettyPrinter( + "my_library") + pp.add_printer('foo', '^foo$', fooPrinter) + pp.add_printer('bar', '^bar$', barPrinter) + return pp + + And here is the autoload support: + + import gdb.printing + import my_library + gdb.printing.register_pretty_printer( + gdb.current_objfile(), + my_library.build_pretty_printer()) + + Finally, when this printer is loaded into GDB, here is the +corresponding output of 'info pretty-printer': + + (gdb) info pretty-printer + my_library.so: + my_library + foo + bar + + +File: gdb.info, Node: Type Printing API, Next: Frame Filter API, Prev: Writing a Pretty-Printer, Up: Python API + +23.3.2.9 Type Printing API +.......................... + +GDB provides a way for Python code to customize type display. This is +mainly useful for substituting canonical typedef names for types. + + A "type printer" is just a Python object conforming to a certain +protocol. A simple base class implementing the protocol is provided; +see *note gdb.types::. A type printer must supply at least: + + -- Instance Variable of type_printer: enabled + A boolean which is True if the printer is enabled, and False + otherwise. This is manipulated by the 'enable type-printer' and + 'disable type-printer' commands. + + -- Instance Variable of type_printer: name + The name of the type printer. This must be a string. This is used + by the 'enable type-printer' and 'disable type-printer' commands. + + -- Method on type_printer: instantiate (self) + This is called by GDB at the start of type-printing. It is only + called if the type printer is enabled. This method must return a + new object that supplies a 'recognize' method, as described below. + + When displaying a type, say via the 'ptype' command, GDB will compute +a list of type recognizers. This is done by iterating first over the +per-objfile type printers (*note Objfiles In Python::), followed by the +per-progspace type printers (*note Progspaces In Python::), and finally +the global type printers. + + GDB will call the 'instantiate' method of each enabled type printer. +If this method returns 'None', then the result is ignored; otherwise, it +is appended to the list of recognizers. + + Then, when GDB is going to display a type name, it iterates over the +list of recognizers. For each one, it calls the recognition function, +stopping if the function returns a non-'None' value. The recognition +function is defined as: + + -- Method on type_recognizer: recognize (self, type) + If TYPE is not recognized, return 'None'. Otherwise, return a + string which is to be printed as the name of TYPE. The TYPE + argument will be an instance of 'gdb.Type' (*note Types In + Python::). + + GDB uses this two-pass approach so that type printers can efficiently +cache information without holding on to it too long. For example, it +can be convenient to look up type information in a type printer and hold +it for a recognizer's lifetime; if a single pass were done then type +printers would have to make use of the event system in order to avoid +holding information that could become stale as the inferior changed. + + +File: gdb.info, Node: Frame Filter API, Next: Frame Decorator API, Prev: Type Printing API, Up: Python API + +23.3.2.10 Filtering Frames +.......................... + +Frame filters are Python objects that manipulate the visibility of a +frame or frames when a backtrace (*note Backtrace::) is printed by GDB. + + Only commands that print a backtrace, or, in the case of GDB/MI +commands (*note GDB/MI::), those that return a collection of frames are +affected. The commands that work with frame filters are: + + 'backtrace' (*note The backtrace command: backtrace-command.), +'-stack-list-frames' (*note The -stack-list-frames command: +-stack-list-frames.), '-stack-list-variables' (*note The +-stack-list-variables command: -stack-list-variables.), +'-stack-list-arguments' *note The -stack-list-arguments command: +-stack-list-arguments.) and '-stack-list-locals' (*note The +-stack-list-locals command: -stack-list-locals.). + + A frame filter works by taking an iterator as an argument, applying +actions to the contents of that iterator, and returning another iterator +(or, possibly, the same iterator it was provided in the case where the +filter does not perform any operations). Typically, frame filters +utilize tools such as the Python's 'itertools' module to work with and +create new iterators from the source iterator. Regardless of how a +filter chooses to apply actions, it must not alter the underlying GDB +frame or frames, or attempt to alter the call-stack within GDB. This +preserves data integrity within GDB. Frame filters are executed on a +priority basis and care should be taken that some frame filters may have +been executed before, and that some frame filters will be executed +after. + + An important consideration when designing frame filters, and well +worth reflecting upon, is that frame filters should avoid unwinding the +call stack if possible. Some stacks can run very deep, into the tens of +thousands in some cases. To search every frame when a frame filter +executes may be too expensive at that step. The frame filter cannot +know how many frames it has to iterate over, and it may have to iterate +through them all. This ends up duplicating effort as GDB performs this +iteration when it prints the frames. If the filter can defer unwinding +frames until frame decorators are executed, after the last filter has +executed, it should. *Note Frame Decorator API::, for more information +on decorators. Also, there are examples for both frame decorators and +filters in later chapters. *Note Writing a Frame Filter::, for more +information. + + The Python dictionary 'gdb.frame_filters' contains key/object +pairings that comprise a frame filter. Frame filters in this dictionary +are called 'global' frame filters, and they are available when debugging +all inferiors. These frame filters must register with the dictionary +directly. In addition to the 'global' dictionary, there are other +dictionaries that are loaded with different inferiors via auto-loading +(*note Python Auto-loading::). The two other areas where frame filter +dictionaries can be found are: 'gdb.Progspace' which contains a +'frame_filters' dictionary attribute, and each 'gdb.Objfile' object +which also contains a 'frame_filters' dictionary attribute. + + When a command is executed from GDB that is compatible with frame +filters, GDB combines the 'global', 'gdb.Progspace' and all +'gdb.Objfile' dictionaries currently loaded. All of the 'gdb.Objfile' +dictionaries are combined, as several frames, and thus several object +files, might be in use. GDB then prunes any frame filter whose +'enabled' attribute is 'False'. This pruned list is then sorted +according to the 'priority' attribute in each filter. + + Once the dictionaries are combined, pruned and sorted, GDB creates an +iterator which wraps each frame in the call stack in a 'FrameDecorator' +object, and calls each filter in order. The output from the previous +filter will always be the input to the next filter, and so on. + + Frame filters have a mandatory interface which each frame filter must +implement, defined here: + + -- Function: FrameFilter.filter (iterator) + GDB will call this method on a frame filter when it has reached the + order in the priority list for that filter. + + For example, if there are four frame filters: + + Name Priority + + Filter1 5 + Filter2 10 + Filter3 100 + Filter4 1 + + The order that the frame filters will be called is: + + Filter3 -> Filter2 -> Filter1 -> Filter4 + + Note that the output from 'Filter3' is passed to the input of + 'Filter2', and so on. + + This 'filter' method is passed a Python iterator. This iterator + contains a sequence of frame decorators that wrap each 'gdb.Frame', + or a frame decorator that wraps another frame decorator. The first + filter that is executed in the sequence of frame filters will + receive an iterator entirely comprised of default 'FrameDecorator' + objects. However, after each frame filter is executed, the + previous frame filter may have wrapped some or all of the frame + decorators with their own frame decorator. As frame decorators + must also conform to a mandatory interface, these decorators can be + assumed to act in a uniform manner (*note Frame Decorator API::). + + This method must return an object conforming to the Python iterator + protocol. Each item in the iterator must be an object conforming + to the frame decorator interface. If a frame filter does not wish + to perform any operations on this iterator, it should return that + iterator untouched. + + This method is not optional. If it does not exist, GDB will raise + and print an error. + + -- Variable: FrameFilter.name + The 'name' attribute must be Python string which contains the name + of the filter displayed by GDB (*note Frame Filter Management::). + This attribute may contain any combination of letters or numbers. + Care should be taken to ensure that it is unique. This attribute + is mandatory. + + -- Variable: FrameFilter.enabled + The 'enabled' attribute must be Python boolean. This attribute + indicates to GDB whether the frame filter is enabled, and should be + considered when frame filters are executed. If 'enabled' is + 'True', then the frame filter will be executed when any of the + backtrace commands detailed earlier in this chapter are executed. + If 'enabled' is 'False', then the frame filter will not be + executed. This attribute is mandatory. + + -- Variable: FrameFilter.priority + The 'priority' attribute must be Python integer. This attribute + controls the order of execution in relation to other frame filters. + There are no imposed limits on the range of 'priority' other than + it must be a valid integer. The higher the 'priority' attribute, + the sooner the frame filter will be executed in relation to other + frame filters. Although 'priority' can be negative, it is + recommended practice to assume zero is the lowest priority that a + frame filter can be assigned. Frame filters that have the same + priority are executed in unsorted order in that priority slot. + This attribute is mandatory. 100 is a good default priority. + + +File: gdb.info, Node: Frame Decorator API, Next: Writing a Frame Filter, Prev: Frame Filter API, Up: Python API + +23.3.2.11 Decorating Frames +........................... + +Frame decorators are sister objects to frame filters (*note Frame Filter +API::). Frame decorators are applied by a frame filter and can only be +used in conjunction with frame filters. + + The purpose of a frame decorator is to customize the printed content +of each 'gdb.Frame' in commands where frame filters are executed. This +concept is called decorating a frame. Frame decorators decorate a +'gdb.Frame' with Python code contained within each API call. This +separates the actual data contained in a 'gdb.Frame' from the decorated +data produced by a frame decorator. This abstraction is necessary to +maintain integrity of the data contained in each 'gdb.Frame'. + + Frame decorators have a mandatory interface, defined below. + + GDB already contains a frame decorator called 'FrameDecorator'. This +contains substantial amounts of boilerplate code to decorate the content +of a 'gdb.Frame'. It is recommended that other frame decorators inherit +and extend this object, and only to override the methods needed. + + 'FrameDecorator' is defined in the Python module +'gdb.FrameDecorator', so your code can import it like: + from gdb.FrameDecorator import FrameDecorator + + -- Function: FrameDecorator.elided (self) + + The 'elided' method groups frames together in a hierarchical + system. An example would be an interpreter, where multiple + low-level frames make up a single call in the interpreted language. + In this example, the frame filter would elide the low-level frames + and present a single high-level frame, representing the call in the + interpreted language, to the user. + + The 'elided' function must return an iterable and this iterable + must contain the frames that are being elided wrapped in a suitable + frame decorator. If no frames are being elided this function may + return an empty iterable, or 'None'. Elided frames are indented + from normal frames in a 'CLI' backtrace, or in the case of GDB/MI, + are placed in the 'children' field of the eliding frame. + + It is the frame filter's task to also filter out the elided frames + from the source iterator. This will avoid printing the frame + twice. + + -- Function: FrameDecorator.function (self) + + This method returns the name of the function in the frame that is + to be printed. + + This method must return a Python string describing the function, or + 'None'. + + If this function returns 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.address (self) + + This method returns the address of the frame that is to be printed. + + This method must return a Python numeric integer type of sufficient + size to describe the address of the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.filename (self) + + This method returns the filename and path associated with this + frame. + + This method must return a Python string containing the filename and + the path to the object file backing the frame, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.line (self): + + This method returns the line number associated with the current + position within the function addressed by this frame. + + This method must return a Python integer type, or 'None'. + + If this function returns a 'None', GDB will not print any data for + this field. + + -- Function: FrameDecorator.frame_args (self) + + This method must return an iterable, or 'None'. Returning an empty + iterable, or 'None' means frame arguments will not be printed for + this frame. This iterable must contain objects that implement two + methods, described here. + + This object must implement a 'symbol' method which takes a single + 'self' parameter and must return a 'gdb.Symbol' (*note Symbols In + Python::), or a Python string. The object must also implement a + 'value' method which takes a single 'self' parameter and must + return a 'gdb.Value' (*note Values From Inferior::), a Python + value, or 'None'. If the 'value' method returns 'None', and the + 'argument' method returns a 'gdb.Symbol', GDB will look-up and + print the value of the 'gdb.Symbol' automatically. + + A brief example: + + class SymValueWrapper(): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value(self): + return self.val + + def symbol(self): + return self.sym + + class SomeFrameDecorator() + ... + ... + def frame_args(self): + args = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Only add + # symbols that are arguments. + for sym in block: + if not sym.is_argument: + continue + args.append(SymValueWrapper(sym,None)) + + # Add example synthetic argument. + args.append(SymValueWrapper(``foo'', 42)) + + return args + + -- Function: FrameDecorator.frame_locals (self) + + This method must return an iterable or 'None'. Returning an empty + iterable, or 'None' means frame local arguments will not be printed + for this frame. + + The object interface, the description of the various strategies for + reading frame locals, and the example are largely similar to those + described in the 'frame_args' function, (*note The frame filter + frame_args function: frame_args.). Below is a modified example: + + class SomeFrameDecorator() + ... + ... + def frame_locals(self): + vars = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Add all + # symbols, except arguments. + for sym in block: + if sym.is_argument: + continue + vars.append(SymValueWrapper(sym,None)) + + # Add an example of a synthetic local variable. + vars.append(SymValueWrapper(``bar'', 99)) + + return vars + + -- Function: FrameDecorator.inferior_frame (self): + + This method must return the underlying 'gdb.Frame' that this frame + decorator is decorating. GDB requires the underlying frame for + internal frame information to determine how to print certain values + when printing a frame. + + +File: gdb.info, Node: Writing a Frame Filter, Next: Unwinding Frames in Python, Prev: Frame Decorator API, Up: Python API + +23.3.2.12 Writing a Frame Filter +................................ + +There are three basic elements that a frame filter must implement: it +must correctly implement the documented interface (*note Frame Filter +API::), it must register itself with GDB, and finally, it must decide if +it is to work on the data provided by GDB. In all cases, whether it +works on the iterator or not, each frame filter must return an iterator. +A bare-bones frame filter follows the pattern in the following example. + + import gdb + + class FrameFilter(): + + def __init__(self): + # Frame filter attribute creation. + # + # 'name' is the name of the filter that GDB will display. + # + # 'priority' is the priority of the filter relative to other + # filters. + # + # 'enabled' is a boolean that indicates whether this filter is + # enabled and should be executed. + + self.name = "Foo" + self.priority = 100 + self.enabled = True + + # Register this frame filter with the global frame_filters + # dictionary. + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + # Just return the iterator. + return frame_iter + + The frame filter in the example above implements the three +requirements for all frame filters. It implements the API, self +registers, and makes a decision on the iterator (in this case, it just +returns the iterator untouched). + + The first step is attribute creation and assignment, and as shown in +the comments the filter assigns the following attributes: 'name', +'priority' and whether the filter should be enabled with the 'enabled' +attribute. + + The second step is registering the frame filter with the dictionary +or dictionaries that the frame filter has interest in. As shown in the +comments, this filter just registers itself with the global dictionary +'gdb.frame_filters'. As noted earlier, 'gdb.frame_filters' is a +dictionary that is initialized in the 'gdb' module when GDB starts. +What dictionary a filter registers with is an important consideration. +Generally, if a filter is specific to a set of code, it should be +registered either in the 'objfile' or 'progspace' dictionaries as they +are specific to the program currently loaded in GDB. The global +dictionary is always present in GDB and is never unloaded. Any filters +registered with the global dictionary will exist until GDB exits. To +avoid filters that may conflict, it is generally better to register +frame filters against the dictionaries that more closely align with the +usage of the filter currently in question. *Note Python Auto-loading::, +for further information on auto-loading Python scripts. + + GDB takes a hands-off approach to frame filter registration, +therefore it is the frame filter's responsibility to ensure registration +has occurred, and that any exceptions are handled appropriately. In +particular, you may wish to handle exceptions relating to Python +dictionary key uniqueness. It is mandatory that the dictionary key is +the same as frame filter's 'name' attribute. When a user manages frame +filters (*note Frame Filter Management::), the names GDB will display +are those contained in the 'name' attribute. + + The final step of this example is the implementation of the 'filter' +method. As shown in the example comments, we define the 'filter' method +and note that the method must take an iterator, and also must return an +iterator. In this bare-bones example, the frame filter is not very +useful as it just returns the iterator untouched. However this is a +valid operation for frame filters that have the 'enabled' attribute set, +but decide not to operate on any frames. + + In the next example, the frame filter operates on all frames and +utilizes a frame decorator to perform some work on the frames. *Note +Frame Decorator API::, for further information on the frame decorator +interface. + + This example works on inlined frames. It highlights frames which are +inlined by tagging them with an "[inlined]" tag. By applying a frame +decorator to all frames with the Python 'itertools imap' method, the +example defers actions to the frame decorator. Frame decorators are +only processed when GDB prints the backtrace. + + This introduces a new decision making topic: whether to perform +decision making operations at the filtering step, or at the printing +step. In this example's approach, it does not perform any filtering +decisions at the filtering step beyond mapping a frame decorator to each +frame. This allows the actual decision making to be performed when each +frame is printed. This is an important consideration, and well worth +reflecting upon when designing a frame filter. An issue that frame +filters should avoid is unwinding the stack if possible. Some stacks +can run very deep, into the tens of thousands in some cases. To search +every frame to determine if it is inlined ahead of time may be too +expensive at the filtering step. The frame filter cannot know how many +frames it has to iterate over, and it would have to iterate through them +all. This ends up duplicating effort as GDB performs this iteration +when it prints the frames. + + In this example decision making can be deferred to the printing step. +As each frame is printed, the frame decorator can examine each frame in +turn when GDB iterates. From a performance viewpoint, this is the most +appropriate decision to make as it avoids duplicating the effort that +the printing step would undertake anyway. Also, if there are many frame +filters unwinding the stack during filtering, it can substantially delay +the printing of the backtrace which will result in large memory usage, +and a poor user experience. + + class InlineFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + frame_iter = itertools.imap(InlinedFrameDecorator, + frame_iter) + return frame_iter + + This frame filter is somewhat similar to the earlier example, except +that the 'filter' method applies a frame decorator object called +'InlinedFrameDecorator' to each element in the iterator. The 'imap' +Python method is light-weight. It does not proactively iterate over the +iterator, but rather creates a new iterator which wraps the existing +one. + + Below is the frame decorator for this example. + + class InlinedFrameDecorator(FrameDecorator): + + def __init__(self, fobj): + super(InlinedFrameDecorator, self).__init__(fobj) + + def function(self): + frame = self.inferior_frame() + name = str(frame.name()) + + if frame.type() == gdb.INLINE_FRAME: + name = name + " [inlined]" + + return name + + This frame decorator only defines and overrides the 'function' +method. It lets the supplied 'FrameDecorator', which is shipped with +GDB, perform the other work associated with printing this frame. + + The combination of these two objects create this output from a +backtrace: + + #0 0x004004e0 in bar () at inline.c:11 + #1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21 + #2 0x00400566 in main () at inline.c:31 + + So in the case of this example, a frame decorator is applied to all +frames, regardless of whether they may be inlined or not. As GDB +iterates over the iterator produced by the frame filters, GDB executes +each frame decorator which then makes a decision on what to print in the +'function' callback. Using a strategy like this is a way to defer +decisions on the frame content to printing time. + +Eliding Frames +-------------- + +It might be that the above example is not desirable for representing +inlined frames, and a hierarchical approach may be preferred. If we +want to hierarchically represent frames, the 'elided' frame decorator +interface might be preferable. + + This example approaches the issue with the 'elided' method. This +example is quite long, but very simplistic. It is out-of-scope for this +section to write a complete example that comprehensively covers all +approaches of finding and printing inlined frames. However, this +example illustrates the approach an author might use. + + This example comprises of three sections. + + class InlineFrameFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + return ElidingInlineIterator(frame_iter) + + This frame filter is very similar to the other examples. The only +difference is this frame filter is wrapping the iterator provided to it +('frame_iter') with a custom iterator called 'ElidingInlineIterator'. +This again defers actions to when GDB prints the backtrace, as the +iterator is not traversed until printing. + + The iterator for this example is as follows. It is in this section +of the example where decisions are made on the content of the backtrace. + + class ElidingInlineIterator: + def __init__(self, ii): + self.input_iterator = ii + + def __iter__(self): + return self + + def next(self): + frame = next(self.input_iterator) + + if frame.inferior_frame().type() != gdb.INLINE_FRAME: + return frame + + try: + eliding_frame = next(self.input_iterator) + except StopIteration: + return frame + return ElidingFrameDecorator(eliding_frame, [frame]) + + This iterator implements the Python iterator protocol. When the +'next' function is called (when GDB prints each frame), the iterator +checks if this frame decorator, 'frame', is wrapping an inlined frame. +If it is not, it returns the existing frame decorator untouched. If it +is wrapping an inlined frame, it assumes that the inlined frame was +contained within the next oldest frame, 'eliding_frame', which it +fetches. It then creates and returns a frame decorator, +'ElidingFrameDecorator', which contains both the elided frame, and the +eliding frame. + + class ElidingInlineDecorator(FrameDecorator): + + def __init__(self, frame, elided_frames): + super(ElidingInlineDecorator, self).__init__(frame) + self.frame = frame + self.elided_frames = elided_frames + + def elided(self): + return iter(self.elided_frames) + + This frame decorator overrides one function and returns the inlined +frame in the 'elided' method. As before it lets 'FrameDecorator' do the +rest of the work involved in printing this frame. This produces the +following output. + + #0 0x004004e0 in bar () at inline.c:11 + #2 0x00400529 in main () at inline.c:25 + #1 0x00400529 in max (b=6, a=12) at inline.c:15 + + In that output, 'max' which has been inlined into 'main' is printed +hierarchically. Another approach would be to combine the 'function' +method, and the 'elided' method to both print a marker in the inlined +frame, and also show the hierarchical relationship. + + +File: gdb.info, Node: Unwinding Frames in Python, Next: Xmethods In Python, Prev: Writing a Frame Filter, Up: Python API + +23.3.2.13 Unwinding Frames in Python +.................................... + +In GDB terminology "unwinding" is the process of finding the previous +frame (that is, caller's) from the current one. An unwinder has three +methods. The first one checks if it can handle given frame ("sniff" +it). For the frames it can sniff an unwinder provides two additional +methods: it can return frame's ID, and it can fetch registers from the +previous frame. A running GDB maintains a list of the unwinders and +calls each unwinder's sniffer in turn until it finds the one that +recognizes the current frame. There is an API to register an unwinder. + + The unwinders that come with GDB handle standard frames. However, +mixed language applications (for example, an application running Java +Virtual Machine) sometimes use frame layouts that cannot be handled by +the GDB unwinders. You can write Python code that can handle such +custom frames. + + You implement a frame unwinder in Python as a class with which has +two attributes, 'name' and 'enabled', with obvious meanings, and a +single method '__call__', which examines a given frame and returns an +object (an instance of 'gdb.UnwindInfo class)' describing it. If an +unwinder does not recognize a frame, it should return 'None'. The code +in GDB that enables writing unwinders in Python uses this object to +return frame's ID and previous frame registers when GDB core asks for +them. + + An unwinder should do as little work as possible. Some otherwise +innocuous operations can cause problems (even crashes, as this code is +not well-hardened yet). For example, making an inferior call from an +unwinder is unadvisable, as an inferior call will reset GDB's stack +unwinding process, potentially causing re-entrant unwinding. + +Unwinder Input +-------------- + +An object passed to an unwinder (a 'gdb.PendingFrame' instance) provides +a method to read frame's registers: + + -- Function: PendingFrame.read_register (register) + This method returns the contents of REGISTER in the frame as a + 'gdb.Value' object. For a description of the acceptable values of + REGISTER see *note Frame.read_register: gdbpy_frame_read_register. + If REGISTER does not name a register for the current architecture, + this method will throw an exception. + + Note that this method will always return a 'gdb.Value' for a valid + register name. This does not mean that the value will be valid. + For example, you may request a register that an earlier unwinder + could not unwind--the value will be unavailable. Instead, the + 'gdb.Value' returned from this method will be lazy; that is, its + underlying bits will not be fetched until it is first used. So, + attempting to use such a value will cause an exception at the point + of use. + + The type of the returned 'gdb.Value' depends on the register and + the architecture. It is common for registers to have a scalar + type, like 'long long'; but many other types are possible, such as + pointer, pointer-to-function, floating point or vector types. + + It also provides a factory method to create a 'gdb.UnwindInfo' +instance to be returned to GDB: + + -- Function: PendingFrame.create_unwind_info (frame_id) + Returns a new 'gdb.UnwindInfo' instance identified by given + FRAME_ID. The FRAME_ID is used internally by GDB to identify the + frames within the current thread's stack. The attributes of + FRAME_ID determine what type of frame is created within GDB: + + 'sp, pc' + The frame is identified by the given stack address and PC. The + stack address must be chosen so that it is constant throughout + the lifetime of the frame, so a typical choice is the value of + the stack pointer at the start of the function--in the DWARF + standard, this would be the "Call Frame Address". + + This is the most common case by far. The other cases are + documented for completeness but are only useful in specialized + situations. + + 'sp, pc, special' + The frame is identified by the stack address, the PC, and a + "special" address. The special address is used on + architectures that can have frames that do not change the + stack, but which are still distinct, for example the IA-64, + which has a second stack for registers. Both SP and SPECIAL + must be constant throughout the lifetime of the frame. + + 'sp' + The frame is identified by the stack address only. Any other + stack frame with a matching SP will be considered to match + this frame. Inside gdb, this is called a "wild frame". You + will never need this. + + Each attribute value should either be an instance of 'gdb.Value' or + an integer. + + A helper class is provided in the 'gdb.unwinder' module that can be + used to represent a frame-id (*note gdb.unwinder.FrameId::). + + -- Function: PendingFrame.architecture () + Return the 'gdb.Architecture' (*note Architectures In Python::) for + this 'gdb.PendingFrame'. This represents the architecture of the + particular frame being unwound. + + -- Function: PendingFrame.level () + Return an integer, the stack frame level for this frame. *Note + Stack Frames: Frames. + + -- Function: PendingFrame.name () + Returns the function name of this pending frame, or 'None' if it + can't be obtained. + + -- Function: PendingFrame.is_valid () + Returns true if the 'gdb.PendingFrame' object is valid, false if + not. A pending frame object becomes invalid when the call to the + unwinder, for which the pending frame was created, returns. + + All 'gdb.PendingFrame' methods, except this one, will raise an + exception if the pending frame object is invalid at the time the + method is called. + + -- Function: PendingFrame.pc () + Returns the pending frame's resume address. + + -- Function: PendingFrame.block () + Return the pending frame's code block (*note Blocks In Python::). + If the frame does not have a block - for example, if there is no + debugging information for the code in question - then this will + raise a 'RuntimeError' exception. + + -- Function: PendingFrame.function () + Return the symbol for the function corresponding to this pending + frame. *Note Symbols In Python::. + + -- Function: PendingFrame.find_sal () + Return the pending frame's symtab and line object (*note Symbol + Tables In Python::). + + -- Function: PendingFrame.language () + Return the language of this frame, as a string, or None. + +Unwinder Output: UnwindInfo +--------------------------- + +Use 'PendingFrame.create_unwind_info' method described above to create a +'gdb.UnwindInfo' instance. Use the following method to specify caller +registers that have been saved in this frame: + + -- Function: gdb.UnwindInfo.add_saved_register (register, value) + REGISTER identifies the register, for a description of the + acceptable values see *note Frame.read_register: + gdbpy_frame_read_register. VALUE is a register value (a + 'gdb.Value' object). + +The 'gdb.unwinder' Module +------------------------- + +GDB comes with a 'gdb.unwinder' module which contains the following +classes: + + -- class: gdb.unwinder.Unwinder + The 'Unwinder' class is a base class from which user created + unwinders can derive, though it is not required that unwinders + derive from this class, so long as any user created unwinder has + the required 'name' and 'enabled' attributes. + + -- Function: gdb.unwinder.Unwinder.__init__(name) + The NAME is a string used to reference this unwinder within + some GDB commands (*note Managing Registered Unwinders::). + + -- Variable: gdb.unwinder.name + A read-only attribute which is a string, the name of this + unwinder. + + -- Variable: gdb.unwinder.enabled + A modifiable attribute containing a boolean; when 'True', the + unwinder is enabled, and will be used by GDB. When 'False', + the unwinder has been disabled, and will not be used. + + -- class: gdb.unwinder.FrameId + This is a class suitable for being used as the frame-id when + calling 'gdb.PendingFrame.create_unwind_info'. It is not required + to use this class, any class with the required attribute (*note + gdb.PendingFrame.create_unwind_info::) will be accepted, but in + most cases this class will be sufficient. + + 'gdb.unwinder.FrameId' has the following method: + + -- Function: gdb.unwinder.FrameId.__init__(sp, pc, special = None) + The SP and PC arguments are required and should be either a + 'gdb.Value' object, or an integer. + + The SPECIAL argument is optional; if specified, it should be a + 'gdb.Value' object, or an integer. + + 'gdb.unwinder.FrameId' has the following read-only attributes: + + -- Variable: gdb.unwinder.sp + The SP value passed to the constructor. + + -- Variable: gdb.unwinder.pc + The PC value passed to the constructor. + + -- Variable: gdb.unwinder.special + The SPECIAL value passed to the constructor, or 'None' if no + such value was passed. + +Registering an Unwinder +----------------------- + +Object files and program spaces can have unwinders registered with them. +In addition, you can register unwinders globally. + + The 'gdb.unwinders' module provides the function to register an +unwinder: + + -- Function: gdb.unwinder.register_unwinder (locus, unwinder, + replace=False) + LOCUS specifies to which unwinder list to prepend the UNWINDER. It + can be either an object file (*note Objfiles In Python::), a + program space (*note Progspaces In Python::), or 'None', in which + case the unwinder is registered globally. The newly added UNWINDER + will be called before any other unwinder from the same locus. Two + unwinders in the same locus cannot have the same name. An attempt + to add an unwinder with an already existing name raises an + exception unless REPLACE is 'True', in which case the old unwinder + is deleted and the new unwinder is registered in its place. + + GDB first calls the unwinders from all the object files in no + particular order, then the unwinders from the current program + space, then the globally registered unwinders, and finally the + unwinders builtin to GDB. + +Unwinder Skeleton Code +---------------------- + +Here is an example of how to structure a user created unwinder: + + from gdb.unwinder import Unwinder, FrameId + + class MyUnwinder(Unwinder): + def __init__(self): + super().__init___("MyUnwinder_Name") + + def __call__(self, pending_frame): + if not : + return None + + # Create a FrameID. Usually the frame is identified by a + # stack pointer and the function address. + sp = ... compute a stack address ... + pc = ... compute function address ... + unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) + + # Find the values of the registers in the caller's frame and + # save them in the result: + unwind_info.add_saved_register(, ) + .... + + # Return the result: + return unwind_info + + gdb.unwinder.register_unwinder(, MyUnwinder(), ) + +Managing Registered Unwinders +----------------------------- + +GDB defines 3 commands to manage registered unwinders. These are: + +'info unwinder [ LOCUS [ NAME-REGEXP ] ]' + Lists all registered unwinders. Arguments LOCUS and NAME-REGEXP + are both optional and can be used to filter which unwinders are + listed. + + The LOCUS argument should be either 'global', 'progspace', or the + name of an object file. Only unwinders registered for the + specified locus will be listed. + + The NAME-REGEXP is a regular expression used to match against + unwinder names. When trying to match against unwinder names that + include a string enclose NAME-REGEXP in quotes. +'disable unwinder [ LOCUS [ NAME-REGEXP ] ]' + The LOCUS and NAME-REGEXP are interpreted as in 'info unwinder' + above, but instead of listing the matching unwinders, all of the + matching unwinders are disabled. The 'enabled' field of each + matching unwinder is set to 'False'. +'enable unwinder [ LOCUS [ NAME-REGEXP ] ]' + The LOCUS and NAME-REGEXP are interpreted as in 'info unwinder' + above, but instead of listing the matching unwinders, all of the + matching unwinders are enabled. The 'enabled' field of each + matching unwinder is set to 'True'. + + +File: gdb.info, Node: Xmethods In Python, Next: Xmethod API, Prev: Unwinding Frames in Python, Up: Python API + +23.3.2.14 Xmethods In Python +............................ + +"Xmethods" are additional methods or replacements for existing methods +of a C++ class. This feature is useful for those cases where a method +defined in C++ source code could be inlined or optimized out by the +compiler, making it unavailable to GDB. For such cases, one can define +an xmethod to serve as a replacement for the method defined in the C++ +source code. GDB will then invoke the xmethod, instead of the C++ +method, to evaluate expressions. One can also use xmethods when +debugging with core files. Moreover, when debugging live programs, +invoking an xmethod need not involve running the inferior (which can +potentially perturb its state). Hence, even if the C++ method is +available, it is better to use its replacement xmethod if one is +defined. + + The xmethods feature in Python is available via the concepts of an +"xmethod matcher" and an "xmethod worker". To implement an xmethod, one +has to implement a matcher and a corresponding worker for it (more than +one worker can be implemented, each catering to a different overloaded +instance of the method). Internally, GDB invokes the 'match' method of +a matcher to match the class type and method name. On a match, the +'match' method returns a list of matching _worker_ objects. Each worker +object typically corresponds to an overloaded instance of the xmethod. +They implement a 'get_arg_types' method which returns a sequence of +types corresponding to the arguments the xmethod requires. GDB uses +this sequence of types to perform overload resolution and picks a +winning xmethod worker. A winner is also selected from among the +methods GDB finds in the C++ source code. Next, the winning xmethod +worker and the winning C++ method are compared to select an overall +winner. In case of a tie between a xmethod worker and a C++ method, the +xmethod worker is selected as the winner. That is, if a winning xmethod +worker is found to be equivalent to the winning C++ method, then the +xmethod worker is treated as a replacement for the C++ method. GDB uses +the overall winner to invoke the method. If the winning xmethod worker +is the overall winner, then the corresponding xmethod is invoked via the +'__call__' method of the worker object. + + If one wants to implement an xmethod as a replacement for an existing +C++ method, then they have to implement an equivalent xmethod which has +exactly the same name and takes arguments of exactly the same type as +the C++ method. If the user wants to invoke the C++ method even though +a replacement xmethod is available for that method, then they can +disable the xmethod. + + *Note Xmethod API::, for API to implement xmethods in Python. *Note +Writing an Xmethod::, for implementing xmethods in Python. + + +File: gdb.info, Node: Xmethod API, Next: Writing an Xmethod, Prev: Xmethods In Python, Up: Python API + +23.3.2.15 Xmethod API +..................... + +The GDB Python API provides classes, interfaces and functions to +implement, register and manipulate xmethods. *Note Xmethods In +Python::. + + An xmethod matcher should be an instance of a class derived from +'XMethodMatcher' defined in the module 'gdb.xmethod', or an object with +similar interface and attributes. An instance of 'XMethodMatcher' has +the following attributes: + + -- Variable: name + The name of the matcher. + + -- Variable: enabled + A boolean value indicating whether the matcher is enabled or + disabled. + + -- Variable: methods + A list of named methods managed by the matcher. Each object in the + list is an instance of the class 'XMethod' defined in the module + 'gdb.xmethod', or any object with the following attributes: + + 'name' + Name of the xmethod which should be unique for each xmethod + managed by the matcher. + + 'enabled' + A boolean value indicating whether the xmethod is enabled or + disabled. + + The class 'XMethod' is a convenience class with same attributes as + above along with the following constructor: + + -- Function: XMethod.__init__ (self, name) + Constructs an enabled xmethod with name NAME. + +The 'XMethodMatcher' class has the following methods: + + -- Function: XMethodMatcher.__init__ (self, name) + Constructs an enabled xmethod matcher with name NAME. The + 'methods' attribute is initialized to 'None'. + + -- Function: XMethodMatcher.match (self, class_type, method_name) + Derived classes should override this method. It should return a + xmethod worker object (or a sequence of xmethod worker objects) + matching the CLASS_TYPE and METHOD_NAME. CLASS_TYPE is a + 'gdb.Type' object, and METHOD_NAME is a string value. If the + matcher manages named methods as listed in its 'methods' attribute, + then only those worker objects whose corresponding entries in the + 'methods' list are enabled should be returned. + + An xmethod worker should be an instance of a class derived from +'XMethodWorker' defined in the module 'gdb.xmethod', or support the +following interface: + + -- Function: XMethodWorker.get_arg_types (self) + This method returns a sequence of 'gdb.Type' objects corresponding + to the arguments that the xmethod takes. It can return an empty + sequence or 'None' if the xmethod does not take any arguments. If + the xmethod takes a single argument, then a single 'gdb.Type' + object corresponding to it can be returned. + + -- Function: XMethodWorker.get_result_type (self, *args) + This method returns a 'gdb.Type' object representing the type of + the result of invoking this xmethod. The ARGS argument is the same + tuple of arguments that would be passed to the '__call__' method of + this worker. + + -- Function: XMethodWorker.__call__ (self, *args) + This is the method which does the _work_ of the xmethod. The ARGS + arguments is the tuple of arguments to the xmethod. Each element + in this tuple is a gdb.Value object. The first element is always + the 'this' pointer value. + + For GDB to lookup xmethods, the xmethod matchers should be registered +using the following function defined in the module 'gdb.xmethod': + + -- Function: register_xmethod_matcher (locus, matcher, replace=False) + The 'matcher' is registered with 'locus', replacing an existing + matcher with the same name as 'matcher' if 'replace' is 'True'. + 'locus' can be a 'gdb.Objfile' object (*note Objfiles In Python::), + or a 'gdb.Progspace' object (*note Progspaces In Python::), or + 'None'. If it is 'None', then 'matcher' is registered globally. + + +File: gdb.info, Node: Writing an Xmethod, Next: Inferiors In Python, Prev: Xmethod API, Up: Python API + +23.3.2.16 Writing an Xmethod +............................ + +Implementing xmethods in Python will require implementing xmethod +matchers and xmethod workers (*note Xmethods In Python::). Consider the +following C++ class: + + class MyClass + { + public: + MyClass (int a) : a_(a) { } + + int geta (void) { return a_; } + int operator+ (int b); + + private: + int a_; + }; + + int + MyClass::operator+ (int b) + { + return a_ + b; + } + +Let us define two xmethods for the class 'MyClass', one replacing the +method 'geta', and another adding an overloaded flavor of 'operator+' +which takes a 'MyClass' argument (the C++ code above already has an +overloaded 'operator+' which takes an 'int' argument). The xmethod +matcher can be defined as follows: + + class MyClass_geta(gdb.xmethod.XMethod): + def __init__(self): + gdb.xmethod.XMethod.__init__(self, 'geta') + + def get_worker(self, method_name): + if method_name == 'geta': + return MyClassWorker_geta() + + + class MyClass_sum(gdb.xmethod.XMethod): + def __init__(self): + gdb.xmethod.XMethod.__init__(self, 'sum') + + def get_worker(self, method_name): + if method_name == 'operator+': + return MyClassWorker_plus() + + + class MyClassMatcher(gdb.xmethod.XMethodMatcher): + def __init__(self): + gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') + # List of methods 'managed' by this matcher + self.methods = [MyClass_geta(), MyClass_sum()] + + def match(self, class_type, method_name): + if class_type.tag != 'MyClass': + return None + workers = [] + for method in self.methods: + if method.enabled: + worker = method.get_worker(method_name) + if worker: + workers.append(worker) + + return workers + +Notice that the 'match' method of 'MyClassMatcher' returns a worker +object of type 'MyClassWorker_geta' for the 'geta' method, and a worker +object of type 'MyClassWorker_plus' for the 'operator+' method. This is +done indirectly via helper classes derived from 'gdb.xmethod.XMethod'. +One does not need to use the 'methods' attribute in a matcher as it is +optional. However, if a matcher manages more than one xmethod, it is a +good practice to list the xmethods in the 'methods' attribute of the +matcher. This will then facilitate enabling and disabling individual +xmethods via the 'enable/disable' commands. Notice also that a worker +object is returned only if the corresponding entry in the 'methods' +attribute of the matcher is enabled. + + The implementation of the worker classes returned by the matcher +setup above is as follows: + + class MyClassWorker_geta(gdb.xmethod.XMethodWorker): + def get_arg_types(self): + return None + + def get_result_type(self, obj): + return gdb.lookup_type('int') + + def __call__(self, obj): + return obj['a_'] + + + class MyClassWorker_plus(gdb.xmethod.XMethodWorker): + def get_arg_types(self): + return gdb.lookup_type('MyClass') + + def get_result_type(self, obj): + return gdb.lookup_type('int') + + def __call__(self, obj, other): + return obj['a_'] + other['a_'] + + For GDB to actually lookup a xmethod, it has to be registered with +it. The matcher defined above is registered with GDB globally as +follows: + + gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher()) + + If an object 'obj' of type 'MyClass' is initialized in C++ code as +follows: + + MyClass obj(5); + +then, after loading the Python script defining the xmethod matchers and +workers into GDB, invoking the method 'geta' or using the operator '+' +on 'obj' will invoke the xmethods defined above: + + (gdb) p obj.geta() + $1 = 5 + + (gdb) p obj + obj + $2 = 10 + + Consider another example with a C++ template class: + + template + class MyTemplate + { + public: + MyTemplate () : dsize_(10), data_ (new T [10]) { } + ~MyTemplate () { delete [] data_; } + + int footprint (void) + { + return sizeof (T) * dsize_ + sizeof (MyTemplate); + } + + private: + int dsize_; + T *data_; + }; + + Let us implement an xmethod for the above class which serves as a +replacement for the 'footprint' method. The full code listing of the +xmethod workers and xmethod matchers is as follows: + + class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): + def __init__(self, class_type): + self.class_type = class_type + + def get_arg_types(self): + return None + + def get_result_type(self): + return gdb.lookup_type('int') + + def __call__(self, obj): + return (self.class_type.sizeof + + obj['dsize_'] * + self.class_type.template_argument(0).sizeof) + + + class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): + def __init__(self): + gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') + + def match(self, class_type, method_name): + if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', + class_type.tag) and + method_name == 'footprint'): + return MyTemplateWorker_footprint(class_type) + + Notice that, in this example, we have not used the 'methods' +attribute of the matcher as the matcher manages only one xmethod. The +user can enable/disable this xmethod by enabling/disabling the matcher +itself. + diff -pruN 16.3-5/gdb/doc/gdb.info-5 16.3-5ubuntu1/gdb/doc/gdb.info-5 --- 16.3-5/gdb/doc/gdb.info-5 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-5 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,7201 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Inferiors In Python, Next: Events In Python, Prev: Writing an Xmethod, Up: Python API + +23.3.2.17 Inferiors In Python +............................. + +Programs which are being run under GDB are called inferiors (*note +Inferiors Connections and Programs::). Python scripts can access +information about and manipulate inferiors controlled by GDB via objects +of the 'gdb.Inferior' class. + + The following inferior-related functions are available in the 'gdb' +module: + + -- Function: gdb.inferiors () + Return a tuple containing all inferior objects. + + -- Function: gdb.selected_inferior () + Return an object representing the current inferior. + + A 'gdb.Inferior' object has the following attributes: + + -- Variable: Inferior.num + ID of inferior, as assigned by GDB. You can use this to make + Python breakpoints inferior-specific, for example (*note The + Breakpoint.inferior attribute: python_breakpoint_inferior.). + + -- Variable: Inferior.connection + The 'gdb.TargetConnection' for this inferior (*note Connections In + Python::), or 'None' if this inferior has no connection. + + -- Variable: Inferior.connection_num + ID of inferior's connection as assigned by GDB, or None if the + inferior is not connected to a target. *Note Inferiors Connections + and Programs::. This is equivalent to + 'gdb.Inferior.connection.num' in the case where + 'gdb.Inferior.connection' is not 'None'. + + -- Variable: Inferior.pid + Process ID of the inferior, as assigned by the underlying operating + system. + + -- Variable: Inferior.was_attached + Boolean signaling whether the inferior was created using 'attach', + or started by GDB itself. + + -- Variable: Inferior.main_name + A string holding the name of this inferior's "main" function, if it + can be determined. If the name of main is not known, this is + 'None'. + + -- Variable: Inferior.progspace + The inferior's program space. *Note Progspaces In Python::. + + -- Variable: Inferior.arguments + The inferior's command line arguments, if known. This corresponds + to the 'set args' and 'show args' commands. *Note Arguments::. + + When accessed, the value is a string holding all the arguments. + The contents are quoted as they would be when passed to the shell. + If there are no arguments, the value is 'None'. + + Either a string or a sequence of strings can be assigned to this + attribute. When a string is assigned, it is assumed to have any + necessary quoting for the shell; when a sequence is assigned, the + quoting is applied by GDB. + + A 'gdb.Inferior' object has the following methods: + + -- Function: Inferior.is_valid () + Returns 'True' if the 'gdb.Inferior' object is valid, 'False' if + not. A 'gdb.Inferior' object will become invalid if the inferior + no longer exists within GDB. All other 'gdb.Inferior' methods will + throw an exception if it is invalid at the time the method is + called. + + -- Function: Inferior.threads () + This method returns a tuple holding all the threads which are valid + when it is called. If there are no valid threads, the method will + return an empty tuple. + + -- Function: Inferior.architecture () + Return the 'gdb.Architecture' (*note Architectures In Python::) for + this inferior. This represents the architecture of the inferior as + a whole. Some platforms can have multiple architectures in a + single address space, so this may not match the architecture of a + particular frame (*note Frames In Python::). + + -- Function: Inferior.read_memory (address, length) + Read LENGTH addressable memory units from the inferior, starting at + ADDRESS. Returns a 'memoryview' object, which behaves much like an + array or a string. It can be modified and given to the + 'Inferior.write_memory' function. + + -- Function: Inferior.write_memory (address, buffer [, length]) + Write the contents of BUFFER to the inferior, starting at ADDRESS. + The BUFFER parameter must be a Python object which supports the + buffer protocol, i.e., a string, an array or the object returned + from 'Inferior.read_memory'. If given, LENGTH determines the + number of addressable memory units from BUFFER to be written. + + -- Function: Inferior.search_memory (address, length, pattern) + Search a region of the inferior memory starting at ADDRESS with the + given LENGTH using the search pattern supplied in PATTERN. The + PATTERN parameter must be a Python object which supports the buffer + protocol, i.e., a string, an array or the object returned from + 'gdb.read_memory'. Returns a Python 'Long' containing the address + where the pattern was found, or 'None' if the pattern could not be + found. + + -- Function: Inferior.thread_from_handle (handle) + Return the thread object corresponding to HANDLE, a thread library + specific data structure such as 'pthread_t' for pthreads library + implementations. + + The function 'Inferior.thread_from_thread_handle' provides the same + functionality, but use of 'Inferior.thread_from_thread_handle' is + deprecated. + + The environment that will be passed to the inferior can be changed +from Python by using the following methods. These methods only take +effect when the inferior is started - they will not affect an inferior +that is already executing. + + -- Function: Inferior.clear_env () + Clear the current environment variables that will be passed to this + inferior. + + -- Function: Inferior.set_env (name, value) + Set the environment variable NAME to have the indicated value. + Both parameters must be strings. + + -- Function: Inferior.unset_env (name) + Unset the environment variable NAME. NAME must be a string. + + One may add arbitrary attributes to 'gdb.Inferior' objects in the +usual Python way. This is useful if, for example, one needs to do some +extra record keeping associated with the inferior. + + When selecting a name for a new attribute, avoid starting the new +attribute name with a lower case letter; future attributes added by GDB +will start with a lower case letter. Additionally, avoid starting +attribute names with two underscore characters, as these could clash +with Python builtin attribute names. + + In this contrived example we record the time when an inferior last +stopped: + + (gdb) python + import datetime + + def thread_stopped(event): + if event.inferior_thread is not None: + thread = event.inferior_thread + else: + thread = gdb.selected_thread() + inferior = thread.inferior + inferior._last_stop_time = datetime.datetime.today() + + gdb.events.stop.connect(thread_stopped) + (gdb) file /tmp/hello + Reading symbols from /tmp/hello... + (gdb) start + Temporary breakpoint 1 at 0x401198: file /tmp/hello.c, line 18. + Starting program: /tmp/hello + + Temporary breakpoint 1, main () at /tmp/hello.c:18 + 18 printf ("Hello World\n"); + (gdb) python print(gdb.selected_inferior()._last_stop_time) + 2024-01-04 14:48:41.347036 + + +File: gdb.info, Node: Events In Python, Next: Threads In Python, Prev: Inferiors In Python, Up: Python API + +23.3.2.18 Events In Python +.......................... + +GDB provides a general event facility so that Python code can be +notified of various state changes, particularly changes that occur in +the inferior. + + An "event" is just an object that describes some state change. The +type of the object and its attributes will vary depending on the details +of the change. All the existing events are described below. + + In order to be notified of an event, you must register an event +handler with an "event registry". An event registry is an object in the +'gdb.events' module which dispatches particular events. A registry +provides methods to register and unregister event handlers: + + -- Function: EventRegistry.connect (object) + Add the given callable OBJECT to the registry. This object will be + called when an event corresponding to this registry occurs. + + -- Function: EventRegistry.disconnect (object) + Remove the given OBJECT from the registry. Once removed, the + object will no longer receive notifications of events. + + Here is an example: + + def exit_handler (event): + print ("event type: exit") + if hasattr (event, 'exit_code'): + print ("exit code: %d" % (event.exit_code)) + else: + print ("exit code not available") + + gdb.events.exited.connect (exit_handler) + + In the above example we connect our handler 'exit_handler' to the +registry 'events.exited'. Once connected, 'exit_handler' gets called +when the inferior exits. The argument "event" in this example is of +type 'gdb.ExitedEvent'. As you can see in the example the 'ExitedEvent' +object has an attribute which indicates the exit code of the inferior. + + Some events can be thread specific when GDB is running in non-stop +mode. When represented in Python, these events all extend +'gdb.ThreadEvent'. This event is a base class and is never emitted +directly; instead, events which are emitted by this or other modules +might extend this event. Examples of these events are +'gdb.BreakpointEvent' and 'gdb.ContinueEvent'. 'gdb.ThreadEvent' holds +the following attributes: + + -- Variable: ThreadEvent.inferior_thread + In non-stop mode this attribute will be set to the specific thread + which was involved in the emitted event. Otherwise, it will be set + to 'None'. + + The following is a listing of the event registries that are available +and details of the events they emit: + +'events.cont' + Emits 'gdb.ContinueEvent', which extends 'gdb.ThreadEvent'. This + event indicates that the inferior has been continued after a stop. + For inherited attribute refer to 'gdb.ThreadEvent' above. + +'events.exited' + Emits 'events.ExitedEvent', which indicates that the inferior has + exited. 'events.ExitedEvent' has two attributes: + + -- Variable: ExitedEvent.exit_code + An integer representing the exit code, if available, which the + inferior has returned. (The exit code could be unavailable + if, for example, GDB detaches from the inferior.) If the exit + code is unavailable, the attribute does not exist. + + -- Variable: ExitedEvent.inferior + A reference to the inferior which triggered the 'exited' + event. + +'events.stop' + Emits 'gdb.StopEvent', which extends 'gdb.ThreadEvent'. + + Indicates that the inferior has stopped. All events emitted by + this registry extend 'gdb.StopEvent'. As a child of + 'gdb.ThreadEvent', 'gdb.StopEvent' will indicate the stopped thread + when GDB is running in non-stop mode. Refer to 'gdb.ThreadEvent' + above for more details. + + 'gdb.StopEvent' has the following additional attributes: + + -- Variable: StopEvent.details + A dictionary holding any details relevant to the stop. The + exact keys and values depend on the type of stop, but are + identical to the corresponding MI output (*note GDB/MI Async + Records::). + + A dictionary was used for this (rather than adding attributes + directly to the event object) so that the MI keys could be + used unchanged. + + When a 'StopEvent' results from a 'finish' command, it will + also hold the return value from the function, if that is + available. This will be an entry named 'return-value' in the + 'details' dictionary. The value of this entry will be a + 'gdb.Value' object. + + Emits 'gdb.SignalEvent', which extends 'gdb.StopEvent'. + + This event indicates that the inferior or one of its threads has + received a signal. 'gdb.SignalEvent' has the following attributes: + + -- Variable: SignalEvent.stop_signal + A string representing the signal received by the inferior. A + list of possible signal values can be obtained by running the + command 'info signals' in the GDB command prompt. + + Also emits 'gdb.BreakpointEvent', which extends 'gdb.StopEvent'. + + 'gdb.BreakpointEvent' event indicates that one or more breakpoints + have been hit, and has the following attributes: + + -- Variable: BreakpointEvent.breakpoints + A sequence containing references to all the breakpoints (type + 'gdb.Breakpoint') that were hit. *Note Breakpoints In + Python::, for details of the 'gdb.Breakpoint' object. + + -- Variable: BreakpointEvent.breakpoint + A reference to the first breakpoint that was hit. This + attribute is maintained for backward compatibility and is now + deprecated in favor of the 'gdb.BreakpointEvent.breakpoints' + attribute. + +'events.new_objfile' + Emits 'gdb.NewObjFileEvent' which indicates that a new object file + has been loaded by GDB. 'gdb.NewObjFileEvent' has one attribute: + + -- Variable: NewObjFileEvent.new_objfile + A reference to the object file ('gdb.Objfile') which has been + loaded. *Note Objfiles In Python::, for details of the + 'gdb.Objfile' object. + +'events.free_objfile' + Emits 'gdb.FreeObjFileEvent' which indicates that an object file is + about to be removed from GDB. One reason this can happen is when + the inferior calls 'dlclose'. 'gdb.FreeObjFileEvent' has one + attribute: + + -- Variable: FreeObjFileEvent.objfile + A reference to the object file ('gdb.Objfile') which will be + unloaded. *Note Objfiles In Python::, for details of the + 'gdb.Objfile' object. + +'events.clear_objfiles' + Emits 'gdb.ClearObjFilesEvent' which indicates that the list of + object files for a program space has been reset. + 'gdb.ClearObjFilesEvent' has one attribute: + + -- Variable: ClearObjFilesEvent.progspace + A reference to the program space ('gdb.Progspace') whose + objfile list has been cleared. *Note Progspaces In Python::. + +'events.inferior_call' + Emits events just before and after a function in the inferior is + called by GDB. Before an inferior call, this emits an event of + type 'gdb.InferiorCallPreEvent', and after an inferior call, this + emits an event of type 'gdb.InferiorCallPostEvent'. + + 'gdb.InferiorCallPreEvent' + Indicates that a function in the inferior is about to be + called. + + -- Variable: InferiorCallPreEvent.ptid + The thread in which the call will be run. + + -- Variable: InferiorCallPreEvent.address + The location of the function to be called. + + 'gdb.InferiorCallPostEvent' + Indicates that a function in the inferior has just been + called. + + -- Variable: InferiorCallPostEvent.ptid + The thread in which the call was run. + + -- Variable: InferiorCallPostEvent.address + The location of the function that was called. + +'events.memory_changed' + Emits 'gdb.MemoryChangedEvent' which indicates that the memory of + the inferior has been modified by the GDB user, for instance via a + command like 'set *addr = value'. The event has the following + attributes: + + -- Variable: MemoryChangedEvent.address + The start address of the changed region. + + -- Variable: MemoryChangedEvent.length + Length in bytes of the changed region. + +'events.register_changed' + Emits 'gdb.RegisterChangedEvent' which indicates that a register in + the inferior has been modified by the GDB user. + + -- Variable: RegisterChangedEvent.frame + A gdb.Frame object representing the frame in which the + register was modified. + -- Variable: RegisterChangedEvent.regnum + Denotes which register was modified. + +'events.breakpoint_created' + This is emitted when a new breakpoint has been created. The + argument that is passed is the new 'gdb.Breakpoint' object. + +'events.breakpoint_modified' + This is emitted when a breakpoint has been modified in some way. + The argument that is passed is the new 'gdb.Breakpoint' object. + +'events.breakpoint_deleted' + This is emitted when a breakpoint has been deleted. The argument + that is passed is the 'gdb.Breakpoint' object. When this event is + emitted, the 'gdb.Breakpoint' object will already be in its invalid + state; that is, the 'is_valid' method will return 'False'. + +'events.before_prompt' + This event carries no payload. It is emitted each time GDB + presents a prompt to the user. + +'events.new_inferior' + This is emitted when a new inferior is created. Note that the + inferior is not necessarily running; in fact, it may not even have + an associated executable. + + The event is of type 'gdb.NewInferiorEvent'. This has a single + attribute: + + -- Variable: NewInferiorEvent.inferior + The new inferior, a 'gdb.Inferior' object. + +'events.inferior_deleted' + This is emitted when an inferior has been deleted. Note that this + is not the same as process exit; it is notified when the inferior + itself is removed, say via 'remove-inferiors'. + + The event is of type 'gdb.InferiorDeletedEvent'. This has a single + attribute: + + -- Variable: InferiorDeletedEvent.inferior + The inferior that is being removed, a 'gdb.Inferior' object. + +'events.new_thread' + This is emitted when GDB notices a new thread. The event is of + type 'gdb.NewThreadEvent', which extends 'gdb.ThreadEvent'. This + has a single attribute: + + -- Variable: NewThreadEvent.inferior_thread + The new thread. + +'events.thread_exited' + This is emitted when GDB notices a thread has exited. The event is + of type 'gdb.ThreadExitedEvent' which extends 'gdb.ThreadEvent'. + This has a single attribute: + + -- Variable: ThreadExitedEvent.inferior_thread + The exiting thread. + +'events.gdb_exiting' + This is emitted when GDB exits. This event is not emitted if GDB + exits as a result of an internal error, or after an unexpected + signal. The event is of type 'gdb.GdbExitingEvent', which has a + single attribute: + + -- Variable: GdbExitingEvent.exit_code + An integer, the value of the exit code GDB will return. + +'events.connection_removed' + This is emitted when GDB removes a connection (*note Connections In + Python::). The event is of type 'gdb.ConnectionEvent'. This has a + single read-only attribute: + + -- Variable: ConnectionEvent.connection + The 'gdb.TargetConnection' that is being removed. + +'events.executable_changed' + Emits 'gdb.ExecutableChangedEvent' which indicates that the + 'gdb.Progspace.executable_filename' has changed. + + This event is emitted when either the value of + 'gdb.Progspace.executable_filename ' has changed to name a + different file, or the executable file named by + 'gdb.Progspace.executable_filename' has changed on disk, and GDB + has therefore reloaded it. + + -- Variable: ExecutableChangedEvent.progspace + The 'gdb.Progspace' in which the current executable has + changed. The file name of the updated executable will be + visible in 'gdb.Progspace.executable_filename' (*note + Progspaces In Python::). + -- Variable: ExecutableChangedEvent.reload + This attribute will be 'True' if the value of + 'gdb.Progspace.executable_filename' didn't change, but the + file it names changed on disk instead, and GDB reloaded it. + + When this attribute is 'False', the value in + 'gdb.Progspace.executable_filename' was changed to name a + different file. + + Remember that GDB tracks the executable file and the symbol file + separately, these are visible as + 'gdb.Progspace.executable_filename' and 'gdb.Progspace.filename' + respectively. When using the 'file' command, GDB updates both of + these fields, but the executable file is updated first, so when + this event is emitted, the executable filename will have changed, + but the symbol filename might still hold its previous value. + +'events.new_progspace' + This is emitted when GDB adds a new program space (*note Program + Spaces In Python: Progspaces In Python.). The event is of type + 'gdb.NewProgspaceEvent', and has a single read-only attribute: + + -- Variable: NewProgspaceEvent.progspace + The 'gdb.Progspace' that was added to GDB. + + No 'NewProgspaceEvent' is emitted for the very first program space, + which is assigned to the first inferior. This first program space + is created within GDB before any Python scripts are sourced. + +'events.free_progspace' + This is emitted when GDB removes a program space (*note Program + Spaces In Python: Progspaces In Python.), for example as a result + of the 'remove-inferiors' command (*note 'remove-inferiors': + remove_inferiors_cli.). The event is of type + 'gdb.FreeProgspaceEvent', and has a single read-only attribute: + + -- Variable: FreeProgspaceEvent.progspace + The 'gdb.Progspace' that is about to be removed from GDB. + +'events.tui_enabled' + This is emitted when the TUI is enabled or disabled. The event is + of type 'gdb.TuiEnabledEvent', which has a single read-only + attribute: + + -- Variable: TuiEnabledEvent.enabled + If the TUI has just been enabled, this is 'True'; otherwise it + is 'False'. + + +File: gdb.info, Node: Threads In Python, Next: Recordings In Python, Prev: Events In Python, Up: Python API + +23.3.2.19 Threads In Python +........................... + +Python scripts can access information about, and manipulate inferior +threads controlled by GDB, via objects of the 'gdb.InferiorThread' +class. + + The following thread-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_thread () + This function returns the thread object for the selected thread. + If there is no selected thread, this will return 'None'. + + To get the list of threads for an inferior, use the +'Inferior.threads()' method. *Note Inferiors In Python::. + + A 'gdb.InferiorThread' object has the following attributes: + + -- Variable: InferiorThread.name + The name of the thread. If the user specified a name using 'thread + name', then this returns that name. Otherwise, if an OS-supplied + name is available, then it is returned. Otherwise, this returns + 'None'. + + This attribute can be assigned to. The new value must be a string + object, which sets the new name, or 'None', which removes any + user-specified thread name. + + -- Variable: InferiorThread.num + The per-inferior number of the thread, as assigned by GDB. + + -- Variable: InferiorThread.global_num + The global ID of the thread, as assigned by GDB. You can use this + to make Python breakpoints thread-specific, for example (*note The + Breakpoint.thread attribute: python_breakpoint_thread.). + + -- Variable: InferiorThread.ptid + ID of the thread, as assigned by the operating system. This + attribute is a tuple containing three integers. The first is the + Process ID (PID); the second is the Lightweight Process ID (LWPID), + and the third is the Thread ID (TID). Either the LWPID or TID may + be 0, which indicates that the operating system does not use that + identifier. + + -- Variable: InferiorThread.ptid_string + This read-only attribute contains a string representing + 'InferiorThread.ptid'. This is the string that GDB uses in the + 'Target Id' column in the 'info threads' output (*note 'info + threads': info_threads.). + + -- Variable: InferiorThread.inferior + The inferior this thread belongs to. This attribute is represented + as a 'gdb.Inferior' object. This attribute is not writable. + + -- Variable: InferiorThread.details + A string containing target specific thread state information. The + format of this string varies by target. If there is no additional + state information for this thread, then this attribute contains + 'None'. + + For example, on a GNU/Linux system, a thread that is in the process + of exiting will return the string 'Exiting'. For remote targets + the 'details' string will be obtained with the 'qThreadExtraInfo' + remote packet, if the target supports it (*note 'qThreadExtraInfo': + qThreadExtraInfo.). + + GDB displays the 'details' string as part of the 'Target Id' + column, in the 'info threads' output (*note 'info threads': + info_threads.). + + A 'gdb.InferiorThread' object has the following methods: + + -- Function: InferiorThread.is_valid () + Returns 'True' if the 'gdb.InferiorThread' object is valid, 'False' + if not. A 'gdb.InferiorThread' object will become invalid if the + thread exits, or the inferior that the thread belongs is deleted. + All other 'gdb.InferiorThread' methods will throw an exception if + it is invalid at the time the method is called. + + -- Function: InferiorThread.switch () + This changes GDB's currently selected thread to the one represented + by this object. + + -- Function: InferiorThread.is_stopped () + Return a Boolean indicating whether the thread is stopped. + + -- Function: InferiorThread.is_running () + Return a Boolean indicating whether the thread is running. + + -- Function: InferiorThread.is_exited () + Return a Boolean indicating whether the thread is exited. + + -- Function: InferiorThread.handle () + Return the thread object's handle, represented as a Python 'bytes' + object. A 'gdb.Value' representation of the handle may be + constructed via 'gdb.Value(bufobj, type)' where BUFOBJ is the + Python 'bytes' representation of the handle and TYPE is a + 'gdb.Type' for the handle type. + + One may add arbitrary attributes to 'gdb.InferiorThread' objects in +the usual Python way. This is useful if, for example, one needs to do +some extra record keeping associated with the thread. + + *Note choosing attribute names::, for guidance on selecting a +suitable name for new attributes. + + In this contrived example we record the time when a thread last +stopped: + + (gdb) python + import datetime + + def thread_stopped(event): + if event.inferior_thread is not None: + thread = event.inferior_thread + else: + thread = gdb.selected_thread() + thread._last_stop_time = datetime.datetime.today() + + gdb.events.stop.connect(thread_stopped) + (gdb) file /tmp/hello + Reading symbols from /tmp/hello... + (gdb) start + Temporary breakpoint 1 at 0x401198: file /tmp/hello.c, line 18. + Starting program: /tmp/hello + + Temporary breakpoint 1, main () at /tmp/hello.c:18 + 18 printf ("Hello World\n"); + (gdb) python print(gdb.selected_thread()._last_stop_time) + 2024-01-04 14:48:41.347036 + + +File: gdb.info, Node: Recordings In Python, Next: CLI Commands In Python, Prev: Threads In Python, Up: Python API + +23.3.2.20 Recordings In Python +.............................. + +The following recordings-related functions (*note Process Record and +Replay::) are available in the 'gdb' module: + + -- Function: gdb.start_recording ([method], [format]) + Start a recording using the given METHOD and FORMAT. If no FORMAT + is given, the default format for the recording method is used. If + no METHOD is given, the default method will be used. Returns a + 'gdb.Record' object on success. Throw an exception on failure. + + The following strings can be passed as METHOD: + + * '"full"' + * '"btrace"': Possible values for FORMAT: '"pt"', '"bts"' or + leave out for default format. + + -- Function: gdb.current_recording () + Access a currently running recording. Return a 'gdb.Record' object + on success. Return 'None' if no recording is currently active. + + -- Function: gdb.stop_recording () + Stop the current recording. Throw an exception if no recording is + currently active. All record objects become invalid after this + call. + + A 'gdb.Record' object has the following attributes: + + -- Variable: Record.method + A string with the current recording method, e.g. 'full' or + 'btrace'. + + -- Variable: Record.format + A string with the current recording format, e.g. 'bt', 'pts' or + 'None'. + + -- Variable: Record.begin + A method specific instruction object representing the first + instruction in this recording. + + -- Variable: Record.end + A method specific instruction object representing the current + instruction, that is not actually part of the recording. + + -- Variable: Record.replay_position + The instruction representing the current replay position. If there + is no replay active, this will be 'None'. + + -- Variable: Record.instruction_history + A list with all recorded instructions. + + -- Variable: Record.function_call_history + A list with all recorded function call segments. + + A 'gdb.Record' object has the following methods: + + -- Function: Record.goto (instruction) + Move the replay position to the given INSTRUCTION. + + -- Function: Record.clear () + Clear the trace data of the current recording. This forces + re-decoding of the trace for successive commands. + + The common 'gdb.Instruction' class that recording method specific +instruction objects inherit from, has the following attributes: + + -- Variable: Instruction.pc + An integer representing this instruction's address. + + -- Variable: Instruction.data + A 'memoryview' object holding the raw instruction data. + + -- Variable: Instruction.decoded + A human readable string with the disassembled instruction. + + -- Variable: Instruction.size + The size of the instruction in bytes. + + Additionally 'gdb.RecordInstruction' has the following attributes: + + -- Variable: RecordInstruction.number + An integer identifying this instruction. 'number' corresponds to + the numbers seen in 'record instruction-history' (*note Process + Record and Replay::). + + -- Variable: RecordInstruction.sal + A 'gdb.Symtab_and_line' object representing the associated symtab + and line of this instruction. May be 'None' if no debug + information is available. + + -- Variable: RecordInstruction.is_speculative + A boolean indicating whether the instruction was executed + speculatively. + + If an error occurred during recording or decoding a recording, this +error is represented by a 'gdb.RecordGap' object in the instruction +list. It has the following attributes: + + -- Variable: RecordGap.number + An integer identifying this gap. 'number' corresponds to the + numbers seen in 'record instruction-history' (*note Process Record + and Replay::). + + -- Variable: RecordGap.error_code + A numerical representation of the reason for the gap. The value is + specific to the current recording method. + + -- Variable: RecordGap.error_string + A human readable string with the reason for the gap. + + Some GDB features write auxiliary information into the execution +history. This information is represented by a 'gdb.RecordAuxiliary' +object in the instruction list. It has the following attributes: + + -- Variable: RecordAuxiliary.NUMBER + An integer identifying this auxiliary. NUMBER corresponds to the + numbers seen in 'record instruction-history' (*note Process Record + and Replay::). + + -- Variable: RecordAuxiliary.data + A string representation of the auxiliary data. + + A 'gdb.RecordFunctionSegment' object has the following attributes: + + -- Variable: RecordFunctionSegment.number + An integer identifying this function segment. 'number' corresponds + to the numbers seen in 'record function-call-history' (*note + Process Record and Replay::). + + -- Variable: RecordFunctionSegment.symbol + A 'gdb.Symbol' object representing the associated symbol. May be + 'None' if no debug information is available. + + -- Variable: RecordFunctionSegment.level + An integer representing the function call's stack level. May be + 'None' if the function call is a gap. + + -- Variable: RecordFunctionSegment.instructions + A list of 'gdb.RecordInstruction' or 'gdb.RecordGap' objects + associated with this function call. + + -- Variable: RecordFunctionSegment.up + A 'gdb.RecordFunctionSegment' object representing the caller's + function segment. If the call has not been recorded, this will be + the function segment to which control returns. If neither the call + nor the return have been recorded, this will be 'None'. + + -- Variable: RecordFunctionSegment.prev + A 'gdb.RecordFunctionSegment' object representing the previous + segment of this function call. May be 'None'. + + -- Variable: RecordFunctionSegment.next + A 'gdb.RecordFunctionSegment' object representing the next segment + of this function call. May be 'None'. + + The following example demonstrates the usage of these objects and +functions to create a function that will rewind a record to the last +time a function in a different file was executed. This would typically +be used to track the execution of user provided callback functions in a +library which typically are not visible in a back trace. + + def bringback (): + rec = gdb.current_recording () + if not rec: + return + + insn = rec.instruction_history + if len (insn) == 0: + return + + try: + position = insn.index (rec.replay_position) + except: + position = -1 + try: + filename = insn[position].sal.symtab.fullname () + except: + filename = None + + for i in reversed (insn[:position]): + try: + current = i.sal.symtab.fullname () + except: + current = None + + if filename == current: + continue + + rec.goto (i) + return + + Another possible application is to write a function that counts the +number of code executions in a given line range. This line range can +contain parts of functions or span across several functions and is not +limited to be contiguous. + + def countrange (filename, linerange): + count = 0 + + def filter_only (file_name): + for call in gdb.current_recording ().function_call_history: + try: + if file_name in call.symbol.symtab.fullname (): + yield call + except: + pass + + for c in filter_only (filename): + for i in c.instructions: + try: + if i.sal.line in linerange: + count += 1 + break; + except: + pass + + return count + + +File: gdb.info, Node: CLI Commands In Python, Next: GDB/MI Commands In Python, Prev: Recordings In Python, Up: Python API + +23.3.2.21 CLI Commands In Python +................................ + +You can implement new GDB CLI commands in Python. A CLI command is +implemented using an instance of the 'gdb.Command' class, most commonly +using a subclass. + + -- Function: Command.__init__ (name, command_class [, completer_class + [, prefix]]) + The object initializer for 'Command' registers the new command with + GDB. This initializer is normally invoked from the subclass' own + '__init__' method. + + NAME is the name of the command. If NAME consists of multiple + words, then the initial words are looked for as prefix commands. + In this case, if one of the prefix commands does not exist, an + exception is raised. + + There is no support for multi-line commands. + + COMMAND_CLASS should be one of the 'COMMAND_' constants defined + below. This argument tells GDB how to categorize the new command + in the help system. + + COMPLETER_CLASS is an optional argument. If given, it should be + one of the 'COMPLETE_' constants defined below. This argument + tells GDB how to perform completion for this command. If not + given, GDB will attempt to complete using the object's 'complete' + method (see below); if no such method is found, an error will occur + when completion is attempted. + + PREFIX is an optional argument. If 'True', then the new command is + a prefix command; sub-commands of this command may be registered. + + The help text for the new command is taken from the Python + documentation string for the command's class, if there is one. If + no documentation string is provided, the default value "This + command is not documented." is used. + + -- Function: Command.dont_repeat () + By default, a GDB command is repeated when the user enters a blank + line at the command prompt. A command can suppress this behavior + by invoking the 'dont_repeat' method at some point in its 'invoke' + method (normally this is done early in case of exception). This is + similar to the user command 'dont-repeat', see *note dont-repeat: + Define. + + -- Function: Command.invoke (argument, from_tty) + This method is called by GDB when this command is invoked. + + ARGUMENT is a string. It is the argument to the command, after + leading and trailing whitespace has been stripped. + + FROM_TTY is a boolean argument. When true, this means that the + command was entered by the user at the terminal; when false it + means that the command came from elsewhere. + + If this method throws an exception, it is turned into a GDB 'error' + call. Otherwise, the return value is ignored. + + To break ARGUMENT up into an argv-like string use + 'gdb.string_to_argv'. This function behaves identically to GDB's + internal argument lexer 'buildargv'. It is recommended to use this + for consistency. Arguments are separated by spaces and may be + quoted. Example: + + print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") + ['1', '2 "3', '4 "5', "6 '7"] + + -- Function: Command.complete (text, word) + This method is called by GDB when the user attempts completion on + this command. All forms of completion are handled by this method, + that is, the and key bindings (*note Completion::), and + the 'complete' command (*note complete: Help.). + + The arguments TEXT and WORD are both strings; TEXT holds the + complete command line up to the cursor's location, while WORD holds + the last word of the command line; this is computed using a + word-breaking heuristic. + + The 'complete' method can return several values: + * If the return value is a sequence, the contents of the + sequence are used as the completions. It is up to 'complete' + to ensure that the contents actually do complete the word. A + zero-length sequence is allowed, it means that there were no + completions available. Only string elements of the sequence + are used; other elements in the sequence are ignored. + + * If the return value is one of the 'COMPLETE_' constants + defined below, then the corresponding GDB-internal completion + function is invoked, and its result is used. + + * All other results are treated as though there were no + available completions. + + When a new command is registered, it must be declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the 'gdb' module: + +'gdb.COMMAND_NONE' + The command does not belong to any particular class. A command in + this category will not be displayed in any of the help categories. + +'gdb.COMMAND_RUNNING' + The command is related to running the inferior. For example, + 'start', 'step', and 'continue' are in this category. Type 'help + running' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_DATA' + The command is related to data or variables. For example, 'call', + 'find', and 'print' are in this category. Type 'help data' at the + GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STACK' + The command has to do with manipulation of the stack. For example, + 'backtrace', 'frame', and 'return' are in this category. Type + 'help stack' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_FILES' + This class is used for file-related commands. For example, 'file', + 'list' and 'section' are in this category. Type 'help files' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_SUPPORT' + This should be used for "support facilities", generally meaning + things that are useful to the user when interacting with GDB, but + not related to the state of the inferior. For example, 'help', + 'make', and 'shell' are in this category. Type 'help support' at + the GDB prompt to see a list of commands in this category. + +'gdb.COMMAND_STATUS' + The command is an 'info'-related command, that is, related to the + state of GDB itself. For example, 'info', 'macro', and 'show' are + in this category. Type 'help status' at the GDB prompt to see a + list of commands in this category. + +'gdb.COMMAND_BREAKPOINTS' + The command has to do with breakpoints. For example, 'break', + 'clear', and 'delete' are in this category. Type 'help + breakpoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_TRACEPOINTS' + The command has to do with tracepoints. For example, 'trace', + 'actions', and 'tfind' are in this category. Type 'help + tracepoints' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_TUI' + The command has to do with the text user interface (*note TUI::). + Type 'help tui' at the GDB prompt to see a list of commands in this + category. + +'gdb.COMMAND_USER' + The command is a general purpose command for the user, and + typically does not fit in one of the other categories. Type 'help + user-defined' at the GDB prompt to see a list of commands in this + category, as well as the list of gdb macros (*note Sequences::). + +'gdb.COMMAND_OBSCURE' + The command is only used in unusual circumstances, or is not of + general interest to users. For example, 'checkpoint', 'fork', and + 'stop' are in this category. Type 'help obscure' at the GDB prompt + to see a list of commands in this category. + +'gdb.COMMAND_MAINTENANCE' + The command is only useful to GDB maintainers. The 'maintenance' + and 'flushregs' commands are in this category. Type 'help + internals' at the GDB prompt to see a list of commands in this + category. + + A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it from +the 'complete' method. These predefined completion constants are all +defined in the 'gdb' module: + +'gdb.COMPLETE_NONE' + This constant means that no completion should be done. + +'gdb.COMPLETE_FILENAME' + This constant means that filename completion should be performed. + +'gdb.COMPLETE_LOCATION' + This constant means that location completion should be done. *Note + Location Specifications::. + +'gdb.COMPLETE_COMMAND' + This constant means that completion should examine GDB command + names. + +'gdb.COMPLETE_SYMBOL' + This constant means that completion should be done using symbol + names as the source. + +'gdb.COMPLETE_EXPRESSION' + This constant means that completion should be done on expressions. + Often this means completing on symbol names, but some language + parsers also have support for completing on field names. + + The following code snippet shows how a trivial CLI command can be +implemented in Python: + + class HelloWorld (gdb.Command): + """Greet the whole world.""" + + def __init__ (self): + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + + def invoke (self, arg, from_tty): + print ("Hello, World!") + + HelloWorld () + + The last line instantiates the class, and is necessary to trigger the +registration of the command with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + +File: gdb.info, Node: GDB/MI Commands In Python, Next: GDB/MI Notifications In Python, Prev: CLI Commands In Python, Up: Python API + +23.3.2.22 GDB/MI Commands In Python +................................... + +It is possible to add GDB/MI (*note GDB/MI::) commands implemented in +Python. A GDB/MI command is implemented using an instance of the +'gdb.MICommand' class, most commonly using a subclass. + + -- Function: MICommand.__init__ (name) + The object initializer for 'MICommand' registers the new command + with GDB. This initializer is normally invoked from the subclass' + own '__init__' method. + + NAME is the name of the command. It must be a valid name of a + GDB/MI command, and in particular must start with a hyphen ('-'). + Reusing the name of a built-in GDB/MI is not allowed, and a + 'RuntimeError' will be raised. Using the name of an GDB/MI command + previously defined in Python is allowed, the previous command will + be replaced with the new command. + + -- Function: MICommand.invoke (arguments) + This method is called by GDB when the new MI command is invoked. + + ARGUMENTS is a list of strings. Note, that '--thread' and + '--frame' arguments are handled by GDB itself therefore they do not + show up in 'arguments'. + + If this method raises an exception, then it is turned into a GDB/MI + '^error' response. Only 'gdb.GdbError' exceptions (or its + sub-classes) should be used for reporting errors to users, any + other exception type is treated as a failure of the 'invoke' + method, and the exception will be printed to the error stream + according to the 'set python print-stack' setting (*note 'set + python print-stack': set_python_print_stack.). + + If this method returns 'None', then the GDB/MI command will return + a '^done' response with no additional values. + + Otherwise, the return value must be a dictionary, which is + converted to a GDB/MI RESULT-RECORD (*note GDB/MI Output Syntax::). + The keys of this dictionary must be strings, and are used as + VARIABLE names in the RESULT-RECORD, these strings must comply with + the naming rules detailed below. The values of this dictionary are + recursively handled as follows: + + * If the value is Python sequence or iterator, it is converted + to GDB/MI LIST with elements converted recursively. + + * If the value is Python dictionary, it is converted to GDB/MI + TUPLE. Keys in that dictionary must be strings, which comply + with the VARIABLE naming rules detailed below. Values are + converted recursively. + + * Otherwise, value is first converted to a Python string using + 'str ()' and then converted to GDB/MI CONST. + + The strings used for VARIABLE names in the GDB/MI output must + follow the following rules; the string must be at least one + character long, the first character must be in the set '[a-zA-Z]', + while every subsequent character must be in the set + '[-_a-zA-Z0-9]'. + + An instance of 'MICommand' has the following attributes: + + -- Variable: MICommand.name + A string, the name of this GDB/MI command, as was passed to the + '__init__' method. This attribute is read-only. + + -- Variable: MICommand.installed + A boolean value indicating if this command is installed ready for a + user to call from the command line. Commands are automatically + installed when they are instantiated, after which this attribute + will be 'True'. + + If later, a new command is created with the same name, then the + original command will become uninstalled, and this attribute will + be 'False'. + + This attribute is read-write, setting this attribute to 'False' + will uninstall the command, removing it from the set of available + commands. Setting this attribute to 'True' will install the + command for use. If there is already a Python command with this + name installed, the currently installed command will be + uninstalled, and this command installed in its stead. + + The following code snippet shows how some trivial MI commands can be +implemented in Python: + + class MIEcho(gdb.MICommand): + """Echo arguments passed to the command.""" + + def __init__(self, name, mode): + self._mode = mode + super(MIEcho, self).__init__(name) + + def invoke(self, argv): + if self._mode == 'dict': + return { 'dict': { 'argv' : argv } } + elif self._mode == 'list': + return { 'list': argv } + else: + return { 'string': ", ".join(argv) } + + + MIEcho("-echo-dict", "dict") + MIEcho("-echo-list", "list") + MIEcho("-echo-string", "string") + + The last three lines instantiate the class three times, creating +three new GDB/MI commands '-echo-dict', '-echo-list', and +'-echo-string'. Each time a subclass of 'gdb.MICommand' is +instantiated, the new command is automatically registered with GDB. + + Depending on how the Python code is read into GDB, you may need to +import the 'gdb' module explicitly. + + The following example shows a GDB session in which the above commands +have been added: + + (gdb) + -echo-dict abc def ghi + ^done,dict={argv=["abc","def","ghi"]} + (gdb) + -echo-list abc def ghi + ^done,list=["abc","def","ghi"] + (gdb) + -echo-string abc def ghi + ^done,string="abc, def, ghi" + (gdb) + + Conversely, it is possible to execute GDB/MI commands from Python, +with the results being a Python object and not a specially-formatted +string. This is done with the 'gdb.execute_mi' function. + + -- Function: gdb.execute_mi (command [, arg ]...) + Invoke a GDB/MI command. COMMAND is the name of the command, a + string. The arguments, ARG, are passed to the command. Each + argument must also be a string. + + This function returns a Python dictionary whose contents reflect + the corresponding GDB/MI command's output. Refer to the + documentation for these commands for details. Lists are + represented as Python lists, and tuples are represented as Python + dictionaries. + + If the command fails, it will raise a Python exception. + + Here is how this works using the commands from the example above: + + (gdb) python print(gdb.execute_mi("-echo-dict", "abc", "def", "ghi")) + {'dict': {'argv': ['abc', 'def', 'ghi']}} + (gdb) python print(gdb.execute_mi("-echo-list", "abc", "def", "ghi")) + {'list': ['abc', 'def', 'ghi']} + (gdb) python print(gdb.execute_mi("-echo-string", "abc", "def", "ghi")) + {'string': 'abc, def, ghi'} + + +File: gdb.info, Node: GDB/MI Notifications In Python, Next: Parameters In Python, Prev: GDB/MI Commands In Python, Up: Python API + +23.3.2.23 GDB/MI Notifications In Python +........................................ + +It is possible to emit GDB/MI notifications from Python. Use the +'gdb.notify_mi' function to do that. + + -- Function: gdb.notify_mi (name [, data]) + Emit a GDB/MI asynchronous notification. NAME is the name of the + notification, consisting of alphanumeric characters and a hyphen + ('-'). DATA is any additional data to be emitted with the + notification, passed as a Python dictionary. This argument is + optional. The dictionary is converted to a GDB/MI RESULT records + (*note GDB/MI Output Syntax::) the same way as result of Python MI + command (*note GDB/MI Commands In Python::). + + If DATA is 'None' then no additional values are emitted. + + While using existing notification names (*note GDB/MI Async +Records::) with 'gdb.notify_mi' is allowed, users are encouraged to +prefix user-defined notification with a hyphen ('-') to avoid possible +conflict. GDB will never introduce notification starting with hyphen. + + Here is how to emit '=-connection-removed' whenever a connection to +remote GDB server is closed (*note Connections In Python::): + + def notify_connection_removed(event): + data = {"id": event.connection.num, "type": event.connection.type} + gdb.notify_mi("-connection-removed", data) + + + gdb.events.connection_removed.connect(notify_connection_removed) + + Then, each time a connection is closed, there will be a notification +on MI channel: + + =-connection-removed,id="1",type="remote" + + +File: gdb.info, Node: Parameters In Python, Next: Functions In Python, Prev: GDB/MI Notifications In Python, Up: Python API + +23.3.2.24 Parameters In Python +.............................. + +You can implement new GDB parameters using Python. A new parameter is +implemented as an instance of the 'gdb.Parameter' class. + + Parameters are exposed to the user via the 'set' and 'show' commands. +*Note Help::. + + There are many parameters that already exist and can be set in GDB. +Two examples are: 'set follow fork' and 'set charset'. Setting these +parameters influences certain behavior in GDB. Similarly, you can +define parameters that can be used to influence behavior in custom +Python scripts and commands. + + -- Function: Parameter.__init__ (name, command_class, parameter_class + [, enum_sequence]) + The object initializer for 'Parameter' registers the new parameter + with GDB. This initializer is normally invoked from the subclass' + own '__init__' method. + + NAME is the name of the new parameter. If NAME consists of + multiple words, then the initial words are looked for as prefix + parameters. An example of this can be illustrated with the 'set + print' set of parameters. If NAME is 'print foo', then 'print' + will be searched as the prefix parameter. In this case the + parameter can subsequently be accessed in GDB as 'set print foo'. + + If NAME consists of multiple words, and no prefix parameter group + can be found, an exception is raised. + + COMMAND_CLASS should be one of the 'COMMAND_' constants (*note CLI + Commands In Python::). This argument tells GDB how to categorize + the new parameter in the help system. + + PARAMETER_CLASS should be one of the 'PARAM_' constants defined + below. This argument tells GDB the type of the new parameter; this + information is used for input validation and completion. + + If PARAMETER_CLASS is 'PARAM_ENUM', then ENUM_SEQUENCE must be a + sequence of strings. These strings represent the possible values + for the parameter. + + If PARAMETER_CLASS is not 'PARAM_ENUM', then the presence of a + fourth argument will cause an exception to be thrown. + + The help text for the new parameter includes the Python + documentation string from the parameter's class, if there is one. + If there is no documentation string, a default value is used. The + documentation string is included in the output of the parameters + 'help set' and 'help show' commands, and should be written taking + this into account. + + -- Variable: Parameter.set_doc + If this attribute exists, and is a string, then its value is used + as the first part of the help text for this parameter's 'set' + command. The second part of the help text is taken from the + documentation string for the parameter's class, if there is one. + + The value of 'set_doc' should give a brief summary specific to the + set action, this text is only displayed when the user runs the + 'help set' command for this parameter. The class documentation + should be used to give a fuller description of what the parameter + does, this text is displayed for both the 'help set' and 'help + show' commands. + + The 'set_doc' value is examined when 'Parameter.__init__' is + invoked; subsequent changes have no effect. + + -- Variable: Parameter.show_doc + If this attribute exists, and is a string, then its value is used + as the first part of the help text for this parameter's 'show' + command. The second part of the help text is taken from the + documentation string for the parameter's class, if there is one. + + The value of 'show_doc' should give a brief summary specific to the + show action, this text is only displayed when the user runs the + 'help show' command for this parameter. The class documentation + should be used to give a fuller description of what the parameter + does, this text is displayed for both the 'help set' and 'help + show' commands. + + The 'show_doc' value is examined when 'Parameter.__init__' is + invoked; subsequent changes have no effect. + + -- Variable: Parameter.value + The 'value' attribute holds the underlying value of the parameter. + It can be read and assigned to just as any other attribute. GDB + does validation when assignments are made. + + There are two methods that may be implemented in any 'Parameter' +class. These are: + + -- Function: Parameter.get_set_string (self) + If this method exists, GDB will call it when a PARAMETER's value + has been changed via the 'set' API (for example, 'set foo off'). + The 'value' attribute has already been populated with the new value + and may be used in output. This method must return a string. If + the returned string is not empty, GDB will present it to the user. + + If this method raises the 'gdb.GdbError' exception (*note Exception + Handling::), then GDB will print the exception's string and the + 'set' command will fail. Note, however, that the 'value' attribute + will not be reset in this case. So, if your parameter must + validate values, it should store the old value internally and reset + the exposed value, like so: + + class ExampleParam (gdb.Parameter): + def __init__ (self, name): + super (ExampleParam, self).__init__ (name, + gdb.COMMAND_DATA, + gdb.PARAM_BOOLEAN) + self.value = True + self.saved_value = True + def validate(self): + return False + def get_set_string (self): + if not self.validate(): + self.value = self.saved_value + raise gdb.GdbError('Failed to validate') + self.saved_value = self.value + return "" + + -- Function: Parameter.get_show_string (self, svalue) + GDB will call this method when a PARAMETER's 'show' API has been + invoked (for example, 'show foo'). The argument 'svalue' receives + the string representation of the current value. This method must + return a string. + + When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the 'gdb' +module: + +'gdb.PARAM_BOOLEAN' + The value is a plain boolean. The Python boolean values, 'True' + and 'False' are the only valid values. + +'gdb.PARAM_AUTO_BOOLEAN' + The value has three possible states: true, false, and 'auto'. In + Python, true and false are represented using boolean constants, and + 'auto' is represented using 'None'. + +'gdb.PARAM_UINTEGER' + The value is an unsigned integer. The value of 'None' should be + interpreted to mean "unlimited" (literal ''unlimited'' can also be + used to set that value), and the value of 0 is reserved and should + not be used. + +'gdb.PARAM_INTEGER' + The value is a signed integer. The value of 'None' should be + interpreted to mean "unlimited" (literal ''unlimited'' can also be + used to set that value), and the value of 0 is reserved and should + not be used. + +'gdb.PARAM_STRING' + The value is a string. When the user modifies the string, any + escape sequences, such as '\t', '\f', and octal escapes, are + translated into corresponding characters and encoded into the + current host charset. + +'gdb.PARAM_STRING_NOESCAPE' + The value is a string. When the user modifies the string, escapes + are passed through untranslated. + +'gdb.PARAM_OPTIONAL_FILENAME' + The value is a either a filename (a string), or 'None'. + +'gdb.PARAM_FILENAME' + The value is a filename. This is just like + 'PARAM_STRING_NOESCAPE', but uses file names for completion. + +'gdb.PARAM_ZINTEGER' + The value is a signed integer. This is like 'PARAM_INTEGER', + except that 0 is allowed and the value of 'None' is not supported. + +'gdb.PARAM_ZUINTEGER' + The value is an unsigned integer. This is like 'PARAM_UINTEGER', + except that 0 is allowed and the value of 'None' is not supported. + +'gdb.PARAM_ZUINTEGER_UNLIMITED' + The value is a signed integer. This is like 'PARAM_INTEGER' + including that the value of 'None' should be interpreted to mean + "unlimited" (literal ''unlimited'' can also be used to set that + value), except that 0 is allowed, and the value cannot be negative, + except the special value -1 is returned for the setting of + "unlimited". + +'gdb.PARAM_ENUM' + The value is a string, which must be one of a collection string + constants provided when the parameter is created. + + +File: gdb.info, Node: Functions In Python, Next: Progspaces In Python, Prev: Parameters In Python, Up: Python API + +23.3.2.25 Writing new convenience functions +........................................... + +You can implement new convenience functions (*note Convenience Vars::) +in Python. A convenience function is an instance of a subclass of the +class 'gdb.Function'. + + -- Function: Function.__init__ (name) + The initializer for 'Function' registers the new function with GDB. + The argument NAME is the name of the function, a string. The + function will be visible to the user as a convenience variable of + type 'internal function', whose name is the same as the given NAME. + + The documentation for the new function is taken from the + documentation string for the new class. + + -- Function: Function.invoke (*args) + When a convenience function is evaluated, its arguments are + converted to instances of 'gdb.Value', and then the function's + 'invoke' method is called. Note that GDB does not predetermine the + arity of convenience functions. Instead, all available arguments + are passed to 'invoke', following the standard Python calling + convention. In particular, a convenience function can have default + values for parameters without ill effect. + + The return value of this method is used as its value in the + enclosing expression. If an ordinary Python value is returned, it + is converted to a 'gdb.Value' following the usual rules. + + The following code snippet shows how a trivial convenience function +can be implemented in Python: + + class Greet (gdb.Function): + """Return string to greet someone. + Takes a name as argument.""" + + def __init__ (self): + super (Greet, self).__init__ ("greet") + + def invoke (self, name): + return "Hello, %s!" % name.string () + + Greet () + + The last line instantiates the class, and is necessary to trigger the +registration of the function with GDB. Depending on how the Python code +is read into GDB, you may need to import the 'gdb' module explicitly. + + Now you can use the function in an expression: + + (gdb) print $greet("Bob") + $1 = "Hello, Bob!" + + +File: gdb.info, Node: Progspaces In Python, Next: Objfiles In Python, Prev: Functions In Python, Up: Python API + +23.3.2.26 Program Spaces In Python +.................................. + +A program space, or "progspace", represents a symbolic view of an +address space. It consists of all of the objfiles of the program. +*Note Objfiles In Python::. *Note program spaces: Inferiors Connections +and Programs, for more details about program spaces. + + The following progspace-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_progspace () + This function returns the program space of the currently selected + inferior. *Note Inferiors Connections and Programs::. This is + identical to 'gdb.selected_inferior().progspace' (*note Inferiors + In Python::) and is included for historical compatibility. + + -- Function: gdb.progspaces () + Return a sequence of all the progspaces currently known to GDB. + + Each progspace is represented by an instance of the 'gdb.Progspace' +class. + + -- Variable: Progspace.filename + The file name, as a string, of the main symbol file (from which + debug symbols have been loaded) for the progspace, e.g. the + argument to the 'symbol-file' or 'file' commands. + + If there is no main symbol table currently loaded, then this + attribute will be 'None'. + + -- Variable: Progspace.symbol_file + The 'gdb.Objfile' representing the main symbol file (from which + debug symbols have been loaded) for the 'gdb.Progspace'. This is + the symbol file set by the 'symbol-file' or 'file' commands. + + This will be the 'gdb.Objfile' representing 'Progspace.filename' + when 'Progspace.filename' is not 'None'. + + If there is no main symbol table currently loaded, then this + attribute will be 'None'. + + If the 'Progspace' is invalid, i.e., when 'Progspace.is_valid()' + returns 'False', then attempting to access this attribute will + raise a 'RuntimeError' exception. + + -- Variable: Progspace.executable_filename + The file name, as a string, of the executable file in use by this + program space. The executable file is the file that GDB will + invoke in order to start an inferior when using a native target. + The file name within this attribute is updated by the 'exec-file' + and 'file' commands. + + If no executable is currently set within this 'Progspace' then this + attribute contains 'None'. + + If the 'Progspace' is invalid, i.e., when 'Progspace.is_valid()' + returns 'False', then attempting to access this attribute will + raise a 'RuntimeError' exception. + + -- Variable: Progspace.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Progspace.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Progspace.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + -- Variable: Progspace.missing_file_handlers + The 'missing_file_handlers' attribute is a list of tuples. Each + tuple holds a missing-file handler object for this program space. + For more information, *note Missing Debug Info In Python::, and + *note Missing Objfiles In Python::. + + A program space has the following methods: + + -- Function: Progspace.block_for_pc (pc) + Return the innermost 'gdb.Block' containing the given PC value. If + the block cannot be found for the PC value specified, the function + will return 'None'. + + -- Function: Progspace.find_pc_line (pc) + Return the 'gdb.Symtab_and_line' object corresponding to the PC + value. *Note Symbol Tables In Python::. If an invalid value of PC + is passed as an argument, then the 'symtab' and 'line' attributes + of the returned 'gdb.Symtab_and_line' object will be 'None' and 0 + respectively. + + -- Function: Progspace.is_valid () + Returns 'True' if the 'gdb.Progspace' object is valid, 'False' if + not. A 'gdb.Progspace' object can become invalid if the program + space file it refers to is not referenced by any inferior. All + other 'gdb.Progspace' methods will throw an exception if it is + invalid at the time the method is called. + + -- Function: Progspace.objfiles () + Return a sequence of all the objfiles referenced by this program + space. *Note Objfiles In Python::. + + -- Function: Progspace.solib_name (address) + Return the name of the shared library holding the given ADDRESS as + a string, or 'None'. + + -- Function: Progspace.objfile_for_address (address) + Return the 'gdb.Objfile' holding the given address, or 'None' if no + objfile covers it. + + One may add arbitrary attributes to 'gdb.Progspace' objects in the +usual Python way. This is useful if, for example, one needs to do some +extra record keeping associated with the program space. + + *Note choosing attribute names::, for guidance on selecting a +suitable name for new attributes. + + In this contrived example, we want to perform some processing when an +objfile with a certain symbol is loaded, but we only want to do this +once because it is expensive. To achieve this we record the results +with the program space because we can't predict when the desired objfile +will be loaded. + + (gdb) python + def clear_objfiles_handler(event): + event.progspace.expensive_computation = None + def expensive(symbol): + """A mock routine to perform an "expensive" computation on symbol.""" + print ("Computing the answer to the ultimate question ...") + return 42 + def new_objfile_handler(event): + objfile = event.new_objfile + progspace = objfile.progspace + if not hasattr(progspace, 'expensive_computation') or \ + progspace.expensive_computation is None: + # We use 'main' for the symbol to keep the example simple. + # Note: There's no current way to constrain the lookup + # to one objfile. + symbol = gdb.lookup_global_symbol('main') + if symbol is not None: + progspace.expensive_computation = expensive(symbol) + gdb.events.clear_objfiles.connect(clear_objfiles_handler) + gdb.events.new_objfile.connect(new_objfile_handler) + end + (gdb) file /tmp/hello + Reading symbols from /tmp/hello... + Computing the answer to the ultimate question ... + (gdb) python print(gdb.current_progspace().expensive_computation) + 42 + (gdb) run + Starting program: /tmp/hello + Hello. + [Inferior 1 (process 4242) exited normally] + + +File: gdb.info, Node: Objfiles In Python, Next: Frames In Python, Prev: Progspaces In Python, Up: Python API + +23.3.2.27 Objfiles In Python +............................ + +GDB loads symbols for an inferior from various symbol-containing files +(*note Files::). These include the primary executable file, any shared +libraries used by the inferior, and any separate debug info files (*note +Separate Debug Files::). GDB calls these symbol-containing files +"objfiles". + + The following objfile-related functions are available in the 'gdb' +module: + + -- Function: gdb.current_objfile () + When auto-loading a Python script (*note Python Auto-loading::), + GDB sets the "current objfile" to the corresponding objfile. This + function returns the current objfile. If there is no current + objfile, this function returns 'None'. + + -- Function: gdb.objfiles () + Return a sequence of objfiles referenced by the current program + space. *Note Objfiles In Python::, and *note Progspaces In + Python::. This is identical to + 'gdb.selected_inferior().progspace.objfiles()' and is included for + historical compatibility. + + -- Function: gdb.lookup_objfile (name [, by_build_id]) + Look up NAME, a file name or build ID, in the list of objfiles for + the current program space (*note Progspaces In Python::). If the + objfile is not found throw the Python 'ValueError' exception. + + If NAME is a relative file name, then it will match any source file + name with the same trailing components. For example, if NAME is + 'gcc/expr.c', then it will match source file name of + '/build/trunk/gcc/expr.c', but not '/build/trunk/libcpp/expr.c' or + '/build/trunk/gcc/x-expr.c'. + + If BY_BUILD_ID is provided and is 'True' then NAME is the build ID + of the objfile. Otherwise, NAME is a file name. This is supported + only on some operating systems, notably those which use the ELF + format for binary files and the GNU Binutils. For more details + about this feature, see the description of the '--build-id' + command-line option in *note Command Line Options: (ld)Options. + + Each objfile is represented by an instance of the 'gdb.Objfile' +class. + + -- Variable: Objfile.filename + The file name of the objfile as a string, with symbolic links + resolved. + + The value is 'None' if the objfile is no longer valid. See the + 'gdb.Objfile.is_valid' method, described below. + + -- Variable: Objfile.username + The file name of the objfile as specified by the user as a string. + + The value is 'None' if the objfile is no longer valid. See the + 'gdb.Objfile.is_valid' method, described below. + + -- Variable: Objfile.is_file + An objfile often comes from an ordinary file, but in some cases it + may be constructed from the contents of memory. This attribute is + 'True' for file-backed objfiles, and 'False' for other kinds. + + -- Variable: Objfile.owner + For separate debug info objfiles this is the corresponding + 'gdb.Objfile' object that debug info is being provided for. + Otherwise this is 'None'. Separate debug info objfiles are added + with the 'gdb.Objfile.add_separate_debug_file' method, described + below. + + -- Variable: Objfile.build_id + The build ID of the objfile as a string. If the objfile does not + have a build ID then the value is 'None'. + + This is supported only on some operating systems, notably those + which use the ELF format for binary files and the GNU Binutils. + For more details about this feature, see the description of the + '--build-id' command-line option in *note Command Line Options: + (ld)Options. + + -- Variable: Objfile.progspace + The containing program space of the objfile as a 'gdb.Progspace' + object. *Note Progspaces In Python::. + + -- Variable: Objfile.pretty_printers + The 'pretty_printers' attribute is a list of functions. It is used + to look up pretty-printers. A 'Value' is passed to each function + in order; if the function returns 'None', then the search + continues. Otherwise, the return value should be an object which + is used to format the value. *Note Pretty Printing API::, for more + information. + + -- Variable: Objfile.type_printers + The 'type_printers' attribute is a list of type printer objects. + *Note Type Printing API::, for more information. + + -- Variable: Objfile.frame_filters + The 'frame_filters' attribute is a dictionary of frame filter + objects. *Note Frame Filter API::, for more information. + + One may add arbitrary attributes to 'gdb.Objfile' objects in the +usual Python way. This is useful if, for example, one needs to do some +extra record keeping associated with the objfile. + + *Note choosing attribute names::, for guidance on selecting a +suitable name for new attributes. + + In this contrived example we record the time when GDB loaded the +objfile. + + (gdb) python + import datetime + def new_objfile_handler(event): + # Set the time_loaded attribute of the new objfile. + event.new_objfile.time_loaded = datetime.datetime.today() + gdb.events.new_objfile.connect(new_objfile_handler) + end + (gdb) file ./hello + Reading symbols from ./hello... + (gdb) python print(gdb.objfiles()[0].time_loaded) + 2014-10-09 11:41:36.770345 + + A 'gdb.Objfile' object has the following methods: + + -- Function: Objfile.is_valid () + Returns 'True' if the 'gdb.Objfile' object is valid, 'False' if + not. A 'gdb.Objfile' object can become invalid if the object file + it refers to is not loaded in GDB any longer. All other + 'gdb.Objfile' methods will throw an exception if it is invalid at + the time the method is called. + + -- Function: Objfile.add_separate_debug_file (file) + Add FILE to the list of files that GDB will search for debug + information for the objfile. This is useful when the debug info + has been removed from the program and stored in a separate file. + GDB has built-in support for finding separate debug info files + (*note Separate Debug Files::), but if the file doesn't live in one + of the standard places that GDB searches then this function can be + used to add a debug info file from a different place. + + -- Function: Objfile.lookup_global_symbol (name [, domain]) + Search for a global symbol named NAME in this objfile. Optionally, + the search scope can be restricted with the DOMAIN argument. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described in *note Symbols In Python::. This function + is similar to 'gdb.lookup_global_symbol', except that the search is + limited to this objfile. + + The result is a 'gdb.Symbol' object or 'None' if the symbol is not + found. + + -- Function: Objfile.lookup_static_symbol (name [, domain]) + Like 'Objfile.lookup_global_symbol', but searches for a global + symbol with static linkage named NAME in this objfile. + + +File: gdb.info, Node: Frames In Python, Next: Blocks In Python, Prev: Objfiles In Python, Up: Python API + +23.3.2.28 Accessing inferior stack frames from Python +..................................................... + +When the debugged program stops, GDB is able to analyze its call stack +(*note Stack frames: Frames.). The 'gdb.Frame' class represents a frame +in the stack. A 'gdb.Frame' object is only valid while its +corresponding frame exists in the inferior's stack. If you try to use +an invalid frame object, GDB will throw a 'gdb.error' exception (*note +Exception Handling::). + + Two 'gdb.Frame' objects can be compared for equality with the '==' +operator, like: + + (gdb) python print gdb.newest_frame() == gdb.selected_frame () + True + + The following frame-related functions are available in the 'gdb' +module: + + -- Function: gdb.selected_frame () + Return the selected frame object. (*note Selecting a Frame: + Selection.). + + -- Function: gdb.newest_frame () + Return the newest frame object for the selected thread. + + -- Function: gdb.frame_stop_reason_string (reason) + Return a string explaining the reason why GDB stopped unwinding + frames, as expressed by the given REASON code (an integer, see the + 'unwind_stop_reason' method further down in this section). + + -- Function: gdb.invalidate_cached_frames + GDB internally keeps a cache of the frames that have been unwound. + This function invalidates this cache. + + This function should not generally be called by ordinary Python + code. It is documented for the sake of completeness. + + A 'gdb.Frame' object has the following methods: + + -- Function: Frame.is_valid () + Returns true if the 'gdb.Frame' object is valid, false if not. A + frame object can become invalid if the frame it refers to doesn't + exist anymore in the inferior. All 'gdb.Frame' methods will throw + an exception if it is invalid at the time the method is called. + + -- Function: Frame.name () + Returns the function name of the frame, or 'None' if it can't be + obtained. + + -- Function: Frame.architecture () + Returns the 'gdb.Architecture' object corresponding to the frame's + architecture. *Note Architectures In Python::. + + -- Function: Frame.type () + Returns the type of the frame. The value can be one of: + 'gdb.NORMAL_FRAME' + An ordinary stack frame. + + 'gdb.DUMMY_FRAME' + A fake stack frame that was created by GDB when performing an + inferior function call. + + 'gdb.INLINE_FRAME' + A frame representing an inlined function. The function was + inlined into a 'gdb.NORMAL_FRAME' that is older than this one. + + 'gdb.TAILCALL_FRAME' + A frame representing a tail call. *Note Tail Call Frames::. + + 'gdb.SIGTRAMP_FRAME' + A signal trampoline frame. This is the frame created by the + OS when it calls into a signal handler. + + 'gdb.ARCH_FRAME' + A fake stack frame representing a cross-architecture call. + + 'gdb.SENTINEL_FRAME' + This is like 'gdb.NORMAL_FRAME', but it is only used for the + newest frame. + + -- Function: Frame.unwind_stop_reason () + Return an integer representing the reason why it's not possible to + find more frames toward the outermost frame. Use + 'gdb.frame_stop_reason_string' to convert the value returned by + this function to a string. The value can be one of: + + 'gdb.FRAME_UNWIND_NO_REASON' + No particular reason (older frames should be available). + + 'gdb.FRAME_UNWIND_NULL_ID' + The previous frame's analyzer returns an invalid result. This + is no longer used by GDB, and is kept only for backward + compatibility. + + 'gdb.FRAME_UNWIND_OUTERMOST' + This frame is the outermost. + + 'gdb.FRAME_UNWIND_UNAVAILABLE' + Cannot unwind further, because that would require knowing the + values of registers or memory that have not been collected. + + 'gdb.FRAME_UNWIND_INNER_ID' + This frame ID looks like it ought to belong to a NEXT frame, + but we got it for a PREV frame. Normally, this is a sign of + unwinder failure. It could also indicate stack corruption. + + 'gdb.FRAME_UNWIND_SAME_ID' + This frame has the same ID as the previous one. That means + that unwinding further would almost certainly give us another + frame with exactly the same ID, so break the chain. Normally, + this is a sign of unwinder failure. It could also indicate + stack corruption. + + 'gdb.FRAME_UNWIND_NO_SAVED_PC' + The frame unwinder did not find any saved PC, but we needed + one to unwind further. + + 'gdb.FRAME_UNWIND_MEMORY_ERROR' + The frame unwinder caused an error while trying to access + memory. + + 'gdb.FRAME_UNWIND_FIRST_ERROR' + Any stop reason greater or equal to this value indicates some + kind of error. This special value facilitates writing code + that tests for errors in unwinding in a way that will work + correctly even if the list of the other values is modified in + future GDB versions. Using it, you could write: + reason = gdb.selected_frame().unwind_stop_reason () + reason_str = gdb.frame_stop_reason_string (reason) + if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: + print ("An error occurred: %s" % reason_str) + + -- Function: Frame.pc () + Returns the frame's resume address. + + -- Function: Frame.block () + Return the frame's code block. *Note Blocks In Python::. If the + frame does not have a block - for example, if there is no debugging + information for the code in question - then this will throw an + exception. + + -- Function: Frame.function () + Return the symbol for the function corresponding to this frame. + *Note Symbols In Python::. + + -- Function: Frame.older () + Return the frame that called this frame. If this is the oldest + frame, return 'None'. + + -- Function: Frame.newer () + Return the frame called by this frame. If this is the newest + frame, return 'None'. + + -- Function: Frame.find_sal () + Return the frame's symtab and line object. *Note Symbol Tables In + Python::. + + -- Function: Frame.read_register (register) + Return the value of REGISTER in this frame. Returns a 'Gdb.Value' + object. Throws an exception if REGISTER does not exist. The + REGISTER argument must be one of the following: + 1. A string that is the name of a valid register (e.g., ''sp'' or + ''rax''). + 2. A 'gdb.RegisterDescriptor' object (*note Registers In + Python::). + 3. A GDB internal, platform specific number. Using these numbers + is supported for historic reasons, but is not recommended as + future changes to GDB could change the mapping between numbers + and the registers they represent, breaking any Python code + that uses the platform-specific numbers. The numbers are + usually found in the corresponding 'PLATFORM-tdep.h' file in + the GDB source tree. + Using a string to access registers will be slightly slower than the + other two methods as GDB must look up the mapping between name and + internal register number. If performance is critical consider + looking up and caching a 'gdb.RegisterDescriptor' object. + + -- Function: Frame.read_var (variable [, block]) + Return the value of VARIABLE in this frame. If the optional + argument BLOCK is provided, search for the variable from that + block; otherwise start at the frame's current block (which is + determined by the frame's current program counter). The VARIABLE + argument must be a string or a 'gdb.Symbol' object; BLOCK must be a + 'gdb.Block' object. + + -- Function: Frame.select () + Set this frame to be the selected frame. *Note Examining the + Stack: Stack. + + -- Function: Frame.static_link () + In some languages (e.g., Ada, but also a GNU C extension), a nested + function can access the variables in the outer scope. This is done + via a "static link", which is a reference from the nested frame to + the appropriate outer frame. + + This method returns this frame's static link frame, if one exists. + If there is no static link, this method returns 'None'. + + -- Function: Frame.level () + Return an integer, the stack frame level for this frame. *Note + Stack Frames: Frames. + + -- Function: Frame.language () + Return a string, the source language for this frame. + + +File: gdb.info, Node: Blocks In Python, Next: Symbols In Python, Prev: Frames In Python, Up: Python API + +23.3.2.29 Accessing blocks from Python +...................................... + +In GDB, symbols are stored in blocks. A block corresponds roughly to a +scope in the source code. Blocks are organized hierarchically, and are +represented individually in Python as a 'gdb.Block'. Blocks rely on +debugging information being available. + + A frame has a block. Please see *note Frames In Python::, for a more +in-depth discussion of frames. + + The outermost block is known as the "global block". The global block +typically holds public global variables and functions. + + The block nested just inside the global block is the "static block". +The static block typically holds file-scoped variables and functions. + + GDB provides a method to get a block's superblock, but there is +currently no way to examine the sub-blocks of a block, or to iterate +over all the blocks in a symbol table (*note Symbol Tables In Python::). + + Here is a short example that should help explain blocks: + + /* This is in the global block. */ + int global; + + /* This is in the static block. */ + static int file_scope; + + /* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ + int function (int argument) + { + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + { + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + } + } + + A 'gdb.Block' is iterable. The iterator returns the symbols (*note +Symbols In Python::) local to the block. Python programs should not +assume that a specific block object will always contain a given symbol, +since changes in GDB features and infrastructure may cause symbols move +across blocks in a symbol table. You can also use Python's "dictionary +syntax" to access variables in this block, e.g.: + + symbol = some_block['variable'] # symbol is of type gdb.Symbol + + The following block-related functions are available in the 'gdb' +module: + + -- Function: gdb.block_for_pc (pc) + Return the innermost 'gdb.Block' containing the given PC value. If + the block cannot be found for the PC value specified, the function + will return 'None'. This is identical to + 'gdb.current_progspace().block_for_pc(pc)' and is included for + historical compatibility. + + A 'gdb.Block' object has the following methods: + + -- Function: Block.is_valid () + Returns 'True' if the 'gdb.Block' object is valid, 'False' if not. + A block object can become invalid if the block it refers to doesn't + exist anymore in the inferior. All other 'gdb.Block' methods will + throw an exception if it is invalid at the time the method is + called. The block's validity is also checked during iteration over + symbols of the block. + + A 'gdb.Block' object has the following attributes: + + -- Variable: Block.start + The start address of the block. This attribute is not writable. + + -- Variable: Block.end + One past the last address that appears in the block. This + attribute is not writable. + + -- Variable: Block.function + The name of the block represented as a 'gdb.Symbol'. If the block + is not named, then this attribute holds 'None'. This attribute is + not writable. + + For ordinary function blocks, the superblock is the static block. + However, you should note that it is possible for a function block + to have a superblock that is not the static block - for instance + this happens for an inlined function. + + -- Variable: Block.superblock + The block containing this block. If this parent block does not + exist, this attribute holds 'None'. This attribute is not + writable. + + -- Variable: Block.global_block + The global block associated with this block. This attribute is not + writable. + + -- Variable: Block.static_block + The static block associated with this block. This attribute is not + writable. + + -- Variable: Block.is_global + 'True' if the 'gdb.Block' object is a global block, 'False' if not. + This attribute is not writable. + + -- Variable: Block.is_static + 'True' if the 'gdb.Block' object is a static block, 'False' if not. + This attribute is not writable. + + +File: gdb.info, Node: Symbols In Python, Next: Symbol Tables In Python, Prev: Blocks In Python, Up: Python API + +23.3.2.30 Python representation of Symbols +.......................................... + +GDB represents every variable, function and type as an entry in a symbol +table. *Note Examining the Symbol Table: Symbols. Similarly, Python +represents these symbols in GDB with the 'gdb.Symbol' object. + + The following symbol-related functions are available in the 'gdb' +module: + + -- Function: gdb.lookup_symbol (name [, block [, domain]]) + This function searches for a symbol by name. The search scope can + be restricted to the parameters defined in the optional domain and + block arguments. + + NAME is the name of the symbol. It must be a string. The optional + BLOCK argument restricts the search to symbols visible in that + BLOCK. The BLOCK argument must be a 'gdb.Block' object. If + omitted, the block for the current frame is used. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a tuple of two elements. The first element is a + 'gdb.Symbol' object or 'None' if the symbol is not found. If the + symbol is found, the second element is 'True' if the symbol is a + field of a method's object (e.g., 'this' in C++), otherwise it is + 'False'. If the symbol is not found, the second element is + 'False'. + + -- Function: gdb.lookup_global_symbol (name [, domain]) + This function searches for a global symbol by name. The search + scope can be restricted to by the domain argument. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a 'gdb.Symbol' object or 'None' if the symbol is not + found. + + -- Function: gdb.lookup_static_symbol (name [, domain]) + This function searches for a global symbol with static linkage by + name. The search scope can be restricted to by the domain + argument. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a 'gdb.Symbol' object or 'None' if the symbol is not + found. + + Note that this function will not find function-scoped static + variables. To look up such variables, iterate over the variables + of the function's 'gdb.Block' and check that 'block.addr_class' is + 'gdb.SYMBOL_LOC_STATIC'. + + There can be multiple global symbols with static linkage with the + same name. This function will only return the first matching + symbol that it finds. Which symbol is found depends on where GDB + is currently stopped, as GDB will first search for matching symbols + in the current object file, and then search all other object files. + If the application is not yet running then GDB will search all + object files in the order they appear in the debug information. + + -- Function: gdb.lookup_static_symbols (name [, domain]) + Similar to 'gdb.lookup_static_symbol', this function searches for + global symbols with static linkage by name, and optionally + restricted by the domain argument. However, this function returns + a list of all matching symbols found, not just the first one. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the 'gdb' + module and described later in this chapter. + + The result is a list of 'gdb.Symbol' objects which could be empty + if no matching symbols were found. + + Note that this function will not find function-scoped static + variables. To look up such variables, iterate over the variables + of the function's 'gdb.Block' and check that 'block.addr_class' is + 'gdb.SYMBOL_LOC_STATIC'. + + A 'gdb.Symbol' object has the following attributes: + + -- Variable: Symbol.type + The type of the symbol or 'None' if no type is recorded. This + attribute is represented as a 'gdb.Type' object. *Note Types In + Python::. This attribute is not writable. + + -- Variable: Symbol.symtab + The symbol table in which the symbol appears. This attribute is + represented as a 'gdb.Symtab' object. *Note Symbol Tables In + Python::. This attribute is not writable. + + -- Variable: Symbol.line + The line number in the source code at which the symbol was defined. + This is an integer. + + -- Variable: Symbol.name + The name of the symbol as a string. This attribute is not + writable. + + -- Variable: Symbol.linkage_name + The name of the symbol, as used by the linker (i.e., may be + mangled). This attribute is not writable. + + -- Variable: Symbol.print_name + The name of the symbol in a form suitable for output. This is + either 'name' or 'linkage_name', depending on whether the user + asked GDB to display demangled or mangled names. + + -- Variable: Symbol.addr_class + The address class of the symbol. This classifies how to find the + value of a symbol. Each address class is a constant defined in the + 'gdb' module and described later in this chapter. + + -- Variable: Symbol.needs_frame + This is 'True' if evaluating this symbol's value requires a frame + (*note Frames In Python::) and 'False' otherwise. Typically, local + variables will require a frame, but other symbols will not. + + -- Variable: Symbol.is_argument + 'True' if the symbol is an argument of a function. + + -- Variable: Symbol.is_artificial + 'True' if the symbol is artificial. An artificial symbol is one + that is introduced by the compiler. + + -- Variable: Symbol.is_constant + 'True' if the symbol is a constant. + + -- Variable: Symbol.is_function + 'True' if the symbol is a function or a method. + + -- Variable: Symbol.is_variable + 'True' if the symbol is a variable, as opposed to something like a + function or type. Note that this also returns 'False' for + arguments. + + A 'gdb.Symbol' object has the following methods: + + -- Function: Symbol.is_valid () + Returns 'True' if the 'gdb.Symbol' object is valid, 'False' if not. + A 'gdb.Symbol' object can become invalid if the symbol it refers to + does not exist in GDB any longer. All other 'gdb.Symbol' methods + will throw an exception if it is invalid at the time the method is + called. + + -- Function: Symbol.value ([frame]) + Compute the value of the symbol, as a 'gdb.Value'. For functions, + this computes the address of the function, cast to the appropriate + type. If the symbol requires a frame in order to compute its + value, then FRAME must be given. If FRAME is not given, or if + FRAME is invalid, then this method will throw an exception. + + The available domain categories in 'gdb.Symbol' are represented as +constants in the 'gdb' module: + +'gdb.SYMBOL_UNDEF_DOMAIN' + This is used when a domain has not been discovered or none of the + following domains apply. This usually indicates an error either in + the symbol information or in GDB's handling of symbols. + +'gdb.SYMBOL_VAR_DOMAIN' + This domain contains variables. + +'gdb.SYMBOL_FUNCTION_DOMAIN' + This domain contains functions. + +'gdb.SYMBOL_TYPE_DOMAIN' + This domain contains types. In a C-like language, types using a + tag (the name appearing after a 'struct', 'union', or 'enum' + keyword) will not appear here; in other languages, all types are in + this domain. + +'gdb.SYMBOL_STRUCT_DOMAIN' + This domain holds struct, union and enum tag names. This domain is + only used for C-like languages. For example, in this code: + struct type_one { int x; }; + typedef struct type_one type_two; + Here 'type_one' will be in 'SYMBOL_STRUCT_DOMAIN', but 'type_two' + will be in 'SYMBOL_TYPE_DOMAIN'. + +'gdb.SYMBOL_LABEL_DOMAIN' + This domain contains names of labels (for gotos). + +'gdb.SYMBOL_MODULE_DOMAIN' + This domain contains names of Fortran module types. + +'gdb.SYMBOL_COMMON_BLOCK_DOMAIN' + This domain contains names of Fortran common blocks. + + When searching for a symbol, the desired domain constant can be +passed verbatim to the lookup function. For example: + symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN) + + For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the 'SEARCH' +prefix replacing the 'SYMBOL' prefix; for example, +'SEARCH_LABEL_DOMAIN'. These may be or'd together to form a search +constant, e.g.: + symbol = gdb.lookup_symbol ("name", + domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN) + + The available address class categories in 'gdb.Symbol' are +represented as constants in the 'gdb' module: + +'gdb.SYMBOL_LOC_UNDEF' + If this is returned by address class, it indicates an error either + in the symbol information or in GDB's handling of symbols. + +'gdb.SYMBOL_LOC_CONST' + Value is constant int. + +'gdb.SYMBOL_LOC_STATIC' + Value is at a fixed address. + +'gdb.SYMBOL_LOC_REGISTER' + Value is in a register. + +'gdb.SYMBOL_LOC_ARG' + Value is an argument. This value is at the offset stored within + the symbol inside the frame's argument list. + +'gdb.SYMBOL_LOC_REF_ARG' + Value address is stored in the frame's argument list. Just like + 'LOC_ARG' except that the value's address is stored at the offset, + not the value itself. + +'gdb.SYMBOL_LOC_REGPARM_ADDR' + Value is a specified register. Just like 'LOC_REGISTER' except the + register holds the address of the argument instead of the argument + itself. + +'gdb.SYMBOL_LOC_LOCAL' + Value is a local variable. + +'gdb.SYMBOL_LOC_TYPEDEF' + Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all + have this class. + +'gdb.SYMBOL_LOC_LABEL' + Value is a label. + +'gdb.SYMBOL_LOC_BLOCK' + Value is a block. + +'gdb.SYMBOL_LOC_CONST_BYTES' + Value is a byte-sequence. + +'gdb.SYMBOL_LOC_UNRESOLVED' + Value is at a fixed address, but the address of the variable has to + be determined from the minimal symbol table whenever the variable + is referenced. + +'gdb.SYMBOL_LOC_OPTIMIZED_OUT' + The value does not actually exist in the program. + +'gdb.SYMBOL_LOC_COMPUTED' + The value's address is a computed location. + +'gdb.SYMBOL_LOC_COMMON_BLOCK' + The value's address is a symbol. This is only used for Fortran + common blocks. + + +File: gdb.info, Node: Symbol Tables In Python, Next: Line Tables In Python, Prev: Symbols In Python, Up: Python API + +23.3.2.31 Symbol table representation in Python +............................................... + +Access to symbol table data maintained by GDB on the inferior is exposed +to Python via two objects: 'gdb.Symtab_and_line' and 'gdb.Symtab'. +Symbol table and line data for a frame is returned from the 'find_sal' +method in 'gdb.Frame' object. *Note Frames In Python::. + + For more information on GDB's symbol table management, see *note +Examining the Symbol Table: Symbols, for more information. + + A 'gdb.Symtab_and_line' object has the following attributes: + + -- Variable: Symtab_and_line.symtab + The symbol table object ('gdb.Symtab') for this frame. This + attribute is not writable. + + -- Variable: Symtab_and_line.pc + Indicates the start of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.last + Indicates the end of the address range occupied by code for the + current source line. This attribute is not writable. + + -- Variable: Symtab_and_line.line + Indicates the current line number for this object. This attribute + is not writable. + + A 'gdb.Symtab_and_line' object has the following methods: + + -- Function: Symtab_and_line.is_valid () + Returns 'True' if the 'gdb.Symtab_and_line' object is valid, + 'False' if not. A 'gdb.Symtab_and_line' object can become invalid + if the Symbol table and line object it refers to does not exist in + GDB any longer. All other 'gdb.Symtab_and_line' methods will throw + an exception if it is invalid at the time the method is called. + + A 'gdb.Symtab' object has the following attributes: + + -- Variable: Symtab.filename + The symbol table's source filename. This attribute is not + writable. + + -- Variable: Symtab.objfile + The symbol table's backing object file. *Note Objfiles In + Python::. This attribute is not writable. + + -- Variable: Symtab.producer + The name and possibly version number of the program that compiled + the code in the symbol table. The contents of this string is up to + the compiler. If no producer information is available then 'None' + is returned. This attribute is not writable. + + A 'gdb.Symtab' object has the following methods: + + -- Function: Symtab.is_valid () + Returns 'True' if the 'gdb.Symtab' object is valid, 'False' if not. + A 'gdb.Symtab' object can become invalid if the symbol table it + refers to does not exist in GDB any longer. All other 'gdb.Symtab' + methods will throw an exception if it is invalid at the time the + method is called. + + -- Function: Symtab.fullname () + Return the symbol table's source absolute file name. + + -- Function: Symtab.global_block () + Return the global block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.static_block () + Return the static block of the underlying symbol table. *Note + Blocks In Python::. + + -- Function: Symtab.linetable () + Return the line table associated with the symbol table. *Note Line + Tables In Python::. + + +File: gdb.info, Node: Line Tables In Python, Next: Breakpoints In Python, Prev: Symbol Tables In Python, Up: Python API + +23.3.2.32 Manipulating line tables using Python +............................................... + +Python code can request and inspect line table information from a symbol +table that is loaded in GDB. A line table is a mapping of source lines +to their executable locations in memory. To acquire the line table +information for a particular symbol table, use the 'linetable' function +(*note Symbol Tables In Python::). + + A 'gdb.LineTable' is iterable. The iterator returns 'LineTableEntry' +objects that correspond to the source line and address for each line +table entry. 'LineTableEntry' objects have the following attributes: + + -- Variable: LineTableEntry.line + The source line number for this line table entry. This number + corresponds to the actual line of source. This attribute is not + writable. + + -- Variable: LineTableEntry.pc + The address that is associated with the line table entry where the + executable code for that source line resides in memory. This + attribute is not writable. + + As there can be multiple addresses for a single source line, you may +receive multiple 'LineTableEntry' objects with matching 'line' +attributes, but with different 'pc' attributes. The iterator is sorted +in ascending 'pc' order. Here is a small example illustrating iterating +over a line table. + + symtab = gdb.selected_frame().find_sal().symtab + linetable = symtab.linetable() + for line in linetable: + print ("Line: "+str(line.line)+" Address: "+hex(line.pc)) + + This will have the following output: + + Line: 33 Address: 0x4005c8L + Line: 37 Address: 0x4005caL + Line: 39 Address: 0x4005d2L + Line: 40 Address: 0x4005f8L + Line: 42 Address: 0x4005ffL + Line: 44 Address: 0x400608L + Line: 42 Address: 0x40060cL + Line: 45 Address: 0x400615L + + In addition to being able to iterate over a 'LineTable', it also has +the following direct access methods: + + -- Function: LineTable.line (line) + Return a Python 'Tuple' of 'LineTableEntry' objects for any entries + in the line table for the given LINE, which specifies the source + code line. If there are no entries for that source code LINE, the + Python 'None' is returned. + + -- Function: LineTable.has_line (line) + Return a Python 'Boolean' indicating whether there is an entry in + the line table for this source line. Return 'True' if an entry is + found, or 'False' if not. + + -- Function: LineTable.source_lines () + Return a Python 'List' of the source line numbers in the symbol + table. Only lines with executable code locations are returned. + The contents of the 'List' will just be the source line entries + represented as Python 'Long' values. + + +File: gdb.info, Node: Breakpoints In Python, Next: Finish Breakpoints in Python, Prev: Line Tables In Python, Up: Python API + +23.3.2.33 Manipulating breakpoints using Python +............................................... + +Python code can manipulate breakpoints via the 'gdb.Breakpoint' class. + + A breakpoint can be created using one of the two forms of the +'gdb.Breakpoint' constructor. The first one accepts a string like one +would pass to the 'break' (*note Setting Breakpoints: Set Breaks.) and +'watch' (*note Setting Watchpoints: Set Watchpoints.) commands, and can +be used to create both breakpoints and watchpoints. The second accepts +separate Python arguments similar to *note Explicit Locations::, and can +only be used to create breakpoints. + + -- Function: Breakpoint.__init__ (spec [, type ][, wp_class ][, + internal ][, temporary ][, qualified ]) + Create a new breakpoint according to SPEC, which is a string naming + the location of a breakpoint, or an expression that defines a + watchpoint. The string should describe a location in a format + recognized by the 'break' command (*note Setting Breakpoints: Set + Breaks.) or, in the case of a watchpoint, by the 'watch' command + (*note Setting Watchpoints: Set Watchpoints.). + + The optional TYPE argument specifies the type of the breakpoint to + create, as defined below. + + The optional WP_CLASS argument defines the class of watchpoint to + create, if TYPE is 'gdb.BP_WATCHPOINT'. If WP_CLASS is omitted, it + defaults to 'gdb.WP_WRITE'. + + The optional INTERNAL argument allows the breakpoint to become + invisible to the user. The breakpoint will neither be reported + when created, nor will it be listed in the output from 'info + breakpoints' (but will be listed with the 'maint info breakpoints' + command). + + The optional TEMPORARY argument makes the breakpoint a temporary + breakpoint. Temporary breakpoints are deleted after they have been + hit. Any further access to the Python breakpoint after it has been + hit will result in a runtime error (as that breakpoint has now been + automatically deleted). + + The optional QUALIFIED argument is a boolean that allows + interpreting the function passed in 'spec' as a fully-qualified + name. It is equivalent to 'break''s '-qualified' flag (*note + Linespec Locations:: and *note Explicit Locations::). + + -- Function: Breakpoint.__init__ ([ source ][, function ][, label ][, + line ], ][ internal ][, temporary ][, qualified ]) + This second form of creating a new breakpoint specifies the + explicit location (*note Explicit Locations::) using keywords. The + new breakpoint will be created in the specified source file SOURCE, + at the specified FUNCTION, LABEL and LINE. + + INTERNAL, TEMPORARY and QUALIFIED have the same usage as explained + previously. + + The available types are represented by constants defined in the 'gdb' +module: + +'gdb.BP_BREAKPOINT' + Normal code breakpoint. + +'gdb.BP_HARDWARE_BREAKPOINT' + Hardware assisted code breakpoint. + +'gdb.BP_WATCHPOINT' + Watchpoint breakpoint. + +'gdb.BP_HARDWARE_WATCHPOINT' + Hardware assisted watchpoint. + +'gdb.BP_READ_WATCHPOINT' + Hardware assisted read watchpoint. + +'gdb.BP_ACCESS_WATCHPOINT' + Hardware assisted access watchpoint. + +'gdb.BP_CATCHPOINT' + Catchpoint. Currently, this type can't be used when creating + 'gdb.Breakpoint' objects, but will be present in 'gdb.Breakpoint' + objects reported from 'gdb.BreakpointEvent's (*note Events In + Python::). + + The available watchpoint types are represented by constants defined +in the 'gdb' module: + +'gdb.WP_READ' + Read only watchpoint. + +'gdb.WP_WRITE' + Write only watchpoint. + +'gdb.WP_ACCESS' + Read/Write watchpoint. + + -- Function: Breakpoint.stop (self) + The 'gdb.Breakpoint' class can be sub-classed and, in particular, + you may choose to implement the 'stop' method. If this method is + defined in a sub-class of 'gdb.Breakpoint', it will be called when + the inferior reaches any location of a breakpoint which + instantiates that sub-class. If the method returns 'True', the + inferior will be stopped at the location of the breakpoint, + otherwise the inferior will continue. + + If there are multiple breakpoints at the same location with a + 'stop' method, each one will be called regardless of the return + status of the previous. This ensures that all 'stop' methods have + a chance to execute at that location. In this scenario if one of + the methods returns 'True' but the others return 'False', the + inferior will still be stopped. + + You should not alter the execution state of the inferior (i.e., + step, next, etc.), alter the current frame context (i.e., change + the current active frame), or alter, add or delete any breakpoint. + As a general rule, you should not alter any data within GDB or the + inferior at this time. + + Example 'stop' implementation: + + class MyBreakpoint (gdb.Breakpoint): + def stop (self): + inf_val = gdb.parse_and_eval("foo") + if inf_val == 3: + return True + return False + + -- Function: Breakpoint.is_valid () + Return 'True' if this 'Breakpoint' object is valid, 'False' + otherwise. A 'Breakpoint' object can become invalid if the user + deletes the breakpoint. In this case, the object still exists, but + the underlying breakpoint does not. In the cases of watchpoint + scope, the watchpoint remains valid even if execution of the + inferior leaves the scope of that watchpoint. + + -- Function: Breakpoint.delete () + Permanently deletes the GDB breakpoint. This also invalidates the + Python 'Breakpoint' object. Any further access to this object's + attributes or methods will raise an error. + + -- Variable: Breakpoint.enabled + This attribute is 'True' if the breakpoint is enabled, and 'False' + otherwise. This attribute is writable. You can use it to enable + or disable the breakpoint. + + -- Variable: Breakpoint.silent + This attribute is 'True' if the breakpoint is silent, and 'False' + otherwise. This attribute is writable. + + Note that a breakpoint can also be silent if it has commands and + the first command is 'silent'. This is not reported by the + 'silent' attribute. + + -- Variable: Breakpoint.pending + This attribute is 'True' if the breakpoint is pending, and 'False' + otherwise. *Note Set Breaks::. This attribute is read-only. + + -- Variable: Breakpoint.thread + If the breakpoint is thread-specific (*note Thread-Specific + Breakpoints::), this attribute holds the thread's global id. If + the breakpoint is not thread-specific, this attribute is 'None'. + This attribute is writable. + + Only one of 'Breakpoint.thread' or 'Breakpoint.inferior' can be set + to a valid id at any time, that is, a breakpoint can be thread + specific, or inferior specific, but not both. + + -- Variable: Breakpoint.inferior + If the breakpoint is inferior-specific (*note Inferior-Specific + Breakpoints::), this attribute holds the inferior's id. If the + breakpoint is not inferior-specific, this attribute is 'None'. + + This attribute can be written for breakpoints of type + 'gdb.BP_BREAKPOINT' and 'gdb.BP_HARDWARE_BREAKPOINT'. + + -- Variable: Breakpoint.task + If the breakpoint is Ada task-specific, this attribute holds the + Ada task id. If the breakpoint is not task-specific (or the + underlying language is not Ada), this attribute is 'None'. This + attribute is writable. + + -- Variable: Breakpoint.ignore_count + This attribute holds the ignore count for the breakpoint, an + integer. This attribute is writable. + + -- Variable: Breakpoint.number + This attribute holds the breakpoint's number -- the identifier used + by the user to manipulate the breakpoint. This attribute is not + writable. + + -- Variable: Breakpoint.type + This attribute holds the breakpoint's type -- the identifier used + to determine the actual breakpoint type or use-case. This + attribute is not writable. + + -- Variable: Breakpoint.visible + This attribute tells whether the breakpoint is visible to the user + when set, or when the 'info breakpoints' command is run. This + attribute is not writable. + + -- Variable: Breakpoint.temporary + This attribute indicates whether the breakpoint was created as a + temporary breakpoint. Temporary breakpoints are automatically + deleted after that breakpoint has been hit. Access to this + attribute, and all other attributes and functions other than the + 'is_valid' function, will result in an error after the breakpoint + has been hit (as it has been automatically deleted). This + attribute is not writable. + + -- Variable: Breakpoint.hit_count + This attribute holds the hit count for the breakpoint, an integer. + This attribute is writable, but currently it can only be set to + zero. + + -- Variable: Breakpoint.location + This attribute holds the location of the breakpoint, as specified + by the user. It is a string. If the breakpoint does not have a + location (that is, it is a watchpoint) the attribute's value is + 'None'. This attribute is not writable. + + -- Variable: Breakpoint.locations + Get the most current list of breakpoint locations that are inserted + for this breakpoint, with elements of type 'gdb.BreakpointLocation' + (described below). This functionality matches that of the 'info + breakpoint' command (*note Set Breaks::), in that it only retrieves + the most current list of locations, thus the list itself when + returned is not updated behind the scenes. This attribute is not + writable. + + -- Variable: Breakpoint.expression + This attribute holds a breakpoint expression, as specified by the + user. It is a string. If the breakpoint does not have an + expression (the breakpoint is not a watchpoint) the attribute's + value is 'None'. This attribute is not writable. + + -- Variable: Breakpoint.condition + This attribute holds the condition of the breakpoint, as specified + by the user. It is a string. If there is no condition, this + attribute's value is 'None'. This attribute is writable. + + -- Variable: Breakpoint.commands + This attribute holds the commands attached to the breakpoint. If + there are commands, this attribute's value is a string holding all + the commands, separated by newlines. If there are no commands, + this attribute is 'None'. This attribute is writable. + +Breakpoint Locations +-------------------- + +A breakpoint location is one of the actual places where a breakpoint has +been set, represented in the Python API by the 'gdb.BreakpointLocation' +type. This type is never instantiated by the user directly, but is +retrieved from 'Breakpoint.locations' which returns a list of breakpoint +locations where it is currently set. Breakpoint locations can become +invalid if new symbol files are loaded or dynamically loaded libraries +are closed. Accessing the attributes of an invalidated breakpoint +location will throw a 'RuntimeError' exception. Access the +'Breakpoint.locations' attribute again to retrieve the new and valid +breakpoints location list. + + -- Variable: BreakpointLocation.source + This attribute returns the source file path and line number where + this location was set. The type of the attribute is a tuple of + STRING and LONG. If the breakpoint location doesn't have a source + location, it returns None, which is the case for watchpoints and + catchpoints. This will throw a 'RuntimeError' exception if the + location has been invalidated. This attribute is not writable. + + -- Variable: BreakpointLocation.address + This attribute returns the address where this location was set. + This attribute is of type long. This will throw a 'RuntimeError' + exception if the location has been invalidated. This attribute is + not writable. + + -- Variable: BreakpointLocation.enabled + This attribute holds the value for whether or not this location is + enabled. This attribute is writable (boolean). This will throw a + 'RuntimeError' exception if the location has been invalidated. + + -- Variable: BreakpointLocation.owner + This attribute holds a reference to the 'gdb.Breakpoint' owner + object, from which this 'gdb.BreakpointLocation' was retrieved + from. This will throw a 'RuntimeError' exception if the location + has been invalidated. This attribute is not writable. + + -- Variable: BreakpointLocation.function + This attribute gets the name of the function where this location + was set. If no function could be found this attribute returns + 'None'. This will throw a 'RuntimeError' exception if the location + has been invalidated. This attribute is not writable. + + -- Variable: BreakpointLocation.fullname + This attribute gets the full name of where this location was set. + If no full name could be found, this attribute returns 'None'. + This will throw a 'RuntimeError' exception if the location has been + invalidated. This attribute is not writable. + + -- Variable: BreakpointLocation.thread_groups + This attribute gets the thread groups it was set in. It returns a + 'List' of the thread group ID's. This will throw a 'RuntimeError' + exception if the location has been invalidated. This attribute is + not writable. + + +File: gdb.info, Node: Finish Breakpoints in Python, Next: Lazy Strings In Python, Prev: Breakpoints In Python, Up: Python API + +23.3.2.34 Finish Breakpoints +............................ + +A finish breakpoint is a temporary breakpoint set at the return address +of a frame, based on the 'finish' command. 'gdb.FinishBreakpoint' +extends 'gdb.Breakpoint'. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope +(i.e. 'Breakpoint.stop' or 'FinishBreakpoint.out_of_scope' triggered). +Finish breakpoints are thread specific and must be create with the right +thread selected. + + -- Function: FinishBreakpoint.__init__ ([frame] [, internal]) + Create a finish breakpoint at the return address of the 'gdb.Frame' + object FRAME. If FRAME is not provided, this defaults to the + newest frame. The optional INTERNAL argument allows the breakpoint + to become invisible to the user. *Note Breakpoints In Python::, + for further details about this argument. + + -- Function: FinishBreakpoint.out_of_scope (self) + In some circumstances (e.g. 'longjmp', C++ exceptions, GDB 'return' + command, ...), a function may not properly terminate, and thus + never hit the finish breakpoint. When GDB notices such a + situation, the 'out_of_scope' callback will be triggered. + + You may want to sub-class 'gdb.FinishBreakpoint' and override this + method: + + class MyFinishBreakpoint (gdb.FinishBreakpoint) + def stop (self): + print ("normal finish") + return True + + def out_of_scope (): + print ("abnormal finish") + + -- Variable: FinishBreakpoint.return_value + When GDB is stopped at a finish breakpoint and the frame used to + build the 'gdb.FinishBreakpoint' object had debug symbols, this + attribute will contain a 'gdb.Value' object corresponding to the + return value of the function. The value will be 'None' if the + function return type is 'void' or if the return value was not + computable. This attribute is not writable. + + +File: gdb.info, Node: Lazy Strings In Python, Next: Architectures In Python, Prev: Finish Breakpoints in Python, Up: Python API + +23.3.2.35 Python representation of lazy strings +............................................... + +A "lazy string" is a string whose contents is not retrieved or encoded +until it is needed. + + A 'gdb.LazyString' is represented in GDB as an 'address' that points +to a region of memory, an 'encoding' that will be used to encode that +region of memory, and a 'length' to delimit the region of memory that +represents the string. The difference between a 'gdb.LazyString' and a +string wrapped within a 'gdb.Value' is that a 'gdb.LazyString' will only +be retrieved and encoded during printing, while a 'gdb.Value' wrapping a +string is immediately retrieved and encoded on creation. + + A 'gdb.LazyString' can be created using the 'gdb.Value.lazy_string' +method (*note Values From Inferior::). + + A 'gdb.LazyString' object has the following functions: + + -- Function: LazyString.value () + Convert the 'gdb.LazyString' to a 'gdb.Value'. This value will + point to the string in memory, but will lose all the delayed + retrieval, encoding and handling that GDB applies to a + 'gdb.LazyString'. + + -- Variable: LazyString.address + This attribute holds the address of the string. This attribute is + not writable. + + -- Variable: LazyString.length + This attribute holds the length of the string in characters. If + the length is -1, then the string will be fetched and encoded up to + the first null of appropriate width. This attribute is not + writable. + + -- Variable: LazyString.encoding + This attribute holds the encoding that will be applied to the + string when the string is printed by GDB. If the encoding is not + set, or contains an empty string, then GDB will select the most + appropriate encoding when the string is printed. This attribute is + not writable. + + -- Variable: LazyString.type + This attribute holds the type that is represented by the lazy + string's type. For a lazy string this is a pointer or array type. + To resolve this to the lazy string's character type, use the type's + 'target' method. *Note Types In Python::. This attribute is not + writable. + + +File: gdb.info, Node: Architectures In Python, Next: Registers In Python, Prev: Lazy Strings In Python, Up: Python API + +23.3.2.36 Python representation of architectures +................................................ + +GDB uses architecture specific parameters and artifacts in a number of +its various computations. An architecture is represented by an instance +of the 'gdb.Architecture' class. + + A 'gdb.Architecture' class has the following methods: + + -- Function: Architecture.name () + Return the name (string value) of the architecture. + + -- Function: Architecture.disassemble (start_pc [, end_pc [, count]]) + Return a list of disassembled instructions starting from the memory + address START_PC. The optional arguments END_PC and COUNT + determine the number of instructions in the returned list. If both + the optional arguments END_PC and COUNT are specified, then a list + of at most COUNT disassembled instructions whose start address + falls in the closed memory address interval from START_PC to END_PC + are returned. If END_PC is not specified, but COUNT is specified, + then COUNT number of instructions starting from the address + START_PC are returned. If COUNT is not specified but END_PC is + specified, then all instructions whose start address falls in the + closed memory address interval from START_PC to END_PC are + returned. If neither END_PC nor COUNT are specified, then a single + instruction at START_PC is returned. For all of these cases, each + element of the returned list is a Python 'dict' with the following + string keys: + + 'addr' + The value corresponding to this key is a Python long integer + capturing the memory address of the instruction. + + 'asm' + The value corresponding to this key is a string value which + represents the instruction with assembly language mnemonics. + The assembly language flavor used is the same as that + specified by the current CLI variable 'disassembly-flavor'. + *Note Machine Code::. + + 'length' + The value corresponding to this key is the length (integer + value) of the instruction in bytes. + + -- Function: Architecture.integer_type (size [, signed]) + This function looks up an integer type by its SIZE, and optionally + whether or not it is signed. + + SIZE is the size, in bits, of the desired integer type. Only + certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and + 128. + + If SIGNED is not specified, it defaults to 'True'. If SIGNED is + 'False', the returned type will be unsigned. + + If the indicated type cannot be found, this function will throw a + 'ValueError' exception. + + -- Function: Architecture.registers ([ reggroup ]) + Return a 'gdb.RegisterDescriptorIterator' (*note Registers In + Python::) for all of the registers in REGGROUP, a string that is + the name of a register group. If REGGROUP is omitted, or is the + empty string, then the register group 'all' is assumed. + + -- Function: Architecture.register_groups () + Return a 'gdb.RegisterGroupsIterator' (*note Registers In Python::) + for all of the register groups available for the + 'gdb.Architecture'. + + +File: gdb.info, Node: Registers In Python, Next: Connections In Python, Prev: Architectures In Python, Up: Python API + +23.3.2.37 Registers In Python +............................. + +Python code can request from a 'gdb.Architecture' information about the +set of registers available (*note 'Architecture.registers': +gdbpy_architecture_registers.). The register information is returned as +a 'gdb.RegisterDescriptorIterator', which is an iterator that in turn +returns 'gdb.RegisterDescriptor' objects. + + A 'gdb.RegisterDescriptor' does not provide the value of a register +(*note 'Frame.read_register': gdbpy_frame_read_register. for reading a +register's value), instead the 'RegisterDescriptor' is a way to discover +which registers are available for a particular architecture. + + A 'gdb.RegisterDescriptor' has the following read-only properties: + + -- Variable: RegisterDescriptor.name + The name of this register. + + It is also possible to lookup a register descriptor based on its name +using the following 'gdb.RegisterDescriptorIterator' function: + + -- Function: RegisterDescriptorIterator.find (name) + Takes NAME as an argument, which must be a string, and returns a + 'gdb.RegisterDescriptor' for the register with that name, or 'None' + if there is no register with that name. + + Python code can also request from a 'gdb.Architecture' information +about the set of register groups available on a given architecture +(*note 'Architecture.register_groups': gdbpy_architecture_reggroups.). + + Every register can be a member of zero or more register groups. Some +register groups are used internally within GDB to control things like +which registers must be saved when calling into the program being +debugged (*note Calling Program Functions: Calling.). Other register +groups exist to allow users to easily see related sets of registers in +commands like 'info registers' (*note 'info registers REGGROUP': +info_registers_reggroup.). + + The register groups information is returned as a +'gdb.RegisterGroupsIterator', which is an iterator that in turn returns +'gdb.RegisterGroup' objects. + + A 'gdb.RegisterGroup' object has the following read-only properties: + + -- Variable: RegisterGroup.name + A string that is the name of this register group. + + +File: gdb.info, Node: Connections In Python, Next: TUI Windows In Python, Prev: Registers In Python, Up: Python API + +23.3.2.38 Connections In Python +............................... + +GDB lets you run and debug multiple programs in a single session. Each +program being debugged has a connection, the connection describes how +GDB controls the program being debugged. Examples of different +connection types are 'native' and 'remote'. *Note Inferiors Connections +and Programs::. + + Connections in GDB are represented as instances of +'gdb.TargetConnection', or as one of its sub-classes. To get a list of +all connections use 'gdb.connections' (*note gdb.connections: +gdbpy_connections.). + + To get the connection for a single 'gdb.Inferior' read its +'gdb.Inferior.connection' attribute (*note gdb.Inferior.connection: +gdbpy_inferior_connection.). + + Currently there is only a single sub-class of 'gdb.TargetConnection', +'gdb.RemoteTargetConnection', however, additional sub-classes may be +added in future releases of GDB. As a result you should avoid writing +code like: + + conn = gdb.selected_inferior().connection + if type(conn) is gdb.RemoteTargetConnection: + print("This is a remote target connection") + +as this may fail when more connection types are added. Instead, you +should write: + + conn = gdb.selected_inferior().connection + if isinstance(conn, gdb.RemoteTargetConnection): + print("This is a remote target connection") + + A 'gdb.TargetConnection' has the following method: + + -- Function: TargetConnection.is_valid () + Return 'True' if the 'gdb.TargetConnection' object is valid, + 'False' if not. A 'gdb.TargetConnection' will become invalid if + the connection no longer exists within GDB, this might happen when + no inferiors are using the connection, but could be delayed until + the user replaces the current target. + + Reading any of the 'gdb.TargetConnection' properties will throw an + exception if the connection is invalid. + + A 'gdb.TargetConnection' has the following read-only properties: + + -- Variable: TargetConnection.num + An integer assigned by GDB to uniquely identify this connection. + This is the same value as displayed in the 'Num' column of the + 'info connections' command output (*note info connections: + Inferiors Connections and Programs.). + + -- Variable: TargetConnection.type + A string that describes what type of connection this is. This + string will be one of the valid names that can be passed to the + 'target' command (*note target command: Target Commands.). + + -- Variable: TargetConnection.description + A string that gives a short description of this target type. This + is the same string that is displayed in the 'Description' column of + the 'info connection' command output (*note info connections: + Inferiors Connections and Programs.). + + -- Variable: TargetConnection.details + An optional string that gives additional information about this + connection. This attribute can be 'None' if there are no + additional details for this connection. + + An example of a connection type that might have additional details + is the 'remote' connection, in this case the details string can + contain the 'HOSTNAME:PORT' that was used to connect to the remote + target. + + The 'gdb.RemoteTargetConnection' class is a sub-class of +'gdb.TargetConnection', and is used to represent 'remote' and +'extended-remote' connections. In addition to the attributes and +methods available from the 'gdb.TargetConnection' base class, a +'gdb.RemoteTargetConnection' has the following method: + + -- Function: RemoteTargetConnection.send_packet (packet) + This method sends PACKET to the remote target and returns the + response. The PACKET should either be a 'bytes' object, or a + 'Unicode' string. + + If PACKET is a 'Unicode' string, then the string is encoded to a + 'bytes' object using the ASCII codec. If the string can't be + encoded then an 'UnicodeError' is raised. + + If PACKET is not a 'bytes' object, or a 'Unicode' string, then a + 'TypeError' is raised. If PACKET is empty then a 'ValueError' is + raised. + + The response is returned as a 'bytes' object. If it is known that + the response can be represented as a string then this can be + decoded from the buffer. For example, if it is known that the + response is an ASCII string: + + remote_connection.send_packet("some_packet").decode("ascii") + + The prefix, suffix, and checksum (as required by the remote serial + protocol) are automatically added to the outgoing packet, and + removed from the incoming packet before the contents of the reply + are returned. + + This is equivalent to the 'maintenance packet' command (*note maint + packet::). + + +File: gdb.info, Node: TUI Windows In Python, Next: Disassembly In Python, Prev: Connections In Python, Up: Python API + +23.3.2.39 Implementing new TUI windows +...................................... + +New TUI (*note TUI::) windows can be implemented in Python. + + -- Function: gdb.register_window_type (name, factory) + Because TUI windows are created and destroyed depending on the + layout the user chooses, new window types are implemented by + registering a factory function with GDB. + + NAME is the name of the new window. It's an error to try to + replace one of the built-in windows, but other window types can be + replaced. The NAME should match the regular expression + '[a-zA-Z][-_.a-zA-Z0-9]*', it is an error to try and create a + window with an invalid name. + + FUNCTION is a factory function that is called to create the TUI + window. This is called with a single argument of type + 'gdb.TuiWindow', described below. It should return an object that + implements the TUI window protocol, also described below. + + As mentioned above, when a factory function is called, it is passed +an object of type 'gdb.TuiWindow'. This object has these methods and +attributes: + + -- Function: TuiWindow.is_valid () + This method returns 'True' when this window is valid. When the + user changes the TUI layout, windows no longer visible in the new + layout will be destroyed. At this point, the 'gdb.TuiWindow' will + no longer be valid, and methods (and attributes) other than + 'is_valid' will throw an exception. + + When the TUI is disabled using 'tui disable' (*note tui disable: + TUI Commands.) the window is hidden rather than destroyed, but + 'is_valid' will still return 'False' and other methods (and + attributes) will still throw an exception. + + -- Variable: TuiWindow.width + This attribute holds the width of the window. It is not writable. + + -- Variable: TuiWindow.height + This attribute holds the height of the window. It is not writable. + + -- Variable: TuiWindow.title + This attribute holds the window's title, a string. This is + normally displayed above the window. This attribute can be + modified. + + -- Function: TuiWindow.erase () + Remove all the contents of the window. + + -- Function: TuiWindow.write (string [, full_window]) + Write STRING to the window. STRING can contain ANSI terminal + escape styling sequences; GDB will translate these as appropriate + for the terminal. + + If the FULL_WINDOW parameter is 'True', then STRING contains the + full contents of the window. This is similar to calling 'erase' + before 'write', but avoids the flickering. + + The factory function that you supply should return an object +conforming to the TUI window protocol. These are the methods that can +be called on this object, which is referred to below as the "window +object". The methods documented below are optional; if the object does +not implement one of these methods, GDB will not attempt to call it. +Additional new methods may be added to the window protocol in the +future. GDB guarantees that they will begin with a lower-case letter, +so you can start implementation methods with upper-case letters or +underscore to avoid any future conflicts. + + -- Function: Window.close () + When the TUI window is closed, the 'gdb.TuiWindow' object will be + put into an invalid state. At this time, GDB will call 'close' + method on the window object. + + After this method is called, GDB will discard any references it + holds on this window object, and will no longer call methods on + this object. + + -- Function: Window.render () + In some situations, a TUI window can change size. For example, + this can happen if the user resizes the terminal, or changes the + layout. When this happens, GDB will call the 'render' method on + the window object. + + If your window is intended to update in response to changes in the + inferior, you will probably also want to register event listeners + and send output to the 'gdb.TuiWindow'. + + -- Function: Window.hscroll (num) + This is a request to scroll the window horizontally. NUM is the + amount by which to scroll, with negative numbers meaning to scroll + right. In the TUI model, it is the viewport that moves, not the + contents. A positive argument should cause the viewport to move + right, and so the content should appear to move to the left. + + -- Function: Window.vscroll (num) + This is a request to scroll the window vertically. NUM is the + amount by which to scroll, with negative numbers meaning to scroll + backward. In the TUI model, it is the viewport that moves, not the + contents. A positive argument should cause the viewport to move + down, and so the content should appear to move up. + + -- Function: Window.click (x, y, button) + This is called on a mouse click in this window. X and Y are the + mouse coordinates inside the window (0-based, from the top left + corner), and BUTTON specifies which mouse button was used, whose + values can be 1 (left), 2 (middle), or 3 (right). + + When TUI mouse events are disabled by turning off the 'tui + mouse-events' setting (*note set tui mouse-events: + tui-mouse-events.), then 'click' will not be called. + + +File: gdb.info, Node: Disassembly In Python, Next: Missing Debug Info In Python, Prev: TUI Windows In Python, Up: Python API + +23.3.2.40 Instruction Disassembly In Python +........................................... + +GDB's builtin disassembler can be extended, or even replaced, using the +Python API. The disassembler related features are contained within the +'gdb.disassembler' module: + + -- class: gdb.disassembler.DisassembleInfo + Disassembly is driven by instances of this class. Each time GDB + needs to disassemble an instruction, an instance of this class is + created and passed to a registered disassembler. The disassembler + is then responsible for disassembling an instruction and returning + a result. + + Instances of this type are usually created within GDB, however, it + is possible to create a copy of an instance of this type, see the + description of '__init__' for more details. + + This class has the following properties and methods: + + -- Variable: DisassembleInfo.address + A read-only integer containing the address at which GDB wishes + to disassemble a single instruction. + + -- Variable: DisassembleInfo.architecture + The 'gdb.Architecture' (*note Architectures In Python::) for + which GDB is currently disassembling, this property is + read-only. + + -- Variable: DisassembleInfo.progspace + The 'gdb.Progspace' (*note Program Spaces In Python: + Progspaces In Python.) for which GDB is currently + disassembling, this property is read-only. + + -- Function: DisassembleInfo.is_valid () + Returns 'True' if the 'DisassembleInfo' object is valid, + 'False' if not. A 'DisassembleInfo' object will become + invalid once the disassembly call for which the + 'DisassembleInfo' was created, has returned. Calling other + 'DisassembleInfo' methods, or accessing 'DisassembleInfo' + properties, will raise a 'RuntimeError' exception if it is + invalid. + + -- Function: DisassembleInfo.__init__ (info) + This can be used to create a new 'DisassembleInfo' object that + is a copy of INFO. The copy will have the same 'address', + 'architecture', and 'progspace' values as INFO, and will + become invalid at the same time as INFO. + + This method exists so that sub-classes of 'DisassembleInfo' + can be created, these sub-classes must be initialized as + copies of an existing 'DisassembleInfo' object, but + sub-classes might choose to override the 'read_memory' method, + and so control what GDB sees when reading from memory (*note + builtin_disassemble::). + + -- Function: DisassembleInfo.read_memory (length, offset) + This method allows the disassembler to read the bytes of the + instruction to be disassembled. The method reads LENGTH + bytes, starting at OFFSET from 'DisassembleInfo.address'. + + It is important that the disassembler read the instruction + bytes using this method, rather than reading inferior memory + directly, as in some cases GDB disassembles from an internal + buffer rather than directly from inferior memory, calling this + method handles this detail. + + Returns a buffer object, which behaves much like an array or a + string, just as 'Inferior.read_memory' does (*note + Inferior.read_memory: gdbpy_inferior_read_memory.). The + length of the returned buffer will always be exactly LENGTH. + + If GDB is unable to read the required memory then a + 'gdb.MemoryError' exception is raised (*note Exception + Handling::). + + This method can be overridden by a sub-class in order to + control what GDB sees when reading from memory (*note + builtin_disassemble::). When overriding this method it is + important to understand how 'builtin_disassemble' makes use of + this method. + + While disassembling a single instruction there could be + multiple calls to this method, and the same bytes might be + read multiple times. Any single call might only read a subset + of the total instruction bytes. + + If an implementation of 'read_memory' is unable to read the + requested memory contents, for example, if there's a request + to read from an invalid memory address, then a + 'gdb.MemoryError' should be raised. + + Raising a 'MemoryError' inside 'read_memory' does not + automatically mean a 'MemoryError' will be raised by + 'builtin_disassemble'. It is possible the GDB's builtin + disassembler is probing to see how many bytes are available. + When 'read_memory' raises the 'MemoryError' the builtin + disassembler might be able to perform a complete disassembly + with the bytes it has available, in this case + 'builtin_disassemble' will not itself raise a 'MemoryError'. + + Any other exception type raised in 'read_memory' will + propagate back and be re-raised by 'builtin_disassemble'. + + -- Function: DisassembleInfo.text_part (style, string) + Create a new 'DisassemblerTextPart' representing a piece of a + disassembled instruction. STRING should be a non-empty + string, and STYLE should be an appropriate style constant + (*note Disassembler Style Constants::). + + Disassembler parts are used when creating a + 'DisassemblerResult' in order to represent the styling within + an instruction (*note DisassemblerResult Class::). + + -- Function: DisassembleInfo.address_part (address) + Create a new 'DisassemblerAddressPart'. ADDRESS is the value + of the absolute address this part represents. A + 'DisassemblerAddressPart' is displayed as an absolute address + and an associated symbol, the address and symbol are styled + appropriately. + + -- class: gdb.disassembler.Disassembler + This is a base class from which all user implemented disassemblers + must inherit. + + -- Function: Disassembler.__init__ (name) + The constructor takes NAME, a string, which should be a short + name for this disassembler. + + -- Function: Disassembler.__call__ (info) + The '__call__' method must be overridden by sub-classes to + perform disassembly. Calling '__call__' on this base class + will raise a 'NotImplementedError' exception. + + The INFO argument is an instance of 'DisassembleInfo', and + describes the instruction that GDB wants disassembling. + + If this function returns 'None', this indicates to GDB that + this sub-class doesn't wish to disassemble the requested + instruction. GDB will then use its builtin disassembler to + perform the disassembly. + + Alternatively, this function can return a 'DisassemblerResult' + that represents the disassembled instruction, this type is + described in more detail below. + + The '__call__' method can raise a 'gdb.MemoryError' exception + (*note Exception Handling::) to indicate to GDB that there was + a problem accessing the required memory, this will then be + displayed by GDB within the disassembler output. + + Ideally, the only three outcomes from invoking '__call__' + would be a return of 'None', a successful disassembly returned + in a 'DisassemblerResult', or a 'MemoryError' indicating that + there was a problem reading memory. + + However, as an implementation of '__call__' could fail due to + other reasons, e.g. some external resource required to perform + disassembly is temporarily unavailable, then, if '__call__' + raises a 'GdbError', the exception will be converted to a + string and printed at the end of the disassembly output, the + disassembly request will then stop. + + Any other exception type raised by the '__call__' method is + considered an error in the user code, the exception will be + printed to the error stream according to the 'set python + print-stack' setting (*note 'set python print-stack': + set_python_print_stack.). + + -- class: gdb.disassembler.DisassemblerResult + This class represents the result of disassembling a single + instruction. An instance of this class will be returned from + 'builtin_disassemble' (*note builtin_disassemble::), and an + instance of this class should be returned from + 'Disassembler.__call__' (*note Disassembler Class::) if an + instruction was successfully disassembled. + + It is not possible to sub-class the 'DisassemblerResult' class. + + The 'DisassemblerResult' class has the following properties and + methods: + + -- Function: DisassemblerResult.__init__ (length, string, parts) + Initialize an instance of this class, LENGTH is the length of + the disassembled instruction in bytes, which must be greater + than zero. + + Only one of STRING or PARTS should be used to initialize a new + 'DisassemblerResult'; the other one should be passed the value + 'None'. Alternatively, the arguments can be passed by name, + and the unused argument can be ignored. + + The STRING argument, if not 'None', is a non-empty string that + represents the entire disassembled instruction. Building a + result object using the STRING argument does not allow for any + styling information to be included in the result. GDB will + style the result as a single 'DisassemblerTextPart' with + 'STYLE_TEXT' style (*note Disassembler Styling Parts::). + + The PARTS argument, if not 'None', is a non-empty sequence of + 'DisassemblerPart' objects. Each part represents a small part + of the disassembled instruction along with associated styling + information. A result object built using PARTS can be + displayed by GDB with full styling information (*note 'set + style disassembler enabled': style_disassembler_enabled.). + + -- Variable: DisassemblerResult.length + A read-only property containing the length of the disassembled + instruction in bytes, this will always be greater than zero. + + -- Variable: DisassemblerResult.string + A read-only property containing a non-empty string + representing the disassembled instruction. The STRING is a + representation of the disassembled instruction without any + styling information. To see how the instruction will be + styled use the PARTS property. + + If this instance was initialized using separate + 'DisassemblerPart' objects, the STRING property will still be + valid. The STRING value is created by concatenating the + 'DisassemblerPart.string' values of each component part (*note + Disassembler Styling Parts::). + + -- Variable: DisassemblerResult.parts + A read-only property containing a non-empty sequence of + 'DisassemblerPart' objects. Each 'DisassemblerPart' object + contains a small part of the instruction along with + information about how that part should be styled. GDB uses + this information to create styled disassembler output (*note + 'set style disassembler enabled': + style_disassembler_enabled.). + + If this instance was initialized using a single string rather + than with a sequence of 'DisassemblerPart' objects, the PARTS + property will still be valid. In this case the PARTS property + will hold a sequence containing a single + 'DisassemblerTextPart' object, the string of which will + represent the entire instruction, and the style of which will + be 'STYLE_TEXT'. + + -- class: gdb.disassembler.DisassemblerPart + This is a parent class from which the different part sub-classes + inherit. Only instances of the sub-classes detailed below will be + returned by the Python API. + + It is not possible to directly create instances of either this + parent class, or any of the sub-classes listed below. Instances of + the sub-classes listed below are created by calling + 'builtin_disassemble' (*note builtin_disassemble::) and are + returned within the 'DisassemblerResult' object, or can be created + by calling the 'text_part' and 'address_part' methods on the + 'DisassembleInfo' class (*note DisassembleInfo Class::). + + The 'DisassemblerPart' class has a single property: + + -- Variable: DisassemblerPart.string + A read-only property that contains a non-empty string + representing this part of the disassembled instruction. The + string within this property doesn't include any styling + information. + + -- class: gdb.disassembler.DisassemblerTextPart + The 'DisassemblerTextPart' class represents a piece of the + disassembled instruction and the associated style for that piece. + Instances of this class can't be created directly, instead call + 'DisassembleInfo.text_part' to create a new instance of this class + (*note DisassembleInfo Class::). + + As well as the properties of its parent class, the + 'DisassemblerTextPart' has the following additional property: + + -- Variable: DisassemblerTextPart.style + A read-only property that contains one of the defined style + constants. GDB will use this style when styling this part of + the disassembled instruction (*note Disassembler Style + Constants::). + + -- class: gdb.disassembler.DisassemblerAddressPart + The 'DisassemblerAddressPart' class represents an absolute address + within a disassembled instruction. Using a + 'DisassemblerAddressPart' instead of a 'DisassemblerTextPart' with + 'STYLE_ADDRESS' is preferred, GDB will display the address as both + an absolute address, and will look up a suitable symbol to display + next to the address. Using 'DisassemblerAddressPart' also ensures + that user settings such as 'set print max-symbolic-offset' are + respected. + + Here is an example of an x86-64 instruction: + + call 0x401136 + + In this instruction the '0x401136 ' was generated from a + single 'DisassemblerAddressPart'. The '0x401136' will be styled + with 'STYLE_ADDRESS', and 'foo' will be styled with 'STYLE_SYMBOL'. + The '<' and '>' will be styled as 'STYLE_TEXT'. + + If the inclusion of the symbol name is not required then a + 'DisassemblerTextPart' with style 'STYLE_ADDRESS' can be used + instead. + + Instances of this class can't be created directly, instead call + 'DisassembleInfo.address_part' to create a new instance of this + class (*note DisassembleInfo Class::). + + As well as the properties of its parent class, the + 'DisassemblerAddressPart' has the following additional property: + + -- Variable: DisassemblerAddressPart.address + A read-only property that contains the ADDRESS passed to this + object's '__init__' method. + + The following table lists all of the disassembler styles that are +available. GDB maps these style constants onto its style settings +(*note Output Styling::). In some cases, several style constants +produce the same style settings, and thus will produce the same visual +effect on the screen. This could change in future releases of GDB, so +care should be taken to select the correct style constant to ensure +correct output styling in future releases of GDB. + +'gdb.disassembler.STYLE_TEXT' + This is the default style used by GDB when styling disassembler + output. This style should be used for any parts of the instruction + that don't fit any of the other styles listed below. GDB styles + text with this style using its default style. + +'gdb.disassembler.STYLE_MNEMONIC' + This style is used for styling the primary instruction mnemonic, + which usually appears at, or near, the start of the disassembled + instruction string. + + GDB styles text with this style using the 'disassembler mnemonic' + style setting. + +'gdb.disassembler.STYLE_SUB_MNEMONIC' + This style is used for styling any sub-mnemonics within a + disassembled instruction. A sub-mnemonic is any text within the + instruction that controls the function of the instruction, but + which is disjoint from the primary mnemonic (which will have styled + 'STYLE_MNEMONIC'). + + As an example, consider this AArch64 instruction: + + add w16, w7, w1, lsl #1 + + The 'add' is the primary instruction mnemonic, and would be given + style 'STYLE_MNEMONIC', while 'lsl' is the sub-mnemonic, and would + be given the style 'STYLE_SUB_MNEMONIC'. + + GDB styles text with this style using the 'disassembler mnemonic' + style setting. + +'gdb.disassembler.STYLE_ASSEMBLER_DIRECTIVE' + Sometimes a series of bytes doesn't decode to a valid instruction. + In this case the disassembler may choose to represent the result of + disassembling using an assembler directive, for example: + + .word 0x1234 + + In this case, the '.word' would be give the + 'STYLE_ASSEMBLER_DIRECTIVE' style. An assembler directive is + similar to a mnemonic in many ways but is something that is not + part of the architecture's instruction set. + + GDB styles text with this style using the 'disassembler mnemonic' + style setting. + +'gdb.disassembler.STYLE_REGISTER' + This style is used for styling any text that represents a register + name, or register number, within a disassembled instruction. + + GDB styles text with this style using the 'disassembler register' + style setting. + +'gdb.disassembler.STYLE_ADDRESS' + This style is used for styling numerical values that represent + absolute addresses within the disassembled instruction. + + When creating a 'DisassemblerTextPart' with this style, you should + consider if a 'DisassemblerAddressPart' would be more appropriate. + See *note Disassembler Styling Parts:: for a description of what + each part offers. + + GDB styles text with this style using the 'disassembler address' + style setting. + +'gdb.disassembler.STYLE_ADDRESS_OFFSET' + This style is used for styling numerical values that represent + offsets to addresses within the disassembled instruction. A value + is considered an address offset when the instruction itself is + going to access memory, and the value is being used to offset which + address is accessed. + + For example, an architecture might have an instruction that loads + from memory using an address within a register. If that + instruction also allowed for an immediate offset to be encoded into + the instruction, this would be an address offset. Similarly, a + branch instruction might jump to an address in a register plus an + address offset that is encoded into the instruction. + + GDB styles text with this style using the 'disassembler immediate' + style setting. + +'gdb.disassembler.STYLE_IMMEDIATE' + Use 'STYLE_IMMEDIATE' for any numerical values within a + disassembled instruction when those values are not addresses, + address offsets, or register numbers (The styles 'STYLE_ADDRESS', + 'STYLE_ADDRESS_OFFSET', or 'STYLE_REGISTER' can be used in those + cases). + + GDB styles text with this style using the 'disassembler immediate' + style setting. + +'gdb.disassembler.STYLE_SYMBOL' + This style is used for styling the textual name of a symbol that is + included within a disassembled instruction. A symbol name is often + included next to an absolute address within a disassembled + instruction to make it easier for the user to understand what the + address is referring too. For example: + + call 0x401136 + + Here 'foo' is the name of a symbol, and should be given the + 'STYLE_SYMBOL' style. + + Adding symbols next to absolute addresses like this is handled + automatically by the 'DisassemblerAddressPart' class (*note + Disassembler Styling Parts::). + + GDB styles text with this style using the 'disassembler symbol' + style setting. + +'gdb.disassembler.STYLE_COMMENT_START' + This style is used to start a line comment in the disassembly + output. Unlike other styles, which only apply to the single + 'DisassemblerTextPiece' to which they are applied, the comment + style is sticky, and overrides the style of any further pieces + within this instruction. + + This means that, after a 'STYLE_COMMENT_START' piece has been seen, + GDB will apply the comment style until the end of the line, + ignoring the specific style within a piece. + + GDB styles text with this style using the 'disassembler comment' + style setting. + + The following functions are also contained in the 'gdb.disassembler' +module: + + -- Function: register_disassembler (disassembler, architecture) + The DISASSEMBLER must be a sub-class of + 'gdb.disassembler.Disassembler' or 'None'. + + The optional ARCHITECTURE is either a string, or the value 'None'. + If it is a string, then it should be the name of an architecture + known to GDB, as returned either from 'gdb.Architecture.name' + (*note gdb.Architecture.name: gdbpy_architecture_name.), or from + 'gdb.architecture_names' (*note gdb.architecture_names: + gdb_architecture_names.). + + The DISASSEMBLER will be installed for the architecture named by + ARCHITECTURE, or if ARCHITECTURE is 'None', then DISASSEMBLER will + be installed as a global disassembler for use by all architectures. + + GDB only records a single disassembler for each architecture, and a + single global disassembler. Calling 'register_disassembler' for an + architecture, or for the global disassembler, will replace any + existing disassembler registered for that ARCHITECTURE value. The + previous disassembler is returned. + + If DISASSEMBLER is 'None' then any disassembler currently + registered for ARCHITECTURE is deregistered and returned. + + When GDB is looking for a disassembler to use, GDB first looks for + an architecture specific disassembler. If none has been registered + then GDB looks for a global disassembler (one registered with + ARCHITECTURE set to 'None'). Only one disassembler is called to + perform disassembly, so, if there is both an architecture specific + disassembler, and a global disassembler registered, it is the + architecture specific disassembler that will be used. + + GDB tracks the architecture specific, and global disassemblers + separately, so it doesn't matter in which order disassemblers are + created or registered; an architecture specific disassembler, if + present, will always be used in preference to a global + disassembler. + + You can use the 'maint info python-disassemblers' command (*note + maint info python-disassemblers::) to see which disassemblers have + been registered. + + -- Function: builtin_disassemble (info) + This function calls back into GDB's builtin disassembler to + disassemble the instruction identified by INFO, an instance, or + sub-class, of 'DisassembleInfo'. + + When the builtin disassembler needs to read memory the + 'read_memory' method on INFO will be called. By sub-classing + 'DisassembleInfo' and overriding the 'read_memory' method, it is + possible to intercept calls to 'read_memory' from the builtin + disassembler, and to modify the values returned. + + It is important to understand that, even when + 'DisassembleInfo.read_memory' raises a 'gdb.MemoryError', it is the + internal disassembler itself that reports the memory error to GDB. + The reason for this is that the disassembler might probe memory to + see if a byte is readable or not; if the byte can't be read then + the disassembler may choose not to report an error, but instead to + disassemble the bytes that it does have available. + + If the builtin disassembler is successful then an instance of + 'DisassemblerResult' is returned from 'builtin_disassemble', + alternatively, if something goes wrong, an exception will be + raised. + + A 'MemoryError' will be raised if 'builtin_disassemble' is unable + to read some memory that is required in order to perform + disassembly correctly. + + Any exception that is not a 'MemoryError', that is raised in a call + to 'read_memory', will pass through 'builtin_disassemble', and be + visible to the caller. + + Finally, there are a few cases where GDB's builtin disassembler can + fail for reasons that are not covered by 'MemoryError'. In these + cases, a 'GdbError' will be raised. The contents of the exception + will be a string describing the problem the disassembler + encountered. + + Here is an example that registers a global disassembler. The new +disassembler invokes the builtin disassembler, and then adds a comment, +'## Comment', to each line of disassembly output: + + class ExampleDisassembler(gdb.disassembler.Disassembler): + def __init__(self): + super().__init__("ExampleDisassembler") + + def __call__(self, info): + result = gdb.disassembler.builtin_disassemble(info) + length = result.length + text = result.string + "\t## Comment" + return gdb.disassembler.DisassemblerResult(length, text) + + gdb.disassembler.register_disassembler(ExampleDisassembler()) + + The following example creates a sub-class of 'DisassembleInfo' in +order to intercept the 'read_memory' calls, within 'read_memory' any +bytes read from memory have the two 4-bit nibbles swapped around. This +isn't a very useful adjustment, but serves as an example. + + class MyInfo(gdb.disassembler.DisassembleInfo): + def __init__(self, info): + super().__init__(info) + + def read_memory(self, length, offset): + buffer = super().read_memory(length, offset) + result = bytearray() + for b in buffer: + v = int.from_bytes(b, 'little') + v = (v << 4) & 0xf0 | (v >> 4) + result.append(v) + return memoryview(result) + + class NibbleSwapDisassembler(gdb.disassembler.Disassembler): + def __init__(self): + super().__init__("NibbleSwapDisassembler") + + def __call__(self, info): + info = MyInfo(info) + return gdb.disassembler.builtin_disassemble(info) + + gdb.disassembler.register_disassembler(NibbleSwapDisassembler()) + + +File: gdb.info, Node: Missing Debug Info In Python, Next: Missing Objfiles In Python, Prev: Disassembly In Python, Up: Python API + +23.3.2.41 Missing Debug Info In Python +...................................... + +When GDB encounters a new objfile (*note Objfiles In Python::), e.g. the +primary executable, or any shared libraries used by the inferior, GDB +will attempt to load the corresponding debug information for that +objfile. The debug information might be found within the objfile +itself, or within a separate objfile which GDB will automatically locate +and load. + + Sometimes though, GDB might not find any debug information for an +objfile, in this case the debugging experience will be restricted. + + If GDB fails to locate any debug information for a particular +objfile, there is an opportunity for a Python extension to step in. A +Python extension can potentially locate the missing debug information +using some platform- or project-specific steps, and inform GDB of its +location. Or a Python extension might provide some platform- or +project-specific advice to the user about how to obtain the missing +debug information. + + A missing debug information Python extension consists of a handler +object which has the 'name' and 'enabled' attributes, and implements the +'__call__' method. When GDB encounters an objfile for which it is +unable to find any debug information, it invokes the '__call__' method. +Full details of how handlers are written can be found below. + +The 'gdb.missing_debug' Module +------------------------------ + +GDB comes with a 'gdb.missing_debug' module which contains the following +class and global function: + + -- class: gdb.missing_debug.MissingDebugHandler + + 'MissingDebugHandler' is a base class from which user-created + handlers can derive, though it is not required that handlers derive + from this class, so long as any user created handler has the 'name' + and 'enabled' attributes, and implements the '__call__' method. + + -- Function: MissingDebugHandler.__init__ (name) + The NAME is a string used to reference this missing debug + handler within some GDB commands. Valid names consist of the + characters '[-_a-zA-Z0-9]', creating a handler with an invalid + name raises a 'ValueError' exception. + + -- Function: MissingDebugHandler.__call__ (objfile) + Sub-classes must override the '__call__' method. The OBJFILE + argument will be a 'gdb.Objfile', this is the objfile for + which GDB was unable to find any debug information. + + The return value from the '__call__' method indicates what GDB + should do next. The possible return values are: + + * 'None' + + This indicates that this handler could not help with + OBJFILE, GDB should call any other registered handlers. + + * 'True' + + This indicates that this handler has installed the debug + information into a location where GDB would normally + expect to find it when looking for separate debug + information files (*note Separate Debug Files::). GDB + will repeat the normal lookup process, which should now + find the separate debug file. + + If GDB still doesn't find the separate debug information + file after this second attempt, then the Python missing + debug information handlers are not invoked a second time, + this prevents a badly behaved handler causing GDB to get + stuck in a loop. GDB will continue without any debug + information for OBJFILE. + + * 'False' + + This indicates that this handler has done everything that + it intends to do with OBJFILE, but no separate debug + information can be found. GDB will not call any other + registered handlers for OBJFILE. GDB will continue + without debugging information for OBJFILE. + + * A string + + The returned string should contain a filename. GDB will + not call any further registered handlers, and will + instead load the debug information from the file + identified by the returned filename. + + Invoking the '__call__' method from this base class will raise + a 'NotImplementedError' exception. + + -- Variable: MissingDebugHandler.name + A read-only attribute which is a string, the name of this + handler passed to the '__init__' method. + + -- Variable: MissingDebugHandler.enabled + A modifiable attribute containing a boolean; when 'True', the + handler is enabled, and will be used by GDB. When 'False', + the handler has been disabled, and will not be used. + + -- Function: gdb.missing_debug.register_handler (locus, handler, + replace=False) + Register a new missing debug handler with GDB. + + HANDLER is an instance of a sub-class of 'MissingDebugHandler', or + at least an instance of an object that has the same attributes and + methods as 'MissingDebugHandler'. + + LOCUS specifies to which handler list to prepend HANDLER. It can + be either a 'gdb.Progspace' (*note Progspaces In Python::) or + 'None', in which case the handler is registered globally. The + newly registered HANDLER will be called before any other handler + from the same locus. Two handlers in the same locus cannot have + the same name, an attempt to add a handler with an already existing + name raises an exception unless REPLACE is 'True', in which case + the old handler is deleted and the new handler is prepended to the + selected handler list. + + GDB first calls the handlers for the current program space, and + then the globally registered handlers. As soon as a handler + returns a value other than 'None', no further handlers are called + for this objfile. + + +File: gdb.info, Node: Missing Objfiles In Python, Prev: Missing Debug Info In Python, Up: Python API + +23.3.2.42 Missing Objfiles In Python +.................................... + +When GDB opens a core file, for example with the 'core-file' command +(*note core-file command::), GDB will attempt to load the corresponding +executable and shared libraries. Often these files can be found on the +local machine, but sometimes these files cannot be found, in which case +the debugging experience will be restricted. + + If GDB fails to locate a particular file then there is an opportunity +for a Python extension to step in. A Python extension can potentially +locate the missing file using some platform- or project-specific steps, +and inform GDB of its location. Or a Python extension might provide +some platform- or project-specific advice to the user about how to +obtain the missing file. + + A missing-objfile Python extension consists of a handler object which +has the 'name' and 'enabled' attributes, and implements the '__call__' +method. When GDB encounters a situation where a file cannot be found, +but the build-id (*note build ID::) for the missing file is known, then +the '__call__' method is invoked to try and find the file. Full details +of how handlers are written can be found below. + +The 'gdb.missing_objfile' Module +-------------------------------- + +GDB comes with a 'gdb.missing_objfile' module which contains the +following class and global function: + + -- class: gdb.missing_objfile.MissingObjfileHandler + + 'MissingObjfileHandler' is a base class from which user-created + handlers can derive, though it is not required that handlers derive + from this class, so long as any user created handler has the 'name' + and 'enabled' attributes, and implements the '__call__' method. + + -- Function: MissingObjfileHandler.__init__ (name) + The NAME is a string used to reference this missing-objfile + handler within some GDB commands. Valid names consist of the + characters '[-_a-zA-Z0-9]', creating a handler with an invalid + name raises a 'ValueError' exception. + + -- Function: MissingObjfileHandler.__call__ (pspace, build_id, + filename) + + Sub-classes must override the '__call__' method. The PSPACE + argument will be a 'gdb.Progspace' (*note Progspaces In + Python::), this is the program space in which GDB is looking + for the missing file. + + The BUILD_ID argument is a string containing the build-id of + the file that is missing, this will be in the same format as + returned by 'Objfile.build_id' (*note Objfile.build_id::). + + The FILENAME argument contains the name of the file that GDB + is looking for. This information is provided to allow + handlers to generate informative messages for the user. A + handler is not required to place the missing file at this + location. There might already be a file present at this + location, but it might not match the required build-id, in + which case GDB will have ignored it. In some limited cases + GDB might not be able to establish the FILENAME of the file it + is searching for, in this case GDB will use a string 'with + build-id BUILD_ID' as a replacement. + + The return value from the '__call__' method indicates what GDB + should do next. The possible return values are: + + * 'None' + + This indicates that this handler could not locate the + missing file and GDB should call any other registered + handlers. + + * 'True' + + This indicates that this handler has installed the + missing file into a location where GDB would normally + expect to find it. The only location in which GDB will + look is within the '.build-id' sub-directory within the + DEBUG-FILE-DIRECTORY (*note debug-file-directory::). + + GDB will repeat the normal lookup process, which should + now find the previously missing file. + + If GDB still doesn't find file after this second attempt, + then the Python missing-objfile handlers are not invoked + a second time, this prevents a badly behaved handler + causing GDB to get stuck in a loop. GDB will continue + without the missing file, though this will degrade the + debugging experience. + + * 'False' + + This indicates that this handler has done everything that + it intends to do but the missing file could not be found. + GDB will not call any other registered handlers to look + for the missing file. GDB will continue without the + missing file, though this will degrade the debugging + experience. + + * A string + + The returned string should contain a filename. GDB will + not call any further registered handlers, and will + instead use the returned filename as the missing file. + + Invoking the '__call__' method from this base class will raise + a 'NotImplementedError' exception. + + -- Variable: MissingObjfileHandler.name + A read-only attribute which is a string, the name of this + handler passed to the '__init__' method. + + -- Variable: MissingObjfileHandler.enabled + A modifiable attribute containing a boolean; when 'True', the + handler is enabled, and will be used by GDB. When 'False', + the handler has been disabled, and will not be used. + + -- Function: gdb.missing_objfile.register_handler (locus, handler, + replace=False) + Register a new missing-objfile handler with GDB. + + HANDLER is an instance of a sub-class of 'MissingObjfileHandler', + or at least an instance of an object that has the same attributes + and methods as 'MissingObjfileHandler'. + + LOCUS specifies to which handler list to prepend HANDLER. It can + be either a 'gdb.Progspace' (*note Progspaces In Python::) or + 'None', in which case the handler is registered globally. The + newly registered HANDLER will be called before any other handler + from the same locus. Two handlers in the same locus cannot have + the same name, an attempt to add a handler with an already existing + name raises an exception unless REPLACE is 'True', in which case + the old handler is deleted and the new handler is prepended to the + selected handler list. + + GDB first calls the handlers for the current program space, and + then the globally registered handlers. As soon as a handler + returns a value other than 'None', no further handlers are called. + +Managing Missing-Objfile Handlers +--------------------------------- + +GDB defines the following commands to manage registered missing-objfile +handlers: + +'info missing-objfile-handlers [ LOCUS [ NAME-REGEXP ] ]' + Lists all registered missing-objfile handlers. Arguments LOCUS and + NAME-REGEXP are both optional and can be used to filter which + handlers are listed. + + The LOCUS argument should be either 'global', 'progspace', or the + name of an object file. Only handlers registered for the specified + locus will be listed. + + The NAME-REGEXP is a regular expression used to match against + handler names. + +'disable missing-objfile-handler [ LOCUS [ NAME-REGEXP ] ]' + The LOCUS and NAME-REGEXP are interpreted as in 'info + missing-objfile-handlers' above, but instead of listing the + matching handlers, all of the matching handlers are disabled. The + 'enabled' field of each matching handler is set to 'False'. + +'enable missing-objfile-handler [ LOCUS [ NAME-REGEXP ] ]' + The LOCUS and NAME-REGEXP are interpreted as in 'info + missing-objfile-handlers' above, but instead of listing the + matching handlers, all of the matching handlers are enabled. The + 'enabled' field of each matching handler is set to 'True'. + + +File: gdb.info, Node: Python Auto-loading, Next: Python modules, Prev: Python API, Up: Python + +23.3.3 Python Auto-loading +-------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +Python support scripts in several ways: 'OBJFILE-gdb.py' and +'.debug_gdb_scripts' section. *Note Auto-loading extensions::. + + The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load python-scripts [on|off]' + Enable or disable the auto-loading of Python scripts. + +'show auto-load python-scripts' + Show whether auto-loading of Python scripts is enabled or disabled. + +'info auto-load python-scripts [REGEXP]' + Print the list of all Python scripts that GDB auto-loaded. + + Also printed is the list of Python scripts that were mentioned in + the '.debug_gdb_scripts' section and were either not found (*note + dotdebug_gdb_scripts section::) or were not auto-loaded due to + 'auto-load safe-path' rejection (*note Auto-loading::). This is + useful because their names are not printed when GDB tries to load + them and fails. There may be many of them, and printing an error + message for each one is problematic. + + If REGEXP is supplied only Python scripts with matching names are + printed. + + Example: + + (gdb) info auto-load python-scripts + Loaded Script + Yes py-section-script.py + full name: /tmp/py-section-script.py + No my-foo-pretty-printers.py + + When reading an auto-loaded file or script, GDB sets the "current +objfile". This is available via the 'gdb.current_objfile' function +(*note Objfiles In Python::). This can be useful for registering +objfile-specific pretty-printers and frame-filters. + + +File: gdb.info, Node: Python modules, Prev: Python Auto-loading, Up: Python + +23.3.4 Python modules +--------------------- + +GDB comes with several modules to assist writing Python code. + +* Menu: + +* gdb.printing:: Building and registering pretty-printers. +* gdb.types:: Utilities for working with types. +* gdb.prompt:: Utilities for prompt value substitution. +* gdb.ptwrite:: Utilities for PTWRITE filter registration. + + +File: gdb.info, Node: gdb.printing, Next: gdb.types, Up: Python modules + +23.3.4.1 gdb.printing +..................... + +This module provides a collection of utilities for working with +pretty-printers. + +'PrettyPrinter (NAME, SUBPRINTERS=None)' + This class specifies the API that makes 'info pretty-printer', + 'enable pretty-printer' and 'disable pretty-printer' work. + Pretty-printers should generally inherit from this class. + +'SubPrettyPrinter (NAME)' + For printers that handle multiple types, this class specifies the + corresponding API for the subprinters. + +'RegexpCollectionPrettyPrinter (NAME)' + Utility class for handling multiple printers, all recognized via + regular expressions. *Note Writing a Pretty-Printer::, for an + example. + +'FlagEnumerationPrinter (NAME)' + A pretty-printer which handles printing of 'enum' values. Unlike + GDB's built-in 'enum' printing, this printer attempts to work + properly when there is some overlap between the enumeration + constants. The argument NAME is the name of the printer and also + the name of the 'enum' type to look up. + +'register_pretty_printer (OBJ, PRINTER, REPLACE=False)' + Register PRINTER with the pretty-printer list of OBJ. If REPLACE + is 'True' then any existing copy of the printer is replaced. + Otherwise a 'RuntimeError' exception is raised if a printer with + the same name already exists. + + +File: gdb.info, Node: gdb.types, Next: gdb.prompt, Prev: gdb.printing, Up: Python modules + +23.3.4.2 gdb.types +.................. + +This module provides a collection of utilities for working with +'gdb.Type' objects. + +'get_basic_type (TYPE)' + Return TYPE with const and volatile qualifiers stripped, and with + typedefs and C++ references converted to the underlying type. + + C++ example: + + typedef const int const_int; + const_int foo (3); + const_int& foo_ref (foo); + int main () { return 0; } + + Then in gdb: + + (gdb) start + (gdb) python import gdb.types + (gdb) python foo_ref = gdb.parse_and_eval("foo_ref") + (gdb) python print gdb.types.get_basic_type(foo_ref.type) + int + +'has_field (TYPE, FIELD)' + Return 'True' if TYPE, assumed to be a type with fields (e.g., a + structure or union), has field FIELD. + +'make_enum_dict (ENUM_TYPE)' + Return a Python 'dictionary' type produced from ENUM_TYPE. + +'deep_items (TYPE)' + Returns a Python iterator similar to the standard + 'gdb.Type.iteritems' method, except that the iterator returned by + 'deep_items' will recursively traverse anonymous struct or union + fields. For example: + + struct A + { + int a; + union { + int b0; + int b1; + }; + }; + + Then in GDB: + (gdb) python import gdb.types + (gdb) python struct_a = gdb.lookup_type("struct A") + (gdb) python print struct_a.keys () + {['a', '']} + (gdb) python print [k for k,v in gdb.types.deep_items(struct_a)] + {['a', 'b0', 'b1']} + +'get_type_recognizers ()' + Return a list of the enabled type recognizers for the current + context. This is called by GDB during the type-printing process + (*note Type Printing API::). + +'apply_type_recognizers (recognizers, type_obj)' + Apply the type recognizers, RECOGNIZERS, to the type object + TYPE_OBJ. If any recognizer returns a string, return that string. + Otherwise, return 'None'. This is called by GDB during the + type-printing process (*note Type Printing API::). + +'register_type_printer (locus, printer)' + This is a convenience function to register a type printer PRINTER. + The printer must implement the type printer protocol. The LOCUS + argument is either a 'gdb.Objfile', in which case the printer is + registered with that objfile; a 'gdb.Progspace', in which case the + printer is registered with that progspace; or 'None', in which case + the printer is registered globally. + +'TypePrinter' + This is a base class that implements the type printer protocol. + Type printers are encouraged, but not required, to derive from this + class. It defines a constructor: + + -- Method on TypePrinter: __init__ (self, name) + Initialize the type printer with the given name. The new + printer starts in the enabled state. + + +File: gdb.info, Node: gdb.prompt, Next: gdb.ptwrite, Prev: gdb.types, Up: Python modules + +23.3.4.3 gdb.prompt +................... + +This module provides a method for prompt value-substitution. + +'substitute_prompt (STRING)' + Return STRING with escape sequences substituted by values. Some + escape sequences take arguments. You can specify arguments inside + "{}" immediately following the escape sequence. + + The escape sequences you can pass to this function are: + + '\\' + Substitute a backslash. + '\e' + Substitute an ESC character. + '\f' + Substitute the selected frame; an argument names a frame + parameter. + '\n' + Substitute a newline. + '\p' + Substitute a parameter's value; the argument names the + parameter. + '\r' + Substitute a carriage return. + '\t' + Substitute the selected thread; an argument names a thread + parameter. + '\v' + Substitute the version of GDB. + '\w' + Substitute the current working directory. + '\[' + Begin a sequence of non-printing characters. These sequences + are typically used with the ESC character, and are not counted + in the string length. Example: "\[\e[0;34m\](gdb)\[\e[0m\]" + will return a blue-colored "(gdb)" prompt where the length is + five. + '\]' + End a sequence of non-printing characters. + + For example: + + substitute_prompt ("frame: \f, args: \p{print frame-arguments}") + +will return the string: + + "frame: main, args: scalars" + + +File: gdb.info, Node: gdb.ptwrite, Prev: gdb.prompt, Up: Python modules + +23.3.4.4 gdb.ptwrite +.................... + +This module provides additional functionality for recording programs +that make use of the 'PTWRITE' instruction. 'PTWRITE' is a x86 +instruction that allows to write values into the Intel Processor Trace +(*note Process Record and Replay::). The GCC intrinsics for it are: + void _ptwrite32 (unsigned int a) + void _ptwrite64 (unsigned __int64 a) + + If an inferior uses the instruction, GDB by default inserts the raw +payload value as auxiliary information into the execution history. +Auxiliary information is by default printed during 'record +instruction-history', 'record function-call-history', and all stepping +commands, and is accessible in Python as a 'RecordAuxiliary' object +(*note Recordings In Python::). + +Sample program: + #include + + void + ptwrite64 (unsigned long long value) + { + _ptwrite64 (value); + } + + int + main (void) + { + ptwrite64 (0x42); + return 0; /* break here. */ + } + +GDB output after recording the sample program in pt format: + (gdb) record instruction-history 12,14 + 12 0x0040074c : ptwrite %rbx + 13 [0x42] + 14 0x00400751 : mov -0x8(%rbp),%rbx + (gdb) record function-call-history + 1 main + 2 ptwrite64 + [0x42] + 3 main + + The 'gdb.ptwrite' module allows customizing the default output of +'PTWRITE' auxiliary information. A custom Python function can be +registered as the 'PTWRITE' filter function. This function will be +called with the 'PTWRITE' payload and PC as arguments during trace +decoding. The function can return a string, which will be printed by +GDB during the aforementioned commands, or 'None', resulting in no +output. To register such a filter function, the user needs to provide a +filter factory function, which returns a new filter function object to +be called by GDB. + + -- Function: register_filter_factory (filter_factory) + Used to register the 'PTWRITE' filter factory. This filter factory + can be any callable object that accepts one argument, the current + thread as a 'gdb.InferiorThread'. It can return None or a + callable. This callable is the 'PTWRITE' filter function for the + specified thread. If 'None' is returned by the factory function, + the default auxiliary information will be printed. + + -- Function: get_filter () + Return the currently active 'PTWRITE' filter function. + + An example: + + (gdb) python-interactive + >>> class my_filter(): + ... def __init__(self): + ... self.var = 0 + ... def __call__(self, payload, ip): + ... self.var += 1 + ... return f"counter: {self.var}, ip: {ip:#x}" + ... + >>> def my_filter_factory(thread): + ... if thread.global_num == 1: + ... return my_filter() + ... else: + ... return None + ... + >>> import gdb.ptwrite + >>> gdb.ptwrite.register_filter_factory(my_filter_factory) + >>> + + (gdb) record function-call-history 59,64 + 59 pthread_create@GLIBC_2.2.5 + 60 job() + 61 task(void*) + 62 ptwrite64(unsigned long) + [counter: 1, ip: 0x401156] + 63 task(void*) + 64 ptwrite32(unsigned int) + [counter: 2, ip: 0x40116c] + + (gdb) info threads + * 1 Thread 0x7ffff7fd8740 (LWP 25796) "ptw_threads" task () + at bin/ptwrite/ptw_threads.c:45 + 2 Thread 0x7ffff6eb8700 (LWP 25797) "ptw_threads" task () + at bin/ptwrite/ptw_threads.c:45 + + (gdb) thread 2 + [Switching to thread 2 (Thread 0x7ffff6eb8700 (LWP 25797))] + #0 task (arg=0x0) at ptwrite_threads.c:45 + 45 return NULL; + + (gdb) record function-call-history 10,14 + 10 start_thread + 11 task(void*) + 12 ptwrite64(unsigned long) + [0x42] + 13 task(void*) + 14 ptwrite32(unsigned int) + [0x43] + + This GDB feature is dependent on hardware and operating system +support and requires the Intel Processor Trace decoder library in +version 2.0.0 or newer. + + +File: gdb.info, Node: Guile, Next: Auto-loading extensions, Prev: Python, Up: Extending GDB + +23.4 Extending GDB using Guile +============================== + +You can extend GDB using the Guile implementation of the Scheme +programming language (http://www.gnu.org/software/guile/). This feature +is available only if GDB was configured using '--with-guile'. + +* Menu: + +* Guile Introduction:: Introduction to Guile scripting in GDB +* Guile Commands:: Accessing Guile from GDB +* Guile API:: Accessing GDB from Guile +* Guile Auto-loading:: Automatically loading Guile code +* Guile Modules:: Guile modules provided by GDB + + +File: gdb.info, Node: Guile Introduction, Next: Guile Commands, Up: Guile + +23.4.1 Guile Introduction +------------------------- + +Guile is an implementation of the Scheme programming language and is the +GNU project's official extension language. + + Guile support in GDB follows the Python support in GDB reasonably +closely, so concepts there should carry over. However, some things are +done differently where it makes sense. + + GDB requires Guile version 3.0, 2.2, or 2.0. + + Guile scripts used by GDB should be installed in +'DATA-DIRECTORY/guile', where DATA-DIRECTORY is the data directory as +determined at GDB startup (*note Data Files::). This directory, known +as the "guile directory", is automatically added to the Guile Search +Path in order to allow the Guile interpreter to locate all scripts +installed at this location. + + +File: gdb.info, Node: Guile Commands, Next: Guile API, Prev: Guile Introduction, Up: Guile + +23.4.2 Guile Commands +--------------------- + +GDB provides two commands for accessing the Guile interpreter: + +'guile-repl' +'gr' + The 'guile-repl' command can be used to start an interactive Guile + prompt or "repl". To return to GDB, type ',q' or the 'EOF' + character (e.g., 'Ctrl-D' on an empty prompt). These commands do + not take any arguments. + +'guile [SCHEME-EXPRESSION]' +'gu [SCHEME-EXPRESSION]' + The 'guile' command can be used to evaluate a Scheme expression. + + If given an argument, GDB will pass the argument to the Guile + interpreter for evaluation. + + (gdb) guile (display (+ 20 3)) (newline) + 23 + + The result of the Scheme expression is displayed using normal Guile + rules. + + (gdb) guile (+ 20 3) + 23 + + If you do not provide an argument to 'guile', it will act as a + multi-line command, like 'define'. In this case, the Guile script + is made up of subsequent command lines, given after the 'guile' + command. This command list is terminated using a line containing + 'end'. For example: + + (gdb) guile + >(display 23) + >(newline) + >end + 23 + + It is also possible to execute a Guile script from the GDB +interpreter: + +'source script-name' + The script name must end with '.scm' and GDB must be configured to + recognize the script language based on filename extension using the + 'script-extension' setting. *Note Extending GDB: Extending GDB. + +'guile (load "script-name")' + This method uses the 'load' Guile function. It takes a string + argument that is the name of the script to load. See the Guile + documentation for a description of this function. (*note + (guile)Loading::). + + +File: gdb.info, Node: Guile API, Next: Guile Auto-loading, Prev: Guile Commands, Up: Guile + +23.4.3 Guile API +---------------- + +You can get quick online help for GDB's Guile API by issuing the command +'help guile', or by issuing the command ',help' from an interactive +Guile session. Furthermore, most Guile procedures provided by GDB have +doc strings which can be obtained with ',describe PROCEDURE-NAME' or ',d +PROCEDURE-NAME' from the Guile interactive prompt. + +* Menu: + +* Basic Guile:: Basic Guile Functions +* Guile Configuration:: Guile configuration variables +* GDB Scheme Data Types:: Scheme representations of GDB objects +* Guile Exception Handling:: How Guile exceptions are translated +* Values From Inferior In Guile:: Guile representation of values +* Arithmetic In Guile:: Arithmetic in Guile +* Types In Guile:: Guile representation of types +* Guile Pretty Printing API:: Pretty-printing values with Guile +* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer +* Writing a Guile Pretty-Printer:: Writing a pretty-printer +* Commands In Guile:: Implementing new commands in Guile +* Parameters In Guile:: Adding new GDB parameters +* Progspaces In Guile:: Program spaces +* Objfiles In Guile:: Object files in Guile +* Frames In Guile:: Accessing inferior stack frames from Guile +* Blocks In Guile:: Accessing blocks from Guile +* Symbols In Guile:: Guile representation of symbols +* Symbol Tables In Guile:: Guile representation of symbol tables +* Breakpoints In Guile:: Manipulating breakpoints using Guile +* Lazy Strings In Guile:: Guile representation of lazy strings +* Architectures In Guile:: Guile representation of architectures +* Disassembly In Guile:: Disassembling instructions from Guile +* I/O Ports in Guile:: GDB I/O ports +* Memory Ports in Guile:: Accessing memory through ports and bytevectors +* Iterators In Guile:: Basic iterator support + + +File: gdb.info, Node: Basic Guile, Next: Guile Configuration, Up: Guile API + +23.4.3.1 Basic Guile +.................... + +At startup, GDB overrides Guile's 'current-output-port' and +'current-error-port' to print using GDB's output-paging streams. A +Guile program which outputs to one of these streams may have its output +interrupted by the user (*note Screen Size::). In this situation, a +Guile 'signal' exception is thrown with value 'SIGINT'. + + Guile's history mechanism uses the same naming as GDB's, namely the +user of dollar-variables (e.g., $1, $2, etc.). The results of +evaluations in Guile and in GDB are counted separately, '$1' in Guile is +not the same value as '$1' in GDB. + + GDB is not thread-safe. If your Guile program uses multiple threads, +you must be careful to only call GDB-specific functions in the GDB +thread. + + Some care must be taken when writing Guile code to run in GDB. Two +things are worth noting in particular: + + * GDB installs handlers for 'SIGCHLD' and 'SIGINT'. Guile code must + not override these, or even change the options using 'sigaction'. + If your program changes the handling of these signals, GDB will + most likely stop working correctly. Note that it is unfortunately + common for GUI toolkits to install a 'SIGCHLD' handler. + + * GDB takes care to mark its internal file descriptors as + close-on-exec. However, this cannot be done in a thread-safe way + on all platforms. Your Guile programs should be aware of this and + should both create new file descriptors with the close-on-exec flag + set and arrange to close unneeded file descriptors before starting + a child process. + + GDB introduces a new Guile module, named 'gdb'. All methods and +classes added by GDB are placed in this module. GDB does not +automatically 'import' the 'gdb' module, scripts must do this +themselves. There are various options for how to import a module, so +GDB leaves the choice of how the 'gdb' module is imported to the user. +To simplify interactive use, it is recommended to add one of the +following to your ~/.gdbinit. + + guile (use-modules (gdb)) + + guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:))) + + Which one to choose depends on your preference. The second one adds +'gdb:' as a prefix to all module functions and variables. + + The rest of this manual assumes the 'gdb' module has been imported +without any prefix. See the Guile documentation for 'use-modules' for +more information (*note (guile)Using Guile Modules::). + + Example: + + (gdb) guile (value-type (make-value 1)) + ERROR: Unbound variable: value-type + Error while executing Scheme code. + (gdb) guile (use-modules (gdb)) + (gdb) guile (value-type (make-value 1)) + int + (gdb) + + The '(gdb)' module provides these basic Guile functions. + + -- Scheme Procedure: execute command [#:from-tty boolean] + [#:to-string boolean] + Evaluate COMMAND, a string, as a GDB CLI command. If a GDB + exception happens while COMMAND runs, it is translated as described + in *note Guile Exception Handling: Guile Exception Handling. + + FROM-TTY specifies whether GDB ought to consider this command as + having originated from the user invoking it interactively. It must + be a boolean value. If omitted, it defaults to '#f'. + + By default, any output produced by COMMAND is sent to GDB's + standard output (and to the log output if logging is turned on). + If the TO-STRING parameter is '#t', then output will be collected + by 'execute' and returned as a string. The default is '#f', in + which case the return value is unspecified. If TO-STRING is '#t', + the GDB virtual terminal will be temporarily set to unlimited width + and height, and its pagination will be disabled; *note Screen + Size::. + + -- Scheme Procedure: history-ref number + Return a value from GDB's value history (*note Value History::). + The NUMBER argument indicates which history element to return. If + NUMBER is negative, then GDB will take its absolute value and count + backward from the last element (i.e., the most recent element) to + find the value to return. If NUMBER is zero, then GDB will return + the most recent element. If the element specified by NUMBER + doesn't exist in the value history, a 'gdb:error' exception will be + raised. + + If no exception is raised, the return value is always an instance + of '' (*note Values From Inferior In Guile::). + + _Note:_ GDB's value history is independent of Guile's. '$1' in + GDB's value history contains the result of evaluating an expression + from GDB's command line and '$1' from Guile's history contains the + result of evaluating an expression from Guile's command line. + + -- Scheme Procedure: history-append! value + Append VALUE, an instance of '', to GDB's value history. + Return its index in the history. + + Putting into history values returned by Guile extensions will allow + the user convenient access to those values via CLI history + facilities. + + -- Scheme Procedure: parse-and-eval expression + Parse EXPRESSION as an expression in the current language, evaluate + it, and return the result as a ''. The EXPRESSION must + be a string. + + This function can be useful when implementing a new command (*note + Commands In Guile::), as it provides a way to parse the command's + arguments as an expression. It is also is useful when computing + values. For example, it is the only way to get the value of a + convenience variable (*note Convenience Vars::) as a ''. + + +File: gdb.info, Node: Guile Configuration, Next: GDB Scheme Data Types, Prev: Basic Guile, Up: Guile API + +23.4.3.2 Guile Configuration +............................ + +GDB provides these Scheme functions to access various configuration +parameters. + + -- Scheme Procedure: data-directory + Return a string containing GDB's data directory. This directory + contains GDB's ancillary files. + + -- Scheme Procedure: guile-data-directory + Return a string containing GDB's Guile data directory. This + directory contains the Guile modules provided by GDB. + + -- Scheme Procedure: gdb-version + Return a string containing the GDB version. + + -- Scheme Procedure: host-config + Return a string containing the host configuration. This is the + string passed to '--host' when GDB was configured. + + -- Scheme Procedure: target-config + Return a string containing the target configuration. This is the + string passed to '--target' when GDB was configured. + + +File: gdb.info, Node: GDB Scheme Data Types, Next: Guile Exception Handling, Prev: Guile Configuration, Up: Guile API + +23.4.3.3 GDB Scheme Data Types +.............................. + +The values exposed by GDB to Guile are known as "GDB objects". There +are several kinds of GDB object, and each is disjoint from all other +types known to Guile. + + -- Scheme Procedure: gdb-object-kind object + Return the kind of the GDB object, e.g., '', as a + symbol. + + GDB defines the following object types: + +'' + *Note Architectures In Guile::. + +'' + *Note Blocks In Guile::. + +'' + *Note Blocks In Guile::. + +'' + *Note Breakpoints In Guile::. + +'' + *Note Commands In Guile::. + +'' + *Note Guile Exception Handling::. + +'' + *Note Frames In Guile::. + +'' + *Note Iterators In Guile::. + +'' + *Note Lazy Strings In Guile::. + +'' + *Note Objfiles In Guile::. + +'' + *Note Parameters In Guile::. + +'' + *Note Guile Pretty Printing API::. + +'' + *Note Guile Pretty Printing API::. + +'' + *Note Progspaces In Guile::. + +'' + *Note Symbols In Guile::. + +'' + *Note Symbol Tables In Guile::. + +'' + *Note Symbol Tables In Guile::. + +'' + *Note Types In Guile::. + +'' + *Note Types In Guile::. + +'' + *Note Values From Inferior In Guile::. + + The following GDB objects are managed internally so that the Scheme +function 'eq?' may be applied to them. + +'' +'' +'' +'' +'' +'' +'' +'' +'' + + +File: gdb.info, Node: Guile Exception Handling, Next: Values From Inferior In Guile, Prev: GDB Scheme Data Types, Up: Guile API + +23.4.3.4 Guile Exception Handling +................................. + +When executing the 'guile' command, Guile exceptions uncaught within the +Guile code are translated to calls to the GDB error-reporting mechanism. +If the command that called 'guile' does not handle the error, GDB will +terminate it and report the error according to the setting of the 'guile +print-stack' parameter. + + The 'guile print-stack' parameter has three settings: + +'none' + Nothing is printed. + +'message' + An error message is printed containing the Guile exception name, + the associated value, and the Guile call stack backtrace at the + point where the exception was raised. Example: + + (gdb) guile (display foo) + ERROR: In procedure memoize-variable-access!: + ERROR: Unbound variable: foo + Error while executing Scheme code. + +'full' + In addition to an error message a full backtrace is printed. + + (gdb) set guile print-stack full + (gdb) guile (display foo) + Guile Backtrace: + In ice-9/boot-9.scm: + 157: 10 [catch #t # ...] + In unknown file: + ?: 9 [apply-smob/1 #] + In ice-9/boot-9.scm: + 157: 8 [catch #t # ...] + In unknown file: + ?: 7 [apply-smob/1 #] + ?: 6 [call-with-input-string "(display foo)" ...] + In ice-9/boot-9.scm: + 2320: 5 [save-module-excursion #] + In ice-9/eval-string.scm: + 44: 4 [read-and-eval # #:lang ...] + 37: 3 [lp (display foo)] + In ice-9/eval.scm: + 387: 2 [eval # ()] + 393: 1 [eval # ()] + In unknown file: + ?: 0 [memoize-variable-access! # ...] + + ERROR: In procedure memoize-variable-access!: + ERROR: Unbound variable: foo + Error while executing Scheme code. + + GDB errors that happen in GDB commands invoked by Guile code are +converted to Guile exceptions. The type of the Guile exception depends +on the error. + + Guile procedures provided by GDB can throw the standard Guile +exceptions like 'wrong-type-arg' and 'out-of-range'. + + User interrupt (via 'C-c' or by typing 'q' at a pagination prompt) is +translated to a Guile 'signal' exception with value 'SIGINT'. + + GDB Guile procedures can also throw these exceptions: + +'gdb:error' + This exception is a catch-all for errors generated from within GDB. + +'gdb:invalid-object' + This exception is thrown when accessing Guile objects that wrap + underlying GDB objects have become invalid. For example, a + '' object becomes invalid if the user deletes it + from the command line. The object still exists in Guile, but the + object it represents is gone. Further operations on this + breakpoint will throw this exception. + +'gdb:memory-error' + This exception is thrown when an operation tried to access invalid + memory in the inferior. + +'gdb:pp-type-error' + This exception is thrown when a Guile pretty-printer passes a bad + object to GDB. + + The following exception-related procedures are provided by the +'(gdb)' module. + + -- Scheme Procedure: make-exception key args + Return a '' object given by its KEY and ARGS, which + are the standard Guile parameters of an exception. See the Guile + documentation for more information (*note (guile)Exceptions::). + + -- Scheme Procedure: exception? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: exception-key exception + Return the ARGS field of a '' object. + + -- Scheme Procedure: exception-args exception + Return the ARGS field of a '' object. + + +File: gdb.info, Node: Values From Inferior In Guile, Next: Arithmetic In Guile, Prev: Guile Exception Handling, Up: Guile API + +23.4.3.5 Values From Inferior In Guile +...................................... + +GDB provides values it obtains from the inferior program in an object of +type ''. GDB uses this object for its internal bookkeeping +of the inferior's values, and for fetching values when necessary. + + GDB does not memoize '' objects. 'make-value' always +returns a fresh object. + + (gdb) guile (eq? (make-value 1) (make-value 1)) + $1 = #f + (gdb) guile (equal? (make-value 1) (make-value 1)) + $1 = #t + + A '' that represents a function can be executed via +inferior function call with 'value-call'. Any arguments provided to the +call must match the function's prototype, and must be provided in the +order specified by that prototype. + + For example, 'some-val' is a '' instance representing a +function that takes two integers as arguments. To execute this +function, call it like so: + + (define result (value-call some-val 10 20)) + + Any values returned from a function call are '' objects. + + Note: Unlike Python scripting in GDB, inferior values that are simple +scalars cannot be used directly in Scheme expressions that are valid for +the value's data type. For example, '(+ (parse-and-eval "int_variable") +2)' does not work. And inferior values that are structures or instances +of some class cannot be accessed using any special syntax, instead +'value-field' must be used. + + The following value-related procedures are provided by the '(gdb)' +module. + + -- Scheme Procedure: value? object + Return '#t' if OBJECT is a '' object. Otherwise return + '#f'. + + -- Scheme Procedure: make-value value [#:type type] + Many Scheme values can be converted directly to a '' + with this procedure. If TYPE is specified, the result is a value + of this type, and if VALUE can't be represented with this type an + exception is thrown. Otherwise the type of the result is + determined from VALUE as described below. + + *Note Architectures In Guile::, for a list of the builtin types for + an architecture. + + Here's how Scheme values are converted when TYPE argument to + 'make-value' is not specified: + + Scheme boolean + A Scheme boolean is converted the boolean type for the current + language. + + Scheme integer + A Scheme integer is converted to the first of a C 'int', + 'unsigned int', 'long', 'unsigned long', 'long long' or + 'unsigned long long' type for the current architecture that + can represent the value. + + If the Scheme integer cannot be represented as a target + integer an 'out-of-range' exception is thrown. + + Scheme real + A Scheme real is converted to the C 'double' type for the + current architecture. + + Scheme string + A Scheme string is converted to a string in the current target + language using the current target encoding. Characters that + cannot be represented in the current target encoding are + replaced with the corresponding escape sequence. This is + Guile's 'SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE' conversion + strategy (*note (guile)Strings::). + + Passing TYPE is not supported in this case, if it is provided + a 'wrong-type-arg' exception is thrown. + + '' + If VALUE is a '' object (*note Lazy Strings + In Guile::), then the 'lazy-string->value' procedure is + called, and its result is used. + + Passing TYPE is not supported in this case, if it is provided + a 'wrong-type-arg' exception is thrown. + + Scheme bytevector + If VALUE is a Scheme bytevector and TYPE is provided, VALUE + must be the same size, in bytes, of values of type TYPE, and + the result is essentially created by using 'memcpy'. + + If VALUE is a Scheme bytevector and TYPE is not provided, the + result is an array of type 'uint8' of the same length. + + -- Scheme Procedure: value-optimized-out? value + Return '#t' if the compiler optimized out VALUE, thus it is not + available for fetching from the inferior. Otherwise return '#f'. + + -- Scheme Procedure: value-address value + If VALUE is addressable, returns a '' object + representing the address. Otherwise, '#f' is returned. + + -- Scheme Procedure: value-type value + Return the type of VALUE as a '' object (*note Types In + Guile::). + + -- Scheme Procedure: value-dynamic-type value + Return the dynamic type of VALUE. This uses C++ run-time type + information (RTTI) to determine the dynamic type of the value. If + the value is of class type, it will return the class in which the + value is embedded, if any. If the value is of pointer or reference + to a class type, it will compute the dynamic type of the referenced + object, and return a pointer or reference to that type, + respectively. In all other cases, it will return the value's + static type. + + Note that this feature will only work when debugging a C++ program + that includes RTTI for the object in question. Otherwise, it will + just return the static type of the value as in 'ptype foo'. *Note + ptype: Symbols. + + -- Scheme Procedure: value-cast value type + Return a new instance of '' that is the result of + casting VALUE to the type described by TYPE, which must be a + '' object. If the cast cannot be performed for some + reason, this method throws an exception. + + -- Scheme Procedure: value-dynamic-cast value type + Like 'value-cast', but works as if the C++ 'dynamic_cast' operator + were used. Consult a C++ reference for details. + + -- Scheme Procedure: value-reinterpret-cast value type + Like 'value-cast', but works as if the C++ 'reinterpret_cast' + operator were used. Consult a C++ reference for details. + + -- Scheme Procedure: value-dereference value + For pointer data types, this method returns a new '' + object whose contents is the object pointed to by VALUE. For + example, if 'foo' is a C pointer to an 'int', declared in your C + program as + + int *foo; + + then you can use the corresponding '' to access what + 'foo' points to like this: + + (define bar (value-dereference foo)) + + The result 'bar' will be a '' object holding the value + pointed to by 'foo'. + + A similar function 'value-referenced-value' exists which also + returns '' objects corresponding to the values pointed + to by pointer values (and additionally, values referenced by + reference values). However, the behavior of 'value-dereference' + differs from 'value-referenced-value' by the fact that the behavior + of 'value-dereference' is identical to applying the C unary + operator '*' on a given value. For example, consider a reference + to a pointer 'ptrref', declared in your C++ program as + + typedef int *intptr; + ... + int val = 10; + intptr ptr = &val; + intptr &ptrref = ptr; + + Though 'ptrref' is a reference value, one can apply the method + 'value-dereference' to the '' object corresponding to it + and obtain a '' which is identical to that corresponding + to 'val'. However, if you apply the method + 'value-referenced-value', the result would be a '' + object identical to that corresponding to 'ptr'. + + (define scm-ptrref (parse-and-eval "ptrref")) + (define scm-val (value-dereference scm-ptrref)) + (define scm-ptr (value-referenced-value scm-ptrref)) + + The '' object 'scm-val' is identical to that + corresponding to 'val', and 'scm-ptr' is identical to that + corresponding to 'ptr'. In general, 'value-dereference' can be + applied whenever the C unary operator '*' can be applied to the + corresponding C value. For those cases where applying both + 'value-dereference' and 'value-referenced-value' is allowed, the + results obtained need not be identical (as we have seen in the + above example). The results are however identical when applied on + '' objects corresponding to pointers ('' + objects with type code 'TYPE_CODE_PTR') in a C/C++ program. + + -- Scheme Procedure: value-referenced-value value + For pointer or reference data types, this method returns a new + '' object corresponding to the value referenced by the + pointer/reference value. For pointer data types, + 'value-dereference' and 'value-referenced-value' produce identical + results. The difference between these methods is that + 'value-dereference' cannot get the values referenced by reference + values. For example, consider a reference to an 'int', declared in + your C++ program as + + int val = 10; + int &ref = val; + + then applying 'value-dereference' to the '' object + corresponding to 'ref' will result in an error, while applying + 'value-referenced-value' will result in a '' object + identical to that corresponding to 'val'. + + (define scm-ref (parse-and-eval "ref")) + (define err-ref (value-dereference scm-ref)) ;; error + (define scm-val (value-referenced-value scm-ref)) ;; ok + + The '' object 'scm-val' is identical to that + corresponding to 'val'. + + -- Scheme Procedure: value-reference-value value + Return a new '' object which is a reference to the value + encapsulated by '' object VALUE. + + -- Scheme Procedure: value-rvalue-reference-value value + Return a new '' object which is an rvalue reference to + the value encapsulated by '' object VALUE. + + -- Scheme Procedure: value-const-value value + Return a new '' object which is a 'const' version of + '' object VALUE. + + -- Scheme Procedure: value-field value field-name + Return field FIELD-NAME from '' object VALUE. + + -- Scheme Procedure: value-subscript value index + Return the value of array VALUE at index INDEX. The VALUE argument + must be a subscriptable '' object. + + -- Scheme Procedure: value-call value arg-list + Perform an inferior function call, taking VALUE as a pointer to the + function to call. Each element of list ARG-LIST must be a + object or an object that can be converted to a value. + The result is the value returned by the function. + + -- Scheme Procedure: value->bool value + Return the Scheme boolean representing '' VALUE. The + value must be "integer like". Pointers are ok. + + -- Scheme Procedure: value->integer + Return the Scheme integer representing '' VALUE. The + value must be "integer like". Pointers are ok. + + -- Scheme Procedure: value->real + Return the Scheme real number representing '' VALUE. + The value must be a number. + + -- Scheme Procedure: value->bytevector + Return a Scheme bytevector with the raw contents of '' + VALUE. No transformation, endian or otherwise, is performed. + + -- Scheme Procedure: value->string value [#:encoding encoding] + [#:errors errors] [#:length length] + If VALUE> represents a string, then this method converts the + contents to a Guile string. Otherwise, this method will throw an + exception. + + Values are interpreted as strings according to the rules of the + current language. If the optional length argument is given, the + string will be converted to that length, and will include any + embedded zeroes that the string may contain. Otherwise, for + languages where the string is zero-terminated, the entire string + will be converted. + + For example, in C-like languages, a value is a string if it is a + pointer to or an array of characters or ints of type 'wchar_t', + 'char16_t', or 'char32_t'. + + If the optional ENCODING argument is given, it must be a string + naming the encoding of the string in the '', such as + '"ascii"', '"iso-8859-6"' or '"utf-8"'. It accepts the same + encodings as the corresponding argument to Guile's + 'scm_from_stringn' function, and the Guile codec machinery will be + used to convert the string. If ENCODING is not given, or if + ENCODING is the empty string, then either the 'target-charset' + (*note Character Sets::) will be used, or a language-specific + encoding will be used, if the current language is able to supply + one. + + The optional ERRORS argument is one of '#f', 'error' or + 'substitute'. 'error' and 'substitute' must be symbols. If ERRORS + is not specified, or if its value is '#f', then the default + conversion strategy is used, which is set with the Scheme function + 'set-port-conversion-strategy!'. If the value is ''error' then an + exception is thrown if there is any conversion error. If the value + is ''substitute' then any conversion error is replaced with + question marks. *Note (guile)Strings::. + + If the optional LENGTH argument is given, the string will be + fetched and converted to the given length. The length must be a + Scheme integer and not a '' integer. + + -- Scheme Procedure: value->lazy-string value [#:encoding encoding] + [#:length length] + If this '' represents a string, then this method + converts VALUE to a '' integer. + + -- Scheme Procedure: value-lazy? value + Return '#t' if VALUE has not yet been fetched from the inferior. + Otherwise return '#f'. GDB does not fetch values until necessary, + for efficiency. For example: + + (define myval (parse-and-eval "somevar")) + + The value of 'somevar' is not fetched at this time. It will be + fetched when the value is needed, or when the 'fetch-lazy' + procedure is invoked. + + -- Scheme Procedure: make-lazy-value type address + Return a '' that will be lazily fetched from the target. + The object of type '' whose value to fetch is specified + by its TYPE and its target memory ADDRESS, which is a Scheme + integer. + + -- Scheme Procedure: value-fetch-lazy! value + If VALUE is a lazy value ('(value-lazy? value)' is '#t'), then the + value is fetched from the inferior. Any errors that occur in the + process will produce a Guile exception. + + If VALUE is not a lazy value, this method has no effect. + + The result of this function is unspecified. + + -- Scheme Procedure: value-print value + Return the string representation (print form) of '' + VALUE. + + +File: gdb.info, Node: Arithmetic In Guile, Next: Types In Guile, Prev: Values From Inferior In Guile, Up: Guile API + +23.4.3.6 Arithmetic In Guile +............................ + +The '(gdb)' module provides several functions for performing arithmetic +on '' objects. The arithmetic is performed as if it were +done by the target, and therefore has target semantics which are not +necessarily those of Scheme. For example operations work with a fixed +precision, not the arbitrary precision of Scheme. + + Wherever a function takes an integer or pointer as an operand, GDB +will convert appropriate Scheme values to perform the operation. + + -- Scheme Procedure: value-add a b + + -- Scheme Procedure: value-sub a b + + -- Scheme Procedure: value-mul a b + + -- Scheme Procedure: value-div a b + + -- Scheme Procedure: value-rem a b + + -- Scheme Procedure: value-mod a b + + -- Scheme Procedure: value-pow a b + + -- Scheme Procedure: value-not a + + -- Scheme Procedure: value-neg a + + -- Scheme Procedure: value-pos a + + -- Scheme Procedure: value-abs a + + -- Scheme Procedure: value-lsh a b + + -- Scheme Procedure: value-rsh a b + + -- Scheme Procedure: value-min a b + + -- Scheme Procedure: value-max a b + + -- Scheme Procedure: value-lognot a + + -- Scheme Procedure: value-logand a b + + -- Scheme Procedure: value-logior a b + + -- Scheme Procedure: value-logxor a b + + -- Scheme Procedure: value=? a b + + -- Scheme Procedure: value? a b + + -- Scheme Procedure: value>=? a b + + Scheme does not provide a 'not-equal' function, and thus Guile +support in GDB does not either. + + +File: gdb.info, Node: Types In Guile, Next: Guile Pretty Printing API, Prev: Arithmetic In Guile, Up: Guile API + +23.4.3.7 Types In Guile +....................... + +GDB represents types from the inferior in objects of type ''. + + The following type-related procedures are provided by the '(gdb)' +module. + + -- Scheme Procedure: type? object + Return '#t' if OBJECT is an object of type ''. Otherwise + return '#f'. + + -- Scheme Procedure: lookup-type name [#:block block] + This function looks up a type by its NAME, which must be a string. + + If BLOCK is given, it is an object of type '', and NAME + is looked up in that scope. Otherwise, it is searched for + globally. + + Ordinarily, this function will return an instance of ''. + If the named type cannot be found, it will throw an exception. + + -- Scheme Procedure: type-code type + Return the type code of TYPE. The type code will be one of the + 'TYPE_CODE_' constants defined below. + + -- Scheme Procedure: type-tag type + Return the tag name of TYPE. The tag name is the name after + 'struct', 'union', or 'enum' in C and C++; not all languages have + this concept. If this type has no tag name, then '#f' is returned. + + -- Scheme Procedure: type-name type + Return the name of TYPE. If this type has no name, then '#f' is + returned. + + -- Scheme Procedure: type-print-name type + Return the print name of TYPE. This returns something even for + anonymous types. For example, for an anonymous C struct '"struct + {...}"' is returned. + + -- Scheme Procedure: type-sizeof type + Return the size of this type, in target 'char' units. Usually, a + target's 'char' type will be an 8-bit byte. However, on some + unusual platforms, this type may have a different size. + + -- Scheme Procedure: type-strip-typedefs type + Return a new '' that represents the real type of TYPE, + after removing all layers of typedefs. + + -- Scheme Procedure: type-array type n1 [n2] + Return a new '' object which represents an array of this + type. If one argument is given, it is the inclusive upper bound of + the array; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the array, and + the second argument is the upper bound of the array. An array's + length must not be negative, but the bounds can be. + + -- Scheme Procedure: type-vector type n1 [n2] + Return a new '' object which represents a vector of this + type. If one argument is given, it is the inclusive upper bound of + the vector; in this case the lower bound is zero. If two arguments + are given, the first argument is the lower bound of the vector, and + the second argument is the upper bound of the vector. A vector's + length must not be negative, but the bounds can be. + + The difference between an 'array' and a 'vector' is that arrays + behave like in C: when used in expressions they decay to a pointer + to the first element whereas vectors are treated as first class + values. + + -- Scheme Procedure: type-pointer type + Return a new '' object which represents a pointer to + TYPE. + + -- Scheme Procedure: type-range type + Return a list of two elements: the low bound and high bound of + TYPE. If TYPE does not have a range, an exception is thrown. + + -- Scheme Procedure: type-reference type + Return a new '' object which represents a reference to + TYPE. + + -- Scheme Procedure: type-target type + Return a new '' object which represents the target type + of TYPE. + + For a pointer type, the target type is the type of the pointed-to + object. For an array type (meaning C-like arrays), the target type + is the type of the elements of the array. For a function or method + type, the target type is the type of the return value. For a + complex type, the target type is the type of the elements. For a + typedef, the target type is the aliased type. + + If the type does not have a target, this method will throw an + exception. + + -- Scheme Procedure: type-const type + Return a new '' object which represents a + 'const'-qualified variant of TYPE. + + -- Scheme Procedure: type-volatile type + Return a new '' object which represents a + 'volatile'-qualified variant of TYPE. + + -- Scheme Procedure: type-unqualified type + Return a new '' object which represents an unqualified + variant of TYPE. That is, the result is neither 'const' nor + 'volatile'. + + -- Scheme Procedure: type-num-fields + Return the number of fields of '' TYPE. + + -- Scheme Procedure: type-fields type + Return the fields of TYPE as a list. For structure and union + types, 'fields' has the usual meaning. Range types have two + fields, the minimum and maximum values. Enum types have one field + per enum constant. Function and method types have one field per + parameter. The base types of C++ classes are also represented as + fields. If the type has no fields, or does not fit into one of + these categories, an empty list will be returned. *Note Fields of + a type in Guile::. + + -- Scheme Procedure: make-field-iterator type + Return the fields of TYPE as a object. *Note + Iterators In Guile::. + + -- Scheme Procedure: type-field type field-name + Return field named FIELD-NAME in TYPE. The result is an object of + type ''. *Note Fields of a type in Guile::. If the + type does not have fields, or FIELD-NAME is not a field of TYPE, an + exception is thrown. + + For example, if 'some-type' is a '' instance holding a + structure type, you can access its 'foo' field with: + + (define bar (type-field some-type "foo")) + + 'bar' will be a '' object. + + -- Scheme Procedure: type-has-field? type name + Return '#t' if '' TYPE has field named NAME. Otherwise + return '#f'. + + Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the '(gdb)' module: + +'TYPE_CODE_PTR' + The type is a pointer. + +'TYPE_CODE_ARRAY' + The type is an array. + +'TYPE_CODE_STRUCT' + The type is a structure. + +'TYPE_CODE_UNION' + The type is a union. + +'TYPE_CODE_ENUM' + The type is an enum. + +'TYPE_CODE_FLAGS' + A bit flags type, used for things such as status registers. + +'TYPE_CODE_FUNC' + The type is a function. + +'TYPE_CODE_INT' + The type is an integer type. + +'TYPE_CODE_FLT' + A floating point type. + +'TYPE_CODE_VOID' + The special type 'void'. + +'TYPE_CODE_SET' + A Pascal set type. + +'TYPE_CODE_RANGE' + A range type, that is, an integer type with bounds. + +'TYPE_CODE_STRING' + A string type. Note that this is only used for certain languages + with language-defined string types; C strings are not represented + this way. + +'TYPE_CODE_BITSTRING' + A string of bits. It is deprecated. + +'TYPE_CODE_ERROR' + An unknown or erroneous type. + +'TYPE_CODE_METHOD' + A method type, as found in C++. + +'TYPE_CODE_METHODPTR' + A pointer-to-member-function. + +'TYPE_CODE_MEMBERPTR' + A pointer-to-member. + +'TYPE_CODE_REF' + A reference type. + +'TYPE_CODE_RVALUE_REF' + A C++11 rvalue reference type. + +'TYPE_CODE_CHAR' + A character type. + +'TYPE_CODE_BOOL' + A boolean type. + +'TYPE_CODE_COMPLEX' + A complex float type. + +'TYPE_CODE_TYPEDEF' + A typedef to some other type. + +'TYPE_CODE_NAMESPACE' + A C++ namespace. + +'TYPE_CODE_DECFLOAT' + A decimal floating point type. + +'TYPE_CODE_INTERNAL_FUNCTION' + A function internal to GDB. This is the type used to represent + convenience functions (*note Convenience Funs::). + +'gdb.TYPE_CODE_XMETHOD' + A method internal to GDB. This is the type used to represent + xmethods (*note Writing an Xmethod::). + +'gdb.TYPE_CODE_FIXED_POINT' + A fixed-point number. + +'gdb.TYPE_CODE_NAMESPACE' + A Fortran namelist. + + Further support for types is provided in the '(gdb types)' Guile +module (*note Guile Types Module::). + + Each field is represented as an object of type ''. + + The following field-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: field? object + Return '#t' if OBJECT is an object of type ''. + Otherwise return '#f'. + + -- Scheme Procedure: field-name field + Return the name of the field, or '#f' for anonymous fields. + + -- Scheme Procedure: field-type field + Return the type of the field. This is usually an instance of + '', but it can be '#f' in some situations. + + -- Scheme Procedure: field-enumval field + Return the enum value represented by '' FIELD. + + -- Scheme Procedure: field-bitpos field + Return the bit position of '' FIELD. This attribute is + not available for 'static' fields (as in C++). + + -- Scheme Procedure: field-bitsize field + If the field is packed, or is a bitfield, return the size of + '' FIELD in bits. Otherwise, zero is returned; in which + case the field's size is given by its type. + + -- Scheme Procedure: field-artificial? field + Return '#t' if the field is artificial, usually meaning that it was + provided by the compiler and not the user. Otherwise return '#f'. + + -- Scheme Procedure: field-base-class? field + Return '#t' if the field represents a base class of a C++ + structure. Otherwise return '#f'. + + +File: gdb.info, Node: Guile Pretty Printing API, Next: Selecting Guile Pretty-Printers, Prev: Types In Guile, Up: Guile API + +23.4.3.8 Guile Pretty Printing API +.................................. + +An example output is provided (*note Pretty Printing::). + + A pretty-printer is represented by an object of type +. Pretty-printer objects are created with +'make-pretty-printer'. + + The following pretty-printer-related procedures are provided by the +'(gdb)' module: + + -- Scheme Procedure: make-pretty-printer name lookup-function + Return a '' object named NAME. + + LOOKUP-FUNCTION is a function of one parameter: the value to be + printed. If the value is handled by this pretty-printer, then + LOOKUP-FUNCTION returns an object of type + to perform the actual pretty-printing. + Otherwise LOOKUP-FUNCTION returns '#f'. + + -- Scheme Procedure: pretty-printer? object + Return '#t' if OBJECT is a '' object. + Otherwise return '#f'. + + -- Scheme Procedure: pretty-printer-enabled? pretty-printer + Return '#t' if PRETTY-PRINTER is enabled. Otherwise return '#f'. + + -- Scheme Procedure: set-pretty-printer-enabled! pretty-printer flag + Set the enabled flag of PRETTY-PRINTER to FLAG. The value returned + is unspecified. + + -- Scheme Procedure: pretty-printers + Return the list of global pretty-printers. + + -- Scheme Procedure: set-pretty-printers! pretty-printers + Set the list of global pretty-printers to PRETTY-PRINTERS. The + value returned is unspecified. + + -- Scheme Procedure: make-pretty-printer-worker display-hint to-string + children + Return an object of type ''. + + This function takes three parameters: + + 'display-hint' + DISPLAY-HINT provides a hint to GDB or GDB front end via MI to + change the formatting of the value being printed. The value + must be a string or '#f' (meaning there is no hint). Several + values for DISPLAY-HINT are predefined by GDB: + + 'array' + Indicate that the object being printed is "array-like". + The CLI uses this to respect parameters such as 'set + print elements' and 'set print array'. + + 'map' + Indicate that the object being printed is "map-like", and + that the children of this value can be assumed to + alternate between keys and values. + + 'string' + Indicate that the object being printed is "string-like". + If the printer's 'to-string' function returns a Guile + string of some kind, then GDB will call its internal + language-specific string-printing function to format the + string. For the CLI this means adding quotation marks, + possibly escaping some characters, respecting 'set print + elements', and the like. + + 'to-string' + TO-STRING is either a function of one parameter, the + '' object, or '#f'. + + When printing from the CLI, if the 'to-string' method exists, + then GDB will prepend its result to the values returned by + 'children'. Exactly how this formatting is done is dependent + on the display hint, and may change as more hints are added. + Also, depending on the print settings (*note Print + Settings::), the CLI may print just the result of 'to-string' + in a stack trace, omitting the result of 'children'. + + If this method returns a string, it is printed verbatim. + + Otherwise, if this method returns an instance of + '', then GDB prints this value. This may result in + a call to another pretty-printer. + + If instead the method returns a Guile value which is + convertible to a '', then GDB performs the + conversion and prints the resulting value. Again, this may + result in a call to another pretty-printer. Guile scalars + (integers, floats, and booleans) and strings are convertible + to ''; other types are not. + + Finally, if this method returns '#f' then no further + operations are performed in this method and nothing is + printed. + + If the result is not one of these types, an exception is + raised. + + TO-STRING may also be '#f' in which case it is left to + CHILDREN to print the value. + + 'children' + CHILDREN is either a function of one parameter, the + '' object, or '#f'. + + GDB will call this function on a pretty-printer to compute the + children of the pretty-printer's value. + + This function must return a object. Each item + returned by the iterator must be a tuple holding two elements. + The first element is the "name" of the child; the second + element is the child's value. The value can be any Guile + object which is convertible to a GDB value. + + If CHILDREN is '#f', GDB will act as though the value has no + children. + + Children may be hidden from display based on the value of 'set + print max-depth' (*note Print Settings::). + + GDB provides a function which can be used to look up the default +pretty-printer for a '': + + -- Scheme Procedure: default-visualizer value + This function takes a '' object as an argument. If a + pretty-printer for this value exists, then it is returned. If no + such printer exists, then this returns '#f'. + + +File: gdb.info, Node: Selecting Guile Pretty-Printers, Next: Writing a Guile Pretty-Printer, Prev: Guile Pretty Printing API, Up: Guile API + +23.4.3.9 Selecting Guile Pretty-Printers +........................................ + +There are three sets of pretty-printers that GDB searches: + + * Per-objfile list of pretty-printers (*note Objfiles In Guile::). + * Per-progspace list of pretty-printers (*note Progspaces In + Guile::). + * The global list of pretty-printers (*note Guile Pretty Printing + API::). These printers are available when debugging any inferior. + + Pretty-printer lookup is done by passing the value to be printed to +the lookup function of each enabled object in turn. Lookup stops when a +lookup function returns a non-'#f' value or when the list is exhausted. +Lookup functions must return either a '' +object or '#f'. Otherwise an exception is thrown. + + GDB first checks the result of 'objfile-pretty-printers' of each +'' in the current program space and iteratively calls each +enabled lookup function in the list for that '' until a +non-'#f' object is returned. If no pretty-printer is found in the +objfile lists, GDB then searches the result of +'progspace-pretty-printers' of the current program space, calling each +enabled function until a non-'#f' object is returned. After these lists +have been exhausted, it tries the global pretty-printers list, obtained +with 'pretty-printers', again calling each enabled function until a +non-'#f' object is returned. + + The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, and +iterated over sequentially until the end of the list, or a +'' object is returned. + + For various reasons a pretty-printer may not work. For example, the +underlying data structure may have changed and the pretty-printer is out +of date. + + The consequences of a broken pretty-printer are severe enough that +GDB provides support for enabling and disabling individual printers. +For example, if 'print frame-arguments' is on, a backtrace can become +highly illegible if any argument is printed with a broken printer. + + Pretty-printers are enabled and disabled from Scheme by calling +'set-pretty-printer-enabled!'. *Note Guile Pretty Printing API::. + + +File: gdb.info, Node: Writing a Guile Pretty-Printer, Next: Commands In Guile, Prev: Selecting Guile Pretty-Printers, Up: Guile API + +23.4.3.10 Writing a Guile Pretty-Printer +........................................ + +A pretty-printer consists of two basic parts: a lookup function to +determine if the type is supported, and the printer itself. + + Here is an example showing how a 'std::string' printer might be +written. *Note Guile Pretty Printing API::, for details. + + (define (make-my-string-printer value) + "Print a my::string string" + (make-pretty-printer-worker + "string" + (lambda (printer) + (value-field value "_data")) + #f)) + + And here is an example showing how a lookup function for the printer +example above might be written. + + (define (str-lookup-function pretty-printer value) + (let ((tag (type-tag (value-type value)))) + (and tag + (string-prefix? "std::string<" tag) + (make-my-string-printer value)))) + + Then to register this printer in the global printer list: + + (append-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function)) + + The example lookup function extracts the value's type, and attempts +to match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a +object. If not, it returns '#f'. + + We recommend that you put your core pretty-printers into a Guile +package. If your pretty-printers are for use with a library, we further +recommend embedding a version number into the package name. This +practice will enable GDB to load multiple versions of your +pretty-printers at the same time, because they will have different +names. + + You should write auto-loaded code (*note Guile Auto-loading::) such +that it can be evaluated multiple times without changing its meaning. +An ideal auto-load file will consist solely of 'import's of your printer +modules, followed by a call to a register pretty-printers with the +current objfile. + + Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Guile package name will ensure that +GDB is able to load both sets of printers simultaneously. Then, because +the search for pretty-printers is done by objfile, and because your +auto-loaded code took care to register your library's printers with a +specific objfile, GDB will find the correct printers for the specific +version of the library used by each inferior. + + To continue the 'my::string' example, this code might appear in +'(my-project my-library v1)': + + (use-modules (gdb)) + (define (register-printers objfile) + (append-objfile-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function))) + +And then the corresponding contents of the auto-load file would be: + + (use-modules (gdb) (my-project my-library v1)) + (register-printers (current-objfile)) + + The previous example illustrates a basic pretty-printer. There are a +few things that can be improved on. The printer only handles one type, +whereas a library typically has several types. One could install a +lookup function for each desired type in the library, but one could also +have a single lookup function recognize several types. The latter is +the conventional way this is handled. If a pretty-printer can handle +multiple data types, then its "subprinters" are the printers for the +individual data types. + + The '(gdb printing)' module provides a formal way of solving this +problem (*note Guile Printing Module::). Here is another example that +handles multiple types. + + These are the types we are going to pretty-print: + + struct foo { int a, b; }; + struct bar { struct foo x, y; }; + + Here are the printers: + + (define (make-foo-printer value) + "Print a foo object" + (make-pretty-printer-worker + "foo" + (lambda (printer) + (format #f "a=<~a> b=<~a>" + (value-field value "a") (value-field value "a"))) + #f)) + + (define (make-bar-printer value) + "Print a bar object" + (make-pretty-printer-worker + "foo" + (lambda (printer) + (format #f "x=<~a> y=<~a>" + (value-field value "x") (value-field value "y"))) + #f)) + + This example doesn't need a lookup function, that is handled by the +'(gdb printing)' module. Instead a function is provided to build up the +object that handles the lookup. + + (use-modules (gdb printing)) + + (define (build-pretty-printer) + (let ((pp (make-pretty-printer-collection "my-library"))) + (pp-collection-add-tag-printer "foo" make-foo-printer) + (pp-collection-add-tag-printer "bar" make-bar-printer) + pp)) + + And here is the autoload support: + + (use-modules (gdb) (my-library)) + (append-objfile-pretty-printer! (current-objfile) (build-pretty-printer)) + + Finally, when this printer is loaded into GDB, here is the +corresponding output of 'info pretty-printer': + + (gdb) info pretty-printer + my_library.so: + my-library + foo + bar + + +File: gdb.info, Node: Commands In Guile, Next: Parameters In Guile, Prev: Writing a Guile Pretty-Printer, Up: Guile API + +23.4.3.11 Commands In Guile +........................... + +You can implement new GDB CLI commands in Guile. A CLI command object +is created with the 'make-command' Guile function, and added to GDB with +the 'register-command!' Guile function. This two-step approach is taken +to separate out the side-effect of adding the command to GDB from +'make-command'. + + There is no support for multi-line commands, that is commands that +consist of multiple lines and are terminated with 'end'. + + -- Scheme Procedure: make-command name [#:invoke invoke] + [#:command-class command-class] [#:completer-class completer] + [#:prefix? prefix] [#:doc doc-string] + + The argument NAME is the name of the command. If NAME consists of + multiple words, then the initial words are looked for as prefix + commands. In this case, if one of the prefix commands does not + exist, an exception is raised. + + The result is the '' object representing the command. + The command is not usable until it has been registered with GDB + with 'register-command!'. + + The rest of the arguments are optional. + + The argument INVOKE is a procedure of three arguments: SELF, ARGS + and FROM-TTY. The argument SELF is the '' object + representing the command. The argument ARGS is a string + representing the arguments passed to the command, after leading and + trailing whitespace has been stripped. The argument FROM-TTY is a + boolean flag and specifies whether the command should consider + itself to have been originated from the user invoking it + interactively. If this function throws an exception, it is turned + into a GDB 'error' call. Otherwise, the return value is ignored. + + The argument COMMAND-CLASS is one of the 'COMMAND_' constants + defined below. This argument tells GDB how to categorize the new + command in the help system. The default is 'COMMAND_NONE'. + + The argument COMPLETER is either '#f', one of the 'COMPLETE_' + constants defined below, or a procedure, also defined below. This + argument tells GDB how to perform completion for this command. If + not provided or if the value is '#f', then no completion is + performed on the command. + + The argument PREFIX is a boolean flag indicating whether the new + command is a prefix command; sub-commands of this command may be + registered. + + The argument DOC-STRING is help text for the new command. If no + documentation string is provided, the default value "This command + is not documented." is used. + + -- Scheme Procedure: register-command! command + Add COMMAND, a '' object, to GDB's list of commands. + It is an error to register a command more than once. The result is + unspecified. + + -- Scheme Procedure: command? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: dont-repeat + By default, a GDB command is repeated when the user enters a blank + line at the command prompt. A command can suppress this behavior + by invoking the 'dont-repeat' function. This is similar to the + user command 'dont-repeat', see *note dont-repeat: Define. + + -- Scheme Procedure: string->argv string + Convert a string to a list of strings split up according to GDB's + argv parsing rules. It is recommended to use this for consistency. + Arguments are separated by spaces and may be quoted. Example: + + scheme@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") + $1 = ("1" "2 \"3" "4 \"5" "6 '7") + + -- Scheme Procedure: throw-user-error message . args + Throw a 'gdb:user-error' exception. The argument MESSAGE is the + error message as a format string, like the FMT argument to the + 'format' Scheme function. *Note (guile)Formatted Output::. The + argument ARGS is a list of the optional arguments of MESSAGE. + + This is used when the command detects a user error of some kind, + say a bad command argument. + + (gdb) guile (use-modules (gdb)) + (gdb) guile + (register-command! (make-command "test-user-error" + #:command-class COMMAND_OBSCURE + #:invoke (lambda (self arg from-tty) + (throw-user-error "Bad argument ~a" arg)))) + end + (gdb) test-user-error ugh + ERROR: Bad argument ugh + + -- completer: self text word + If the COMPLETER option to 'make-command' is a procedure, it takes + three arguments: SELF which is the '' object, and TEXT + and WORD which are both strings. The argument TEXT holds the + complete command line up to the cursor's location. The argument + WORD holds the last word of the command line; this is computed + using a word-breaking heuristic. + + All forms of completion are handled by this function, that is, the + and key bindings (*note Completion::), and the + 'complete' command (*note complete: Help.). + + This procedure can return several kinds of values: + + * If the return value is a list, the contents of the list are + used as the completions. It is up to COMPLETER to ensure that + the contents actually do complete the word. An empty list is + allowed, it means that there were no completions available. + Only string elements of the list are used; other elements in + the list are ignored. + + * If the return value is a '' object, it is + iterated over to obtain the completions. It is up to + 'completer-procedure' to ensure that the results actually do + complete the word. Only string elements of the result are + used; other elements in the sequence are ignored. + + * All other results are treated as though there were no + available completions. + + When a new command is registered, it will have been declared as a +member of some general class of commands. This is used to classify +top-level commands in the on-line help system; note that prefix commands +are not listed under their own category but rather that of their +top-level command. The available classifications are represented by +constants defined in the 'gdb' module: + +'COMMAND_NONE' + The command does not belong to any particular class. A command in + this category will not be displayed in any of the help categories. + This is the default. + +'COMMAND_RUNNING' + The command is related to running the inferior. For example, + 'start', 'step', and 'continue' are in this category. Type 'help + running' at the GDB prompt to see a list of commands in this + category. + +'COMMAND_DATA' + The command is related to data or variables. For example, 'call', + 'find', and 'print' are in this category. Type 'help data' at the + GDB prompt to see a list of commands in this category. + +'COMMAND_STACK' + The command has to do with manipulation of the stack. For example, + 'backtrace', 'frame', and 'return' are in this category. Type + 'help stack' at the GDB prompt to see a list of commands in this + category. + +'COMMAND_FILES' + This class is used for file-related commands. For example, 'file', + 'list' and 'section' are in this category. Type 'help files' at + the GDB prompt to see a list of commands in this category. + +'COMMAND_SUPPORT' + This should be used for "support facilities", generally meaning + things that are useful to the user when interacting with GDB, but + not related to the state of the inferior. For example, 'help', + 'make', and 'shell' are in this category. Type 'help support' at + the GDB prompt to see a list of commands in this category. + +'COMMAND_STATUS' + The command is an 'info'-related command, that is, related to the + state of GDB itself. For example, 'info', 'macro', and 'show' are + in this category. Type 'help status' at the GDB prompt to see a + list of commands in this category. + +'COMMAND_BREAKPOINTS' + The command has to do with breakpoints. For example, 'break', + 'clear', and 'delete' are in this category. Type 'help + breakpoints' at the GDB prompt to see a list of commands in this + category. + +'COMMAND_TRACEPOINTS' + The command has to do with tracepoints. For example, 'trace', + 'actions', and 'tfind' are in this category. Type 'help + tracepoints' at the GDB prompt to see a list of commands in this + category. + +'COMMAND_USER' + The command is a general purpose command for the user, and + typically does not fit in one of the other categories. Type 'help + user-defined' at the GDB prompt to see a list of commands in this + category, as well as the list of gdb macros (*note Sequences::). + +'COMMAND_OBSCURE' + The command is only used in unusual circumstances, or is not of + general interest to users. For example, 'checkpoint', 'fork', and + 'stop' are in this category. Type 'help obscure' at the GDB prompt + to see a list of commands in this category. + +'COMMAND_MAINTENANCE' + The command is only useful to GDB maintainers. The 'maintenance' + and 'flushregs' commands are in this category. Type 'help + internals' at the GDB prompt to see a list of commands in this + category. + + A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it from +the 'completer' procedure. These predefined completion constants are +all defined in the 'gdb' module: + +'COMPLETE_NONE' + This constant means that no completion should be done. + +'COMPLETE_FILENAME' + This constant means that filename completion should be performed. + +'COMPLETE_LOCATION' + This constant means that location completion should be done. *Note + Location Specifications::. + +'COMPLETE_COMMAND' + This constant means that completion should examine GDB command + names. + +'COMPLETE_SYMBOL' + This constant means that completion should be done using symbol + names as the source. + +'COMPLETE_EXPRESSION' + This constant means that completion should be done on expressions. + Often this means completing on symbol names, but some language + parsers also have support for completing on field names. + + The following code snippet shows how a trivial CLI command can be +implemented in Guile: + + (gdb) guile + (register-command! (make-command "hello-world" + #:command-class COMMAND_USER + #:doc "Greet the whole world." + #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) + end + (gdb) hello-world + Hello, World! + + +File: gdb.info, Node: Parameters In Guile, Next: Progspaces In Guile, Prev: Commands In Guile, Up: Guile API + +23.4.3.12 Parameters In Guile +............................. + +You can implement new GDB "parameters" using Guile (1). + + There are many parameters that already exist and can be set in GDB. +Two examples are: 'set follow-fork' and 'set charset'. Setting these +parameters influences certain behavior in GDB. Similarly, you can +define parameters that can be used to influence behavior in custom Guile +scripts and commands. + + A new parameter is defined with the 'make-parameter' Guile function, +and added to GDB with the 'register-parameter!' Guile function. This +two-step approach is taken to separate out the side-effect of adding the +parameter to GDB from 'make-parameter'. + + Parameters are exposed to the user via the 'set' and 'show' commands. +*Note Help::. + + -- Scheme Procedure: make-parameter name + [#:command-class command-class] + [#:parameter-type parameter-type] [#:enum-list enum-list] + [#:set-func set-func] [#:show-func show-func] [#:doc doc] + [#:set-doc set-doc] [#:show-doc show-doc] + [#:initial-value initial-value] + + The argument NAME is the name of the new parameter. If NAME + consists of multiple words, then the initial words are looked for + as prefix parameters. An example of this can be illustrated with + the 'set print' set of parameters. If NAME is 'print foo', then + 'print' will be searched as the prefix parameter. In this case the + parameter can subsequently be accessed in GDB as 'set print foo'. + If NAME consists of multiple words, and no prefix parameter group + can be found, an exception is raised. + + The result is the '' object representing the + parameter. The parameter is not usable until it has been + registered with GDB with 'register-parameter!'. + + The rest of the arguments are optional. + + The argument COMMAND-CLASS should be one of the 'COMMAND_' + constants (*note Commands In Guile::). This argument tells GDB how + to categorize the new parameter in the help system. The default is + 'COMMAND_NONE'. + + The argument PARAMETER-TYPE should be one of the 'PARAM_' constants + defined below. This argument tells GDB the type of the new + parameter; this information is used for input validation and + completion. The default is 'PARAM_BOOLEAN'. + + If PARAMETER-TYPE is 'PARAM_ENUM', then ENUM-LIST must be a list of + strings. These strings represent the possible values for the + parameter. + + If PARAMETER-TYPE is not 'PARAM_ENUM', then the presence of + ENUM-LIST will cause an exception to be thrown. + + The argument SET-FUNC is a function of one argument: SELF which is + the '' object representing the parameter. GDB will + call this function when a PARAMETER's value has been changed via + the 'set' API (for example, 'set foo off'). The value of the + parameter has already been set to the new value. This function + must return a string to be displayed to the user. GDB will add a + trailing newline if the string is non-empty. GDB generally doesn't + print anything when a parameter is set, thus typically this + function should return '""'. A non-empty string result should + typically be used for displaying warnings and errors. + + The argument SHOW-FUNC is a function of two arguments: SELF which + is the '' object representing the parameter, and + SVALUE which is the string representation of the current value. + GDB will call this function when a PARAMETER's 'show' API has been + invoked (for example, 'show foo'). This function must return a + string, and will be displayed to the user. GDB will add a trailing + newline. + + The argument DOC is the help text for the new parameter. If there + is no documentation string, a default value is used. + + The argument SET-DOC is the help text for this parameter's 'set' + command. + + The argument SHOW-DOC is the help text for this parameter's 'show' + command. + + The argument INITIAL-VALUE specifies the initial value of the + parameter. If it is a function, it takes one parameter, the + '' object and its result is used as the initial + value of the parameter. The initial value must be valid for the + parameter type, otherwise an exception is thrown. + + -- Scheme Procedure: register-parameter! parameter + Add PARAMETER, a '' object, to GDB's list of + parameters. It is an error to register a parameter more than once. + The result is unspecified. + + -- Scheme Procedure: parameter? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: parameter-value parameter + Return the value of PARAMETER which may either be a + '' object or a string naming the parameter. + + -- Scheme Procedure: set-parameter-value! parameter new-value + Assign PARAMETER the value of NEW-VALUE. The argument PARAMETER + must be an object of type ''. GDB does validation + when assignments are made. + + When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the 'gdb' +module: + +'PARAM_BOOLEAN' + The value is a plain boolean. The Guile boolean values, '#t' and + '#f' are the only valid values. + +'PARAM_AUTO_BOOLEAN' + The value has three possible states: true, false, and 'auto'. In + Guile, true and false are represented using boolean constants, and + 'auto' is represented using '#:auto'. + +'PARAM_UINTEGER' + The value is an unsigned integer. The value of '#:unlimited' + should be interpreted to mean "unlimited", and the value of '0' is + reserved and should not be used. + +'PARAM_ZINTEGER' + The value is an integer. + +'PARAM_ZUINTEGER' + The value is an unsigned integer. + +'PARAM_ZUINTEGER_UNLIMITED' + The value is an integer in the range '[0, INT_MAX]'. The value of + '#:unlimited' means "unlimited", the value of '-1' is reserved and + should not be used, and other negative numbers are not allowed. + +'PARAM_STRING' + The value is a string. When the user modifies the string, any + escape sequences, such as '\t', '\f', and octal escapes, are + translated into corresponding characters and encoded into the + current host charset. + +'PARAM_STRING_NOESCAPE' + The value is a string. When the user modifies the string, escapes + are passed through untranslated. + +'PARAM_OPTIONAL_FILENAME' + The value is a either a filename (a string), or '#f'. + +'PARAM_FILENAME' + The value is a filename. This is just like + 'PARAM_STRING_NOESCAPE', but uses file names for completion. + +'PARAM_ENUM' + The value is a string, which must be one of a collection of string + constants provided when the parameter is created. + + ---------- Footnotes ---------- + + (1) Note that GDB parameters must not be confused with Guile’s +parameter objects (*note (guile)Parameters::). + + +File: gdb.info, Node: Progspaces In Guile, Next: Objfiles In Guile, Prev: Parameters In Guile, Up: Guile API + +23.4.3.13 Program Spaces In Guile +................................. + +A program space, or "progspace", represents a symbolic view of an +address space. It consists of all of the objfiles of the program. +*Note Objfiles In Guile::. *Note program spaces: Inferiors Connections +and Programs, for more details about program spaces. + + Each progspace is represented by an instance of the '' +smob. *Note GDB Scheme Data Types::. + + The following progspace-related functions are available in the +'(gdb)' module: + + -- Scheme Procedure: progspace? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: progspace-valid? progspace + Return '#t' if PROGSPACE is valid, '#f' if not. A + '' object can become invalid if the program it + refers to is not loaded in GDB any longer. + + -- Scheme Procedure: current-progspace + This function returns the program space of the currently selected + inferior. There is always a current progspace, this never returns + '#f'. *Note Inferiors Connections and Programs::. + + -- Scheme Procedure: progspaces + Return a list of all the progspaces currently known to GDB. + + -- Scheme Procedure: progspace-filename progspace + Return the absolute file name of PROGSPACE as a string. This is + the name of the file passed as the argument to the 'file' or + 'symbol-file' commands. If the program space does not have an + associated file name, then '#f' is returned. This occurs, for + example, when GDB is started without a program to debug. + + A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is + invalid. + + -- Scheme Procedure: progspace-objfiles progspace + Return the list of objfiles of PROGSPACE. The order of objfiles in + the result is arbitrary. Each element is an object of type + ''. *Note Objfiles In Guile::. + + A 'gdb:invalid-object-error' exception is thrown if PROGSPACE is + invalid. + + -- Scheme Procedure: progspace-pretty-printers progspace + Return the list of pretty-printers of PROGSPACE. Each element is + an object of type ''. *Note Guile Pretty + Printing API::, for more information. + + -- Scheme Procedure: set-progspace-pretty-printers! progspace + printer-list + Set the list of registered '' objects for + PROGSPACE to PRINTER-LIST. *Note Guile Pretty Printing API::, for + more information. + + +File: gdb.info, Node: Objfiles In Guile, Next: Frames In Guile, Prev: Progspaces In Guile, Up: Guile API + +23.4.3.14 Objfiles In Guile +........................... + +GDB loads symbols for an inferior from various symbol-containing files +(*note Files::). These include the primary executable file, any shared +libraries used by the inferior, and any separate debug info files (*note +Separate Debug Files::). GDB calls these symbol-containing files +"objfiles". + + Each objfile is represented as an object of type ''. + + The following objfile-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: objfile? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: objfile-valid? objfile + Return '#t' if OBJFILE is valid, '#f' if not. A '' + object can become invalid if the object file it refers to is not + loaded in GDB any longer. All other '' procedures + will throw an exception if it is invalid at the time the procedure + is called. + + -- Scheme Procedure: objfile-filename objfile + Return the file name of OBJFILE as a string, with symbolic links + resolved. + + -- Scheme Procedure: objfile-progspace objfile + Return the '' that this object file lives in. *Note + Progspaces In Guile::, for more on progspaces. + + -- Scheme Procedure: objfile-pretty-printers objfile + Return the list of registered '' objects for + OBJFILE. *Note Guile Pretty Printing API::, for more information. + + -- Scheme Procedure: set-objfile-pretty-printers! objfile printer-list + Set the list of registered '' objects for + OBJFILE to PRINTER-LIST. The PRINTER-LIST must be a list of + '' objects. *Note Guile Pretty Printing API::, + for more information. + + -- Scheme Procedure: current-objfile + When auto-loading a Guile script (*note Guile Auto-loading::), GDB + sets the "current objfile" to the corresponding objfile. This + function returns the current objfile. If there is no current + objfile, this function returns '#f'. + + -- Scheme Procedure: objfiles + Return a list of all the objfiles in the current program space. + + +File: gdb.info, Node: Frames In Guile, Next: Blocks In Guile, Prev: Objfiles In Guile, Up: Guile API + +23.4.3.15 Accessing inferior stack frames from Guile. +..................................................... + +When the debugged program stops, GDB is able to analyze its call stack +(*note Stack frames: Frames.). The '' class represents a +frame in the stack. A '' object is only valid while its +corresponding frame exists in the inferior's stack. If you try to use +an invalid frame object, GDB will throw a 'gdb:invalid-object' exception +(*note Guile Exception Handling::). + + Two '' objects can be compared for equality with the +'equal?' function, like: + + (gdb) guile (equal? (newest-frame) (selected-frame)) + #t + + The following frame-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: frame? object + Return '#t' if OBJECT is a '' object. Otherwise return + '#f'. + + -- Scheme Procedure: frame-valid? frame + Returns '#t' if FRAME is valid, '#f' if not. A frame object can + become invalid if the frame it refers to doesn't exist anymore in + the inferior. All '' procedures will throw an exception + if the frame is invalid at the time the procedure is called. + + -- Scheme Procedure: frame-name frame + Return the function name of FRAME, or '#f' if it can't be obtained. + + -- Scheme Procedure: frame-arch frame + Return the '' object corresponding to FRAME's + architecture. *Note Architectures In Guile::. + + -- Scheme Procedure: frame-type frame + Return the type of FRAME. The value can be one of: + + 'NORMAL_FRAME' + An ordinary stack frame. + + 'DUMMY_FRAME' + A fake stack frame that was created by GDB when performing an + inferior function call. + + 'INLINE_FRAME' + A frame representing an inlined function. The function was + inlined into a 'NORMAL_FRAME' that is older than this one. + + 'TAILCALL_FRAME' + A frame representing a tail call. *Note Tail Call Frames::. + + 'SIGTRAMP_FRAME' + A signal trampoline frame. This is the frame created by the + OS when it calls into a signal handler. + + 'ARCH_FRAME' + A fake stack frame representing a cross-architecture call. + + 'SENTINEL_FRAME' + This is like 'NORMAL_FRAME', but it is only used for the + newest frame. + + -- Scheme Procedure: frame-unwind-stop-reason frame + Return an integer representing the reason why it's not possible to + find more frames toward the outermost frame. Use + 'unwind-stop-reason-string' to convert the value returned by this + function to a string. The value can be one of: + + 'FRAME_UNWIND_NO_REASON' + No particular reason (older frames should be available). + + 'FRAME_UNWIND_NULL_ID' + The previous frame's analyzer returns an invalid result. + + 'FRAME_UNWIND_OUTERMOST' + This frame is the outermost. + + 'FRAME_UNWIND_UNAVAILABLE' + Cannot unwind further, because that would require knowing the + values of registers or memory that have not been collected. + + 'FRAME_UNWIND_INNER_ID' + This frame ID looks like it ought to belong to a NEXT frame, + but we got it for a PREV frame. Normally, this is a sign of + unwinder failure. It could also indicate stack corruption. + + 'FRAME_UNWIND_SAME_ID' + This frame has the same ID as the previous one. That means + that unwinding further would almost certainly give us another + frame with exactly the same ID, so break the chain. Normally, + this is a sign of unwinder failure. It could also indicate + stack corruption. + + 'FRAME_UNWIND_NO_SAVED_PC' + The frame unwinder did not find any saved PC, but we needed + one to unwind further. + + 'FRAME_UNWIND_MEMORY_ERROR' + The frame unwinder caused an error while trying to access + memory. + + 'FRAME_UNWIND_FIRST_ERROR' + Any stop reason greater or equal to this value indicates some + kind of error. This special value facilitates writing code + that tests for errors in unwinding in a way that will work + correctly even if the list of the other values is modified in + future GDB versions. Using it, you could write: + + (define reason (frame-unwind-stop-readon (selected-frame))) + (define reason-str (unwind-stop-reason-string reason)) + (if (>= reason FRAME_UNWIND_FIRST_ERROR) + (format #t "An error occurred: ~s\n" reason-str)) + + -- Scheme Procedure: frame-pc frame + Return the frame's resume address. + + -- Scheme Procedure: frame-block frame + Return the frame's code block as a '' object. *Note + Blocks In Guile::. + + -- Scheme Procedure: frame-function frame + Return the symbol for the function corresponding to this frame as a + '' object, or '#f' if there isn't one. *Note Symbols + In Guile::. + + -- Scheme Procedure: frame-older frame + Return the frame that called FRAME. + + -- Scheme Procedure: frame-newer frame + Return the frame called by FRAME. + + -- Scheme Procedure: frame-sal frame + Return the frame's '' (symtab and line) object. *Note + Symbol Tables In Guile::. + + -- Scheme Procedure: frame-read-register frame register + Return the value of REGISTER in FRAME. REGISTER should be a + string, like 'pc'. + + -- Scheme Procedure: frame-read-var frame variable [#:block block] + Return the value of VARIABLE in FRAME. If the optional argument + BLOCK is provided, search for the variable from that block; + otherwise start at the frame's current block (which is determined + by the frame's current program counter). The VARIABLE must be + given as a string or a '' object, and BLOCK must be a + '' object. + + -- Scheme Procedure: frame-select frame + Set FRAME to be the selected frame. *Note Examining the Stack: + Stack. + + -- Scheme Procedure: selected-frame + Return the selected frame object. *Note Selecting a Frame: + Selection. + + -- Scheme Procedure: newest-frame + Return the newest frame object for the selected thread. + + -- Scheme Procedure: unwind-stop-reason-string reason + Return a string explaining the reason why GDB stopped unwinding + frames, as expressed by the given REASON code (an integer, see the + 'frame-unwind-stop-reason' procedure above in this section). + + +File: gdb.info, Node: Blocks In Guile, Next: Symbols In Guile, Prev: Frames In Guile, Up: Guile API + +23.4.3.16 Accessing blocks from Guile. +...................................... + +In GDB, symbols are stored in blocks. A block corresponds roughly to a +scope in the source code. Blocks are organized hierarchically, and are +represented individually in Guile as an object of type ''. +Blocks rely on debugging information being available. + + A frame has a block. Please see *note Frames In Guile::, for a more +in-depth discussion of frames. + + The outermost block is known as the "global block". The global block +typically holds public global variables and functions. + + The block nested just inside the global block is the "static block". +The static block typically holds file-scoped variables and functions. + + GDB provides a method to get a block's superblock, but there is +currently no way to examine the sub-blocks of a block, or to iterate +over all the blocks in a symbol table (*note Symbol Tables In Guile::). + + Here is a short example that should help explain blocks: + + /* This is in the global block. */ + int global; + + /* This is in the static block. */ + static int file_scope; + + /* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ + int function (int argument) + { + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + { + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + } + } + + The following block-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: block? object + Return '#t' if OBJECT is a '' object. Otherwise return + '#f'. + + -- Scheme Procedure: block-valid? block + Returns '#t' if '' BLOCK is valid, '#f' if not. A block + object can become invalid if the block it refers to doesn't exist + anymore in the inferior. All other '' methods will + throw an exception if it is invalid at the time the procedure is + called. The block's validity is also checked during iteration over + symbols of the block. + + -- Scheme Procedure: block-start block + Return the start address of '' BLOCK. + + -- Scheme Procedure: block-end block + Return the end address of '' BLOCK. + + -- Scheme Procedure: block-function block + Return the name of '' BLOCK represented as a + '' object. If the block is not named, then '#f' is + returned. + + For ordinary function blocks, the superblock is the static block. + However, you should note that it is possible for a function block + to have a superblock that is not the static block - for instance + this happens for an inlined function. + + -- Scheme Procedure: block-superblock block + Return the block containing '' BLOCK. If the parent + block does not exist, then '#f' is returned. + + -- Scheme Procedure: block-global-block block + Return the global block associated with '' BLOCK. + + -- Scheme Procedure: block-static-block block + Return the static block associated with '' BLOCK. + + -- Scheme Procedure: block-global? block + Return '#t' if '' BLOCK is a global block. Otherwise + return '#f'. + + -- Scheme Procedure: block-static? block + Return '#t' if '' BLOCK is a static block. Otherwise + return '#f'. + + -- Scheme Procedure: block-symbols + Return a list of all symbols (as objects) in + '' BLOCK. + + -- Scheme Procedure: make-block-symbols-iterator block + Return an object of type '' that will iterate over + all symbols of the block. Guile programs should not assume that a + specific block object will always contain a given symbol, since + changes in GDB features and infrastructure may cause symbols move + across blocks in a symbol table. *Note Iterators In Guile::. + + -- Scheme Procedure: block-symbols-progress? + Return #t if the object is a object. + This object would be obtained from the 'progress' element of the + '' object returned by 'make-block-symbols-iterator'. + + -- Scheme Procedure: lookup-block pc + Return the innermost '' containing the given PC value. + If the block cannot be found for the PC value specified, the + function will return '#f'. + + +File: gdb.info, Node: Symbols In Guile, Next: Symbol Tables In Guile, Prev: Blocks In Guile, Up: Guile API + +23.4.3.17 Guile representation of Symbols. +.......................................... + +GDB represents every variable, function and type as an entry in a symbol +table. *Note Examining the Symbol Table: Symbols. Guile represents +these symbols in GDB with the '' object. + + The following symbol-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: symbol? object + Return '#t' if OBJECT is an object of type ''. + Otherwise return '#f'. + + -- Scheme Procedure: symbol-valid? symbol + Return '#t' if the '' object is valid, '#f' if not. A + '' object can become invalid if the symbol it refers to + does not exist in GDB any longer. All other '' + procedures will throw an exception if it is invalid at the time the + procedure is called. + + -- Scheme Procedure: symbol-type symbol + Return the type of SYMBOL or '#f' if no type is recorded. The + result is an object of type ''. *Note Types In Guile::. + + -- Scheme Procedure: symbol-symtab symbol + Return the symbol table in which SYMBOL appears. The result is an + object of type ''. *Note Symbol Tables In Guile::. + + -- Scheme Procedure: symbol-line symbol + Return the line number in the source code at which SYMBOL was + defined. This is an integer. + + -- Scheme Procedure: symbol-name symbol + Return the name of SYMBOL as a string. + + -- Scheme Procedure: symbol-linkage-name symbol + Return the name of SYMBOL, as used by the linker (i.e., may be + mangled). + + -- Scheme Procedure: symbol-print-name symbol + Return the name of SYMBOL in a form suitable for output. This is + either 'name' or 'linkage_name', depending on whether the user + asked GDB to display demangled or mangled names. + + -- Scheme Procedure: symbol-addr-class symbol + Return the address class of the symbol. This classifies how to + find the value of a symbol. Each address class is a constant + defined in the '(gdb)' module and described later in this chapter. + + -- Scheme Procedure: symbol-needs-frame? symbol + Return '#t' if evaluating SYMBOL's value requires a frame (*note + Frames In Guile::) and '#f' otherwise. Typically, local variables + will require a frame, but other symbols will not. + + -- Scheme Procedure: symbol-argument? symbol + Return '#t' if SYMBOL is an argument of a function. Otherwise + return '#f'. + + -- Scheme Procedure: symbol-constant? symbol + Return '#t' if SYMBOL is a constant. Otherwise return '#f'. + + -- Scheme Procedure: symbol-function? symbol + Return '#t' if SYMBOL is a function or a method. Otherwise return + '#f'. + + -- Scheme Procedure: symbol-variable? symbol + Return '#t' if SYMBOL is a variable. Otherwise return '#f'. + + -- Scheme Procedure: symbol-value symbol [#:frame frame] + Compute the value of SYMBOL, as a ''. For functions, + this computes the address of the function, cast to the appropriate + type. If the symbol requires a frame in order to compute its + value, then FRAME must be given. If FRAME is not given, or if + FRAME is invalid, then an exception is thrown. + + -- Scheme Procedure: lookup-symbol name [#:block block] + [#:domain domain] + This function searches for a symbol by name. The search scope can + be restricted to the parameters defined in the optional domain and + block arguments. + + NAME is the name of the symbol. It must be a string. The optional + BLOCK argument restricts the search to symbols visible in that + BLOCK. The BLOCK argument must be a '' object. If + omitted, the block for the current frame is used. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the '(gdb)' + module and described later in this chapter. + + The result is a list of two elements. The first element is a + '' object or '#f' if the symbol is not found. If the + symbol is found, the second element is '#t' if the symbol is a + field of a method's object (e.g., 'this' in C++), otherwise it is + '#f'. If the symbol is not found, the second element is '#f'. + + -- Scheme Procedure: lookup-global-symbol name [#:domain domain] + This function searches for a global symbol by name. The search + scope can be restricted by the domain argument. + + NAME is the name of the symbol. It must be a string. The optional + DOMAIN argument restricts the search to the domain type. The + DOMAIN argument must be a domain constant defined in the '(gdb)' + module and described later in this chapter. + + The result is a '' object or '#f' if the symbol is not + found. + + The available domain categories in '' are represented as +constants in the '(gdb)' module: + +'SYMBOL_UNDEF_DOMAIN' + This is used when a domain has not been discovered or none of the + following domains apply. This usually indicates an error either in + the symbol information or in GDB's handling of symbols. + +'SYMBOL_VAR_DOMAIN' + This domain contains variables, function names, typedef names and + enum type values. + +'SYMBOL_FUNCTION_DOMAIN' + This domain contains functions. + +'SYMBOL_TYPE_DOMAIN' + This domain contains types. In a C-like language, types using a + tag (the name appearing after a 'struct', 'union', or 'enum' + keyword) will not appear here; in other languages, all types are in + this domain. + +'SYMBOL_STRUCT_DOMAIN' + This domain holds struct, union and enum tag names. This domain is + only used for C-like languages. For example, in this code: + struct type_one { int x; }; + typedef struct type_one type_two; + Here 'type_one' will be in 'SYMBOL_STRUCT_DOMAIN', but 'type_two' + will be in 'SYMBOL_TYPE_DOMAIN'. + +'SYMBOL_LABEL_DOMAIN' + This domain contains names of labels (for gotos). + +'SYMBOL_VARIABLES_DOMAIN' + This domain holds a subset of the 'SYMBOLS_VAR_DOMAIN'; it contains + everything minus functions and types. + +'SYMBOL_FUNCTIONS_DOMAIN' + This domain contains all functions. + +'SYMBOL_TYPES_DOMAIN' + This domain contains all types. + + The available address class categories in '' are +represented as constants in the 'gdb' module: + + When searching for a symbol, the desired domain constant can be +passed verbatim to the lookup function. + + For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the 'SEARCH' +prefix replacing the 'SYMBOL' prefix; for example, +'SEARCH_LABEL_DOMAIN'. These may be or'd together to form a search +constant. + +'SYMBOL_LOC_UNDEF' + If this is returned by address class, it indicates an error either + in the symbol information or in GDB's handling of symbols. + +'SYMBOL_LOC_CONST' + Value is constant int. + +'SYMBOL_LOC_STATIC' + Value is at a fixed address. + +'SYMBOL_LOC_REGISTER' + Value is in a register. + +'SYMBOL_LOC_ARG' + Value is an argument. This value is at the offset stored within + the symbol inside the frame's argument list. + +'SYMBOL_LOC_REF_ARG' + Value address is stored in the frame's argument list. Just like + 'LOC_ARG' except that the value's address is stored at the offset, + not the value itself. + +'SYMBOL_LOC_REGPARM_ADDR' + Value is a specified register. Just like 'LOC_REGISTER' except the + register holds the address of the argument instead of the argument + itself. + +'SYMBOL_LOC_LOCAL' + Value is a local variable. + +'SYMBOL_LOC_TYPEDEF' + Value not used. Symbols in the domain 'SYMBOL_STRUCT_DOMAIN' all + have this class. + +'SYMBOL_LOC_BLOCK' + Value is a block. + +'SYMBOL_LOC_CONST_BYTES' + Value is a byte-sequence. + +'SYMBOL_LOC_UNRESOLVED' + Value is at a fixed address, but the address of the variable has to + be determined from the minimal symbol table whenever the variable + is referenced. + +'SYMBOL_LOC_OPTIMIZED_OUT' + The value does not actually exist in the program. + +'SYMBOL_LOC_COMPUTED' + The value's address is a computed location. + diff -pruN 16.3-5/gdb/doc/gdb.info-6 16.3-5ubuntu1/gdb/doc/gdb.info-6 --- 16.3-5/gdb/doc/gdb.info-6 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-6 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,8663 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Symbol Tables In Guile, Next: Breakpoints In Guile, Prev: Symbols In Guile, Up: Guile API + +23.4.3.18 Symbol table representation in Guile. +............................................... + +Access to symbol table data maintained by GDB on the inferior is exposed +to Guile via two objects: '' (symtab-and-line) and +''. Symbol table and line data for a frame is returned from +the 'frame-find-sal' '' procedure. *Note Frames In Guile::. + + For more information on GDB's symbol table management, see *note +Examining the Symbol Table: Symbols. + + The following symtab-related procedures are provided by the '(gdb)' +module: + + -- Scheme Procedure: symtab? object + Return '#t' if OBJECT is an object of type ''. + Otherwise return '#f'. + + -- Scheme Procedure: symtab-valid? symtab + Return '#t' if the '' object is valid, '#f' if not. A + '' object becomes invalid when the symbol table it + refers to no longer exists in GDB. All other '' + procedures will throw an exception if it is invalid at the time the + procedure is called. + + -- Scheme Procedure: symtab-filename symtab + Return the symbol table's source filename. + + -- Scheme Procedure: symtab-fullname symtab + Return the symbol table's source absolute file name. + + -- Scheme Procedure: symtab-objfile symtab + Return the symbol table's backing object file. *Note Objfiles In + Guile::. + + -- Scheme Procedure: symtab-global-block symtab + Return the global block of the underlying symbol table. *Note + Blocks In Guile::. + + -- Scheme Procedure: symtab-static-block symtab + Return the static block of the underlying symbol table. *Note + Blocks In Guile::. + + The following symtab-and-line-related procedures are provided by the +'(gdb)' module: + + -- Scheme Procedure: sal? object + Return '#t' if OBJECT is an object of type ''. Otherwise + return '#f'. + + -- Scheme Procedure: sal-valid? sal + Return '#t' if SAL is valid, '#f' if not. A '' object + becomes invalid when the Symbol table object it refers to no longer + exists in GDB. All other '' procedures will throw an + exception if it is invalid at the time the procedure is called. + + -- Scheme Procedure: sal-symtab sal + Return the symbol table object ('') for SAL. + + -- Scheme Procedure: sal-line sal + Return the line number for SAL. + + -- Scheme Procedure: sal-pc sal + Return the start of the address range occupied by code for SAL. + + -- Scheme Procedure: sal-last sal + Return the end of the address range occupied by code for SAL. + + -- Scheme Procedure: find-pc-line pc + Return the '' object corresponding to the PC value. If an + invalid value of PC is passed as an argument, then the 'symtab' and + 'line' attributes of the returned '' object will be '#f' + and 0 respectively. + + +File: gdb.info, Node: Breakpoints In Guile, Next: Lazy Strings In Guile, Prev: Symbol Tables In Guile, Up: Guile API + +23.4.3.19 Manipulating breakpoints using Guile +.............................................. + +Breakpoints in Guile are represented by objects of type +''. New breakpoints can be created with the +'make-breakpoint' Guile function, and then added to GDB with the +'register-breakpoint!' Guile function. This two-step approach is taken +to separate out the side-effect of adding the breakpoint to GDB from +'make-breakpoint'. + + Support is also provided to view and manipulate breakpoints created +outside of Guile. + + The following breakpoint-related procedures are provided by the +'(gdb)' module: + + -- Scheme Procedure: make-breakpoint location [#:type type] + [#:wp-class wp-class] [#:internal internal] + [#:temporary temporary] + Create a new breakpoint at LOCATION, a string naming the location + of the breakpoint, or an expression that defines a watchpoint. The + contents can be any location recognized by the 'break' command, or + in the case of a watchpoint, by the 'watch' command. + + The breakpoint is initially marked as 'invalid'. The breakpoint is + not usable until it has been registered with GDB with + 'register-breakpoint!', at which point it becomes 'valid'. The + result is the '' object representing the + breakpoint. + + The optional TYPE denotes the breakpoint to create. This argument + can be either 'BP_BREAKPOINT' or 'BP_WATCHPOINT', and defaults to + 'BP_BREAKPOINT'. + + The optional WP-CLASS argument defines the class of watchpoint to + create, if TYPE is 'BP_WATCHPOINT'. If a watchpoint class is not + provided, it is assumed to be a 'WP_WRITE' class. + + The optional INTERNAL argument allows the breakpoint to become + invisible to the user. The breakpoint will neither be reported + when registered, nor will it be listed in the output from 'info + breakpoints' (but will be listed with the 'maint info breakpoints' + command). If an internal flag is not provided, the breakpoint is + visible (non-internal). + + The optional TEMPORARY argument makes the breakpoint a temporary + breakpoint. Temporary breakpoints are deleted after they have been + hit, after which the Guile breakpoint is no longer usable (although + it may be re-registered with 'register-breakpoint!'). + + When a watchpoint is created, GDB will try to create a hardware + assisted watchpoint. If successful, the type of the watchpoint is + changed from 'BP_WATCHPOINT' to 'BP_HARDWARE_WATCHPOINT' for + 'WP_WRITE', 'BP_READ_WATCHPOINT' for 'WP_READ', and + 'BP_ACCESS_WATCHPOINT' for 'WP_ACCESS'. If not successful, the + type of the watchpoint is left as 'WP_WATCHPOINT'. + + The available types are represented by constants defined in the + 'gdb' module: + + 'BP_BREAKPOINT' + Normal code breakpoint. + + 'BP_WATCHPOINT' + Watchpoint breakpoint. + + 'BP_HARDWARE_WATCHPOINT' + Hardware assisted watchpoint. This value cannot be specified + when creating the breakpoint. + + 'BP_READ_WATCHPOINT' + Hardware assisted read watchpoint. This value cannot be + specified when creating the breakpoint. + + 'BP_ACCESS_WATCHPOINT' + Hardware assisted access watchpoint. This value cannot be + specified when creating the breakpoint. + + 'BP_CATCHPOINT' + Catchpoint. This value cannot be specified when creating the + breakpoint. + + The available watchpoint types are represented by constants defined + in the '(gdb)' module: + + 'WP_READ' + Read only watchpoint. + + 'WP_WRITE' + Write only watchpoint. + + 'WP_ACCESS' + Read/Write watchpoint. + + -- Scheme Procedure: register-breakpoint! breakpoint + Add BREAKPOINT, a '' object, to GDB's list of + breakpoints. The breakpoint must have been created with + 'make-breakpoint'. One cannot register breakpoints that have been + created outside of Guile. Once a breakpoint is registered it + becomes 'valid'. It is an error to register an already registered + breakpoint. The result is unspecified. + + -- Scheme Procedure: delete-breakpoint! breakpoint + Remove BREAKPOINT from GDB's list of breakpoints. This also + invalidates the Guile BREAKPOINT object. Any further attempt to + access the object will throw an exception. + + If BREAKPOINT was created from Guile with 'make-breakpoint' it may + be re-registered with GDB, in which case the breakpoint becomes + valid again. + + -- Scheme Procedure: breakpoints + Return a list of all breakpoints. Each element of the list is a + '' object. + + -- Scheme Procedure: breakpoint? object + Return '#t' if OBJECT is a '' object, and '#f' + otherwise. + + -- Scheme Procedure: breakpoint-valid? breakpoint + Return '#t' if BREAKPOINT is valid, '#f' otherwise. Breakpoints + created with 'make-breakpoint' are marked as invalid until they are + registered with GDB with 'register-breakpoint!'. A + '' object can become invalid if the user deletes + the breakpoint. In this case, the object still exists, but the + underlying breakpoint does not. In the cases of watchpoint scope, + the watchpoint remains valid even if execution of the inferior + leaves the scope of that watchpoint. + + -- Scheme Procedure: breakpoint-number breakpoint + Return the breakpoint's number -- the identifier used by the user + to manipulate the breakpoint. + + -- Scheme Procedure: breakpoint-temporary? breakpoint + Return '#t' if the breakpoint was created as a temporary + breakpoint. Temporary breakpoints are automatically deleted after + they've been hit. Calling this procedure, and all other procedures + other than 'breakpoint-valid?' and 'register-breakpoint!', will + result in an error after the breakpoint has been hit (since it has + been automatically deleted). + + -- Scheme Procedure: breakpoint-type breakpoint + Return the breakpoint's type -- the identifier used to determine + the actual breakpoint type or use-case. + + -- Scheme Procedure: breakpoint-visible? breakpoint + Return '#t' if the breakpoint is visible to the user when hit, or + when the 'info breakpoints' command is run. Otherwise return '#f'. + + -- Scheme Procedure: breakpoint-location breakpoint + Return the location of the breakpoint, as specified by the user. + It is a string. If the breakpoint does not have a location (that + is, it is a watchpoint) return '#f'. + + -- Scheme Procedure: breakpoint-expression breakpoint + Return the breakpoint expression, as specified by the user. It is + a string. If the breakpoint does not have an expression (the + breakpoint is not a watchpoint) return '#f'. + + -- Scheme Procedure: breakpoint-enabled? breakpoint + Return '#t' if the breakpoint is enabled, and '#f' otherwise. + + -- Scheme Procedure: set-breakpoint-enabled! breakpoint flag + Set the enabled state of BREAKPOINT to FLAG. If flag is '#f' it is + disabled, otherwise it is enabled. + + -- Scheme Procedure: breakpoint-silent? breakpoint + Return '#t' if the breakpoint is silent, and '#f' otherwise. + + Note that a breakpoint can also be silent if it has commands and + the first command is 'silent'. This is not reported by the + 'silent' attribute. + + -- Scheme Procedure: set-breakpoint-silent! breakpoint flag + Set the silent state of BREAKPOINT to FLAG. If flag is '#f' the + breakpoint is made silent, otherwise it is made non-silent (or + noisy). + + -- Scheme Procedure: breakpoint-ignore-count breakpoint + Return the ignore count for BREAKPOINT. + + -- Scheme Procedure: set-breakpoint-ignore-count! breakpoint count + Set the ignore count for BREAKPOINT to COUNT. + + -- Scheme Procedure: breakpoint-hit-count breakpoint + Return hit count of BREAKPOINT. + + -- Scheme Procedure: set-breakpoint-hit-count! breakpoint count + Set the hit count of BREAKPOINT to COUNT. At present, COUNT must + be zero. + + -- Scheme Procedure: breakpoint-thread breakpoint + Return the global-thread-id for thread-specific breakpoint + BREAKPOINT. Return #f if BREAKPOINT is not thread-specific. + + -- Scheme Procedure: set-breakpoint-thread! breakpoint + global-thread-id|#f + Set the thread-id for BREAKPOINT to GLOBAL-THREAD-ID If set to + '#f', the breakpoint is no longer thread-specific. + + -- Scheme Procedure: breakpoint-task breakpoint + If the breakpoint is Ada task-specific, return the Ada task id. If + the breakpoint is not task-specific (or the underlying language is + not Ada), return '#f'. + + -- Scheme Procedure: set-breakpoint-task! breakpoint task + Set the Ada task of BREAKPOINT to TASK. If set to '#f', the + breakpoint is no longer task-specific. + + -- Scheme Procedure: breakpoint-condition breakpoint + Return the condition of BREAKPOINT, as specified by the user. It + is a string. If there is no condition, return '#f'. + + -- Scheme Procedure: set-breakpoint-condition! breakpoint condition + Set the condition of BREAKPOINT to CONDITION, which must be a + string. If set to '#f' then the breakpoint becomes unconditional. + + -- Scheme Procedure: breakpoint-stop breakpoint + Return the stop predicate of BREAKPOINT. See + 'set-breakpoint-stop!' below in this section. + + -- Scheme Procedure: set-breakpoint-stop! breakpoint procedure|#f + Set the stop predicate of BREAKPOINT. The predicate PROCEDURE + takes one argument: the object. If this predicate + is set to a procedure then it is invoked whenever the inferior + reaches this breakpoint. If it returns '#t', or any non-'#f' + value, then the inferior is stopped, otherwise the inferior will + continue. + + If there are multiple breakpoints at the same location with a + 'stop' predicate, each one will be called regardless of the return + status of the previous. This ensures that all 'stop' predicates + have a chance to execute at that location. In this scenario if one + of the methods returns '#t' but the others return '#f', the + inferior will still be stopped. + + You should not alter the execution state of the inferior (i.e., + step, next, etc.), alter the current frame context (i.e., change + the current active frame), or alter, add or delete any breakpoint. + As a general rule, you should not alter any data within GDB or the + inferior at this time. + + Example 'stop' implementation: + + (define (my-stop? bkpt) + (let ((int-val (parse-and-eval "foo"))) + (value=? int-val 3))) + (define bkpt (make-breakpoint "main.c:42")) + (register-breakpoint! bkpt) + (set-breakpoint-stop! bkpt my-stop?) + + -- Scheme Procedure: breakpoint-commands breakpoint + Return the commands attached to BREAKPOINT as a string, or '#f' if + there are none. + + +File: gdb.info, Node: Lazy Strings In Guile, Next: Architectures In Guile, Prev: Breakpoints In Guile, Up: Guile API + +23.4.3.20 Guile representation of lazy strings. +............................................... + +A "lazy string" is a string whose contents is not retrieved or encoded +until it is needed. + + A '' is represented in GDB as an 'address' that +points to a region of memory, an 'encoding' that will be used to encode +that region of memory, and a 'length' to delimit the region of memory +that represents the string. The difference between a +'' and a string wrapped within a '' is that +a '' will be treated differently by GDB when printing. +A '' is retrieved and encoded during printing, while a +'' wrapping a string is immediately retrieved and encoded on +creation. + + The following lazy-string-related procedures are provided by the +'(gdb)' module: + + -- Scheme Procedure: lazy-string? object + Return '#t' if OBJECT is an object of type ''. + Otherwise return '#f'. + + -- Scheme Procedure: lazy-string-address lazy-sring + Return the address of LAZY-STRING. + + -- Scheme Procedure: lazy-string-length lazy-string + Return the length of LAZY-STRING in characters. If the length is + -1, then the string will be fetched and encoded up to the first + null of appropriate width. + + -- Scheme Procedure: lazy-string-encoding lazy-string + Return the encoding that will be applied to LAZY-STRING when the + string is printed by GDB. If the encoding is not set, or contains + an empty string, then GDB will select the most appropriate encoding + when the string is printed. + + -- Scheme Procedure: lazy-string-type lazy-string + Return the type that is represented by LAZY-STRING's type. For a + lazy string this is a pointer or array type. To resolve this to + the lazy string's character type, use 'type-target-type'. *Note + Types In Guile::. + + -- Scheme Procedure: lazy-string->value lazy-string + Convert the '' to a ''. This value + will point to the string in memory, but will lose all the delayed + retrieval, encoding and handling that GDB applies to a + ''. + + +File: gdb.info, Node: Architectures In Guile, Next: Disassembly In Guile, Prev: Lazy Strings In Guile, Up: Guile API + +23.4.3.21 Guile representation of architectures +............................................... + +GDB uses architecture specific parameters and artifacts in a number of +its various computations. An architecture is represented by an instance +of the '' class. + + The following architecture-related procedures are provided by the +'(gdb)' module: + + -- Scheme Procedure: arch? object + Return '#t' if OBJECT is an object of type ''. Otherwise + return '#f'. + + -- Scheme Procedure: current-arch + Return the current architecture as a '' object. + + -- Scheme Procedure: arch-name arch + Return the name (string value) of '' ARCH. + + -- Scheme Procedure: arch-charset arch + Return name of target character set of '' ARCH. + + -- Scheme Procedure: arch-wide-charset + Return name of target wide character set of '' ARCH. + + Each architecture provides a set of predefined types, obtained by the +following functions. + + -- Scheme Procedure: arch-void-type arch + Return the '' object for a 'void' type of architecture + ARCH. + + -- Scheme Procedure: arch-char-type arch + Return the '' object for a 'char' type of architecture + ARCH. + + -- Scheme Procedure: arch-short-type arch + Return the '' object for a 'short' type of architecture + ARCH. + + -- Scheme Procedure: arch-int-type arch + Return the '' object for an 'int' type of architecture + ARCH. + + -- Scheme Procedure: arch-long-type arch + Return the '' object for a 'long' type of architecture + ARCH. + + -- Scheme Procedure: arch-schar-type arch + Return the '' object for a 'signed char' type of + architecture ARCH. + + -- Scheme Procedure: arch-uchar-type arch + Return the '' object for an 'unsigned char' type of + architecture ARCH. + + -- Scheme Procedure: arch-ushort-type arch + Return the '' object for an 'unsigned short' type of + architecture ARCH. + + -- Scheme Procedure: arch-uint-type arch + Return the '' object for an 'unsigned int' type of + architecture ARCH. + + -- Scheme Procedure: arch-ulong-type arch + Return the '' object for an 'unsigned long' type of + architecture ARCH. + + -- Scheme Procedure: arch-float-type arch + Return the '' object for a 'float' type of architecture + ARCH. + + -- Scheme Procedure: arch-double-type arch + Return the '' object for a 'double' type of architecture + ARCH. + + -- Scheme Procedure: arch-longdouble-type arch + Return the '' object for a 'long double' type of + architecture ARCH. + + -- Scheme Procedure: arch-bool-type arch + Return the '' object for a 'bool' type of architecture + ARCH. + + -- Scheme Procedure: arch-longlong-type arch + Return the '' object for a 'long long' type of + architecture ARCH. + + -- Scheme Procedure: arch-ulonglong-type arch + Return the '' object for an 'unsigned long long' type of + architecture ARCH. + + -- Scheme Procedure: arch-int8-type arch + Return the '' object for an 'int8' type of architecture + ARCH. + + -- Scheme Procedure: arch-uint8-type arch + Return the '' object for a 'uint8' type of architecture + ARCH. + + -- Scheme Procedure: arch-int16-type arch + Return the '' object for an 'int16' type of architecture + ARCH. + + -- Scheme Procedure: arch-uint16-type arch + Return the '' object for a 'uint16' type of architecture + ARCH. + + -- Scheme Procedure: arch-int32-type arch + Return the '' object for an 'int32' type of architecture + ARCH. + + -- Scheme Procedure: arch-uint32-type arch + Return the '' object for a 'uint32' type of architecture + ARCH. + + -- Scheme Procedure: arch-int64-type arch + Return the '' object for an 'int64' type of architecture + ARCH. + + -- Scheme Procedure: arch-uint64-type arch + Return the '' object for a 'uint64' type of architecture + ARCH. + + Example: + + (gdb) guile (type-name (arch-uchar-type (current-arch))) + "unsigned char" + + +File: gdb.info, Node: Disassembly In Guile, Next: I/O Ports in Guile, Prev: Architectures In Guile, Up: Guile API + +23.4.3.22 Disassembly In Guile +.............................. + +The disassembler can be invoked from Scheme code. Furthermore, the +disassembler can take a Guile port as input, allowing one to disassemble +from any source, and not just target memory. + + -- Scheme Procedure: arch-disassemble arch start-pc [#:port port] + [#:offset offset] [#:size size] [#:count count] + Return a list of disassembled instructions starting from the memory + address START-PC. + + The optional argument PORT specifies the input port to read bytes + from. If PORT is '#f' then bytes are read from target memory. + + The optional argument OFFSET specifies the address offset of the + first byte in PORT. This is useful, for example, when PORT + specifies a 'bytevector' and you want the bytevector to be + disassembled as if it came from that address. The START-PC passed + to the reader for PORT is offset by the same amount. + + Example: + (gdb) guile (use-modules (rnrs io ports)) + (gdb) guile (define pc (value->integer (parse-and-eval "$pc"))) + (gdb) guile (define mem (open-memory #:start pc)) + (gdb) guile (define bv (get-bytevector-n mem 10)) + (gdb) guile (define bv-port (open-bytevector-input-port bv)) + (gdb) guile (define arch (current-arch)) + (gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc) + (((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5))) + + The optional arguments SIZE and COUNT determine the number of + instructions in the returned list. If either SIZE or COUNT is + specified as zero, then no instructions are disassembled and an + empty list is returned. If both the optional arguments SIZE and + COUNT are specified, then a list of at most COUNT disassembled + instructions whose start address falls in the closed memory address + interval from START-PC to (START-PC + SIZE - 1) are returned. If + SIZE is not specified, but COUNT is specified, then COUNT number of + instructions starting from the address START-PC are returned. If + COUNT is not specified but SIZE is specified, then all instructions + whose start address falls in the closed memory address interval + from START-PC to (START-PC + SIZE - 1) are returned. If neither + SIZE nor COUNT are specified, then a single instruction at START-PC + is returned. + + Each element of the returned list is an alist (associative list) + with the following keys: + + 'address' + The value corresponding to this key is a Guile integer of the + memory address of the instruction. + + 'asm' + The value corresponding to this key is a string value which + represents the instruction with assembly language mnemonics. + The assembly language flavor used is the same as that + specified by the current CLI variable 'disassembly-flavor'. + *Note Machine Code::. + + 'length' + The value corresponding to this key is the length of the + instruction in bytes. + + +File: gdb.info, Node: I/O Ports in Guile, Next: Memory Ports in Guile, Prev: Disassembly In Guile, Up: Guile API + +23.4.3.23 I/O Ports in Guile +............................ + + -- Scheme Procedure: input-port + Return GDB's input port as a Guile port object. + + -- Scheme Procedure: output-port + Return GDB's output port as a Guile port object. + + -- Scheme Procedure: error-port + Return GDB's error port as a Guile port object. + + -- Scheme Procedure: stdio-port? object + Return '#t' if OBJECT is a GDB stdio port. Otherwise return '#f'. + + +File: gdb.info, Node: Memory Ports in Guile, Next: Iterators In Guile, Prev: I/O Ports in Guile, Up: Guile API + +23.4.3.24 Memory Ports in Guile +............................... + +GDB provides a 'port' interface to target memory. This allows Guile +code to read/write target memory using Guile's port and bytevector +functionality. The main routine is 'open-memory' which returns a port +object. One can then read/write memory using that object. + + -- Scheme Procedure: open-memory [#:mode mode] [#:start address] + [#:size size] + Return a port object that can be used for reading and writing + memory. The port will be open according to MODE, which is the + standard mode argument to Guile port open routines, except that the + '"a"' and '"l"' modes are not supported. *Note (guile)File + Ports::. The '"b"' (binary) character may be present, but is + ignored: memory ports are binary only. If '"0"' is appended then + the port is marked as unbuffered. The default is '"r"', read-only + and buffered. + + The chunk of memory that can be accessed can be bounded. If both + START and SIZE are unspecified, all of memory can be accessed. If + only START is specified, all of memory from that point on can be + accessed. If only SIZE if specified, all memory in the range + [0,SIZE) can be accessed. If both are specified, all memory in the + rane [START,START+SIZE) can be accessed. + + -- Scheme Procedure: memory-port? + Return '#t' if OBJECT is an object of type ''. + Otherwise return '#f'. + + -- Scheme Procedure: memory-port-range memory-port + Return the range of '' MEMORY-PORT as a list of + two elements: '(start end)'. The range is START to END inclusive. + + -- Scheme Procedure: memory-port-read-buffer-size memory-port + Return the size of the read buffer of '' + MEMORY-PORT. + + This procedure is deprecated and will be removed in GDB 11. It + returns 0 when using Guile 2.2 or later. + + -- Scheme Procedure: set-memory-port-read-buffer-size! memory-port size + Set the size of the read buffer of '' MEMORY-PORT + to SIZE. The result is unspecified. + + This procedure is deprecated and will be removed in GDB 11. When + GDB is built with Guile 2.2 or later, you can call 'setvbuf' + instead (*note 'setvbuf': (guile)Buffering.). + + -- Scheme Procedure: memory-port-write-buffer-size memory-port + Return the size of the write buffer of '' + MEMORY-PORT. + + This procedure is deprecated and will be removed in GDB 11. It + returns 0 when GDB is built with Guile 2.2 or later. + + -- Scheme Procedure: set-memory-port-write-buffer-size! memory-port + size + Set the size of the write buffer of '' MEMORY-PORT + to SIZE. The result is unspecified. + + This procedure is deprecated and will be removed in GDB 11. When + GDB is built with Guile 2.2 or later, you can call 'setvbuf' + instead. + + A memory port is closed like any other port, with 'close-port'. + + Combined with Guile's 'bytevectors', memory ports provide a lot of +utility. For example, to fill a buffer of 10 integers in memory, one +can do something like the following. + + ;; In the program: int buffer[10]; + (use-modules (rnrs bytevectors)) + (use-modules (rnrs io ports)) + (define addr (parse-and-eval "buffer")) + (define n 10) + (define byte-size (* n 4)) + (define mem-port (open-memory #:mode "r+" #:start + (value->integer addr) #:size byte-size)) + (define byte-vec (make-bytevector byte-size)) + (do ((i 0 (+ i 1))) + ((>= i n)) + (bytevector-s32-native-set! byte-vec (* i 4) (* i 42))) + (put-bytevector mem-port byte-vec) + (close-port mem-port) + + +File: gdb.info, Node: Iterators In Guile, Prev: Memory Ports in Guile, Up: Guile API + +23.4.3.25 Iterators In Guile +............................ + +A simple iterator facility is provided to allow, for example, iterating +over the set of program symbols without having to first construct a list +of all of them. A useful contribution would be to add support for SRFI +41 and SRFI 45. + + -- Scheme Procedure: make-iterator object progress next! + A '' object is constructed with the 'make-iterator' + procedure. It takes three arguments: the object to be iterated + over, an object to record the progress of the iteration, and a + procedure to return the next element in the iteration, or an + implementation chosen value to denote the end of iteration. + + By convention, end of iteration is marked with + '(end-of-iteration)', and may be tested with the + 'end-of-iteration?' predicate. The result of '(end-of-iteration)' + is chosen so that it is not otherwise used by the '(gdb)' module. + If you are using '' in your own code it is your + responsibility to maintain this invariant. + + A trivial example for illustration's sake: + + (use-modules (gdb iterator)) + (define my-list (list 1 2 3)) + (define iter + (make-iterator my-list my-list + (lambda (iter) + (let ((l (iterator-progress iter))) + (if (eq? l '()) + (end-of-iteration) + (begin + (set-iterator-progress! iter (cdr l)) + (car l))))))) + + Here is a slightly more realistic example, which computes a list of + all the functions in 'my-global-block'. + + (use-modules (gdb iterator)) + (define this-sal (find-pc-line (frame-pc (selected-frame)))) + (define this-symtab (sal-symtab this-sal)) + (define this-global-block (symtab-global-block this-symtab)) + (define syms-iter (make-block-symbols-iterator this-global-block)) + (define functions (iterator-filter symbol-function? syms-iter)) + + -- Scheme Procedure: iterator? object + Return '#t' if OBJECT is a '' object. Otherwise + return '#f'. + + -- Scheme Procedure: iterator-object iterator + Return the first argument that was passed to 'make-iterator'. This + is the object being iterated over. + + -- Scheme Procedure: iterator-progress iterator + Return the object tracking iteration progress. + + -- Scheme Procedure: set-iterator-progress! iterator new-value + Set the object tracking iteration progress. + + -- Scheme Procedure: iterator-next! iterator + Invoke the procedure that was the third argument to + 'make-iterator', passing it one argument, the '' + object. The result is either the next element in the iteration, or + an end marker as implemented by the 'next!' procedure. By + convention the end marker is the result of '(end-of-iteration)'. + + -- Scheme Procedure: end-of-iteration + Return the Scheme object that denotes end of iteration. + + -- Scheme Procedure: end-of-iteration? object + Return '#t' if OBJECT is the end of iteration marker. Otherwise + return '#f'. + + These functions are provided by the '(gdb iterator)' module to assist +in using iterators. + + -- Scheme Procedure: make-list-iterator list + Return a '' object that will iterate over LIST. + + -- Scheme Procedure: iterator->list iterator + Return the elements pointed to by ITERATOR as a list. + + -- Scheme Procedure: iterator-map proc iterator + Return the list of objects obtained by applying PROC to the object + pointed to by ITERATOR and to each subsequent object. + + -- Scheme Procedure: iterator-for-each proc iterator + Apply PROC to each element pointed to by ITERATOR. The result is + unspecified. + + -- Scheme Procedure: iterator-filter pred iterator + Return the list of elements pointed to by ITERATOR that satisfy + PRED. + + -- Scheme Procedure: iterator-until pred iterator + Run ITERATOR until the result of '(pred element)' is true and + return that as the result. Otherwise return '#f'. + + +File: gdb.info, Node: Guile Auto-loading, Next: Guile Modules, Prev: Guile API, Up: Guile + +23.4.4 Guile Auto-loading +------------------------- + +When a new object file is read (for example, due to the 'file' command, +or because the inferior has loaded a shared library), GDB will look for +Guile support scripts in two ways: 'OBJFILE-gdb.scm' and the +'.debug_gdb_scripts' section. *Note Auto-loading extensions::. + + The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. + +'set auto-load guile-scripts [on|off]' + Enable or disable the auto-loading of Guile scripts. + +'show auto-load guile-scripts' + Show whether auto-loading of Guile scripts is enabled or disabled. + +'info auto-load guile-scripts [REGEXP]' + Print the list of all Guile scripts that GDB auto-loaded. + + Also printed is the list of Guile scripts that were mentioned in + the '.debug_gdb_scripts' section and were not found. This is + useful because their names are not printed when GDB tries to load + them and fails. There may be many of them, and printing an error + message for each one is problematic. + + If REGEXP is supplied only Guile scripts with matching names are + printed. + + Example: + + (gdb) info auto-load guile-scripts + Loaded Script + Yes scm-section-script.scm + full name: /tmp/scm-section-script.scm + No my-foo-pretty-printers.scm + + When reading an auto-loaded file, GDB sets the "current objfile". +This is available via the 'current-objfile' procedure (*note Objfiles In +Guile::). This can be useful for registering objfile-specific +pretty-printers. + + +File: gdb.info, Node: Guile Modules, Prev: Guile Auto-loading, Up: Guile + +23.4.5 Guile Modules +-------------------- + +GDB comes with several modules to assist writing Guile code. + +* Menu: + +* Guile Printing Module:: Building and registering pretty-printers +* Guile Types Module:: Utilities for working with types + + +File: gdb.info, Node: Guile Printing Module, Next: Guile Types Module, Up: Guile Modules + +23.4.5.1 Guile Printing Module +.............................. + +This module provides a collection of utilities for working with +pretty-printers. + + Usage: + + (use-modules (gdb printing)) + + -- Scheme Procedure: prepend-pretty-printer! object printer + Add PRINTER to the front of the list of pretty-printers for OBJECT. + The OBJECT must either be a '' object, or '#f' in + which case PRINTER is added to the global list of printers. + + -- Scheme Procedure: append-pretty-printer! object printer + Add PRINTER to the end of the list of pretty-printers for OBJECT. + The OBJECT must either be a '' object, or '#f' in + which case PRINTER is added to the global list of printers. + + +File: gdb.info, Node: Guile Types Module, Prev: Guile Printing Module, Up: Guile Modules + +23.4.5.2 Guile Types Module +........................... + +This module provides a collection of utilities for working with +'' objects. + + Usage: + + (use-modules (gdb types)) + + -- Scheme Procedure: get-basic-type type + Return TYPE with const and volatile qualifiers stripped, and with + typedefs and C++ references converted to the underlying type. + + C++ example: + + typedef const int const_int; + const_int foo (3); + const_int& foo_ref (foo); + int main () { return 0; } + + Then in gdb: + + (gdb) start + (gdb) guile (use-modules (gdb) (gdb types)) + (gdb) guile (define foo-ref (parse-and-eval "foo_ref")) + (gdb) guile (get-basic-type (value-type foo-ref)) + # + + -- Scheme Procedure: type-has-field-deep? type field + Return '#t' if TYPE, assumed to be a type with fields (e.g., a + structure or union), has field FIELD. Otherwise return '#f'. This + searches baseclasses, whereas 'type-has-field?' does not. + + -- Scheme Procedure: make-enum-hashtable enum-type + Return a Guile hash table produced from ENUM-TYPE. Elements in the + hash table are referenced with 'hashq-ref'. + + +File: gdb.info, Node: Auto-loading extensions, Next: Multiple Extension Languages, Prev: Guile, Up: Extending GDB + +23.5 Auto-loading extensions +============================ + +GDB provides two mechanisms for automatically loading extensions when a +new object file is read (for example, due to the 'file' command, or +because the inferior has loaded a shared library): 'OBJFILE-gdb.EXT' +(*note The 'OBJFILE-gdb.EXT' file: objfile-gdbdotext file.) and the +'.debug_gdb_scripts' section of modern file formats like ELF (*note The +'.debug_gdb_scripts' section: dotdebug_gdb_scripts section.). For a +discussion of the differences between these two approaches see *note +Which flavor to choose?::. + + The auto-loading feature is useful for supplying application-specific +debugging commands and features. + + Auto-loading can be enabled or disabled, and the list of auto-loaded +scripts can be printed. See the 'auto-loading' section of each +extension language for more information. For GDB command files see +*note Auto-loading sequences::. For Python files see *note Python +Auto-loading::. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + +* Menu: + +* objfile-gdbdotext file:: The 'OBJFILE-gdb.EXT' file +* dotdebug_gdb_scripts section:: The '.debug_gdb_scripts' section +* Which flavor to choose?:: Choosing between these approaches + + +File: gdb.info, Node: objfile-gdbdotext file, Next: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.5.1 The 'OBJFILE-gdb.EXT' file +--------------------------------- + +When a new object file is read, GDB looks for a file named +'OBJFILE-gdb.EXT' (we call it SCRIPT-NAME below), where OBJFILE is the +object file's name and where EXT is the file extension for the extension +language: + +'OBJFILE-gdb.gdb' + GDB's own command language +'OBJFILE-gdb.py' + Python +'OBJFILE-gdb.scm' + Guile + + SCRIPT-NAME is formed by ensuring that the file name of OBJFILE is +absolute, following all symlinks, and resolving '.' and '..' components, +and appending the '-gdb.EXT' suffix. If this file exists and is +readable, GDB will evaluate it as a script in the specified extension +language. + + If this file does not exist, then GDB will look for SCRIPT-NAME file +in all of the directories as specified below. (On MS-Windows/MS-DOS, +the drive letter of the executable's leading directories is converted to +a one-letter subdirectory, i.e. 'd:/usr/bin/' is converted to +'/d/usr/bin/', because Windows filesystems disallow colons in file +names.) + + Note that loading of these files requires an accordingly configured +'auto-load safe-path' (*note Auto-loading safe path::). + + For object files using '.exe' suffix GDB tries to load first the +scripts normally according to its '.exe' filename. But if no scripts +are found GDB also tries script filenames matching the object file +without its '.exe' suffix. This '.exe' stripping is case insensitive +and it is attempted on any platform. This makes the script filenames +compatible between Unix and MS-Windows hosts. + +'set auto-load scripts-directory [DIRECTORIES]' + Control GDB auto-loaded scripts location. Multiple directory + entries may be delimited by the host platform path separator in use + (':' on Unix, ';' on MS-Windows and MS-DOS). + + Each entry here needs to be covered also by the security setting + 'set auto-load safe-path' (*note set auto-load safe-path::). + + This variable defaults to '$debugdir:$datadir/auto-load'. The + default 'set auto-load safe-path' value can be also overridden by + GDB configuration option '--with-auto-load-dir'. + + Any reference to '$debugdir' will get replaced by + DEBUG-FILE-DIRECTORY value (*note Separate Debug Files::) and any + reference to '$datadir' will get replaced by DATA-DIRECTORY which + is determined at GDB startup (*note Data Files::). '$debugdir' and + '$datadir' must be placed as a directory component -- either alone + or delimited by '/' or '\' directory separators, depending on the + host platform. + + The list of directories uses path separator (':' on GNU and Unix + systems, ';' on MS-Windows and MS-DOS) to separate directories, + similarly to the 'PATH' environment variable. + +'show auto-load scripts-directory' + Show GDB auto-loaded scripts location. + +'add-auto-load-scripts-directory [DIRECTORIES...]' + Add an entry (or list of entries) to the list of auto-loaded + scripts locations. Multiple entries may be delimited by the host + platform path separator in use. + + GDB does not track which files it has already auto-loaded this way. +GDB will load the associated script every time the corresponding OBJFILE +is opened. So your '-gdb.EXT' file should be careful to avoid errors if +it is evaluated more than once. + + +File: gdb.info, Node: dotdebug_gdb_scripts section, Next: Which flavor to choose?, Prev: objfile-gdbdotext file, Up: Auto-loading extensions + +23.5.2 The '.debug_gdb_scripts' section +--------------------------------------- + +For systems using file formats like ELF and COFF, when GDB loads a new +object file it will look for a special section named +'.debug_gdb_scripts'. If this section exists, its contents is a list of +null-terminated entries specifying scripts to load. Each entry begins +with a non-null prefix byte that specifies the kind of entry, typically +the extension language and whether the script is in a file or inlined in +'.debug_gdb_scripts'. + + The following entries are supported: + +'SECTION_SCRIPT_ID_PYTHON_FILE = 1' +'SECTION_SCRIPT_ID_SCHEME_FILE = 3' +'SECTION_SCRIPT_ID_PYTHON_TEXT = 4' +'SECTION_SCRIPT_ID_SCHEME_TEXT = 6' + +23.5.2.1 Script File Entries +............................ + +If the entry specifies a file, GDB will look for the file first in the +current directory and then along the source search path (*note +Specifying Source Directories: Source Path.), except that '$cdir' is not +searched, since the compilation directory is not relevant to scripts. + + File entries can be placed in section '.debug_gdb_scripts' with, for +example, this GCC macro for Python scripts. + + /* Note: The "MS" section flags are to remove duplicates. */ + #define DEFINE_GDB_PY_SCRIPT(script_name) \ + asm("\ + .pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n\ + .byte 1 /* Python */\n\ + .asciz \"" script_name "\"\n\ + .popsection \n\ + "); + +For Guile scripts, replace '.byte 1' with '.byte 3'. Then one can +reference the macro in a header or source file like this: + + DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") + + The script name may include directories if desired. + + Note that loading of this script file also requires accordingly +configured 'auto-load safe-path' (*note Auto-loading safe path::). + + If the macro invocation is put in a header, any application or +library using this header will get a reference to the specified script, +and with the use of '"MS"' attributes on the section, the linker will +remove duplicates. + +23.5.2.2 Script Text Entries +............................ + +Script text entries allow to put the executable script in the entry +itself instead of loading it from a file. The first line of the entry, +everything after the prefix byte and up to the first newline ('0xa') +character, is the script name, and must not contain any kind of space +character, e.g., spaces or tabs. The rest of the entry, up to the +trailing null byte, is the script to execute in the specified language. +The name needs to be unique among all script names, as GDB executes each +script only once based on its name. + + Here is an example from file 'py-section-script.c' in the GDB +testsuite. + + #include "symcat.h" + #include "gdb/section-scripts.h" + asm( + ".pushsection \".debug_gdb_scripts\", \"MS\",@progbits,1\n" + ".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" + ".ascii \"gdb.inlined-script\\n\"\n" + ".ascii \"class test_cmd (gdb.Command):\\n\"\n" + ".ascii \" def __init__ (self):\\n\"\n" + ".ascii \" super (test_cmd, self).__init__ (" + "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" + ".ascii \" def invoke (self, arg, from_tty):\\n\"\n" + ".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" + ".ascii \"test_cmd ()\\n\"\n" + ".byte 0\n" + ".popsection\n" + ); + + Loading of inlined scripts requires a properly configured 'auto-load +safe-path' (*note Auto-loading safe path::). The path to specify in +'auto-load safe-path' is the path of the file containing the +'.debug_gdb_scripts' section. + + +File: gdb.info, Node: Which flavor to choose?, Prev: dotdebug_gdb_scripts section, Up: Auto-loading extensions + +23.5.3 Which flavor to choose? +------------------------------ + +Given the multiple ways of auto-loading extensions, it might not always +be clear which one to choose. This section provides some guidance. + +Benefits of the '-gdb.EXT' way: + + * Can be used with file formats that don't support multiple sections. + + * Ease of finding scripts for public libraries. + + Scripts specified in the '.debug_gdb_scripts' section are searched + for in the source search path. For publicly installed libraries, + e.g., 'libstdc++', there typically isn't a source directory in + which to find the script. + + * Doesn't require source code additions. + +Benefits of the '.debug_gdb_scripts' way: + + * Works with static linking. + + Scripts for libraries done the '-gdb.EXT' way require an objfile to + trigger their loading. When an application is statically linked + the only objfile available is the executable, and it is cumbersome + to attach all the scripts from all the input libraries to the + executable's '-gdb.EXT' script. + + * Works with classes that are entirely inlined. + + Some classes can be entirely inlined, and thus there may not be an + associated shared library to attach a '-gdb.EXT' script to. + + * Scripts needn't be copied out of the source tree. + + In some circumstances, apps can be built out of large collections + of internal libraries, and the build infrastructure necessary to + install the '-gdb.EXT' scripts in a place where GDB can find them + is cumbersome. It may be easier to specify the scripts in the + '.debug_gdb_scripts' section as relative paths, and add a path to + the top of the source tree to the source search path. + + +File: gdb.info, Node: Multiple Extension Languages, Prev: Auto-loading extensions, Up: Extending GDB + +23.6 Multiple Extension Languages +================================= + +The Guile and Python extension languages do not share any state, and +generally do not interfere with each other. There are some things to be +aware of, however. + +23.6.1 Python comes first +------------------------- + +Python was GDB's first extension language, and to avoid breaking +existing behavior Python comes first. This is generally solved by the +"first one wins" principle. GDB maintains a list of enabled extension +languages, and when it makes a call to an extension language, (say to +pretty-print a value), it tries each in turn until an extension language +indicates it has performed the request (e.g., has returned the +pretty-printed form of a value). This extends to errors while +performing such requests: If an error happens while, for example, trying +to pretty-print an object then the error is reported and any following +extension languages are not tried. + + +File: gdb.info, Node: Interpreters, Next: TUI, Prev: Extending GDB, Up: Top + +24 Command Interpreters +*********************** + +GDB supports multiple command interpreters, and some command +infrastructure to allow users or user interface writers to switch +between interpreters or run commands in other interpreters. + + GDB currently supports two command interpreters, the console +interpreter (sometimes called the command-line interpreter or CLI) and +the machine interface interpreter (or GDB/MI). This manual describes +both of these interfaces in great detail. + + By default, GDB will start with the console interpreter. However, +the user may choose to start GDB with another interpreter by specifying +the '-i' or '--interpreter' startup options. Defined interpreters +include: + +'console' + The traditional console or command-line interpreter. This is the + most often used interpreter with GDB. With no interpreter + specified at runtime, GDB will use this interpreter. + +'dap' + When GDB has been built with Python support, it also supports the + Debugger Adapter Protocol. This protocol can be used by a debugger + GUI or an IDE to communicate with GDB. This protocol is documented + at . *Note + Debugger Adapter Protocol::, for information about GDB extensions + to the protocol. + +'mi' + The newest GDB/MI interface (currently 'mi3'). Used primarily by + programs wishing to use GDB as a backend for a debugger GUI or an + IDE. For more information, see *note The GDB/MI Interface: GDB/MI. + +'mi3' + The GDB/MI interface introduced in GDB 9.1. + +'mi2' + The GDB/MI interface introduced in GDB 6.0. + + You may execute commands in any interpreter from the current +interpreter using the appropriate command. If you are running the +console interpreter, simply use the 'interpreter-exec' command: + + interpreter-exec mi "-data-list-register-names" + + GDB/MI has a similar command, although it is only available in +versions of GDB which support GDB/MI version 2 (or greater). + + Note that 'interpreter-exec' only changes the interpreter for the +duration of the specified command. It does not change the interpreter +permanently. + + Although you may only choose a single interpreter at startup, it is +possible to run an independent interpreter on a specified input/output +device (usually a tty). + + For example, consider a debugger GUI or IDE that wants to provide a +GDB console view. It may do so by embedding a terminal emulator widget +in its GUI, starting GDB in the traditional command-line mode with +stdin/stdout/stderr redirected to that terminal, and then creating an MI +interpreter running on a specified input/output device. The console +interpreter created by GDB at startup handles commands the user types in +the terminal widget, while the GUI controls and synchronizes state with +GDB using the separate MI interpreter. + + To start a new secondary "user interface" running MI, use the +'new-ui' command: + + new-ui INTERPRETER TTY + + The INTERPRETER parameter specifies the interpreter to run. This +accepts the same values as the 'interpreter-exec' command. For example, +'console', 'mi', 'mi2', etc. The TTY parameter specifies the name of +the bidirectional file the interpreter uses for input/output, usually +the name of a pseudoterminal slave on Unix systems. For example: + + (gdb) new-ui mi /dev/pts/9 + +runs an MI interpreter on '/dev/pts/9'. + + +File: gdb.info, Node: TUI, Next: Emacs, Prev: Interpreters, Up: Top + +25 GDB Text User Interface +************************** + +The GDB Text User Interface (TUI) is a terminal interface which uses the +'curses' library to show the source file, the assembly output, the +program registers and GDB commands in separate text windows. The TUI +mode is supported only on platforms where a suitable version of the +'curses' library is available. + + The TUI mode is enabled by default when you invoke GDB as 'gdb -tui'. +You can also switch in and out of TUI mode while GDB runs by using +various TUI commands and key bindings, such as 'tui enable' or 'C-x +C-a'. *Note TUI Commands: TUI Commands, and *note TUI Key Bindings: TUI +Keys. + +* Menu: + +* TUI Overview:: TUI overview +* TUI Keys:: TUI key bindings +* TUI Single Key Mode:: TUI single key mode +* TUI Mouse Support:: TUI mouse support +* TUI Commands:: TUI-specific commands +* TUI Configuration:: TUI configuration variables + + +File: gdb.info, Node: TUI Overview, Next: TUI Keys, Up: TUI + +25.1 TUI Overview +================= + +In TUI mode, GDB can display several text windows: + +_command_ + This window is the GDB command window with the GDB prompt and the + GDB output. The GDB input is still managed using readline. + +_source_ + The source window shows the source file of the program. The + current line and active breakpoints are displayed in this window. + +_assembly_ + The assembly window shows the disassembly output of the program. + +_register_ + This window shows the processor registers. Registers are + highlighted when their values change. + + The source and assembly windows show the current program position by +highlighting the current line and marking it with a '>' marker. By +default, source and assembly code styling is disabled for the +highlighted text, but you can enable it with the 'set style +tui-current-position on' command. *Note Output Styling::. + + Breakpoints are indicated with two markers. The first marker +indicates the breakpoint type: + +'B' + Breakpoint which was hit at least once. + +'b' + Breakpoint which was never hit. + +'H' + Hardware breakpoint which was hit at least once. + +'h' + Hardware breakpoint which was never hit. + + The second marker indicates whether the breakpoint is enabled or not: + +'+' + Breakpoint is enabled. + +'-' + Breakpoint is disabled. + + The source, assembly and register windows are updated when the +current thread changes, when the frame changes, or when the program +counter changes. + + These windows are not all visible at the same time. The command +window is always visible. The others can be arranged in several +layouts: + + * source only, + + * assembly only, + + * source and assembly, + + * source and registers, or + + * assembly and registers. + + These are the standard layouts, but other layouts can be defined. + + A status line above the command window shows the following +information: + +_target_ + Indicates the current GDB target. (*note Specifying a Debugging + Target: Targets.). + +_process_ + Gives the current process or thread number. When no process is + being debugged, this field is set to 'No process'. + +_focus_ + Shows the name of the TUI window that has the focus. + +_function_ + Gives the current function name for the selected frame. The name + is demangled if demangling is turned on (*note Print Settings::). + When there is no symbol corresponding to the current program + counter, the string '??' is displayed. + +_line_ + Indicates the current line number for the selected frame. When the + current line number is not known, the string '??' is displayed. + +_pc_ + Indicates the current program counter address. + + +File: gdb.info, Node: TUI Keys, Next: TUI Single Key Mode, Prev: TUI Overview, Up: TUI + +25.2 TUI Key Bindings +===================== + +The TUI installs several key bindings in the readline keymaps (*note +Command Line Editing::). The following key bindings are installed for +both TUI mode and the GDB standard mode. + +'C-x C-a' +'C-x a' +'C-x A' + Enter or leave the TUI mode. When leaving the TUI mode, the curses + window management stops and GDB operates using its standard mode, + writing on the terminal directly. When reentering the TUI mode, + control is given back to the curses windows. The screen is then + refreshed. + + This key binding uses the bindable Readline function + 'tui-switch-mode'. + +'C-x 1' + Use a TUI layout with only one window. The layout will either be + 'source' or 'assembly'. When the TUI mode is not active, it will + switch to the TUI mode. + + Think of this key binding as the Emacs 'C-x 1' binding. + + This key binding uses the bindable Readline function + 'tui-delete-other-windows'. + +'C-x 2' + Use a TUI layout with at least two windows. When the current + layout already has two windows, the next layout with two windows is + used. When a new layout is chosen, one window will always be + common to the previous layout and the new one. + + Think of it as the Emacs 'C-x 2' binding. + + This key binding uses the bindable Readline function + 'tui-change-windows'. + +'C-x o' + Change the active window. The TUI associates several key bindings + (like scrolling and arrow keys) with the active window. This + command gives the focus to the next TUI window. + + Think of it as the Emacs 'C-x o' binding. + + This key binding uses the bindable Readline function + 'tui-other-window'. + +'C-x s' + Switch in and out of the TUI SingleKey mode that binds single keys + to GDB commands (*note TUI Single Key Mode::). + + This key binding uses the bindable Readline function 'next-keymap'. + + The following key bindings only work in the TUI mode: + + + Scroll the active window one page up. + + + Scroll the active window one page down. + + + Scroll the active window one line up. + + + Scroll the active window one line down. + + + Scroll the active window one column left. + + + Scroll the active window one column right. + +'C-L' + Refresh the screen. + + Because the arrow keys scroll the active window in the TUI mode, they +are not available for their normal use by readline unless the command +window has the focus. When another window is active, you must use other +readline key bindings such as 'C-p', 'C-n', 'C-b' and 'C-f' to control +the command window. + + +File: gdb.info, Node: TUI Single Key Mode, Next: TUI Mouse Support, Prev: TUI Keys, Up: TUI + +25.3 TUI Single Key Mode +======================== + +The TUI also provides a "SingleKey" mode, which binds several frequently +used GDB commands to single keys. Type 'C-x s' to switch into this +mode, where the following key bindings are used: + +'c' + continue + +'C' + reverse-continue + +'d' + down + +'f' + finish + +'F' + reverse-finish + +'n' + next + +'N' + reverse-next + +'o' + nexti. The shortcut letter 'o' stands for "step Over". + +'O' + reverse-nexti + +'q' + exit the SingleKey mode. + +'r' + run + +'s' + step + +'S' + reverse-step + +'i' + stepi. The shortcut letter 'i' stands for "step Into". + +'I' + reverse-stepi + +'u' + up + +'v' + info locals + +'w' + where + + Other keys temporarily switch to the GDB command prompt. The key +that was pressed is inserted in the editing buffer so that it is +possible to type most GDB commands without interaction with the TUI +SingleKey mode. Once the command is entered the TUI SingleKey mode is +restored. The only way to permanently leave this mode is by typing 'q' +or 'C-x s'. + + If GDB was built with Readline 8.0 or later, the TUI SingleKey keymap +will be named 'SingleKey'. This can be used in '.inputrc' to add +additional bindings to this keymap. + + +File: gdb.info, Node: TUI Mouse Support, Next: TUI Commands, Prev: TUI Single Key Mode, Up: TUI + +25.4 TUI Mouse Support +====================== + +If the curses library supports the mouse, the TUI supports mouse +actions. + + The mouse wheel scrolls the appropriate window under the mouse +cursor. + + The TUI itself does not directly support copying/pasting with the +mouse. However, on Unix terminals, you can typically press and hold the + key on your keyboard to temporarily bypass GDB's TUI and access +the terminal's native mouse copy/paste functionality (commonly, +click-drag-release or double-click to select text, middle-click to +paste). This copy/paste works with the terminal's selection buffer, as +opposed to the TUI's buffer. Alternatively, to disable mouse support in +the TUI entirely and give the terminal control over mouse clicks, turn +off the 'tui mouse-events' setting (*note set tui mouse-events: +tui-mouse-events.). + + Python extensions can react to mouse clicks (*note Window.click: +python-window-click.). + + +File: gdb.info, Node: TUI Commands, Next: TUI Configuration, Prev: TUI Mouse Support, Up: TUI + +25.5 TUI-specific Commands +========================== + +The TUI has specific commands to control the text windows. These +commands are always available, even when GDB is not in the TUI mode. +When GDB is in the standard mode, most of these commands will +automatically switch to the TUI mode. + + Note that if GDB's 'stdout' is not connected to a terminal, or GDB +has been started with the machine interface interpreter (*note The +GDB/MI Interface: GDB/MI.), most of these commands will fail with an +error, because it would not be possible or desirable to enable curses +window management. + +'tui enable' + Activate TUI mode. The last active TUI window layout will be used + if TUI mode has previously been used in the current debugging + session, otherwise a default layout is used. + +'tui disable' + Disable TUI mode, returning to the console interpreter. + +'info win' + List the names and sizes of all currently displayed windows. + +'tui new-layout NAME WINDOW WEIGHT [WINDOW WEIGHT...]' + Create a new TUI layout. The new layout will be named NAME, and + can be accessed using the 'layout' command (see below). + + Each WINDOW parameter is either the name of a window to display, or + a window description. The windows will be displayed from top to + bottom in the order listed. + + The names of the windows are the same as the ones given to the + 'focus' command (see below); additionally, the 'status' window can + be specified. Note that, because it is of fixed height, the weight + assigned to the status window is of no importance. It is + conventional to use '0' here. + + A window description looks a bit like an invocation of 'tui + new-layout', and is of the form {['-horizontal']WINDOW WEIGHT + [WINDOW WEIGHT...]}. + + This specifies a sub-layout. If '-horizontal' is given, the + windows in this description will be arranged side-by-side, rather + than top-to-bottom. + + Each WEIGHT is an integer. It is the weight of this window + relative to all the other windows in the layout. These numbers are + used to calculate how much of the screen is given to each window. + + For example: + + (gdb) tui new-layout example src 1 regs 1 status 0 cmd 1 + + Here, the new layout is called 'example'. It shows the source and + register windows, followed by the status window, and then finally + the command window. The non-status windows all have the same + weight, so the terminal will be split into three roughly equal + sections. + + Here is a more complex example, showing a horizontal layout: + + (gdb) tui new-layout example {-horizontal src 1 asm 1} 2 status 0 cmd 1 + + This will result in side-by-side source and assembly windows; with + the status and command window being beneath these, filling the + entire width of the terminal. Because they have weight 2, the + source and assembly windows will be twice the height of the command + window. + +'tui layout NAME' +'layout NAME' + Changes which TUI windows are displayed. The NAME parameter + controls which layout is shown. It can be either one of the + built-in layout names, or the name of a layout defined by the user + using 'tui new-layout'. + + The built-in layouts are as follows: + + 'next' + Display the next layout. + + 'prev' + Display the previous layout. + + 'src' + Display the source and command windows. + + 'asm' + Display the assembly and command windows. + + 'split' + Display the source, assembly, and command windows. + + 'regs' + When in 'src' layout display the register, source, and command + windows. When in 'asm' or 'split' layout display the + register, assembler, and command windows. + +'tui focus NAME' +'focus NAME' + Changes which TUI window is currently active for scrolling. The + NAME parameter can be any of the following: + + 'next' + Make the next window active for scrolling. + + 'prev' + Make the previous window active for scrolling. + + 'src' + Make the source window active for scrolling. + + 'asm' + Make the assembly window active for scrolling. + + 'regs' + Make the register window active for scrolling. + + 'cmd' + Make the command window active for scrolling. + +'tui refresh' +'refresh' + Refresh the screen. This is similar to typing 'C-L'. + +'tui reg GROUP' + Changes the register group displayed in the tui register window to + GROUP. If the register window is not currently displayed this + command will cause the register window to be displayed. The list + of register groups, as well as their order is target specific. The + following groups are available on most targets: + 'next' + Repeatedly selecting this group will cause the display to + cycle through all of the available register groups. + + 'prev' + Repeatedly selecting this group will cause the display to + cycle through all of the available register groups in the + reverse order to NEXT. + + 'general' + Display the general registers. + 'float' + Display the floating point registers. + 'system' + Display the system registers. + 'vector' + Display the vector registers. + 'all' + Display all registers. + +'update' + Update the source window and the current execution point. + +'tui window height NAME +COUNT' +'tui window height NAME -COUNT' +'winheight NAME +COUNT' +'winheight NAME -COUNT' + Change the height of the window NAME by COUNT lines. Positive + counts increase the height, while negative counts decrease it. The + NAME parameter can be the name of any currently visible window. + The names of the currently visible windows can be discovered using + 'info win' (*note info win: info_win_command.). + + The set of currently visible windows must always fill the terminal, + and so, it is only possible to resize on window if there are other + visible windows that can either give or receive the extra terminal + space. + +'tui window width NAME +COUNT' +'tui window width NAME -COUNT' +'winwidth NAME +COUNT' +'winwidth NAME -COUNT' + Change the width of the window NAME by COUNT columns. Positive + counts increase the width, while negative counts decrease it. The + NAME parameter can be the name of any currently visible window. + The names of the currently visible windows can be discovered using + 'info win' (*note info win: info_win_command.). + + The set of currently visible windows must always fill the terminal, + and so, it is only possible to resize on window if there are other + visible windows that can either give or receive the extra terminal + space. + + +File: gdb.info, Node: TUI Configuration, Prev: TUI Commands, Up: TUI + +25.6 TUI Configuration Variables +================================ + +Several configuration variables control the appearance of TUI windows. + +'set tui border-kind KIND' + Select the border appearance for the source, assembly and register + windows. The possible values are the following: + 'space' + Use a space character to draw the border. + + 'ascii' + Use ASCII characters '+', '-' and '|' to draw the border. + + 'acs' + Use the Alternate Character Set to draw the border. The + border is drawn using character line graphics if the terminal + supports them. + +'set tui border-mode MODE' +'set tui active-border-mode MODE' + Select the display attributes for the borders of the inactive + windows or the active window. The MODE can be one of the + following: + 'normal' + Use normal attributes to display the border. + + 'standout' + Use standout mode. + + 'reverse' + Use reverse video mode. + + 'half' + Use half bright mode. + + 'half-standout' + Use half bright and standout mode. + + 'bold' + Use extra bright or bold mode. + + 'bold-standout' + Use extra bright or bold and standout mode. + +'set tui tab-width NCHARS' + Set the width of tab stops to be NCHARS characters. This setting + affects the display of TAB characters in the source and assembly + windows. + +'set tui compact-source [on|off]' + Set whether the TUI source window is displayed in "compact" form. + The default display uses more space for line numbers; the compact + display uses only as much space as is needed for the line numbers + in the current file. + +'set tui mouse-events [on|off]' + When on (default), mouse clicks control the TUI (*note TUI Mouse + Support::). When off, mouse clicks are handled by the terminal, + enabling terminal-native text selection. + +'set debug tui [on|off]' + Turn on or off display of GDB internal debug messages relating to + the TUI. + +'show debug tui' + Show the current status of displaying GDB internal debug messages + relating to the TUI. + + Note that the colors of the TUI borders can be controlled using the +appropriate 'set style' commands. *Note Output Styling::. + + +File: gdb.info, Node: Emacs, Next: GDB/MI, Prev: TUI, Up: Top + +26 Using GDB under GNU Emacs +**************************** + +A special interface allows you to use GNU Emacs to view (and edit) the +source files for the program you are debugging with GDB. + + To use this interface, use the command 'M-x gdb' in Emacs. Give the +executable file you want to debug as an argument. This command starts +GDB as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. + + Running GDB under Emacs can be just like running GDB normally except +for two things: + + * All "terminal" input and output goes through an Emacs buffer, + called the GUD buffer. + + This applies both to GDB commands and their output, and to the + input and output done by the program you are debugging. + + This is useful because it means that you can copy the text of + previous commands and input them again; you can even use parts of + the output in this way. + + All the facilities of Emacs' Shell mode are available for + interacting with your program. In particular, you can send signals + the usual way--for example, 'C-c C-c' for an interrupt, 'C-c C-z' + for a stop. + + * GDB displays source code through Emacs. + + Each time GDB displays a stack frame, Emacs automatically finds the + source file for that frame and puts an arrow ('=>') at the left + margin of the current line. Emacs uses a separate buffer for + source display, and splits the screen to show both your GDB session + and the source. + + Explicit GDB 'list' or search commands still produce output as + usual, but you probably have no reason to use them from Emacs. + + We call this "text command mode". Emacs 22.1, and later, also uses a +graphical mode, enabled by default, which provides further buffers that +can control the execution and describe the state of your program. *Note +(Emacs)GDB Graphical Interface::. + + If you specify an absolute file name when prompted for the 'M-x gdb' +argument, then Emacs sets your current working directory to where your +program resides. If you only specify the file name, then Emacs sets +your current working directory to the directory associated with the +previous buffer. In this case, GDB may find your program by searching +your environment's 'PATH' variable, but on some operating systems it +might not find the source. So, although the GDB input and output +session proceeds normally, the auxiliary buffer does not display the +current source and line of execution. + + The initial working directory of GDB is printed on the top line of +the GUD buffer and this serves as a default for the commands that +specify files for GDB to operate on. *Note Commands to Specify Files: +Files. + + By default, 'M-x gdb' calls the program called 'gdb'. If you need to +call GDB by a different name (for example, if you keep several +configurations around, with different names) you can customize the Emacs +variable 'gud-gdb-command-name' to run the one you want. + + In the GUD buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: + +'C-h m' + Describe the features of Emacs' GUD Mode. + +'C-c C-s' + Execute to another source line, like the GDB 'step' command; also + update the display window to show the current file and location. + +'C-c C-n' + Execute to next source line in this function, skipping all function + calls, like the GDB 'next' command. Then update the display window + to show the current file and location. + +'C-c C-i' + Execute one instruction, like the GDB 'stepi' command; update + display window accordingly. + +'C-c C-f' + Execute until exit from the selected stack frame, like the GDB + 'finish' command. + +'C-c C-r' + Continue execution of your program, like the GDB 'continue' + command. + +'C-c <' + Go up the number of frames indicated by the numeric argument (*note + Numeric Arguments: (Emacs)Arguments.), like the GDB 'up' command. + +'C-c >' + Go down the number of frames indicated by the numeric argument, + like the GDB 'down' command. + + In any source file, the Emacs command 'C-x ' ('gud-break') tells +GDB to set a breakpoint on the source line point is on. + + In text command mode, if you type 'M-x speedbar', Emacs displays a +separate frame which shows a backtrace when the GUD buffer is current. +Move point to any frame in the stack and type to make it become +the current frame and display the associated source in the source +buffer. Alternatively, click 'Mouse-2' to make the selected frame +become the current one. In graphical mode, the speedbar displays watch +expressions. + + If you accidentally delete the source-display buffer, an easy way to +get it back is to type the command 'f' in the GDB buffer, to request a +frame display; when you run under Emacs, this recreates the source +buffer if necessary to show you the context of the current frame. + + The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit the +files with these buffers if you wish; but keep in mind that GDB +communicates with Emacs in terms of line numbers. If you add or delete +lines from the text, the line numbers that GDB knows cease to correspond +properly with the code. + + A more detailed description of Emacs' interaction with GDB is given +in the Emacs manual (*note (Emacs)Debuggers::). + + +File: gdb.info, Node: GDB/MI, Next: Annotations, Prev: Emacs, Up: Top + +27 The GDB/MI Interface +*********************** + +* Menu: + +* GDB/MI General Design:: +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Development and Front Ends:: +* GDB/MI Output Records:: +* GDB/MI Simple Examples:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Commands:: +* GDB/MI Catchpoint Commands:: +* GDB/MI Program Context:: +* GDB/MI Thread Commands:: +* GDB/MI Ada Tasking Commands:: +* GDB/MI Program Execution:: +* GDB/MI Stack Manipulation:: +* GDB/MI Variable Objects:: +* GDB/MI Data Manipulation:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Symbol Query:: +* GDB/MI File Commands:: +* GDB/MI Target Manipulation:: +* GDB/MI File Transfer Commands:: +* GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: +* GDB/MI Miscellaneous Commands:: + +Function and Purpose +==================== + +GDB/MI is a line based machine oriented text interface to GDB and is +activated by specifying using the '--interpreter' command line option +(*note Mode Options::). It is specifically intended to support the +development of systems which use the debugger as just one small +component of a larger system. + + This chapter is a specification of the GDB/MI interface. It is +written in the form of a reference manual. + + Note that GDB/MI is still under construction, so some of the features +described below are incomplete and subject to change (*note GDB/MI +Development and Front Ends: GDB/MI Development and Front Ends.). + +Notation and Terminology +======================== + +This chapter uses the following notation: + + * '|' separates two alternatives. + + * '[ SOMETHING ]' indicates that SOMETHING is optional: it may or may + not be given. + + * '( GROUP )*' means that GROUP inside the parentheses may repeat + zero or more times. + + * '( GROUP )+' means that GROUP inside the parentheses may repeat one + or more times. + + * '( GROUP )' means that GROUP inside the parentheses occurs exactly + once. + + * '"STRING"' means a literal STRING. + +* Menu: + +* GDB/MI General Design:: +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Development and Front Ends:: +* GDB/MI Output Records:: +* GDB/MI Simple Examples:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Commands:: +* GDB/MI Catchpoint Commands:: +* GDB/MI Program Context:: +* GDB/MI Thread Commands:: +* GDB/MI Ada Tasking Commands:: +* GDB/MI Program Execution:: +* GDB/MI Stack Manipulation:: +* GDB/MI Variable Objects:: +* GDB/MI Data Manipulation:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Symbol Query:: +* GDB/MI File Commands:: +* GDB/MI Target Manipulation:: +* GDB/MI File Transfer Commands:: +* GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: +* GDB/MI Miscellaneous Commands:: + + +File: gdb.info, Node: GDB/MI General Design, Next: GDB/MI Command Syntax, Up: GDB/MI + +27.1 GDB/MI General Design +========================== + +Interaction of a GDB/MI frontend with GDB involves three parts--commands +sent to GDB, responses to those commands and notifications. Each +command results in exactly one response, indicating either successful +completion of the command, or an error. For the commands that do not +resume the target, the response contains the requested information. For +the commands that resume the target, the response only indicates whether +the target was successfully resumed. Notifications is the mechanism for +reporting changes in the state of the target, or in GDB state, that +cannot conveniently be associated with a command and reported as part of +that command response. + + The important examples of notifications are: + + * Exec notifications. These are used to report changes in target + state--when a target is resumed, or stopped. It would not be + feasible to include this information in response of resuming + commands, because one resume commands can result in multiple events + in different threads. Also, quite some time may pass before any + event happens in the target, while a frontend needs to know whether + the resuming command itself was successfully executed. + + * Console output, and status notifications. Console output + notifications are used to report output of CLI commands, as well as + diagnostics for other commands. Status notifications are used to + report the progress of a long-running operation. Naturally, + including this information in command response would mean no output + is produced until the command is finished, which is undesirable. + + * General notifications. Commands may have various side effects on + the GDB or target state beyond their official purpose. For + example, a command may change the selected thread. Although such + changes can be included in command response, using notification + allows for more orthogonal frontend design. + + There's no guarantee that whenever an MI command reports an error, +GDB or the target are in any specific state, and especially, the state +is not reverted to the state before the MI command was processed. +Therefore, whenever an MI command results in an error, we recommend that +the frontend refreshes all the information shown in the user interface. + +* Menu: + +* Context management:: +* Asynchronous and non-stop modes:: +* Thread groups:: + + +File: gdb.info, Node: Context management, Next: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.1 Context management +------------------------- + +27.1.1.1 Threads and Frames +........................... + +In most cases when GDB accesses the target, this access is done in +context of a specific thread and frame (*note Frames::). Often, even +when accessing global data, the target requires that a thread be +specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with GDB via a +single terminal, so no confusion is possible as to what thread and frame +are the current ones. + + In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information itself. +Second, a graphical frontend can have more than one window, each one +used for debugging a different thread, and the frontend might want to +access additional threads for internal purposes. This increases the +risk that by relying on implicitly selected thread, the frontend may be +operating on a wrong one. Therefore, each MI command should explicitly +specify which thread and frame to operate on. To make it possible, each +MI command accepts the '--thread' and '--frame' options, the value to +each is GDB global identifier for thread and frame to operate on. + + Usually, each top-level window in a frontend allows the user to +select a thread and a frame, and remembers the user selection for +further operations. However, in some cases GDB may suggest that the +current thread or frame be changed. For example, when stopping on a +breakpoint it is reasonable to switch to the thread where breakpoint is +hit. For another example, if the user issues the CLI 'thread' or +'frame' commands via the frontend, it is desirable to change the +frontend's selection to the one specified by user. GDB communicates the +suggestion to change current thread and frame using the +'=thread-selected' notification. + + Note that historically, MI shares the selected thread with CLI, so +frontends used the '-thread-select' to execute commands in the right +context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit '-thread-select' command before +every command. This doubles the number of commands that need to be +sent. The alternative approach is to suppress '-thread-select' if the +selected thread in GDB is supposed to be identical to the thread the +frontend wants to operate on. However, getting this optimization right +can be tricky. In particular, if the frontend sends several commands to +GDB, and one of the commands changes the selected thread, then the +behavior of subsequent commands will change. So, a frontend should +either wait for response from such problematic commands, or explicitly +add '-thread-select' for all subsequent commands. No frontend is known +to do this exactly right, so it is suggested to just always pass the +'--thread' and '--frame' options. + +27.1.1.2 Language +................. + +The execution of several commands depends on which language is selected. +By default, the current language (*note show language::) is used. But +for commands known to be language-sensitive, it is recommended to use +the '--language' option. This option takes one argument, which is the +name of the language to use while executing the command. For instance: + + -data-evaluate-expression --language c "sizeof (void*)" + ^done,value="4" + (gdb) + + The valid language names are the same names accepted by the 'set +language' command (*note Manually::), excluding 'auto', 'local' or +'unknown'. + + +File: gdb.info, Node: Asynchronous and non-stop modes, Next: Thread groups, Prev: Context management, Up: GDB/MI General Design + +27.1.2 Asynchronous command execution and non-stop mode +------------------------------------------------------- + +On some targets, GDB is capable of processing MI commands even while the +target is running. This is called "asynchronous command execution" +(*note Background Execution::). The frontend may specify a preference +for asynchronous execution using the '-gdb-set mi-async 1' command, +which should be emitted before either running the executable or +attaching to the target. After the frontend has started the executable +or attached to the target, it can find if asynchronous execution is +enabled using the '-list-target-features' command. + +'-gdb-set mi-async [on|off]' + Set whether MI is in asynchronous mode. + + When 'off', which is the default, MI execution commands (e.g., + '-exec-continue') are foreground commands, and GDB waits for the + program to stop before processing further commands. + + When 'on', MI execution commands are background execution commands + (e.g., '-exec-continue' becomes the equivalent of the 'c&' CLI + command), and so GDB is capable of processing MI commands even + while the target is running. + +'-gdb-show mi-async' + Show whether MI asynchronous mode is enabled. + + Note: In GDB version 7.7 and earlier, this option was called +'target-async' instead of 'mi-async', and it had the effect of both +putting MI in asynchronous mode and making CLI background commands +possible. CLI background commands are now always possible "out of the +box" if the target supports them. The old spelling is kept as a +deprecated alias for backwards compatibility. + + Even if GDB can accept a command while target is running, many +commands that access the target do not work when the target is running. +Therefore, asynchronous command execution is most useful when combined +with non-stop mode (*note Non-Stop Mode::). Then, it is possible to +examine the state of one thread, while other threads are running. + + When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as 'print', 'set', +and breakpoint commands, still access the target in the context of a +specific thread, so frontend should try to find a stopped thread and +perform the operation on that thread (using the '--thread' option). + + Which commands will work in the context of a running thread is highly +target dependent. However, the two commands '-exec-interrupt', to stop +a thread, and '-thread-info', to find the state of a thread, will always +work. + + +File: gdb.info, Node: Thread groups, Prev: Asynchronous and non-stop modes, Up: GDB/MI General Design + +27.1.3 Thread groups +-------------------- + +GDB may be used to debug several processes at the same time. On some +platforms, GDB may support debugging of several hardware systems, each +one having several cores with several different processes running on +each core. This section describes the MI mechanism to support such +debugging scenarios. + + The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the '--thread' option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce neither +additional '--process' option, nor an notion of the current process in +the MI interface. The only strictly new feature that is required is the +ability to find how the threads are grouped into processes. + + To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +"thread group". Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new command, +'-list-thread-groups', returns the list of top-level thread groups, +which correspond to processes that GDB is debugging at the moment. By +passing an identifier of a thread group to the '-list-thread-groups' +command, it is possible to obtain the members of specific thread group. + + To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of "available thread group" is introduced. +Available thread group is an thread group that GDB is not debugging, but +that can be attached to, using the '-target-attach' command. The list +of available top-level thread groups can be obtained using +'-list-thread-groups --available'. In general, the content of a thread +group may be only retrieved only after attaching to that thread group. + + Thread groups are related to inferiors (*note Inferiors Connections +and Programs::). Each inferior corresponds to a thread group of a +special type 'process', and some additional operations are permitted on +such thread groups. + + +File: gdb.info, Node: GDB/MI Command Syntax, Next: GDB/MI Compatibility with CLI, Prev: GDB/MI General Design, Up: GDB/MI + +27.2 GDB/MI Command Syntax +========================== + +* Menu: + +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: + + +File: gdb.info, Node: GDB/MI Input Syntax, Next: GDB/MI Output Syntax, Up: GDB/MI Command Syntax + +27.2.1 GDB/MI Input Syntax +-------------------------- + +'COMMAND ==>' + 'CLI-COMMAND | MI-COMMAND' + +'CLI-COMMAND ==>' + '[ TOKEN ] CLI-COMMAND NL', where CLI-COMMAND is any existing GDB + CLI command. + +'MI-COMMAND ==>' + '[ TOKEN ] "-" OPERATION ( " " OPTION )* [ " --" ] ( " " PARAMETER + )* NL' + +'TOKEN ==>' + "any sequence of digits" + +'OPTION ==>' + '"-" PARAMETER [ " " PARAMETER ]' + +'PARAMETER ==>' + 'NON-BLANK-SEQUENCE | C-STRING' + +'OPERATION ==>' + _any of the operations described in this chapter_ + +'NON-BLANK-SEQUENCE ==>' + _anything, provided it doesn't contain special characters such as + "-", NL, """ and of course " "_ + +'C-STRING ==>' + '""" SEVEN-BIT-ISO-C-STRING-CONTENT """' + +'NL ==>' + 'CR | CR-LF' + +Notes: + + * The CLI commands are still handled by the MI interpreter; their + output is described below. + + * The 'TOKEN', when present, is passed back when the command + finishes. + + * Some MI commands accept optional arguments as part of the parameter + list. Each option is identified by a leading '-' (dash) and may be + followed by an optional argument parameter. Options occur first in + the parameter list and can be delimited from normal parameters + using '--' (this is useful when some parameters begin with a dash). + + Pragmatics: + + * We want easy access to the existing CLI syntax (for debugging). + + * We want it to be easy to spot a MI operation. + + +File: gdb.info, Node: GDB/MI Output Syntax, Prev: GDB/MI Input Syntax, Up: GDB/MI Command Syntax + +27.2.2 GDB/MI Output Syntax +--------------------------- + +The output from GDB/MI consists of zero or more out-of-band records +followed, optionally, by a single result record. This result record is +for the most recent command. The sequence of output records is +terminated by '(gdb)'. + + If an input command was prefixed with a 'TOKEN' then the +corresponding output for that command will also be prefixed by that same +TOKEN. + +'OUTPUT ==>' + '( OUT-OF-BAND-RECORD )* [ RESULT-RECORD ] "(gdb)" NL' + +'RESULT-RECORD ==>' + ' [ TOKEN ] "^" RESULT-CLASS ( "," RESULT )* NL' + +'OUT-OF-BAND-RECORD ==>' + 'ASYNC-RECORD | STREAM-RECORD' + +'ASYNC-RECORD ==>' + 'EXEC-ASYNC-OUTPUT | STATUS-ASYNC-OUTPUT | NOTIFY-ASYNC-OUTPUT' + +'EXEC-ASYNC-OUTPUT ==>' + '[ TOKEN ] "*" ASYNC-OUTPUT NL' + +'STATUS-ASYNC-OUTPUT ==>' + '[ TOKEN ] "+" ASYNC-OUTPUT NL' + +'NOTIFY-ASYNC-OUTPUT ==>' + '[ TOKEN ] "=" ASYNC-OUTPUT NL' + +'ASYNC-OUTPUT ==>' + 'ASYNC-CLASS ( "," RESULT )*' + +'RESULT-CLASS ==>' + '"done" | "running" | "connected" | "error" | "exit"' + +'ASYNC-CLASS ==>' + '"stopped" | OTHERS' (where OTHERS will be added depending on the + needs--this is still in development). + +'RESULT ==>' + ' VARIABLE "=" VALUE' + +'VARIABLE ==>' + ' STRING ' + +'VALUE ==>' + ' CONST | TUPLE | LIST ' + +'CONST ==>' + 'C-STRING' + +'TUPLE ==>' + ' "{}" | "{" RESULT ( "," RESULT )* "}" ' + +'LIST ==>' + ' "[]" | "[" VALUE ( "," VALUE )* "]" | "[" RESULT ( "," RESULT )* + "]" ' + +'STREAM-RECORD ==>' + 'CONSOLE-STREAM-OUTPUT | TARGET-STREAM-OUTPUT | LOG-STREAM-OUTPUT' + +'CONSOLE-STREAM-OUTPUT ==>' + '"~" C-STRING NL' + +'TARGET-STREAM-OUTPUT ==>' + '"@" C-STRING NL' + +'LOG-STREAM-OUTPUT ==>' + '"&" C-STRING NL' + +'NL ==>' + 'CR | CR-LF' + +'TOKEN ==>' + _any sequence of digits_. + +Notes: + + * All output sequences end in a single line containing a period. + + * The 'TOKEN' is from the corresponding request. Note that for all + async output, while the token is allowed by the grammar and may be + output by future versions of GDB for select async output messages, + it is generally omitted. Frontends should treat all async output + as reporting general changes in the state of the target and there + should be no need to associate async output to any prior command. + + * STATUS-ASYNC-OUTPUT contains on-going status information about the + progress of a slow operation. It can be discarded. All status + output is prefixed by '+'. + + * EXEC-ASYNC-OUTPUT contains asynchronous state change on the target + (stopped, started, disappeared). All async output is prefixed by + '*'. + + * NOTIFY-ASYNC-OUTPUT contains supplementary information that the + client should handle (e.g., a new breakpoint information). All + notify output is prefixed by '='. + + * CONSOLE-STREAM-OUTPUT is output that should be displayed as is in + the console. It is the textual response to a CLI command. All the + console output is prefixed by '~'. + + * TARGET-STREAM-OUTPUT is the output produced by the target program. + All the target output is prefixed by '@'. + + * LOG-STREAM-OUTPUT is output text coming from GDB's internals, for + instance messages that should be displayed as part of an error log. + All the log output is prefixed by '&'. + + * New GDB/MI commands should only output LISTS containing VALUES. + + *Note GDB/MI Stream Records: GDB/MI Stream Records, for more details +about the various output records. + + +File: gdb.info, Node: GDB/MI Compatibility with CLI, Next: GDB/MI Development and Front Ends, Prev: GDB/MI Command Syntax, Up: GDB/MI + +27.3 GDB/MI Compatibility with CLI +================================== + +For the developers convenience CLI commands can be entered directly, but +there may be some unexpected behavior. For example, commands that query +the user will behave as if the user replied yes, breakpoint command +lists are not executed and some CLI commands, such as 'if', 'when' and +'define', prompt for further input with '>', which is not valid MI +output. + + This feature may be removed at some stage in the future and it is +recommended that front ends use the '-interpreter-exec' command (*note +-interpreter-exec::). + + +File: gdb.info, Node: GDB/MI Development and Front Ends, Next: GDB/MI Output Records, Prev: GDB/MI Compatibility with CLI, Up: GDB/MI + +27.4 GDB/MI Development and Front Ends +====================================== + +The application which takes the MI output and presents the state of the +program being debugged to the user is called a "front end". + + Since GDB/MI is used by a variety of front ends to GDB, changes to +the MI interface may break existing usage. This section describes how +the protocol changes and how to request previous version of the protocol +when it does. + + Some changes in MI need not break a carefully designed front end, and +for these the MI version will remain unchanged. The following is a list +of changes that may occur within one level, so front ends should parse +MI output in a way that can handle them: + + * New MI commands may be added. + + * New fields may be added to the output of any MI command. + + * The range of values for fields with specified values, e.g., + 'in_scope' (*note -var-update::) may be extended. + + If the changes are likely to break front ends, the MI version level +will be increased by one. The new versions of the MI protocol are not +compatible with the old versions. Old versions of MI remain available, +allowing front ends to keep using them until they are modified to use +the latest MI version. + + Since '--interpreter=mi' always points to the latest MI version, it +is recommended that front ends request a specific version of MI when +launching GDB (e.g. '--interpreter=mi2') to make sure they get an +interpreter with the MI version they expect. + + The following table gives a summary of the released versions of the +MI interface: the version number, the version of GDB in which it first +appeared and the breaking changes compared to the previous version. + +MI GDB Breaking changes +version version +--------------------------------------------------------------------------- + 1 5.1 None + + 2 6.0 + * The '-environment-pwd', '-environment-directory' + and '-environment-path' commands now returns values + using the MI output syntax, rather than CLI output + syntax. + + * '-var-list-children''s 'children' result field is + now a list, rather than a tuple. + + * '-var-update''s 'changelist' result field is now a + list, rather than a tuple. + + 3 9.1 + * The output of information about multi-location + breakpoints has changed in the responses to the + '-break-insert' and '-break-info' commands, as well + as in the '=breakpoint-created' and + '=breakpoint-modified' events. The multiple + locations are now placed in a 'locations' field, + whose value is a list. + + 4 13.1 + * The syntax of the "script" field in breakpoint + output has changed in the responses to the + '-break-insert' and '-break-info' commands, as well + as the '=breakpoint-created' and + '=breakpoint-modified' events. The previous output + was syntactically invalid. The new output is a + list. + + + If your front end cannot yet migrate to a more recent version of the +MI protocol, you can nevertheless selectively enable specific features +available in those recent MI versions, using the following commands: + +'-fix-multi-location-breakpoint-output' + Use the output for multi-location breakpoints which was introduced + by MI 3, even when using MI versions below 3. This command has no + effect when using MI version 3 or later. + +'-fix-breakpoint-script-output' + Use the output for the breakpoint "script" field which was + introduced by MI 4, even when using MI versions below 4. This + command has no effect when using MI version 4 or later. + + The best way to avoid unexpected changes in MI that might break your +front end is to make your project known to GDB developers and follow +development on and . + + +File: gdb.info, Node: GDB/MI Output Records, Next: GDB/MI Simple Examples, Prev: GDB/MI Development and Front Ends, Up: GDB/MI + +27.5 GDB/MI Output Records +========================== + +* Menu: + +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Async Records:: +* GDB/MI Breakpoint Information:: +* GDB/MI Frame Information:: +* GDB/MI Thread Information:: +* GDB/MI Ada Exception Information:: + + +File: gdb.info, Node: GDB/MI Result Records, Next: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.1 GDB/MI Result Records +---------------------------- + +In addition to a number of out-of-band notifications, the response to a +GDB/MI command includes one of the following result indications: + +'"^done" [ "," RESULTS ]' + The synchronous operation was successful, 'RESULTS' are the return + values. + +'"^running"' + This result record is equivalent to '^done'. Historically, it was + output instead of '^done' if the command has resumed the target. + This behavior is maintained for backward compatibility, but all + frontends should treat '^done' and '^running' identically and rely + on the '*running' output record to determine which threads are + resumed. + +'"^connected"' + GDB has connected to a remote target. + +'"^error" "," "msg=" C-STRING [ "," "code=" C-STRING ]' + The operation failed. The 'msg=C-STRING' variable contains the + corresponding error message. + + If present, the 'code=C-STRING' variable provides an error code on + which consumers can rely on to detect the corresponding error + condition. At present, only one error code is defined: + + '"undefined-command"' + Indicates that the command causing the error does not exist. + +'"^exit"' + GDB has terminated. + + +File: gdb.info, Node: GDB/MI Stream Records, Next: GDB/MI Async Records, Prev: GDB/MI Result Records, Up: GDB/MI Output Records + +27.5.2 GDB/MI Stream Records +---------------------------- + +GDB internally maintains a number of output streams: the console, the +target, and the log. The output intended for each of these streams is +funneled through the GDB/MI interface using "stream records". + + Each stream record begins with a unique "prefix character" which +identifies its stream (*note GDB/MI Output Syntax: GDB/MI Output +Syntax.). In addition to the prefix, each stream record contains a +'STRING-OUTPUT'. This is either raw text (with an implicit new line) or +a quoted C string (which does not contain an implicit newline). + +'"~" STRING-OUTPUT' + The console output stream contains text that should be displayed in + the CLI console window. It contains the textual responses to CLI + commands. + +'"@" STRING-OUTPUT' + The target output stream contains any textual output from the + running target. This is only present when GDB's event loop is + truly asynchronous, which is currently only the case for remote + targets. + +'"&" STRING-OUTPUT' + The log stream contains debugging messages being produced by GDB's + internals. + + +File: gdb.info, Node: GDB/MI Async Records, Next: GDB/MI Breakpoint Information, Prev: GDB/MI Stream Records, Up: GDB/MI Output Records + +27.5.3 GDB/MI Async Records +--------------------------- + +"Async" records are used to notify the GDB/MI client of additional +changes that have occurred. Those changes can either be a consequence +of GDB/MI commands (e.g., a breakpoint modified) or a result of target +activity (e.g., target stopped). + + The following is the list of possible async records: + +'*running,thread-id="THREAD"' + The target is now running. The THREAD field can be the global + thread ID of the thread that is now running, and it can be 'all' if + all threads are running. The frontend should assume that no + interaction with a running thread is possible after this + notification is produced. The frontend should not assume that this + notification is output only once for any command. GDB may emit + this notification several times, either for different threads, + because it cannot resume all threads together, or even for a single + thread, if the thread must be stepped though some code before + letting it run freely. + +'*stopped,reason="REASON",thread-id="ID",stopped-threads="STOPPED",core="CORE"' + The target has stopped. The REASON field can have one of the + following values: + + 'breakpoint-hit' + A breakpoint was reached. + 'watchpoint-trigger' + A watchpoint was triggered. + 'read-watchpoint-trigger' + A read watchpoint was triggered. + 'access-watchpoint-trigger' + An access watchpoint was triggered. + 'function-finished' + An -exec-finish or similar CLI command was accomplished. + 'location-reached' + An -exec-until or similar CLI command was accomplished. + 'watchpoint-scope' + A watchpoint has gone out of scope. + 'end-stepping-range' + An -exec-next, -exec-next-instruction, -exec-step, + -exec-step-instruction or similar CLI command was + accomplished. + 'exited-signalled' + The inferior exited because of a signal. + 'exited' + The inferior exited. + 'exited-normally' + The inferior exited normally. + 'signal-received' + A signal was received by the inferior. + 'solib-event' + The inferior has stopped due to a library being loaded or + unloaded. This can happen when 'stop-on-solib-events' (*note + Files::) is set or when a 'catch load' or 'catch unload' + catchpoint is in use (*note Set Catchpoints::). + 'fork' + The inferior has forked. This is reported when 'catch fork' + (*note Set Catchpoints::) has been used. + 'vfork' + The inferior has vforked. This is reported in when 'catch + vfork' (*note Set Catchpoints::) has been used. + 'syscall-entry' + The inferior entered a system call. This is reported when + 'catch syscall' (*note Set Catchpoints::) has been used. + 'syscall-return' + The inferior returned from a system call. This is reported + when 'catch syscall' (*note Set Catchpoints::) has been used. + 'exec' + The inferior called 'exec'. This is reported when 'catch + exec' (*note Set Catchpoints::) has been used. + 'no-history' + There isn't enough history recorded to continue reverse + execution. + + The ID field identifies the global thread ID of the thread that + directly caused the stop - for example by hitting a breakpoint. + Depending on whether all-stop mode is in effect (*note All-Stop + Mode::), GDB may either stop all threads, or only the thread that + directly triggered the stop. If all threads are stopped, the + STOPPED field will have the value of '"all"'. Otherwise, the value + of the STOPPED field will be a list of thread identifiers. + Presently, this list will always include a single thread, but + frontend should be prepared to see several threads in the list. + The CORE field reports the processor core on which the stop event + has happened. This field may be absent if such information is not + available. + +'=thread-group-added,id="ID"' +'=thread-group-removed,id="ID"' + A thread group was either added or removed. The ID field contains + the GDB identifier of the thread group. When a thread group is + added, it generally might not be associated with a running process. + When a thread group is removed, its id becomes invalid and cannot + be used in any way. + +'=thread-group-started,id="ID",pid="PID"' + A thread group became associated with a running program, either + because the program was just started or the thread group was + attached to a program. The ID field contains the GDB identifier of + the thread group. The PID field contains process identifier, + specific to the operating system. + +'=thread-group-exited,id="ID"[,exit-code="CODE"]' + A thread group is no longer associated with a running program, + either because the program has exited, or because it was detached + from. The ID field contains the GDB identifier of the thread + group. The CODE field is the exit code of the inferior; it exists + only when the inferior exited with some code. + +'=thread-created,id="ID",group-id="GID"' +'=thread-exited,id="ID",group-id="GID"' + A thread either was created, or has exited. The ID field contains + the global GDB identifier of the thread. The GID field identifies + the thread group this thread belongs to. + +'=thread-selected,id="ID"[,frame="FRAME"]' + Informs that the selected thread or frame were changed. This + notification is not emitted as result of the '-thread-select' or + '-stack-select-frame' commands, but is emitted whenever an MI + command that is not documented to change the selected thread and + frame actually changes them. In particular, invoking, directly or + indirectly (via user-defined command), the CLI 'thread' or 'frame' + commands, will generate this notification. Changing the thread or + frame from another user interface (see *note Interpreters::) will + also generate this notification. + + The FRAME field is only present if the newly selected thread is + stopped. See *note GDB/MI Frame Information:: for the format of + its value. + + We suggest that in response to this notification, front ends + highlight the selected thread and cause subsequent commands to + apply to that thread. + +'=library-loaded,...' + Reports that a new library file was loaded by the program. This + notification has 5 fields--ID, TARGET-NAME, HOST-NAME, + SYMBOLS-LOADED and RANGES. The ID field is an opaque identifier of + the library. For remote debugging case, TARGET-NAME and HOST-NAME + fields give the name of the library file on the target, and on the + host respectively. For native debugging, both those fields have + the same value. The SYMBOLS-LOADED field is emitted only for + backward compatibility and should not be relied on to convey any + useful information. The THREAD-GROUP field, if present, specifies + the id of the thread group in whose context the library was loaded. + If the field is absent, it means the library was loaded in the + context of all present thread groups. The RANGES field specifies + the ranges of addresses belonging to this library. + +'=library-unloaded,...' + Reports that a library was unloaded by the program. This + notification has 3 fields--ID, TARGET-NAME and HOST-NAME with the + same meaning as for the '=library-loaded' notification. The + THREAD-GROUP field, if present, specifies the id of the thread + group in whose context the library was unloaded. If the field is + absent, it means the library was unloaded in the context of all + present thread groups. + +'=traceframe-changed,num=TFNUM,tracepoint=TPNUM' +'=traceframe-changed,end' + Reports that the trace frame was changed and its new number is + TFNUM. The number of the tracepoint associated with this trace + frame is TPNUM. + +'=tsv-created,name=NAME,initial=INITIAL' + Reports that the new trace state variable NAME is created with + initial value INITIAL. + +'=tsv-deleted,name=NAME' +'=tsv-deleted' + Reports that the trace state variable NAME is deleted or all trace + state variables are deleted. + +'=tsv-modified,name=NAME,initial=INITIAL[,current=CURRENT]' + Reports that the trace state variable NAME is modified with the + initial value INITIAL. The current value CURRENT of trace state + variable is optional and is reported if the current value of trace + state variable is known. + +'=breakpoint-created,bkpt={...}' +'=breakpoint-modified,bkpt={...}' +'=breakpoint-deleted,id=NUMBER' + Reports that a breakpoint was created, modified, or deleted, + respectively. Only user-visible breakpoints are reported to the MI + user. + + The BKPT argument is of the same form as returned by the various + breakpoint commands; *Note GDB/MI Breakpoint Commands::. The + NUMBER is the ordinal number of the breakpoint. + + Note that if a breakpoint is emitted in the result record of a + command, then it will not also be emitted in an async record. + +'=record-started,thread-group="ID",method="METHOD"[,format="FORMAT"]' +'=record-stopped,thread-group="ID"' + Execution log recording was either started or stopped on an + inferior. The ID is the GDB identifier of the thread group + corresponding to the affected inferior. + + The METHOD field indicates the method used to record execution. If + the method in use supports multiple recording formats, FORMAT will + be present and contain the currently used format. *Note Process + Record and Replay::, for existing method and format values. + +'=cmd-param-changed,param=PARAM,value=VALUE' + Reports that a parameter of the command 'set PARAM' is changed to + VALUE. In the multi-word 'set' command, the PARAM is the whole + parameter list to 'set' command. For example, In command 'set + check type on', PARAM is 'check type' and VALUE is 'on'. + +'=memory-changed,thread-group=ID,addr=ADDR,len=LEN[,type="code"]' + Reports that bytes from ADDR to DATA + LEN were written in an + inferior. The ID is the identifier of the thread group + corresponding to the affected inferior. The optional 'type="code"' + part is reported if the memory written to holds executable code. + + +File: gdb.info, Node: GDB/MI Breakpoint Information, Next: GDB/MI Frame Information, Prev: GDB/MI Async Records, Up: GDB/MI Output Records + +27.5.4 GDB/MI Breakpoint Information +------------------------------------ + +When GDB reports information about a breakpoint, a tracepoint, a +watchpoint, or a catchpoint, it uses a tuple with the following fields: + +'number' + The breakpoint number. + +'type' + The type of the breakpoint. For ordinary breakpoints this will be + 'breakpoint', but many values are possible. + +'catch-type' + If the type of the breakpoint is 'catchpoint', then this indicates + the exact type of catchpoint. + +'disp' + This is the breakpoint disposition--either 'del', meaning that the + breakpoint will be deleted at the next stop, or 'keep', meaning + that the breakpoint will not be deleted. + +'enabled' + This indicates whether the breakpoint is enabled, in which case the + value is 'y', or disabled, in which case the value is 'n'. Note + that this is not the same as the field 'enable'. + +'addr' + The address of the breakpoint. This may be a hexadecimal number, + giving the address; or the string '', for a pending + breakpoint; or the string '', for a breakpoint with + multiple locations. This field will not be present if no address + can be determined. For example, a watchpoint does not have an + address. + +'addr_flags' + Optional field containing any flags related to the address. These + flags are architecture-dependent; see *note Architectures:: for + their meaning for a particular CPU. + +'func' + If known, the function in which the breakpoint appears. If not + known, this field is not present. + +'filename' + The name of the source file which contains this function, if known. + If not known, this field is not present. + +'fullname' + The full file name of the source file which contains this function, + if known. If not known, this field is not present. + +'line' + The line number at which this breakpoint appears, if known. If not + known, this field is not present. + +'at' + If the source file is not known, this field may be provided. If + provided, this holds the address of the breakpoint, possibly + followed by a symbol name. + +'pending' + If this breakpoint is pending, this field is present and holds the + text used to set the breakpoint, as entered by the user. + +'evaluated-by' + Where this breakpoint's condition is evaluated, either 'host' or + 'target'. + +'thread' + If this is a thread-specific breakpoint, then this identifies the + thread in which the breakpoint can trigger. + +'inferior' + If this is an inferior-specific breakpoint, this this identifies + the inferior in which the breakpoint can trigger. + +'task' + If this breakpoint is restricted to a particular Ada task, then + this field will hold the task identifier. + +'cond' + If the breakpoint is conditional, this is the condition expression. + +'ignore' + The ignore count of the breakpoint. + +'enable' + The enable count of the breakpoint. + +'traceframe-usage' + FIXME. + +'static-tracepoint-marker-string-id' + For a static tracepoint, the name of the static tracepoint marker. + +'mask' + For a masked watchpoint, this is the mask. + +'pass' + A tracepoint's pass count. + +'original-location' + The location of the breakpoint as originally specified by the user. + This field is optional. + +'times' + The number of times the breakpoint has been hit. + +'installed' + This field is only given for tracepoints. This is either 'y', + meaning that the tracepoint is installed, or 'n', meaning that it + is not. + +'what' + Some extra data, the exact contents of which are type-dependent. + +'locations' + This field is present if the breakpoint has multiple locations. It + is also exceptionally present if the breakpoint is enabled and has + a single, disabled location. + + The value is a list of locations. The format of a location is + described below. + + A location in a multi-location breakpoint is represented as a tuple +with the following fields: + +'number' + The location number as a dotted pair, like '1.2'. The first digit + is the number of the parent breakpoint. The second digit is the + number of the location within that breakpoint. + +'enabled' + There are three possible values, with the following meanings: + 'y' + The location is enabled. + 'n' + The location is disabled by the user. + 'N' + The location is disabled because the breakpoint condition is + invalid at this location. + +'addr' + The address of this location as an hexadecimal number. + +'addr_flags' + Optional field containing any flags related to the address. These + flags are architecture-dependent; see *note Architectures:: for + their meaning for a particular CPU. + +'func' + If known, the function in which the location appears. If not + known, this field is not present. + +'file' + The name of the source file which contains this location, if known. + If not known, this field is not present. + +'fullname' + The full file name of the source file which contains this location, + if known. If not known, this field is not present. + +'line' + The line number at which this location appears, if known. If not + known, this field is not present. + +'thread-groups' + The thread groups this location is in. + + For example, here is what the output of '-break-insert' (*note GDB/MI +Breakpoint Commands::) might be: + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + + +File: gdb.info, Node: GDB/MI Frame Information, Next: GDB/MI Thread Information, Prev: GDB/MI Breakpoint Information, Up: GDB/MI Output Records + +27.5.5 GDB/MI Frame Information +------------------------------- + +Response from many MI commands includes an information about stack +frame. This information is a tuple that may have the following fields: + +'level' + The level of the stack frame. The innermost frame has the level of + zero. This field is always present. + +'func' + The name of the function corresponding to the frame. This field + may be absent if GDB is unable to determine the function name. + +'addr' + The code address for the frame. This field is always present. + +'addr_flags' + Optional field containing any flags related to the address. These + flags are architecture-dependent; see *note Architectures:: for + their meaning for a particular CPU. + +'file' + The name of the source files that correspond to the frame's code + address. This field may be absent. + +'line' + The source line corresponding to the frames' code address. This + field may be absent. + +'from' + The name of the binary file (either executable or shared library) + the corresponds to the frame's code address. This field may be + absent. + + +File: gdb.info, Node: GDB/MI Thread Information, Next: GDB/MI Ada Exception Information, Prev: GDB/MI Frame Information, Up: GDB/MI Output Records + +27.5.6 GDB/MI Thread Information +-------------------------------- + +Whenever GDB has to report an information about a thread, it uses a +tuple with the following fields. The fields are always present unless +stated otherwise. + +'id' + The global numeric id assigned to the thread by GDB. + +'target-id' + The target-specific string identifying the thread. + +'details' + Additional information about the thread provided by the target. It + is supposed to be human-readable and not interpreted by the + frontend. This field is optional. + +'name' + The name of the thread. If the user specified a name using the + 'thread name' command, then this name is given. Otherwise, if GDB + can extract the thread name from the target, then that name is + given. If GDB cannot find the thread name, then this field is + omitted. + +'state' + The execution state of the thread, either 'stopped' or 'running', + depending on whether the thread is presently running. + +'frame' + The stack frame currently executing in the thread. This field is + only present if the thread is stopped. Its format is documented in + *note GDB/MI Frame Information::. + +'core' + The value of this field is an integer number of the processor core + the thread was last seen on. This field is optional. + + +File: gdb.info, Node: GDB/MI Ada Exception Information, Prev: GDB/MI Thread Information, Up: GDB/MI Output Records + +27.5.7 GDB/MI Ada Exception Information +--------------------------------------- + +Whenever a '*stopped' record is emitted because the program stopped +after hitting an exception catchpoint (*note Set Catchpoints::), GDB +provides the name of the exception that was raised via the +'exception-name' field. Also, for exceptions that were raised with an +exception message, GDB provides that message via the 'exception-message' +field. + + +File: gdb.info, Node: GDB/MI Simple Examples, Next: GDB/MI Command Description Format, Prev: GDB/MI Output Records, Up: GDB/MI + +27.6 Simple Examples of GDB/MI Interaction +========================================== + +This subsection presents several simple examples of interaction using +the GDB/MI interface. In these examples, '->' means that the following +line is passed to GDB/MI as input, while '<-' means the output received +from GDB/MI. + + Note the line breaks shown in the examples are here only for +readability, they don't appear in the real output. + +Setting a Breakpoint +-------------------- + +Setting a breakpoint generates synchronous output which contains +detailed information of the breakpoint. + + -> -break-insert main + <- ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"} + <- (gdb) + +Program Execution +----------------- + +Program execution generates asynchronous records and MI gives the reason +that execution stopped. + + -> -exec-run + <- ^running + <- (gdb) + <- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x08048564",func="main", + args=[{name="argc",value="1"},{name="argv",value="0xbfc4d4d4"}], + file="myprog.c",fullname="/home/nickrob/myprog.c",line="68", + arch="i386:x86_64"} + <- (gdb) + -> -exec-continue + <- ^running + <- (gdb) + <- *stopped,reason="exited-normally" + <- (gdb) + +Quitting GDB +------------ + +Quitting GDB just prints the result class '^exit'. + + -> (gdb) + <- -gdb-exit + <- ^exit + + Please note that '^exit' is printed immediately, but it might take +some time for GDB to actually exit. During that time, GDB performs +necessary cleanups, including killing programs being debugged or +disconnecting from debug hardware, so the frontend should wait till GDB +exits and should only forcibly kill GDB if it fails to exit in +reasonable time. + +A Bad Command +------------- + +Here's what happens if you pass a non-existent command: + + -> -rubbish + <- ^error,msg="Undefined MI command: rubbish" + <- (gdb) + + +File: gdb.info, Node: GDB/MI Command Description Format, Next: GDB/MI Breakpoint Commands, Prev: GDB/MI Simple Examples, Up: GDB/MI + +27.7 GDB/MI Command Description Format +====================================== + +The remaining sections describe blocks of commands. Each block of +commands is laid out in a fashion similar to this section. + +Motivation +---------- + +The motivation for this collection of commands. + +Introduction +------------ + +A brief introduction to this collection of commands as a whole. + +Commands +-------- + +For each command in the block, the following is described: + +Synopsis +........ + + -command ARGS... + +Result +...... + +GDB Command +........... + +The corresponding GDB CLI command(s), if any. + +Example +....... + +Example(s) formatted for readability. Some of the described commands +have not been implemented yet and these are labeled N.A. (not +available). + + +File: gdb.info, Node: GDB/MI Breakpoint Commands, Next: GDB/MI Catchpoint Commands, Prev: GDB/MI Command Description Format, Up: GDB/MI + +27.8 GDB/MI Breakpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating breakpoints. + +The '-break-after' Command +-------------------------- + +Synopsis +........ + + -break-after NUMBER COUNT + + The breakpoint number NUMBER is not in effect until it has been hit +COUNT times. To see how this is reflected in the output of the +'-break-list' command, see the description of the '-break-list' command +below. + +GDB Command +........... + +The corresponding GDB command is 'ignore'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-after 1 3 + ~ + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-commands' Command +----------------------------- + +Synopsis +........ + + -break-commands NUMBER [ COMMAND1 ... COMMANDN ] + + Specifies the CLI commands that should be executed when breakpoint +NUMBER is hit. The parameters COMMAND1 to COMMANDN are the commands. +If no command is specified, any previously-set commands are cleared. +*Note Break Commands::. Typical use of this functionality is tracing a +program, that is, printing of values of some variables whenever +breakpoint is hit and then continuing. + +GDB Command +........... + +The corresponding GDB command is 'commands'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x000100d0",func="main",file="hello.c", + fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], + times="0"} + (gdb) + -break-commands 1 "print v" "continue" + ^done + (gdb) + +The '-break-condition' Command +------------------------------ + +Synopsis +........ + + -break-condition [ --force ] NUMBER [ EXPR ] + + Breakpoint NUMBER will stop the program only if the condition in EXPR +is true. The condition becomes part of the '-break-list' output (see +the description of the '-break-list' command below). If the '--force' +flag is passed, the condition is forcibly defined even when it is +invalid for all locations of breakpoint NUMBER. If the EXPR argument is +omitted, breakpoint NUMBER becomes unconditional. + +GDB Command +........... + +The corresponding GDB command is 'condition'. + +Example +....... + + (gdb) + -break-condition 1 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"}]} + (gdb) + +The '-break-delete' Command +--------------------------- + +Synopsis +........ + + -break-delete ( BREAKPOINT )+ + + Delete the breakpoint(s) whose number(s) are specified in the +argument list. This is obviously reflected in the breakpoint list. + +GDB Command +........... + +The corresponding GDB command is 'delete'. + +Example +....... + + (gdb) + -break-delete 1 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-disable' Command +---------------------------- + +Synopsis +........ + + -break-disable ( BREAKPOINT )+ + + Disable the named BREAKPOINT(s). The field 'enabled' in the break +list is now set to 'n' for the named BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'disable'. + +Example +....... + + (gdb) + -break-disable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="n", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-enable' Command +--------------------------- + +Synopsis +........ + + -break-enable ( BREAKPOINT )+ + + Enable (previously disabled) BREAKPOINT(s). + +GDB Command +........... + +The corresponding GDB command is 'enable'. + +Example +....... + + (gdb) + -break-enable 2 + ^done + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", + line="5",thread-groups=["i1"],times="0"}]} + (gdb) + +The '-break-info' Command +------------------------- + +Synopsis +........ + + -break-info BREAKPOINT + + Get information about a single breakpoint. + + The result is a table of breakpoints. *Note GDB/MI Breakpoint +Information::, for details on the format of each breakpoint in the +table. + +GDB Command +........... + +The corresponding GDB command is 'info break BREAKPOINT'. + +Example +....... + +N.A. + +The '-break-insert' Command +--------------------------- + +Synopsis +........ + + -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ] + [ -c CONDITION ] [ --force-condition ] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ -g THREAD-GROUP-ID ] [ LOCSPEC ] + +If specified, LOCSPEC, can be one of: + +LINESPEC LOCATION + A linespec location. *Note Linespec Locations::. + +EXPLICIT LOCATION + An explicit location. GDB/MI explicit locations are analogous to + the CLI's explicit locations using the option names listed below. + *Note Explicit Locations::. + + '--source FILENAME' + The source file name of the location. This option requires + the use of either '--function' or '--line'. + + '--function FUNCTION' + The name of a function or method. + + '--label LABEL' + The name of a label. + + '--line LINEOFFSET' + An absolute or relative line offset from the start of the + location. + +ADDRESS LOCATION + An address location, *ADDRESS. *Note Address Locations::. + +The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-h' + Insert a hardware breakpoint. +'-f' + If LOCSPEC cannot be resolved (for example if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCSPEC cannot be parsed. +'-d' + Create a disabled breakpoint. +'-a' + Create a tracepoint. *Note Tracepoints::. When this parameter is + used together with '-h', a fast tracepoint is created. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'--force-condition' + Forcibly define the breakpoint even if the condition is invalid at + all of the breakpoint locations. +'-i IGNORE-COUNT' + Initialize the IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the thread with the specified global + THREAD-ID. THREAD-ID must be a valid thread-id at the time the + breakpoint is requested. Breakpoints created with a THREAD-ID will + automatically be deleted when the corresponding thread exits. +'-g THREAD-GROUP-ID' + Restrict the breakpoint to the thread group with the specified + THREAD-GROUP-ID. +'--qualified' + This option makes GDB interpret a function name specified as a + complete fully-qualified name. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + + Note: this format is open to change. + +GDB Command +........... + +The corresponding GDB commands are 'break', 'tbreak', 'hbreak', and +'thbreak'. + +Example +....... + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], + times="0"} + (gdb) + -break-insert -t foo + ^done,bkpt={number="2",addr="0x00010774",file="recursive2.c", + fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], + times="0"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x0001072c", func="main",file="recursive2.c", + fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="del",enabled="y", + addr="0x00010774",func="foo",file="recursive2.c", + fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], + times="0"}]} + (gdb) + +The '-dprintf-insert' Command +----------------------------- + +Synopsis +........ + + -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ] + [ -c CONDITION ] [--force-condition] [ -i IGNORE-COUNT ] + [ -p THREAD-ID ] [ LOCSPEC ] FORMAT + [ ARGUMENT... ] + +Insert a new dynamic print breakpoint at the given location. *Note +Dynamic Printf::. FORMAT is the format to use, and any remaining +arguments are passed as expressions to substitute. + +If supplied, LOCSPEC and '--qualified' may be specified the same way as +for the '-break-insert' command. *Note -break-insert::. + + The possible optional parameters of this command are: + +'-t' + Insert a temporary breakpoint. +'-f' + If LOCSPEC cannot be parsed (for example, if it refers to unknown + files or functions), create a pending breakpoint. Without this + flag, GDB will report an error, and won't create a breakpoint, if + LOCSPEC cannot be parsed. +'-d' + Create a disabled breakpoint. +'-c CONDITION' + Make the breakpoint conditional on CONDITION. +'--force-condition' + Forcibly define the breakpoint even if the condition is invalid at + all of the breakpoint locations. +'-i IGNORE-COUNT' + Set the ignore count of the breakpoint (*note ignore count: + Conditions.) to IGNORE-COUNT. +'-p THREAD-ID' + Restrict the breakpoint to the thread with the specified global + THREAD-ID. + +Result +...... + +*Note GDB/MI Breakpoint Information::, for details on the format of the +resulting breakpoint. + +GDB Command +........... + +The corresponding GDB command is 'dprintf'. + +Example +....... + + (gdb) + 4-dprintf-insert foo "At foo entry\n" + 4^done,bkpt={number="1",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040061b",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="25",thread-groups=["i1"], + times="0",script=["printf \"At foo entry\\n\"","continue"], + original-location="foo"} + (gdb) + 5-dprintf-insert 26 "arg=%d, g=%d\n" arg g + 5^done,bkpt={number="2",type="dprintf",disp="keep",enabled="y", + addr="0x000000000040062a",func="foo",file="mi-dprintf.c", + fullname="mi-dprintf.c",line="26",thread-groups=["i1"], + times="0",script=["printf \"arg=%d, g=%d\\n\", arg, g","continue"], + original-location="mi-dprintf.c:26"} + (gdb) + +The '-break-list' Command +------------------------- + +Synopsis +........ + + -break-list + + Displays the list of inserted breakpoints, showing the following +fields: + +'Number' + number of the breakpoint +'Type' + type of the breakpoint: 'breakpoint' or 'watchpoint' +'Disposition' + should the breakpoint be deleted or disabled when it is hit: 'keep' + or 'nokeep' +'Enabled' + is the breakpoint enabled or no: 'y' or 'n' +'Address' + memory location at which the breakpoint is set +'What' + logical location of the breakpoint, expressed by function name, + file name, line number +'Thread-groups' + list of thread groups to which this breakpoint applies +'Times' + number of times the breakpoint has been hit + + If there are no breakpoints, watchpoints, tracepoints, or +catchpoints, the 'BreakpointTable' 'body' field is an empty list. + +GDB Command +........... + +The corresponding GDB command is 'info break'. + +Example +....... + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], + times="0"}, + bkpt={number="2",type="breakpoint",disp="keep",enabled="y", + addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", + line="13",thread-groups=["i1"],times="0"}]} + (gdb) + + Here's an example of the result when there are no breakpoints: + + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="0",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[]} + (gdb) + +The '-break-passcount' Command +------------------------------ + +Synopsis +........ + + -break-passcount TRACEPOINT-NUMBER PASSCOUNT + + Set the passcount for tracepoint TRACEPOINT-NUMBER to PASSCOUNT. If +the breakpoint referred to by TRACEPOINT-NUMBER is not a tracepoint, +error is emitted. This corresponds to CLI command 'passcount'. + +The '-break-watch' Command +-------------------------- + +Synopsis +........ + + -break-watch [ -a | -r ] + + Create a watchpoint. With the '-a' option it will create an "access" +watchpoint, i.e., a watchpoint that triggers either on a read from or on +a write to the memory location. With the '-r' option, the watchpoint +created is a "read" watchpoint, i.e., it will trigger only when the +memory location is accessed for reading. Without either of the options, +the watchpoint created is a regular watchpoint, i.e., it will trigger +when the memory location is accessed for writing. *Note Setting +Watchpoints: Set Watchpoints. + + Note that '-break-list' will report a single list of watchpoints and +breakpoints inserted. + +GDB Command +........... + +The corresponding GDB commands are 'watch', 'awatch', and 'rwatch'. + +Example +....... + +Setting a watchpoint on a variable in the 'main' function: + + (gdb) + -break-watch x + ^done,wpt={number="2",exp="x"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="x"}, + value={old="-268439212",new="55"}, + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"} + (gdb) + + Setting a watchpoint on a variable local to a function. GDB will +stop the program execution twice: first for the variable changing value, +then for the watchpoint going out of scope. + + (gdb) + -break-watch C + ^done,wpt={number="5",exp="C"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger", + wpt={number="5",exp="C"},value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", + arch="i386:x86_64"} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-scope",wpnum="5", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", + arch="i386:x86_64"} + (gdb) + + Listing breakpoints and watchpoints, at different points in the +program execution. Note that once the watchpoint goes out of scope, it +is deleted. + + (gdb) + -break-watch C + ^done,wpt={number="2",exp="C"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="0"}]} + (gdb) + -exec-continue + ^running + (gdb) + *stopped,reason="watchpoint-trigger",wpt={number="2",exp="C"}, + value={old="-276895068",new="3"}, + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", + arch="i386:x86_64"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="2",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], + times="1"}, + bkpt={number="2",type="watchpoint",disp="keep", + enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"}]} + (gdb) + -exec-continue + ^running + ^done,reason="watchpoint-scope",wpnum="2", + frame={func="callee3",args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", + arch="i386:x86_64"} + (gdb) + -break-list + ^done,BreakpointTable={nr_rows="1",nr_cols="6", + hdr=[{width="3",alignment="-1",col_name="number",colhdr="Num"}, + {width="14",alignment="-1",col_name="type",colhdr="Type"}, + {width="4",alignment="-1",col_name="disp",colhdr="Disp"}, + {width="3",alignment="-1",col_name="enabled",colhdr="Enb"}, + {width="10",alignment="-1",col_name="addr",colhdr="Address"}, + {width="40",alignment="2",col_name="what",colhdr="What"}], + body=[bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", + thread-groups=["i1"],times="1"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Catchpoint Commands, Next: GDB/MI Program Context, Prev: GDB/MI Breakpoint Commands, Up: GDB/MI + +27.9 GDB/MI Catchpoint Commands +=============================== + +This section documents GDB/MI commands for manipulating catchpoints. + +* Menu: + +* Shared Library GDB/MI Catchpoint Commands:: +* Ada Exception GDB/MI Catchpoint Commands:: +* C++ Exception GDB/MI Catchpoint Commands:: + + +File: gdb.info, Node: Shared Library GDB/MI Catchpoint Commands, Next: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.1 Shared Library GDB/MI Catchpoints +---------------------------------------- + +The '-catch-load' Command +------------------------- + +Synopsis +........ + + -catch-load [ -t ] [ -d ] REGEXP + + Add a catchpoint for library load events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the loaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch load'. + +Example +....... + + -catch-load -t foo.so + ^done,bkpt={number="1",type="catchpoint",disp="del",enabled="y", + what="load of library matching foo.so",catch-type="load",times="0"} + (gdb) + +The '-catch-unload' Command +--------------------------- + +Synopsis +........ + + -catch-unload [ -t ] [ -d ] REGEXP + + Add a catchpoint for library unload events. If the '-t' option is +used, the catchpoint is a temporary one (*note Setting Breakpoints: Set +Breaks.). If the '-d' option is used, the catchpoint is created in a +disabled state. The 'regexp' argument is a regular expression used to +match the name of the unloaded library. + +GDB Command +........... + +The corresponding GDB command is 'catch unload'. + +Example +....... + + -catch-unload -d bar.so + ^done,bkpt={number="2",type="catchpoint",disp="keep",enabled="n", + what="load of library matching bar.so",catch-type="unload",times="0"} + (gdb) + + +File: gdb.info, Node: Ada Exception GDB/MI Catchpoint Commands, Next: C++ Exception GDB/MI Catchpoint Commands, Prev: Shared Library GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.2 Ada Exception GDB/MI Catchpoints +--------------------------------------- + +The following GDB/MI commands can be used to create catchpoints that +stop the execution when Ada exceptions are being raised. + +The '-catch-assert' Command +--------------------------- + +Synopsis +........ + + -catch-assert [ -c CONDITION] [ -d ] [ -t ] + + Add a catchpoint for failed Ada assertions. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-t' + Create a temporary catchpoint. + +GDB Command +........... + +The corresponding GDB command is 'catch assert'. + +Example +....... + + -catch-assert + ^done,bkptno="5",bkpt={number="5",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404888",what="failed Ada assertions", + thread-groups=["i1"],times="0", + original-location="__gnat_debug_raise_assert_failure"} + (gdb) + +The '-catch-exception' Command +------------------------------ + +Synopsis +........ + + -catch-exception [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] + [ -t ] [ -u ] + + Add a catchpoint stopping when Ada exceptions are raised. By +default, the command stops the program when any Ada exception gets +raised. But it is also possible, by using some of the optional +parameters described below, to create more selective catchpoints. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-e EXCEPTION-NAME' + Only stop when EXCEPTION-NAME is raised. This option cannot be + used combined with '-u'. +'-t' + Create a temporary catchpoint. +'-u' + Stop only when an unhandled exception gets raised. This option + cannot be used combined with '-e'. + +GDB Command +........... + +The corresponding GDB commands are 'catch exception' and 'catch +exception unhandled'. + +Example +....... + + -catch-exception -e Program_Error + ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000404874", + what="`Program_Error' Ada exception", thread-groups=["i1"], + times="0",original-location="__gnat_debug_raise_exception"} + (gdb) + +The '-catch-handlers' Command +----------------------------- + +Synopsis +........ + + -catch-handlers [ -c CONDITION] [ -d ] [ -e EXCEPTION-NAME ] + [ -t ] + + Add a catchpoint stopping when Ada exceptions are handled. By +default, the command stops the program when any Ada exception gets +handled. But it is also possible, by using some of the optional +parameters described below, to create more selective catchpoints. + + The possible optional parameters for this command are: + +'-c CONDITION' + Make the catchpoint conditional on CONDITION. +'-d' + Create a disabled catchpoint. +'-e EXCEPTION-NAME' + Only stop when EXCEPTION-NAME is handled. +'-t' + Create a temporary catchpoint. + +GDB Command +........... + +The corresponding GDB command is 'catch handlers'. + +Example +....... + + -catch-handlers -e Constraint_Error + ^done,bkptno="4",bkpt={number="4",type="breakpoint",disp="keep", + enabled="y",addr="0x0000000000402f68", + what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"], + times="0",original-location="__gnat_begin_handler"} + (gdb) + + +File: gdb.info, Node: C++ Exception GDB/MI Catchpoint Commands, Prev: Ada Exception GDB/MI Catchpoint Commands, Up: GDB/MI Catchpoint Commands + +27.9.3 C++ Exception GDB/MI Catchpoints +--------------------------------------- + +The following GDB/MI commands can be used to create catchpoints that +stop the execution when C++ exceptions are being throw, rethrown, or +caught. + +The '-catch-throw' Command +-------------------------- + +Synopsis +........ + + -catch-throw [ -t ] [ -r REGEXP] + + Stop when the debuggee throws a C++ exception. If REGEXP is given, +then only exceptions whose type matches the regular expression will be +caught. + + If '-t' is given, then the catchpoint is enabled only for one stop, +the catchpoint is automatically deleted after stopping once for the +event. + +GDB Command +........... + +The corresponding GDB commands are 'catch throw' and 'tcatch throw' +(*note Set Catchpoints::). + +Example +....... + + -catch-throw -r exception_type + ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", + what="exception throw",catch-type="throw", + thread-groups=["i1"], + regexp="exception_type",times="0"} + (gdb) + -exec-run + ^running + (gdb) + ~"\n" + ~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed + in __cxa_throw () from /lib64/libstdc++.so.6\n" + *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame={addr="0x00007ffff7ae00ed",func="__cxa_throw", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, + thread-id="1",stopped-threads="all",core="6" + (gdb) + +The '-catch-rethrow' Command +---------------------------- + +Synopsis +........ + + -catch-rethrow [ -t ] [ -r REGEXP] + + Stop when a C++ exception is re-thrown. If REGEXP is given, then +only exceptions whose type matches the regular expression will be +caught. + + If '-t' is given, then the catchpoint is enabled only for one stop, +the catchpoint is automatically deleted after the first event is caught. + +GDB Command +........... + +The corresponding GDB commands are 'catch rethrow' and 'tcatch rethrow' +(*note Set Catchpoints::). + +Example +....... + + -catch-rethrow -r exception_type + ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", + what="exception rethrow",catch-type="rethrow", + thread-groups=["i1"], + regexp="exception_type",times="0"} + (gdb) + -exec-run + ^running + (gdb) + ~"\n" + ~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed + in __cxa_rethrow () from /lib64/libstdc++.so.6\n" + *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame={addr="0x00007ffff7ae00ed",func="__cxa_rethrow", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, + thread-id="1",stopped-threads="all",core="6" + (gdb) + +The '-catch-catch' Command +-------------------------- + +Synopsis +........ + + -catch-catch [ -t ] [ -r REGEXP] + + Stop when the debuggee catches a C++ exception. If REGEXP is given, +then only exceptions whose type matches the regular expression will be +caught. + + If '-t' is given, then the catchpoint is enabled only for one stop, +the catchpoint is automatically deleted after the first event is caught. + +GDB Command +........... + +The corresponding GDB commands are 'catch catch' and 'tcatch catch' +(*note Set Catchpoints::). + +Example +....... + + -catch-catch -r exception_type + ^done,bkpt={number="1",type="catchpoint",disp="keep",enabled="y", + what="exception catch",catch-type="catch", + thread-groups=["i1"], + regexp="exception_type",times="0"} + (gdb) + -exec-run + ^running + (gdb) + ~"\n" + ~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed + in __cxa_begin_catch () from /lib64/libstdc++.so.6\n" + *stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame={addr="0x00007ffff7ae00ed",func="__cxa_begin_catch", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"}, + thread-id="1",stopped-threads="all",core="6" + (gdb) + + +File: gdb.info, Node: GDB/MI Program Context, Next: GDB/MI Thread Commands, Prev: GDB/MI Catchpoint Commands, Up: GDB/MI + +27.10 GDB/MI Program Context +============================ + +The '-exec-arguments' Command +----------------------------- + +Synopsis +........ + + -exec-arguments ARGS + + Set the inferior program arguments, to be used in the next +'-exec-run'. + +GDB Command +........... + +The corresponding GDB command is 'set args'. + +Example +....... + + (gdb) + -exec-arguments -v word + ^done + (gdb) + +The '-environment-cd' Command +----------------------------- + +Synopsis +........ + + -environment-cd PATHDIR + + Set GDB's working directory. + +GDB Command +........... + +The corresponding GDB command is 'cd'. + +Example +....... + + (gdb) + -environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done + (gdb) + +The '-environment-directory' Command +------------------------------------ + +Synopsis +........ + + -environment-directory [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for source files. +If the '-r' option is used, the search path is reset to the default +search path. If directories PATHDIR are supplied in addition to the +'-r' option, the search path is first reset and then addition occurs as +normal. Multiple directories may be specified, separated by blanks. +Specifying multiple directories in a single command results in the +directories added to the beginning of the search path in the same order +they were presented in the command. If blanks are needed as part of a +directory name, double-quotes should be used around the name. In the +command output, the path will show up separated by the system +directory-separator character. The directory-separator character must +not be used in any directory name. If no directories are specified, the +current search path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'dir'. + +Example +....... + + (gdb) + -environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory "" + ^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" + (gdb) + -environment-directory -r /home/jjohnstn/src/gdb /usr/src + ^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" + (gdb) + -environment-directory -r + ^done,source-path="$cdir:$cwd" + (gdb) + +The '-environment-path' Command +------------------------------- + +Synopsis +........ + + -environment-path [ -r ] [ PATHDIR ]+ + + Add directories PATHDIR to beginning of search path for object files. +If the '-r' option is used, the search path is reset to the original +search path that existed at gdb start-up. If directories PATHDIR are +supplied in addition to the '-r' option, the search path is first reset +and then addition occurs as normal. Multiple directories may be +specified, separated by blanks. Specifying multiple directories in a +single command results in the directories added to the beginning of the +search path in the same order they were presented in the command. If +blanks are needed as part of a directory name, double-quotes should be +used around the name. In the command output, the path will show up +separated by the system directory-separator character. The +directory-separator character must not be used in any directory name. +If no directories are specified, the current path is displayed. + +GDB Command +........... + +The corresponding GDB command is 'path'. + +Example +....... + + (gdb) + -environment-path + ^done,path="/usr/bin" + (gdb) + -environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin + ^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" + (gdb) + -environment-path -r /usr/local/bin + ^done,path="/usr/local/bin:/usr/bin" + (gdb) + +The '-environment-pwd' Command +------------------------------ + +Synopsis +........ + + -environment-pwd + + Show the current working directory. + +GDB Command +........... + +The corresponding GDB command is 'pwd'. + +Example +....... + + (gdb) + -environment-pwd + ^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" + (gdb) + + +File: gdb.info, Node: GDB/MI Thread Commands, Next: GDB/MI Ada Tasking Commands, Prev: GDB/MI Program Context, Up: GDB/MI + +27.11 GDB/MI Thread Commands +============================ + +The '-thread-info' Command +-------------------------- + +Synopsis +........ + + -thread-info [ THREAD-ID ] + + Reports information about either a specific thread, if the THREAD-ID +parameter is present, or about all threads. THREAD-ID is the thread's +global thread ID. When printing information about all threads, also +reports the global ID of the current thread. + +GDB Command +........... + +The 'info thread' command prints the same information about all threads. + +Result +...... + +The result contains the following attributes: + +'threads' + A list of threads. The format of the elements of the list is + described in *note GDB/MI Thread Information::. + +'current-thread-id' + The global id of the currently selected thread. This field is + omitted if there is no selected thread (for example, when the + selected inferior is not running, and therefore has no threads) or + if a THREAD-ID argument was passed to the command. + +Example +....... + + -thread-info + ^done,threads=[ + {id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall", + args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo", + args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"}, + state="running"}], + current-thread-id="1" + (gdb) + +The '-thread-list-ids' Command +------------------------------ + +Synopsis +........ + + -thread-list-ids + + Produces a list of the currently known global GDB thread ids. At the +end of the list it also prints the total number of such threads. + + This command is retained for historical reasons, the '-thread-info' +command should be used instead. + +GDB Command +........... + +Part of 'info threads' supplies the same information. + +Example +....... + + (gdb) + -thread-list-ids + ^done,thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + current-thread-id="1",number-of-threads="3" + (gdb) + +The '-thread-select' Command +---------------------------- + +Synopsis +........ + + -thread-select THREAD-ID + + Make thread with global thread number THREAD-ID the current thread. +It prints the number of the new current thread, and the topmost frame +for that thread. + + This command is deprecated in favor of explicitly using the +'--thread' option to each command. + +GDB Command +........... + +The corresponding GDB command is 'thread'. + +Example +....... + + (gdb) + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",thread-id="2",line="187", + file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" + (gdb) + -thread-list-ids + ^done, + thread-ids={thread-id="3",thread-id="2",thread-id="1"}, + number-of-threads="3" + (gdb) + -thread-select 3 + ^done,new-thread-id="3", + frame={level="0",func="vprintf", + args=[{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""}, + {name="arg",value="0x2"}],file="vprintf.c",line="31",arch="i386:x86_64"} + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Tasking Commands, Next: GDB/MI Program Execution, Prev: GDB/MI Thread Commands, Up: GDB/MI + +27.12 GDB/MI Ada Tasking Commands +================================= + +The '-ada-task-info' Command +---------------------------- + +Synopsis +........ + + -ada-task-info [ TASK-ID ] + + Reports information about either a specific Ada task, if the TASK-ID +parameter is present, or about all Ada tasks. + +GDB Command +........... + +The 'info tasks' command prints the same information about all Ada tasks +(*note Ada Tasks::). + +Result +...... + +The result is a table of Ada tasks. The following columns are defined +for each Ada task: + +'current' + This field exists only for the current thread. It has the value + '*'. + +'id' + The identifier that GDB uses to refer to the Ada task. + +'task-id' + The identifier that the target uses to refer to the Ada task. + +'thread-id' + The global thread identifier of the thread corresponding to the Ada + task. + + This field should always exist, as Ada tasks are always implemented + on top of a thread. But if GDB cannot find this corresponding + thread for any reason, the field is omitted. + +'parent-id' + This field exists only when the task was created by another task. + In this case, it provides the ID of the parent task. + +'priority' + The base priority of the task. + +'state' + The current state of the task. For a detailed description of the + possible states, see *note Ada Tasks::. + +'name' + The name of the task. + +Example +....... + + -ada-task-info + ^done,tasks={nr_rows="3",nr_cols="8", + hdr=[{width="1",alignment="-1",col_name="current",colhdr=""}, + {width="3",alignment="1",col_name="id",colhdr="ID"}, + {width="9",alignment="1",col_name="task-id",colhdr="TID"}, + {width="4",alignment="1",col_name="thread-id",colhdr=""}, + {width="4",alignment="1",col_name="parent-id",colhdr="P-ID"}, + {width="3",alignment="1",col_name="priority",colhdr="Pri"}, + {width="22",alignment="-1",col_name="state",colhdr="State"}, + {width="1",alignment="2",col_name="name",colhdr="Name"}], + body=[{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", + state="Child Termination Wait",name="main_task"}]} + (gdb) + + +File: gdb.info, Node: GDB/MI Program Execution, Next: GDB/MI Stack Manipulation, Prev: GDB/MI Ada Tasking Commands, Up: GDB/MI + +27.13 GDB/MI Program Execution +============================== + +These are the asynchronous commands which generate the out-of-band +record '*stopped'. Currently GDB only really executes asynchronously +with remote targets and this interaction is mimicked in other cases. + +The '-exec-continue' Command +---------------------------- + +Synopsis +........ + + -exec-continue [--reverse] [--all|--thread-group N] + + Resumes the execution of the inferior program, which will continue to +execute until it reaches a debugger stop event. If the '--reverse' +option is specified, execution resumes in reverse until it reaches a +stop event. Stop events may include + * breakpoints, watchpoints, tracepoints, or catchpoints + * signals or exceptions + * the end of the process (or its beginning under '--reverse') + * the end or beginning of a replay log if one is being used. + In all-stop mode (*note All-Stop Mode::), may resume only one thread, +or all threads, depending on the value of the 'scheduler-locking' +variable. If '--all' is specified, all threads (in all inferiors) will +be resumed. The '--all' option is ignored in all-stop mode. If the +'--thread-group' options is specified, then all threads in that thread +group are resumed. + +GDB Command +........... + +The corresponding GDB corresponding is 'continue'. + +Example +....... + + -exec-continue + ^running + (gdb) + @Hello world + *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame={ + func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", + line="13",arch="i386:x86_64"} + (gdb) + + For a 'breakpoint-hit' stopped reason, when the breakpoint +encountered has multiple locations, the field 'bkptno' is followed by +the field 'locno'. + + -exec-continue + ^running + (gdb) + @Hello world + *stopped,reason="breakpoint-hit",disp="keep",bkptno="2",locno="3",frame={ + func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", + line="13",arch="i386:x86_64"} + (gdb) + +The '-exec-finish' Command +-------------------------- + +Synopsis +........ + + -exec-finish [--reverse] + + Resumes the execution of the inferior program until the current +function is exited. Displays the results returned by the function. If +the '--reverse' option is specified, resumes the reverse execution of +the inferior program until the point where current function was called. + +GDB Command +........... + +The corresponding GDB command is 'finish'. + +Example +....... + +Function returning 'void'. + + -exec-finish + ^running + (gdb) + @hello from foo + *stopped,reason="function-finished",frame={func="main",args=[], + file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"} + (gdb) + + Function returning other than 'void'. The name of the internal GDB +variable storing the result is printed, together with the value itself. + + -exec-finish + ^running + (gdb) + *stopped,reason="function-finished",frame={addr="0x000107b0",func="foo", + args=[{name="a",value="1"],{name="b",value="9"}}, + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + gdb-result-var="$1",return-value="0" + (gdb) + +The '-exec-interrupt' Command +----------------------------- + +Synopsis +........ + + -exec-interrupt [--all|--thread-group N] + + Interrupts the background execution of the target. Note how the +token associated with the stop message is the one for the execution +command that has been interrupted. The token for the interrupt itself +only appears in the '^done' output. If the user is trying to interrupt +a non-running program, an error message will be printed. + + Note that when asynchronous execution is enabled, this command is +asynchronous just like other execution commands. That is, first the +'^done' response will be printed, and the target stop will be reported +after that using the '*stopped' notification. + + In non-stop mode, only the context thread is interrupted by default. +All threads (in all inferiors) will be interrupted if the '--all' option +is specified. If the '--thread-group' option is specified, all threads +in that group will be interrupted. + +GDB Command +........... + +The corresponding GDB command is 'interrupt'. + +Example +....... + + (gdb) + 111-exec-continue + 111^running + + (gdb) + 222-exec-interrupt + 222^done + (gdb) + 111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", + frame={addr="0x00010140",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"} + (gdb) + + (gdb) + -exec-interrupt + ^error,msg="mi_cmd_exec_interrupt: Inferior not executing." + (gdb) + +The '-exec-jump' Command +------------------------ + +Synopsis +........ + + -exec-jump LOCSPEC + + Resumes execution of the inferior program at the address to which +LOCSPEC resolves. *Note Location Specifications::, for a description of +the different forms of LOCSPEC. + +GDB Command +........... + +The corresponding GDB command is 'jump'. + +Example +....... + + -exec-jump foo.c:10 + *running,thread-id="all" + ^running + +The '-exec-next' Command +------------------------ + +Synopsis +........ + + -exec-next [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the beginning of the previous source +line. If you issue this command on the first line of a function, it +will take you back to the caller of that function, to the source line +where the function was called. + +GDB Command +........... + +The corresponding GDB command is 'next'. + +Example +....... + + -exec-next + ^running + (gdb) + *stopped,reason="end-stepping-range",line="8",file="hello.c" + (gdb) + +The '-exec-next-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-next-instruction [--reverse] + + Executes one machine instruction. If the instruction is a function +call, continues until the function returns. If the program stops at an +instruction in the middle of a source line, the address will be printed +as well. + + If the '--reverse' option is specified, resumes reverse execution of +the inferior program, stopping at the previous instruction. If the +previously executed instruction was a return from another function, it +will continue to execute in reverse until the call to that function +(from the current stack frame) is reached. + +GDB Command +........... + +The corresponding GDB command is 'nexti'. + +Example +....... + + (gdb) + -exec-next-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + addr="0x000100d4",line="5",file="hello.c" + (gdb) + +The '-exec-return' Command +-------------------------- + +Synopsis +........ + + -exec-return + + Makes current function return immediately. Doesn't execute the +inferior. Displays the new current frame. + +GDB Command +........... + +The corresponding GDB command is 'return'. + +Example +....... + + (gdb) + 200-break-insert callee4 + 200^done,bkpt={number="1",addr="0x00010734", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"} + (gdb) + 000-exec-run + 000^running + (gdb) + 000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="callee4",args=[], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", + arch="i386:x86_64"} + (gdb) + 205-break-delete + 205^done + (gdb) + 111-exec-return + 111^done,frame={level="0",func="callee3", + args=[{name="strarg", + value="0x11940 \"A string argument.\""}], + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", + arch="i386:x86_64"} + (gdb) + +The '-exec-run' Command +----------------------- + +Synopsis +........ + + -exec-run [ --all | --thread-group N ] [ --start ] + + Starts execution of the inferior from the beginning. The inferior +executes until either a breakpoint is encountered or the program exits. +In the latter case the output will include an exit code, if the program +has exited exceptionally. + + When neither the '--all' nor the '--thread-group' option is +specified, the current inferior is started. If the '--thread-group' +option is specified, it should refer to a thread group of type +'process', and that thread group will be started. If the '--all' option +is specified, then all inferiors will be started. + + Using the '--start' option instructs the debugger to stop the +execution at the start of the inferior's main subprogram, following the +same behavior as the 'start' command (*note Starting::). + +GDB Command +........... + +The corresponding GDB command is 'run'. + +Examples +........ + + (gdb) + -break-insert main + ^done,bkpt={number="1",addr="0x0001072c",file="recursive2.c",line="4"} + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1", + frame={func="main",args=[],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"} + (gdb) + +Program exited normally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited-normally" + (gdb) + +Program exited exceptionally: + + (gdb) + -exec-run + ^running + (gdb) + x = 55 + *stopped,reason="exited",exit-code="01" + (gdb) + + Another way the program can terminate is if it receives a signal such +as 'SIGINT'. In this case, GDB/MI displays this: + + (gdb) + *stopped,reason="exited-signalled",signal-name="SIGINT", + signal-meaning="Interrupt" + +The '-exec-step' Command +------------------------ + +Synopsis +........ + + -exec-step [--reverse] + + Resumes execution of the inferior program, stopping when the +beginning of the next source line is reached, if the next source line is +not a function call. If it is, stop at the first instruction of the +called function. If the '--reverse' option is specified, resumes +reverse execution of the inferior program, stopping at the beginning of +the previously executed source line. + +GDB Command +........... + +The corresponding GDB command is 'step'. + +Example +....... + +Stepping into a function: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[{name="a",value="10"}, + {name="b",value="0"}],file="recursive2.c", + fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"} + (gdb) + + Regular stepping: + + -exec-step + ^running + (gdb) + *stopped,reason="end-stepping-range",line="14",file="recursive2.c" + (gdb) + +The '-exec-step-instruction' Command +------------------------------------ + +Synopsis +........ + + -exec-step-instruction [--reverse] + + Resumes the inferior which executes one machine instruction. If the +'--reverse' option is specified, resumes reverse execution of the +inferior program, stopping at the previously executed instruction. The +output, once GDB has stopped, will vary depending on whether we have +stopped in the middle of a source line or not. In the former case, the +address at which the program stopped will be printed as well. + +GDB Command +........... + +The corresponding GDB command is 'stepi'. + +Example +....... + + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"} + (gdb) + -exec-step-instruction + ^running + + (gdb) + *stopped,reason="end-stepping-range", + frame={addr="0x000100f4",func="foo",args=[],file="try.c", + fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"} + (gdb) + +The '-exec-until' Command +------------------------- + +Synopsis +........ + + -exec-until [ LOCSPEC ] + + Executes the inferior until it reaches the address to which LOCSPEC +resolves. If there is no argument, the inferior executes until it +reaches a source line greater than the current one. The reason for +stopping in this case will be 'location-reached'. + +GDB Command +........... + +The corresponding GDB command is 'until'. + +Example +....... + + (gdb) + -exec-until recursive2.c:6 + ^running + (gdb) + x = 55 + *stopped,reason="location-reached",frame={func="main",args=[], + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6", + arch="i386:x86_64"} + (gdb) + + +File: gdb.info, Node: GDB/MI Stack Manipulation, Next: GDB/MI Variable Objects, Prev: GDB/MI Program Execution, Up: GDB/MI + +27.14 GDB/MI Stack Manipulation Commands +======================================== + +The '-enable-frame-filters' Command +----------------------------------- + + -enable-frame-filters + + GDB allows Python-based frame filters to affect the output of the MI +commands relating to stack traces. As there is no way to implement this +in a fully backward-compatible way, a front end must request that this +functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + +The '-stack-info-frame' Command +------------------------------- + +Synopsis +........ + + -stack-info-frame + + Get info on the selected frame. + +GDB Command +........... + +The corresponding GDB command is 'info frame' or 'frame' (without +arguments). + +Example +....... + + (gdb) + -stack-info-frame + ^done,frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", + arch="i386:x86_64"} + (gdb) + +The '-stack-info-depth' Command +------------------------------- + +Synopsis +........ + + -stack-info-depth [ MAX-DEPTH ] + + Return the depth of the stack. If the integer argument MAX-DEPTH is +specified, do not count beyond MAX-DEPTH frames. + +GDB Command +........... + +There's no equivalent GDB command. + +Example +....... + +For a stack with frame levels 0 through 11: + + (gdb) + -stack-info-depth + ^done,depth="12" + (gdb) + -stack-info-depth 4 + ^done,depth="4" + (gdb) + -stack-info-depth 12 + ^done,depth="12" + (gdb) + -stack-info-depth 11 + ^done,depth="11" + (gdb) + -stack-info-depth 13 + ^done,depth="12" + (gdb) + +The '-stack-list-arguments' Command +----------------------------------- + +Synopsis +........ + + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + [ LOW-FRAME HIGH-FRAME ] + + Display a list of the arguments for the frames between LOW-FRAME and +HIGH-FRAME (inclusive). If LOW-FRAME and HIGH-FRAME are not provided, +list the arguments for the whole call stack. If the two arguments are +equal, show the single frame at the corresponding level. It is an error +if LOW-FRAME is larger than the actual number of frames. On the other +hand, HIGH-FRAME may be larger than the actual number of frames, in +which case only existing frames will be returned. + + If PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. If +the option '--no-frame-filters' is supplied, then Python frame filters +will not be executed. + + If the '--skip-unavailable' option is specified, arguments that are +not available are not listed. Partially available arguments are still +displayed, however. + + Use of this command to obtain arguments in a single frame is +deprecated in favor of the '-stack-list-variables' command. + +GDB Command +........... + +GDB does not have an equivalent command. 'gdbtk' has a 'gdb_get_args' +command which partially overlaps with the functionality of +'-stack-list-arguments'. + +Example +....... + + (gdb) + -stack-list-frames + ^done, + stack=[ + frame={level="0",addr="0x00010734",func="callee4", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", + arch="i386:x86_64"}, + frame={level="1",addr="0x0001076c",func="callee3", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", + arch="i386:x86_64"}, + frame={level="2",addr="0x0001078c",func="callee2", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22", + arch="i386:x86_64"}, + frame={level="3",addr="0x000107b4",func="callee1", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27", + arch="i386:x86_64"}, + frame={level="4",addr="0x000107e0",func="main", + file="../../../devo/gdb/testsuite/gdb.mi/basics.c", + fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32", + arch="i386:x86_64"}] + (gdb) + -stack-list-arguments 0 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1",args=[name="strarg"]}, + frame={level="2",args=[name="intarg",name="strarg"]}, + frame={level="3",args=[name="intarg",name="strarg",name="fltarg"]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 1 + ^done, + stack-args=[ + frame={level="0",args=[]}, + frame={level="1", + args=[{name="strarg",value="0x11940 \"A string argument.\""}]}, + frame={level="2",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}, + {frame={level="3",args=[ + {name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}, + {name="fltarg",value="3.5"}]}, + frame={level="4",args=[]}] + (gdb) + -stack-list-arguments 0 2 2 + ^done,stack-args=[frame={level="2",args=[name="intarg",name="strarg"]}] + (gdb) + -stack-list-arguments 1 2 2 + ^done,stack-args=[frame={level="2", + args=[{name="intarg",value="2"}, + {name="strarg",value="0x11940 \"A string argument.\""}]}] + (gdb) + +The '-stack-list-frames' Command +-------------------------------- + +Synopsis +........ + + -stack-list-frames [ --no-frame-filters LOW-FRAME HIGH-FRAME ] + + List the frames currently on the stack. For each frame it displays +the following info: + +'LEVEL' + The frame number, 0 being the topmost frame, i.e., the innermost + function. +'ADDR' + The '$pc' value for that frame. +'FUNC' + Function name. +'FILE' + File name of the source file where the function lives. +'FULLNAME' + The full file name of the source file where the function lives. +'LINE' + Line number corresponding to the '$pc'. +'FROM' + The shared library where this function is defined. This is only + given if the frame's function is not known. +'ARCH' + Frame's architecture. + + If invoked without arguments, this command prints a backtrace for the +whole stack. If given two integer arguments, it shows the frames whose +levels are between the two arguments (inclusive). If the two arguments +are equal, it shows the single frame at the corresponding level. It is +an error if LOW-FRAME is larger than the actual number of frames. On +the other hand, HIGH-FRAME may be larger than the actual number of +frames, in which case only existing frames will be returned. If the +option '--no-frame-filters' is supplied, then Python frame filters will +not be executed. + +GDB Command +........... + +The corresponding GDB commands are 'backtrace' and 'where'. + +Example +....... + +Full stack backtrace: + + (gdb) + -stack-list-frames + ^done,stack= + [frame={level="0",addr="0x0001076c",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11", + arch="i386:x86_64"}, + frame={level="1",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="2",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="6",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="7",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="8",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="9",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="10",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="11",addr="0x00010738",func="main", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4", + arch="i386:x86_64"}] + (gdb) + + Show frames between LOW_FRAME and HIGH_FRAME: + + (gdb) + -stack-list-frames 3 5 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}, + frame={level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}] + (gdb) + + Show a single frame: + + (gdb) + -stack-list-frames 3 3 + ^done,stack= + [frame={level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"}] + (gdb) + +The '-stack-list-locals' Command +-------------------------------- + +Synopsis +........ + + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the local variable names for the selected frame. If +PRINT-VALUES is 0 or '--no-values', print only the names of the +variables; if it is 1 or '--all-values', print also their values; and if +it is 2 or '--simple-values', print the name, type and value for simple +data types, and the name and type for arrays, structures and unions. In +this last case, a frontend can immediately display the value of simple +data types and create variable objects for other data types when the +user wishes to explore their values in more detail. If the option +'--no-frame-filters' is supplied, then Python frame filters will not be +executed. + + If the '--skip-unavailable' option is specified, local variables that +are not available are not listed. Partially available local variables +are still displayed, however. + + This command is deprecated in favor of the '-stack-list-variables' +command. + +GDB Command +........... + +'info locals' in GDB, 'gdb_get_locals' in 'gdbtk'. + +Example +....... + + (gdb) + -stack-list-locals 0 + ^done,locals=[name="A",name="B",name="C"] + (gdb) + -stack-list-locals --all-values + ^done,locals=[{name="A",value="1"},{name="B",value="2"}, + {name="C",value="{1, 2, 3}"}] + -stack-list-locals --simple-values + ^done,locals=[{name="A",type="int",value="1"}, + {name="B",type="int",value="2"},{name="C",type="int [3]"}] + (gdb) + +The '-stack-list-variables' Command +----------------------------------- + +Synopsis +........ + + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] PRINT-VALUES + + Display the names of local variables and function arguments for the +selected frame. If PRINT-VALUES is 0 or '--no-values', print only the +names of the variables; if it is 1 or '--all-values', print also their +values; and if it is 2 or '--simple-values', print the name, type and +value for simple data types, and the name and type for arrays, +structures and unions. If the option '--no-frame-filters' is supplied, +then Python frame filters will not be executed. + + If the '--skip-unavailable' option is specified, local variables and +arguments that are not available are not listed. Partially available +arguments and local variables are still displayed, however. + +Example +....... + + (gdb) + -stack-list-variables --thread 1 --frame 0 --all-values + ^done,variables=[{name="x",value="11"},{name="s",value="{a = 1, b = 2}"}] + (gdb) + +The '-stack-select-frame' Command +--------------------------------- + +Synopsis +........ + + -stack-select-frame FRAMENUM + + Change the selected frame. Select a different frame FRAMENUM on the +stack. + + This command in deprecated in favor of passing the '--frame' option +to every command. + +GDB Command +........... + +The corresponding GDB commands are 'frame', 'up', 'down', +'select-frame', 'up-silent', and 'down-silent'. + +Example +....... + + (gdb) + -stack-select-frame 2 + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Variable Objects, Next: GDB/MI Data Manipulation, Prev: GDB/MI Stack Manipulation, Up: GDB/MI + +27.15 GDB/MI Variable Objects +============================= + +Introduction to Variable Objects +-------------------------------- + +Variable objects are "object-oriented" MI interface for examining and +changing values of expressions. Unlike some other MI interfaces that +work with expressions, variable objects are specifically designed for +simple and efficient presentation in the frontend. A variable object is +identified by string name. When a variable object is created, the +frontend specifies the expression for that variable object. The +expression can be a simple variable, or it can be an arbitrary complex +expression, and can even involve CPU registers. After creating a +variable object, the frontend can invoke other variable object +operations--for example to obtain or change the value of a variable +object, or to change display format. + + Variable objects have hierarchical tree structure. Any variable +object that corresponds to a composite type, such as structure in C, has +a number of child variable objects, for example corresponding to each +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach leaf variable +objects, which always have built-in types. Child variable objects are +created only by explicit request, so if a frontend is not interested in +the children of a particular variable object, no child will be created. + + For a leaf variable object it is possible to obtain its value as a +string, or set the value from a string. String value can be also +obtained for a non-leaf variable object, but it's generally a string +that only indicates the type of the object, and does not list its +contents. Assignment to a non-leaf variable object is not allowed. + + A frontend does not need to read the values of all variable objects +each time the program stops. Instead, MI provides an update command +that lists all variable objects whose values has changed since the last +update operation. This considerably reduces the amount of data that +must be transferred to the frontend. As noted above, children variable +objects are created on demand, and only leaf variable objects have a +real value. As result, gdb will read target memory only for leaf +variables that frontend has created. + + The automatic update is not always desirable. For example, a +frontend might want to keep a value of some expression for future +reference, and never update it. For another example, fetching memory is +relatively slow for embedded targets, so a frontend might want to +disable automatic update for the variables that are either not visible +on the screen, or "closed". This is possible using so called "frozen +variable objects". Such variable objects are never implicitly updated. + + Variable objects can be either "fixed" or "floating". For the fixed +variable object, the expression is parsed when the variable object is +created, including associating identifiers to specific variables. The +meaning of expression never changes. For a floating variable object the +values of variables whose names appear in the expressions are +re-evaluated every time in the context of the current frame. Consider +this example: + + void do_work(...) + { + struct work_state state; + + if (...) + do_work(...); + } + + If a fixed variable object for the 'state' variable is created in +this function, and we enter the recursive call, the variable object will +report the value of 'state' in the top-level 'do_work' invocation. On +the other hand, a floating variable object will report the value of +'state' in the current frame. + + If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, GDB makes sure that the thread/frame +combination the variable object is bound to still exists, and +re-evaluates the variable object in context of that thread/frame. + + The following is the complete set of GDB/MI operations defined to +access this functionality: + +*Operation* *Description* + +'-enable-pretty-printing' enable Python-based pretty-printing +'-var-create' create a variable object +'-var-delete' delete the variable object and/or its + children +'-var-set-format' set the display format of this variable +'-var-show-format' show the display format of this variable +'-var-info-num-children' tells how many children this object has +'-var-list-children' return a list of the object's children +'-var-info-type' show the type of this variable object +'-var-info-expression' print parent-relative expression that + this variable object represents +'-var-info-path-expression' print full expression that this variable + object represents +'-var-show-attributes' is this variable editable? does it exist + here? +'-var-evaluate-expression' get the value of this variable +'-var-assign' set the value of this variable +'-var-update' update the variable and its children +'-var-set-frozen' set frozenness attribute +'-var-set-update-range' set range of children to display on + update + + In the next subsection we describe each operation in detail and +suggest how it can be used. + +Description And Use of Operations on Variable Objects +----------------------------------------------------- + +The '-enable-pretty-printing' Command +------------------------------------- + + -enable-pretty-printing + + GDB allows Python-based visualizers to affect the output of the MI +variable object commands. However, because there was no way to +implement this in a fully backward-compatible way, a front end must +request that this functionality be enabled. + + Once enabled, this feature cannot be disabled. + + Note that if Python support has not been compiled into GDB, this +command will still succeed (and do nothing). + +The '-var-create' Command +------------------------- + +Synopsis +........ + + -var-create {NAME | "-"} + {FRAME-ADDR | "*" | "@"} EXPRESSION + + This operation creates a variable object, which allows the monitoring +of a variable, the result of an expression, a memory cell or a CPU +register. + + The NAME parameter is the string by which the object can be +referenced. It must be unique. If '-' is specified, the varobj system +will generate a string "varNNNNNN" automatically. It will be unique +provided that one does not specify NAME of that format. The command +fails if a duplicate name is found. + + The frame under which the expression should be evaluated can be +specified by FRAME-ADDR. A '*' indicates that the current frame should +be used. A '@' indicates that a floating variable object must be +created. + + EXPRESSION is any expression valid on the current language set (must +not begin with a '*'), or one of the following: + + * '*ADDR', where ADDR is the address of a memory cell + + * '*ADDR-ADDR' -- a memory address range (TBD) + + * '$REGNAME' -- a CPU register name + + A varobj's contents may be provided by a Python-based pretty-printer. +In this case the varobj is known as a "dynamic varobj". Dynamic varobjs +have slightly different semantics in some cases. If the +'-enable-pretty-printing' command is not sent, then GDB will never +create a dynamic varobj. This ensures backward compatibility for +existing clients. + +Result +...... + +This operation returns attributes of the newly-created varobj. These +are: + +'name' + The name of the varobj. + +'numchild' + The number of children of the varobj. This number is not + necessarily reliable for a dynamic varobj. Instead, you must + examine the 'has_more' attribute. + +'value' + The varobj's scalar value. For a varobj whose type is some sort of + aggregate (e.g., a 'struct'), this value will not be interesting. + For a dynamic varobj, this value comes directly from the Python + pretty-printer object's 'to_string' method. + +'type' + The varobj's type. This is a string representation of the type, as + would be printed by the GDB CLI. If 'print object' (*note set print + object: Print Settings.) is set to 'on', the _actual_ (derived) + type of the object is shown rather than the _declared_ one. + +'thread-id' + If a variable object is bound to a specific thread, then this is + the thread's global identifier. + +'has_more' + For a dynamic varobj, this indicates whether there appear to be any + children available. For a non-dynamic varobj, this will be 0. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + + Typical output will look like this: + + name="NAME",numchild="N",type="TYPE",thread-id="M", + has_more="HAS_MORE" + +The '-var-delete' Command +------------------------- + +Synopsis +........ + + -var-delete [ -c ] NAME + + Deletes a previously created variable object and all of its children. +With the '-c' option, just deletes the children. + + Returns an error if the object NAME is not found. + +The '-var-set-format' Command +----------------------------- + +Synopsis +........ + + -var-set-format NAME FORMAT-SPEC + + Sets the output format for the value of the object NAME to be +FORMAT-SPEC. + + The syntax for the FORMAT-SPEC is as follows: + + FORMAT-SPEC ==> + {binary | decimal | hexadecimal | octal | natural | zero-hexadecimal} + + The natural format is the default format chosen automatically based +on the variable type (like decimal for an 'int', hex for pointers, +etc.). + + The zero-hexadecimal format has a representation similar to +hexadecimal but with padding zeroes to the left of the value. For +example, a 32-bit hexadecimal value of 0x1234 would be represented as +0x00001234 in the zero-hexadecimal format. + + For a variable with children, the format is set only on the variable +itself, and the children are not affected. + +The '-var-show-format' Command +------------------------------ + +Synopsis +........ + + -var-show-format NAME + + Returns the format used to display the value of the object NAME. + + FORMAT ==> + FORMAT-SPEC + +The '-var-info-num-children' Command +------------------------------------ + +Synopsis +........ + + -var-info-num-children NAME + + Returns the number of children of a variable object NAME: + + numchild=N + + Note that this number is not completely reliable for a dynamic +varobj. It will return the current number of children, but more +children may be available. + +The '-var-list-children' Command +-------------------------------- + +Synopsis +........ + + -var-list-children [PRINT-VALUES] NAME [FROM TO] + + Return a list of the children of the specified variable object and +create variable objects for them, if they do not already exist. With a +single argument or if PRINT-VALUES has a value of 0 or '--no-values', +print only the names of the variables; if PRINT-VALUES is 1 or +'--all-values', also print their values; and if it is 2 or +'--simple-values' print the name and value for simple data types and +just the name for arrays, structures and unions. + + FROM and TO, if specified, indicate the range of children to report. +If FROM or TO is less than zero, the range is reset and all children +will be reported. Otherwise, children starting at FROM (zero-based) and +up to and excluding TO will be reported. + + If a child range is requested, it will only affect the current call +to '-var-list-children', but not future calls to '-var-update'. For +this, you must instead use '-var-set-update-range'. The intent of this +approach is to enable a front end to implement any update approach it +likes; for example, scrolling a view may cause the front end to request +more children with '-var-list-children', and then the front end could +call '-var-set-update-range' with a different range to ensure that +future updates are restricted to just the visible items. + + For each child the following results are returned: + +NAME + Name of the variable object created for this child. + +EXP + The expression to be shown to the user by the front end to + designate this child. For example this may be the name of a + structure member. + + For a dynamic varobj, this value cannot be used to form an + expression. There is no way to do this at all with a dynamic + varobj. + + For C/C++ structures there are several pseudo children returned to + designate access qualifiers. For these pseudo children EXP is + 'public', 'private', or 'protected'. In this case the type and + value are not present. + + A dynamic varobj will not report the access qualifying + pseudo-children, regardless of the language. This information is + not available at all with a dynamic varobj. + +NUMCHILD + Number of children this child has. For a dynamic varobj, this will + be 0. + +TYPE + The type of the child. If 'print object' (*note set print object: + Print Settings.) is set to 'on', the _actual_ (derived) type of the + object is shown rather than the _declared_ one. + +VALUE + If values were requested, this is the value. + +THREAD-ID + If this variable object is associated with a thread, this is the + thread's global thread id. Otherwise this result is not present. + +FROZEN + If the variable object is frozen, this variable will be present + with a value of 1. + +DISPLAYHINT + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +DYNAMIC + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + + The result may have its own attributes: + +'displayhint' + A dynamic varobj can supply a display hint to the front end. The + value comes directly from the Python pretty-printer object's + 'display_hint' method. *Note Pretty Printing API::. + +'has_more' + This is an integer attribute which is nonzero if there are children + remaining after the end of the selected range. + +Example +....... + + (gdb) + -var-list-children n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,type=TYPE},(repeats N times)] + (gdb) + -var-list-children --all-values n + ^done,numchild=N,children=[child={name=NAME,exp=EXP, + numchild=N,value=VALUE,type=TYPE},(repeats N times)] + +The '-var-info-type' Command +---------------------------- + +Synopsis +........ + + -var-info-type NAME + + Returns the type of the specified variable NAME. The type is +returned as a string in the same format as it is output by the GDB CLI: + + type=TYPENAME + +The '-var-info-expression' Command +---------------------------------- + +Synopsis +........ + + -var-info-expression NAME + + Returns a string that is suitable for presenting this variable object +in user interface. The string is generally not valid expression in the +current language, and cannot be evaluated. + + For example, if 'a' is an array, and variable object 'A' was created +for 'a', then we'll get this output: + + (gdb) -var-info-expression A.1 + ^done,lang="C",exp="1" + +Here, the value of 'lang' is the language name, which can be found in +*note Supported Languages::. + + Note that the output of the '-var-list-children' command also +includes those expressions, so the '-var-info-expression' command is of +limited use. + +The '-var-info-path-expression' Command +--------------------------------------- + +Synopsis +........ + + -var-info-path-expression NAME + + Returns an expression that can be evaluated in the current context +and will yield the same value that a variable object has. Compare this +with the '-var-info-expression' command, which result can be used only +for UI presentation. Typical use of the '-var-info-path-expression' +command is creating a watchpoint from a variable object. + + This command is currently not valid for children of a dynamic varobj, +and will give an error when invoked on one. + + For example, suppose 'C' is a C++ class, derived from class 'Base', +and that the 'Base' class has a member called 'm_size'. Assume a +variable 'c' is has the type of 'C' and a variable object 'C' was +created for variable 'c'. Then, we'll get this output: + (gdb) -var-info-path-expression C.Base.public.m_size + ^done,path_expr=((Base)c).m_size) + +The '-var-show-attributes' Command +---------------------------------- + +Synopsis +........ + + -var-show-attributes NAME + + List attributes of the specified variable object NAME: + + status=ATTR [ ( ,ATTR )* ] + +where ATTR is '{ { editable | noneditable } | TBD }'. + +The '-var-evaluate-expression' Command +-------------------------------------- + +Synopsis +........ + + -var-evaluate-expression [-f FORMAT-SPEC] NAME + + Evaluates the expression that is represented by the specified +variable object and returns its value as a string. The format of the +string can be specified with the '-f' option. The possible values of +this option are the same as for '-var-set-format' (*note +-var-set-format::). If the '-f' option is not specified, the current +display format will be used. The current display format can be changed +using the '-var-set-format' command. + + value=VALUE + + Note that one must invoke '-var-list-children' for a variable before +the value of a child variable can be evaluated. + +The '-var-assign' Command +------------------------- + +Synopsis +........ + + -var-assign NAME EXPRESSION + + Assigns the value of EXPRESSION to the variable object specified by +NAME. The object must be 'editable'. If the variable's value is +altered by the assign, the variable will show up in any subsequent +'-var-update' list. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update * + ^done,changelist=[{name="var1",in_scope="true",type_changed="false"}] + (gdb) + +The '-var-update' Command +------------------------- + +Synopsis +........ + + -var-update [PRINT-VALUES] {NAME | "*"} + + Reevaluate the expressions corresponding to the variable object NAME +and all its direct and indirect children, and return the list of +variable objects whose values have changed; NAME must be a root variable +object. Here, "changed" means that the result of +'-var-evaluate-expression' before and after the '-var-update' is +different. If '*' is used as the variable object names, all existing +variable objects are updated, except for frozen ones (*note +-var-set-frozen::). The option PRINT-VALUES determines whether both +names and values, or just names are printed. The possible values of +this option are the same as for '-var-list-children' (*note +-var-list-children::). It is recommended to use the '--all-values' +option, to reduce the number of MI commands needed on each program stop. + + With the '*' parameter, if a variable object is bound to a currently +running thread, it will not be updated, without any diagnostic. + + If '-var-set-update-range' was previously used on a varobj, then only +the selected range of children will be reported. + + '-var-update' reports all the changed varobjs in a tuple named +'changelist'. + + Each item in the change list is itself a tuple holding: + +'name' + The name of the varobj. + +'value' + If values were requested for this update, then this field will be + present and will hold the value of the varobj. + +'in_scope' + This field is a string which may take one of three values: + + '"true"' + The variable object's current value is valid. + + '"false"' + The variable object does not currently hold a valid value but + it may hold one in the future if its associated expression + comes back into scope. + + '"invalid"' + The variable object no longer holds a valid value. This can + occur when the executable file being debugged has changed, + either through recompilation or by using the GDB 'file' + command. The front end should normally choose to delete these + variable objects. + + In the future new values may be added to this list so the front + should be prepared for this possibility. *Note GDB/MI Development + and Front Ends: GDB/MI Development and Front Ends. + +'type_changed' + This is only present if the varobj is still valid. If the type + changed, then this will be the string 'true'; otherwise it will be + 'false'. + + When a varobj's type changes, its children are also likely to have + become incorrect. Therefore, the varobj's children are + automatically deleted when this attribute is 'true'. Also, the + varobj's update range, when set using the '-var-set-update-range' + command, is unset. + +'new_type' + If the varobj's type changed, then this field will be present and + will hold the new type. + +'new_num_children' + For a dynamic varobj, if the number of children changed, or if the + type changed, this will be the new number of children. + + The 'numchild' field in other varobj responses is generally not + valid for a dynamic varobj - it will show the number of children + that GDB knows about, but because dynamic varobjs lazily + instantiate their children, this will not reflect the number of + children which may be available. + + The 'new_num_children' attribute only reports changes to the number + of children known by GDB. This is the only way to detect whether + an update has removed children (which necessarily can only happen + at the end of the update range). + +'displayhint' + The display hint, if any. + +'has_more' + This is an integer value, which will be 1 if there are more + children available outside the varobj's update range. + +'dynamic' + This attribute will be present and have the value '1' if the varobj + is a dynamic varobj. If the varobj is not a dynamic varobj, then + this attribute will not be present. + +'new_children' + If new children were added to a dynamic varobj within the selected + update range (as set by '-var-set-update-range'), then they will be + listed in this attribute. + +Example +....... + + (gdb) + -var-assign var1 3 + ^done,value="3" + (gdb) + -var-update --all-values var1 + ^done,changelist=[{name="var1",value="3",in_scope="true", + type_changed="false"}] + (gdb) + +The '-var-set-frozen' Command +----------------------------- + +Synopsis +........ + + -var-set-frozen NAME FLAG + + Set the frozenness flag on the variable object NAME. The FLAG +parameter should be either '1' to make the variable frozen or '0' to +make it unfrozen. If a variable object is frozen, then neither itself, +nor any of its children, are implicitly updated by '-var-update' of a +parent variable or by '-var-update *'. Only '-var-update' of the +variable itself will update its value and values of its children. After +a variable object is unfrozen, it is implicitly updated by all +subsequent '-var-update' operations. Unfreezing a variable does not +update it, only subsequent '-var-update' does. + +Example +....... + + (gdb) + -var-set-frozen V 1 + ^done + (gdb) + +The '-var-set-update-range' command +----------------------------------- + +Synopsis +........ + + -var-set-update-range NAME FROM TO + + Set the range of children to be returned by future invocations of +'-var-update'. + + FROM and TO indicate the range of children to report. If FROM or TO +is less than zero, the range is reset and all children will be reported. +Otherwise, children starting at FROM (zero-based) and up to and +excluding TO will be reported. + +Example +....... + + (gdb) + -var-set-update-range V 1 2 + ^done + +The '-var-set-visualizer' command +--------------------------------- + +Synopsis +........ + + -var-set-visualizer NAME VISUALIZER + + Set a visualizer for the variable object NAME. + + VISUALIZER is the visualizer to use. The special value 'None' means +to disable any visualizer in use. + + If not 'None', VISUALIZER must be a Python expression. This +expression must evaluate to a callable object which accepts a single +argument. GDB will call this object with the value of the varobj NAME +as an argument (this is done so that the same Python pretty-printing +code can be used for both the CLI and MI). When called, this object must +return an object which conforms to the pretty-printing interface (*note +Pretty Printing API::). + + The pre-defined function 'gdb.default_visualizer' may be used to +select a visualizer by following the built-in process (*note Selecting +Pretty-Printers::). This is done automatically when a varobj is +created, and so ordinarily is not needed. + + This feature is only available if Python support is enabled. The MI +command '-list-features' (*note GDB/MI Support Commands::) can be used +to check this. + +Example +....... + +Resetting the visualizer: + + (gdb) + -var-set-visualizer V None + ^done + + Reselecting the default (type-based) visualizer: + + (gdb) + -var-set-visualizer V gdb.default_visualizer + ^done + + Suppose 'SomeClass' is a visualizer class. A lambda expression can +be used to instantiate this class for a varobj: + + (gdb) + -var-set-visualizer V "lambda val: SomeClass()" + ^done + + +File: gdb.info, Node: GDB/MI Data Manipulation, Next: GDB/MI Tracepoint Commands, Prev: GDB/MI Variable Objects, Up: GDB/MI + +27.16 GDB/MI Data Manipulation +============================== + +This section describes the GDB/MI commands that manipulate data: examine +memory and registers, evaluate expressions, etc. + + For details about what an addressable memory unit is, *note +addressable memory unit::. + +The '-data-disassemble' Command +------------------------------- + +Synopsis +........ + + -data-disassemble + ( -s START-ADDR -e END-ADDR + | -a ADDR + | -f FILENAME -l LINENUM [ -n LINES ] ) + [ --opcodes OPCODES-MODE ] + [ --source ] + [ -- MODE ] + +Where: + +'START-ADDR' + is the beginning address (or '$pc') +'END-ADDR' + is the end address +'ADDR' + is an address anywhere within (or the name of) the function to + disassemble. If an address is specified, the whole function + surrounding that address will be disassembled. If a name is + specified, the whole function with that name will be disassembled. +'FILENAME' + is the name of the file to disassemble +'LINENUM' + is the line number to disassemble around +'LINES' + is the number of disassembly lines to be produced. If it is -1, + the whole function will be disassembled, in case no END-ADDR is + specified. If END-ADDR is specified as a non-zero value, and LINES + is lower than the number of disassembly lines between START-ADDR + and END-ADDR, only LINES lines are displayed; if LINES is higher + than the number of lines between START-ADDR and END-ADDR, only the + lines up to END-ADDR are displayed. +'OPCODES-MODE' + can only be used with MODE 0, and should be one of the following: + 'none' + no opcode information will be included in the result. + + 'bytes' + opcodes will be included in the result, the opcodes will be + formatted as for 'disassemble /b'. + + 'display' + opcodes will be included in the result, the opcodes will be + formatted as for 'disassemble /r'. +'MODE' + the use of MODE is deprecated in favour of using the '--opcodes' + and '--source' options. When no MODE is given, MODE 0 will be + assumed. However, the MODE is still available for backward + compatibility. The MODE should be one of: + '0' + _disassembly only_, this is the default mode if no mode is + specified. + + '1' + _mixed source and disassembly (deprecated)_, it is not + possible to recreate this mode using '--opcodes' and + '--source' options. + + '2' + _disassembly with raw opcodes_, this mode is equivalent to + using MODE 0 and passing '--opcodes bytes' to the command. + + '3' + _mixed source and disassembly with raw opcodes (deprecated)_, + it is not possible to recreate this mode using '--opcodes' and + '--source' options. + + '4' + _mixed source and disassembly_, this mode is equivalent to + using MODE 0 and passing '--source' to the command. + + '5' + _mixed source and disassembly with raw opcodes_, this mode is + equivalent to using MODE 0 and passing '--opcodes bytes' and + '--source' to the command. + Modes 1 and 3 are deprecated. The output is "source centric" which + hasn't proved useful in practice. *Note Machine Code::, for a + discussion of the difference between '/m' and '/s' output of the + 'disassemble' command. + + The '--source' can only be used with MODE 0. Passing this option +will include the source code in the disassembly result as if MODE 4 or 5 +had been used. + +Result +...... + +The result of the '-data-disassemble' command will be a list named +'asm_insns', the contents of this list depend on the options used with +the '-data-disassemble' command. + + For modes 0 and 2, and when the '--source' option is not used, the +'asm_insns' list contains tuples with the following fields: + +'address' + The address at which this instruction was disassembled. + +'func-name' + The name of the function this instruction is within. + +'offset' + The decimal offset in bytes from the start of 'func-name'. + +'inst' + The text disassembly for this 'address'. + +'opcodes' + This field is only present for modes 2, 3 and 5, or when the + '--opcodes' option 'bytes' or 'display' is used. This contains the + raw opcode bytes for the 'inst' field. + + When the '--opcodes' option is not passed to '-data-disassemble', + or the 'bytes' value is passed to '--opcodes', then the bytes are + formatted as a series of single bytes, in hex, in ascending address + order, with a single space between each byte. This format is + equivalent to the '/b' option being used with the 'disassemble' + command (*note 'disassemble': disassemble.). + + When '--opcodes' is passed the value 'display' then the bytes are + formatted in the natural instruction display order. This means + multiple bytes can be grouped together, and the bytes might be + byte-swapped. This format is equivalent to the '/r' option being + used with the 'disassemble' command. + + For modes 1, 3, 4 and 5, or when the '--source' option is used, the +'asm_insns' list contains tuples named 'src_and_asm_line', each of which +has the following fields: + +'line' + The line number within 'file'. + +'file' + The file name from the compilation unit. This might be an absolute + file name or a relative file name depending on the compile command + used. + +'fullname' + Absolute file name of 'file'. It is converted to a canonical form + using the source file search path (*note Specifying Source + Directories: Source Path.) and after resolving all the symbolic + links. + + If the source file is not found this field will contain the path as + present in the debug information. + +'line_asm_insn' + This is a list of tuples containing the disassembly for 'line' in + 'file'. The fields of each tuple are the same as for + '-data-disassemble' in MODE 0 and 2, so 'address', 'func-name', + 'offset', 'inst', and optionally 'opcodes'. + + Note that whatever included in the 'inst' field, is not manipulated +directly by GDB/MI, i.e., it is not possible to adjust its format. + +GDB Command +........... + +The corresponding GDB command is 'disassemble'. + +Example +....... + +Disassemble from the current value of '$pc' to '$pc + 20': + + (gdb) + -data-disassemble -s $pc -e "$pc + 20" -- 0 + ^done, + asm_insns=[ + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107c8",func-name="main",offset="12", + inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"}, + {address="0x000107cc",func-name="main",offset="16", + inst="sethi %hi(0x11800), %o2"}, + {address="0x000107d0",func-name="main",offset="20", + inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"}] + (gdb) + + Disassemble the whole 'main' function. Line 32 is part of 'main'. + + -data-disassemble -f basics.c -l 32 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}, + [...] + {address="0x0001081c",func-name="main",offset="96",inst="ret "}, + {address="0x00010820",func-name="main",offset="100",inst="restore "}] + (gdb) + + Disassemble 3 instructions from the start of 'main': + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 0 + ^done,asm_insns=[ + {address="0x000107bc",func-name="main",offset="0", + inst="save %sp, -112, %sp"}, + {address="0x000107c0",func-name="main",offset="4", + inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}] + (gdb) + + Disassemble 3 instructions from the start of 'main' in mixed mode: + + (gdb) + -data-disassemble -f basics.c -l 32 -n 3 -- 1 + ^done,asm_insns=[ + src_and_asm_line={line="31", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107bc", + func-name="main",offset="0",inst="save %sp, -112, %sp"}]}, + src_and_asm_line={line="32", + file="../../../src/gdb/testsuite/gdb.mi/basics.c", + fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", + line_asm_insn=[{address="0x000107c0", + func-name="main",offset="4",inst="mov 2, %o0"}, + {address="0x000107c4",func-name="main",offset="8", + inst="sethi %hi(0x11800), %o2"}]}] + (gdb) + +The '-data-evaluate-expression' Command +--------------------------------------- + +Synopsis +........ + + -data-evaluate-expression EXPR + + Evaluate EXPR as an expression. The expression could contain an +inferior function call. The function call will execute synchronously. +If the expression contains spaces, it must be enclosed in double quotes. + +GDB Command +........... + +The corresponding GDB commands are 'print', 'output', and 'call'. In +'gdbtk' only, there's a corresponding 'gdb_eval' command. + +Example +....... + +In the following example, the numbers that precede the commands are the +"tokens" described in *note GDB/MI Command Syntax: GDB/MI Command +Syntax. Notice how GDB/MI returns the same tokens in its output. + + 211-data-evaluate-expression A + 211^done,value="1" + (gdb) + 311-data-evaluate-expression &A + 311^done,value="0xefffeb7c" + (gdb) + 411-data-evaluate-expression A+3 + 411^done,value="4" + (gdb) + 511-data-evaluate-expression "A + 3" + 511^done,value="4" + (gdb) + +The '-data-list-changed-registers' Command +------------------------------------------ + +Synopsis +........ + + -data-list-changed-registers + + Display a list of the registers that have changed. + +GDB Command +........... + +GDB doesn't have a direct analog for this command; 'gdbtk' has the +corresponding command 'gdb_changed_register_list'. + +Example +....... + +On a PPC MBX board: + + (gdb) + -exec-continue + ^running + + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame={ + func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", + line="5",arch="powerpc"} + (gdb) + -data-list-changed-registers + ^done,changed-registers=["0","1","2","4","5","6","7","8","9", + "10","11","13","14","15","16","17","18","19","20","21","22","23", + "24","25","26","27","28","30","31","64","65","66","67","69"] + (gdb) + +The '-data-list-register-names' Command +--------------------------------------- + +Synopsis +........ + + -data-list-register-names [ ( REGNO )+ ] + + Show a list of register names for the current target. If no +arguments are given, it shows a list of the names of all the registers. +If integer numbers are given as arguments, it will print a list of the +names of the registers corresponding to the arguments. To ensure +consistency between a register name and its number, the output list may +include empty register names. + +GDB Command +........... + +GDB does not have a command which corresponds to +'-data-list-register-names'. In 'gdbtk' there is a corresponding +command 'gdb_regnames'. + +Example +....... + +For the PPC MBX board: + (gdb) + -data-list-register-names + ^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", + "r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", + "r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", + "r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", + "f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", + "f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", + "", "pc","ps","cr","lr","ctr","xer"] + (gdb) + -data-list-register-names 1 2 3 + ^done,register-names=["r1","r2","r3"] + (gdb) + +The '-data-list-register-values' Command +---------------------------------------- + +Synopsis +........ + + -data-list-register-values + [ --skip-unavailable ] FMT [ ( REGNO )*] + + Display the registers' contents. The format according to which the +registers' contents are to be returned is given by FMT, followed by an +optional list of numbers specifying the registers to display. A missing +list of numbers indicates that the contents of all the registers must be +returned. The '--skip-unavailable' option indicates that only the +available registers are to be returned. + + Allowed formats for FMT are: + +'x' + Hexadecimal +'o' + Octal +'t' + Binary +'d' + Decimal +'r' + Raw +'N' + Natural + +GDB Command +........... + +The corresponding GDB commands are 'info reg', 'info all-reg', and (in +'gdbtk') 'gdb_fetch_registers'. + +Example +....... + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + + (gdb) + -data-list-register-values r 64 65 + ^done,register-values=[{number="64",value="0xfe00a300"}, + {number="65",value="0x00029002"}] + (gdb) + -data-list-register-values x + ^done,register-values=[{number="0",value="0xfe0043c8"}, + {number="1",value="0x3fff88"},{number="2",value="0xfffffffe"}, + {number="3",value="0x0"},{number="4",value="0xa"}, + {number="5",value="0x3fff68"},{number="6",value="0x3fff58"}, + {number="7",value="0xfe011e98"},{number="8",value="0x2"}, + {number="9",value="0xfa202820"},{number="10",value="0xfa202808"}, + {number="11",value="0x1"},{number="12",value="0x0"}, + {number="13",value="0x4544"},{number="14",value="0xffdfffff"}, + {number="15",value="0xffffffff"},{number="16",value="0xfffffeff"}, + {number="17",value="0xefffffed"},{number="18",value="0xfffffffe"}, + {number="19",value="0xffffffff"},{number="20",value="0xffffffff"}, + {number="21",value="0xffffffff"},{number="22",value="0xfffffff7"}, + {number="23",value="0xffffffff"},{number="24",value="0xffffffff"}, + {number="25",value="0xffffffff"},{number="26",value="0xfffffffb"}, + {number="27",value="0xffffffff"},{number="28",value="0xf7bfffff"}, + {number="29",value="0x0"},{number="30",value="0xfe010000"}, + {number="31",value="0x0"},{number="32",value="0x0"}, + {number="33",value="0x0"},{number="34",value="0x0"}, + {number="35",value="0x0"},{number="36",value="0x0"}, + {number="37",value="0x0"},{number="38",value="0x0"}, + {number="39",value="0x0"},{number="40",value="0x0"}, + {number="41",value="0x0"},{number="42",value="0x0"}, + {number="43",value="0x0"},{number="44",value="0x0"}, + {number="45",value="0x0"},{number="46",value="0x0"}, + {number="47",value="0x0"},{number="48",value="0x0"}, + {number="49",value="0x0"},{number="50",value="0x0"}, + {number="51",value="0x0"},{number="52",value="0x0"}, + {number="53",value="0x0"},{number="54",value="0x0"}, + {number="55",value="0x0"},{number="56",value="0x0"}, + {number="57",value="0x0"},{number="58",value="0x0"}, + {number="59",value="0x0"},{number="60",value="0x0"}, + {number="61",value="0x0"},{number="62",value="0x0"}, + {number="63",value="0x0"},{number="64",value="0xfe00a300"}, + {number="65",value="0x29002"},{number="66",value="0x202f04b5"}, + {number="67",value="0xfe0043b0"},{number="68",value="0xfe00b3e4"}, + {number="69",value="0x20002b03"}] + (gdb) + +The '-data-read-memory' Command +------------------------------- + +This command is deprecated, use '-data-read-memory-bytes' instead. + +Synopsis +........ + + -data-read-memory [ -o BYTE-OFFSET ] + ADDRESS WORD-FORMAT WORD-SIZE + NR-ROWS NR-COLS [ ASCHAR ] + +where: + +'ADDRESS' + An expression specifying the address of the first memory word to be + read. Complex expressions containing embedded white space should + be quoted using the C convention. + +'WORD-FORMAT' + The format to be used to print the memory words. The notation is + the same as for GDB's 'print' command (*note Output Formats: Output + Formats.). + +'WORD-SIZE' + The size of each memory word in bytes. + +'NR-ROWS' + The number of rows in the output table. + +'NR-COLS' + The number of columns in the output table. + +'ASCHAR' + If present, indicates that each row should include an ASCII dump. + The value of ASCHAR is used as a padding character when a byte is + not a member of the printable ASCII character set (printable ASCII + characters are those whose code is between 32 and 126, + inclusively). + +'BYTE-OFFSET' + An offset to add to the ADDRESS before fetching memory. + + This command displays memory contents as a table of NR-ROWS by +NR-COLS words, each word being WORD-SIZE bytes. In total, 'NR-ROWS * +NR-COLS * WORD-SIZE' bytes are read (returned as 'total-bytes'). Should +less than the requested number of bytes be returned by the target, the +missing words are identified using 'N/A'. The number of bytes read from +the target is returned in 'nr-bytes' and the starting address used to +read memory in 'addr'. + + The address of the next/previous row or page is available in +'next-row' and 'prev-row', 'next-page' and 'prev-page'. + +GDB Command +........... + +The corresponding GDB command is 'x'. 'gdbtk' has 'gdb_get_mem' memory +read command. + +Example +....... + +Read six bytes of memory starting at 'bytes+6' but then offset by '-6' +bytes. Format as three rows of two columns. One byte per word. +Display each word in hex. + + (gdb) + 9-data-read-memory -o -6 -- bytes+6 x 1 3 2 + 9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", + next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", + prev-page="0x0000138a",memory=[ + {addr="0x00001390",data=["0x00","0x01"]}, + {addr="0x00001392",data=["0x02","0x03"]}, + {addr="0x00001394",data=["0x04","0x05"]}] + (gdb) + + Read two bytes of memory starting at address 'shorts + 64' and +display as a single word formatted in decimal. + + (gdb) + 5-data-read-memory shorts+64 d 2 1 1 + 5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", + next-row="0x00001512",prev-row="0x0000150e", + next-page="0x00001512",prev-page="0x0000150e",memory=[ + {addr="0x00001510",data=["128"]}] + (gdb) + + Read thirty two bytes of memory starting at 'bytes+16' and format as +eight rows of four columns. Include a string encoding with 'x' used as +the non-printable character. + + (gdb) + 4-data-read-memory bytes+16 x 1 8 4 x + 4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", + next-row="0x000013c0",prev-row="0x0000139c", + next-page="0x000013c0",prev-page="0x00001380",memory=[ + {addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"}, + {addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"}, + {addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"}, + {addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"}, + {addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"}, + {addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"}, + {addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"}, + {addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"}] + (gdb) + +The '-data-read-memory-bytes' Command +------------------------------------- + +Synopsis +........ + + -data-read-memory-bytes [ -o OFFSET ] + ADDRESS COUNT + +where: + +'ADDRESS' + An expression specifying the address of the first addressable + memory unit to be read. Complex expressions containing embedded + white space should be quoted using the C convention. + +'COUNT' + The number of addressable memory units to read. This should be an + integer literal. + +'OFFSET' + The offset relative to ADDRESS at which to start reading. This + should be an integer literal. This option is provided so that a + frontend is not required to first evaluate address and then perform + address arithmetic itself. + + This command attempts to read all accessible memory regions in the +specified range. First, all regions marked as unreadable in the memory +map (if one is defined) will be skipped. *Note Memory Region +Attributes::. Second, GDB will attempt to read the remaining regions. +For each one, if reading full region results in an errors, GDB will try +to read a subset of the region. + + In general, every single memory unit in the region may be readable or +not, and the only way to read every readable unit is to try a read at +every address, which is not practical. Therefore, GDB will attempt to +read all accessible memory units at either beginning or the end of the +region, using a binary division scheme. This heuristic works well for +reading across a memory map boundary. Note that if a region has a +readable range that is neither at the beginning or the end, GDB will not +read it. + + The result record (*note GDB/MI Result Records::) that is output of +the command includes a field named 'memory' whose content is a list of +tuples. Each tuple represent a successfully read memory block and has +the following fields: + +'begin' + The start address of the memory block, as hexadecimal literal. + +'end' + The end address of the memory block, as hexadecimal literal. + +'offset' + The offset of the memory block, as hexadecimal literal, relative to + the start address passed to '-data-read-memory-bytes'. + +'contents' + The contents of the memory block, in hex. + +GDB Command +........... + +The corresponding GDB command is 'x'. + +Example +....... + + (gdb) + -data-read-memory-bytes &a 10 + ^done,memory=[{begin="0xbffff154",offset="0x00000000", + end="0xbffff15e", + contents="01000000020000000300"}] + (gdb) + +The '-data-write-memory-bytes' Command +-------------------------------------- + +Synopsis +........ + + -data-write-memory-bytes ADDRESS CONTENTS + -data-write-memory-bytes ADDRESS CONTENTS [COUNT] + +where: + +'ADDRESS' + An expression specifying the address of the first addressable + memory unit to be written. Complex expressions containing embedded + white space should be quoted using the C convention. + +'CONTENTS' + The hex-encoded data to write. It is an error if CONTENTS does not + represent an integral number of addressable memory units. + +'COUNT' + Optional argument indicating the number of addressable memory units + to be written. If COUNT is greater than CONTENTS' length, GDB will + repeatedly write CONTENTS until it fills COUNT memory units. + +GDB Command +........... + +There's no corresponding GDB command. + +Example +....... + + (gdb) + -data-write-memory-bytes &a "aabbccdd" + ^done + (gdb) + + (gdb) + -data-write-memory-bytes &a "aabbccdd" 16e + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Tracepoint Commands, Next: GDB/MI Symbol Query, Prev: GDB/MI Data Manipulation, Up: GDB/MI + +27.17 GDB/MI Tracepoint Commands +================================ + +The commands defined in this section implement MI support for +tracepoints. For detailed introduction, see *note Tracepoints::. + +The '-trace-find' Command +------------------------- + +Synopsis +........ + + -trace-find MODE [PARAMETERS...] + + Find a trace frame using criteria defined by MODE and PARAMETERS. +The following table lists permissible modes and their parameters. For +details of operation, see *note tfind::. + +'none' + No parameters are required. Stops examining trace frames. + +'frame-number' + An integer is required as parameter. Selects tracepoint frame with + that index. + +'tracepoint-number' + An integer is required as parameter. Finds next trace frame that + corresponds to tracepoint with the specified number. + +'pc' + An address is required as parameter. Finds next trace frame that + corresponds to any tracepoint at the specified address. + +'pc-inside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address inside the specified + range. Both bounds are considered to be inside the range. + +'pc-outside-range' + Two addresses are required as parameters. Finds next trace frame + that corresponds to a tracepoint at an address outside the + specified range. Both bounds are considered to be inside the + range. + +'line' + Location specification is required as parameter. *Note Location + Specifications::. Finds next trace frame that corresponds to a + tracepoint at the specified location. + + If 'none' was passed as MODE, the response does not have fields. +Otherwise, the response may have the following fields: + +'found' + This field has either '0' or '1' as the value, depending on whether + a matching tracepoint was found. + +'traceframe' + The index of the found traceframe. This field is present iff the + 'found' field has value of '1'. + +'tracepoint' + The index of the found tracepoint. This field is present iff the + 'found' field has value of '1'. + +'frame' + The information about the frame corresponding to the found trace + frame. This field is present only if a trace frame was found. + *Note GDB/MI Frame Information::, for description of this field. + +GDB Command +........... + +The corresponding GDB command is 'tfind'. + +The '-trace-define-variable' Command +------------------------------------ + +Synopsis +........ + + -trace-define-variable NAME [ VALUE ] + + Create trace variable NAME if it does not exist. If VALUE is +specified, sets the initial value of the specified trace variable to +that value. Note that the NAME should start with the '$' character. + +GDB Command +........... + +The corresponding GDB command is 'tvariable'. + +The '-trace-frame-collected' Command +------------------------------------ + +Synopsis +........ + + -trace-frame-collected + [--var-print-values VAR_PVAL] + [--comp-print-values COMP_PVAL] + [--registers-format REGFORMAT] + [--memory-contents] + + This command returns the set of collected objects, register names, +trace state variable names, memory ranges and computed expressions that +have been collected at a particular trace frame. The optional +parameters to the command affect the output format in different ways. +See the output description table below for more details. + + The reported names can be used in the normal manner to create varobjs +and inspect the objects themselves. The items returned by this command +are categorized so that it is clear which is a variable, which is a +register, which is a trace state variable, which is a memory range and +which is a computed expression. + + For instance, if the actions were + collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 + collect *(int*)0xaf02bef0@40 + +the object collected in its entirety would be 'myVar'. The object +'myArray' would be partially collected, because only the element at +index 'myIndex' would be collected. The remaining objects would be +computed expressions. + + An example output would be: + + (gdb) + -trace-frame-collected + ^done, + explicit-variables=[{name="myVar",value="1"}], + computed-expressions=[{name="myArray[myIndex]",value="0"}, + {name="myObj.field",value="0"}, + {name="myPtr->field",value="1"}, + {name="myCount + 2",value="3"}, + {name="$tvar1 + 1",value="43970027"}], + registers=[{number="0",value="0x7fe2c6e79ec8"}, + {number="1",value="0x0"}, + {number="2",value="0x4"}, + ... + {number="125",value="0x0"}], + tvars=[{name="$tvar1",current="43970026"}], + memory=[{address="0x0000000000602264",length="4"}, + {address="0x0000000000615bc0",length="4"}] + (gdb) + + Where: + +'explicit-variables' + The set of objects that have been collected in their entirety (as + opposed to collecting just a few elements of an array or a few + struct members). For each object, its name and value are printed. + The '--var-print-values' option affects how or whether the value + field is output. If VAR_PVAL is 0, then print only the names; if + it is 1, print also their values; and if it is 2, print the name, + type and value for simple data types, and the name and type for + arrays, structures and unions. + +'computed-expressions' + The set of computed expressions that have been collected at the + current trace frame. The '--comp-print-values' option affects this + set like the '--var-print-values' option affects the + 'explicit-variables' set. See above. + +'registers' + The registers that have been collected at the current trace frame. + For each register collected, the name and current value are + returned. The value is formatted according to the + '--registers-format' option. See the '-data-list-register-values' + command for a list of the allowed formats. The default is 'x'. + +'tvars' + The trace state variables that have been collected at the current + trace frame. For each trace state variable collected, the name and + current value are returned. + +'memory' + The set of memory ranges that have been collected at the current + trace frame. Its content is a list of tuples. Each tuple + represents a collected memory range and has the following fields: + + 'address' + The start address of the memory range, as hexadecimal literal. + + 'length' + The length of the memory range, as decimal literal. + + 'contents' + The contents of the memory block, in hex. This field is only + present if the '--memory-contents' option is specified. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + +The '-trace-list-variables' Command +----------------------------------- + +Synopsis +........ + + -trace-list-variables + + Return a table of all defined trace variables. Each element of the +table has the following fields: + +'name' + The name of the trace variable. This field is always present. + +'initial' + The initial value. This is a 64-bit signed integer. This field is + always present. + +'current' + The value the trace variable has at the moment. This is a 64-bit + signed integer. This field is absent iff current value is not + defined, for example if the trace was never run, or is presently + running. + +GDB Command +........... + +The corresponding GDB command is 'tvariables'. + +Example +....... + + (gdb) + -trace-list-variables + ^done,trace-variables={nr_rows="1",nr_cols="3", + hdr=[{width="15",alignment="-1",col_name="name",colhdr="Name"}, + {width="11",alignment="-1",col_name="initial",colhdr="Initial"}, + {width="11",alignment="-1",col_name="current",colhdr="Current"}], + body=[variable={name="$trace_timestamp",initial="0"} + variable={name="$foo",initial="10",current="15"}]} + (gdb) + +The '-trace-save' Command +------------------------- + +Synopsis +........ + + -trace-save [ -r ] [ -ctf ] FILENAME + + Saves the collected trace data to FILENAME. Without the '-r' option, +the data is downloaded from the target and saved in a local file. With +the '-r' option the target is asked to perform the save. + + By default, this command will save the trace in the tfile format. +You can supply the optional '-ctf' argument to save it the CTF format. +See *note Trace Files:: for more information about CTF. + +GDB Command +........... + +The corresponding GDB command is 'tsave'. + +The '-trace-start' Command +-------------------------- + +Synopsis +........ + + -trace-start + + Starts a tracing experiment. The result of this command does not +have any fields. + +GDB Command +........... + +The corresponding GDB command is 'tstart'. + +The '-trace-status' Command +--------------------------- + +Synopsis +........ + + -trace-status + + Obtains the status of a tracing experiment. The result may include +the following fields: + +'supported' + May have a value of either '0', when no tracing operations are + supported, '1', when all tracing operations are supported, or + 'file' when examining trace file. In the latter case, examining of + trace frame is possible but new tracing experiment cannot be + started. This field is always present. + +'running' + May have a value of either '0' or '1' depending on whether tracing + experiment is in progress on target. This field is present if + 'supported' field is not '0'. + +'stop-reason' + Report the reason why the tracing was stopped last time. This + field may be absent iff tracing was never stopped on target yet. + The value of 'request' means the tracing was stopped as result of + the '-trace-stop' command. The value of 'overflow' means the + tracing buffer is full. The value of 'disconnection' means tracing + was automatically stopped when GDB has disconnected. The value of + 'passcount' means tracing was stopped when a tracepoint was passed + a maximal number of times for that tracepoint. This field is + present if 'supported' field is not '0'. + +'stopping-tracepoint' + The number of tracepoint whose passcount as exceeded. This field + is present iff the 'stop-reason' field has the value of + 'passcount'. + +'frames' +'frames-created' + The 'frames' field is a count of the total number of trace frames + in the trace buffer, while 'frames-created' is the total created + during the run, including ones that were discarded, such as when a + circular trace buffer filled up. Both fields are optional. + +'buffer-size' +'buffer-free' + These fields tell the current size of the tracing buffer and the + remaining space. These fields are optional. + +'circular' + The value of the circular trace buffer flag. '1' means that the + trace buffer is circular and old trace frames will be discarded if + necessary to make room, '0' means that the trace buffer is linear + and may fill up. + +'disconnected' + The value of the disconnected tracing flag. '1' means that tracing + will continue after GDB disconnects, '0' means that the trace run + will stop. + +'trace-file' + The filename of the trace file being examined. This field is + optional, and only present when examining a trace file. + +GDB Command +........... + +The corresponding GDB command is 'tstatus'. + +The '-trace-stop' Command +------------------------- + +Synopsis +........ + + -trace-stop + + Stops a tracing experiment. The result of this command has the same +fields as '-trace-status', except that the 'supported' and 'running' +fields are not output. + +GDB Command +........... + +The corresponding GDB command is 'tstop'. + + +File: gdb.info, Node: GDB/MI Symbol Query, Next: GDB/MI File Commands, Prev: GDB/MI Tracepoint Commands, Up: GDB/MI + +27.18 GDB/MI Symbol Query Commands +================================== + +The '-symbol-info-functions' Command +------------------------------------ + +Synopsis +........ + + -symbol-info-functions [--include-nondebug] + [--type TYPE_REGEXP] + [--name NAME_REGEXP] + [--max-results LIMIT] + +Return a list containing the names and types for all global functions +taken from the debug information. The functions are grouped by source +file, and shown with the line number on which each function is defined. + + The '--include-nondebug' option causes the output to include code +symbols from the symbol table. + + The options '--type' and '--name' allow the symbols returned to be +filtered based on either the name of the function, or the type signature +of the function. + + The option '--max-results' restricts the command to return no more +than LIMIT results. If exactly LIMIT results are returned then there +might be additional results available if a higher limit is used. + +GDB Command +........... + +The corresponding GDB command is 'info functions'. + +Example +....... + + (gdb) + -symbol-info-functions + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="36", name="f4", type="void (int *)", + description="void f4(int *);"}, + {line="42", name="main", type="int ()", + description="int main();"}, + {line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="33", name="f2", type="float (another_float_t)", + description="float f2(another_float_t);"}, + {line="39", name="f3", type="int (another_int_t)", + description="int f3(another_int_t);"}, + {line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"}]}]} + (gdb) + -symbol-info-functions --name f1 + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"}]}]} + (gdb) + -symbol-info-functions --type void + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="36", name="f4", type="void (int *)", + description="void f4(int *);"}]}]} + (gdb) + -symbol-info-functions --include-nondebug + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="36", name="f4", type="void (int *)", + description="void f4(int *);"}, + {line="42", name="main", type="int ()", + description="int main();"}, + {line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="33", name="f2", type="float (another_float_t)", + description="float f2(another_float_t);"}, + {line="39", name="f3", type="int (another_int_t)", + description="int f3(another_int_t);"}, + {line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"}]}], + nondebug= + [{address="0x0000000000400398",name="_init"}, + {address="0x00000000004003b0",name="_start"}, + ... + ]} + +The '-symbol-info-module-functions' Command +------------------------------------------- + +Synopsis +........ + + -symbol-info-module-functions [--module MODULE_REGEXP] + [--name NAME_REGEXP] + [--type TYPE_REGEXP] + +Return a list containing the names of all known functions within all +know Fortran modules. The functions are grouped by source file and +containing module, and shown with the line number on which each function +is defined. + + The option '--module' only returns results for modules matching +MODULE_REGEXP. The option '--name' only returns functions whose name +matches NAME_REGEXP, and '--type' only returns functions whose type +matches TYPE_REGEXP. + +GDB Command +........... + +The corresponding GDB command is 'info module functions'. + +Example +....... + + (gdb) + -symbol-info-module-functions + ^done,symbols= + [{module="mod1", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="21",name="mod1::check_all",type="void (void)", + description="void mod1::check_all(void);"}]}]}, + {module="mod2", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="30",name="mod2::check_var_i",type="void (void)", + description="void mod2::check_var_i(void);"}]}]}, + {module="mod3", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="21",name="mod3::check_all",type="void (void)", + description="void mod3::check_all(void);"}, + {line="27",name="mod3::check_mod2",type="void (void)", + description="void mod3::check_mod2(void);"}]}]}, + {module="modmany", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="35",name="modmany::check_some",type="void (void)", + description="void modmany::check_some(void);"}]}]}, + {module="moduse", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="44",name="moduse::check_all",type="void (void)", + description="void moduse::check_all(void);"}, + {line="49",name="moduse::check_var_x",type="void (void)", + description="void moduse::check_var_x(void);"}]}]}] + +The '-symbol-info-module-variables' Command +------------------------------------------- + +Synopsis +........ + + -symbol-info-module-variables [--module MODULE_REGEXP] + [--name NAME_REGEXP] + [--type TYPE_REGEXP] + +Return a list containing the names of all known variables within all +know Fortran modules. The variables are grouped by source file and +containing module, and shown with the line number on which each variable +is defined. + + The option '--module' only returns results for modules matching +MODULE_REGEXP. The option '--name' only returns variables whose name +matches NAME_REGEXP, and '--type' only returns variables whose type +matches TYPE_REGEXP. + +GDB Command +........... + +The corresponding GDB command is 'info module variables'. + +Example +....... + + (gdb) + -symbol-info-module-variables + ^done,symbols= + [{module="mod1", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="18",name="mod1::var_const",type="integer(kind=4)", + description="integer(kind=4) mod1::var_const;"}, + {line="17",name="mod1::var_i",type="integer(kind=4)", + description="integer(kind=4) mod1::var_i;"}]}]}, + {module="mod2", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="28",name="mod2::var_i",type="integer(kind=4)", + description="integer(kind=4) mod2::var_i;"}]}]}, + {module="mod3", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="18",name="mod3::mod1",type="integer(kind=4)", + description="integer(kind=4) mod3::mod1;"}, + {line="17",name="mod3::mod2",type="integer(kind=4)", + description="integer(kind=4) mod3::mod2;"}, + {line="19",name="mod3::var_i",type="integer(kind=4)", + description="integer(kind=4) mod3::var_i;"}]}]}, + {module="modmany", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="33",name="modmany::var_a",type="integer(kind=4)", + description="integer(kind=4) modmany::var_a;"}, + {line="33",name="modmany::var_b",type="integer(kind=4)", + description="integer(kind=4) modmany::var_b;"}, + {line="33",name="modmany::var_c",type="integer(kind=4)", + description="integer(kind=4) modmany::var_c;"}, + {line="33",name="modmany::var_i",type="integer(kind=4)", + description="integer(kind=4) modmany::var_i;"}]}]}, + {module="moduse", + files=[{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="42",name="moduse::var_x",type="integer(kind=4)", + description="integer(kind=4) moduse::var_x;"}, + {line="42",name="moduse::var_y",type="integer(kind=4)", + description="integer(kind=4) moduse::var_y;"}]}]}] + +The '-symbol-info-modules' Command +---------------------------------- + +Synopsis +........ + + -symbol-info-modules [--name NAME_REGEXP] + [--max-results LIMIT] + + +Return a list containing the names of all known Fortran modules. The +modules are grouped by source file, and shown with the line number on +which each modules is defined. + + The option '--name' allows the modules returned to be filtered based +the name of the module. + + The option '--max-results' restricts the command to return no more +than LIMIT results. If exactly LIMIT results are returned then there +might be additional results available if a higher limit is used. + +GDB Command +........... + +The corresponding GDB command is 'info modules'. + +Example +....... + + (gdb) + -symbol-info-modules + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="16",name="mod1"}, + {line="22",name="mod2"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="16",name="mod3"}, + {line="22",name="modmany"}, + {line="26",name="moduse"}]}]} + (gdb) + -symbol-info-modules --name mod[123] + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[{line="16",name="mod1"}, + {line="22",name="mod2"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[{line="16",name="mod3"}]}]} + +The '-symbol-info-types' Command +-------------------------------- + +Synopsis +........ + + -symbol-info-types [--name NAME_REGEXP] + [--max-results LIMIT] + + +Return a list of all defined types. The types are grouped by source +file, and shown with the line number on which each user defined type is +defined. Some base types are not defined in the source code but are +added to the debug information by the compiler, for example 'int', +'float', etc.; these types do not have an associated line number. + + The option '--name' allows the list of types returned to be filtered +by name. + + The option '--max-results' restricts the command to return no more +than LIMIT results. If exactly LIMIT results are returned then there +might be additional results available if a higher limit is used. + +GDB Command +........... + +The corresponding GDB command is 'info types'. + +Example +....... + + (gdb) + -symbol-info-types + ^done,symbols= + {debug= + [{filename="gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{name="float"}, + {name="int"}, + {line="27",name="typedef int my_int_t;"}]}, + {filename="gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb.mi/mi-sym-info-2.c", + symbols=[{line="24",name="typedef float another_float_t;"}, + {line="23",name="typedef int another_int_t;"}, + {name="float"}, + {name="int"}]}]} + (gdb) + -symbol-info-types --name _int_ + ^done,symbols= + {debug= + [{filename="gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="27",name="typedef int my_int_t;"}]}, + {filename="gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb.mi/mi-sym-info-2.c", + symbols=[{line="23",name="typedef int another_int_t;"}]}]} + +The '-symbol-info-variables' Command +------------------------------------ + +Synopsis +........ + + -symbol-info-variables [--include-nondebug] + [--type TYPE_REGEXP] + [--name NAME_REGEXP] + [--max-results LIMIT] + + +Return a list containing the names and types for all global variables +taken from the debug information. The variables are grouped by source +file, and shown with the line number on which each variable is defined. + + The '--include-nondebug' option causes the output to include data +symbols from the symbol table. + + The options '--type' and '--name' allow the symbols returned to be +filtered based on either the name of the variable, or the type of the +variable. + + The option '--max-results' restricts the command to return no more +than LIMIT results. If exactly LIMIT results are returned then there +might be additional results available if a higher limit is used. + +GDB Command +........... + +The corresponding GDB command is 'info variables'. + +Example +....... + + (gdb) + -symbol-info-variables + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="25",name="global_f1",type="float", + description="static float global_f1;"}, + {line="24",name="global_i1",type="int", + description="static int global_i1;"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="21",name="global_f2",type="int", + description="int global_f2;"}, + {line="20",name="global_i2",type="int", + description="int global_i2;"}, + {line="19",name="global_f1",type="float", + description="static float global_f1;"}, + {line="18",name="global_i1",type="int", + description="static int global_i1;"}]}]} + (gdb) + -symbol-info-variables --name f1 + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="25",name="global_f1",type="float", + description="static float global_f1;"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="19",name="global_f1",type="float", + description="static float global_f1;"}]}]} + (gdb) + -symbol-info-variables --type float + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="25",name="global_f1",type="float", + description="static float global_f1;"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="19",name="global_f1",type="float", + description="static float global_f1;"}]}]} + (gdb) + -symbol-info-variables --include-nondebug + ^done,symbols= + {debug= + [{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[{line="25",name="global_f1",type="float", + description="static float global_f1;"}, + {line="24",name="global_i1",type="int", + description="static int global_i1;"}]}, + {filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[{line="21",name="global_f2",type="int", + description="int global_f2;"}, + {line="20",name="global_i2",type="int", + description="int global_i2;"}, + {line="19",name="global_f1",type="float", + description="static float global_f1;"}, + {line="18",name="global_i1",type="int", + description="static int global_i1;"}]}], + nondebug= + [{address="0x00000000004005d0",name="_IO_stdin_used"}, + {address="0x00000000004005d8",name="__dso_handle"} + ... + ]} + +The '-symbol-list-lines' Command +-------------------------------- + +Synopsis +........ + + -symbol-list-lines FILENAME + + Print the list of lines that contain code and their associated +program addresses for the given source filename. The entries are sorted +in ascending PC order. + +GDB Command +........... + +There is no corresponding GDB command. + +Example +....... + + (gdb) + -symbol-list-lines basics.c + ^done,lines=[{pc="0x08048554",line="7"},{pc="0x0804855a",line="8"}] + (gdb) + + +File: gdb.info, Node: GDB/MI File Commands, Next: GDB/MI Target Manipulation, Prev: GDB/MI Symbol Query, Up: GDB/MI + +27.19 GDB/MI File Commands +========================== + +This section describes the GDB/MI commands to specify executable file +names and to read in and obtain symbol table information. + +The '-file-exec-and-symbols' Command +------------------------------------ + +Synopsis +........ + + -file-exec-and-symbols FILE + + Specify the executable file to be debugged. This file is the one +from which the symbol table is also read. If no file is specified, the +command clears the executable and symbol information. If breakpoints +are set when using this command with no arguments, GDB will produce +error messages. Otherwise, no output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'file'. + +Example +....... + + (gdb) + -file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-exec-file' Command +----------------------------- + +Synopsis +........ + + -file-exec-file FILE + + Specify the executable file to be debugged. Unlike +'-file-exec-and-symbols', the symbol table is _not_ read from this file. +If used without argument, GDB clears the information about the +executable file. No output is produced, except a completion +notification. + +GDB Command +........... + +The corresponding GDB command is 'exec-file'. + +Example +....... + + (gdb) + -file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + +The '-file-list-exec-source-file' Command +----------------------------------------- + +Synopsis +........ + + -file-list-exec-source-file + + List the line number, the current source file, and the absolute path +to the current source file for the current executable. The macro +information field has a value of '1' or '0' depending on whether or not +the file includes preprocessor macro information. + +GDB Command +........... + +The GDB equivalent is 'info source' + +Example +....... + + (gdb) + 123-file-list-exec-source-file + 123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" + (gdb) + +The '-file-list-exec-source-files' Command +------------------------------------------ + +Synopsis +........ + + -file-list-exec-source-files [ --GROUP-BY-OBJFILE ] + [ --DIRNAME | --BASENAME ] + [ -- ] + [ REGEXP ] + + This command returns information about the source files GDB knows +about, it will output both the filename and fullname (absolute file +name) of a source file, though the fullname can be elided if this +information is not known to GDB. + + With no arguments this command returns a list of source files. Each +source file is represented by a tuple with the fields; FILE, FULLNAME, +and DEBUG-FULLY-READ. The FILE is the display name for the file, while +FULLNAME is the absolute name of the file. The FULLNAME field can be +elided if the absolute name of the source file can't be computed. The +field DEBUG-FULLY-READ will be a string, either 'true' or 'false'. When +'true', this indicates the full debug information for the compilation +unit describing this file has been read in. When 'false', the full +debug information has not yet been read in. While reading in the full +debug information it is possible that GDB could become aware of +additional source files. + + The optional REGEXP can be used to filter the list of source files +returned. The REGEXP will be matched against the full source file name. +The matching is case-sensitive, except on operating systems that have +case-insensitive filesystem (e.g., MS-Windows). '--' can be used before +REGEXP to prevent GDB interpreting REGEXP as a command option (e.g. if +REGEXP starts with '-'). + + If '--dirname' is provided, then REGEXP is matched only against the +directory name of each source file. If '--basename' is provided, then +REGEXP is matched against the basename of each source file. Only one of +'--dirname' or '--basename' may be given, and if either is given then +REGEXP is required. + + If '--group-by-objfile' is used then the format of the results is +changed. The results will now be a list of tuples, with each tuple +representing an object file (executable or shared library) loaded into +GDB. The fields of these tuples are; FILENAME, DEBUG-INFO, and SOURCES. +The FILENAME is the absolute name of the object file, DEBUG-INFO is a +string with one of the following values: + +'none' + This object file has no debug information. +'partially-read' + This object file has debug information, but it is not fully read in + yet. When it is read in later, GDB might become aware of + additional source files. +'fully-read' + This object file has debug information, and this information is + fully read into GDB. The list of source files is complete. + + The SOURCES is a list or tuples, with each tuple describing a single +source file with the same fields as described previously. The SOURCES +list can be empty for object files that have no debug information. + +GDB Command +........... + +The GDB equivalent is 'info sources'. 'gdbtk' has an analogous command +'gdb_listfiles'. + +Example +....... + + (gdb) + -file-list-exec-source-files + ^done,files=[{file="foo.c",fullname="/home/foo.c",debug-fully-read="true"}, + {file="/home/bar.c",fullname="/home/bar.c",debug-fully-read="true"}, + {file="gdb_could_not_find_fullpath.c",debug-fully-read="true"}] + (gdb) + -file-list-exec-source-files + ^done,files=[{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"}, + {file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"}, + {file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"}, + {file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"}] + (gdb) + -file-list-exec-source-files -- \\.c + ^done,files=[{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"}, + {file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"}] + (gdb) + -file-list-exec-source-files --group-by-objfile + ^done,files=[{filename="/tmp/info-sources/test.x", + debug-info="fully-read", + sources=[{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"}, + {file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"}, + {file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"}]}, + {filename="/lib64/ld-linux-x86-64.so.2", + debug-info="none", + sources=[]}, + {filename="system-supplied DSO at 0x7ffff7fcf000", + debug-info="none", + sources=[]}, + {filename="/tmp/info-sources/libhelper.so", + debug-info="fully-read", + sources=[{file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"}, + {file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"}, + {file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"}]}, + {filename="/lib64/libc.so.6", + debug-info="none", + sources=[]}] + +The '-file-list-shared-libraries' Command +----------------------------------------- + +Synopsis +........ + + -file-list-shared-libraries [ REGEXP ] + + List the shared libraries in the program. With a regular expression +REGEXP, only those libraries whose names match REGEXP are listed. + +GDB Command +........... + +The corresponding GDB command is 'info shared'. The fields have a +similar meaning to the '=library-loaded' notification. The 'ranges' +field specifies the multiple segments belonging to this library. Each +range has the following fields: + +'from' + The address defining the inclusive lower bound of the segment. +'to' + The address defining the exclusive upper bound of the segment. + +Example +....... + + (gdb) + -file-list-exec-source-files + ^done,shared-libraries=[ + {id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x72815989",to="0x728162c0"}]}, + {id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[{from="0x76ee48c0",to="0x76ee9160"}]}] + (gdb) + +The '-file-symbol-file' Command +------------------------------- + +Synopsis +........ + + -file-symbol-file FILE + + Read symbol table info from the specified FILE argument. When used +without arguments, clears GDB's symbol table info. No output is +produced, except for a completion notification. + +GDB Command +........... + +The corresponding GDB command is 'symbol-file'. + +Example +....... + + (gdb) + -file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Target Manipulation, Next: GDB/MI File Transfer Commands, Prev: GDB/MI File Commands, Up: GDB/MI + +27.20 GDB/MI Target Manipulation Commands +========================================= + +The '-target-attach' Command +---------------------------- + +Synopsis +........ + + -target-attach PID | GID | FILE + + Attach to a process PID or a file FILE outside of GDB, or a thread +group GID. If attaching to a thread group, the id previously returned +by '-list-thread-groups --available' must be used. + +GDB Command +........... + +The corresponding GDB command is 'attach'. + +Example +....... + + (gdb) + -target-attach 34 + =thread-created,id="1" + *stopped,thread-id="1",frame={addr="0xb7f7e410",func="bar",args=[]} + ^done + (gdb) + +The '-target-detach' Command +---------------------------- + +Synopsis +........ + + -target-detach [ PID | GID ] + + Detach from the remote target which normally resumes its execution. +If either PID or GID is specified, detaches from either the specified +process, or specified thread group. There's no output. + +GDB Command +........... + +The corresponding GDB command is 'detach'. + +Example +....... + + (gdb) + -target-detach + ^done + (gdb) + +The '-target-disconnect' Command +-------------------------------- + +Synopsis +........ + + -target-disconnect + + Disconnect from the remote target. There's no output and the target +is generally not resumed. + +GDB Command +........... + +The corresponding GDB command is 'disconnect'. + +Example +....... + + (gdb) + -target-disconnect + ^done + (gdb) + +The '-target-download' Command +------------------------------ + +Synopsis +........ + + -target-download + + Loads the executable onto the remote target. It prints out an update +message every half second, which includes the fields: + +'section' + The name of the section. +'section-sent' + The size of what has been sent so far for that section. +'section-size' + The size of the section. +'total-sent' + The total size of what was sent so far (the current and the + previous sections). +'total-size' + The size of the overall executable to download. + +Each message is sent as status record (*note GDB/MI Output Syntax: +GDB/MI Output Syntax.). + + In addition, it prints the name and size of the sections, as they are +downloaded. These messages include the following fields: + +'section' + The name of the section. +'section-size' + The size of the section. +'total-size' + The size of the overall executable to download. + +At the end, a summary is printed. + +GDB Command +........... + +The corresponding GDB command is 'load'. + +Example +....... + +Note: each status message appears on a single line. Here the messages +have been broken down so that they can fit onto a page. + + (gdb) + -target-download + +download,{section=".text",section-size="6668",total-size="9880"} + +download,{section=".text",section-sent="512",section-size="6668", + total-sent="512",total-size="9880"} + +download,{section=".text",section-sent="1024",section-size="6668", + total-sent="1024",total-size="9880"} + +download,{section=".text",section-sent="1536",section-size="6668", + total-sent="1536",total-size="9880"} + +download,{section=".text",section-sent="2048",section-size="6668", + total-sent="2048",total-size="9880"} + +download,{section=".text",section-sent="2560",section-size="6668", + total-sent="2560",total-size="9880"} + +download,{section=".text",section-sent="3072",section-size="6668", + total-sent="3072",total-size="9880"} + +download,{section=".text",section-sent="3584",section-size="6668", + total-sent="3584",total-size="9880"} + +download,{section=".text",section-sent="4096",section-size="6668", + total-sent="4096",total-size="9880"} + +download,{section=".text",section-sent="4608",section-size="6668", + total-sent="4608",total-size="9880"} + +download,{section=".text",section-sent="5120",section-size="6668", + total-sent="5120",total-size="9880"} + +download,{section=".text",section-sent="5632",section-size="6668", + total-sent="5632",total-size="9880"} + +download,{section=".text",section-sent="6144",section-size="6668", + total-sent="6144",total-size="9880"} + +download,{section=".text",section-sent="6656",section-size="6668", + total-sent="6656",total-size="9880"} + +download,{section=".init",section-size="28",total-size="9880"} + +download,{section=".fini",section-size="28",total-size="9880"} + +download,{section=".data",section-size="3156",total-size="9880"} + +download,{section=".data",section-sent="512",section-size="3156", + total-sent="7236",total-size="9880"} + +download,{section=".data",section-sent="1024",section-size="3156", + total-sent="7748",total-size="9880"} + +download,{section=".data",section-sent="1536",section-size="3156", + total-sent="8260",total-size="9880"} + +download,{section=".data",section-sent="2048",section-size="3156", + total-sent="8772",total-size="9880"} + +download,{section=".data",section-sent="2560",section-size="3156", + total-sent="9284",total-size="9880"} + +download,{section=".data",section-sent="3072",section-size="3156", + total-sent="9796",total-size="9880"} + ^done,address="0x10004",load-size="9880",transfer-rate="6586", + write-rate="429" + (gdb) + +GDB Command +........... + +No equivalent. + +Example +....... + +N.A. + +The '-target-flash-erase' Command +--------------------------------- + +Synopsis +........ + + -target-flash-erase + + Erases all known flash memory regions on the target. + + The corresponding GDB command is 'flash-erase'. + + The output is a list of flash regions that have been erased, with +starting addresses and memory region sizes. + + (gdb) + -target-flash-erase + ^done,erased-regions={address="0x0",size="0x40000"} + (gdb) + +The '-target-select' Command +---------------------------- + +Synopsis +........ + + -target-select TYPE PARAMETERS ... + + Connect GDB to the remote target. This command takes two args: + +'TYPE' + The type of target, for instance 'remote', etc. +'PARAMETERS' + Device names, host names and the like. *Note Commands for Managing + Targets: Target Commands, for more details. + + The output is a connection notification, followed by the address at +which the target program is, in the following form: + + ^connected,addr="ADDRESS",func="FUNCTION NAME", + args=[ARG LIST] + +GDB Command +........... + +The corresponding GDB command is 'target'. + +Example +....... + + (gdb) + -target-select remote /dev/ttya + ^connected,addr="0xfe00a300",func="??",args=[] + (gdb) + + +File: gdb.info, Node: GDB/MI File Transfer Commands, Next: GDB/MI Ada Exceptions Commands, Prev: GDB/MI Target Manipulation, Up: GDB/MI + +27.21 GDB/MI File Transfer Commands +=================================== + +The '-target-file-put' Command +------------------------------ + +Synopsis +........ + + -target-file-put HOSTFILE TARGETFILE + + Copy file HOSTFILE from the host system (the machine running GDB) to +TARGETFILE on the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote put'. + +Example +....... + + (gdb) + -target-file-put localfile remotefile + ^done + (gdb) + +The '-target-file-get' Command +------------------------------ + +Synopsis +........ + + -target-file-get TARGETFILE HOSTFILE + + Copy file TARGETFILE from the target system to HOSTFILE on the host +system. + +GDB Command +........... + +The corresponding GDB command is 'remote get'. + +Example +....... + + (gdb) + -target-file-get remotefile localfile + ^done + (gdb) + +The '-target-file-delete' Command +--------------------------------- + +Synopsis +........ + + -target-file-delete TARGETFILE + + Delete TARGETFILE from the target system. + +GDB Command +........... + +The corresponding GDB command is 'remote delete'. + +Example +....... + + (gdb) + -target-file-delete remotefile + ^done + (gdb) + + +File: gdb.info, Node: GDB/MI Ada Exceptions Commands, Next: GDB/MI Support Commands, Prev: GDB/MI File Transfer Commands, Up: GDB/MI + +27.22 Ada Exceptions GDB/MI Commands +==================================== + +The '-info-ada-exceptions' Command +---------------------------------- + +Synopsis +........ + + -info-ada-exceptions [ REGEXP] + + List all Ada exceptions defined within the program being debugged. +With a regular expression REGEXP, only those exceptions whose names +match REGEXP are listed. + +GDB Command +........... + +The corresponding GDB command is 'info exceptions'. + +Result +...... + +The result is a table of Ada exceptions. The following columns are +defined for each exception: + +'name' + The name of the exception. + +'address' + The address of the exception. + +Example +....... + + -info-ada-exceptions aint + ^done,ada-exceptions={nr_rows="2",nr_cols="2", + hdr=[{width="1",alignment="-1",col_name="name",colhdr="Name"}, + {width="1",alignment="-1",col_name="address",colhdr="Address"}], + body=[{name="constraint_error",address="0x0000000000613da0"}, + {name="const.aint_global_e",address="0x0000000000613b00"}]} + +Catching Ada Exceptions +----------------------- + +The commands describing how to ask GDB to stop when a program raises an +exception are described at *note Ada Exception GDB/MI Catchpoint +Commands::. + + +File: gdb.info, Node: GDB/MI Support Commands, Next: GDB/MI Miscellaneous Commands, Prev: GDB/MI Ada Exceptions Commands, Up: GDB/MI + +27.23 GDB/MI Support Commands +============================= + +Since new commands and features get regularly added to GDB/MI, some +commands are available to help front-ends query the debugger about +support for these capabilities. Similarly, it is also possible to query +GDB about target support of certain features. + +The '-info-gdb-mi-command' Command +---------------------------------- + +Synopsis +........ + + -info-gdb-mi-command CMD_NAME + + Query support for the GDB/MI command named CMD_NAME. + + Note that the dash ('-') starting all GDB/MI commands is technically +not part of the command name (*note GDB/MI Input Syntax::), and thus +should be omitted in CMD_NAME. However, for ease of use, this command +also accepts the form with the leading dash. + +GDB Command +........... + +There is no corresponding GDB command. + +Result +...... + +The result is a tuple. There is currently only one field: + +'exists' + This field is equal to '"true"' if the GDB/MI command exists, + '"false"' otherwise. + +Example +....... + +Here is an example where the GDB/MI command does not exist: + + -info-gdb-mi-command unsupported-command + ^done,command={exists="false"} + +And here is an example where the GDB/MI command is known to the +debugger: + + -info-gdb-mi-command symbol-list-lines + ^done,command={exists="true"} + +The '-list-features' Command +---------------------------- + +Returns a list of particular features of the MI protocol that this +version of gdb implements. A feature can be a command, or a new field +in an output of some command, or even an important bugfix. While a +frontend can sometimes detect presence of a feature at runtime, it is +easier to perform detection at debugger startup. + + The command returns a list of strings, with each string naming an +available feature. Each returned string is just a name, it does not +have any internal structure. The list of possible feature names is +given below. + + Example output: + + (gdb) -list-features + ^done,result=["feature1","feature2"] + + The current list of features is: + +'frozen-varobjs' + Indicates support for the '-var-set-frozen' command, as well as + possible presence of the 'frozen' field in the output of + '-varobj-create'. +'pending-breakpoints' + Indicates support for the '-f' option to the '-break-insert' + command. +'python' + Indicates Python scripting support, Python-based pretty-printing + commands, and possible presence of the 'display_hint' field in the + output of '-var-list-children' +'thread-info' + Indicates support for the '-thread-info' command. +'data-read-memory-bytes' + Indicates support for the '-data-read-memory-bytes' and the + '-data-write-memory-bytes' commands. +'breakpoint-notifications' + Indicates that changes to breakpoints and breakpoints created via + the CLI will be announced via async records. +'ada-task-info' + Indicates support for the '-ada-task-info' command. +'language-option' + Indicates that all GDB/MI commands accept the '--language' option + (*note Context management::). +'info-gdb-mi-command' + Indicates support for the '-info-gdb-mi-command' command. +'undefined-command-error-code' + Indicates support for the "undefined-command" error code in error + result records, produced when trying to execute an undefined GDB/MI + command (*note GDB/MI Result Records::). +'exec-run-start-option' + Indicates that the '-exec-run' command supports the '--start' + option (*note GDB/MI Program Execution::). +'data-disassemble-a-option' + Indicates that the '-data-disassemble' command supports the '-a' + option (*note GDB/MI Data Manipulation::). +'simple-values-ref-types' + Indicates that the '--simple-values' argument to the + '-stack-list-arguments', '-stack-list-locals', + '-stack-list-variables', and '-var-list-children' commands takes + reference types into account: that is, a value is considered simple + if it is neither an array, structure, or union, nor a reference to + an array, structure, or union. + +The '-list-target-features' Command +----------------------------------- + +Returns a list of particular features that are supported by the target. +Those features affect the permitted MI commands, but unlike the features +reported by the '-list-features' command, the features depend on which +target GDB is using at the moment. Whenever a target can change, due to +commands such as '-target-select', '-target-attach' or '-exec-run', the +list of target features may change, and the frontend should obtain it +again. Example output: + + (gdb) -list-target-features + ^done,result=["async"] + + The current list of features is: + +'async' + Indicates that the target is capable of asynchronous command + execution, which means that GDB will accept further commands while + the target is running. + +'reverse' + Indicates that the target is capable of reverse execution. *Note + Reverse Execution::, for more information. + diff -pruN 16.3-5/gdb/doc/gdb.info-7 16.3-5ubuntu1/gdb/doc/gdb.info-7 --- 16.3-5/gdb/doc/gdb.info-7 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-7 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,7730 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: GDB/MI Miscellaneous Commands, Prev: GDB/MI Support Commands, Up: GDB/MI + +27.24 Miscellaneous GDB/MI Commands +=================================== + +The '-gdb-exit' Command +----------------------- + +Synopsis +........ + + -gdb-exit + + Exit GDB immediately. + +GDB Command +........... + +Approximately corresponds to 'quit'. + +Example +....... + + (gdb) + -gdb-exit + ^exit + +The '-gdb-set' Command +---------------------- + +Synopsis +........ + + -gdb-set + + Set an internal GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'set'. + +Example +....... + + (gdb) + -gdb-set $foo=3 + ^done + (gdb) + +The '-gdb-show' Command +----------------------- + +Synopsis +........ + + -gdb-show + + Show the current value of a GDB variable. + +GDB Command +........... + +The corresponding GDB command is 'show'. + +Example +....... + + (gdb) + -gdb-show annotate + ^done,value="0" + (gdb) + +The '-gdb-version' Command +-------------------------- + +Synopsis +........ + + -gdb-version + + Show version information for GDB. Used mostly in testing. + +GDB Command +........... + +The GDB equivalent is 'show version'. GDB by default shows this +information when you start an interactive session. + +Example +....... + + (gdb) + -gdb-version + ~GNU gdb 5.2.1 + ~Copyright 2000 Free Software Foundation, Inc. + ~GDB is free software, covered by the GNU General Public License, and + ~you are welcome to change it and/or distribute copies of it under + ~ certain conditions. + ~Type "show copying" to see the conditions. + ~There is absolutely no warranty for GDB. Type "show warranty" for + ~ details. + ~This GDB was configured as + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". + ^done + (gdb) + +The '-list-thread-groups' Command +--------------------------------- + +Synopsis +........ + + -list-thread-groups [ --available ] [ --recurse 1 ] [ GROUP ... ] + + Lists thread groups (*note Thread groups::). When a single thread +group is passed as the argument, lists the children of that group. When +several thread group are passed, lists information about those thread +groups. Without any parameters, lists information about all top-level +thread groups. + + Normally, thread groups that are being debugged are reported. With +the '--available' option, GDB reports thread groups available on the +target. + + The output of this command may have either a 'threads' result or a +'groups' result. The 'thread' result has a list of tuples as value, +with each tuple describing a thread (*note GDB/MI Thread Information::). +The 'groups' result has a list of tuples as value, each tuple describing +a thread group. If top-level groups are requested (that is, no +parameter is passed), or when several groups are passed, the output +always has a 'groups' result. The format of the 'group' result is +described below. + + To reduce the number of roundtrips it's possible to list thread +groups together with their children, by passing the '--recurse' option +and the recursion depth. Presently, only recursion depth of 1 is +permitted. If this option is present, then every reported thread group +will also include its children, either as 'group' or 'threads' field. + + In general, any combination of option and parameters is permitted, +with the following caveats: + + * When a single thread group is passed, the output will typically be + the 'threads' result. Because threads may not contain anything, + the 'recurse' option will be ignored. + + * When the '--available' option is passed, limited information may be + available. In particular, the list of threads of a process might + be inaccessible. Further, specifying specific thread groups might + not give any performance advantage over listing all thread groups. + The frontend should assume that '-list-thread-groups --available' + is always an expensive operation and cache the results. + + The 'groups' result is a list of tuples, where each tuple may have +the following fields: + +'id' + Identifier of the thread group. This field is always present. The + identifier is an opaque string; frontends should not try to convert + it to an integer, even though it might look like one. + +'type' + The type of the thread group. At present, only 'process' is a + valid type. + +'pid' + The target-specific process identifier. This field is only present + for thread groups of type 'process' and only if the process exists. + +'exit-code' + The exit code of this group's last exited thread, formatted in + octal. This field is only present for thread groups of type + 'process' and only if the process is not running. + +'num_children' + The number of children this thread group has. This field may be + absent for an available thread group. + +'threads' + This field has a list of tuples as value, each tuple describing a + thread. It may be present if the '--recurse' option is specified, + and it's actually possible to obtain the threads. + +'cores' + This field is a list of integers, each identifying a core that one + thread of the group is running on. This field may be absent if + such information is not available. + +'executable' + The name of the executable file that corresponds to this thread + group. The field is only present for thread groups of type + 'process', and only if there is a corresponding executable file. + +Example +....... + + (gdb) + -list-thread-groups + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2"}] + -list-thread-groups 17 + ^done,threads=[{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame={level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]},state="running"}, + {id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame={level="0",addr="0x0804891f",func="foo",args=[{name="i",value="10"}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"},state="running"}]] + -list-thread-groups --available + ^done,groups=[{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]}] + -list-thread-groups --available --recurse 1 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},..] + -list-thread-groups --available --recurse 1 17 18 + ^done,groups=[{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[{id="1",target-id="Thread 0xb7e14b90",cores=[1]}, + {id="2",target-id="Thread 0xb7e14b90",cores=[2]}]},...] + +The '-info-os' Command +---------------------- + +Synopsis +........ + + -info-os [ TYPE ] + + If no argument is supplied, the command returns a table of available +operating-system-specific information types. If one of these types is +supplied as an argument TYPE, then the command returns a table of data +of that type. + + The types of information available depend on the target operating +system. + +GDB Command +........... + +The corresponding GDB command is 'info os'. + +Example +....... + +When run on a GNU/Linux system, the output will look something like +this: + + (gdb) + -info-os + ^done,OSDataTable={nr_rows="10",nr_cols="3", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="Type"}, + {width="10",alignment="-1",col_name="col1",colhdr="Description"}, + {width="10",alignment="-1",col_name="col2",colhdr="Title"}], + body=[item={col0="cpus",col1="Listing of all cpus/cores on the system", + col2="CPUs"}, + item={col0="files",col1="Listing of all file descriptors", + col2="File descriptors"}, + item={col0="modules",col1="Listing of all loaded kernel modules", + col2="Kernel modules"}, + item={col0="msg",col1="Listing of all message queues", + col2="Message queues"}, + item={col0="processes",col1="Listing of all processes", + col2="Processes"}, + item={col0="procgroups",col1="Listing of all process groups", + col2="Process groups"}, + item={col0="semaphores",col1="Listing of all semaphores", + col2="Semaphores"}, + item={col0="shm",col1="Listing of all shared-memory regions", + col2="Shared-memory regions"}, + item={col0="sockets",col1="Listing of all internet-domain sockets", + col2="Sockets"}, + item={col0="threads",col1="Listing of all threads", + col2="Threads"}] + (gdb) + -info-os processes + ^done,OSDataTable={nr_rows="190",nr_cols="4", + hdr=[{width="10",alignment="-1",col_name="col0",colhdr="pid"}, + {width="10",alignment="-1",col_name="col1",colhdr="user"}, + {width="10",alignment="-1",col_name="col2",colhdr="command"}, + {width="10",alignment="-1",col_name="col3",colhdr="cores"}], + body=[item={col0="1",col1="root",col2="/sbin/init",col3="0"}, + item={col0="2",col1="root",col2="[kthreadd]",col3="1"}, + item={col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"}, + ... + item={col0="26446",col1="stan",col2="bash",col3="0"}, + item={col0="28152",col1="stan",col2="bash",col3="1"}]} + (gdb) + + (Note that the MI output here includes a '"Title"' column that does +not appear in command-line 'info os'; this column is useful for MI +clients that want to enumerate the types of data, such as in a popup +menu, but is needless clutter on the command line, and 'info os' omits +it.) + +The '-add-inferior' Command +--------------------------- + +Synopsis +........ + + -add-inferior [ --no-connection ] + + Creates a new inferior (*note Inferiors Connections and Programs::). +The created inferior is not associated with any executable. Such +association may be established with the '-file-exec-and-symbols' command +(*note GDB/MI File Commands::). + + By default, the new inferior begins connected to the same target +connection as the current inferior. For example, if the current +inferior was connected to 'gdbserver' with 'target remote', then the new +inferior will be connected to the same 'gdbserver' instance. The +'--no-connection' option starts the new inferior with no connection yet. +You can then for example use the '-target-select remote' command to +connect to some other 'gdbserver' instance, use '-exec-run' to spawn a +local program, etc. + + The command response always has a field, INFERIOR, whose value is the +identifier of the thread group corresponding to the new inferior. + + An additional section field, CONNECTION, is optional. This field +will only exist if the new inferior has a target connection. If this +field exists, then its value will be a tuple containing the following +fields: + +'number' + The number of the connection used for the new inferior. + +'name' + The name of the connection type used for the new inferior. + +GDB Command +........... + +The corresponding GDB command is 'add-inferior' (*note 'add-inferior': +add_inferior_cli.). + +Example +....... + + (gdb) + -add-inferior + ^done,inferior="i3" + +The '-remove-inferior' Command +------------------------------ + +Synopsis +........ + + -remove-inferior INFERIOR-ID + + Removes an inferior (*note Inferiors Connections and Programs::). +Only inferiors that have exited can be removed. The INFERIOR-ID is the +inferior to be removed, and should be the same id string as returned by +the '-add-inferior' command. + + When an inferior is successfully removed a '=thread-group-removed' +notification (*note GDB/MI Async Records::) is emitted, the ID field of +which contains the INFERIOR-ID for the removed inferior. + +GDB Command +........... + +The corresponding GDB command is 'remove-inferiors' (*note +'remove-inferiors': remove_inferiors_cli.). + +Example +....... + + (gdb) + -remove-inferior i3 + =thread-group-removed,id="i3" + ^done + +The '-interpreter-exec' Command +------------------------------- + +Synopsis +........ + + -interpreter-exec INTERPRETER COMMAND + + Execute the specified COMMAND in the given INTERPRETER. + +GDB Command +........... + +The corresponding GDB command is 'interpreter-exec'. + +Example +....... + + (gdb) + -interpreter-exec console "break main" + &"During symbol reading, couldn't parse type; debugger out of date?.\n" + &"During symbol reading, bad structure-type format.\n" + ~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" + ^done + (gdb) + +The '-inferior-tty-set' Command +------------------------------- + +Synopsis +........ + + -inferior-tty-set /dev/pts/1 + + Set terminal for future runs of the program being debugged. + +GDB Command +........... + +The corresponding GDB command is 'set inferior-tty' /dev/pts/1. + +Example +....... + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + +The '-inferior-tty-show' Command +-------------------------------- + +Synopsis +........ + + -inferior-tty-show + + Show terminal for future runs of program being debugged. + +GDB Command +........... + +The corresponding GDB command is 'show inferior-tty'. + +Example +....... + + (gdb) + -inferior-tty-set /dev/pts/1 + ^done + (gdb) + -inferior-tty-show + ^done,inferior_tty_terminal="/dev/pts/1" + (gdb) + +The '-enable-timings' Command +----------------------------- + +Synopsis +........ + + -enable-timings [yes | no] + + Toggle the printing of the wallclock, user and system times for an MI +command as a field in its output. This command is to help frontend +developers optimize the performance of their code. No argument is +equivalent to 'yes'. + +GDB Command +........... + +No equivalent. + +Example +....... + + (gdb) + -enable-timings + ^done + (gdb) + -break-insert main + ^done,bkpt={number="1",type="breakpoint",disp="keep",enabled="y", + addr="0x080484ed",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], + times="0"}, + time={wallclock="0.05185",user="0.00800",system="0.00000"} + (gdb) + -enable-timings no + ^done + (gdb) + -exec-run + ^running + (gdb) + *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame={addr="0x080484ed",func="main",args=[{name="argc",value="1"}, + {name="argv",value="0xbfb60364"}],file="myprog.c", + fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"} + (gdb) + +The '-complete' Command +----------------------- + +Synopsis +........ + + -complete COMMAND + + Show a list of completions for partially typed CLI COMMAND. + + This command is intended for GDB/MI frontends that cannot use two +separate CLI and MI channels -- for example: because of lack of PTYs +like on Windows or because GDB is used remotely via a SSH connection. + +Result +...... + +The result consists of two or three fields: + +'completion' + This field contains the completed COMMAND. If COMMAND has no known + completions, this field is omitted. + +'matches' + This field contains a (possibly empty) array of matches. It is + always present. + +'max_completions_reached' + This field contains '1' if number of known completions is above + 'max-completions' limit (*note Completion::), otherwise it contains + '0'. It is always present. + +GDB Command +........... + +The corresponding GDB command is 'complete'. + +Example +....... + + (gdb) + -complete br + ^done,completion="break", + matches=["break","break-range"], + max_completions_reached="0" + (gdb) + -complete "b ma" + ^done,completion="b ma", + matches=["b madvise","b main"],max_completions_reached="0" + (gdb) + -complete "b push_b" + ^done,completion="b push_back(", + matches=[ + "b A::push_back(void*)", + "b std::string::push_back(char)", + "b std::vector >::push_back(int&&)"], + max_completions_reached="0" + (gdb) + -complete "nonexist" + ^done,matches=[],max_completions_reached="0" + (gdb) + + + +File: gdb.info, Node: Annotations, Next: Debugger Adapter Protocol, Prev: GDB/MI, Up: Top + +28 GDB Annotations +****************** + +This chapter describes annotations in GDB. Annotations were designed to +interface GDB to graphical user interfaces or other similar programs +which want to interact with GDB at a relatively high level. + + The annotation mechanism has largely been superseded by GDB/MI (*note +GDB/MI::). + +* Menu: + +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Prompting:: Annotations marking GDB's need for input. +* Errors:: Annotations for error messages. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. + + +File: gdb.info, Node: Annotations Overview, Next: Server Prefix, Up: Annotations + +28.1 What is an Annotation? +=========================== + +Annotations start with a newline character, two 'control-z' characters, +and the name of the annotation. If there is no additional information +associated with this annotation, the name of the annotation is followed +immediately by a newline. If there is additional information, the name +of the annotation is followed by a space, the additional information, +and a newline. The additional information cannot contain newline +characters. + + Any output not beginning with a newline and two 'control-z' +characters denotes literal output from GDB. Currently there is no need +for GDB to output a newline followed by two 'control-z' characters, but +if there was such a need, the annotations could be extended with an +'escape' annotation which means those three characters as output. + + The annotation LEVEL, which is specified using the '--annotate' +command line option (*note Mode Options::), controls how much +information GDB prints together with its prompt, values of expressions, +source lines, and other types of output. Level 0 is for no annotations, +level 1 is for use when GDB is run as a subprocess of GNU Emacs, level 3 +is the maximum annotation suitable for programs that control GDB, and +level 2 annotations have been made obsolete (*note Limitations of the +Annotation Interface: (annotate)Limitations.). + +'set annotate LEVEL' + The GDB command 'set annotate' sets the level of annotations to the + specified LEVEL. + +'show annotate' + Show the current annotation level. + + This chapter describes level 3 annotations. + + A simple example of starting up GDB with annotations is: + + $ gdb --annotate=3 + GNU gdb 6.0 + Copyright 2003 Free Software Foundation, Inc. + GDB is free software, covered by the GNU General Public License, + and you are welcome to change it and/or distribute copies of it + under certain conditions. + Type "show copying" to see the conditions. + There is absolutely no warranty for GDB. Type "show warranty" + for details. + This GDB was configured as "i386-pc-linux-gnu" + + ^Z^Zpre-prompt + (gdb) + ^Z^Zprompt + quit + + ^Z^Zpost-prompt + $ + + Here 'quit' is input to GDB; the rest is output from GDB. The three +lines beginning '^Z^Z' (where '^Z' denotes a 'control-z' character) are +annotations; the rest is output from GDB. + + +File: gdb.info, Node: Server Prefix, Next: Prompting, Prev: Annotations Overview, Up: Annotations + +28.2 The Server Prefix +====================== + +If you prefix a command with 'server ' then it will not affect the +command history, nor will it affect GDB's notion of which command to +repeat if is pressed on a line by itself. This means that +commands can be run behind a user's back by a front-end in a transparent +manner. + + The 'server ' prefix does not affect the recording of values into the +value history; to print a value without recording it into the value +history, use the 'output' command instead of the 'print' command. + + Using this prefix also disables confirmation requests (*note +confirmation requests::). + + +File: gdb.info, Node: Prompting, Next: Errors, Prev: Server Prefix, Up: Annotations + +28.3 Annotation for GDB Input +============================= + +When GDB prompts for input, it annotates this fact so it is possible to +know when to send output, when the output from a given command is over, +etc. + + Different kinds of input each have a different "input type". Each +input type has three annotations: a 'pre-' annotation, which denotes the +beginning of any prompt which is being output, a plain annotation, which +denotes the end of the prompt, and then a 'post-' annotation which +denotes the end of any echo which may (or may not) be associated with +the input. For example, the 'prompt' input type features the following +annotations: + + ^Z^Zpre-prompt + ^Z^Zprompt + ^Z^Zpost-prompt + + The input types are + +'prompt' + When GDB is prompting for a command (the main GDB prompt). + +'commands' + When GDB prompts for a set of commands, like in the 'commands' + command. The annotations are repeated for each command which is + input. + +'overload-choice' + When GDB wants the user to select between various overloaded + functions. + +'query' + When GDB wants the user to confirm a potentially dangerous + operation. + +'prompt-for-continue' + When GDB is asking the user to press return to continue. Note: + Don't expect this to work well; instead use 'set height 0' to + disable prompting. This is because the counting of lines is buggy + in the presence of annotations. + + +File: gdb.info, Node: Errors, Next: Invalidation, Prev: Prompting, Up: Annotations + +28.4 Errors +=========== + + ^Z^Zquit + + This annotation occurs right before GDB responds to an interrupt. + + ^Z^Zerror + + This annotation occurs right before GDB responds to an error. + + Quit and error annotations indicate that any annotations which GDB +was in the middle of may end abruptly. For example, if a +'value-history-begin' annotation is followed by a 'error', one cannot +expect to receive the matching 'value-history-end'. One cannot expect +not to receive it either, however; an error annotation does not +necessarily mean that GDB is immediately returning all the way to the +top level. + + A quit or error annotation may be preceded by + + ^Z^Zerror-begin + + Any output between that and the quit or error annotation is the error +message. + + Warning messages are not yet annotated. + + +File: gdb.info, Node: Invalidation, Next: Annotations for Running, Prev: Errors, Up: Annotations + +28.5 Invalidation Notices +========================= + +The following annotations say that certain pieces of state may have +changed. + +'^Z^Zframes-invalid' + + The frames (for example, output from the 'backtrace' command) may + have changed. + +'^Z^Zbreakpoints-invalid' + + The breakpoints may have changed. For example, the user just added + or deleted a breakpoint. + + +File: gdb.info, Node: Annotations for Running, Next: Source Annotations, Prev: Invalidation, Up: Annotations + +28.6 Running the Program +======================== + +When the program starts executing due to a GDB command such as 'step' or +'continue', + + ^Z^Zstarting + + is output. When the program stops, + + ^Z^Zstopped + + is output. Before the 'stopped' annotation, a variety of annotations +describe how the program stopped. + +'^Z^Zexited EXIT-STATUS' + The program exited, and EXIT-STATUS is the exit status (zero for + successful exit, otherwise nonzero). + +'^Z^Zsignalled' + The program exited with a signal. After the '^Z^Zsignalled', the + annotation continues: + + INTRO-TEXT + ^Z^Zsignal-name + NAME + ^Z^Zsignal-name-end + MIDDLE-TEXT + ^Z^Zsignal-string + STRING + ^Z^Zsignal-string-end + END-TEXT + + where NAME is the name of the signal, such as 'SIGILL' or + 'SIGSEGV', and STRING is the explanation of the signal, such as + 'Illegal Instruction' or 'Segmentation fault'. The arguments + INTRO-TEXT, MIDDLE-TEXT, and END-TEXT are for the user's benefit + and have no particular format. + +'^Z^Zsignal' + The syntax of this annotation is just like 'signalled', but GDB is + just saying that the program received the signal, not that it was + terminated with it. + +'^Z^Zbreakpoint NUMBER' + The program hit breakpoint number NUMBER. + +'^Z^Zwatchpoint NUMBER' + The program hit watchpoint number NUMBER. + + +File: gdb.info, Node: Source Annotations, Prev: Annotations for Running, Up: Annotations + +28.7 Displaying Source +====================== + +The following annotation is used instead of displaying source code: + + ^Z^Zsource FILENAME:LINE:CHARACTER:MIDDLE:ADDR + + where FILENAME is an absolute file name indicating which source file, +LINE is the line number within that file (where 1 is the first line in +the file), CHARACTER is the character position within the file (where 0 +is the first character in the file) (for most debug formats this will +necessarily point to the beginning of a line), MIDDLE is 'middle' if +ADDR is in the middle of the line, or 'beg' if ADDR is at the beginning +of the line, and ADDR is the address in the target program associated +with the source which is being displayed. The ADDR is in the form '0x' +followed by one or more lowercase hex digits (note that this does not +depend on the language). + + +File: gdb.info, Node: Debugger Adapter Protocol, Next: JIT Interface, Prev: Annotations, Up: Top + +29 Debugger Adapter Protocol +**************************** + +The Debugger Adapter Protocol is a generic API that is used by some IDEs +to communicate with debuggers. It is documented at +. + + Generally, GDB implements the Debugger Adapter Protocol as written. +However, in some cases, extensions are either needed or even expected. + + GDB defines some parameters that can be passed to the 'launch' +request: + +'args' + If provided, this should be an array of strings. These strings are + provided as command-line arguments to the inferior, as if by 'set + args'. *Note Arguments::. + +'cwd' + If provided, this should be a string. GDB will change its working + directory to this directory, as if by the 'cd' command (*note + Working Directory::). The launched program will inherit this as + its working directory. Note that change of directory happens + before the 'program' parameter is processed. This will affect the + result if 'program' is a relative filename. + +'env' + If provided, this should be an object. Each key of the object will + be used as the name of an environment variable; each value must be + a string and will be the value of that variable. The environment + of the inferior will be set to exactly as passed in. *Note + Environment::. + +'program' + If provided, this is a string that specifies the program to use. + This corresponds to the 'file' command. *Note Files::. + +'stopAtBeginningOfMainSubprogram' + If provided, this must be a boolean. When 'True', GDB will set a + temporary breakpoint at the program's main procedure, using the + same approach as the 'start' command. *Note Starting::. + +'stopOnEntry' + If provided, this must be a boolean. When 'True', GDB will set a + temporary breakpoint at the program's first instruction, using the + same approach as the 'starti' command. *Note Starting::. + + GDB defines some parameters that can be passed to the 'attach' +request. Either 'pid' or 'target' must be specified, but if both are +specified then 'target' will be ignored. + +'pid' + The process ID to which GDB should attach. *Note Attach::. + +'program' + If provided, this is a string that specifies the program to use. + This corresponds to the 'file' command. *Note Files::. In some + cases, GDB can automatically determine which program is running. + However, for many remote targets, this is not the case, and so this + should be supplied. + +'target' + The target to which GDB should connect. This is a string and is + passed to the 'target remote' command. *Note Connecting::. + + In response to the 'disassemble' request, DAP allows the client to +return the bytes of each instruction in an implementation-defined +format. GDB implements this by sending a string with the bytes encoded +in hex, like '"55a2b900"'. + + When the 'repl' context is used for the 'evaluate' request, GDB +evaluates the provided expression as a CLI command. + + Evaluation in general can cause the inferior to continue execution. +For example, evaluating the 'continue' command could do this, as could +evaluating an expression that involves an inferior function call. + + 'repl' evaluation can also cause GDB to appear to stop responding to +requests, for example if a CLI script does a lengthy computation. + + Evaluations like this can be interrupted using the DAP 'cancel' +request. (In fact, 'cancel' should work for any request, but it is +unlikely to be useful for most of them.) + + GDB provides a couple of logging settings that can be used in DAP +mode. These can be set on the command line using the '-iex' option +(*note File Options::). + +'set debug dap-log-file [FILENAME]' + Enable DAP logging. Logs are written to FILENAME. If no FILENAME + is given, logging is stopped. + +'set debug dap-log-level LEVEL' + Set the DAP logging level. The default is '1', which logs the DAP + protocol, whatever debug messages the developers thought were + useful, and unexpected exceptions. Level '2' can be used to log + all exceptions, including ones that are considered to be expected. + For example, a failure to parse an expression would be considered a + normal exception and not normally be logged. + + +File: gdb.info, Node: JIT Interface, Next: In-Process Agent, Prev: Debugger Adapter Protocol, Up: Top + +30 JIT Compilation Interface +**************************** + +This chapter documents GDB's "just-in-time" (JIT) compilation interface. +A JIT compiler is a program or library that generates native executable +code at runtime and executes it, usually in order to achieve good +performance while maintaining platform independence. + + Programs that use JIT compilation are normally difficult to debug +because portions of their code are generated at runtime, instead of +being loaded from object files, which is where GDB normally finds the +program's symbols and debug information. In order to debug programs +that use JIT compilation, GDB has an interface that allows the program +to register in-memory symbol files with GDB at runtime. + + If you are using GDB to debug a program that uses this interface, +then it should work transparently so long as you have not stripped the +binary. If you are developing a JIT compiler, then the interface is +documented in the rest of this chapter. At this time, the only known +client of this interface is the LLVM JIT. + + Broadly speaking, the JIT interface mirrors the dynamic loader +interface. The JIT compiler communicates with GDB by writing data into +a global variable and calling a function at a well-known symbol. When +GDB attaches, it reads a linked list of symbol files from the global +variable to find existing code, and puts a breakpoint in the function so +that it can find out about additional code. + +* Menu: + +* Declarations:: Relevant C struct declarations +* Registering Code:: Steps to register code +* Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format + + +File: gdb.info, Node: Declarations, Next: Registering Code, Up: JIT Interface + +30.1 JIT Declarations +===================== + +These are the relevant struct declarations that a C program should +include to implement the interface: + + typedef enum + { + JIT_NOACTION = 0, + JIT_REGISTER_FN, + JIT_UNREGISTER_FN + } jit_actions_t; + + struct jit_code_entry + { + struct jit_code_entry *next_entry; + struct jit_code_entry *prev_entry; + const char *symfile_addr; + uint64_t symfile_size; + }; + + struct jit_descriptor + { + uint32_t version; + /* This type should be jit_actions_t, but we use uint32_t + to be explicit about the bitwidth. */ + uint32_t action_flag; + struct jit_code_entry *relevant_entry; + struct jit_code_entry *first_entry; + }; + + /* GDB puts a breakpoint in this function. */ + void __attribute__((noinline)) __jit_debug_register_code() { }; + + /* Make sure to specify the version statically, because the + debugger may check the version before we can set it. */ + struct jit_descriptor __jit_debug_descriptor = { 1, 0, 0, 0 }; + + If the JIT is multi-threaded, then it is important that the JIT +synchronize any modifications to this global data properly, which can +easily be done by putting a global mutex around modifications to these +structures. + + +File: gdb.info, Node: Registering Code, Next: Unregistering Code, Prev: Declarations, Up: JIT Interface + +30.2 Registering Code +===================== + +To register code with GDB, the JIT should follow this protocol: + + * Generate an object file in memory with symbols and other desired + debug information. The file must include the virtual addresses of + the sections. + + * Create a code entry for the file, which gives the start and size of + the symbol file. + + * Add it to the linked list in the JIT descriptor. + + * Point the relevant_entry field of the descriptor at the entry. + + * Set 'action_flag' to 'JIT_REGISTER' and call + '__jit_debug_register_code'. + + When GDB is attached and the breakpoint fires, GDB uses the +'relevant_entry' pointer so it doesn't have to walk the list looking for +new code. However, the linked list must still be maintained in order to +allow GDB to attach to a running process and still find the symbol +files. + + +File: gdb.info, Node: Unregistering Code, Next: Custom Debug Info, Prev: Registering Code, Up: JIT Interface + +30.3 Unregistering Code +======================= + +If code is freed, then the JIT should use the following protocol: + + * Remove the code entry corresponding to the code from the linked + list. + + * Point the 'relevant_entry' field of the descriptor at the code + entry. + + * Set 'action_flag' to 'JIT_UNREGISTER' and call + '__jit_debug_register_code'. + + If the JIT frees or recompiles code without unregistering it, then +GDB and the JIT will leak the memory used for the associated symbol +files. + + +File: gdb.info, Node: Custom Debug Info, Prev: Unregistering Code, Up: JIT Interface + +30.4 Custom Debug Info +====================== + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The issue +can be resolved by having the JIT writers decide on a debug info format +and also provide a reader that parses the debug info generated by the +JIT compiler. This section gives a brief overview on writing such a +parser. More specific details can be found in the source file +'gdb/jit-reader.in', which is also installed as a header at +'INCLUDEDIR/gdb/jit-reader.h' for easy inclusion. + + The reader is implemented as a shared object (so this functionality +is not available on platforms which don't allow loading shared objects +at runtime). Two GDB commands, 'jit-reader-load' and +'jit-reader-unload' are provided, to be used to load and unload the +readers from a preconfigured directory. Once loaded, the shared object +is used the parse the debug information emitted by the JIT compiler. + +* Menu: + +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader + + +File: gdb.info, Node: Using JIT Debug Info Readers, Next: Writing JIT Debug Info Readers, Up: Custom Debug Info + +30.4.1 Using JIT Debug Info Readers +----------------------------------- + +Readers can be loaded and unloaded using the 'jit-reader-load' and +'jit-reader-unload' commands. + +'jit-reader-load READER' + Load the JIT reader named READER, which is a shared object + specified as either an absolute or a relative file name. In the + latter case, GDB will try to load the reader from a pre-configured + directory, usually 'LIBDIR/gdb/' on a UNIX system (here LIBDIR is + the system library directory, often '/usr/local/lib'). + + Only one reader can be active at a time; trying to load a second + reader when one is already loaded will result in GDB reporting an + error. A new JIT reader can be loaded by first unloading the + current one using 'jit-reader-unload' and then invoking + 'jit-reader-load'. + +'show jit-reader-directory' + This command will show the directory that is used by + 'jit-reader-load' when a relative file name is specified. + +'jit-reader-unload' + Unload the currently loaded JIT reader. + + +File: gdb.info, Node: Writing JIT Debug Info Readers, Prev: Using JIT Debug Info Readers, Up: Custom Debug Info + +30.4.2 Writing JIT Debug Info Readers +------------------------------------- + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in 'jit-reader.h'. + + 'jit-reader.h' defines the structures, macros and functions required +to write a reader. It is installed (along with GDB), in +'INCLUDEDIR/gdb' where INCLUDEDIR is the system include directory. + + Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +'GDB_DECLARE_GPL_COMPATIBLE_READER' in a source file. + + The entry point for readers is the symbol 'gdb_init_reader', which is +expected to be a function with the prototype + + extern struct gdb_reader_funcs *gdb_init_reader (void); + + 'struct gdb_reader_funcs' contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler ('read'), to unwind stack frames +('unwind') and to create canonical frame IDs ('get_frame_id'). It also +has a callback that is called when the reader is being unloaded +('destroy'). The struct looks like this + + struct gdb_reader_funcs + { + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; + }; + + The callbacks are provided with another set of callbacks by GDB to do +their job. For 'read', these callbacks are passed in a 'struct +gdb_symbol_callbacks' and for 'unwind' and 'get_frame_id', in a 'struct +gdb_unwind_callbacks'. 'struct gdb_symbol_callbacks' has callbacks to +create new object files and new symbol tables inside those object files. +'struct gdb_unwind_callbacks' has callbacks to read registers off the +current frame and to write out the values of the registers in the +previous frame. Both have a callback ('target_read') to read bytes off +the target's address space. + + +File: gdb.info, Node: In-Process Agent, Next: GDB Bugs, Prev: JIT Interface, Up: Top + +31 In-Process Agent +******************* + +The traditional debugging model is conceptually low-speed, but works +fine, because most bugs can be reproduced in debugging-mode execution. +However, as multi-core or many-core processors are becoming mainstream, +and multi-threaded programs become more and more popular, there should +be more and more bugs that only manifest themselves at normal-mode +execution, for example, thread races, because debugger's interference +with the program's timing may conceal the bugs. On the other hand, in +some applications, it is not feasible for the debugger to interrupt the +program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Therefore, traditional debugging model is too intrusive to reproduce +some bugs. In order to reduce the interference with the program, we can +reduce the number of operations performed by debugger. The "In-Process +Agent", a shared library, is running within the same process with +inferior, and is able to perform some debugging operations itself. As a +result, debugger is only involved when necessary, and performance of +debugging can be improved accordingly. Note that interference with +program can be reduced but can't be removed completely, because the +in-process agent will still stop or slow down the program. + + The in-process agent can interpret and execute Agent Expressions +(*note Agent Expressions::) during performing debugging operations. The +agent expressions can be used for different purposes, such as collecting +data in tracepoints, and condition evaluation in breakpoints. + + You can control whether the in-process agent is used as an aid for +debugging with the following commands: + +'set agent on' + Causes the in-process agent to perform some operations on behalf of + the debugger. Just which operations requested by the user will be + done by the in-process agent depends on the its capabilities. For + example, if you request to evaluate breakpoint conditions in the + in-process agent, and the in-process agent has such capability as + well, then breakpoint conditions will be evaluated in the + in-process agent. + +'set agent off' + Disables execution of debugging operations by the in-process agent. + All of the operations will be performed by GDB. + +'show agent' + Display the current setting of execution of debugging operations by + the in-process agent. + +* Menu: + +* In-Process Agent Protocol:: + + +File: gdb.info, Node: In-Process Agent Protocol, Up: In-Process Agent + +31.1 In-Process Agent Protocol +============================== + +The in-process agent is able to communicate with both GDB and GDBserver +(*note In-Process Agent::). This section documents the protocol used +for communications between GDB or GDBserver and the IPA. In general, GDB +or GDBserver sends commands (*note IPA Protocol Commands::) and data to +in-process agent, and then in-process agent replies back with the return +result of the command, or some other information. The data sent to +in-process agent is composed of primitive data types, such as 4-byte or +8-byte type, and composite types, which are called objects (*note IPA +Protocol Objects::). + +* Menu: + +* IPA Protocol Objects:: +* IPA Protocol Commands:: + + +File: gdb.info, Node: IPA Protocol Objects, Next: IPA Protocol Commands, Up: In-Process Agent Protocol + +31.1.1 IPA Protocol Objects +--------------------------- + +The commands sent to and results received from agent may contain some +complex data types called "objects". + + The in-process agent is running on the same machine with GDB or +GDBserver, so it doesn't have to handle as much differences between two +ends as remote protocol (*note Remote Protocol::) tries to handle. +However, there are still some differences of two ends in two processes: + + 1. word size. On some 64-bit machines, GDB or GDBserver can be + compiled as a 64-bit executable, while in-process agent is a 32-bit + one. + 2. ABI. Some machines may have multiple types of ABI, GDB or GDBserver + is compiled with one, and in-process agent is compiled with the + other one. + + Here are the IPA Protocol Objects: + + 1. agent expression object. It represents an agent expression (*note + Agent Expressions::). + 2. tracepoint action object. It represents a tracepoint action (*note + Tracepoint Action Lists: Tracepoint Actions.) to collect registers, + memory, static trace data and to evaluate expression. + 3. tracepoint object. It represents a tracepoint (*note + Tracepoints::). + + The following table describes important attributes of each IPA +protocol object: + +Name Size Description +--------------------------------------------------------------------------- +_agent expression +object_ +length 4 length of bytes code +byte code LENGTH contents of byte code +_tracepoint action +for collecting +memory_ +'M' 1 type of tracepoint action +addr 8 if BASEREG is '-1', ADDR is the + address of the lowest byte to + collect, otherwise ADDR is the + offset of BASEREG for memory + collecting. +len 8 length of memory for collecting +basereg 4 the register number containing the + starting memory address for + collecting. +_tracepoint action +for collecting +registers_ +'R' 1 type of tracepoint action +_tracepoint action +for collecting +static trace data_ +'L' 1 type of tracepoint action +_tracepoint action +for expression +evaluation_ +'X' 1 type of tracepoint action +agent expression length of *note agent expression object:: +_tracepoint object_ +number 4 number of tracepoint +address 8 address of tracepoint inserted on +type 4 type of tracepoint +enabled 1 enable or disable of tracepoint +step_count 8 step +pass_count 8 pass +numactions 4 number of tracepoint actions +hit count 8 hit count +trace frame usage 8 trace frame usage +compiled_cond 8 compiled condition +orig_size 8 orig size +condition 4 if zero if condition is NULL, + condition is otherwise is + NULL *note agent expression object:: + otherwise + length of + *note agent expression object:: +actions variable numactions number of + *note tracepoint action object:: + + +File: gdb.info, Node: IPA Protocol Commands, Prev: IPA Protocol Objects, Up: In-Process Agent Protocol + +31.1.2 IPA Protocol Commands +---------------------------- + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +'FastTrace:TRACEPOINT_OBJECT GDB_JUMP_PAD_HEAD' + Installs a new fast tracepoint described by TRACEPOINT_OBJECT + (*note tracepoint object::). The GDB_JUMP_PAD_HEAD, 8-byte long, + is the head of "jumppad", which is used to jump to data collection + routine in IPA finally. + + Replies: + 'OK TARGET_ADDRESS GDB_JUMP_PAD_HEAD FJUMP_SIZE FJUMP' + TARGET_ADDRESS is address of tracepoint in the inferior. The + GDB_JUMP_PAD_HEAD is updated head of jumppad. Both of + TARGET_ADDRESS and GDB_JUMP_PAD_HEAD are 8-byte long. The + FJUMP contains a sequence of instructions jump to jumppad + entry. The FJUMP_SIZE, 4-byte long, is the size of FJUMP. + +'close' + Closes the in-process agent. This command is sent when GDB or + GDBserver is about to kill inferiors. + +'qTfSTM' + *Note qTfSTM::. +'qTsSTM' + *Note qTsSTM::. +'qTSTMat' + *Note qTSTMat::. +'probe_marker_at:ADDRESS' + Asks in-process agent to probe the marker at ADDRESS. + + Replies: +'unprobe_marker_at:ADDRESS' + Asks in-process agent to unprobe the marker at ADDRESS. + + +File: gdb.info, Node: GDB Bugs, Next: Command Line Editing, Prev: In-Process Agent, Up: Top + +32 Reporting Bugs in GDB +************************ + +Your bug reports play an essential role in making GDB reliable. + + Reporting a bug may help you by bringing a solution to your problem, +or it may not. But in any case the principal function of a bug report +is to help the entire community by making the next version of GDB work +better. Bug reports are your contribution to the maintenance of GDB. + + In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +* Menu: + +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs + + +File: gdb.info, Node: Bug Criteria, Next: Bug Reporting, Up: GDB Bugs + +32.1 Have You Found a Bug? +========================== + +If you are not sure whether you have found a bug, here are some +guidelines: + + * If the debugger gets a fatal signal, for any input whatever, that + is a GDB bug. Reliable debuggers never crash. + + * If GDB produces an error message for valid input, that is a bug. + (Note that if you're cross debugging, the problem may also be + somewhere in the connection to the target.) + + * If GDB does not produce an error message for invalid input, that is + a bug. However, you should note that your idea of "invalid input" + might be our idea of "an extension" or "support for traditional + practice". + + * If you are an experienced user of debugging tools, your suggestions + for improvement of GDB are welcome in any case. + + +File: gdb.info, Node: Bug Reporting, Prev: Bug Criteria, Up: GDB Bugs + +32.2 How to Report Bugs +======================= + +A number of companies and individuals offer support for GNU products. +If you obtained GDB from a support organization, we recommend you +contact that organization first. + + You can find contact information for many support companies and +individuals in the file 'etc/SERVICE' in the GNU Emacs distribution. + + In any event, we also recommend that you submit bug reports for GDB +to . + + The fundamental principle of reporting bugs usefully is this: *report +all the facts*. If you are not sure whether to state a fact or leave it +out, state it! + + Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not +matter. Well, probably it does not, but one cannot be sure. Perhaps +the bug is a stray memory reference which happens to fetch from the +location where that name is stored in memory; perhaps, if the name were +different, the contents of that location would fool the debugger into +doing the right thing despite the bug. Play it safe and give a +specific, complete example. That is the easiest thing for you to do, +and the most helpful. + + Keep in mind that the purpose of a bug report is to enable us to fix +the bug. It may be that the bug has been reported previously, but +neither you nor we can know that unless your bug report is complete and +self-contained. + + Sometimes people give a few sketchy facts and ask, "Does this ring a +bell?" Those bug reports are useless, and we urge everyone to _refuse +to respond to them_ except to chide the sender to report bugs properly. + + To enable us to fix the bug, you should include all these things: + + * The version of GDB. GDB announces it if you start with no + arguments; you can also print it at any time using 'show version'. + + Without this, we will not know whether there is any point in + looking for the bug in the current version of GDB. + + * The type of machine you are using, and the operating system name + and version number. + + * The details of the GDB build-time configuration. GDB shows these + details if you invoke it with the '--configuration' command-line + option, or if you type 'show configuration' at GDB's prompt. + + * What compiler (and its version) was used to compile GDB--e.g. + "gcc-2.8.1". + + * What compiler (and its version) was used to compile the program you + are debugging--e.g. "gcc-2.8.1", or "HP92453-01 A.10.32.03 HP C + Compiler". For GCC, you can say 'gcc --version' to get this + information; for other compilers, see the documentation for those + compilers. + + * The command arguments you gave the compiler to compile your example + and observe the bug. For example, did you use '-O'? To guarantee + you will not omit something important, list them all. A copy of + the Makefile (or the output from make) is sufficient. + + If we were to try to guess the arguments, we would probably guess + wrong and then we might not encounter the bug. + + * A complete input script, and all necessary source files, that will + reproduce the bug. + + * A description of what behavior you observe that you believe is + incorrect. For example, "It gets a fatal signal." + + Of course, if the bug is that GDB gets a fatal signal, then we will + certainly notice it. But if the bug is incorrect output, we might + not notice unless it is glaringly wrong. You might as well not + give us a chance to make a mistake. + + Even if the problem you experience is a fatal signal, you should + still say so explicitly. Suppose something strange is going on, + such as, your copy of GDB is out of synch, or you have encountered + a bug in the C library on your system. (This has happened!) Your + copy might crash and ours would not. If you told us to expect a + crash, then when ours fails to crash, we would know that the bug + was not happening for us. If you had not told us to expect a + crash, then we would not be able to draw any conclusion from our + observations. + + To collect all this information, you can use a session recording + program such as 'script', which is available on many Unix systems. + Just run your GDB session inside 'script' and then include the + 'typescript' file with your bug report. + + Another way to record a GDB session is to run GDB inside Emacs and + then save the entire buffer to a file. + + * If you wish to suggest changes to the GDB source, send us context + diffs. If you even discuss something in the GDB source, refer to + it by context, not by line number. + + The line numbers in our development sources will not match those in + your sources. Your line numbers would convey no useful information + to us. + + Here are some things that are not necessary: + + * A description of the envelope of the bug. + + Often people who encounter a bug spend a lot of time investigating + which changes to the input file will make the bug go away and which + changes will not affect it. + + This is often time consuming and not very useful, because the way + we will find the bug is by running a single example under the + debugger with breakpoints, not by pure deduction from a series of + examples. We recommend that you save your time for something else. + + Of course, if you can find a simpler example to report _instead_ of + the original one, that is a convenience for us. Errors in the + output will be easier to spot, running under the debugger will take + less time, and so on. + + However, simplification is not vital; if you do not want to do + this, report the bug anyway and send us the entire test case you + used. + + * A patch for the bug. + + A patch for the bug does help us if it is a good one. But do not + omit the necessary information, such as the test case, on the + assumption that a patch is all we need. We might see problems with + your patch and decide to fix the problem another way, or we might + not understand it at all. + + Sometimes with a program as complicated as GDB it is very hard to + construct an example that will make the program follow a certain + path through the code. If you do not send us the example, we will + not be able to construct one, so we will not be able to verify that + the bug is fixed. + + And if we cannot understand what bug you are trying to fix, or why + your patch should be an improvement, we will not install it. A + test case will help us to understand. + + * A guess about what the bug is or what it depends on. + + Such guesses are usually wrong. Even we cannot guess right about + such things without first using the debugger to find the facts. + + +File: gdb.info, Node: Command Line Editing, Next: Using History Interactively, Prev: GDB Bugs, Up: Top + +33 Command Line Editing +*********************** + +This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: gdb.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +33.1 Introduction to Line Editing +================================= + +The following paragraphs describe the notation used to represent +keystrokes. + + The text 'C-k' is read as 'Control-K' and describes the character +produced when the key is pressed while the Control key is depressed. + + The text 'M-k' is read as 'Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed. The Meta key is labeled on many keyboards. On +keyboards with two keys labeled (usually to either side of the +space bar), the on the left side is generally set to work as a +Meta key. The key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or key, or another key working as a +Meta key, the identical keystroke can be generated by typing +_first_, and then typing . Either process is known as "metafying" +the key. + + The text 'M-C-k' is read as 'Meta-Control-k' and describes the +character produced by "metafying" 'C-k'. + + In addition, several keys have their own names. Specifically, , +, , , , and all stand for themselves when seen +in this text, or in an init file (*note Readline Init File::). If your +keyboard lacks a key, typing will produce the desired +character. The key may be labeled or on some +keyboards. + + +File: gdb.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +33.2 Readline Interaction +========================= + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press . You do not have to be at the end of +the line to press ; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: gdb.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +33.2.1 Readline Bare Essentials +------------------------------- + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error until +you have typed several other characters. In that case, you can type +'C-b' to move the cursor to the left, and then correct your mistake. +Afterwards, you can move the cursor to the right with 'C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are 'pushed over' to make room for +the text that you have inserted. Likewise, when you delete text behind +the cursor, characters to the right of the cursor are 'pulled back' to +fill in the blank space created by the removal of the text. A list of +the bare essentials for editing the text of an input line follows. + +'C-b' + Move back one character. +'C-f' + Move forward one character. + or + Delete the character to the left of the cursor. +'C-d' + Delete the character underneath the cursor. +Printing characters + Insert the character into the line at the cursor. +'C-_' or 'C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the key might be set to +delete the character to the left of the cursor and the key set to +delete the character underneath the cursor, like 'C-d', rather than the +character to the left of the cursor.) + + +File: gdb.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +33.2.2 Readline Movement Commands +--------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many other +commands have been added in addition to 'C-b', 'C-f', 'C-d', and . +Here are some commands for moving more rapidly about the line. + +'C-a' + Move to the start of the line. +'C-e' + Move to the end of the line. +'M-f' + Move forward a word, where a word is composed of letters and + digits. +'M-b' + Move backward a word. +'C-l' + Clear the screen, reprinting the current line at the top. + + Notice how 'C-f' moves forward a character, while 'M-f' moves forward +a word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: gdb.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +33.2.3 Readline Killing Commands +-------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into the +line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) + + If the description for a command says that it 'kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". Any +number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +'C-k' + Kill the text from the current cursor position to the end of the + line. + +'M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by 'M-f'. + +'M-' + Kill from the cursor to the start of the current word, or, if + between words, to the start of the previous word. Word boundaries + are the same as those used by 'M-b'. + +'C-w' + Kill from the cursor to the previous whitespace. This is different + than 'M-' because the word boundaries differ. + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +'C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +'M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'C-y' or 'M-y'. + + +File: gdb.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +33.2.4 Readline Arguments +------------------------- + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type 'M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first 'digit' typed is a minus +sign ('-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give the +'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will +delete the next ten characters on the input line. + + +File: gdb.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +33.2.5 Searching for Commands in the History +-------------------------------------------- + +Readline provides commands for searching through the command history for +lines containing a specified string. There are two search modes: +"incremental" and "non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters as +needed to find the desired history entry. To search backward in the +history for a particular string, type 'C-r'. Typing 'C-s' searches +forward through the history. The characters present in the value of the +'isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the and +'C-J' characters will terminate an incremental search. 'C-g' will abort +an incremental search and restore the original line. When the search is +terminated, the history entry containing the search string becomes the +current line. + + To find other matching entries in the history list, type 'C-r' or +'C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. Any +other key sequence bound to a Readline command will terminate the search +and execute that command. For instance, a will terminate the +search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two 'C-r's +are typed without any intervening characters defining a new search +string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: gdb.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +33.3 Readline Init File +======================= + +Although the Readline library comes with a set of Emacs-like keybindings +installed by default, it is possible to use a different set of +keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in their home +directory. The name of this file is taken from the value of the +environment variable 'INPUTRC'. If that variable is unset, the default +is '~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is '/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the 'C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: gdb.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +33.3.1 Readline Init File Syntax +-------------------------------- + +There are only a few basic constructs allowed in the Readline init file. +Blank lines are ignored. Lines beginning with a '#' are comments. +Lines beginning with a '$' indicate conditional constructs (*note +Conditional Init Constructs::). Other lines denote variable settings +and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the 'set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like key + binding to use 'vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. Any + other value results in the variable being set to off. + + A great deal of run-time behavior is changeable with the following + variables. + + 'active-region-start-color' + A string variable that controls the text color and background + when displaying the text in the active region (see the + description of 'enable-active-region' below). This string + must not take up any physical character positions on the + display, so it should consist only of terminal escape + sequences. It is output to the terminal before displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that puts the terminal in standout mode, + as obtained from the terminal's terminfo description. A + sample value might be '\e[01;33m'. + + 'active-region-end-color' + A string variable that "undoes" the effects of + 'active-region-start-color' and restores "normal" terminal + display appearance after displaying text in the active region. + This string must not take up any physical character positions + on the display, so it should consist only of terminal escape + sequences. It is output to the terminal after displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that restores the terminal from standout + mode, as obtained from the terminal's terminfo description. A + sample value might be '\e[0m'. + + 'bell-style' + Controls what happens when Readline wants to ring the terminal + bell. If set to 'none', Readline never rings the bell. If + set to 'visible', Readline uses a visible bell if one is + available. If set to 'audible' (the default), Readline + attempts to ring the terminal's bell. + + 'bind-tty-special-chars' + If set to 'on' (the default), Readline attempts to bind the + control characters treated specially by the kernel's terminal + driver to their Readline equivalents. + + 'blink-matching-paren' + If set to 'on', Readline attempts to briefly move the cursor + to an opening parenthesis when a closing parenthesis is + inserted. The default is 'off'. + + 'colored-completion-prefix' + If set to 'on', when listing completions, Readline displays + the common prefix of the set of possible completions using a + different color. The color definitions are taken from the + value of the 'LS_COLORS' environment variable. If there is a + color definition in 'LS_COLORS' for the custom suffix + 'readline-colored-completion-prefix', Readline uses this color + for the common prefix instead of its default. The default is + 'off'. + + 'colored-stats' + If set to 'on', Readline displays possible completions using + different colors to indicate their file type. The color + definitions are taken from the value of the 'LS_COLORS' + environment variable. The default is 'off'. + + 'comment-begin' + The string to insert at the beginning of the line when the + 'insert-comment' command is executed. The default value is + '"#"'. + + 'completion-display-width' + The number of screen columns used to display possible matches + when performing completion. The value is ignored if it is + less than 0 or greater than the terminal screen width. A + value of 0 will cause matches to be displayed one per line. + The default value is -1. + + 'completion-ignore-case' + If set to 'on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is 'off'. + + 'completion-map-case' + If set to 'on', and COMPLETION-IGNORE-CASE is enabled, + Readline treats hyphens ('-') and underscores ('_') as + equivalent when performing case-insensitive filename matching + and completion. The default value is 'off'. + + 'completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + 'completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than or equal to this value, Readline will ask whether or not + the user wishes to view them; otherwise, they are simply + listed. This variable must be set to an integer value greater + than or equal to zero. A zero value means Readline should + never ask; negative values are treated as zero. The default + limit is '100'. + + 'convert-meta' + If set to 'on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an character, converting them + to a meta-prefixed key sequence. The default value is 'on', + but will be set to 'off' if the locale is one that contains + eight-bit characters. This variable is dependent on the + 'LC_CTYPE' locale category, and may change if the locale is + changed. + + 'disable-completion' + If set to 'On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to 'self-insert'. The default is 'off'. + + 'echo-control-characters' + When set to 'on', on operating systems that indicate they + support it, Readline echoes a character corresponding to a + signal generated from the keyboard. The default is 'on'. + + 'editing-mode' + The 'editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either 'emacs' or 'vi'. + + 'emacs-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when emacs editing mode is active. The value is + expanded like a key binding, so the standard set of meta- and + control prefixes and backslash escape sequences is available. + Use the '\1' and '\2' escapes to begin and end sequences of + non-printing characters, which can be used to embed a terminal + control sequence into the mode string. The default is '@'. + + 'enable-active-region' + The "point" is the current cursor position, and "mark" refers + to a saved cursor position (*note Commands For Moving::). The + text between the point and mark is referred to as the + "region". When this variable is set to 'On', Readline allows + certain commands to designate the region as "active". When + the region is active, Readline highlights the text in the + region using the value of the 'active-region-start-color', + which defaults to the string that enables the terminal's + standout mode. The active region shows the text inserted by + bracketed-paste and any matching text found by incremental and + non-incremental history searches. The default is 'On'. + + 'enable-bracketed-paste' + When set to 'On', Readline configures the terminal to insert + each paste into the editing buffer as a single string of + characters, instead of treating each character as if it had + been read from the keyboard. This is called putting the + terminal into "bracketed paste mode"; it prevents Readline + from executing any editing commands bound to key sequences + appearing in the pasted text. The default is 'On'. + + 'enable-keypad' + When set to 'on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is 'off'. + + 'enable-meta-key' + When set to 'on', Readline will try to enable any meta + modifier key the terminal claims to support when it is called. + On many terminals, the meta key is used to send eight-bit + characters. The default is 'on'. + + 'expand-tilde' + If set to 'on', tilde expansion is performed when Readline + attempts word completion. The default is 'off'. + + 'history-preserve-point' + If set to 'on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with 'previous-history' or + 'next-history'. The default is 'off'. + + 'history-size' + Set the maximum number of history entries saved in the history + list. If set to zero, any existing history entries are + deleted and no new entries are saved. If set to a value less + than zero, the number of history entries is not limited. By + default, the number of history entries is not limited. If an + attempt is made to set HISTORY-SIZE to a non-numeric value, + the maximum number of history entries will be set to 500. + + 'horizontal-scroll-mode' + This variable can be set to either 'on' or 'off'. Setting it + to 'on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. This variable is automatically set to 'on' + for terminals of height 1. By default, this variable is set + to 'off'. + + 'input-meta' + If set to 'on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is 'off', but Readline will set it to 'on' if + the locale contains eight-bit characters. The name + 'meta-flag' is a synonym for this variable. This variable is + dependent on the 'LC_CTYPE' locale category, and may change if + the locale is changed. + + 'isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters and 'C-J' will terminate + an incremental search. + + 'keymap' + Sets Readline's idea of the current keymap for key binding + commands. Built-in 'keymap' names are 'emacs', + 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', + 'vi-command', and 'vi-insert'. 'vi' is equivalent to + 'vi-command' ('vi-move' is also a synonym); 'emacs' is + equivalent to 'emacs-standard'. Applications may add + additional names. The default value is 'emacs'. The value of + the 'editing-mode' variable also affects the default keymap. + + 'keyseq-timeout' + Specifies the duration Readline will wait for a character when + reading an ambiguous key sequence (one that can form a + complete key sequence using the input read so far, or can take + additional input to complete a longer key sequence). If no + input is received within the timeout, Readline will use the + shorter but complete key sequence. Readline uses this value + to determine whether or not input is available on the current + input source ('rl_instream' by default). The value is + specified in milliseconds, so a value of 1000 means that + Readline will wait one second for additional input. If this + variable is set to a value less than or equal to zero, or to a + non-numeric value, Readline will wait until another key is + pressed to decide which key sequence to complete. The default + value is '500'. + + 'mark-directories' + If set to 'on', completed directory names have a slash + appended. The default is 'on'. + + 'mark-modified-lines' + This variable, when set to 'on', causes Readline to display an + asterisk ('*') at the start of history lines which have been + modified. This variable is 'off' by default. + + 'mark-symlinked-directories' + If set to 'on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + 'mark-directories'). The default is 'off'. + + 'match-hidden-files' + This variable, when set to 'on', causes Readline to match + files whose names begin with a '.' (hidden files) when + performing filename completion. If set to 'off', the leading + '.' must be supplied by the user in the filename to be + completed. This variable is 'on' by default. + + 'menu-complete-display-prefix' + If set to 'on', menu completion displays the common prefix of + the list of possible completions (which may be empty) before + cycling through the list. The default is 'off'. + + 'output-meta' + If set to 'on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is 'off', but Readline will set it to + 'on' if the locale contains eight-bit characters. This + variable is dependent on the 'LC_CTYPE' locale category, and + may change if the locale is changed. + + 'page-completions' + If set to 'on', Readline uses an internal 'more'-like pager to + display a screenful of possible completions at a time. This + variable is 'on' by default. + + 'print-completions-horizontally' + If set to 'on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is 'off'. + + 'revert-all-at-newline' + If set to 'on', Readline will undo all changes to history + lines before returning when 'accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to 'readline()'. The default is + 'off'. + + 'show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to 'on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is 'off'. + + 'show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + 'on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is 'off'. + + 'show-mode-in-prompt' + If set to 'on', add a string to the beginning of the prompt + indicating the editing mode: emacs, vi command, or vi + insertion. The mode strings are user-settable (e.g., + EMACS-MODE-STRING). The default value is 'off'. + + 'skip-completed-text' + If set to 'on', this alters the default completion behavior + when inserting a single match into the line. It's only active + when performing completion in the middle of a word. If + enabled, Readline does not insert characters from the + completion that match characters after point in the word being + completed, so portions of the word following the cursor are + not duplicated. For instance, if this is enabled, attempting + completion when the cursor is after the 'e' in 'Makefile' will + result in 'Makefile' rather than 'Makefilefile', assuming + there is a single possible completion. The default value is + 'off'. + + 'vi-cmd-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in command mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(cmd)'. + + 'vi-ins-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in insertion mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(ins)'. + + 'visible-stats' + If set to 'on', a character denoting a file's type is appended + to the filename when listing possible completions. The + default is 'off'. + +Key Bindings + The syntax for controlling key bindings in the init file is simple. + First you need to find the name of the command that you want to + change. The following sections contain tables of the command name, + the default keybinding, if any, and a short description of what the + command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, Readline allows keys to be bound to a + string that is inserted when the key is pressed (a MACRO). + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the example above, 'C-u' is bound to the function + 'universal-argument', 'M-DEL' is bound to the function + 'backward-kill-word', and 'C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + '> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, 'C-u' is again bound to the function + 'universal-argument' (just as it was in the first example), + ''C-x' 'C-r'' is bound to the function 're-read-init-file', + and ' <[> <1> <1> <~>' is bound to insert the text + 'Function Key 1'. + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + '\C-' + control prefix + '\M-' + meta prefix + '\e' + an escape character + '\\' + backslash + '\"' + <">, a double quotation mark + '\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + '\a' + alert (bell) + '\b' + backspace + '\d' + delete + '\f' + form feed + '\n' + newline + '\r' + carriage return + '\t' + horizontal tab + '\v' + vertical tab + '\NNN' + the eight-bit character whose value is the octal value NNN + (one to three digits) + '\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including '"' and '''. For example, + the following binding will make ''C-x' \' insert a single '\' into + the line: + "\C-x\\": "\\" + + +File: gdb.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +33.3.2 Conditional Init Constructs +---------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings and +variable settings to be performed as the result of tests. There are +four parser directives used. + +'$if' + The '$if' construct allows bindings to be made based on the editing + mode, the terminal being used, or the application using Readline. + The text of the test, after any comparison operator, extends to the + end of the line; unless otherwise noted, no characters are required + to isolate it. + + 'mode' + The 'mode=' form of the '$if' directive is used to test + whether Readline is in 'emacs' or 'vi' mode. This may be used + in conjunction with the 'set keymap' command, for instance, to + set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps + only if Readline is starting out in 'emacs' mode. + + 'term' + The 'term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + '=' is tested against both the full name of the terminal and + the portion of the terminal name before the first '-'. This + allows 'sun' to match both 'sun' and 'sun-cmd', for instance. + + 'version' + The 'version' test may be used to perform comparisons against + specific Readline versions. The 'version' expands to the + current Readline version. The set of comparison operators + includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The + version number supplied on the right side of the operator + consists of a major version number, an optional decimal point, + and an optional minor version (e.g., '7.1'). If the minor + version is omitted, it is assumed to be '0'. The operator may + be separated from the string 'version' and from the version + number argument by whitespace. The following example sets a + variable if the Readline version being used is 7.0 or newer: + $if version >= 7.0 + set show-mode-in-prompt on + $endif + + 'application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + + 'variable' + The VARIABLE construct provides simple equality tests for + Readline variables and values. The permitted comparison + operators are '=', '==', and '!='. The variable name must be + separated from the comparison operator by whitespace; the + operator may be separated from the value on the right hand + side by whitespace. Both string and boolean variables may be + tested. Boolean variables must be tested against the values + ON and OFF. The following example is equivalent to the + 'mode=emacs' test described above: + $if editing-mode == emacs + set show-mode-in-prompt on + $endif + +'$endif' + This command, as seen in the previous example, terminates an '$if' + command. + +'$else' + Commands in this branch of the '$if' directive are executed if the + test fails. + +'$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from '/etc/inputrc': + $include /etc/inputrc + + +File: gdb.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +33.3.3 Sample Init File +----------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any system-wide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are 150 or more possible completions for a word, + # ask whether or not the user wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: gdb.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +33.4 Bindable Readline Commands +=============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + +This section describes Readline commands that may be bound to key +sequences. Command names without an accompanying key sequence are +unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the 'set-mark' +command. The text between the point and mark is referred to as the +"region". + + +File: gdb.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +33.4.1 Commands For Moving +-------------------------- + +'beginning-of-line (C-a)' + Move to the start of the current line. + +'end-of-line (C-e)' + Move to the end of the line. + +'forward-char (C-f)' + Move forward a character. + +'backward-char (C-b)' + Move back a character. + +'forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +'backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +'previous-screen-line ()' + Attempt to move point to the same physical screen column on the + previous physical screen line. This will not have the desired + effect if the current Readline line does not take up more than one + physical line or if point is not greater than the length of the + prompt plus the screen width. + +'next-screen-line ()' + Attempt to move point to the same physical screen column on the + next physical screen line. This will not have the desired effect + if the current Readline line does not take up more than one + physical line or if the length of the current Readline line is not + greater than the length of the prompt plus the screen width. + +'clear-display (M-C-l)' + Clear the screen and, if possible, the terminal's scrollback + buffer, then redraw the current line, leaving the current line at + the top of the screen. + +'clear-screen (C-l)' + Clear the screen, then redraw the current line, leaving the current + line at the top of the screen. + +'redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: gdb.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +33.4.2 Commands For Manipulating The History +-------------------------------------------- + +'accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, it may be added to the history list for future recall + with 'add_history()'. If this line is a modified history line, the + history line is restored to its original state. + +'previous-history (C-p)' + Move 'back' through the history list, fetching the previous + command. + +'next-history (C-n)' + Move 'forward' through the history list, fetching the next command. + +'beginning-of-history (M-<)' + Move to the first line in the history. + +'end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +'reverse-search-history (C-r)' + Search backward starting at the current line and moving 'up' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'forward-search-history (C-s)' + Search forward starting at the current line and moving 'down' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving 'up' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving 'down' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the '!N' + history expansion had been specified. + +'yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With a numeric argument, behave exactly + like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back + through the history list, inserting the last word (or the word + specified by the argument to the first call) of each line in turn. + Any numeric argument supplied to these successive calls determines + the direction to move through the history. A negative argument + switches the direction through the history (back or forward). The + history expansion facilities are used to extract the last argument, + as if the '!$' history expansion had been specified. + +'operate-and-get-next (C-o)' + Accept the current line for return to the calling application as if + a newline had been entered, and fetch the next line relative to the + current line from the history for editing. A numeric argument, if + supplied, specifies the history entry to use instead of the current + line. + +'fetch-history ()' + With a numeric argument, fetch that entry from the history list and + make it the current line. Without an argument, move back to the + first entry in the history list. + + +File: gdb.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +33.4.3 Commands For Changing Text +--------------------------------- + +'end-of-file (usually C-d)' + The character indicating end-of-file as set, for example, by + 'stty'. If this character is read when there are no characters on + the line, and point is at the beginning of the line, Readline + interprets it as the end of input and returns EOF. + +'delete-char (C-d)' + Delete the character at point. If this function is bound to the + same character as the tty EOF character, as 'C-d' commonly is, see + above for the effects. + +'backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +'forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +'quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like 'C-q', for example. + +'tab-insert (M-)' + Insert a tab character. + +'self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +'bracketed-paste-begin ()' + This function is intended to be bound to the "bracketed paste" + escape sequence sent by some terminals, and such a binding is + assigned by default. It allows Readline to insert the pasted text + as a single unit without treating each character as if it had been + read from the keyboard. The characters are inserted as if each one + was bound to 'self-insert' instead of executing any editing + commands. + + Bracketed paste sets the region (the characters between point and + the mark) to the inserted text. It uses the concept of an _active + mark_: when the mark is active, Readline redisplay uses the + terminal's standout mode to denote the region. + +'transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +'transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +'upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +'downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +'capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +'overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + 'emacs' mode; 'vi' mode does overwrite differently. Each call to + 'readline()' starts in insert mode. + + In overwrite mode, characters bound to 'self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to 'backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + +File: gdb.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +33.4.4 Killing And Yanking +-------------------------- + +'kill-line (C-k)' + Kill the text from point to the end of the line. With a negative + numeric argument, kill backward from the cursor to the beginning of + the current line. + +'backward-kill-line (C-x Rubout)' + Kill backward from the cursor to the beginning of the current line. + With a negative numeric argument, kill forward from the cursor to + the end of the current line. + +'unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +'kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +'kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as 'forward-word'. + +'backward-kill-word (M-)' + Kill the word behind point. Word boundaries are the same as + 'backward-word'. + +'shell-transpose-words (M-C-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. Word + boundaries are the same as 'shell-forward-word' and + 'shell-backward-word'. + +'unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +'unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +'delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +'kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +'copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +'copy-backward-word ()' + Copy the word before point to the kill buffer. The word boundaries + are the same as 'backward-word'. By default, this command is + unbound. + +'copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as 'forward-word'. By default, this + command is unbound. + +'yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +'yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'yank' or 'yank-pop'. + + +File: gdb.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +33.4.5 Specifying Numeric Arguments +----------------------------------- + +'digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. 'M--' starts a negative argument. + +'universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is followed + by digits, executing 'universal-argument' again ends the numeric + argument, but is otherwise ignored. As a special case, if this + command is immediately followed by a character that is neither a + digit nor minus sign, the argument count for the next command is + multiplied by four. The argument count is initially one, so + executing this function the first time makes the argument count + four, a second time makes the argument count sixteen, and so on. + By default, this is not bound to a key. + + +File: gdb.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +33.4.6 Letting Readline Type For You +------------------------------------ + +'complete ()' + Attempt to perform completion on the text before point. The actual + completion performed is application-specific. The default is + filename completion. + +'possible-completions (M-?)' + List the possible completions of the text before point. When + displaying completions, Readline sets the number of columns used + for display to the value of 'completion-display-width', the value + of the environment variable 'COLUMNS', or the screen width, in that + order. + +'insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by 'possible-completions'. + +'menu-complete ()' + Similar to 'complete', but replaces the word to be completed with a + single match from the list of possible completions. Repeated + execution of 'menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + 'bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to , but is unbound by + default. + +'menu-complete-backward ()' + Identical to 'menu-complete', but moves backward through the list + of possible completions, as if 'menu-complete' had been given a + negative argument. + +'delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like 'delete-char'). If at the end of the line, + behaves identically to 'possible-completions'. This command is + unbound by default. + + +File: gdb.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +33.4.7 Keyboard Macros +---------------------- + +'start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +'end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +'call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + +'print-last-kbd-macro ()' + Print the last keyboard macro defined in a format suitable for the + INPUTRC file. + + +File: gdb.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +33.4.8 Some Miscellaneous Commands +---------------------------------- + +'re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +'abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of 'bell-style'). + +'do-lowercase-version (M-A, M-B, M-X, ...)' + If the metafied character X is upper case, run the command that is + bound to the corresponding metafied lower case character. The + behavior is undefined if X is already lower case. + +'prefix-meta ()' + Metafy the next character typed. This is for keyboards without a + meta key. Typing ' f' is equivalent to typing 'M-f'. + +'undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +'revert-line (M-r)' + Undo all changes made to this line. This is like executing the + 'undo' command enough times to get back to the beginning. + +'tilde-expand (M-~)' + Perform tilde expansion on the current word. + +'set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +'exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +'character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative argument searches for previous + occurrences. + +'character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative argument searches for subsequent + occurrences. + +'skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will have + no effect unless explicitly bound to a Readline command, instead of + inserting stray characters into the editing buffer. This is + unbound by default, but usually bound to ESC-[. + +'insert-comment (M-#)' + Without a numeric argument, the value of the 'comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if the + characters at the beginning of the line do not match the value of + 'comment-begin', the value is inserted, otherwise the characters in + 'comment-begin' are deleted from the beginning of the line. In + either case, the line is accepted as if a newline had been typed. + +'dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +'dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'emacs-editing-mode (C-e)' + When in 'vi' command mode, this causes a switch to 'emacs' editing + mode. + +'vi-editing-mode (M-C-j)' + When in 'emacs' editing mode, this causes a switch to 'vi' editing + mode. + + +File: gdb.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +33.5 Readline vi Mode +===================== + +While the Readline library does not have a full set of 'vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline 'vi' mode behaves as specified in the POSIX standard. + + In order to switch interactively between 'emacs' and 'vi' editing +modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' +mode and to vi-editing-mode in 'emacs' mode). The Readline default is +'emacs' mode. + + When you enter a line in 'vi' mode, you are already placed in +'insertion' mode, as if you had typed an 'i'. Pressing switches +you into 'command' mode, where you can edit the text of the line with +the standard 'vi' movement keys, move to previous history lines with 'k' +and subsequent lines with 'j', and so forth. + + +File: gdb.info, Node: Using History Interactively, Next: In Memoriam, Prev: Command Line Editing, Up: Top + +34 Using History Interactively +****************************** + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the GNU History Library in your own programs, *note +(history)Programming with GNU History::. + +* Menu: + +* History Interaction:: What it feels like using History as a user. + + +File: gdb.info, Node: History Interaction, Up: Using History Interactively + +34.1 History Expansion +====================== + +The History library provides a history expansion feature that is similar +to the history expansion provided by 'csh'. This section describes the +syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments to +a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the history list should be used during +substitution. The second is to select portions of that line for +inclusion into the current one. The line selected from the history is +called the "event", and the portions of that line that are acted upon +are called "words". Various "modifiers" are available to manipulate the +selected words. The line is broken into words in the same fashion that +Bash does, so that several words surrounded by quotes are considered one +word. History expansions are introduced by the appearance of the +history expansion character, which is '!' by default. + + History expansion implements shell-like quoting conventions: a +backslash can be used to remove the special handling for the next +character; single quotes enclose verbatim sequences of characters, and +can be used to inhibit history expansion; and characters enclosed within +double quotes may be subject to history expansion, since backslash can +escape the history expansion character, but single quotes may not, since +they are not treated specially within double quotes. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: gdb.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +34.1.1 Event Designators +------------------------ + +An event designator is a reference to a command line entry in the +history list. Unless the reference is absolute, events are relative to +the current position in the history list. + +'!' + Start a history substitution, except when followed by a space, tab, + the end of the line, or '='. + +'!N' + Refer to command line N. + +'!-N' + Refer to the command N lines back. + +'!!' + Refer to the previous command. This is a synonym for '!-1'. + +'!STRING' + Refer to the most recent command preceding the current position in + the history list starting with STRING. + +'!?STRING[?]' + Refer to the most recent command preceding the current position in + the history list containing STRING. The trailing '?' may be + omitted if the STRING is followed immediately by a newline. If + STRING is missing, the string from the most recent search is used; + it is an error if there is no previous search string. + +'^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to '!!:s^STRING1^STRING2^'. + +'!#' + The entire command line typed so far. + + +File: gdb.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +34.1.2 Word Designators +----------------------- + +Word designators are used to select desired words from the event. A ':' +separates the event specification from the word designator. It may be +omitted if the word designator begins with a '^', '$', '*', '-', or '%'. +Words are numbered from the beginning of the line, with the first word +being denoted by 0 (zero). Words are inserted into the current line +separated by single spaces. + + For example, + +'!!' + designates the preceding command. When you type this, the + preceding command is repeated in toto. + +'!!:$' + designates the last argument of the preceding command. This may be + shortened to '!$'. + +'!fi:2' + designates the second argument of the most recent command starting + with the letters 'fi'. + + Here are the word designators: + +'0 (zero)' + The '0'th word. For many applications, this is the command word. + +'N' + The Nth word. + +'^' + The first argument; that is, word 1. + +'$' + The last argument. + +'%' + The first word matched by the most recent '?STRING?' search, if the + search string begins with a character that is part of a word. + +'X-Y' + A range of words; '-Y' abbreviates '0-Y'. + +'*' + All of the words, except the '0'th. This is a synonym for '1-$'. + It is not an error to use '*' if there is just one word in the + event; the empty string is returned in that case. + +'X*' + Abbreviates 'X-$' + +'X-' + Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is + missing, it defaults to 0. + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: gdb.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +34.1.3 Modifiers +---------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a ':'. These modify, +or edit, the word or words selected from the history event. + +'h' + Remove a trailing pathname component, leaving only the head. + +'t' + Remove all leading pathname components, leaving the tail. + +'r' + Remove a trailing suffix of the form '.SUFFIX', leaving the + basename. + +'e' + Remove all but the trailing suffix. + +'p' + Print the new command but do not execute it. + +'s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any character may be used as the delimiter in place of '/'. The + delimiter may be quoted in OLD and NEW with a single backslash. If + '&' appears in NEW, it is replaced by OLD. A single backslash will + quote the '&'. If OLD is null, it is set to the last OLD + substituted, or, if no previous history substitutions took place, + the last STRING in a !?STRING'[?]' search. If NEW is null, each + matching OLD is deleted. The final delimiter is optional if it is + the last character on the input line. + +'&' + Repeat the previous substitution. + +'g' +'a' + Cause changes to be applied over the entire event line. Used in + conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. + +'G' + Apply the following 's' or '&' modifier once to each word in the + event. + + +File: gdb.info, Node: In Memoriam, Next: Formatting Documentation, Prev: Using History Interactively, Up: Top + +Appendix A In Memoriam +********************** + +The GDB project mourns the loss of the following long-time contributors: + +'Fred Fish' + Fred was a long-standing contributor to GDB (1991-2006), and to + Free Software in general. Outside of GDB, he was known in the + Amiga world for his series of Fish Disks, and the GeekGadget + project. + +'Michael Snyder' + Michael was one of the Global Maintainers of the GDB project, with + contributions recorded as early as 1996, until 2011. In addition + to his day to day participation, he was a large driving force + behind adding Reverse Debugging to GDB. + + Beyond their technical contributions to the project, they were also +enjoyable members of the Free Software Community. We will miss them. + + +File: gdb.info, Node: Formatting Documentation, Next: Installing GDB, Prev: In Memoriam, Up: Top + +Appendix B Formatting Documentation +*********************************** + +The GDB 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the 'gdb' subdirectory +of the main source directory(1). If you can use PostScript or +Ghostscript with your printer, you can print the reference card +immediately with 'refcard.ps'. + + The release also includes the source for the reference card. You can +format it, using TeX, by typing: + + make refcard.dvi + + The GDB reference card is designed to print in "landscape" mode on US +"letter" size paper; that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your DVI output program. + + All the documentation for GDB comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and TeX (or 'texi2roff') to typeset the printed version. + + GDB includes an already formatted copy of the on-line Info version of +this manual in the 'gdb' subdirectory. The main Info file is +'gdb-16.3/gdb/gdb.info', and it refers to subordinate files matching +'gdb.info*' in the same directory. If necessary, you can print out +these files, or read them with any editor; but they are easier to read +using the 'info' subsystem in GNU Emacs or the standalone 'info' +program, available as part of the GNU Texinfo distribution. + + If you want to format these Info files yourself, you need one of the +Info formatting programs, such as 'texinfo-format-buffer' or 'makeinfo'. + + If you have 'makeinfo' installed, and are in the top level GDB source +directory ('gdb-16.3', in the case of version 16.3), you can make the +Info file by typing: + + cd gdb + make gdb.info + + If you want to typeset and print copies of this manual, you need TeX, +a program to print its DVI output files, and 'texinfo.tex', the Texinfo +definitions file. + + TeX is a typesetting program; it does not print files directly, but +produces output files called DVI files. To print a typeset document, +you need a program to print DVI files. If your system has TeX +installed, chances are it has such a program. The precise command to +use depends on your system; 'lpr -d' is common; another (for PostScript +devices) is 'dvips'. The DVI print command may require a file name +without any extension or a '.dvi' extension. + + TeX also requires a macro definitions file called 'texinfo.tex'. +This file tells TeX how to typeset a document written in Texinfo format. +On its own, TeX cannot either read or typeset a Texinfo file. +'texinfo.tex' is distributed with GDB and is located in the +'gdb-VERSION-NUMBER/texinfo' directory. + + If you have TeX and a DVI printer program installed, you can typeset +and print this manual. First switch to the 'gdb' subdirectory of the +main source directory (for example, to 'gdb-16.3/gdb') and type: + + make gdb.dvi + + Then give 'gdb.dvi' to your DVI printing program. + + ---------- Footnotes ---------- + + (1) In 'gdb-16.3/gdb/refcard.ps' of the version 16.3 release. + + +File: gdb.info, Node: Installing GDB, Next: Maintenance Commands, Prev: Formatting Documentation, Up: Top + +Appendix C Installing GDB +************************* + +* Menu: + +* Requirements:: Requirements for building GDB +* Running Configure:: Invoking the GDB 'configure' script +* Separate Objdir:: Compiling GDB in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +* System-wide configuration:: Having a system-wide init file + + +File: gdb.info, Node: Requirements, Next: Running Configure, Up: Installing GDB + +C.1 Requirements for Building GDB +================================= + +Building GDB requires various tools and packages to be available. Other +packages will be used only if they are found. + +Tools/Packages Necessary for Building GDB +========================================= + +C++17 compiler + GDB is written in C++17. It should be buildable with any recent + C++17 compiler, e.g. GCC. + +GNU make + GDB's build system relies on features only found in the GNU make + program. Other variants of 'make' will not work. + +Libraries + The following libraries are mandatory for building GDB. The + 'configure' script searches for each of these libraries in several + standard locations; if some library is installed in an unusual + place, you can use either the '--with-LIB' 'configure' option to + specify its installation directory, or the two separate options + '---with-LIBRARY-include' (to specify the location of its header + files) and '--with-LIBRARY-lib' (to specify the location of its + libraries). For example, for the GMP library, the 3 options are + '--with-gmp', '--with-gmp-include', and '--with-gmp-lib'. *Note + Configure Options::. We mention below the home site of each + library, so that you could download and install them if your system + doesn't already include them. + + GMP (The GNU Multiple Precision arithmetic library) + GDB uses GMP to perform some of its extended-precision + arithmetic. The latest version of GMP is available from + . + + MPFR (The GNU Multiple-precision floating-point library) + GDB uses MPFR to emulate the target floating-point arithmetic + during expression evaluation, if the target uses different + floating-point formats than the host. The latest version of + MPFR is available from . + +Tools/Packages Optional for Building GDB +======================================== + +The tools/packages and libraries listed below are optional; GDB can be +build without them, at the expense of some run-time functionality that +will be missing. As above, we list the home sites for each +package/library, and the command-line options supported by the +'configure' script to specify their installation directories if they are +non-standard. In addition, for each package you can use the option +'--with-PACKAGE' to force GDB to be compiled with the named PACKAGE, and +'--without-PACKAGE' to disable building with it even if it is available. +*Note Configure Options::, for detailed description of the options to +'configure'. + +Python + GDB can be scripted using Python language. *Note Python::. The + latest version is available from + . Use the '--with-python=DIR' + to specify the non-standard directory where Python is installed. + +Guile + GDB can also be scripted using GNU Guile. *Note Guile::. The + latest version can be found on + . If you have more + than one version of Guile installed, use the + '--with-guile=GUILE-VERSION' to specify the Guile version to + include in the build. + +Expat + If available, GDB uses the Expat library for parsing XML files. + GDB uses XML files for the following functionalities: + + * Remote protocol memory maps (*note Memory Map Format::) + * Target descriptions (*note Target Descriptions::) + * Remote shared library lists (*Note Library List Format::, or + alternatively *note Library List Format for SVR4 Targets::) + * MS-Windows shared libraries (*note Shared Libraries::) + * Traceframe info (*note Traceframe Info Format::) + * Branch trace (*note Branch Trace Format::, *note Branch Trace + Configuration Format::) + + The latest version of Expat is available from + . Use the '--with-libexpat-prefix' + to specify non-standard installation places for Expat. + +iconv + GDB's features related to character sets (*note Character Sets::) + require a functioning 'iconv' implementation. If you are on a GNU + system, then this is provided by the GNU C Library. Some other + systems also provide a working 'iconv'. Use the option + '--with-iconv-bin' to specify where to find the 'iconv' program. + + On systems without 'iconv', you can install the GNU Libiconv + library; its latest version can be found on + if your system doesn't + provide it. Use the '--with-libiconv-prefix' option to 'configure' + to specify non-standard installation place for it. + + Alternatively, GDB's top-level 'configure' and 'Makefile' will + arrange to build Libiconv if a directory named 'libiconv' appears + in the top-most source directory. If Libiconv is built this way, + and if the operating system does not provide a suitable 'iconv' + implementation, then the just-built library will automatically be + used by GDB. One easy way to set this up is to download GNU + Libiconv, unpack it inside the top-level directory of the GDB + source tree, and then rename the directory holding the Libiconv + source code to 'libiconv'. + +lzma + GDB can support debugging sections that are compressed with the + LZMA library. *Note MiniDebugInfo::. If this library is not + included with your operating system, you can find it in the xz + package at . Use the + '--with-liblzma-prefix' option to specify its non-standard + location. + +zlib + GDB will use the 'zlib' library, if available, to read compressed + debug sections. Some linkers, such as GNU 'gold', are capable of + producing binaries with compressed debug sections. If GDB is + compiled with 'zlib', it will be able to read the debug information + in such binaries. + + The 'zlib' library is likely included with your operating system + distribution; if it is not, you can get the latest version from + . + + +File: gdb.info, Node: Running Configure, Next: Separate Objdir, Prev: Requirements, Up: Installing GDB + +C.2 Invoking the GDB 'configure' Script +======================================= + +GDB comes with a 'configure' script that automates the process of +preparing GDB for installation; you can then use 'make' to build the +'gdb' program. + + The GDB distribution includes all the source code you need for GDB in +a single directory, whose name is usually composed by appending the +version number to 'gdb'. + + For example, the GDB version 16.3 distribution is in the 'gdb-16.3' +directory. That directory contains: + +'gdb-16.3/configure (and supporting files)' + script for configuring GDB and all its supporting libraries + +'gdb-16.3/gdb' + the source specific to GDB itself + +'gdb-16.3/bfd' + source for the Binary File Descriptor library + +'gdb-16.3/include' + GNU include files + +'gdb-16.3/libiberty' + source for the '-liberty' free software library + +'gdb-16.3/opcodes' + source for the library of opcode tables and disassemblers + +'gdb-16.3/readline' + source for the GNU command-line interface + + There may be other subdirectories as well. + + The simplest way to configure and build GDB is to run 'configure' +from the 'gdb-VERSION-NUMBER' source directory, which in this example is +the 'gdb-16.3' directory. + + First switch to the 'gdb-VERSION-NUMBER' source directory if you are +not already in it; then run 'configure'. Pass the identifier for the +platform on which GDB will run as an argument. + + For example: + + cd gdb-16.3 + ./configure + make + + Running 'configure' and then running 'make' builds the included +supporting libraries, then 'gdb' itself. The configured source files, +and the binaries, are left in the corresponding source directories. + + 'configure' is a Bourne-shell ('/bin/sh') script; if your system does +not recognize this automatically when you run a different shell, you may +need to run 'sh' on it explicitly: + + sh configure + + You should run the 'configure' script from the top directory in the +source tree, the 'gdb-VERSION-NUMBER' directory. If you run 'configure' +from one of the subdirectories, you will configure only that +subdirectory. That is usually not what you want. In particular, if you +run the first 'configure' from the 'gdb' subdirectory of the +'gdb-VERSION-NUMBER' directory, you will omit the configuration of +'bfd', 'readline', and other sibling directories of the 'gdb' +subdirectory. This leads to build errors about missing include files +such as 'bfd/bfd.h'. + + You can install 'GDB' anywhere. The best way to do this is to pass +the '--prefix' option to 'configure', and then install it with 'make +install'. + + +File: gdb.info, Node: Separate Objdir, Next: Config Names, Prev: Running Configure, Up: Installing GDB + +C.3 Compiling GDB in Another Directory +====================================== + +If you want to run GDB versions for several host or target machines, you +need a different 'gdb' compiled for each combination of host and target. +'configure' is designed to make this easy by allowing you to generate +each configuration in a separate subdirectory, rather than in the source +directory. If your 'make' program handles the 'VPATH' feature (GNU +'make' does), running 'make' in each of these directories builds the +'gdb' program specified there. + + To build 'gdb' in a separate directory, run 'configure' with the +'--srcdir' option to specify where to find the source. (You also need +to specify a path to find 'configure' itself from your working +directory. If the path to 'configure' would be the same as the argument +to '--srcdir', you can leave out the '--srcdir' option; it is assumed.) + + For example, with version 16.3, you can build GDB in a separate +directory for a Sun 4 like this: + + cd gdb-16.3 + mkdir ../gdb-sun4 + cd ../gdb-sun4 + ../gdb-16.3/configure + make + + When 'configure' builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library 'libiberty.a' in the directory +'gdb-sun4/libiberty', and GDB itself in 'gdb-sun4/gdb'. + + Make sure that your path to the 'configure' script has just one +instance of 'gdb' in it. If your path to 'configure' looks like +'../gdb-16.3/gdb/configure', you are configuring only one subdirectory +of GDB, not the whole package. This leads to build errors about missing +include files such as 'bfd/bfd.h'. + + One popular reason to build several GDB configurations in separate +directories is to configure GDB for cross-compiling (where GDB runs on +one machine--the "host"--while debugging programs that run on another +machine--the "target"). You specify a cross-debugging target by giving +the '--target=TARGET' option to 'configure'. + + When you run 'make' to build a program or library, you must run it in +a configured directory--whatever directory you were in when you called +'configure' (or one of its subdirectories). + + The 'Makefile' that 'configure' generates in each source directory +also runs recursively. If you type 'make' in a source directory such as +'gdb-16.3' (or in a separate configured directory configured with +'--srcdir=DIRNAME/gdb-16.3'), you will build all the required libraries, +and then build GDB. + + When you have multiple hosts or targets configured in separate +directories, you can run 'make' on them in parallel (for example, if +they are NFS-mounted on each of the hosts); they will not interfere with +each other. + + +File: gdb.info, Node: Config Names, Next: Configure Options, Prev: Separate Objdir, Up: Installing GDB + +C.4 Specifying Names for Hosts and Targets +========================================== + +The specifications used for hosts and targets in the 'configure' script +are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: + + ARCHITECTURE-VENDOR-OS + + For example, you can use the alias 'sun4' as a HOST argument, or as +the value for TARGET in a '--target=TARGET' option. The equivalent full +name is 'sparc-sun-sunos4'. + + The 'configure' script accompanying GDB does not provide any query +facility to list all supported host and target names or aliases. +'configure' calls the Bourne shell script 'config.sub' to map +abbreviations to full names; you can read the script, if you wish, or +you can use it to test your guesses on abbreviations--for example: + + % sh config.sub i386-linux + i386-pc-linux-gnu + % sh config.sub alpha-linux + alpha-unknown-linux-gnu + % sh config.sub hp9k700 + hppa1.1-hp-hpux + % sh config.sub sun4 + sparc-sun-sunos4.1.1 + % sh config.sub sun3 + m68k-sun-sunos4.1.1 + % sh config.sub i986v + Invalid configuration `i986v': machine `i986v' not recognized + +'config.sub' is also distributed in the GDB source directory +('gdb-16.3', for version 16.3). + + +File: gdb.info, Node: Configure Options, Next: System-wide configuration, Prev: Config Names, Up: Installing GDB + +C.5 'configure' Options +======================= + +Here is a summary of the 'configure' options and arguments that are most +often useful for building GDB. 'configure' also has several other +options not listed here. *Note (autoconf)Running configure Scripts::, +for a full explanation of 'configure'. + + configure [--help] + [--prefix=DIR] + [--exec-prefix=DIR] + [--srcdir=DIRNAME] + [--target=TARGET] + +You may introduce options with a single '-' rather than '--' if you +prefer; but you may abbreviate option names if you use '--'. + +'--help' + Display a quick summary of how to invoke 'configure'. + +'--prefix=DIR' + Configure the source to install programs and files under directory + 'DIR'. + +'--exec-prefix=DIR' + Configure the source to install programs under directory 'DIR'. + +'--srcdir=DIRNAME' + Use this option to make configurations in directories separate from + the GDB source directories. Among other things, you can use this + to build (or maintain) several configurations simultaneously, in + separate directories. 'configure' writes configuration-specific + files in the current directory, but arranges for them to use the + source in the directory DIRNAME. 'configure' creates directories + under the working directory in parallel to the source directories + below DIRNAME. + +'--target=TARGET' + Configure GDB for cross-debugging programs running on the specified + TARGET. Without this option, GDB is configured to debug programs + that run on the same machine (HOST) as GDB itself. + + There is no convenient way to generate a list of all available + targets. Also see the '--enable-targets' option, below. + + There are many other options that are specific to GDB. This lists +just the most common ones; there are some very specialized options not +described here. + +'--enable-targets=[TARGET]...' +'--enable-targets=all' + Configure GDB for cross-debugging programs running on the specified + list of targets. The special value 'all' configures GDB for + debugging programs running on any target it supports. + +'--with-gdb-datadir=PATH' + Set the GDB-specific data directory. GDB will look here for + certain supporting files or scripts. This defaults to the 'gdb' + subdirectory of 'datadir' (which can be set using '--datadir'). + +'--with-relocated-sources=DIR' + Sets up the default source path substitution rule so that directory + names recorded in debug information will be automatically adjusted + for any directory under DIR. DIR should be a subdirectory of GDB's + configured prefix, the one mentioned in the '--prefix' or + '--exec-prefix' options to configure. This option is useful if GDB + is supposed to be moved to a different place after it is built. + +'--enable-64-bit-bfd' + Enable 64-bit support in BFD on 32-bit hosts. + +'--disable-gdbmi' + Build GDB without the GDB/MI machine interface (*note GDB/MI::). + +'--enable-tui' + Build GDB with the text-mode full-screen user interface (TUI). + Requires a curses library (ncurses and cursesX are also supported). + +'--with-curses' + Use the curses library instead of the termcap library, for + text-mode terminal operations. + +'--with-debuginfod' + Build GDB with 'libdebuginfod', the 'debuginfod' client library. + Used to automatically fetch ELF, DWARF and source files from + 'debuginfod' servers using build IDs associated with any missing + files. Enabled by default if 'libdebuginfod' is installed and + found at configure time. For more information regarding + 'debuginfod' see *note Debuginfod::. + +'--with-libunwind-ia64' + Use the libunwind library for unwinding function call stack on ia64 + target platforms. See + for details. + +'--with-system-readline' + Use the readline library installed on the host, rather than the + library supplied as part of GDB. Readline 7 or newer is required; + this is enforced by the build system. + +'--with-system-zlib' + Use the zlib library installed on the host, rather than the library + supplied as part of GDB. + +'--with-expat' + Build GDB with Expat, a library for XML parsing. (Done by default + if libexpat is installed and found at configure time.) This + library is used to read XML files supplied with GDB. If it is + unavailable, some features, such as remote protocol memory maps, + target descriptions, and shared library lists, that are based on + XML files, will not be available in GDB. If your host does not + have libexpat installed, you can get the latest version from + . + +'--with-libiconv-prefix[=DIR]' + Build GDB with GNU libiconv, a character set encoding conversion + library. This is not done by default, as on GNU systems the + 'iconv' that is built in to the C library is sufficient. If your + host does not have a working 'iconv', you can get the latest + version of GNU iconv from . + + GDB's build system also supports building GNU libiconv as part of + the overall build. *Note Requirements::. + +'--with-lzma' + Build GDB with LZMA, a compression library. (Done by default if + liblzma is installed and found at configure time.) LZMA is used by + GDB's "mini debuginfo" feature, which is only useful on platforms + using the ELF object file format. If your host does not have + liblzma installed, you can get the latest version from + . + +'--with-python[=PYTHON]' + Build GDB with Python scripting support. (Done by default if + libpython is present and found at configure time.) Python makes + GDB scripting much more powerful than the restricted CLI scripting + language. If your host does not have Python installed, you can + find it on . The oldest version + of Python supported by GDB is 3.0.1. The optional argument PYTHON + is used to find the Python headers and libraries. It can be either + the name of a Python executable, or the name of the directory in + which Python is installed. + +'--with-guile[=GUILE]' + Build GDB with GNU Guile scripting support. (Done by default if + libguile is present and found at configure time.) If your host + does not have Guile installed, you can find it at + . The optional argument GUILE + can be a version number, which will cause 'configure' to try to use + that version of Guile; or the file name of a 'pkg-config' + executable, which will be queried to find the information needed to + compile and link against Guile. + +'--without-included-regex' + Don't use the regex library included with GDB (as part of the + libiberty library). This is the default on hosts with version 2 of + the GNU C library. + +'--with-sysroot=DIR' + Use DIR as the default system root directory for libraries whose + file names begin with '/lib'' or '/usr/lib''. (The value of DIR + can be modified at run time by using the 'set sysroot' command.) + If DIR is under the GDB configured prefix (set with '--prefix' or + '--exec-prefix options', the default system root will be + automatically adjusted if and when GDB is moved to a different + location. + +'--with-system-gdbinit=FILE' + Configure GDB to automatically load a system-wide init file. FILE + should be an absolute file name. If FILE is in a directory under + the configured prefix, and GDB is moved to another location after + being built, the location of the system-wide init file will be + adjusted accordingly. + +'--with-system-gdbinit-dir=DIRECTORY' + Configure GDB to automatically load init files from a system-wide + directory. DIRECTORY should be an absolute directory name. If + DIRECTORY is in a directory under the configured prefix, and GDB is + moved to another location after being built, the location of the + system-wide init directory will be adjusted accordingly. + +'--enable-build-warnings' + When building the GDB sources, ask the compiler to warn about any + code which looks even vaguely suspicious. It passes many different + warning flags, depending on the exact version of the compiler you + are using. + +'--enable-werror' + Treat compiler warnings as errors. It adds the '-Werror' flag to + the compiler, which will fail the compilation if the compiler + outputs any warning messages. + +'--enable-ubsan' + Enable the GCC undefined behavior sanitizer. This is disabled by + default, but passing '--enable-ubsan=yes' or '--enable-ubsan=auto' + to 'configure' will enable it. The undefined behavior sanitizer + checks for C++ undefined behavior. It has a performance cost, so + if you are looking at GDB's performance, you should disable it. + The undefined behavior sanitizer was first introduced in GCC 4.9. + + +File: gdb.info, Node: System-wide configuration, Prev: Configure Options, Up: Installing GDB + +C.6 System-wide configuration and settings +========================================== + +GDB can be configured to have a system-wide init file and a system-wide +init file directory; this file and files in that directory (if they have +a recognized file extension) will be read and executed at startup (*note +What GDB does during startup: Startup.). + + Here are the corresponding configure options: + +'--with-system-gdbinit=FILE' + Specify that the default location of the system-wide init file is + FILE. +'--with-system-gdbinit-dir=DIRECTORY' + Specify that the default location of the system-wide init file + directory is DIRECTORY. + + If GDB has been configured with the option '--prefix=$prefix', they +may be subject to relocation. Two possible cases: + + * If the default location of this init file/directory contains + '$prefix', it will be subject to relocation. Suppose that the + configure options are '--prefix=$prefix + --with-system-gdbinit=$prefix/etc/gdbinit'; if GDB is moved from + '$prefix' to '$install', the system init file is looked for as + '$install/etc/gdbinit' instead of '$prefix/etc/gdbinit'. + + * By contrast, if the default location does not contain the prefix, + it will not be relocated. E.g. if GDB has been configured with + '--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit', + then GDB will always look for '/usr/share/gdb/gdbinit', wherever + GDB is installed. + + If the configured location of the system-wide init file (as given by +the '--with-system-gdbinit' option at configure time) is in the +data-directory (as specified by '--with-gdb-datadir' at configure time) +or in one of its subdirectories, then GDB will look for the system-wide +init file in the directory specified by the '--data-directory' +command-line option. Note that the system-wide init file is only read +once, during GDB initialization. If the data-directory is changed after +GDB has started with the 'set data-directory' command, the file will not +be reread. + + This applies similarly to the system-wide directory specified in +'--with-system-gdbinit-dir'. + + Any supported scripting language can be used for these init files, as +long as the file extension matches the scripting language. To be +interpreted as regular GDB commands, the files needs to have a '.gdb' +extension. + +* Menu: + +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts + + +File: gdb.info, Node: System-wide Configuration Scripts, Up: System-wide configuration + +C.6.1 Installed System-wide Configuration Scripts +------------------------------------------------- + +The 'system-gdbinit' directory, located inside the data-directory (as +specified by '--with-gdb-datadir' at configure time) contains a number +of scripts which can be used as system-wide init files. To +automatically source those scripts at startup, GDB should be configured +with '--with-system-gdbinit'. Otherwise, any user should be able to +source them by hand as needed. + + The following scripts are currently available: + + * 'elinos.py' This script is useful when debugging a program on an + ELinOS target. It takes advantage of the environment variables + defined in a standard ELinOS environment in order to determine the + location of the system shared libraries, and then sets the + 'solib-absolute-prefix' and 'solib-search-path' variables + appropriately. + + * 'wrs-linux.py' This script is useful when debugging a program on a + target running Wind River Linux. It expects the 'ENV_PREFIX' to be + set to the host-side sysroot used by the target system. + + +File: gdb.info, Node: Maintenance Commands, Next: Remote Protocol, Prev: Installing GDB, Up: Top + +Appendix D Maintenance Commands +******************************* + +In addition to commands intended for GDB users, GDB includes a number of +commands intended for GDB developers, that are not documented elsewhere +in this manual. These commands are provided here for reference. (For +commands that turn on debugging messages, see *note Debugging Output::.) + +'maint agent [-at LINESPEC,] EXPRESSION' +'maint agent-eval [-at LINESPEC,] EXPRESSION' + Translate the given EXPRESSION into remote agent bytecodes. This + command is useful for debugging the Agent Expression mechanism + (*note Agent Expressions::). The 'agent' version produces an + expression useful for data collection, such as by tracepoints, + while 'maint agent-eval' produces an expression that evaluates + directly to a result. For instance, a collection expression for + 'globa + globb' will include bytecodes to record four bytes of + memory at each of the addresses of 'globa' and 'globb', while + discarding the result of the addition, while an evaluation + expression will do the addition and return the sum. If '-at' is + given, generate remote agent bytecode for all the addresses to + which LINESPEC resolves (*note Linespec Locations::). If not, + generate remote agent bytecode for current frame PC address. + +'maint agent-printf FORMAT,EXPR,...' + Translate the given format string and list of argument expressions + into remote agent bytecodes and display them as a disassembled + list. This command is useful for debugging the agent version of + dynamic printf (*note Dynamic Printf::). + +'maint info breakpoints' + Using the same format as 'info breakpoints', display both the + breakpoints you've set explicitly, and those GDB is using for + internal purposes. Internal breakpoints are shown with negative + breakpoint numbers. The type column identifies what kind of + breakpoint is shown: + + 'breakpoint' + Normal, explicitly set breakpoint. + + 'watchpoint' + Normal, explicitly set watchpoint. + + 'longjmp' + Internal breakpoint, used to handle correctly stepping through + 'longjmp' calls. + + 'longjmp resume' + Internal breakpoint at the target of a 'longjmp'. + + 'until' + Temporary internal breakpoint used by the GDB 'until' command. + + 'finish' + Temporary internal breakpoint used by the GDB 'finish' + command. + + 'shlib events' + Shared library events. + +'maint info btrace' + Pint information about raw branch tracing data. + +'maint btrace packet-history' + Print the raw branch trace packets that are used to compute the + execution history for the 'record btrace' command. Both the + information and the format in which it is printed depend on the + btrace recording format. + + 'bts' + For the BTS recording format, print a list of blocks of + sequential code. For each block, the following information is + printed: + + Block number + Newer blocks have higher numbers. The oldest block has + number zero. + Lowest 'PC' + Highest 'PC' + + 'pt' + For the Intel Processor Trace recording format, print a list + of Intel Processor Trace packets. For each packet, the + following information is printed: + + Packet number + Newer packets have higher numbers. The oldest packet has + number zero. + Trace offset + The packet's offset in the trace stream. + Packet opcode and payload + +'maint btrace clear-packet-history' + Discards the cached packet history printed by the 'maint btrace + packet-history' command. The history will be computed again when + needed. + +'maint btrace clear' + Discard the branch trace data. The data will be fetched anew and + the branch trace will be recomputed when needed. + + This implicitly truncates the branch trace to a single branch trace + buffer. When updating branch trace incrementally, the branch trace + available to GDB may be bigger than a single branch trace buffer. + +'maint set btrace pt skip-pad' +'maint show btrace pt skip-pad' + Control whether GDB will skip PAD packets when computing the packet + history. + +'maint info jit' + Print information about JIT code objects loaded in the current + inferior. + +'maint info python-disassemblers' + This command is defined within the 'gdb.disassembler' Python module + (*note Disassembly In Python::), and will only be present after + that module has been imported. To force the module to be imported + do the following: + +'maint info linux-lwps' + Print information about LWPs under control of the Linux native + target. + + (gdb) python import gdb.disassembler + + This command lists all the architectures for which a disassembler + is currently registered, and the name of the disassembler. If a + disassembler is registered for all architectures, then this is + listed last against the 'GLOBAL' architecture. + + If one of the disassemblers would be selected for the architecture + of the current inferior, then this disassembler will be marked. + + The following example shows a situation in which two disassemblers + are registered, initially the 'i386' disassembler matches the + current architecture, then the architecture is changed, now the + 'GLOBAL' disassembler matches. + + (gdb) show architecture + The target architecture is set to "auto" (currently "i386"). + (gdb) maint info python-disassemblers + Architecture Disassember Name + i386 Disassembler_1 (Matches current architecture) + GLOBAL Disassembler_2 + (gdb) set architecture arm + The target architecture is set to "arm". + (gdb) maint info python-disassemblers + quit + Architecture Disassember Name + i386 Disassembler_1 + GLOBAL Disassembler_2 (Matches current architecture) + +'set displaced-stepping' +'show displaced-stepping' + Control whether or not GDB will do "displaced stepping" if the + target supports it. Displaced stepping is a way to single-step + over breakpoints without removing them from the inferior, by + executing an out-of-line copy of the instruction that was + originally at the breakpoint location. It is also known as + out-of-line single-stepping. + + 'set displaced-stepping on' + If the target architecture supports it, GDB will use displaced + stepping to step over breakpoints. + + 'set displaced-stepping off' + GDB will not use displaced stepping to step over breakpoints, + even if such is supported by the target architecture. + + 'set displaced-stepping auto' + This is the default mode. GDB will use displaced stepping + only if non-stop mode is active (*note Non-Stop Mode::) and + the target architecture supports displaced stepping. + +'maint check-psymtabs' + Check the consistency of currently expanded psymtabs versus + symtabs. Use this to check, for example, whether a symbol is in + one but not the other. + +'maint check-symtabs' + Check the consistency of currently expanded symtabs. + +'maint expand-symtabs [REGEXP]' + Expand symbol tables. If REGEXP is specified, only expand symbol + tables for file names matching REGEXP. + +'maint set catch-demangler-crashes [on|off]' +'maint show catch-demangler-crashes' + Control whether GDB should attempt to catch crashes in the symbol + name demangler. The default is to attempt to catch crashes. If + enabled, the first time a crash is caught, a core file is created, + the offending symbol is displayed and the user is presented with + the option to terminate the current session. + +'maint cplus first_component NAME' + Print the first C++ class/namespace component of NAME. + +'maint cplus namespace' + Print the list of possible C++ namespaces. + +'maint deprecate COMMAND [REPLACEMENT]' +'maint undeprecate COMMAND' + Deprecate or undeprecate the named COMMAND. Deprecated commands + cause GDB to issue a warning when you use them. The optional + argument REPLACEMENT says which newer command should be used in + favor of the deprecated one; if it is given, GDB will mention the + replacement as part of the warning. + +'maint dump-me' + Cause a fatal signal in the debugger and force it to dump its core. + This is supported only on systems which support aborting a program + with the 'SIGQUIT' signal. + +'maint internal-error [MESSAGE-TEXT]' +'maint internal-warning [MESSAGE-TEXT]' +'maint demangler-warning [MESSAGE-TEXT]' + + Cause GDB to call the internal function 'internal_error', + 'internal_warning' or 'demangler_warning' and hence behave as + though an internal problem has been detected. In addition to + reporting the internal problem, these functions give the user the + opportunity to either quit GDB or (for 'internal_error' and + 'internal_warning') create a core file of the current GDB session. + + These commands take an optional parameter MESSAGE-TEXT that is used + as the text of the error or warning message. + + Here's an example of using 'internal-error': + + (gdb) maint internal-error testing, 1, 2 + .../maint.c:121: internal-error: testing, 1, 2 + A problem internal to GDB has been detected. Further + debugging may prove unreliable. + Quit this debugging session? (y or n) n + Create a core file? (y or n) n + (gdb) + +'maint set debuginfod download-sections' +'maint set debuginfod download-sections [on|off]' +'maint show debuginfod download-sections' + Controls whether GDB will attempt to download individual ELF/DWARF + sections from 'debuginfod'. If disabled, only whole debug info + files will be downloaded; this could result in GDB downloading + larger amounts of data. + +'maint set internal-error ACTION [ask|yes|no]' +'maint show internal-error ACTION' +'maint set internal-warning ACTION [ask|yes|no]' +'maint show internal-warning ACTION' +'maint set demangler-warning ACTION [ask|yes|no]' +'maint show demangler-warning ACTION' + When GDB reports an internal problem (error or warning) it gives + the user the opportunity to both quit GDB and create a core file of + the current GDB session. These commands let you override the + default behavior for each particular ACTION, described in the table + below. + + 'quit' + You can specify that GDB should always (yes) or never (no) + quit. The default is to ask the user what to do. + + 'corefile' + You can specify that GDB should always (yes) or never (no) + create a core file. The default is to ask the user what to + do. Note that there is no 'corefile' option for + 'demangler-warning': demangler warnings always create a core + file and this cannot be disabled. + +'maint set internal-error backtrace [on|off]' +'maint show internal-error backtrace' +'maint set internal-warning backtrace [on|off]' +'maint show internal-warning backtrace' + When GDB reports an internal problem (error or warning) it is + possible to have a backtrace of GDB printed to the standard error + stream. This is 'on' by default for 'internal-error' and 'off' by + default for 'internal-warning'. + +'maint packet TEXT' + If GDB is talking to an inferior via the serial protocol, then this + command sends the string TEXT to the inferior, and displays the + response packet. GDB supplies the initial '$' character, the + terminating '#' character, and the checksum. + + Any non-printable characters in the reply are printed as escaped + hex, e.g. '\x00', '\x01', etc. + +'maint print architecture [FILE]' + Print the entire architecture configuration. The optional argument + FILE names the file where the output goes. + +'maint print c-tdesc [-single-feature] [FILE]' + Print the target description (*note Target Descriptions::) as a C + source file. By default, the target description is for the current + target, but if the optional argument FILE is provided, that file is + used to produce the description. The FILE should be an XML + document, of the form described in *note Target Description + Format::. The created source file is built into GDB when GDB is + built again. This command is used by developers after they add or + modify XML target descriptions. + + When the optional flag '-single-feature' is provided then the + target description being processed (either the default, or from + FILE) must only contain a single feature. The source file produced + is different in this case. + + The FILE argument supports escaping and quoting, see *note + Filenames As Command Arguments: Filename Arguments. + +'maint print xml-tdesc [FILE]' + Print the target description (*note Target Descriptions::) as an + XML file. By default print the target description for the current + target, but if the optional argument FILE is provided, then that + file is read in by GDB and then used to produce the description. + The FILE should be an XML document, of the form described in *note + Target Description Format::. + +'maint check xml-descriptions DIR' + Check that the target descriptions dynamically created by GDB equal + the descriptions created from XML files found in DIR. + +'maint check libthread-db' + Run integrity checks on the current inferior's thread debugging + library. This exercises all 'libthread_db' functionality used by + GDB on GNU/Linux systems, and by extension also exercises the + 'proc_service' functions provided by GDB that 'libthread_db' uses. + Note that parts of the test may be skipped on some platforms when + debugging core files. + +'maint print core-file-backed-mappings' + Print the file-backed mappings which were loaded from a core file + note. This output represents state internal to GDB and should be + similar to the mappings displayed by the 'info proc mappings' + command. + +'maint print dummy-frames' + Prints the contents of GDB's internal dummy-frame stack. + + (gdb) b add + ... + (gdb) print add(2,3) + Breakpoint 2, add (a=2, b=3) at ... + 58 return (a + b); + The program being debugged stopped while in a function called from GDB. + ... + (gdb) maint print dummy-frames + 0xa8206d8: id={stack=0xbfffe734,code=0xbfffe73f,!special}, ptid=process 9353 + (gdb) + + Takes an optional file parameter. + +'maint print frame-id' +'maint print frame-id LEVEL' + Print GDB's internal frame-id for the frame at relative LEVEL, or + for the currently selected frame when LEVEL is not given. + + If used, LEVEL should be an integer, as displayed in the + 'backtrace' output. + + (gdb) maint print frame-id + frame-id for frame #0: {stack=0x7fffffffac70,code=0x0000000000401106,!special} + (gdb) maint print frame-id 2 + frame-id for frame #2: {stack=0x7fffffffac90,code=0x000000000040111c,!special} + +'maint info inline-frames' +'maint info inline-frames ADDRESS' + Print information about inlined frames which start at the current + address, or ADDRESS if specified. + + In order to allow the user to correctly step into inlined + functions, GDB needs to identify which inlined functions start at a + particular address, and GDB also needs to track which of these + functions was last displayed to the user as the current frame. + + Imagine a situation where function 'main' calls 'foo', which then + calls 'bar', something like this: + + int + main () + { + /* Some interesting code here... */ + + foo (); + + /* More interesting code here... */ + } + + void + foo () + { + bar (); + } + + void + bar () + { + /* Some interesting code here... */ + } + + As both 'foo' and 'bar' are inlined within 'main' then there could + be one address within 'main' which is also the start of 'foo' and + also the start of 'bar'. When the user stops at this address they + will initially be told the inferior is in 'main', if the user does + a 'step' then GDB doesn't actually step the inferior, instead the + user is told the inferior entered 'foo'. After the next 'step' the + user is told the inferior entered 'bar'. The 'maint info + inline-frames' command can be used to view this internal GDB state, + like this: + + (gdb) step + 24 foo (); + (gdb) maintenance info inline-frames + Cached inline state information for thread 1. + program counter = 0x401137 + skipped frames = 2 + bar + foo + > main + + Here the user is stopped in 'main' at the call to 'foo'. The + inline-frames information shows that at this address GDB has found + the start of inlined functions 'bar' and 'foo', but currently GDB + has skipped 2 frames and considers 'main' to be the current frame, + this is indicated with the '>'. + + If the user performs a 'step' to enter 'foo' then the situation is + updated: + + (gdb) step + foo () at inline.c:14 + 14 bar (); + (gdb) maintenance info inline-frames + Cached inline state information for thread 1. + program counter = 0x401137 + skipped frames = 1 + bar + > foo + main + + Notice that the program counter value '0x401137' hasn't change, but + now GDB considers 'foo' to be the current frame, and it is marked + as such with the '>'. + + Finally, the user performs another 'step' to enter 'bar': + + (gdb) step + bar () at inline.c:6 + 6 ++global_counter; + (gdb) maintenance info inline-frames + Cached inline state information for thread 1. + program counter = 0x401137 + skipped frames = 0 + > bar + foo + main + +'maint info blocks' +'maint info blocks ADDRESS' + Print information about all blocks at ADDRESS, or at the current + '$pc' if ADDRESS is not given. + + For information about what blocks are in GDB see *note Blocks In + Python::. + + Blocks are listed starting from the global block, then the static + block, and then proceeding through progressively narrower scopes. + + Here is an example of the command's output: + (gdb) maintenance info blocks + Blocks at 0x401137: + from objfile: [(objfile *) 0x50507d0] /tmp/inline_func_demo + + [(block *) 0x504da90] 0x401106..0x40119a + entry pc: 0x401106 + is global block + symbol count: 2 + is contiguous + [(block *) 0x504d9f0] 0x401106..0x40119a + entry pc: 0x401106 + is static block + symbol count: 1 + is contiguous + [(block *) 0x504d9a0] 0x401106..0x40119a + entry pc: 0x401106 + function: main + is contiguous + [(block *) 0x504d900] 0x401137..0x401166 + entry pc: 0x401137 + inline function: foo + symbol count: 1 + is contiguous + [(block *) 0x504d860] 0x401137..0x401165 + entry pc: 0x401137 + inline function: bar + symbol count: 1 + is contiguous + + The command 'maint info blocks' lists the symbol count for each + block but doesn't print the symbols themselves. The symbol names + can be found using 'maint print symbols' (*note maint print + symbols::). + +'maint print registers [FILE]' +'maint print raw-registers [FILE]' +'maint print cooked-registers [FILE]' +'maint print register-groups [FILE]' +'maint print remote-registers [FILE]' + Print GDB's internal register data structures. + + The command 'maint print raw-registers' includes the contents of + the raw register cache; the command 'maint print cooked-registers' + includes the (cooked) value of all registers, including registers + which aren't available on the target nor visible to user; the + command 'maint print register-groups' includes the groups that each + register is a member of; and the command 'maint print + remote-registers' includes the remote target's register numbers and + offsets in the 'G' packets, as well as an indication of which + registers were included in the last stop reply packet received by + GDB (*note Stop Reply Packets::). Please note that the list of + registers included in a stop reply can change from one stop to the + next. + + These commands take an optional parameter, a file name to which to + write the information. + +'maint print reggroups [FILE]' + Print GDB's internal register group data structures. The optional + argument FILE tells to what file to write the information. + + The register groups info looks like this: + + (gdb) maint print reggroups + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal + +'maint flush register-cache' +'flushregs' + Flush the contents of the register cache and as a consequence the + frame cache. This command is useful when debugging issues related + to register fetching, or frame unwinding. The command 'flushregs' + is deprecated in favor of 'maint flush register-cache'. + +'maint flush source-cache' + Flush GDB's cache of source code file contents. After GDB reads a + source file, and optionally applies styling (*note Output + Styling::), the file contents are cached. This command clears that + cache. The next time GDB wants to show lines from a source file, + the content will be re-read. + + This command is useful when debugging issues related to source code + styling. After flushing the cache any source code displayed by GDB + will be re-read and re-styled. + +'maint print objfiles [REGEXP]' + Print a dump of all known object files. If REGEXP is specified, + only print object files whose names match REGEXP. For each object + file, this command prints its name, address in memory, and all of + its psymtabs and symtabs. + +'maint print user-registers' + List all currently available "user registers". User registers + typically provide alternate names for actual hardware registers. + They include the four "standard" registers '$fp', '$pc', '$sp', and + '$ps'. *Note standard registers::. User registers can be used in + expressions in the same way as the canonical register names, but + only the latter are listed by the 'info registers' and 'maint print + registers' commands. + +'maint print section-scripts [REGEXP]' + Print a dump of scripts specified in the '.debug_gdb_section' + section. If REGEXP is specified, only print scripts loaded by + object files matching REGEXP. For each script, this command prints + its name as specified in the objfile, and the full path if known. + *Note dotdebug_gdb_scripts section::. + +'maint print statistics' + This command prints, for each object file in the program, various + data about that object file followed by the byte cache ("bcache") + statistics for the object file. The objfile data includes the + number of minimal, partial, full, and stabs symbols, the number of + types defined by the objfile, the number of as yet unexpanded psym + tables, the number of line tables and string tables, and the amount + of memory used by the various tables. The bcache statistics + include the counts, sizes, and counts of duplicates of all and + unique objects, max, average, and median entry size, total memory + used and its overhead and savings, and various measures of the hash + table size and chain lengths. + +'maint print target-stack' + A "target" is an interface between the debugger and a particular + kind of file or process. Targets can be stacked in "strata", so + that more than one target can potentially respond to a request. In + particular, memory accesses will walk down the stack of targets + until they find a target that is interested in handling that + particular address. + + This command prints a short description of each layer that was + pushed on the "target stack", starting from the top layer down to + the bottom one. + +'maint print type EXPR' + Print the type chain for a type specified by EXPR. The argument + can be either a type name or a symbol. If it is a symbol, the type + of that symbol is described. The type chain produced by this + command is a recursive definition of the data type as stored in + GDB's data structures, including its flags and contained types. + +'maint print record-instruction' +'maint print record-instruction N' + print how GDB recorded a given instruction. If N is not positive + number, it prints the values stored by the inferior before the N-th + previous instruction was executed. If N is positive, print the + values after the N-th following instruction is executed. If N is + not given, 0 is assumed. + +'maint selftest [-verbose] [FILTER]' + Run any self tests that were compiled in to GDB. This will print a + message showing how many tests were run, and how many failed. If a + FILTER is passed, only the tests with FILTER in their name will be + ran. If '-verbose' is passed, the self tests can be more verbose. + +'maint set selftest verbose' +'maint show selftest verbose' + Control whether self tests are run verbosely or not. + +'maint info selftests' + List the selftests compiled in to GDB. + +'maint set dwarf always-disassemble' +'maint show dwarf always-disassemble' + Control the behavior of 'info address' when using DWARF debugging + information. + + The default is 'off', which means that GDB should try to describe a + variable's location in an easily readable format. When 'on', GDB + will instead display the DWARF location expression in an + assembly-like format. Note that some locations are too complex for + GDB to describe simply; in this case you will always see the + disassembly form. + + Here is an example of the resulting disassembly: + + (gdb) info addr argc + Symbol "argc" is a complex DWARF expression: + 1: DW_OP_fbreg 0 + + For more information on these expressions, see the DWARF standard + (http://www.dwarfstd.org/). + +'maint set dwarf max-cache-age' +'maint show dwarf max-cache-age' + Control the DWARF compilation unit cache. + + In object files with inter-compilation-unit references, such as + those produced by the GCC option '-feliminate-dwarf2-dups', the + DWARF reader needs to frequently refer to previously read + compilation units. This setting controls how long a compilation + unit will remain in the cache if it is not referenced. A higher + limit means that cached compilation units will be stored in memory + longer, and more total memory will be used. Setting it to zero + disables caching, which will slow down GDB startup, but reduce + memory consumption. + +'maint set dwarf synchronous' +'maint show dwarf synchronous' + Control whether DWARF is read asynchronously. + + On hosts where threading is available, the DWARF reader is mostly + asynchronous with respect to the rest of GDB. That is, the bulk of + the reading is done in the background, and GDB will only pause for + completion of this task when absolutely necessary. + + When this setting is enabled, GDB will instead wait for DWARF + processing to complete before continuing. + + On hosts without threading, or where worker threads have been + disabled at runtime, this setting has no effect, as DWARF reading + is always done on the main thread, and is therefore always + synchronous. + +'maint set dwarf unwinders' +'maint show dwarf unwinders' + Control use of the DWARF frame unwinders. + + Many targets that support DWARF debugging use GDB's DWARF frame + unwinders to build the backtrace. Many of these targets will also + have a second mechanism for building the backtrace for use in cases + where DWARF information is not available, this second mechanism is + often an analysis of a function's prologue. + + In order to extend testing coverage of the second level stack + unwinding mechanisms it is helpful to be able to disable the DWARF + stack unwinders, this can be done with this switch. + + In normal use of GDB disabling the DWARF unwinders is not + advisable, there are cases that are better handled through DWARF + than prologue analysis, and the debug experience is likely to be + better with the DWARF frame unwinders enabled. + + If DWARF frame unwinders are not supported for a particular target + architecture, then enabling this flag does not cause them to be + used. + +'maint info frame-unwinders' + List the frame unwinders currently in effect, starting with the + highest priority. + +'maint set worker-threads' +'maint show worker-threads' + Control the number of worker threads that may be used by GDB. On + capable hosts, GDB may use multiple threads to speed up certain + CPU-intensive operations, such as demangling symbol names. While + the number of threads used by GDB may vary, this command can be + used to set an upper bound on this number. The default is + 'unlimited', which lets GDB choose a reasonable number. Note that + this only controls worker threads started by GDB itself; libraries + used by GDB may start threads of their own. + +'maint set profile' +'maint show profile' + Control profiling of GDB. + + Profiling will be disabled until you use the 'maint set profile' + command to enable it. When you enable profiling, the system will + begin collecting timing and execution count data; when you disable + profiling or exit GDB, the results will be written to a log file. + Remember that if you use profiling, GDB will overwrite the + profiling log file (often called 'gmon.out'). If you have a record + of important profiling data in a 'gmon.out' file, be sure to move + it to a safe location. + + Configuring with '--enable-profiling' arranges for GDB to be + compiled with the '-pg' compiler option. + +'maint set show-debug-regs' +'maint show show-debug-regs' + Control whether to show variables that mirror the hardware debug + registers. Use 'on' to enable, 'off' to disable. If enabled, the + debug registers values are shown when GDB inserts or removes a + hardware breakpoint or watchpoint, and when the inferior triggers a + hardware-assisted breakpoint or watchpoint. + +'maint set show-all-tib' +'maint show show-all-tib' + Control whether to show all non zero areas within a 1k block + starting at thread local base, when using the 'info w32 + thread-information-block' command. + +'maint set target-async' +'maint show target-async' + This controls whether GDB targets operate in synchronous or + asynchronous mode (*note Background Execution::). Normally the + default is asynchronous, if it is available; but this can be + changed to more easily debug problems occurring only in synchronous + mode. + +'maint set target-non-stop' +'maint show target-non-stop' + + This controls whether GDB targets always operate in non-stop mode + even if 'set non-stop' is 'off' (*note Non-Stop Mode::). The + default is 'auto', meaning non-stop mode is enabled if supported by + the target. + + 'maint set target-non-stop auto' + This is the default mode. GDB controls the target in non-stop + mode if the target supports it. + + 'maint set target-non-stop on' + GDB controls the target in non-stop mode even if the target + does not indicate support. + + 'maint set target-non-stop off' + GDB does not control the target in non-stop mode even if the + target supports it. + +'maint set tui-resize-message' +'maint show tui-resize-message' + Control whether GDB displays a message each time the terminal is + resized when in TUI mode. The default is 'off', which means that + GDB is silent during resizes. When 'on', GDB will display a + message after a resize is completed; the message will include a + number indicating how many times the terminal has been resized. + This setting is intended for use by the test suite, where it would + otherwise be difficult to determine when a resize and refresh has + been completed. + +'maint set tui-left-margin-verbose' +'maint show tui-left-margin-verbose' + Control whether the left margin of the TUI source and disassembly + windows uses '_' and '0' at locations where otherwise there would + be a space. The default is 'off', which means spaces are used. + The setting is intended to make it clear where the left margin + begins and ends, to avoid incorrectly interpreting a space as being + part of the the left margin. + +'maint set per-command' +'maint show per-command' + + GDB can display the resources used by each command. This is useful + in debugging performance problems. + + 'maint set per-command space [on|off]' + 'maint show per-command space' + Enable or disable the printing of the memory used by GDB for + each command. If enabled, GDB will display how much memory + each command took, following the command's own output. This + can also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command time [on|off]' + 'maint show per-command time' + Enable or disable the printing of the execution time of GDB + for each command. If enabled, GDB will display how much time + it took to execute each command, following the command's own + output. Both CPU time and wallclock time are printed. + Printing both is useful when trying to determine whether the + cost is CPU or, e.g., disk/network latency. Note that the CPU + time printed is for GDB only, it does not include the + execution time of the inferior because there's no mechanism + currently to compute how much time was spent by GDB and how + much time was spent by the program been debugged. This can + also be requested by invoking GDB with the '--statistics' + command-line switch (*note Mode Options::). + + 'maint set per-command symtab [on|off]' + 'maint show per-command symtab' + Enable or disable the printing of basic symbol table + statistics for each command. If enabled, GDB will display the + following information: + + a. number of symbol tables + b. number of primary symbol tables + c. number of blocks in the blockvector + +'maint set check-libthread-db [on|off]' +'maint show check-libthread-db' + Control whether GDB should run integrity checks on inferior + specific thread debugging libraries as they are loaded. The + default is not to perform such checks. If any check fails GDB will + unload the library and continue searching for a suitable candidate + as described in *note set libthread-db-search-path::. For more + information about the tests, see *note maint check libthread-db::. + +'maint set gnu-source-highlight enabled [on|off]' +'maint show gnu-source-highlight enabled' + Control whether GDB should use the GNU Source Highlight library for + applying styling to source code (*note Output Styling::). This + will be 'on' by default if the GNU Source Highlight library is + available. If the GNU Source Highlight library is not available, + then this will be 'off' by default, and attempting to change this + value to 'on' will give an error. + + If the GNU Source Highlight library is not being used, then GDB + will use the Python Pygments package for source code styling, if it + is available. + + This option is useful for debugging GDB's use of the Pygments + library when GDB is linked against the GNU Source Highlight + library. + +'maint set libopcodes-styling enabled [on|off]' +'maint show libopcodes-styling enabled' + Control whether GDB should use its builtin disassembler + ('libopcodes') to style disassembler output (*note Output + Styling::). The builtin disassembler does not support styling for + all architectures. + + When this option is 'off' the builtin disassembler will not be used + for styling, GDB will fall back to using the Python Pygments + package if possible. + + Trying to set this option 'on' for an architecture that the builtin + disassembler is unable to style will give an error, otherwise, the + builtin disassembler will be used to style disassembler output. + + This option is 'on' by default for supported architectures. + + This option is useful for debugging GDB's use of the Pygments + library when GDB is built for an architecture that supports styling + with the builtin disassembler + +'maint info screen' + Print various characteristics of the screen, such as various + notions of width and height. + +'maint space VALUE' + An alias for 'maint set per-command space'. A non-zero value + enables it, zero disables it. + +'maint time VALUE' + An alias for 'maint set per-command time'. A non-zero value + enables it, zero disables it. + +'maint translate-address [SECTION] ADDR' + Find the symbol stored at the location specified by the address + ADDR and an optional section name SECTION. If found, GDB prints + the name of the closest symbol and an offset from the symbol's + location to the specified address. This is similar to the 'info + address' command (*note Symbols::), except that this command also + allows to find symbols in other sections. + + If section was not specified, the section in which the symbol was + found is also printed. For dynamically linked executables, the + name of executable or shared library containing the symbol is + printed as well. + +'maint test-options require-delimiter' +'maint test-options unknown-is-error' +'maint test-options unknown-is-operand' + These commands are used by the testsuite to validate the command + options framework. The 'require-delimiter' variant requires a + double-dash delimiter to indicate end of options. The + 'unknown-is-error' and 'unknown-is-operand' do not. The + 'unknown-is-error' variant throws an error on unknown option, while + 'unknown-is-operand' treats unknown options as the start of the + command's operands. When run, the commands output the result of + the processed options. When completed, the commands store the + internal result of completion in a variable exposed by the 'maint + show test-options-completion-result' command. + +'maint show test-options-completion-result' + Shows the result of completing the 'maint test-options' + subcommands. This is used by the testsuite to validate completion + support in the command options framework. + +'maint set test-settings KIND' +'maint show test-settings KIND' + These are representative commands for each KIND of setting type GDB + supports. They are used by the testsuite for exercising the + settings infrastructure. + +'maint set backtrace-on-fatal-signal [on|off]' +'maint show backtrace-on-fatal-signal' + When this setting is 'on', if GDB itself terminates with a fatal + signal (e.g. SIGSEGV), then a limited backtrace will be printed to + the standard error stream. This backtrace can be used to help + diagnose crashes within GDB in situations where a user is unable to + share a corefile with the GDB developers. + + If the functionality to provide this backtrace is not available for + the platform on which GDB is running then this feature will be + 'off' by default, and attempting to turn this feature on will give + an error. + + For platforms that do support creating the backtrace this feature + is 'on' by default. + +'maint wait-for-index-cache' + Wait until all pending writes to the index cache have completed. + This is used by the test suite to avoid races when the index cache + is being updated by a worker thread. + +'maint with SETTING [VALUE] [-- COMMAND]' + Like the 'with' command, but works with 'maintenance set' + variables. This is used by the testsuite to exercise the 'with' + command's infrastructure. + +'maint ignore-probes [-V|-VERBOSE] [PROVIDER [NAME [OBJFILE]]]' +'maint ignore-probes -RESET' + Set or reset the ignore-probes filter. The PROVIDER, NAME and + OBJFILE arguments are as in 'enable probes' and 'disable probes' + (*note enable probes::). Only supported for SystemTap probes. + + Here's an example of using 'maint ignore-probes': + (gdb) maint ignore-probes -verbose libc ^longjmp$ + ignore-probes filter has been set to: + PROVIDER: 'libc' + PROBE_NAME: '^longjmp$' + OBJNAME: '' + (gdb) start + <... more output ...> + Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M + Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M + Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M + + The following command is useful for non-interactive invocations of +GDB, such as in the test suite. + +'set watchdog NSEC' + Set the maximum number of seconds GDB will wait for the target + operation to finish. If this time expires, GDB reports and error + and the command is aborted. + +'show watchdog' + Show the current setting of the target wait timeout. + + +File: gdb.info, Node: Remote Protocol, Next: Agent Expressions, Prev: Maintenance Commands, Up: Top + +Appendix E GDB Remote Serial Protocol +************************************* + +* Menu: + +* Overview:: +* Standard Replies:: +* Packets:: +* Stop Reply Packets:: +* General Query Packets:: +* Architecture-Specific Protocol Details:: +* Tracepoint Packets:: +* Host I/O Packets:: +* Interrupts:: +* Notification Packets:: +* Remote Non-Stop:: +* Packet Acknowledgment:: +* Examples:: +* File-I/O Remote Protocol Extension:: +* Library List Format:: +* Library List Format for SVR4 Targets:: +* Memory Map Format:: +* Thread List Format:: +* Traceframe Info Format:: +* Branch Trace Format:: +* Branch Trace Configuration Format:: + + +File: gdb.info, Node: Overview, Next: Standard Replies, Up: Remote Protocol + +E.1 Overview +============ + +There may be occasions when you need to know something about the +protocol--for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for GDB. + + In the examples below, '->' and '<-' are used to indicate transmitted +and received data, respectively. + + All GDB commands and responses (other than acknowledgments and +notifications, see *note Notification Packets::) are sent as a PACKET. +A PACKET is introduced with the character '$', the actual PACKET-DATA, +and the terminating character '#' followed by a two-digit CHECKSUM: + + $PACKET-DATA#CHECKSUM + +The two-digit CHECKSUM is computed as the modulo 256 sum of all +characters between the leading '$' and the trailing '#' (an eight bit +unsigned checksum). + + Implementors should note that prior to GDB 5.0 the protocol +specification also included an optional two-digit SEQUENCE-ID: + + $SEQUENCE-ID:PACKET-DATA#CHECKSUM + +That SEQUENCE-ID was appended to the acknowledgment. GDB has never +output SEQUENCE-IDs. Stubs that handle packets added since GDB 5.0 must +not accept SEQUENCE-ID. + + When either the host or the target machine receives a packet, the +first response expected is an acknowledgment: either '+' (to indicate +the package was received correctly) or '-' (to request retransmission): + + -> $PACKET-DATA#CHECKSUM + <- + + + The '+'/'-' acknowledgments can be disabled once a connection is +established. *Note Packet Acknowledgment::, for details. + + The host (GDB) sends COMMANDs, and the target (the debugging stub +incorporated in your program) sends a RESPONSE. In the case of step and +continue COMMANDs, the response is only sent when the operation has +completed, and the target has again stopped all threads in all attached +processes. This is the default all-stop mode behavior, but the remote +protocol also supports GDB's non-stop execution mode; see *note Remote +Non-Stop::, for details. + + PACKET-DATA consists of a sequence of characters with the exception +of '#' and '$' (see 'X' packet for additional exceptions). + + Fields within the packet should be separated using ',' ';' or ':'. +Except where otherwise noted all numbers are represented in HEX with +leading zeros suppressed. + + Implementors should note that prior to GDB 5.0, the character ':' +could not appear as the third character in a packet (as it would +potentially conflict with the SEQUENCE-ID). + + Binary data in most packets is encoded as two hexadecimal digits per +byte of binary data. This allowed the traditional remote protocol to +work over connections which were only seven-bit clean. Some packets +designed more recently assume an eight-bit clean connection, and use a +more efficient encoding to send and receive binary data. + + The binary data representation uses '7d' (ASCII '}') as an escape +character. Any escaped byte is transmitted as the escape character +followed by the original character XORed with '0x20'. For example, the +byte '0x7d' would be transmitted as the two bytes '0x7d 0x5d'. The +bytes '0x23' (ASCII '#'), '0x24' (ASCII '$'), and '0x7d' (ASCII '}') +must always be escaped. Responses sent by the stub must also escape +'0x2a' (ASCII '*'), so that it is not interpreted as the start of a +run-length encoded sequence (described next). + + Response DATA can be run-length encoded to save space. Run-length +encoding replaces runs of identical characters with one instance of the +repeated character, followed by a '*' and a repeat count. The repeat +count is itself sent encoded, to avoid binary characters in DATA: a +value of N is sent as 'N+29'. For a repeat count greater or equal to 3, +this produces a printable ASCII character, e.g. a space (ASCII code 32) +for a repeat count of 3. (This is because run-length encoding starts to +win for counts 3 or more.) Thus, for example, '0* ' is a run-length +encoding of "0000": the space character after '*' means repeat the +leading '0' '32 - 29 = 3' more times. + + The printable characters '#' and '$' or with a numeric value greater +than 126 must not be used. Runs of six repeats ('#') or seven repeats +('$') can be expanded using a repeat count of only five ('"'). For +example, '00000000' can be encoded as '0*"00'. + + *Note Standard Replies:: for standard error responses, and how to +respond indicating a command is not supported. + + In describing packets (commands and responses), each description has +a template showing the overall syntax, followed by an explanation of the +packet's meaning. We include spaces in some of the templates for +clarity; these are not part of the packet's syntax. No GDB packet uses +spaces to separate its components. For example, a template like 'foo +BAR BAZ' describes a packet beginning with the three ASCII bytes 'foo', +followed by a BAR, followed directly by a BAZ. GDB does not transmit a +space character between the 'foo' and the BAR, or between the BAR and +the BAZ. + + We place optional portions of a packet in [square brackets]; for +example, a template like 'c [ADDR]' describes a packet beginning with +the single ASCII character 'c', possibly followed by an ADDR. + + At a minimum, a stub is required to support the '?' command to tell +GDB the reason for halting, 'g' and 'G' commands for register access, +and the 'm' and 'M' commands for memory access. Stubs that only control +single-threaded targets can implement run control with the 'c' +(continue) command, and if the target architecture supports +hardware-assisted single-stepping, the 's' (step) command. Stubs that +support multi-threading targets should support the 'vCont' command. All +other commands are optional. + + +File: gdb.info, Node: Standard Replies, Next: Packets, Prev: Overview, Up: Remote Protocol + +E.2 Standard Replies +==================== + +The remote protocol specifies a few standard replies. All commands +support these, except as noted in the individual command descriptions. + +empty response + + An empty response (raw character sequence '$#00') means the COMMAND + is not supported by the stub. This way it is possible to extend + the protocol. A newer GDB can tell if a command is supported based + on that response (but see also *note qSupported::). + +'E XX' + An error has occurred; XX is a two-digit hexadecimal error number. + In almost all cases, the protocol does not specify the meaning of + the error numbers; GDB usually ignores the numbers, or displays + them to the user without further interpretation. + +'E.ERRTEXT' + An error has occurred; ERRTEXT is the textual error message, + encoded in ASCII. + + +File: gdb.info, Node: Packets, Next: Stop Reply Packets, Prev: Standard Replies, Up: Remote Protocol + +E.3 Packets +=========== + +The following table provides a complete list of all currently defined +COMMANDs and their corresponding response DATA. *Note File-I/O Remote +Protocol Extension::, for details about the File I/O extension of the +remote protocol. + + Each packet's description has a template showing the packet's overall +syntax, followed by an explanation of the packet's meaning. We include +spaces in some of the templates for clarity; these are not part of the +packet's syntax. No GDB packet uses spaces to separate its components. +For example, a template like 'foo BAR BAZ' describes a packet beginning +with the three ASCII bytes 'foo', followed by a BAR, followed directly +by a BAZ. GDB does not transmit a space character between the 'foo' and +the BAR, or between the BAR and the BAZ. + + Several packets and replies include a THREAD-ID field to identify a +thread. Normally these are positive numbers with a target-specific +interpretation, formatted as big-endian hex strings. A THREAD-ID can +also be a literal '-1' to indicate all threads, or '0' to pick any +thread. + + In addition, the remote protocol supports a multiprocess feature in +which the THREAD-ID syntax is extended to optionally include both +process and thread ID fields, as 'pPID.TID'. The PID (process) and TID +(thread) components each have the format described above: a positive +number with target-specific interpretation formatted as a big-endian hex +string, literal '-1' to indicate all processes or threads +(respectively), or '0' to indicate an arbitrary process or thread. +Specifying just a process, as 'pPID', is equivalent to 'pPID.-1'. It is +an error to specify all processes but a specific thread, such as +'p-1.TID'. Note that the 'p' prefix is _not_ used for those packets and +replies explicitly documented to include a process ID, rather than a +THREAD-ID. + + The multiprocess THREAD-ID syntax extensions are only used if both +GDB and the stub report support for the 'multiprocess' feature using +'qSupported'. *Note multiprocess extensions::, for more information. + + Note that all packet forms beginning with an upper- or lower-case +letter, other than those described here, are reserved for future use. + + Here are the packet descriptions. + +'!' + Enable extended mode. In extended mode, the remote server is made + persistent. The 'R' packet is used to restart the program being + debugged. + + Reply: + 'OK' + The remote target both supports and has enabled extended mode. + +'?' + This is sent when connection is first established to query the + reason the target halted. The reply is the same as for step and + continue. This packet has a special interpretation when the target + is in non-stop mode; see *note Remote Non-Stop::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'A ARGLEN,ARGNUM,ARG,...' + Initialized 'argv[]' array passed into program. ARGLEN specifies + the number of bytes in the hex encoded byte stream ARG. See + 'gdbserver' for more details. + + Reply: + 'OK' + The arguments were set. + +'b BAUD' + (Don't use this packet; its behavior is not well-defined.) Change + the serial line speed to BAUD. + + JTC: _When does the transport layer state change? When it's + received, or after the ACK is transmitted. In either case, there + are problems if the command or the acknowledgment packet is + dropped._ + + Stan: _If people really wanted to add something like this, and get + it working for the first time, they ought to modify ser-unix.c to + send some kind of out-of-band message to a specially-setup stub and + have the switch happen "in between" packets, so that from remote + protocol's point of view, nothing actually happened._ + +'B ADDR,MODE' + Set (MODE is 'S') or clear (MODE is 'C') a breakpoint at ADDR. + + Don't use this packet. Use the 'Z' and 'z' packets instead (*note + insert breakpoint or watchpoint packet::). + +'bc' + Backward continue. Execute the target system in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'bs' + Backward single step. Execute one instruction in reverse. No + parameter. *Note Reverse Execution::, for more information. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'c [ADDR]' + Continue at ADDR, which is the address to resume. If ADDR is + omitted, resume at current address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'C SIG[;ADDR]' + Continue with signal SIG (hex signal number). If ';ADDR' is + omitted, resume at same address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'d' + Toggle debug flag. + + Don't use this packet; instead, define a general set packet (*note + General Query Packets::). + +'D' +'D;PID' + The first form of the packet is used to detach GDB from the remote + system. It is sent to the remote target before GDB disconnects via + the 'detach' command. + + The second form, including a process ID, is used when multiprocess + protocol extensions are enabled (*note multiprocess extensions::), + to detach only a specific process. The PID is specified as a + big-endian hex string. + + Reply: + 'OK' + for success + +'F RC,EE,CF;XX' + A reply from GDB to an 'F' packet sent by the target. This is part + of the File-I/O protocol extension. *Note File-I/O Remote Protocol + Extension::, for the specification. + +'g' + Read general registers. + + Reply: + 'XX...' + Each byte of register data is described by two hex digits. + The bytes with the register are transmitted in target byte + order. The size of each register and their position within + the 'g' packet are determined by the target description (*note + Target Descriptions::); in the absence of a target + description, this is done using code internal to GDB; + typically this is some customary register layout for the + architecture in question. + + When reading registers, the stub may also return a string of + literal 'x''s in place of the register data digits, to + indicate that the corresponding register's value is + unavailable. For example, when reading registers from a trace + frame (*note Using the Collected Data: Analyze Collected + Data.), this means that the register has not been collected in + the trace frame. When reading registers from a live program, + this indicates that the stub has no means to access the + register contents, even though the corresponding register is + known to exist. Note that if a register truly does not exist + on the target, then it is better to not include it in the + target description in the first place. + + For example, for an architecture with 4 registers of 4 bytes + each, the following reply indicates to GDB that registers 0 + and 2 are unavailable, while registers 1 and 3 are available, + and both have zero value: + + -> g + <- xxxxxxxx00000000xxxxxxxx00000000 + +'G XX...' + Write general registers. *Note read registers packet::, for a + description of the XX... data. + + Reply: + 'OK' + for success + +'H OP THREAD-ID' + Set thread for subsequent operations ('m', 'M', 'g', 'G', et.al.). + Depending on the operation to be performed, OP should be 'c' for + step and continue operations (note that this is deprecated, + supporting the 'vCont' command is a better option), and 'g' for + other operations. The thread designator THREAD-ID has the format + and interpretation described in *note thread-id syntax::. + + Reply: + 'OK' + for success + +'i [ADDR[,NNN]]' + Step the remote target by a single clock cycle. If ',NNN' is + present, cycle step NNN cycles. If ADDR is present, cycle step + starting at that address. + +'I' + Signal, then cycle step. *Note step with signal packet::. *Note + cycle step packet::. + +'k' + Kill request. + + The exact effect of this packet is not specified. + + For a bare-metal target, it may power cycle or reset the target + system. For that reason, the 'k' packet has no reply. + + For a single-process target, it may kill that process if possible. + + A multiple-process target may choose to kill just one process, or + all that are under GDB's control. For more precise control, use + the vKill packet (*note vKill packet::). + + If the target system immediately closes the connection in response + to 'k', GDB does not consider the lack of packet acknowledgment to + be an error, and assumes the kill was successful. + + If connected using 'target extended-remote', and the target does + not close the connection in response to a kill request, GDB probes + the target state as if a new connection was opened (*note ? + packet::). + +'m ADDR,LENGTH' + Read LENGTH addressable memory units starting at address ADDR + (*note addressable memory unit::). Note that ADDR does not have to + be aligned to any particular boundary. + + The stub need not use any particular size or alignment when + gathering data from memory for the response; even if ADDR is + word-aligned and LENGTH is a multiple of the word size, the stub is + free to use byte accesses, or not. For this reason, this packet + may not be suitable for accessing memory-mapped I/O devices. + + Reply: + 'XX...' + Memory contents; each byte is transmitted as a two-digit + hexadecimal number. The reply may contain fewer addressable + memory units than requested if the server was reading from a + trace frame memory and was able to read only part of the + region of memory. + + Unlike most packets, this packet does not support 'E.ERRTEXT'-style + textual error replies (*note textual error reply::) by default. + Stubs should be careful to only send such a reply if GDB reported + support for it with the 'error-message' feature (*note + error-message::). + +'M ADDR,LENGTH:XX...' + Write LENGTH addressable memory units starting at address ADDR + (*note addressable memory unit::). The data is given by XX...; + each byte is transmitted as a two-digit hexadecimal number. + + Reply: + 'OK' + All the data was written successfully. (If only part of the + data was written, this command returns an error.) + +'p N' + Read the value of register N; N is in hex. *Note read registers + packet::, for a description of how the returned register value is + encoded. + + Reply: + 'XX...' + the register's value + +'P N...=R...' + Write register N... with value R.... The register number N is in + hexadecimal, and R... contains two hex digits for each byte in the + register (target byte order). + + Reply: + 'OK' + for success + +'q NAME PARAMS...' +'Q NAME PARAMS...' + General query ('q') and set ('Q'). These packets are described + fully in *note General Query Packets::. + +'r' + Reset the entire system. + + Don't use this packet; use the 'R' packet instead. + +'R XX' + Restart the program being debugged. The XX, while needed, is + ignored. This packet is only available in extended mode (*note + extended mode::). + + The 'R' packet has no reply. + +'s [ADDR]' + Single step, resuming at ADDR. If ADDR is omitted, resume at same + address. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'S SIG[;ADDR]' + Step with signal. This is analogous to the 'C' packet, but + requests a single-step, rather than a normal resumption of + execution. + + This packet is deprecated for multi-threading support. *Note vCont + packet::. + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'t ADDR:PP,MM' + Search backwards starting at address ADDR for a match with pattern + PP and mask MM, both of which are are 4 byte long. There must be + at least 3 digits in ADDR. + +'T THREAD-ID' + Find out if the thread THREAD-ID is alive. *Note thread-id + syntax::. + + Reply: + 'OK' + thread is still alive + +'v' + Packets starting with 'v' are identified by a multi-letter name, up + to the first ';' or '?' (or the end of the packet). + +'vAttach;PID' + Attach to a new process with the specified process ID PID. The + process ID is a hexadecimal integer identifying the process. In + all-stop mode, all threads in the attached process are stopped; in + non-stop mode, it may be attached without being stopped if that is + supported by the target. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'Any stop packet' + for success in all-stop mode (*note Stop Reply Packets::) + 'OK' + for success in non-stop mode (*note Remote Non-Stop::) + +'vCont[;ACTION[:THREAD-ID]]...' + Resume the inferior, specifying different actions for each thread. + + For each inferior thread, the leftmost action with a matching + THREAD-ID is applied. Threads that don't match any action remain + in their current state. Thread IDs are specified using the syntax + described in *note thread-id syntax::. If multiprocess extensions + (*note multiprocess extensions::) are supported, actions can be + specified to match all threads in a process by using the 'pPID.-1' + form of the THREAD-ID. An action with no THREAD-ID matches all + threads. Specifying no actions is an error. + + Currently supported actions are: + + 'c' + Continue. + 'C SIG' + Continue with signal SIG. The signal SIG should be two hex + digits. + 's' + Step. + 'S SIG' + Step with signal SIG. The signal SIG should be two hex + digits. + 't' + Stop. + 'r START,END' + Step once, and then keep stepping as long as the thread stops + at addresses between START (inclusive) and END (exclusive). + The remote stub reports a stop reply when either the thread + goes out of the range or is stopped due to an unrelated + reason, such as hitting a breakpoint. *Note range stepping::. + + If the range is empty (START == END), then the action becomes + equivalent to the 's' action. In other words, single-step + once, and report the stop (even if the stepped instruction + jumps to START). + + (A stop reply may be sent at any point even if the PC is still + within the stepping range; for example, it is valid to + implement this packet in a degenerate way as a single + instruction step operation.) + + The optional argument ADDR normally associated with the 'c', 'C', + 's', and 'S' packets is not supported in 'vCont'. + + The 't' action is only relevant in non-stop mode (*note Remote + Non-Stop::) and may be ignored by the stub otherwise. A stop reply + should be generated for any affected thread not already stopped. + When a thread is stopped by means of a 't' action, the + corresponding stop reply should indicate that the thread has + stopped with signal '0', regardless of whether the target uses some + other signal as an implementation detail. + + The server must ignore 'c', 'C', 's', 'S', and 'r' actions for + threads that are already running. Conversely, the server must + ignore 't' actions for threads that are already stopped. + + _Note:_ In non-stop mode, a thread is considered running until GDB + acknowledges an asynchronous stop notification for it with the + 'vStopped' packet (*note Remote Non-Stop::). + + The stub must support 'vCont' if it reports support for + multiprocess extensions (*note multiprocess extensions::). + + Reply: *Note Stop Reply Packets::, for the reply specifications. + +'vCont?' + Request a list of actions supported by the 'vCont' packet. + + Reply: + 'vCont[;ACTION...]' + The 'vCont' packet is supported. Each ACTION is a supported + command in the 'vCont' packet. + +'vCtrlC' + Interrupt remote target as if a control-C was pressed on the remote + terminal. This is the equivalent to reacting to the '^C' ('\003', + the control-C character) character in all-stop mode while the + target is running, except this works in non-stop mode. *Note + interrupting remote targets::, for more info on the all-stop + variant. + + Reply: + 'OK' + for success + +'vFile:OPERATION:PARAMETER...' + Perform a file operation on the target system. For details, see + *note Host I/O Packets::. + +'vFlashErase:ADDR,LENGTH' + Direct the stub to erase LENGTH bytes of flash starting at ADDR. + The region may enclose any number of flash blocks, but its start + and end must fall on block boundaries, as indicated by the flash + block size appearing in the memory map (*note Memory Map Format::). + GDB groups flash memory programming operations together, and sends + a 'vFlashDone' request after each group; the stub is allowed to + delay erase operation until the 'vFlashDone' packet is received. + + Reply: + 'OK' + for success + +'vFlashWrite:ADDR:XX...' + Direct the stub to write data to flash address ADDR. The data is + passed in binary form using the same encoding as for the 'X' packet + (*note Binary Data::). The memory ranges specified by + 'vFlashWrite' packets preceding a 'vFlashDone' packet must not + overlap, and must appear in order of increasing addresses (although + 'vFlashErase' packets for higher addresses may already have been + received; the ordering is guaranteed only between 'vFlashWrite' + packets). If a packet writes to an address that was neither erased + by a preceding 'vFlashErase' packet nor by some other + target-specific method, the results are unpredictable. + + Reply: + 'OK' + for success + 'E.memtype' + for vFlashWrite addressing non-flash memory + +'vFlashDone' + Indicate to the stub that flash programming operation is finished. + The stub is permitted to delay or batch the effects of a group of + 'vFlashErase' and 'vFlashWrite' packets until a 'vFlashDone' packet + is received. The contents of the affected regions of flash memory + are unpredictable until the 'vFlashDone' request is completed. + +'vKill;PID' + Kill the process with the specified process ID PID, which is a + hexadecimal integer identifying the process. This packet is used + in preference to 'k' when multiprocess protocol extensions are + supported; see *note multiprocess extensions::. + + Reply: + 'OK' + for success + +'vMustReplyEmpty' + The correct reply to an unknown 'v' packet is to return the empty + string, however, some older versions of 'gdbserver' would + incorrectly return 'OK' for unknown 'v' packets. + + The 'vMustReplyEmpty' is used as a feature test to check how + 'gdbserver' handles unknown packets, it is important that this + packet be handled in the same way as other unknown 'v' packets. If + this packet is handled differently to other unknown 'v' packets + then it is possible that GDB may run into problems in other areas, + specifically around use of 'vFile:setfs:'. + +'vRun;FILENAME[;ARGUMENT]...' + Run the program FILENAME, passing it each ARGUMENT on its command + line. The file and arguments are hex-encoded strings. If FILENAME + is an empty string, the stub may use a default program (e.g. the + last program run). The program is created in the stopped state. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'Any stop packet' + for success (*note Stop Reply Packets::) + +'vStopped' + *Note Notification Packets::. + +'x ADDR,LENGTH' + Read LENGTH addressable memory units starting at address ADDR + (*note addressable memory unit::). Note that ADDR does not have to + be aligned to any particular boundary. + + The stub need not use any particular size or alignment when + gathering data from memory for the response; even if ADDR is + word-aligned and LENGTH is a multiple of the word size, the stub is + free to use byte accesses, or not. For this reason, this packet + may not be suitable for accessing memory-mapped I/O devices. + + GDB will only use this packet if the stub reports the + 'binary-upload' feature is supported in its 'qSupported' reply + (*note qSupported::). + + Reply: + 'b XX...' + Memory contents as binary data (*note Binary Data::). The + reply may contain fewer addressable memory units than + requested if the server was reading from a trace frame memory + and was able to read only part of the region of memory. + 'E NN' + for an error + +'X ADDR,LENGTH:XX...' + Write data to memory, where the data is transmitted in binary. + Memory is specified by its address ADDR and number of addressable + memory units LENGTH (*note addressable memory unit::); 'XX...' is + binary data (*note Binary Data::). + + Reply: + 'OK' + for success + +'z TYPE,ADDR,KIND' +'Z TYPE,ADDR,KIND' + Insert ('Z') or remove ('z') a TYPE breakpoint or watchpoint + starting at address ADDRESS of kind KIND. + + Each breakpoint and watchpoint packet TYPE is documented + separately. + + _Implementation notes: A remote target shall return an empty string + for an unrecognized breakpoint or watchpoint packet TYPE. A remote + target shall support either both or neither of a given 'ZTYPE...' + and 'zTYPE...' packet pair. To avoid potential problems with + duplicate packets, the operations should be implemented in an + idempotent way._ + +'z0,ADDR,KIND' +'Z0,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' + Insert ('Z0') or remove ('z0') a software breakpoint at address + ADDR of type KIND. + + A software breakpoint is implemented by replacing the instruction + at ADDR with a software breakpoint or trap instruction. The KIND + is target-specific and typically indicates the size of the + breakpoint in bytes that should be inserted. E.g., the ARM and + MIPS can insert either a 2 or 4 byte breakpoint. Some + architectures have additional meanings for KIND (*note + Architecture-Specific Protocol Details::); if no + architecture-specific value is being used, it should be '0'. KIND + is hex-encoded. COND_LIST is an optional list of conditional + expressions in bytecode form that should be evaluated on the + target's side. These are the conditions that should be taken into + consideration when deciding if the breakpoint trigger should be + reported back to GDB. + + See also the 'swbreak' stop reason (*note swbreak stop reason::) + for how to best report a software breakpoint event to GDB. + + The COND_LIST parameter is comprised of a series of expressions, + concatenated without separators. Each expression has the following + form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual conditional expression in bytecode form. + + The optional CMD_LIST parameter introduces commands that may be run + on the target, rather than being reported back to GDB. The + parameter starts with a numeric flag PERSIST; if the flag is + nonzero, then the breakpoint may remain active and the commands + continue to be run even when GDB disconnects from the target. + Following this flag is a series of expressions concatenated with no + separators. Each expression has the following form: + + 'X LEN,EXPR' + LEN is the length of the bytecode expression and EXPR is the + actual commands expression in bytecode form. + + _Implementation note: It is possible for a target to copy or move + code that contains software breakpoints (e.g., when implementing + overlays). The behavior of this packet, in the presence of such a + target, is not defined._ + + Reply: + 'OK' + success + +'z1,ADDR,KIND' +'Z1,ADDR,KIND[;COND_LIST...][;cmds:PERSIST,CMD_LIST...]' + Insert ('Z1') or remove ('z1') a hardware breakpoint at address + ADDR. + + A hardware breakpoint is implemented using a mechanism that is not + dependent on being able to modify the target's memory. The KIND, + COND_LIST, and CMD_LIST arguments have the same meaning as in 'Z0' + packets. + + _Implementation note: A hardware breakpoint is not affected by code + movement._ + + Reply: + 'OK' + success + +'z2,ADDR,KIND' +'Z2,ADDR,KIND' + Insert ('Z2') or remove ('z2') a write watchpoint at ADDR. The + number of bytes to watch is specified by KIND. + + Reply: + 'OK' + success + +'z3,ADDR,KIND' +'Z3,ADDR,KIND' + Insert ('Z3') or remove ('z3') a read watchpoint at ADDR. The + number of bytes to watch is specified by KIND. + + Reply: + 'OK' + success + +'z4,ADDR,KIND' +'Z4,ADDR,KIND' + Insert ('Z4') or remove ('z4') an access watchpoint at ADDR. The + number of bytes to watch is specified by KIND. + + Reply: + 'OK' + success + + +File: gdb.info, Node: Stop Reply Packets, Next: General Query Packets, Prev: Packets, Up: Remote Protocol + +E.4 Stop Reply Packets +====================== + +The 'C', 'c', 'S', 's', 'vCont', 'vAttach', 'vRun', 'vStopped', and '?' +packets can receive any of the below as a reply. Except for '?' and +'vStopped', that reply is only returned when the target halts. In the +below the exact meaning of "signal number" is defined by the header +'include/gdb/signals.h' in the GDB source code. + + In non-stop mode, the server will simply reply 'OK' to commands such +as 'vCont'; any stop will be the subject of a future notification. +*Note Remote Non-Stop::. + + As in the description of request packets, we include spaces in the +reply templates for clarity; these are not part of the reply packet's +syntax. No GDB stop reply packet uses spaces to separate its +components. + +'S AA' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to a 'T' response with no N:R pairs. + +'T AA N1:R1;N2:R2;...' + The program received signal number AA (a two-digit hexadecimal + number). This is equivalent to an 'S' response, except that the + 'N:R' pairs can carry values of important registers and other + information directly in the stop reply packet, reducing round-trip + latency. Single-step and breakpoint traps are reported this way. + Each 'N:R' pair is interpreted as follows: + + * If N is a hexadecimal number, it is a register number, and the + corresponding R gives that register's value. The data R is a + series of bytes in target byte order, with each byte given by + a two-digit hex number. + + * If N is 'thread', then R is the thread ID of the stopped + thread, as specified in *note thread-id syntax::. + + * If N is 'core', then R is the hexadecimal number of the core + on which the stop event was detected. + + * If N is a recognized "stop reason", it describes a more + specific event that stopped the target. The currently defined + stop reasons are listed below. The AA should be '05', the + trap signal. At most one stop reason should be present. + + * Otherwise, GDB should ignore this 'N:R' pair and go on to the + next; this allows us to extend the protocol in the future. + + The currently defined stop reasons are: + + 'watch' + 'rwatch' + 'awatch' + The packet indicates a watchpoint hit, and R is the data + address, in hex. + + 'syscall_entry' + 'syscall_return' + The packet indicates a syscall entry or return, and R is the + syscall number, in hex. + + 'library' + The packet indicates that the loaded libraries have changed. + GDB should use 'qXfer:libraries:read' to fetch a new list of + loaded libraries. The R part is ignored. + + 'replaylog' + The packet indicates that the target cannot continue replaying + logged execution events, because it has reached the end (or + the beginning when executing backward) of the log. The value + of R will be either 'begin' or 'end'. *Note Reverse + Execution::, for more information. + + 'swbreak' + The packet indicates a software breakpoint instruction was + executed, irrespective of whether it was GDB that planted the + breakpoint or the breakpoint is hardcoded in the program. The + R part must be left empty. + + On some architectures, such as x86, at the architecture level, + when a breakpoint instruction executes the program counter + points at the breakpoint address plus an offset. On such + targets, the stub is responsible for adjusting the PC to point + back at the breakpoint address. + + This packet should not be sent by default; older GDB versions + did not support it. GDB requests it, by supplying an + appropriate 'qSupported' feature (*note qSupported::). The + remote stub must also supply the appropriate 'qSupported' + feature indicating support. + + This packet is required for correct non-stop mode operation. + + 'hwbreak' + The packet indicates the target stopped for a hardware + breakpoint. The R part must be left empty. + + The same remarks about 'qSupported' and non-stop mode above + apply. + + 'fork' + The packet indicates that 'fork' was called, and R is the + thread ID of the new child process, as specified in *note + thread-id syntax::. This packet is only applicable to targets + that support fork events. + + This packet should not be sent by default; older GDB versions + did not support it. GDB requests it, by supplying an + appropriate 'qSupported' feature (*note qSupported::). The + remote stub must also supply the appropriate 'qSupported' + feature indicating support. + + 'vfork' + The packet indicates that 'vfork' was called, and R is the + thread ID of the new child process, as specified in *note + thread-id syntax::. This packet is only applicable to targets + that support vfork events. + + This packet should not be sent by default; older GDB versions + did not support it. GDB requests it, by supplying an + appropriate 'qSupported' feature (*note qSupported::). The + remote stub must also supply the appropriate 'qSupported' + feature indicating support. + + 'vforkdone' + The packet indicates that a child process created by a vfork + has either called 'exec' or terminated, so that the address + spaces of the parent and child process are no longer shared. + The R part is ignored. This packet is only applicable to + targets that support vforkdone events. + + This packet should not be sent by default; older GDB versions + did not support it. GDB requests it, by supplying an + appropriate 'qSupported' feature (*note qSupported::). The + remote stub must also supply the appropriate 'qSupported' + feature indicating support. + + 'exec' + The packet indicates that 'execve' was called, and R is the + absolute pathname of the file that was executed, in hex. This + packet is only applicable to targets that support exec events. + + This packet should not be sent by default; older GDB versions + did not support it. GDB requests it, by supplying an + appropriate 'qSupported' feature (*note qSupported::). The + remote stub must also supply the appropriate 'qSupported' + feature indicating support. + + 'clone' + The packet indicates that 'clone' was called, and R is the + thread ID of the new child thread, as specified in *note + thread-id syntax::. This packet is only applicable to targets + that support clone events. + + This packet should not be sent by default; GDB requests it + with the *note QThreadOptions:: packet. + + 'create' + The packet indicates that the thread was just created. The + new thread is stopped until GDB sets it running with a + resumption packet (*note vCont packet::). This packet should + not be sent by default; GDB requests it with the *note + QThreadEvents:: packet. See also the 'w' (*note thread exit + event::) remote reply below. The R part is ignored. + +'W AA' +'W AA ; process:PID' + The process exited, and AA is the exit status. This is only + applicable to certain targets. + + The second form of the response, including the process ID of the + exited process, can be used only when GDB has reported support for + multiprocess protocol extensions; see *note multiprocess + extensions::. Both AA and PID are formatted as big-endian hex + strings. + +'X AA' +'X AA ; process:PID' + The process terminated with signal AA. + + The second form of the response, including the process ID of the + terminated process, can be used only when GDB has reported support + for multiprocess protocol extensions; see *note multiprocess + extensions::. Both AA and PID are formatted as big-endian hex + strings. + +'w AA ; TID' + + The thread exited, and AA is the exit status. This response should + not be sent by default; GDB requests it with either the *note + QThreadEvents:: or *note QThreadOptions:: packets. See also *note + thread create event:: above. AA is formatted as a big-endian hex + string. + +'N' + There are no resumed threads left in the target. In other words, + even though the process is alive, the last resumed thread has + exited. For example, say the target process has two threads: + thread 1 and thread 2. The client leaves thread 1 stopped, and + resumes thread 2, which subsequently exits. At this point, even + though the process is still alive, and thus no 'W' stop reply is + sent, no thread is actually executing either. The 'N' stop reply + thus informs the client that it can stop waiting for stop replies. + This packet should not be sent by default; older GDB versions did + not support it. GDB requests it, by supplying an appropriate + 'qSupported' feature (*note qSupported::). The remote stub must + also supply the appropriate 'qSupported' feature indicating + support. + +'O XX...' + 'XX...' is hex encoding of ASCII data, to be written as the + program's console output. This can happen at any time while the + program is running and the debugger should continue to wait for + 'W', 'T', etc. This reply is not permitted in non-stop mode. + +'F CALL-ID,PARAMETER...' + CALL-ID is the identifier which says which host system call should + be called. This is just the name of the function. Translation + into the correct system call is only applicable as it's defined in + GDB. *Note File-I/O Remote Protocol Extension::, for a list of + implemented system calls. + + 'PARAMETER...' is a list of parameters as defined for this very + system call. + + The target replies with this packet when it expects GDB to call a + host system call on behalf of the target. GDB replies with an + appropriate 'F' packet and keeps up waiting for the next reply + packet from the target. The latest 'C', 'c', 'S' or 's' action is + expected to be continued. *Note File-I/O Remote Protocol + Extension::, for more details. + + +File: gdb.info, Node: General Query Packets, Next: Architecture-Specific Protocol Details, Prev: Stop Reply Packets, Up: Remote Protocol + +E.5 General Query Packets +========================= + +Packets starting with 'q' are "general query packets"; packets starting +with 'Q' are "general set packets". General query and set packets are a +semi-unified form for retrieving and sending information to and from the +stub. + + The initial letter of a query or set packet is followed by a name +indicating what sort of thing the packet applies to. For example, GDB +may use a 'qSymbol' packet to exchange symbol definitions with the stub. +These packet names follow some conventions: + + * The name must not contain commas, colons or semicolons. + * Most GDB query and set packets have a leading upper case letter. + * The names of custom vendor packets should use a company prefix, in + lower case, followed by a period. For example, packets designed at + the Acme Corporation might begin with 'qacme.foo' (for querying + foos) or 'Qacme.bar' (for setting bars). + + The name of a query or set packet should be separated from any +parameters by a ':'; the parameters themselves should be separated by +',' or ';'. Stubs must be careful to match the full packet name, and +check for a separator or the end of the packet, in case two packet names +share a common prefix. New packets should not begin with 'qC', 'qP', or +'qL'(1). + + Like the descriptions of the other packets, each description here has +a template showing the packet's overall syntax, followed by an +explanation of the packet's meaning. We include spaces in some of the +templates for clarity; these are not part of the packet's syntax. No +GDB packet uses spaces to separate its components. + + Here are the currently defined query and set packets: + +'QAgent:1' +'QAgent:0' + Turn on or off the agent as a helper to perform some debugging + operations delegated from GDB (*note Control Agent::). + +'QAllow:OP:VAL...' + Specify which operations GDB expects to request of the target, as a + semicolon-separated list of operation name and value pairs. + Possible values for OP include 'WriteReg', 'WriteMem', + 'InsertBreak', 'InsertTrace', 'InsertFastTrace', and 'Stop'. VAL + is either 0, indicating that GDB will not request the operation, or + 1, indicating that it may. (The target can then use this to set up + its own internals optimally, for instance if the debugger never + expects to insert breakpoints, it may not need to install its own + trap handler.) + +'qC' + Return the current thread ID. + + Reply: + 'QC THREAD-ID' + Where THREAD-ID is a thread ID as documented in *note + thread-id syntax::. + '(anything else)' + Any other reply implies the old thread ID. + +'qCRC:ADDR,LENGTH' + Compute the CRC checksum of a block of memory using CRC-32 defined + in IEEE 802.3. The CRC is computed byte at a time, taking the most + significant bit of each byte first. The initial pattern code + '0xffffffff' is used to ensure leading zeros affect the CRC. + + _Note:_ This is the same CRC used in validating separate debug + files (*note Debugging Information in Separate Files: Separate + Debug Files.). However the algorithm is slightly different. When + validating separate debug files, the CRC is computed taking the + _least_ significant bit of each byte first, and the final result is + inverted to detect trailing zeros. + + Reply: + 'C CRC32' + The specified memory region's checksum is CRC32. + +'QDisableRandomization:VALUE' + Some target operating systems will randomize the virtual address + space of the inferior process as a security feature, but provide a + feature to disable such randomization, e.g. to allow for a more + deterministic debugging experience. On such systems, this packet + with a VALUE of 1 directs the target to disable address space + randomization for processes subsequently started via 'vRun' + packets, while a packet with a VALUE of 0 tells the target to + enable address space randomization. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support disabling address space randomization. + +'QStartupWithShell:VALUE' + On UNIX-like targets, it is possible to start the inferior using a + shell program. This is the default behavior on both GDB and + 'gdbserver' (*note set startup-with-shell::). This packet is used + to inform 'gdbserver' whether it should start the inferior using a + shell or not. + + If VALUE is '0', 'gdbserver' will not use a shell to start the + inferior. If VALUE is '1', 'gdbserver' will use a shell to start + the inferior. All other values are considered an error. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support starting the inferior using a shell. + + Use of this packet is controlled by the 'set startup-with-shell' + command; *note set startup-with-shell::. + +'QEnvironmentHexEncoded:HEX-VALUE' + On UNIX-like targets, it is possible to set environment variables + that will be passed to the inferior during the startup process. + This packet is used to inform 'gdbserver' of an environment + variable that has been defined by the user on GDB (*note set + environment::). + + The packet is composed by HEX-VALUE, an hex encoded representation + of the NAME=VALUE format representing an environment variable. The + name of the environment variable is represented by NAME, and the + value to be assigned to the environment variable is represented by + VALUE. If the variable has no value (i.e., the value is 'null'), + then VALUE will not be present. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support passing environment variables to the starting inferior. + + This packet is related to the 'set environment' command; *note set + environment::. + +'QEnvironmentUnset:HEX-VALUE' + On UNIX-like targets, it is possible to unset environment variables + before starting the inferior in the remote target. This packet is + used to inform 'gdbserver' of an environment variable that has been + unset by the user on GDB (*note unset environment::). + + The packet is composed by HEX-VALUE, an hex encoded representation + of the name of the environment variable to be unset. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support passing environment variables to the starting inferior. + + This packet is related to the 'unset environment' command; *note + unset environment::. + +'QEnvironmentReset' + On UNIX-like targets, this packet is used to reset the state of + environment variables in the remote target before starting the + inferior. In this context, reset means unsetting all environment + variables that were previously set by the user (i.e., were not + initially present in the environment). It is sent to 'gdbserver' + before the 'QEnvironmentHexEncoded' (*note + QEnvironmentHexEncoded::) and the 'QEnvironmentUnset' (*note + QEnvironmentUnset::) packets. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). This should only be done on targets that actually + support passing environment variables to the starting inferior. + +'QSetWorkingDir:[DIRECTORY]' + This packet is used to inform the remote server of the intended + current working directory for programs that are going to be + executed. + + The packet is composed by DIRECTORY, an hex encoded representation + of the directory that the remote inferior will use as its current + working directory. If DIRECTORY is an empty string, the remote + server should reset the inferior's current working directory to its + original, empty value. + + This packet is only available in extended mode (*note extended + mode::). + + Reply: + 'OK' + The request succeeded. + +'qfThreadInfo' +'qsThreadInfo' + Obtain a list of all active thread IDs from the target (OS). Since + there may be too many active threads to fit into one reply packet, + this query works iteratively: it may require more than one + query/reply sequence to obtain the entire list of threads. The + first query of the sequence will be the 'qfThreadInfo' query; + subsequent queries in the sequence will be the 'qsThreadInfo' + query. + + NOTE: This packet replaces the 'qL' query (see below). + + Reply: + 'm THREAD-ID' + A single thread ID + 'm THREAD-ID,THREAD-ID...' + a comma-separated list of thread IDs + 'l' + (lower case letter 'L') denotes end of list. + + In response to each query, the target will reply with a list of one + or more thread IDs, separated by commas. GDB will respond to each + reply with a request for more thread ids (using the 'qs' form of + the query), until the target responds with 'l' (lower-case ell, for + "last"). Refer to *note thread-id syntax::, for the format of the + THREAD-ID fields. + + _Note: GDB will send the 'qfThreadInfo' query during the initial + connection with the remote target, and the very first thread ID + mentioned in the reply will be stopped by GDB in a subsequent + message. Therefore, the stub should ensure that the first thread + ID in the 'qfThreadInfo' reply is suitable for being stopped by + GDB._ + +'qGetTLSAddr:THREAD-ID,OFFSET,LM' + Fetch the address associated with thread local storage specified by + THREAD-ID, OFFSET, and LM. + + THREAD-ID is the thread ID associated with the thread for which to + fetch the TLS address. *Note thread-id syntax::. + + OFFSET is the (big endian, hex encoded) offset associated with the + thread local variable. (This offset is obtained from the debug + information associated with the variable.) + + LM is the (big endian, hex encoded) OS/ABI-specific encoding of the + load module associated with the thread local storage. For example, + a GNU/Linux system will pass the link map address of the shared + object associated with the thread local storage under + consideration. Other operating environments may choose to + represent the load module differently, so the precise meaning of + this parameter will vary. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the address of the + thread local storage requested. + +'qGetTIBAddr:THREAD-ID' + Fetch address of the Windows OS specific Thread Information Block. + + THREAD-ID is the thread ID associated with the thread. + + Reply: + 'XX...' + Hex encoded (big endian) bytes representing the linear address + of the thread information block. + +'qL STARTFLAG THREADCOUNT NEXTTHREAD' + Obtain thread information from RTOS. Where: STARTFLAG (one hex + digit) is one to indicate the first query and zero to indicate a + subsequent query; THREADCOUNT (two hex digits) is the maximum + number of threads the response packet can contain; and NEXTTHREAD + (eight hex digits), for subsequent queries (STARTFLAG is zero), is + returned in the response as ARGTHREAD. + + Don't use this packet; use the 'qfThreadInfo' query instead (see + above). + + Reply: + 'qM COUNT DONE ARGTHREAD THREAD...' + Where: COUNT (two hex digits) is the number of threads being + returned; DONE (one hex digit) is zero to indicate more + threads and one indicates no further threads; ARGTHREADID + (eight hex digits) is NEXTTHREAD from the request packet; + THREAD... is a sequence of thread IDs, THREADID (eight hex + digits), from the target. See + 'remote.c:parse_threadlist_response()'. + +'qMemTags:START ADDRESS,LENGTH:TYPE' + Fetch memory tags of type TYPE from the address range + [START ADDRESS, START ADDRESS + LENGTH). The target is responsible + for calculating how many tags will be returned, as this is + architecture-specific. + + START ADDRESS is the starting address of the memory range. + + LENGTH is the length, in bytes, of the memory range. + + TYPE is the type of tag the request wants to fetch. The type is a + signed integer. + + GDB will only send this packet if the stub has advertised support + for memory tagging via 'qSupported'. + + Reply: + 'MXX...' + Hex encoded sequence of uninterpreted bytes, XX..., + representing the tags found in the requested memory range. + +'qIsAddressTagged:ADDRESS' + Check if address ADDRESS is in a memory tagged region; if it is, + it's said to be "tagged". The target is responsible for checking + it, as this is architecture-specific. + + ADDRESS is the address to be checked. + + Reply: + Replies to this packet should all be in two hex digit format, + as follows: + + ''01'' + Address ADDRESS is tagged. + + ''00'' + Address ADDRESS is not tagged. + +'QMemTags:START ADDRESS,LENGTH:TYPE:TAG BYTES' + Store memory tags of type TYPE to the address range + [START ADDRESS, START ADDRESS + LENGTH). The target is responsible + for interpreting the type, the tag bytes and modifying the memory + tag granules accordingly, given this is architecture-specific. + + The interpretation of how many tags (NT) should be written to how + many memory tag granules (NG) is also architecture-specific. The + behavior is implementation-specific, but the following is + suggested. + + If the number of memory tags, NT, is greater than or equal to the + number of memory tag granules, NG, only NG tags will be stored. + + If NT is less than NG, the behavior is that of a fill operation, + and the tag bytes will be used as a pattern that will get repeated + until NG tags are stored. + + START ADDRESS is the starting address of the memory range. The + address does not have any restriction on alignment or size. + + LENGTH is the length, in bytes, of the memory range. + + TYPE is the type of tag the request wants to fetch. The type is a + signed integer. + + TAG BYTES is a sequence of hex encoded uninterpreted bytes which + will be interpreted by the target. Each pair of hex digits is + interpreted as a single byte. + + GDB will only send this packet if the stub has advertised support + for memory tagging via 'qSupported'. + + Reply: + 'OK' + The request was successful and the memory tag granules were + modified accordingly. + +'qOffsets' + Get section offsets that the target used when relocating the + downloaded image. + + Reply: + 'Text=XXX;Data=YYY[;Bss=ZZZ]' + Relocate the 'Text' section by XXX from its original address. + Relocate the 'Data' section by YYY from its original address. + If the object file format provides segment information (e.g. + ELF 'PT_LOAD' program headers), GDB will relocate entire + segments by the supplied offsets. + + _Note: while a 'Bss' offset may be included in the response, + GDB ignores this and instead applies the 'Data' offset to the + 'Bss' section._ + + 'TextSeg=XXX[;DataSeg=YYY]' + Relocate the first segment of the object file, which + conventionally contains program code, to a starting address of + XXX. If 'DataSeg' is specified, relocate the second segment, + which conventionally contains modifiable data, to a starting + address of YYY. GDB will report an error if the object file + does not contain segment information, or does not contain at + least as many segments as mentioned in the reply. Extra + segments are kept at fixed offsets relative to the last + relocated segment. + +'qP MODE THREAD-ID' + Returns information on THREAD-ID. Where: MODE is a hex encoded 32 + bit mode; THREAD-ID is a thread ID (*note thread-id syntax::). + + Don't use this packet; use the 'qThreadExtraInfo' query instead + (see below). + + Reply: see 'remote.c:remote_unpack_thread_info_response()'. + +'QNonStop:1' +'QNonStop:0' + Enter non-stop ('QNonStop:1') or all-stop ('QNonStop:0') mode. + *Note Remote Non-Stop::, for more information. + + Reply: + 'OK' + The request succeeded. + + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). Use of this packet is controlled by the 'set + non-stop' command; *note Non-Stop Mode::. + +'QCatchSyscalls:1 [;SYSNO]...' +'QCatchSyscalls:0' + Enable ('QCatchSyscalls:1') or disable ('QCatchSyscalls:0') + catching syscalls from the inferior process. + + For 'QCatchSyscalls:1', each listed syscall SYSNO (encoded in hex) + should be reported to GDB. If no syscall SYSNO is listed, every + system call should be reported. + + Note that if a syscall not in the list is reported, GDB will still + filter the event according to its own list from all corresponding + 'catch syscall' commands. However, it is more efficient to only + report the requested syscalls. + + Multiple 'QCatchSyscalls:1' packets do not combine; any earlier + 'QCatchSyscalls:1' list is completely replaced by the new list. + + If the inferior process execs, the state of 'QCatchSyscalls' is + kept for the new process too. On targets where exec may affect + syscall numbers, for example with exec between 32 and 64-bit + processes, the client should send a new packet with the new syscall + list. + + Reply: + 'OK' + The request succeeded. + + Use of this packet is controlled by the 'set remote catch-syscalls' + command (*note set remote catch-syscalls: Remote Configuration.). + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). + +'QPassSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL should be passed directly to the inferior + process. Signals are numbered identically to continue packets and + stop replies (*note Stop Reply Packets::). Each SIGNAL list item + should be strictly greater than the previous item. These signals + do not need to stop the inferior, or be reported to GDB. All other + signals should be reported to GDB. Multiple 'QPassSignals' packets + do not combine; any earlier 'QPassSignals' list is completely + replaced by the new list. This packet improves performance when + using 'handle SIGNAL nostop noprint pass'. + + Reply: + 'OK' + The request succeeded. + + Use of this packet is controlled by the 'set remote pass-signals' + command (*note set remote pass-signals: Remote Configuration.). + This packet is not probed by default; the remote stub must request + it, by supplying an appropriate 'qSupported' response (*note + qSupported::). + +'QProgramSignals: SIGNAL [;SIGNAL]...' + Each listed SIGNAL may be delivered to the inferior process. + Others should be silently discarded. + + In some cases, the remote stub may need to decide whether to + deliver a signal to the program or not without GDB involvement. + One example of that is while detaching -- the program's threads may + have stopped for signals that haven't yet had a chance of being + reported to GDB, and so the remote stub can use the signal list + specified by this packet to know whether to deliver or ignore those + pending signals. + + This does not influence whether to deliver a signal as requested by + a resumption packet (*note vCont packet::). + + Signals are numbered identically to continue packets and stop + replies (*note Stop Reply Packets::). Each SIGNAL list item should + be strictly greater than the previous item. Multiple + 'QProgramSignals' packets do not combine; any earlier + 'QProgramSignals' list is completely replaced by the new list. + + Reply: + 'OK' + The request succeeded. + + Use of this packet is controlled by the 'set remote + program-signals' command (*note set remote program-signals: Remote + Configuration.). This packet is not probed by default; the remote + stub must request it, by supplying an appropriate 'qSupported' + response (*note qSupported::). + +'QThreadEvents:1' +'QThreadEvents:0' + + Enable ('QThreadEvents:1') or disable ('QThreadEvents:0') reporting + of thread create and exit events. *Note thread create event::, for + the reply specifications. For example, this is used in non-stop + mode when GDB stops a set of threads and synchronously waits for + the their corresponding stop replies. Without exit events, if one + of the threads exits, GDB would hang forever not knowing that it + should no longer expect a stop for that same thread. GDB does not + enable this feature unless the stub reports that it supports it by + including 'QThreadEvents+' in its 'qSupported' reply. + + This packet always enables/disables event reporting for all threads + of all processes under control of the remote stub. For per-thread + control of optional event reporting, see the *note QThreadOptions:: + packet. + + Reply: + 'OK' + The request succeeded. + + Use of this packet is controlled by the 'set remote thread-events' + command (*note set remote thread-events: Remote Configuration.). + +'QThreadOptions[;OPTIONS[:THREAD-ID]]...' + + For each inferior thread, the last OPTIONS in the list with a + matching THREAD-ID are applied. Any options previously set on a + thread are discarded and replaced by the new options specified. + Threads that do not match any THREAD-ID retain their previously-set + options. Thread IDs are specified using the syntax described in + *note thread-id syntax::. If multiprocess extensions (*note + multiprocess extensions::) are supported, options can be specified + to apply to all threads of a process by using the 'pPID.-1' form of + THREAD-ID. Options with no THREAD-ID apply to all threads. + Specifying no options value is an error. Zero is a valid value. + + OPTIONS is an hexadecimal integer specifying the enabled thread + options, and is the bitwise 'OR' of the following values. All + values are given in hexadecimal representation. + + 'GDB_THREAD_OPTION_CLONE (0x1)' + Report thread clone events (*note thread clone event::). This + is only meaningful for targets that support clone events + (e.g., GNU/Linux systems). + + 'GDB_THREAD_OPTION_EXIT (0x2)' + Report thread exit events (*note thread exit event::). + + + For example, GDB enables the 'GDB_THREAD_OPTION_EXIT' and + 'GDB_THREAD_OPTION_CLONE' options when single-stepping a thread + past a breakpoint, for the following reasons: + + * If the single-stepped thread exits (e.g., it executes a thread + exit system call), enabling 'GDB_THREAD_OPTION_EXIT' prevents + GDB from waiting forever, not knowing that it should no longer + expect a stop for that same thread, and blocking other threads + from progressing. + + * If the single-stepped thread spawns a new clone child (i.e., + it executes a clone system call), enabling + 'GDB_THREAD_OPTION_CLONE' halts the cloned thread before it + executes any instructions, and thus prevents the following + problematic situations: + + - If the breakpoint is stepped-over in-line, the spawned + thread would incorrectly run free while the breakpoint + being stepped over is not inserted, and thus the cloned + thread may potentially run past the breakpoint without + stopping for it; + + - If displaced (out-of-line) stepping is used, the cloned + thread starts running at the out-of-line PC, leading to + undefined behavior, usually crashing or corrupting data. + + New threads start with thread options cleared. + + GDB does not enable this feature unless the stub reports that it + supports it by including 'QThreadOptions=SUPPORTED_OPTIONS' in its + 'qSupported' reply. + + Reply: + 'OK' + The request succeeded. + + Use of this packet is controlled by the 'set remote thread-options' + command (*note set remote thread-options: Remote Configuration.). + +'qRcmd,COMMAND' + COMMAND (hex encoded) is passed to the local interpreter for + execution. Invalid commands should be reported using the output + string. Before the final result packet, the target may also + respond with a number of intermediate 'OOUTPUT' console output + packets. _Implementors should note that providing access to a + stubs's interpreter may have security implications_. + + Reply: + 'OK' + A command response with no output. + 'OUTPUT' + A command response with the hex encoded output string OUTPUT. + + Unlike most packets, this packet does not support 'E.ERRTEXT'-style + textual error replies (*note textual error reply::) by default. + Stubs should be careful to only send such a reply if GDB reported + support for it with the 'error-message' feature (*note + error-message::). + + (Note that the 'qRcmd' packet's name is separated from the command + by a ',', not a ':', contrary to the naming conventions above. + Please don't use this packet as a model for new packets.) + +'qSearch:memory:ADDRESS;LENGTH;SEARCH-PATTERN' + Search LENGTH bytes at ADDRESS for SEARCH-PATTERN. Both ADDRESS + and LENGTH are encoded in hex; SEARCH-PATTERN is a sequence of + bytes, also hex encoded. + + Reply: + '0' + The pattern was not found. + '1,address' + The pattern was found at ADDRESS. + +'QStartNoAckMode' + Request that the remote stub disable the normal '+'/'-' protocol + acknowledgments (*note Packet Acknowledgment::). + + Reply: + 'OK' + The stub has switched to no-acknowledgment mode. GDB + acknowledges this response, but neither the stub nor GDB shall + send or expect further '+'/'-' acknowledgments in the current + connection. + +'qSupported [:GDBFEATURE [;GDBFEATURE]... ]' + Tell the remote stub about features supported by GDB, and query the + stub for features it supports. This packet allows GDB and the + remote stub to take advantage of each others' features. + 'qSupported' also consolidates multiple feature probes at startup, + to improve GDB performance--a single larger packet performs better + than multiple smaller probe packets on high-latency links. Some + features may enable behavior which must not be on by default, e.g. + because it would confuse older clients or stubs. Other features + may describe packets which could be automatically probed for, but + are not. These features must be reported before GDB will use them. + This "default unsupported" behavior is not appropriate for all + packets, but it helps to keep the initial connection time under + control with new versions of GDB which support increasing numbers + of packets. + + Reply: + 'STUBFEATURE [;STUBFEATURE]...' + The stub supports or does not support each returned + STUBFEATURE, depending on the form of each STUBFEATURE (see + below for the possible forms). + + The allowed forms for each feature (either a GDBFEATURE in the + 'qSupported' packet, or a STUBFEATURE in the response) are: + + 'NAME=VALUE' + The remote protocol feature NAME is supported, and associated + with the specified VALUE. The format of VALUE depends on the + feature, but it must not include a semicolon. + 'NAME+' + The remote protocol feature NAME is supported, and does not + need an associated value. + 'NAME-' + The remote protocol feature NAME is not supported. + 'NAME?' + The remote protocol feature NAME may be supported, and GDB + should auto-detect support in some other way when it is + needed. This form will not be used for GDBFEATURE + notifications, but may be used for STUBFEATURE responses. + + Whenever the stub receives a 'qSupported' request, the supplied set + of GDB features should override any previous request. This allows + GDB to put the stub in a known state, even if the stub had + previously been communicating with a different version of GDB. + + The following values of GDBFEATURE (for the packet sent by GDB) are + defined: + + 'multiprocess' + This feature indicates whether GDB supports multiprocess + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'multiprocess+' in its 'qSupported' reply. *Note + multiprocess extensions::, for details. + + 'xmlRegisters' + This feature indicates that GDB supports the XML target + description. If the stub sees 'xmlRegisters=' with target + specific strings separated by a comma, it will report register + description. + + 'qRelocInsn' + This feature indicates whether GDB supports the 'qRelocInsn' + packet (*note Relocate instruction reply packet: Tracepoint + Packets.). + + 'swbreak' + This feature indicates whether GDB supports the swbreak stop + reason in stop replies. *Note swbreak stop reason::, for + details. + + 'hwbreak' + This feature indicates whether GDB supports the hwbreak stop + reason in stop replies. *Note swbreak stop reason::, for + details. + + 'fork-events' + This feature indicates whether GDB supports fork event + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'fork-events+' in its 'qSupported' reply. + + 'vfork-events' + This feature indicates whether GDB supports vfork event + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'vfork-events+' in its 'qSupported' reply. + + 'exec-events' + This feature indicates whether GDB supports exec event + extensions to the remote protocol. GDB does not use such + extensions unless the stub also reports that it supports them + by including 'exec-events+' in its 'qSupported' reply. + + 'vContSupported' + This feature indicates whether GDB wants to know the supported + actions in the reply to 'vCont?' packet. + + 'error-message' + This feature indicates whether GDB supports accepting a reply + in 'E.ERRTEXT' format (*Note textual error reply::) from the + 'qRcmd' and 'm' packets. These packets, historically, didn't + support 'E.ERRTEXT', and older versions of GDB didn't expect + to see a reply in this format. + + New packets should be written to support 'E.ERRTEXT' + regardless of this feature being true or not. + + Stubs should ignore any unknown values for GDBFEATURE. Any GDB + which sends a 'qSupported' packet supports receiving packets of + unlimited length (earlier versions of GDB may reject overly long + responses). Additional values for GDBFEATURE may be defined in the + future to let the stub take advantage of new features in GDB, e.g. + incompatible improvements in the remote protocol--the + 'multiprocess' feature is an example of such a feature. The stub's + reply should be independent of the GDBFEATURE entries sent by GDB; + first GDB describes all the features it supports, and then the stub + replies with all the features it supports. + + Similarly, GDB will silently ignore unrecognized stub feature + responses, as long as each response uses one of the standard forms. + + Some features are flags. A stub which supports a flag feature + should respond with a '+' form response. Other features require + values, and the stub should respond with an '=' form response. + + Each feature has a default value, which GDB will use if + 'qSupported' is not available or if the feature is not mentioned in + the 'qSupported' response. The default values are fixed; a stub is + free to omit any feature responses that match the defaults. + + Not all features can be probed, but for those which can, the + probing mechanism is useful: in some cases, a stub's internal + architecture may not allow the protocol layer to know some + information about the underlying target in advance. This is + especially common in stubs which may be configured for multiple + targets. + + These are the currently defined stub features and their properties: + + Feature Name Value Default Probe + Required Allowed + + 'PacketSize' Yes '-' No + + 'qXfer:auxv:read' No '-' Yes + + 'qXfer:btrace:read' No '-' Yes + + 'qXfer:btrace-conf:read' No '-' Yes + + 'qXfer:exec-file:read' No '-' Yes + + 'qXfer:features:read' No '-' Yes + + 'qXfer:libraries:read' No '-' Yes + + 'qXfer:libraries-svr4:read'No '-' Yes + + 'augmented-libraries-svr4-read'No '-' No + + 'qXfer:memory-map:read' No '-' Yes + + 'qXfer:sdata:read' No '-' Yes + + 'qXfer:siginfo:read' No '-' Yes + + 'qXfer:siginfo:write' No '-' Yes + + 'qXfer:threads:read' No '-' Yes + + 'qXfer:traceframe-info:read'No '-' Yes + + 'qXfer:uib:read' No '-' Yes + + 'qXfer:fdpic:read' No '-' Yes + + 'Qbtrace:off' Yes '-' Yes + + 'Qbtrace:bts' Yes '-' Yes + + 'Qbtrace:pt' Yes '-' Yes + + 'Qbtrace-conf:bts:size' Yes '-' Yes + + 'Qbtrace-conf:pt:size' Yes '-' Yes + + 'Qbtrace-conf:pt:ptwrite' Yes '-' Yes + + 'Qbtrace-conf:pt:event-tracing'Yes '-' Yes + + 'QNonStop' No '-' Yes + + 'QCatchSyscalls' No '-' Yes + + 'QPassSignals' No '-' Yes + + 'QStartNoAckMode' No '-' Yes + + 'multiprocess' No '-' No + + 'ConditionalBreakpoints' No '-' No + + 'ConditionalTracepoints' No '-' No + + 'ReverseContinue' No '-' No + + 'ReverseStep' No '-' No + + 'TracepointSource' No '-' No + + 'QAgent' No '-' No + + 'QAllow' No '-' No + + 'QDisableRandomization' No '-' No + + 'EnableDisableTracepoints'No '-' No + + 'QTBuffer:size' No '-' No + + 'tracenz' No '-' No + + 'BreakpointCommands' No '-' No + + 'swbreak' No '-' No + + 'hwbreak' No '-' No + + 'fork-events' No '-' No + + 'vfork-events' No '-' No + + 'exec-events' No '-' No + + 'QThreadEvents' No '-' No + + 'QThreadOptions' Yes '-' No + + 'no-resumed' No '-' No + + 'memory-tagging' No '-' No + + 'error-message' No '+' No + + 'binary-upload' No '-' No + + + These are the currently defined stub features, in more detail: + + 'PacketSize=BYTES' + The remote stub can accept packets up to at least BYTES in + length. GDB will send packets up to this size for bulk + transfers, and will never send larger packets. This is a + limit on the data characters in the packet, not including the + frame and checksum. There is no trailing NUL byte in a remote + protocol packet; if the stub stores packets in a + NUL-terminated format, it should allow an extra byte in its + buffer for the NUL. If this stub feature is not supported, GDB + guesses based on the size of the 'g' packet response. + + 'qXfer:auxv:read' + The remote stub understands the 'qXfer:auxv:read' packet + (*note qXfer auxiliary vector read::). + + 'qXfer:btrace:read' + The remote stub understands the 'qXfer:btrace:read' packet + (*note qXfer btrace read::). + + 'qXfer:btrace-conf:read' + The remote stub understands the 'qXfer:btrace-conf:read' + packet (*note qXfer btrace-conf read::). + + 'qXfer:exec-file:read' + The remote stub understands the 'qXfer:exec-file:read' packet + (*note qXfer executable filename read::). + + 'qXfer:features:read' + The remote stub understands the 'qXfer:features:read' packet + (*note qXfer target description read::). + + 'qXfer:libraries:read' + The remote stub understands the 'qXfer:libraries:read' packet + (*note qXfer library list read::). + + 'qXfer:libraries-svr4:read' + The remote stub understands the 'qXfer:libraries-svr4:read' + packet (*note qXfer svr4 library list read::). + + 'augmented-libraries-svr4-read' + The remote stub understands the augmented form of the + 'qXfer:libraries-svr4:read' packet (*note qXfer svr4 library + list read::). + + 'qXfer:memory-map:read' + The remote stub understands the 'qXfer:memory-map:read' packet + (*note qXfer memory map read::). + + 'qXfer:sdata:read' + The remote stub understands the 'qXfer:sdata:read' packet + (*note qXfer sdata read::). + + 'qXfer:siginfo:read' + The remote stub understands the 'qXfer:siginfo:read' packet + (*note qXfer siginfo read::). + + 'qXfer:siginfo:write' + The remote stub understands the 'qXfer:siginfo:write' packet + (*note qXfer siginfo write::). + + 'qXfer:threads:read' + The remote stub understands the 'qXfer:threads:read' packet + (*note qXfer threads read::). + + 'qXfer:traceframe-info:read' + The remote stub understands the 'qXfer:traceframe-info:read' + packet (*note qXfer traceframe info read::). + + 'qXfer:uib:read' + The remote stub understands the 'qXfer:uib:read' packet (*note + qXfer unwind info block::). + + 'qXfer:fdpic:read' + The remote stub understands the 'qXfer:fdpic:read' packet + (*note qXfer fdpic loadmap read::). + + 'QNonStop' + The remote stub understands the 'QNonStop' packet (*note + QNonStop::). + + 'QCatchSyscalls' + The remote stub understands the 'QCatchSyscalls' packet (*note + QCatchSyscalls::). + + 'QPassSignals' + The remote stub understands the 'QPassSignals' packet (*note + QPassSignals::). + + 'QStartNoAckMode' + The remote stub understands the 'QStartNoAckMode' packet and + prefers to operate in no-acknowledgment mode. *Note Packet + Acknowledgment::. + + 'multiprocess' + The remote stub understands the multiprocess extensions to the + remote protocol syntax. The multiprocess extensions affect + the syntax of thread IDs in both packets and replies (*note + thread-id syntax::), and add process IDs to the 'D' packet and + 'W' and 'X' replies. Note that reporting this feature + indicates support for the syntactic extensions only, not that + the stub necessarily supports debugging of more than one + process at a time. The stub must not use multiprocess + extensions in packet replies unless GDB has also indicated it + supports them in its 'qSupported' request. + + 'qXfer:osdata:read' + The remote stub understands the 'qXfer:osdata:read' packet + ((*note qXfer osdata read::). + + 'ConditionalBreakpoints' + The target accepts and implements evaluation of conditional + expressions defined for breakpoints. The target will only + report breakpoint triggers when such conditions are true + (*note Break Conditions: Conditions.). + + 'ConditionalTracepoints' + The remote stub accepts and implements conditional expressions + defined for tracepoints (*note Tracepoint Conditions::). + + 'ReverseContinue' + The remote stub accepts and implements the reverse continue + packet (*note bc::). + + 'ReverseStep' + The remote stub accepts and implements the reverse step packet + (*note bs::). + + 'TracepointSource' + The remote stub understands the 'QTDPsrc' packet that supplies + the source form of tracepoint definitions. + + 'QAgent' + The remote stub understands the 'QAgent' packet. + + 'QAllow' + The remote stub understands the 'QAllow' packet. + + 'QDisableRandomization' + The remote stub understands the 'QDisableRandomization' + packet. + + 'StaticTracepoint' + The remote stub supports static tracepoints. + + 'InstallInTrace' + The remote stub supports installing tracepoint in tracing. + + 'EnableDisableTracepoints' + The remote stub supports the 'QTEnable' (*note QTEnable::) and + 'QTDisable' (*note QTDisable::) packets that allow tracepoints + to be enabled and disabled while a trace experiment is + running. + + 'QTBuffer:size' + The remote stub supports the 'QTBuffer:size' (*note + QTBuffer-size::) packet that allows to change the size of the + trace buffer. + + 'tracenz' + The remote stub supports the 'tracenz' bytecode for collecting + strings. See *note Bytecode Descriptions:: for details about + the bytecode. + + 'BreakpointCommands' + The remote stub supports running a breakpoint's command list + itself, rather than reporting the hit to GDB. + + 'Qbtrace:off' + The remote stub understands the 'Qbtrace:off' packet. + + 'Qbtrace:bts' + The remote stub understands the 'Qbtrace:bts' packet. + + 'Qbtrace:pt' + The remote stub understands the 'Qbtrace:pt' packet. + + 'Qbtrace-conf:bts:size' + The remote stub understands the 'Qbtrace-conf:bts:size' + packet. + + 'Qbtrace-conf:pt:size' + The remote stub understands the 'Qbtrace-conf:pt:size' packet. + + 'Qbtrace-conf:pt:ptwrite' + The remote stub understands the 'Qbtrace-conf:pt:ptwrite' + packet. + + 'Qbtrace-conf:pt:event-tracing' + The remote stub understands the + 'Qbtrace-conf:pt:event-tracing' packet. + + 'swbreak' + The remote stub reports the 'swbreak' stop reason for memory + breakpoints. + + 'hwbreak' + The remote stub reports the 'hwbreak' stop reason for hardware + breakpoints. + + 'fork-events' + The remote stub reports the 'fork' stop reason for fork + events. + + 'vfork-events' + The remote stub reports the 'vfork' stop reason for vfork + events and vforkdone events. + + 'exec-events' + The remote stub reports the 'exec' stop reason for exec + events. + + 'vContSupported' + The remote stub reports the supported actions in the reply to + 'vCont?' packet. + + 'QThreadEvents' + The remote stub understands the 'QThreadEvents' packet. + + 'QThreadOptions=SUPPORTED_OPTIONS' + The remote stub understands the 'QThreadOptions' packet. + SUPPORTED_OPTIONS indicates the set of thread options the + remote stub supports. SUPPORTED_OPTIONS has the same format + as the OPTIONS parameter of the 'QThreadOptions' packet, + described at *note QThreadOptions::. + + 'no-resumed' + The remote stub reports the 'N' stop reply. + + 'memory-tagging' + The remote stub supports and implements the required memory + tagging functionality and understands the 'qMemTags' (*note + qMemTags::) and 'QMemTags' (*note QMemTags::) packets. + + For AArch64 GNU/Linux systems, this feature can require access + to the '/proc/PID/smaps' file so memory mapping page flags can + be inspected, if 'qIsAddressTagged' (*note qIsAddressTagged::) + packet is not supported by the stub. Access to the + '/proc/PID/smaps' file is done via 'vFile' requests. + + 'error-message' + The remote stub supports replying with an error in a + 'E.ERRTEXT' (*Note textual error reply::) format from the 'm' + and 'qRcmd' packets. It is not usually necessary to send this + feature back to GDB in the 'qSupported' reply, GDB will always + support 'E.ERRTEXT' format replies if it sent the + 'error-message' feature. + + 'binary-upload' + The remote stub supports the 'x' packet (*note x packet::). + +'qSymbol::' + Notify the target that GDB is prepared to serve symbol lookup + requests. Accept requests from the target for the values of + symbols. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of symbol SYM_NAME (hex + encoded). GDB may provide the value by using the + 'qSymbol:SYM_VALUE:SYM_NAME' message, described below. + +'qSymbol:SYM_VALUE:SYM_NAME' + Set the value of SYM_NAME to SYM_VALUE. + + SYM_NAME (hex encoded) is the name of a symbol whose value the + target has previously requested. + + SYM_VALUE (hex) is the value for symbol SYM_NAME. If GDB cannot + supply a value for SYM_NAME, then this field will be empty. + + Reply: + 'OK' + The target does not need to look up any (more) symbols. + 'qSymbol:SYM_NAME' + The target requests the value of a new symbol SYM_NAME (hex + encoded). GDB will continue to supply the values of symbols + (if available), until the target ceases to request them. + +'qTBuffer' +'QTBuffer' +'QTDisconnected' +'QTDP' +'QTDPsrc' +'QTDV' +'qTfP' +'qTfV' +'QTFrame' +'qTMinFTPILen' + + *Note Tracepoint Packets::. + +'qThreadExtraInfo,THREAD-ID' + Obtain from the target OS a printable string description of thread + attributes for the thread THREAD-ID; see *note thread-id syntax::, + for the forms of THREAD-ID. This string may contain anything that + the target OS thinks is interesting for GDB to tell the user about + the thread. The string is displayed in GDB's 'info threads' + display. Some examples of possible thread extra info strings are + 'Runnable', or 'Blocked on Mutex'. + + Reply: + 'XX...' + Where 'XX...' is a hex encoding of ASCII data, comprising the + printable string containing the extra information about the + thread's attributes. + + (Note that the 'qThreadExtraInfo' packet's name is separated from + the command by a ',', not a ':', contrary to the naming conventions + above. Please don't use this packet as a model for new packets.) + +'QTNotes' +'qTP' +'QTSave' +'qTsP' +'qTsV' +'QTStart' +'QTStop' +'QTEnable' +'QTDisable' +'QTinit' +'QTro' +'qTStatus' +'qTV' +'qTfSTM' +'qTsSTM' +'qTSTMat' + *Note Tracepoint Packets::. + +'qXfer:OBJECT:read:ANNEX:OFFSET,LENGTH' + Read uninterpreted bytes from the target's special data area + identified by the keyword OBJECT. Request LENGTH bytes starting at + OFFSET bytes into the data. The content and encoding of ANNEX is + specific to OBJECT; it can supply additional details about what + data to access. + + Reply: + 'm DATA' + Data DATA (*note Binary Data::) has been read from the target. + There may be more data at a higher address (although it is + permitted to return 'm' even for the last valid block of data, + as long as at least one byte of data was read). It is + possible for DATA to have fewer bytes than the LENGTH in the + request. + + 'l DATA' + Data DATA (*note Binary Data::) has been read from the target. + There is no more data to be read. It is possible for DATA to + have fewer bytes than the LENGTH in the request. + + 'l' + The OFFSET in the request is at the end of the data. There is + no more data to be read. + + Here are the specific requests of this form defined so far. All + the 'qXfer:OBJECT:read:...' requests use the same reply formats, + listed above. + + 'qXfer:auxv:read::OFFSET,LENGTH' + Access the target's "auxiliary vector". *Note auxiliary + vector: OS Information. Note ANNEX must be empty. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:btrace:read:ANNEX:OFFSET,LENGTH' + + Return a description of the current branch trace. *Note + Branch Trace Format::. The annex part of the generic 'qXfer' + packet may have one of the following values: + + 'all' + Returns all available branch trace. + + 'new' + Returns all available branch trace if the branch trace + changed since the last read request. + + 'delta' + Returns the new branch trace since the last read request. + Adds a new block to the end of the trace that begins at + zero and ends at the source location of the first branch + in the trace buffer. This extra block is used to stitch + traces together. + + If the trace buffer overflowed, returns an error + indicating the overflow. + + This packet is not probed by default; the remote stub must + request it by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:btrace-conf:read::OFFSET,LENGTH' + + Return a description of the current branch trace + configuration. *Note Branch Trace Configuration Format::. + + This packet is not probed by default; the remote stub must + request it by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:exec-file:read:ANNEX:OFFSET,LENGTH' + Return the full absolute name of the file that was executed to + create a process running on the remote system. The annex + specifies the numeric process ID of the process to query, + encoded as a hexadecimal number. If the annex part is empty + the remote stub should return the filename corresponding to + the currently executing process. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:features:read:ANNEX:OFFSET,LENGTH' + Access the "target description". *Note Target Descriptions::. + The annex specifies which XML document to access. The main + description is always loaded from the 'target.xml' annex. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries. *Note Library + List Format::. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). + + Targets which maintain a list of libraries in the program's + memory do not need to implement this packet; it is designed + for platforms where the operating system manages the list of + loaded libraries. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:libraries-svr4:read:ANNEX:OFFSET,LENGTH' + Access the target's list of loaded libraries when the target + is an SVR4 platform. *Note Library List Format for SVR4 + Targets::. The annex part of the generic 'qXfer' packet must + be empty unless the remote stub indicated it supports the + augmented form of this packet by supplying an appropriate + 'qSupported' response (*note qXfer read::, *note + qSupported::). + + This packet is optional for better performance on SVR4 + targets. GDB uses memory read packets to read the SVR4 + library list otherwise. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + If the remote stub indicates it supports the augmented form of + this packet then the annex part of the generic 'qXfer' packet + may contain a semicolon-separated list of 'NAME=VALUE' + arguments. The currently supported arguments are: + + 'start=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' to start reading the library list from. + If unset or zero then the first 'struct link_map' in the + library list will be chosen as the starting point. + + 'prev=ADDRESS' + A hexadecimal number specifying the address of the + 'struct link_map' immediately preceding the 'struct + link_map' specified by the 'start' argument. If unset or + zero then the remote stub will expect that no 'struct + link_map' exists prior to the starting point. + + 'lmid=LMID' + A hexadecimal number specifying a namespace identifier. + This is currently only used together with 'start' to + provide the namespace identifier back to GDB in the + response. GDB will only provide values that were + previously reported to it. If unset, the response will + include 'lmid="0x0"'. + + Arguments that are not understood by the remote stub will be + silently ignored. + + 'qXfer:memory-map:read::OFFSET,LENGTH' + Access the target's "memory-map". *Note Memory Map Format::. + The annex part of the generic 'qXfer' packet must be empty + (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:sdata:read::OFFSET,LENGTH' + + Read contents of the extra collected static tracepoint marker + information. The annex part of the generic 'qXfer' packet + must be empty (*note qXfer read::). *Note Tracepoint Action + Lists: Tracepoint Actions. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:siginfo:read::OFFSET,LENGTH' + Read contents of the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:threads:read::OFFSET,LENGTH' + Access the list of threads on target. *Note Thread List + Format::. The annex part of the generic 'qXfer' packet must + be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:traceframe-info:read::OFFSET,LENGTH' + + Return a description of the current traceframe's contents. + *Note Traceframe Info Format::. The annex part of the generic + 'qXfer' packet must be empty (*note qXfer read::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:uib:read:PC:OFFSET,LENGTH' + + Return the unwind information block for PC. This packet is + used on OpenVMS/ia64 to ask the kernel unwind information. + + This packet is not probed by default. + + 'qXfer:fdpic:read:ANNEX:OFFSET,LENGTH' + Read contents of 'loadmap's on the target system. The annex, + either 'exec' or 'interp', specifies which 'loadmap', + executable 'loadmap' or interpreter 'loadmap' to read. + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + + 'qXfer:osdata:read::OFFSET,LENGTH' + Access the target's "operating system information". *Note + Operating System Information::. + +'qXfer:OBJECT:write:ANNEX:OFFSET:DATA...' + Write uninterpreted bytes into the target's special data area + identified by the keyword OBJECT, starting at OFFSET bytes into the + data. The binary-encoded data (*note Binary Data::) to be written + is given by DATA.... The content and encoding of ANNEX is specific + to OBJECT; it can supply additional details about what data to + access. + + Reply: + 'NN' + NN (hex encoded) is the number of bytes written. This may be + fewer bytes than supplied in the request. + + Here are the specific requests of this form defined so far. All + the 'qXfer:OBJECT:write:...' requests use the same reply formats, + listed above. + + 'qXfer:siginfo:write::OFFSET:DATA...' + Write DATA to the extra signal information on the target + system. The annex part of the generic 'qXfer' packet must be + empty (*note qXfer write::). + + This packet is not probed by default; the remote stub must + request it, by supplying an appropriate 'qSupported' response + (*note qSupported::). + +'qXfer:OBJECT:OPERATION:...' + Requests of this form may be added in the future. When a stub does + not recognize the OBJECT keyword, or its support for OBJECT does + not recognize the OPERATION keyword, the stub must respond with an + empty packet. + +'qAttached:PID' + Return an indication of whether the remote server attached to an + existing process or created a new process. When the multiprocess + protocol extensions are supported (*note multiprocess + extensions::), PID is an integer in hexadecimal format identifying + the target process. Otherwise, GDB will omit the PID field and the + query packet will be simplified as 'qAttached'. + + This query is used, for example, to know whether the remote process + should be detached or killed when a GDB session is ended with the + 'quit' command. + + Reply: + '1' + The remote server attached to an existing process. + '0' + The remote server created a new process. + +'Qbtrace:bts' + Enable branch tracing for the current thread using Branch Trace + Store. + + Reply: + 'OK' + Branch tracing has been enabled. + +'Qbtrace:pt' + Enable branch tracing for the current thread using Intel Processor + Trace. + + Reply: + 'OK' + Branch tracing has been enabled. + +'Qbtrace:off' + Disable branch tracing for the current thread. + + Reply: + 'OK' + Branch tracing has been disabled. + +'Qbtrace-conf:bts:size=VALUE' + Set the requested ring buffer size for new threads that use the + btrace recording method in bts format. + + Reply: + 'OK' + The ring buffer size has been set. + +'Qbtrace-conf:pt:size=VALUE' + Set the requested ring buffer size for new threads that use the + btrace recording method in pt format. + + Reply: + 'OK' + The ring buffer size has been set. + +'Qbtrace-conf:pt:ptwrite=(YES|NO)' + Indicate support for 'PTWRITE' packets. This allows for backwards + compatibility. + + Reply: + 'OK' + The ptwrite config parameter has been set. + 'E.errtext' + A badly formed request or an error was encountered. + +'Qbtrace-conf:pt:event-tracing=(YES|NO)' + Indicate support for event-tracing packets. This allows for + backwards compatibility. + + Reply: + 'OK' + The event-tracing config parameter has been set. + 'E.errtext' + A badly formed request or an error was encountered. + + ---------- Footnotes ---------- + + (1) The 'qP' and 'qL' packets predate these conventions, and have +arguments without any terminator for the packet name; we suspect they +are in widespread use in places that are difficult to upgrade. The 'qC' +packet has no arguments, but some existing stubs (e.g. RedBoot) are +known to not check for the end of the packet. + diff -pruN 16.3-5/gdb/doc/gdb.info-8 16.3-5ubuntu1/gdb/doc/gdb.info-8 --- 16.3-5/gdb/doc/gdb.info-8 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.info-8 2025-04-20 17:25:33.000000000 +0000 @@ -0,0 +1,8949 @@ +This is gdb.info, produced by makeinfo version 6.8 from gdb.texinfo. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +END-INFO-DIR-ENTRY + + This file documents the GNU debugger GDB. + + This is the Tenth Edition, of 'Debugging with GDB: the GNU +Source-Level Debugger' for GDB (GDB) Version 16.3. + + Copyright (C) 1988-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being "Free Software" and "Free Software Needs Free +Documentation", with the Front-Cover Texts being "A GNU Manual," and +with the Back-Cover Texts as in (a) below. + + (a) The FSF's Back-Cover Text is: "You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom." + + +File: gdb.info, Node: Architecture-Specific Protocol Details, Next: Tracepoint Packets, Prev: General Query Packets, Up: Remote Protocol + +E.6 Architecture-Specific Protocol Details +========================================== + +This section describes how the remote protocol is applied to specific +target architectures. Also see *note Standard Target Features::, for +details of XML target descriptions for each architecture. + +* Menu: + +* ARM-Specific Protocol Details:: +* MIPS-Specific Protocol Details:: + + +File: gdb.info, Node: ARM-Specific Protocol Details, Next: MIPS-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.6.1 ARM-specific Protocol Details +----------------------------------- + +* Menu: + +* ARM Breakpoint Kinds:: +* ARM Memory Tag Types:: + + +File: gdb.info, Node: ARM Breakpoint Kinds, Next: ARM Memory Tag Types, Up: ARM-Specific Protocol Details + +E.6.1.1 ARM Breakpoint Kinds +............................ + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit Thumb mode breakpoint. + +3 + 32-bit Thumb mode (Thumb-2) breakpoint. + +4 + 32-bit ARM mode breakpoint. + + +File: gdb.info, Node: ARM Memory Tag Types, Prev: ARM Breakpoint Kinds, Up: ARM-Specific Protocol Details + +E.6.1.2 ARM Memory Tag Types +............................ + +These memory tag types are defined for the 'qMemTag' and 'QMemTag' +packets. + +0 + MTE logical tag + +1 + MTE allocation tag + + +File: gdb.info, Node: MIPS-Specific Protocol Details, Prev: ARM-Specific Protocol Details, Up: Architecture-Specific Protocol Details + +E.6.2 MIPS-specific Protocol Details +------------------------------------ + +* Menu: + +* MIPS Register packet Format:: +* MIPS Breakpoint Kinds:: + + +File: gdb.info, Node: MIPS Register packet Format, Next: MIPS Breakpoint Kinds, Up: MIPS-Specific Protocol Details + +E.6.2.1 MIPS Register Packet Format +................................... + +The following 'g'/'G' packets have previously been defined. In the +below, some thirty-two bit registers are transferred as sixty-four bits. +Those registers should be zero/sign extended (which?) to fill the space +allocated. Register bytes are transferred in target byte order. The +two nibbles within a register byte are transferred most-significant - +least-significant. + +MIPS32 + All registers are transferred as thirty-two bit quantities in the + order: 32 general-purpose; sr; lo; hi; bad; cause; pc; 32 + floating-point registers; fsr; fir; fp. + +MIPS64 + All registers are transferred as sixty-four bit quantities + (including thirty-two bit registers such as 'sr'). The ordering is + the same as 'MIPS32'. + + +File: gdb.info, Node: MIPS Breakpoint Kinds, Prev: MIPS Register packet Format, Up: MIPS-Specific Protocol Details + +E.6.2.2 MIPS Breakpoint Kinds +............................. + +These breakpoint kinds are defined for the 'Z0' and 'Z1' packets. + +2 + 16-bit MIPS16 mode breakpoint. + +3 + 16-bit microMIPS mode breakpoint. + +4 + 32-bit standard MIPS mode breakpoint. + +5 + 32-bit microMIPS mode breakpoint. + + +File: gdb.info, Node: Tracepoint Packets, Next: Host I/O Packets, Prev: Architecture-Specific Protocol Details, Up: Remote Protocol + +E.7 Tracepoint Packets +====================== + +Here we describe the packets GDB uses to implement tracepoints (*note +Tracepoints::). + +'QTDP:N:ADDR:ENA:STEP:PASS[:FFLEN][:XLEN,BYTES][-]' + Create a new tracepoint, number N, at ADDR. If ENA is 'E', then + the tracepoint is enabled; if it is 'D', then the tracepoint is + disabled. The STEP gives the tracepoint's step count, and PASS + gives its pass count. If an 'F' is present, then the tracepoint is + to be a fast tracepoint, and the FLEN is the number of bytes that + the target should copy elsewhere to make room for the tracepoint. + If an 'X' is present, it introduces a tracepoint condition, which + consists of a hexadecimal length, followed by a comma and + hex-encoded bytes, in a manner similar to action encodings as + described below. If the trailing '-' is present, further 'QTDP' + packets will follow to specify this tracepoint's actions. + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + +'QTDP:-N:ADDR:[S]ACTION...[-]' + Define actions to be taken when a tracepoint is hit. The N and + ADDR must be the same as in the initial 'QTDP' packet for this + tracepoint. This packet may only be sent immediately after another + 'QTDP' packet that ended with a '-'. If the trailing '-' is + present, further 'QTDP' packets will follow, specifying more + actions for this tracepoint. + + In the series of action packets for a given tracepoint, at most one + can have an 'S' before its first ACTION. If such a packet is sent, + it and the following packets define "while-stepping" actions. Any + prior packets define ordinary actions -- that is, those taken when + the tracepoint is first hit. If no action packet has an 'S', then + all the packets in the series specify ordinary tracepoint actions. + + The 'ACTION...' portion of the packet is a series of actions, + concatenated without separators. Each action has one of the + following forms: + + 'R MASK' + Collect the registers whose bits are set in MASK, a + hexadecimal number whose I'th bit is set if register number I + should be collected. (The least significant bit is numbered + zero.) Note that MASK may be any number of digits long; it + may not fit in a 32-bit word. + + 'M BASEREG,OFFSET,LEN' + Collect LEN bytes of memory starting at the address in + register number BASEREG, plus OFFSET. If BASEREG is '-1', + then the range has a fixed address: OFFSET is the address of + the lowest byte to collect. The BASEREG, OFFSET, and LEN + parameters are all unsigned hexadecimal values (the '-1' value + for BASEREG is a special case). + + 'X LEN,EXPR' + Evaluate EXPR, whose length is LEN, and collect memory as it + directs. The agent expression EXPR is as described in *note + Agent Expressions::. Each byte of the expression is encoded + as a two-digit hex number in the packet; LEN is the number of + bytes in the expression (and thus one-half the number of hex + digits in the packet). + + Any number of actions may be packed together in a single 'QTDP' + packet, as long as the packet does not exceed the maximum packet + length (400 bytes, for many stubs). There may be only one 'R' + action per tracepoint, and it must precede any 'M' or 'X' actions. + Any registers referred to by 'M' and 'X' actions must be collected + by a preceding 'R' action. (The "while-stepping" actions are + treated as if they were attached to a separate tracepoint, as far + as these restrictions are concerned.) + + Replies: + 'OK' + The packet was understood and carried out. + 'qRelocInsn' + *Note Relocate instruction reply packet: Tracepoint Packets. + +'QTDPsrc:N:ADDR:TYPE:START:SLEN:BYTES' + Specify a source string of tracepoint N at address ADDR. This is + useful to get accurate reproduction of the tracepoints originally + downloaded at the beginning of the trace run. The TYPE is the name + of the tracepoint part, such as 'cond' for the tracepoint's + conditional expression (see below for a list of types), while BYTES + is the string, encoded in hexadecimal. + + START is the offset of the BYTES within the overall source string, + while SLEN is the total length of the source string. This is + intended for handling source strings that are longer than will fit + in a single packet. + + The available string types are 'at' for the location, 'cond' for + the conditional, and 'cmd' for an action command. GDB sends a + separate packet for each command in the action list, in the same + order in which the commands are stored in the list. + + The target does not need to do anything with source strings except + report them back as part of the replies to the 'qTfP'/'qTsP' query + packets. + + Although this packet is optional, and GDB will only send it if the + target replies with 'TracepointSource' *Note General Query + Packets::, it makes both disconnected tracing and trace files much + easier to use. Otherwise the user must be careful that the + tracepoints in effect while looking at trace frames are identical + to the ones in effect during the trace run; even a small + discrepancy could cause 'tdump' not to work, or a particular trace + frame not be found. + +'QTDV:N:VALUE:BUILTIN:NAME' + Create a new trace state variable, number N, with an initial value + of VALUE, which is a 64-bit signed integer. Both N and VALUE are + encoded as hexadecimal values. GDB has the option of not using + this packet for initial values of zero; the target should simply + create the trace state variables as they are mentioned in + expressions. The value BUILTIN should be 1 (one) if the trace + state variable is builtin and 0 (zero) if it is not builtin. GDB + only sets BUILTIN to 1 if a previous 'qTfV' or 'qTsV' packet had it + set. The contents of NAME is the hex-encoded name (without the + leading '$') of the trace state variable. + +'QTFrame:N' + Select the N'th tracepoint frame from the buffer, and use the + register and memory contents recorded there to answer subsequent + request packets from GDB. + + A successful reply from the stub indicates that the stub has found + the requested frame. The response is a series of parts, + concatenated without separators, describing the frame we selected. + Each part has one of the following forms: + + 'F F' + The selected frame is number N in the trace frame buffer; F is + a hexadecimal number. If F is '-1', then there was no frame + matching the criteria in the request packet. + + 'T T' + The selected trace frame records a hit of tracepoint number T; + T is a hexadecimal number. + +'QTFrame:pc:ADDR' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is ADDR; ADDR is a hexadecimal + number. + +'QTFrame:tdp:T' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame that is a hit of tracepoint T; T is a + hexadecimal number. + +'QTFrame:range:START:END' + Like 'QTFrame:N', but select the first tracepoint frame after the + currently selected frame whose PC is between START (inclusive) and + END (inclusive); START and END are hexadecimal numbers. + +'QTFrame:outside:START:END' + Like 'QTFrame:range:START:END', but select the first frame + _outside_ the given range of addresses (exclusive). + +'qTMinFTPILen' + This packet requests the minimum length of instruction at which a + fast tracepoint (*note Set Tracepoints::) may be placed. For + instance, on the 32-bit x86 architecture, it is possible to use a + 4-byte jump, but it depends on the target system being able to + create trampolines in the first 64K of memory, which might or might + not be possible for that system. So the reply to this packet will + be 4 if it is able to arrange for that. + + Replies: + + '0' + The minimum instruction length is currently unknown. + 'LENGTH' + The minimum instruction length is LENGTH, where LENGTH is a + hexadecimal number greater or equal to 1. A reply of 1 means + that a fast tracepoint may be placed on any instruction + regardless of size. + 'E' + An error has occurred. + +'QTStart' + Begin the tracepoint experiment. Begin collecting data from + tracepoint hits in the trace frame buffer. This packet supports + the 'qRelocInsn' reply (*note Relocate instruction reply packet: + Tracepoint Packets.). + +'QTStop' + End the tracepoint experiment. Stop collecting trace frames. + +'QTEnable:N:ADDR' + Enable tracepoint N at address ADDR in a started tracepoint + experiment. If the tracepoint was previously disabled, then + collection of data from it will resume. + +'QTDisable:N:ADDR' + Disable tracepoint N at address ADDR in a started tracepoint + experiment. No more data will be collected from the tracepoint + unless 'QTEnable:N:ADDR' is subsequently issued. + +'QTinit' + Clear the table of tracepoints, and empty the trace frame buffer. + +'QTro:START1,END1:START2,END2:...' + Establish the given ranges of memory as "transparent". The stub + will answer requests for these ranges from memory's current + contents, if they were not collected as part of the tracepoint hit. + + GDB uses this to mark read-only regions of memory, like those + containing program code. Since these areas never change, they + should still have the same contents they did when the tracepoint + was hit, so there's no reason for the stub to refuse to provide + their contents. + +'QTDisconnected:VALUE' + Set the choice to what to do with the tracing run when GDB + disconnects from the target. A VALUE of 1 directs the target to + continue the tracing run, while 0 tells the target to stop tracing + if GDB is no longer in the picture. + +'qTStatus' + Ask the stub if there is a trace experiment running right now. + + The reply has the form: + + 'TRUNNING[;FIELD]...' + RUNNING is a single digit '1' if the trace is presently + running, or '0' if not. It is followed by semicolon-separated + optional fields that an agent may use to report additional + status. + + If the trace is not running, the agent may report any of several + explanations as one of the optional fields: + + 'tnotrun:0' + No trace has been run yet. + + 'tstop[:TEXT]:0' + The trace was stopped by a user-originated stop command. The + optional TEXT field is a user-supplied string supplied as part + of the stop command (for instance, an explanation of why the + trace was stopped manually). It is hex-encoded. + + 'tfull:0' + The trace stopped because the trace buffer filled up. + + 'tdisconnected:0' + The trace stopped because GDB disconnected from the target. + + 'tpasscount:TPNUM' + The trace stopped because tracepoint TPNUM exceeded its pass + count. + + 'terror:TEXT:TPNUM' + The trace stopped because tracepoint TPNUM had an error. The + string TEXT is available to describe the nature of the error + (for instance, a divide by zero in the condition expression); + it is hex encoded. + + 'tunknown:0' + The trace stopped for some other reason. + + Additional optional fields supply statistical and other + information. Although not required, they are extremely useful for + users monitoring the progress of a trace run. If a trace has + stopped, and these numbers are reported, they must reflect the + state of the just-stopped trace. + + 'tframes:N' + The number of trace frames in the buffer. + + 'tcreated:N' + The total number of trace frames created during the run. This + may be larger than the trace frame count, if the buffer is + circular. + + 'tsize:N' + The total size of the trace buffer, in bytes. + + 'tfree:N' + The number of bytes still unused in the buffer. + + 'circular:N' + The value of the circular trace buffer flag. '1' means that + the trace buffer is circular and old trace frames will be + discarded if necessary to make room, '0' means that the trace + buffer is linear and may fill up. + + 'disconn:N' + The value of the disconnected tracing flag. '1' means that + tracing will continue after GDB disconnects, '0' means that + the trace run will stop. + +'qTP:TP:ADDR' + Ask the stub for the current state of tracepoint number TP at + address ADDR. + + Replies: + 'VHITS:USAGE' + The tracepoint has been hit HITS times so far during the trace + run, and accounts for USAGE in the trace buffer. Note that + 'while-stepping' steps are not counted as separate hits, but + the steps' space consumption is added into the usage number. + +'qTV:VAR' + Ask the stub for the value of the trace state variable number VAR. + + Replies: + 'VVALUE' + The value of the variable is VALUE. This will be the current + value of the variable if the user is examining a running + target, or a saved value if the variable was collected in the + trace frame that the user is looking at. Note that multiple + requests may result in different reply values, such as when + requesting values while the program is running. + + 'U' + The value of the variable is unknown. This would occur, for + example, if the user is examining a trace frame in which the + requested variable was not collected. + +'qTfP' +'qTsP' + These packets request data about tracepoints that are being used by + the target. GDB sends 'qTfP' to get the first piece of data, and + multiple 'qTsP' to get additional pieces. Replies to these packets + generally take the form of the 'QTDP' packets that define + tracepoints. (FIXME add detailed syntax) + +'qTfV' +'qTsV' + These packets request data about trace state variables that are on + the target. GDB sends 'qTfV' to get the first vari of data, and + multiple 'qTsV' to get additional variables. Replies to these + packets follow the syntax of the 'QTDV' packets that define trace + state variables. + +'qTfSTM' +'qTsSTM' + These packets request data about static tracepoint markers that + exist in the target program. GDB sends 'qTfSTM' to get the first + piece of data, and multiple 'qTsSTM' to get additional pieces. + Replies to these packets take the following form: + + Reply: + 'm ADDRESS:ID:EXTRA' + A single marker + 'm ADDRESS:ID:EXTRA,ADDRESS:ID:EXTRA...' + a comma-separated list of markers + 'l' + (lower case letter 'L') denotes end of list. + + The ADDRESS is encoded in hex; ID and EXTRA are strings encoded in + hex. + + In response to each query, the target will reply with a list of one + or more markers, separated by commas. GDB will respond to each + reply with a request for more markers (using the 'qs' form of the + query), until the target responds with 'l' (lower-case ell, for + "last"). + +'qTSTMat:ADDRESS' + This packets requests data about static tracepoint markers in the + target program at ADDRESS. Replies to this packet follow the + syntax of the 'qTfSTM' and 'qTsSTM' packets that list static + tracepoint markers. + +'QTSave:FILENAME' + This packet directs the target to save trace data to the file name + FILENAME in the target's filesystem. The FILENAME is encoded as a + hex string; the interpretation of the file name (relative vs + absolute, wild cards, etc) is up to the target. + +'qTBuffer:OFFSET,LEN' + Return up to LEN bytes of the current contents of trace buffer, + starting at OFFSET. The trace buffer is treated as if it were a + contiguous collection of traceframes, as per the trace file format. + The reply consists as many hex-encoded bytes as the target can + deliver in a packet; it is not an error to return fewer than were + asked for. A reply consisting of just 'l' indicates that no bytes + are available. + +'QTBuffer:circular:VALUE' + This packet directs the target to use a circular trace buffer if + VALUE is 1, or a linear buffer if the value is 0. + +'QTBuffer:size:SIZE' + This packet directs the target to make the trace buffer be of size + SIZE if possible. A value of '-1' tells the target to use whatever + size it prefers. + +'QTNotes:[TYPE:TEXT][;TYPE:TEXT]...' + This packet adds optional textual notes to the trace run. + Allowable types include 'user', 'notes', and 'tstop', the TEXT + fields are arbitrary strings, hex-encoded. + +E.7.1 Relocate instruction reply packet +--------------------------------------- + +When installing fast tracepoints in memory, the target may need to +relocate the instruction currently at the tracepoint address to a +different address in memory. For most instructions, a simple copy is +enough, but, for example, call instructions that implicitly push the +return address on the stack, and relative branches or other PC-relative +instructions require offset adjustment, so that the effect of executing +the instruction at a different address is the same as if it had executed +in the original location. + + In response to several of the tracepoint packets, the target may also +respond with a number of intermediate 'qRelocInsn' request packets +before the final result packet, to have GDB handle this relocation +operation. If a packet supports this mechanism, its documentation will +explicitly say so. See for example the above descriptions for the +'QTStart' and 'QTDP' packets. The format of the request is: + +'qRelocInsn:FROM;TO' + + This requests GDB to copy instruction at address FROM to address + TO, possibly adjusted so that executing the instruction at TO has + the same effect as executing it at FROM. GDB writes the adjusted + instruction to target memory starting at TO. + + Replies: +'qRelocInsn:ADJUSTED_SIZE' + Informs the stub the relocation is complete. The ADJUSTED_SIZE is + the length in bytes of resulting relocated instruction sequence. + + +File: gdb.info, Node: Host I/O Packets, Next: Interrupts, Prev: Tracepoint Packets, Up: Remote Protocol + +E.8 Host I/O Packets +==================== + +The "Host I/O" packets allow GDB to perform I/O operations on the far +side of a remote link. For example, Host I/O is used to upload and +download files to a remote target with its own filesystem. Host I/O +uses the same constant values and data structure layout as the +target-initiated File-I/O protocol. However, the Host I/O packets are +structured differently. The target-initiated protocol relies on target +memory to store parameters and buffers. Host I/O requests are initiated +by GDB, and the target's memory is not involved. *Note File-I/O Remote +Protocol Extension::, for more details on the target-initiated protocol. + + The Host I/O request packets all encode a single operation along with +its arguments. They have this format: + +'vFile:OPERATION: PARAMETER...' + OPERATION is the name of the particular request; the target should + compare the entire packet name up to the second colon when checking + for a supported operation. The format of PARAMETER depends on the + operation. Numbers are always passed in hexadecimal. Negative + numbers have an explicit minus sign (i.e. two's complement is not + used). Strings (e.g. filenames) are encoded as a series of + hexadecimal bytes. The last argument to a system call may be a + buffer of escaped binary data (*note Binary Data::). + + The valid responses to Host I/O packets are: + +'F RESULT [, ERRNO] [; ATTACHMENT]' + RESULT is the integer value returned by this operation, usually + non-negative for success and -1 for errors. If an error has + occurred, ERRNO will be included in the result specifying a value + defined by the File-I/O protocol (*note Errno Values::). For + operations which return data, ATTACHMENT supplies the data as a + binary buffer. Binary buffers in response packets are escaped in + the normal way (*note Binary Data::). See the individual packet + documentation for the interpretation of RESULT and ATTACHMENT. + +'' + An empty response indicates that this operation is not recognized. + + These are the supported Host I/O operations: + +'vFile:open: FILENAME, FLAGS, MODE' + Open a file at FILENAME and return a file descriptor for it, or + return -1 if an error occurs. The FILENAME is a string, FLAGS is + an integer indicating a mask of open flags (*note Open Flags::), + and MODE is an integer indicating a mask of mode bits to use if the + file is created (*note mode_t Values::). *Note open::, for details + of the open flags and mode values. + +'vFile:close: FD' + Close the open file corresponding to FD and return 0, or -1 if an + error occurs. + +'vFile:pread: FD, COUNT, OFFSET' + Read data from the open file corresponding to FD. Up to COUNT + bytes will be read from the file, starting at OFFSET relative to + the start of the file. The target may read fewer bytes; common + reasons include packet size limits and an end-of-file condition. + The number of bytes read is returned. Zero should only be returned + for a successful read at the end of the file, or if COUNT was zero. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + +'vFile:pwrite: FD, OFFSET, DATA' + Write DATA (a binary buffer) to the open file corresponding to FD. + Start the write at OFFSET from the start of the file. Unlike many + 'write' system calls, there is no separate COUNT argument; the + length of DATA in the packet is used. 'vFile:pwrite' returns the + number of bytes written, which may be shorter than the length of + DATA, or -1 if an error occurred. + +'vFile:fstat: FD' + Get information about the open file corresponding to FD. On + success the information is returned as a binary attachment and the + return value is the size of this attachment in bytes. If an error + occurs the return value is -1. The format of the returned binary + attachment is as described in *note struct stat::. + +'vFile:stat: FILENAME' + Get information about the file FILENAME on the target. On success + the information is returned as a binary attachment and the return + value is the size of this attachment in bytes. If an error occurs + the return value is -1. The format of the returned binary + attachment is as described in *note struct stat::. + +'vFile:unlink: FILENAME' + Delete the file at FILENAME on the target. Return 0, or -1 if an + error occurs. The FILENAME is a string. + +'vFile:readlink: FILENAME' + Read value of symbolic link FILENAME on the target. Return the + number of bytes read, or -1 if an error occurs. + + The data read should be returned as a binary attachment on success. + If zero bytes were read, the response should include an empty + binary attachment (i.e. a trailing semicolon). The return value is + the number of target bytes read; the binary attachment may be + longer if some characters were escaped. + +'vFile:setfs: PID' + Select the filesystem on which 'vFile' operations with FILENAME + arguments will operate. This is required for GDB to be able to + access files on remote targets where the remote stub does not share + a common filesystem with the inferior(s). + + If PID is nonzero, select the filesystem as seen by process PID. + If PID is zero, select the filesystem as seen by the remote stub. + Return 0 on success, or -1 if an error occurs. If 'vFile:setfs:' + indicates success, the selected filesystem remains selected until + the next successful 'vFile:setfs:' operation. + + +File: gdb.info, Node: Interrupts, Next: Notification Packets, Prev: Host I/O Packets, Up: Remote Protocol + +E.9 Interrupts +============== + +In all-stop mode, when a program on the remote target is running, GDB +may attempt to interrupt it by sending a 'Ctrl-C', 'BREAK' or a 'BREAK' +followed by 'g', control of which is specified via GDB's +'interrupt-sequence'. + + The precise meaning of 'BREAK' is defined by the transport mechanism +and may, in fact, be undefined. GDB does not currently define a 'BREAK' +mechanism for any of the network interfaces except for TCP, in which +case GDB sends the 'telnet' BREAK sequence. + + 'Ctrl-C', on the other hand, is defined and implemented for all +transport mechanisms. It is represented by sending the single byte +'0x03' without any of the usual packet overhead described in the +Overview section (*note Overview::). When a '0x03' byte is transmitted +as part of a packet, it is considered to be packet data and does _not_ +represent an interrupt. E.g., an 'X' packet (*note X packet::), used +for binary downloads, may include an unescaped '0x03' as part of its +packet. + + 'BREAK' followed by 'g' is also known as Magic SysRq g. When Linux +kernel receives this sequence from serial port, it stops execution and +connects to gdb. + + In non-stop mode, because packet resumptions are asynchronous (*note +vCont packet::), GDB is always free to send a remote command to the +remote stub, even when the target is running. For that reason, GDB +instead sends a regular packet (*note vCtrlC packet::) with the usual +packet framing instead of the single byte '0x03'. + + Stubs are not required to recognize these interrupt mechanisms and +the precise meaning associated with receipt of the interrupt is +implementation defined. If the target supports debugging of multiple +threads and/or processes, it should attempt to interrupt all +currently-executing threads and processes. If the stub is successful at +interrupting the running program, it should send one of the stop reply +packets (*note Stop Reply Packets::) to GDB as a result of successfully +stopping the program in all-stop mode, and a stop reply for each stopped +thread in non-stop mode. Interrupts received while the program is +stopped are queued and the program will be interrupted when it is +resumed next time. + + +File: gdb.info, Node: Notification Packets, Next: Remote Non-Stop, Prev: Interrupts, Up: Remote Protocol + +E.10 Notification Packets +========================= + +The GDB remote serial protocol includes "notifications", packets that +require no acknowledgment. Both the GDB and the stub may send +notifications (although the only notifications defined at present are +sent by the stub). Notifications carry information without incurring +the round-trip latency of an acknowledgment, and so are useful for +low-impact communications where occasional packet loss is not a problem. + + A notification packet has the form '% DATA # CHECKSUM', where DATA is +the content of the notification, and CHECKSUM is a checksum of DATA, +computed and formatted as for ordinary GDB packets. A notification's +DATA never contains '$', '%' or '#' characters. Upon receiving a +notification, the recipient sends no '+' or '-' to acknowledge the +notification's receipt or to report its corruption. + + Every notification's DATA begins with a name, which contains no colon +characters, followed by a colon character. + + Recipients should silently ignore corrupted notifications and +notifications they do not understand. Recipients should restart timeout +periods on receipt of a well-formed notification, whether or not they +understand it. + + Senders should only send the notifications described here when this +protocol description specifies that they are permitted. In the future, +we may extend the protocol to permit existing notifications in new +contexts; this rule helps older senders avoid confusing newer +recipients. + + (Older versions of GDB ignore bytes received until they see the '$' +byte that begins an ordinary packet, so new stubs may transmit +notifications without fear of confusing older clients. There are no +notifications defined for GDB to send at the moment, but we assume that +most older stubs would ignore them, as well.) + + Each notification is comprised of three parts: +'NAME:EVENT' + The notification packet is sent by the side that initiates the + exchange (currently, only the stub does that), with EVENT carrying + the specific information about the notification, and NAME + specifying the name of the notification. +'ACK' + The acknowledge sent by the other side, usually GDB, to acknowledge + the exchange and request the event. + + The purpose of an asynchronous notification mechanism is to report to +GDB that something interesting happened in the remote stub. + + The remote stub may send notification NAME:EVENT at any time, but GDB +acknowledges the notification when appropriate. The notification event +is pending before GDB acknowledges. Only one notification at a time may +be pending; if additional events occur before GDB has acknowledged the +previous notification, they must be queued by the stub for later +synchronous transmission in response to ACK packets from GDB. Because +the notification mechanism is unreliable, the stub is permitted to +resend a notification if it believes GDB may not have received it. + + Specifically, notifications may appear when GDB is not otherwise +reading input from the stub, or when GDB is expecting to read a normal +synchronous response or a '+'/'-' acknowledgment to a packet it has +sent. Notification packets are distinct from any other communication +from the stub so there is no ambiguity. + + After receiving a notification, GDB shall acknowledge it by sending a +ACK packet as a regular, synchronous request to the stub. Such +acknowledgment is not required to happen immediately, as GDB is +permitted to send other, unrelated packets to the stub first, which the +stub should process normally. + + Upon receiving a ACK packet, if the stub has other queued events to +report to GDB, it shall respond by sending a normal EVENT. GDB shall +then send another ACK packet to solicit further responses; again, it is +permitted to send other, unrelated packets as well which the stub should +process normally. + + If the stub receives a ACK packet and there are no additional EVENT +to report, the stub shall return an 'OK' response. At this point, GDB +has finished processing a notification and the stub has completed +sending any queued events. GDB won't accept any new notifications until +the final 'OK' is received . If further notification events occur, the +stub shall send a new notification, GDB shall accept the notification, +and the process shall be repeated. + + The process of asynchronous notification can be illustrated by the +following example: + <- %Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0; + ... + -> vStopped + <- T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0; + -> vStopped + <- T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0; + -> vStopped + <- OK + + The following notifications are defined: + +NotificationAck Event Description + +Stop vStopped REPLY. The REPLY has the Report an asynchronous + form of a stop reply, as stop event in non-stop + described in mode. + *note Stop Reply Packets::. + Refer to + *note Remote Non-Stop::, + for information on how + these notifications are + acknowledged by GDB. + + +File: gdb.info, Node: Remote Non-Stop, Next: Packet Acknowledgment, Prev: Notification Packets, Up: Remote Protocol + +E.11 Remote Protocol Support for Non-Stop Mode +============================================== + +GDB's remote protocol supports non-stop debugging of multi-threaded +programs, as described in *note Non-Stop Mode::. If the stub supports +non-stop mode, it should report that to GDB by including 'QNonStop+' in +its 'qSupported' response (*note qSupported::). + + GDB typically sends a 'QNonStop' packet only when establishing a new +connection with the stub. Entering non-stop mode does not alter the +state of any currently-running threads, but targets must stop all +threads in any already-attached processes when entering all-stop mode. +GDB uses the '?' packet as necessary to probe the target state after a +mode change. + + In non-stop mode, when an attached process encounters an event that +would otherwise be reported with a stop reply, it uses the asynchronous +notification mechanism (*note Notification Packets::) to inform GDB. In +contrast to all-stop mode, where all threads in all processes are +stopped when a stop reply is sent, in non-stop mode only the thread +reporting the stop event is stopped. That is, when reporting a 'S' or +'T' response to indicate completion of a step operation, hitting a +breakpoint, or a fault, only the affected thread is stopped; any other +still-running threads continue to run. When reporting a 'W' or 'X' +response, all running threads belonging to other attached processes +continue to run. + + In non-stop mode, the target shall respond to the '?' packet as +follows. First, any incomplete stop reply notification/'vStopped' +sequence in progress is abandoned. The target must begin a new sequence +reporting stop events for all stopped threads, whether or not it has +previously reported those events to GDB. The first stop reply is sent +as a synchronous reply to the '?' packet, and subsequent stop replies +are sent as responses to 'vStopped' packets using the mechanism +described above. The target must not send asynchronous stop reply +notifications until the sequence is complete. If all threads are +running when the target receives the '?' packet, or if the target is not +attached to any process, it shall respond 'OK'. + + If the stub supports non-stop mode, it should also support the +'swbreak' stop reason if software breakpoints are supported, and the +'hwbreak' stop reason if hardware breakpoints are supported (*note +swbreak stop reason::). This is because given the asynchronous nature +of non-stop mode, between the time a thread hits a breakpoint and the +time the event is finally processed by GDB, the breakpoint may have +already been removed from the target. Due to this, GDB needs to be able +to tell whether a trap stop was caused by a delayed breakpoint event, +which should be ignored, as opposed to a random trap signal, which +should be reported to the user. Note the 'swbreak' feature implies that +the target is responsible for adjusting the PC when a software +breakpoint triggers, if necessary, such as on the x86 architecture. + + +File: gdb.info, Node: Packet Acknowledgment, Next: Examples, Prev: Remote Non-Stop, Up: Remote Protocol + +E.12 Packet Acknowledgment +========================== + +By default, when either the host or the target machine receives a +packet, the first response expected is an acknowledgment: either '+' (to +indicate the package was received correctly) or '-' (to request +retransmission). This mechanism allows the GDB remote protocol to +operate over unreliable transport mechanisms, such as a serial line. + + In cases where the transport mechanism is itself reliable (such as a +pipe or TCP connection), the '+'/'-' acknowledgments are redundant. It +may be desirable to disable them in that case to reduce communication +overhead, or for other reasons. This can be accomplished by means of +the 'QStartNoAckMode' packet; *note QStartNoAckMode::. + + When in no-acknowledgment mode, neither the stub nor GDB shall send +or expect '+'/'-' protocol acknowledgments. The packet and response +format still includes the normal checksum, as described in *note +Overview::, but the checksum may be ignored by the receiver. + + If the stub supports 'QStartNoAckMode' and prefers to operate in +no-acknowledgment mode, it should report that to GDB by including +'QStartNoAckMode+' in its response to 'qSupported'; *note qSupported::. +If GDB also supports 'QStartNoAckMode' and it has not been disabled via +the 'set remote noack-packet off' command (*note Remote +Configuration::), GDB may then send a 'QStartNoAckMode' packet to the +stub. Only then may the stub actually turn off packet acknowledgments. +GDB sends a final '+' acknowledgment of the stub's 'OK' response, which +can be safely ignored by the stub. + + Note that 'set remote noack-packet' command only affects negotiation +between GDB and the stub when subsequent connections are made; it does +not affect the protocol acknowledgment state for any current connection. +Since '+'/'-' acknowledgments are enabled by default when a new +connection is established, there is also no protocol request to +re-enable the acknowledgments for the current connection, once disabled. + + +File: gdb.info, Node: Examples, Next: File-I/O Remote Protocol Extension, Prev: Packet Acknowledgment, Up: Remote Protocol + +E.13 Examples +============= + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + + -> R00 + <- + + _target restarts_ + -> ? + <- + + <- T001:1234123412341234 + -> + + + Example sequence of a target being stepped by a single instruction: + + -> G1445... + <- + + -> s + <- + + _time passes_ + <- T001:1234123412341234 + -> + + -> g + <- + + <- 1455... + -> + + + +File: gdb.info, Node: File-I/O Remote Protocol Extension, Next: Library List Format, Prev: Examples, Up: Remote Protocol + +E.14 File-I/O Remote Protocol Extension +======================================= + +* Menu: + +* File-I/O Overview:: +* Protocol Basics:: +* The F Request Packet:: +* The F Reply Packet:: +* The Ctrl-C Message:: +* Console I/O:: +* List of Supported Calls:: +* Protocol-specific Representation of Datatypes:: +* Constants:: +* File-I/O Examples:: + + +File: gdb.info, Node: File-I/O Overview, Next: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.14.1 File-I/O Overview +------------------------ + +The "File I/O remote protocol extension" (short: File-I/O) allows the +target to use the host's file system and console I/O to perform various +system calls. System calls on the target system are translated into a +remote protocol packet to the host system, which then performs the +needed actions and returns a response packet to the target system. This +simulates file system operations even on targets that lack file systems. + + The protocol is defined to be independent of both the host and target +systems. It uses its own internal representation of datatypes and +values. Both GDB and the target's GDB stub are responsible for +translating the system-dependent value representations into the internal +protocol representations when data is transmitted. + + The communication is synchronous. A system call is possible only +when GDB is waiting for a response from the 'C', 'c', 'S' or 's' +packets. While GDB handles the request for a system call, the target is +stopped to allow deterministic access to the target's memory. Therefore +File-I/O is not interruptible by target signals. On the other hand, it +is possible to interrupt File-I/O by a user interrupt ('Ctrl-C') within +GDB. + + The target's request to perform a host system call does not finish +the latest 'C', 'c', 'S' or 's' action. That means, after finishing the +system call, the target returns to continuing the previous activity +(continue, step). No additional continue or step request from GDB is +required. + + (gdb) continue + <- target requests 'system call X' + target is stopped, GDB executes system call + -> GDB returns result + ... target continues, GDB returns to wait for the target + <- target hits breakpoint and sends a Txx packet + + The protocol only supports I/O on the console and to regular files on +the host file system. Character or block special devices, pipes, named +pipes, sockets or any other communication method on the host system are +not supported by this protocol. + + File I/O is not supported in non-stop mode. + + +File: gdb.info, Node: Protocol Basics, Next: The F Request Packet, Prev: File-I/O Overview, Up: File-I/O Remote Protocol Extension + +E.14.2 Protocol Basics +---------------------- + +The File-I/O protocol uses the 'F' packet as the request as well as +reply packet. Since a File-I/O system call can only occur when GDB is +waiting for a response from the continuing or stepping target, the +File-I/O request is a reply that GDB has to expect as a result of a +previous 'C', 'c', 'S' or 's' packet. This 'F' packet contains all +information needed to allow GDB to call the appropriate host system +call: + + * A unique identifier for the requested system call. + + * All parameters to the system call. Pointers are given as addresses + in the target memory address space. Pointers to strings are given + as pointer/length pair. Numerical values are given as they are. + Numerical control flags are given in a protocol-specific + representation. + + At this point, GDB has to perform the following actions. + + * If the parameters include pointer values to data needed as input to + a system call, GDB requests this data from the target with a + standard 'm' packet request. This additional communication has to + be expected by the target implementation and is handled as any + other 'm' packet. + + * GDB translates all value from protocol representation to host + representation as needed. Datatypes are coerced into the host + types. + + * GDB calls the system call. + + * It then coerces datatypes back to protocol representation. + + * If the system call is expected to return data in buffer space + specified by pointer parameters to the call, the data is + transmitted to the target using a 'M' or 'X' packet. This packet + has to be expected by the target implementation and is handled as + any other 'M' or 'X' packet. + + Eventually GDB replies with another 'F' packet which contains all +necessary information for the target to continue. This at least +contains + + * Return value. + + * 'errno', if has been changed by the system call. + + * "Ctrl-C" flag. + + After having done the needed type and value coercion, the target +continues the latest continue or step action. + + +File: gdb.info, Node: The F Request Packet, Next: The F Reply Packet, Prev: Protocol Basics, Up: File-I/O Remote Protocol Extension + +E.14.3 The 'F' Request Packet +----------------------------- + +The 'F' request packet has the following format: + +'FCALL-ID,PARAMETER...' + + CALL-ID is the identifier to indicate the host system call to be + called. This is just the name of the function. + + PARAMETER... are the parameters to the system call. Parameters are + hexadecimal integer values, either the actual values in case of + scalar datatypes, pointers to target buffer space in case of + compound datatypes and unspecified memory areas, or pointer/length + pairs in case of string parameters. These are appended to the + CALL-ID as a comma-delimited list. All values are transmitted in + ASCII string representation, pointer/length pairs separated by a + slash. + + +File: gdb.info, Node: The F Reply Packet, Next: The Ctrl-C Message, Prev: The F Request Packet, Up: File-I/O Remote Protocol Extension + +E.14.4 The 'F' Reply Packet +--------------------------- + +The 'F' reply packet has the following format: + +'FRETCODE,ERRNO,CTRL-C FLAG;CALL-SPECIFIC ATTACHMENT' + + RETCODE is the return code of the system call as hexadecimal value. + + ERRNO is the 'errno' set by the call, in protocol-specific + representation. This parameter can be omitted if the call was + successful. + + CTRL-C FLAG is only sent if the user requested a break. In this + case, ERRNO must be sent as well, even if the call was successful. + The CTRL-C FLAG itself consists of the character 'C': + + F0,0,C + + or, if the call was interrupted before the host call has been + performed: + + F-1,4,C + + assuming 4 is the protocol-specific representation of 'EINTR'. + + +File: gdb.info, Node: The Ctrl-C Message, Next: Console I/O, Prev: The F Reply Packet, Up: File-I/O Remote Protocol Extension + +E.14.5 The 'Ctrl-C' Message +--------------------------- + +If the 'Ctrl-C' flag is set in the GDB reply packet (*note The F Reply +Packet::), the target should behave as if it had gotten a break message. +The meaning for the target is "system call interrupted by 'SIGINT'". +Consequently, the target should actually stop (as with a break message) +and return to GDB with a 'T02' packet. + + It's important for the target to know in which state the system call +was interrupted. There are two possible cases: + + * The system call hasn't been performed on the host yet. + + * The system call on the host has been finished. + + These two states can be distinguished by the target by the value of +the returned 'errno'. If it's the protocol representation of 'EINTR', +the system call hasn't been performed. This is equivalent to the +'EINTR' handling on POSIX systems. In any other case, the target may +presume that the system call has been finished -- successfully or not -- +and should behave as if the break message arrived right after the system +call. + + GDB must behave reliably. If the system call has not been called +yet, GDB may send the 'F' reply immediately, setting 'EINTR' as 'errno' +in the packet. If the system call on the host has been finished before +the user requests a break, the full action must be finished by GDB. +This requires sending 'M' or 'X' packets as necessary. The 'F' packet +may only be sent when either nothing has happened or the full action has +been completed. + + +File: gdb.info, Node: Console I/O, Next: List of Supported Calls, Prev: The Ctrl-C Message, Up: File-I/O Remote Protocol Extension + +E.14.6 Console I/O +------------------ + +By default and if not explicitly closed by the target system, the file +descriptors 0, 1 and 2 are connected to the GDB console. Output on the +GDB console is handled as any other file output operation ('write(1, +...)' or 'write(2, ...)'). Console input is handled by GDB so that +after the target read request from file descriptor 0 all following +typing is buffered until either one of the following conditions is met: + + * The user types 'Ctrl-c'. The behavior is as explained above, and + the 'read' system call is treated as finished. + + * The user presses . This is treated as end of input with a + trailing newline. + + * The user types 'Ctrl-d'. This is treated as end of input. No + trailing character (neither newline nor 'Ctrl-D') is appended to + the input. + + If the user has typed more characters than fit in the buffer given to +the 'read' call, the trailing characters are buffered in GDB until +either another 'read(0, ...)' is requested by the target, or debugging +is stopped at the user's request. + + +File: gdb.info, Node: List of Supported Calls, Next: Protocol-specific Representation of Datatypes, Prev: Console I/O, Up: File-I/O Remote Protocol Extension + +E.14.7 List of Supported Calls +------------------------------ + +* Menu: + +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: + + +File: gdb.info, Node: open, Next: close, Up: List of Supported Calls + +open +.... + +Synopsis: + int open(const char *pathname, int flags); + int open(const char *pathname, int flags, mode_t mode); + +Request: + 'Fopen,PATHPTR/LEN,FLAGS,MODE' + + FLAGS is the bitwise 'OR' of the following values: + + 'O_CREAT' + If the file does not exist it will be created. The host rules + apply as far as file ownership and time stamps are concerned. + + 'O_EXCL' + When used with 'O_CREAT', if the file already exists it is an + error and open() fails. + + 'O_TRUNC' + If the file already exists and the open mode allows writing + ('O_RDWR' or 'O_WRONLY' is given) it will be truncated to zero + length. + + 'O_APPEND' + The file is opened in append mode. + + 'O_RDONLY' + The file is opened for reading only. + + 'O_WRONLY' + The file is opened for writing only. + + 'O_RDWR' + The file is opened for reading and writing. + + Other bits are silently ignored. + + MODE is the bitwise 'OR' of the following values: + + 'S_IRUSR' + User has read permission. + + 'S_IWUSR' + User has write permission. + + 'S_IRGRP' + Group has read permission. + + 'S_IWGRP' + Group has write permission. + + 'S_IROTH' + Others have read permission. + + 'S_IWOTH' + Others have write permission. + + Other bits are silently ignored. + +Return value: + 'open' returns the new file descriptor or -1 if an error occurred. + +Errors: + + 'EEXIST' + PATHNAME already exists and 'O_CREAT' and 'O_EXCL' were used. + + 'EISDIR' + PATHNAME refers to a directory. + + 'EACCES' + The requested access is not allowed. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENODEV' + PATHNAME refers to a device, pipe, named pipe or socket. + + 'EROFS' + PATHNAME refers to a file on a read-only filesystem and write + access was requested. + + 'EFAULT' + PATHNAME is an invalid pointer value. + + 'ENOSPC' + No space on device to create the file. + + 'EMFILE' + The process already has the maximum number of files open. + + 'ENFILE' + The limit on the total number of files open on the system has + been reached. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: close, Next: read, Prev: open, Up: List of Supported Calls + +close +..... + +Synopsis: + int close(int fd); + +Request: + 'Fclose,FD' + +Return value: + 'close' returns zero on success, or -1 if an error occurred. + +Errors: + + 'EBADF' + FD isn't a valid open file descriptor. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: read, Next: write, Prev: close, Up: List of Supported Calls + +read +.... + +Synopsis: + int read(int fd, void *buf, unsigned int count); + +Request: + 'Fread,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes read is returned. Zero indicates + end of file. If count is zero, read returns zero as well. On + error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for reading. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: write, Next: lseek, Prev: read, Up: List of Supported Calls + +write +..... + +Synopsis: + int write(int fd, const void *buf, unsigned int count); + +Request: + 'Fwrite,FD,BUFPTR,COUNT' + +Return value: + On success, the number of bytes written are returned. Zero + indicates nothing was written. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid file descriptor or is not open for writing. + + 'EFAULT' + BUFPTR is an invalid pointer value. + + 'EFBIG' + An attempt was made to write a file that exceeds the + host-specific maximum file size allowed. + + 'ENOSPC' + No space on device to write the data. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: lseek, Next: rename, Prev: write, Up: List of Supported Calls + +lseek +..... + +Synopsis: + long lseek (int fd, long offset, int flag); + +Request: + 'Flseek,FD,OFFSET,FLAG' + + FLAG is one of: + + 'SEEK_SET' + The offset is set to OFFSET bytes. + + 'SEEK_CUR' + The offset is set to its current location plus OFFSET bytes. + + 'SEEK_END' + The offset is set to the size of the file plus OFFSET bytes. + +Return value: + On success, the resulting unsigned offset in bytes from the + beginning of the file is returned. Otherwise, a value of -1 is + returned. + +Errors: + + 'EBADF' + FD is not a valid open file descriptor. + + 'ESPIPE' + FD is associated with the GDB console. + + 'EINVAL' + FLAG is not a proper value. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: rename, Next: unlink, Prev: lseek, Up: List of Supported Calls + +rename +...... + +Synopsis: + int rename(const char *oldpath, const char *newpath); + +Request: + 'Frename,OLDPATHPTR/LEN,NEWPATHPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EISDIR' + NEWPATH is an existing directory, but OLDPATH is not a + directory. + + 'EEXIST' + NEWPATH is a non-empty directory. + + 'EBUSY' + OLDPATH or NEWPATH is a directory that is in use by some + process. + + 'EINVAL' + An attempt was made to make a directory a subdirectory of + itself. + + 'ENOTDIR' + A component used as a directory in OLDPATH or new path is not + a directory. Or OLDPATH is a directory and NEWPATH exists but + is not a directory. + + 'EFAULT' + OLDPATHPTR or NEWPATHPTR are invalid pointer values. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + + OLDPATH or NEWPATH was too long. + + 'ENOENT' + A directory component in OLDPATH or NEWPATH does not exist. + + 'EROFS' + The file is on a read-only filesystem. + + 'ENOSPC' + The device containing the file has no room for the new + directory entry. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: unlink, Next: stat/fstat, Prev: rename, Up: List of Supported Calls + +unlink +...... + +Synopsis: + int unlink(const char *pathname); + +Request: + 'Funlink,PATHNAMEPTR/LEN' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EACCES' + No access to the file or the path of the file. + + 'EPERM' + The system does not allow unlinking of directories. + + 'EBUSY' + The file PATHNAME cannot be unlinked because it's being used + by another process. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'ENOENT' + A directory component in PATHNAME does not exist. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EROFS' + The file is on a read-only filesystem. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: stat/fstat, Next: gettimeofday, Prev: unlink, Up: List of Supported Calls + +stat/fstat +.......... + +Synopsis: + int stat(const char *pathname, struct stat *buf); + int fstat(int fd, struct stat *buf); + +Request: + 'Fstat,PATHNAMEPTR/LEN,BUFPTR' + 'Ffstat,FD,BUFPTR' + +Return value: + On success, zero is returned. On error, -1 is returned. + +Errors: + + 'EBADF' + FD is not a valid open file. + + 'ENOENT' + A directory component in PATHNAME does not exist or the path + is an empty string. + + 'ENOTDIR' + A component of the path is not a directory. + + 'EFAULT' + PATHNAMEPTR is an invalid pointer value. + + 'EACCES' + No access to the file or the path of the file. + + 'ENAMETOOLONG' + PATHNAME was too long. + + 'EINTR' + The call was interrupted by the user. + + +File: gdb.info, Node: gettimeofday, Next: isatty, Prev: stat/fstat, Up: List of Supported Calls + +gettimeofday +............ + +Synopsis: + int gettimeofday(struct timeval *tv, void *tz); + +Request: + 'Fgettimeofday,TVPTR,TZPTR' + +Return value: + On success, 0 is returned, -1 otherwise. + +Errors: + + 'EINVAL' + TZ is a non-NULL pointer. + + 'EFAULT' + TVPTR and/or TZPTR is an invalid pointer value. + + +File: gdb.info, Node: isatty, Next: system, Prev: gettimeofday, Up: List of Supported Calls + +isatty +...... + +Synopsis: + int isatty(int fd); + +Request: + 'Fisatty,FD' + +Return value: + Returns 1 if FD refers to the GDB console, 0 otherwise. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + Note that the 'isatty' call is treated as a special case: it returns +1 to the target if the file descriptor is attached to the GDB console, 0 +otherwise. Implementing through system calls would require implementing +'ioctl' and would be more complex than needed. + + +File: gdb.info, Node: system, Prev: isatty, Up: List of Supported Calls + +system +...... + +Synopsis: + int system(const char *command); + +Request: + 'Fsystem,COMMANDPTR/LEN' + +Return value: + If LEN is zero, the return value indicates whether a shell is + available. A zero return value indicates a shell is not available. + For non-zero LEN, the value returned is -1 on error and the return + status of the command otherwise. Only the exit status of the + command is returned, which is extracted from the host's 'system' + return value by calling 'WEXITSTATUS(retval)'. In case '/bin/sh' + could not be executed, 127 is returned. + +Errors: + + 'EINTR' + The call was interrupted by the user. + + GDB takes over the full task of calling the necessary host calls to +perform the 'system' call. The return value of 'system' on the host is +simplified before it's returned to the target. Any termination signal +information from the child process is discarded, and the return value +consists entirely of the exit status of the called command. + + Due to security concerns, the 'system' call is by default refused by +GDB. The user has to allow this call explicitly with the 'set remote +system-call-allowed 1' command. + +'set remote system-call-allowed' + Control whether to allow the 'system' calls in the File I/O + protocol for the remote target. The default is zero (disabled). + +'show remote system-call-allowed' + Show whether the 'system' calls are allowed in the File I/O + protocol. + + +File: gdb.info, Node: Protocol-specific Representation of Datatypes, Next: Constants, Prev: List of Supported Calls, Up: File-I/O Remote Protocol Extension + +E.14.8 Protocol-specific Representation of Datatypes +---------------------------------------------------- + +* Menu: + +* Integral Datatypes:: +* Pointer Values:: +* Memory Transfer:: +* struct stat:: +* struct timeval:: + + +File: gdb.info, Node: Integral Datatypes, Next: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Integral Datatypes +.................. + +The integral datatypes used in the system calls are 'int', 'unsigned +int', 'long', 'unsigned long', 'mode_t', and 'time_t'. + + 'int', 'unsigned int', 'mode_t' and 'time_t' are implemented as 32 +bit values in this protocol. + + 'long' and 'unsigned long' are implemented as 64 bit types. + + *Note Limits::, for corresponding MIN and MAX values (similar to +those in 'limits.h') to allow range checking on host and target. + + 'time_t' datatypes are defined as seconds since the Epoch. + + All integral datatypes transferred as part of a memory read or write +of a structured datatype e.g. a 'struct stat' have to be given in big +endian byte order. + + +File: gdb.info, Node: Pointer Values, Next: Memory Transfer, Prev: Integral Datatypes, Up: Protocol-specific Representation of Datatypes + +Pointer Values +.............. + +Pointers to target data are transmitted as they are. An exception is +made for pointers to buffers for which the length isn't transmitted as +part of the function call, namely strings. Strings are transmitted as a +pointer/length pair, both as hex values, e.g. + + 1aaf/12 + +which is a pointer to data of length 18 bytes at position 0x1aaf. The +length is defined as the full string length in bytes, including the +trailing null byte. For example, the string '"hello world"' at address +0x123456 is transmitted as + + 123456/d + + +File: gdb.info, Node: Memory Transfer, Next: struct stat, Prev: Pointer Values, Up: Protocol-specific Representation of Datatypes + +Memory Transfer +............... + +Structured data which is transferred using a memory read or write (for +example, a 'struct stat') is expected to be in a protocol-specific +format with all scalar multibyte datatypes being big endian. +Translation to this representation needs to be done both by the target +before the 'F' packet is sent, and by GDB before it transfers memory to +the target. Transferred pointers to structured data should point to the +already-coerced data at any time. + + +File: gdb.info, Node: struct stat, Next: struct timeval, Prev: Memory Transfer, Up: Protocol-specific Representation of Datatypes + +struct stat +........... + +The buffer of type 'struct stat' used by the target and GDB is defined +as follows: + + struct stat { + unsigned int st_dev; /* device */ + unsigned int st_ino; /* inode */ + mode_t st_mode; /* protection */ + unsigned int st_nlink; /* number of hard links */ + unsigned int st_uid; /* user ID of owner */ + unsigned int st_gid; /* group ID of owner */ + unsigned int st_rdev; /* device type (if inode device) */ + unsigned long st_size; /* total size, in bytes */ + unsigned long st_blksize; /* blocksize for filesystem I/O */ + unsigned long st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last change */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 64 bytes. + + The values of several fields have a restricted meaning and/or range +of values. + +'st_dev' + A value of 0 represents a file, 1 the console. + +'st_ino' + No valid meaning for the target. Transmitted unchanged. + +'st_mode' + Valid mode bits are described in *note Constants::. Any other bits + have currently no meaning for the target. + +'st_uid' +'st_gid' +'st_rdev' + No valid meaning for the target. Transmitted unchanged. + +'st_atime' +'st_mtime' +'st_ctime' + These values have a host and file system dependent accuracy. + Especially on Windows hosts, the file system may not support exact + timing values. + + The target gets a 'struct stat' of the above representation and is +responsible for coercing it to the target representation before +continuing. + + Note that due to size differences between the host, target, and +protocol representations of 'struct stat' members, these members could +eventually get truncated on the target. + + +File: gdb.info, Node: struct timeval, Prev: struct stat, Up: Protocol-specific Representation of Datatypes + +struct timeval +.............. + +The buffer of type 'struct timeval' used by the File-I/O protocol is +defined as follows: + + struct timeval { + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ + }; + + The integral datatypes conform to the definitions given in the +appropriate section (see *note Integral Datatypes::, for details) so +this structure is of size 8 bytes. + + +File: gdb.info, Node: Constants, Next: File-I/O Examples, Prev: Protocol-specific Representation of Datatypes, Up: File-I/O Remote Protocol Extension + +E.14.9 Constants +---------------- + +The following values are used for the constants inside of the protocol. +GDB and target are responsible for translating these values before and +after the call as needed. + +* Menu: + +* Open Flags:: +* mode_t Values:: +* Errno Values:: +* Lseek Flags:: +* Limits:: + + +File: gdb.info, Node: Open Flags, Next: mode_t Values, Up: Constants + +Open Flags +.......... + +All values are given in hexadecimal representation. + + O_RDONLY 0x0 + O_WRONLY 0x1 + O_RDWR 0x2 + O_APPEND 0x8 + O_CREAT 0x200 + O_TRUNC 0x400 + O_EXCL 0x800 + + +File: gdb.info, Node: mode_t Values, Next: Errno Values, Prev: Open Flags, Up: Constants + +mode_t Values +............. + +All values are given in octal representation. + + S_IFREG 0100000 + S_IFDIR 040000 + S_IRUSR 0400 + S_IWUSR 0200 + S_IXUSR 0100 + S_IRGRP 040 + S_IWGRP 020 + S_IXGRP 010 + S_IROTH 04 + S_IWOTH 02 + S_IXOTH 01 + + +File: gdb.info, Node: Errno Values, Next: Lseek Flags, Prev: mode_t Values, Up: Constants + +Errno Values +............ + +All values are given in decimal representation. + + EPERM 1 + ENOENT 2 + EINTR 4 + EBADF 9 + EACCES 13 + EFAULT 14 + EBUSY 16 + EEXIST 17 + ENODEV 19 + ENOTDIR 20 + EISDIR 21 + EINVAL 22 + ENFILE 23 + EMFILE 24 + EFBIG 27 + ENOSPC 28 + ESPIPE 29 + EROFS 30 + ENAMETOOLONG 91 + EUNKNOWN 9999 + + 'EUNKNOWN' is used as a fallback error value if a host system returns +any error value not in the list of supported error numbers. + + +File: gdb.info, Node: Lseek Flags, Next: Limits, Prev: Errno Values, Up: Constants + +Lseek Flags +........... + + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 + + +File: gdb.info, Node: Limits, Prev: Lseek Flags, Up: Constants + +Limits +...... + +All values are given in decimal representation. + + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 + + +File: gdb.info, Node: File-I/O Examples, Prev: Constants, Up: File-I/O Remote Protocol Extension + +E.14.10 File-I/O Examples +------------------------- + +Example sequence of a write call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be written: + + <- Fwrite,3,1234,6 + _request memory read from target_ + -> m1234,6 + <- XXXXXX + _return "6 bytes written"_ + -> F6 + + Example sequence of a read call, file descriptor 3, buffer is at +target address 0x1234, 6 bytes should be read: + + <- Fread,3,1234,6 + _request memory write to target_ + -> X1234,6:XXXXXX + _return "6 bytes read"_ + -> F6 + + Example sequence of a read call, call fails on the host due to +invalid file descriptor ('EBADF'): + + <- Fread,3,1234,6 + -> F-1,9 + + Example sequence of a read call, user presses 'Ctrl-c' before syscall +on host is called: + + <- Fread,3,1234,6 + -> F-1,4,C + <- T02 + + Example sequence of a read call, user presses 'Ctrl-c' after syscall +on host is called: + + <- Fread,3,1234,6 + -> X1234,6:XXXXXX + <- T02 + + +File: gdb.info, Node: Library List Format, Next: Library List Format for SVR4 Targets, Prev: File-I/O Remote Protocol Extension, Up: Remote Protocol + +E.15 Library List Format +======================== + +On some platforms, a dynamic loader (e.g. 'ld.so') runs in the same +process as your application to manage libraries. In this case, GDB can +use the loader's symbol table and normal memory operations to maintain a +list of shared libraries. On other platforms, the operating system +manages loaded libraries. GDB can not retrieve the list of currently +loaded libraries through memory operations, so it uses the +'qXfer:libraries:read' packet (*note qXfer library list read::) instead. +The remote stub queries the target's operating system and reports which +libraries are loaded. + + The 'qXfer:libraries:read' packet returns an XML document which lists +loaded libraries and their offsets. Each library has an associated name +and one or more segment or section base addresses, which report where +the library was loaded in memory. + + For the common case of libraries that are fully linked binaries, the +library should have a list of segments. If the target supports dynamic +linking of a relocatable object file, its library XML element should +instead include a list of allocated sections. The segment or section +bases are start addresses, not relocation offsets; they do not depend on +the library's link-time base addresses. + + GDB must be linked with the Expat library to support XML library +lists. *Note Expat::. + + A simple memory map, with one loaded library relocated by a single +offset, looks like this: + + + + + + + + Another simple memory map, with one loaded library with three +allocated sections (.text, .data, .bss), looks like this: + + + +
+
+
+ + + + The format of a library list is described by this DTD: + + + + + + + + + + + + In addition, segments and section descriptors cannot be mixed within +a single library element, and you must supply at least one segment or +section for each library. + + +File: gdb.info, Node: Library List Format for SVR4 Targets, Next: Memory Map Format, Prev: Library List Format, Up: Remote Protocol + +E.16 Library List Format for SVR4 Targets +========================================= + +On SVR4 platforms GDB can use the symbol table of a dynamic loader (e.g. +'ld.so') and normal memory operations to maintain a list of shared +libraries. Still a special library list provided by this packet is more +efficient for the GDB remote protocol. + + The 'qXfer:libraries-svr4:read' packet returns an XML document which +lists loaded libraries and their SVR4 linker parameters. For each +library on SVR4 target, the following parameters are reported: + + - 'name', the absolute file name from the 'l_name' field of 'struct + link_map'. + - 'lm' with address of 'struct link_map' used for TLS (Thread Local + Storage) access. + - 'l_addr', the displacement as read from the field 'l_addr' of + 'struct link_map'. For prelinked libraries this is not an absolute + memory address. It is a displacement of absolute memory address + against address the file was prelinked to during the library load. + - 'l_ld', which is memory address of the 'PT_DYNAMIC' segment + - 'lmid', which is an identifier for a linker namespace, such as the + memory address of the 'r_debug' object that contains this + namespace's load map or the namespace identifier returned by + 'dlinfo (3)'. + + Additionally the single 'main-lm' attribute specifies address of +'struct link_map' used for the main executable. This parameter is used +for TLS access and its presence is optional. + + GDB must be linked with the Expat library to support XML SVR4 library +lists. *Note Expat::. + + A simple memory map, with two loaded libraries (which do not use +prelink), looks like this: + + + + + + + The format of an SVR4 library list is described by this DTD: + + + + + + + + + + + + + +File: gdb.info, Node: Memory Map Format, Next: Thread List Format, Prev: Library List Format for SVR4 Targets, Up: Remote Protocol + +E.17 Memory Map Format +====================== + +To be able to write into flash memory, GDB needs to obtain a memory map +from the target. This section describes the format of the memory map. + + The memory map is obtained using the 'qXfer:memory-map:read' (*note +qXfer memory map read::) packet and is an XML document that lists memory +regions. + + GDB must be linked with the Expat library to support XML memory maps. +*Note Expat::. + + The top-level structure of the document is shown below: + + + + + region... + + + Each region can be either: + + * A region of RAM starting at ADDR and extending for LENGTH bytes + from there: + + + + * A region of read-only memory: + + + + * A region of flash memory, with erasure blocks BLOCKSIZE bytes in + length: + + + BLOCKSIZE + + + Regions must not overlap. GDB assumes that areas of memory not +covered by the memory map are RAM, and uses the ordinary 'M' and 'X' +packets to write to addresses in such ranges. + + The formal DTD for memory map format is given below: + + + + + + + + + + + + + + + + + +File: gdb.info, Node: Thread List Format, Next: Traceframe Info Format, Prev: Memory Map Format, Up: Remote Protocol + +E.18 Thread List Format +======================= + +To efficiently update the list of threads and their attributes, GDB +issues the 'qXfer:threads:read' packet (*note qXfer threads read::) and +obtains the XML document with the following structure: + + + + + ... description ... + + + + Each 'thread' element must have the 'id' attribute that identifies +the thread (*note thread-id syntax::). The 'core' attribute, if +present, specifies which processor core the thread was last executing +on. The 'name' attribute, if present, specifies the human-readable name +of the thread. The content of the of 'thread' element is interpreted as +human-readable auxiliary information. The 'handle' attribute, if +present, is a hex encoded representation of the thread handle. + + +File: gdb.info, Node: Traceframe Info Format, Next: Branch Trace Format, Prev: Thread List Format, Up: Remote Protocol + +E.19 Traceframe Info Format +=========================== + +To be able to know which objects in the inferior can be examined when +inspecting a tracepoint hit, GDB needs to obtain the list of memory +ranges, registers and trace state variables that have been collected in +a traceframe. + + This list is obtained using the 'qXfer:traceframe-info:read' (*note +qXfer traceframe info read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + Each traceframe block can be either: + + * A region of collected memory starting at ADDR and extending for + LENGTH bytes from there: + + + + * A block indicating trace state variable numbered NUMBER has been + collected: + + + + The formal DTD for the traceframe info format is given below: + + + + + + + + + + +File: gdb.info, Node: Branch Trace Format, Next: Branch Trace Configuration Format, Prev: Traceframe Info Format, Up: Remote Protocol + +E.20 Branch Trace Format +======================== + +In order to display the branch trace of an inferior thread, GDB needs to +obtain the list of branches. This list is represented as list of +sequential code blocks that are connected via branches. The code in +each block has been executed sequentially. + + This list is obtained using the 'qXfer:btrace:read' (*note qXfer +btrace read::) packet and is an XML document. + + GDB must be linked with the Expat library to support XML traceframe +info discovery. *Note Expat::. + + The top-level structure of the document is shown below: + + + + + block... + + + * A block of sequentially executed instructions starting at BEGIN and + ending at END: + + + + The formal DTD for the branch trace format is given below: + + + + + + + + + + + + + + + + + +File: gdb.info, Node: Branch Trace Configuration Format, Prev: Branch Trace Format, Up: Remote Protocol + +E.21 Branch Trace Configuration Format +====================================== + +For each inferior thread, GDB can obtain the branch trace configuration +using the 'qXfer:btrace-conf:read' (*note qXfer btrace-conf read::) +packet. + + The configuration describes the branch trace format and configuration +settings for that format. The following information is described: + +'bts' + This thread uses the "Branch Trace Store" (BTS) format. + 'size' + The size of the BTS ring buffer in bytes. +'pt' + This thread uses the "Intel Processor Trace" (Intel PT) format. + 'size' + The size of the Intel PT ring buffer in bytes. + + GDB must be linked with the Expat library to support XML branch trace +configuration discovery. *Note Expat::. + + The formal DTD for the branch trace configuration format is given +below: + + + + + + + + + + + + + +File: gdb.info, Node: Agent Expressions, Next: Target Descriptions, Prev: Remote Protocol, Up: Top + +Appendix F The GDB Agent Expression Mechanism +********************************************* + +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn anything +helpful about its behavior. If the program's correctness depends on its +real-time behavior, delays introduced by a debugger might cause the +program to fail, even when the code itself is correct. It is useful to +be able to observe the program's behavior without interrupting it. + + Using GDB's 'trace' and 'collect' commands, the user can specify +locations in the program, and arbitrary expressions to evaluate when +those locations are reached. Later, using the 'tfind' command, she can +examine the values those expressions had when the program hit the trace +points. The expressions may also denote objects in memory -- structures +or arrays, for example -- whose values GDB should record; while visiting +a particular tracepoint, the user may inspect those objects as if they +were in memory at that moment. However, because GDB records these +values without interacting with the user, it can do so quickly and +unobtrusively, hopefully not disturbing the program's behavior. + + When GDB is debugging a remote target, the GDB "agent" code running +on the target computes the values of the expressions itself. To avoid +having a full symbolic expression evaluator on the agent, GDB translates +expressions in the source language into a simpler bytecode language, and +then sends the bytecode to the agent; the agent then executes the +bytecode, and records the values for GDB to retrieve later. + + The bytecode language is simple; there are forty-odd opcodes, the +bulk of which are the usual vocabulary of C operands (addition, +subtraction, shifts, and so on) and various sizes of literals and memory +reference operations. The bytecode interpreter operates strictly on +machine-level values -- various sizes of integers and floating point +numbers -- and requires no information about types or symbols; thus, the +interpreter's internal data structures are simple, and each bytecode +requires only a few native machine instructions to implement it. The +interpreter is small, and strict limits on the memory and time required +to evaluate an expression are easy to determine, making it suitable for +use by the debugging agent in real-time applications. + +* Menu: + +* General Bytecode Design:: Overview of the interpreter. +* Bytecode Descriptions:: What each one does. +* Using Agent Expressions:: How agent expressions fit into the big picture. +* Varying Target Capabilities:: How to discover what the target can do. +* Rationale:: Why we did it this way. + + +File: gdb.info, Node: General Bytecode Design, Next: Bytecode Descriptions, Up: Agent Expressions + +F.1 General Bytecode Design +=========================== + +The agent represents bytecode expressions as an array of bytes. Each +instruction is one byte long (thus the term "bytecode"). Some +instructions are followed by operand bytes; for example, the 'goto' +instruction is followed by a destination for the jump. + + The bytecode interpreter is a stack-based machine; most instructions +pop their operands off the stack, perform some operation, and push the +result back on the stack for the next instruction to consume. Each +element of the stack may contain either a integer or a floating point +value; these values are as many bits wide as the largest integer that +can be directly manipulated in the source language. Stack elements +carry no record of their type; bytecode could push a value as an +integer, then pop it as a floating point value. However, GDB will not +generate code which does this. In C, one might define the type of a +stack element as follows: + union agent_val { + LONGEST l; + DOUBLEST d; + }; +where 'LONGEST' and 'DOUBLEST' are 'typedef' names for the largest +integer and floating point types on the machine. + + By the time the bytecode interpreter reaches the end of the +expression, the value of the expression should be the only value left on +the stack. For tracing applications, 'trace' bytecodes in the +expression will have recorded the necessary data, and the value on the +stack may be discarded. For other applications, like conditional +breakpoints, the value may be useful. + + Separate from the stack, the interpreter has two registers: +'pc' + The address of the next bytecode to execute. + +'start' + The address of the start of the bytecode expression, necessary for + interpreting the 'goto' and 'if_goto' instructions. + +Neither of these registers is directly visible to the bytecode language +itself, but they are useful for defining the meanings of the bytecode +operations. + + There are no instructions to perform side effects on the running +program, or call the program's functions; we assume that these +expressions are only used for unobtrusive debugging, not for patching +the running code. + + Most bytecode instructions do not distinguish between the various +sizes of values, and operate on full-width values; the upper bits of the +values are simply ignored, since they do not usually make a difference +to the value computed. The exceptions to this rule are: + +memory reference instructions ('ref'N) + There are distinct instructions to fetch different word sizes from + memory. Once on the stack, however, the values are treated as + full-size integers. They may need to be sign-extended; the 'ext' + instruction exists for this purpose. + +the sign-extension instruction ('ext' N) + These clearly need to know which portion of their operand is to be + extended to occupy the full length of the word. + + If the interpreter is unable to evaluate an expression completely for +some reason (a memory location is inaccessible, or a divisor is zero, +for example), we say that interpretation "terminates with an error". +This means that the problem is reported back to the interpreter's caller +in some helpful way. In general, code using agent expressions should +assume that they may attempt to divide by zero, fetch arbitrary memory +locations, and misbehave in other ways. + + Even complicated C expressions compile to a few bytecode +instructions; for example, the expression 'x + y * z' would typically +produce code like the following, assuming that 'x' and 'y' live in +registers, and 'z' is a global variable holding a 32-bit 'int': + reg 1 + reg 2 + const32 address of z + ref32 + ext 32 + mul + add + end + + In detail, these mean: + +'reg 1' + Push the value of register 1 (presumably holding 'x') onto the + stack. + +'reg 2' + Push the value of register 2 (holding 'y'). + +'const32 address of z' + Push the address of 'z' onto the stack. + +'ref32' + Fetch a 32-bit word from the address at the top of the stack; + replace the address on the stack with the value. Thus, we replace + the address of 'z' with 'z''s value. + +'ext 32' + Sign-extend the value on the top of the stack from 32 bits to full + length. This is necessary because 'z' is a signed integer. + +'mul' + Pop the top two numbers on the stack, multiply them, and push their + product. Now the top of the stack contains the value of the + expression 'y * z'. + +'add' + Pop the top two numbers, add them, and push the sum. Now the top + of the stack contains the value of 'x + y * z'. + +'end' + Stop executing; the value left on the stack top is the value to be + recorded. + + +File: gdb.info, Node: Bytecode Descriptions, Next: Using Agent Expressions, Prev: General Bytecode Design, Up: Agent Expressions + +F.2 Bytecode Descriptions +========================= + +Each bytecode description has the following form: + +'add' (0x02): A B => A+B + + Pop the top two stack items, A and B, as integers; push their sum, + as an integer. + + In this example, 'add' is the name of the bytecode, and '(0x02)' is +the one-byte value used to encode the bytecode, in hexadecimal. The +phrase "A B => A+B" shows the stack before and after the bytecode +executes. Beforehand, the stack must contain at least two values, A and +B; since the top of the stack is to the right, B is on the top of the +stack, and A is underneath it. After execution, the bytecode will have +popped A and B from the stack, and replaced them with a single value, +A+B. There may be other values on the stack below those shown, but the +bytecode affects only those shown. + + Here is another example: + +'const8' (0x22) N: => N + Push the 8-bit integer constant N on the stack, without sign + extension. + + In this example, the bytecode 'const8' takes an operand N directly +from the bytecode stream; the operand follows the 'const8' bytecode +itself. We write any such operands immediately after the name of the +bytecode, before the colon, and describe the exact encoding of the +operand in the bytecode stream in the body of the bytecode description. + + For the 'const8' bytecode, there are no stack items given before the +=>; this simply means that the bytecode consumes no values from the +stack. If a bytecode consumes no values, or produces no values, the +list on either side of the => may be empty. + + If a value is written as A, B, or N, then the bytecode treats it as +an integer. If a value is written is ADDR, then the bytecode treats it +as an address. + + We do not fully describe the floating point operations here; although +this design can be extended in a clean way to handle floating point +values, they are not of immediate interest to the customer, so we avoid +describing them, to save time. + +'float' (0x01): => + + Prefix for floating-point bytecodes. Not implemented yet. + +'add' (0x02): A B => A+B + Pop two integers from the stack, and push their sum, as an integer. + +'sub' (0x03): A B => A-B + Pop two integers from the stack, subtract the top value from the + next-to-top value, and push the difference. + +'mul' (0x04): A B => A*B + Pop two integers from the stack, multiply them, and push the + product on the stack. Note that, when one multiplies two N-bit + numbers yielding another N-bit number, it is irrelevant whether the + numbers are signed or not; the results are the same. + +'div_signed' (0x05): A B => A/B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'div_unsigned' (0x06): A B => A/B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the quotient. If the divisor is + zero, terminate with an error. + +'rem_signed' (0x07): A B => A MODULO B + Pop two signed integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'rem_unsigned' (0x08): A B => A MODULO B + Pop two unsigned integers from the stack; divide the next-to-top + value by the top value, and push the remainder. If the divisor is + zero, terminate with an error. + +'lsh' (0x09): A B => A< '(signed)'A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting copies + of the top bit at the high end, and push the result. + +'rsh_unsigned' (0x0b): A B => A>>B + Pop two integers from the stack; let A be the next-to-top value, + and B be the top value. Shift A right by B bits, inserting zero + bits at the high end, and push the result. + +'log_not' (0x0e): A => !A + Pop an integer from the stack; if it is zero, push the value one; + otherwise, push the value zero. + +'bit_and' (0x0f): A B => A&B + Pop two integers from the stack, and push their bitwise 'and'. + +'bit_or' (0x10): A B => A|B + Pop two integers from the stack, and push their bitwise 'or'. + +'bit_xor' (0x11): A B => A^B + Pop two integers from the stack, and push their bitwise + exclusive-'or'. + +'bit_not' (0x12): A => ~A + Pop an integer from the stack, and push its bitwise complement. + +'equal' (0x13): A B => A=B + Pop two integers from the stack; if they are equal, push the value + one; otherwise, push the value zero. + +'less_signed' (0x14): A B => A A A, sign-extended from N bits + Pop an unsigned value from the stack; treating it as an N-bit + twos-complement value, extend it to full length. This means that + all bits to the left of bit N-1 (where the least significant bit is + bit 0) are set to the value of bit N-1. Note that N may be larger + than or equal to the width of the stack elements of the bytecode + engine; in this case, the bytecode should have no effect. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'ext' bytecode. + +'zero_ext' (0x2a) N: A => A, zero-extended from N bits + Pop an unsigned value from the stack; zero all but the bottom N + bits. + + The number of source bits to preserve, N, is encoded as a single + byte unsigned integer following the 'zero_ext' bytecode. + +'ref8' (0x17): ADDR => A +'ref16' (0x18): ADDR => A +'ref32' (0x19): ADDR => A +'ref64' (0x1a): ADDR => A + Pop an address ADDR from the stack. For bytecode 'ref'N, fetch an + N-bit value from ADDR, using the natural target endianness. Push + the fetched value as an unsigned integer. + + Note that ADDR may not be aligned in any particular way; the 'refN' + bytecodes should operate correctly for any address. + + If attempting to access memory at ADDR would cause a processor + exception of some sort, terminate with an error. + +'ref_float' (0x1b): ADDR => D +'ref_double' (0x1c): ADDR => D +'ref_long_double' (0x1d): ADDR => D +'l_to_d' (0x1e): A => D +'d_to_l' (0x1f): D => A + Not implemented yet. + +'dup' (0x28): A => A A + Push another copy of the stack's top element. + +'swap' (0x2b): A B => B A + Exchange the top two items on the stack. + +'pop' (0x29): A => + Discard the top value on the stack. + +'pick' (0x32) N: A ... B => A ... B A + Duplicate an item from the stack and push it on the top of the + stack. N, a single byte, indicates the stack item to copy. If N + is zero, this is the same as 'dup'; if N is one, it copies the item + under the top item, etc. If N exceeds the number of items on the + stack, terminate with an error. + +'rot' (0x33): A B C => C A B + Rotate the top three items on the stack. The top item (c) becomes + the third item, the next-to-top item (b) becomes the top item and + the third item (a) from the top becomes the next-to-top item. + +'if_goto' (0x20) OFFSET: A => + Pop an integer off the stack; if it is non-zero, branch to the + given offset in the bytecode string. Otherwise, continue to the + next instruction in the bytecode stream. In other words, if A is + non-zero, set the 'pc' register to 'start' + OFFSET. Thus, an + offset of zero denotes the beginning of the expression. + + The OFFSET is stored as a sixteen-bit unsigned value, stored + immediately following the 'if_goto' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The offset is not guaranteed to fall at any particular + alignment within the bytecode stream; thus, on machines where + fetching a 16-bit on an unaligned address raises an exception, you + should fetch the offset one byte at a time. + +'goto' (0x21) OFFSET: => + Branch unconditionally to OFFSET; in other words, set the 'pc' + register to 'start' + OFFSET. + + The offset is stored in the same way as for the 'if_goto' bytecode. + +'const8' (0x22) N: => N +'const16' (0x23) N: => N +'const32' (0x24) N: => N +'const64' (0x25) N: => N + Push the integer constant N on the stack, without sign extension. + To produce a small negative value, push a small twos-complement + value, and then sign-extend it using the 'ext' bytecode. + + The constant N is stored in the appropriate number of bytes + following the 'const'B bytecode. The constant N is always stored + most significant byte first, regardless of the target's normal + endianness. The constant is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch N one byte at a time. + +'reg' (0x26) N: => A + Push the value of register number N, without sign extension. The + registers are numbered following GDB's conventions. + + The register number N is encoded as a 16-bit unsigned integer + immediately following the 'reg' bytecode. It is always stored most + significant byte first, regardless of the target's normal + endianness. The register number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'getv' (0x2c) N: => V + Push the value of trace state variable number N, without sign + extension. + + The variable number N is encoded as a 16-bit unsigned integer + immediately following the 'getv' bytecode. It is always stored + most significant byte first, regardless of the target's normal + endianness. The variable number is not guaranteed to fall at any + particular alignment within the bytecode stream; thus, on machines + where fetching a 16-bit on an unaligned address raises an + exception, you should fetch the register number one byte at a time. + +'setv' (0x2d) N: V => V + Set trace state variable number N to the value found on the top of + the stack. The stack is unchanged, so that the value is readily + available if the assignment is part of a larger expression. The + handling of N is as described for 'getv'. + +'trace' (0x0c): ADDR SIZE => + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. + +'trace_quick' (0x0d) SIZE: ADDR => ADDR + Record the contents of the SIZE bytes at ADDR in a trace buffer, + for later retrieval by GDB. SIZE is a single byte unsigned integer + following the 'trace' opcode. + + This bytecode is equivalent to the sequence 'dup const8 SIZE + trace', but we provide it anyway to save space in bytecode strings. + +'trace16' (0x30) SIZE: ADDR => ADDR + Identical to trace_quick, except that SIZE is a 16-bit big-endian + unsigned integer, not a single byte. This should probably have + been named 'trace_quick16', for consistency. + +'tracev' (0x2e) N: => A + Record the value of trace state variable number N in the trace + buffer. The handling of N is as described for 'getv'. + +'tracenz' (0x2f) ADDR SIZE => + Record the bytes at ADDR in a trace buffer, for later retrieval by + GDB. Stop at either the first zero byte, or when SIZE bytes have + been recorded, whichever occurs first. + +'printf' (0x34) NUMARGS STRING => + Do a formatted print, in the style of the C function 'printf'). + The value of NUMARGS is the number of arguments to expect on the + stack, while STRING is the format string, prefixed with a two-byte + length. The last byte of the string must be zero, and is included + in the length. The format string includes escaped sequences just + as it appears in C source, so for instance the format string + '"\t%d\n"' is six characters long, and the output will consist of a + tab character, a decimal number, and a newline. At the top of the + stack, above the values to be printed, this bytecode will pop a + "function" and "channel". If the function is nonzero, then the + target may treat it as a function and call it, passing the channel + as a first argument, as with the C function 'fprintf'. If the + function is zero, then the target may simply call a standard + formatted print function of its choice. In all, this bytecode pops + 2 + NUMARGS stack elements, and pushes nothing. + +'end' (0x27): => + Stop executing bytecode; the result should be the top element of + the stack. If the purpose of the expression was to compute an + lvalue or a range of memory, then the next-to-top of the stack is + the lvalue's address, and the top of the stack is the lvalue's + size, in bytes. + + +File: gdb.info, Node: Using Agent Expressions, Next: Varying Target Capabilities, Prev: Bytecode Descriptions, Up: Agent Expressions + +F.3 Using Agent Expressions +=========================== + +Agent expressions can be used in several different ways by GDB, and the +debugger can generate different bytecode sequences as appropriate. + + One possibility is to do expression evaluation on the target rather +than the host, such as for the conditional of a conditional tracepoint. +In such a case, GDB compiles the source expression into a bytecode +sequence that simply gets values from registers or memory, does +arithmetic, and returns a result. + + Another way to use agent expressions is for tracepoint data +collection. GDB generates a different bytecode sequence for collection; +in addition to bytecodes that do the calculation, GDB adds 'trace' +bytecodes to save the pieces of memory that were used. + + * The user selects trace points in the program's code at which GDB + should collect data. + + * The user specifies expressions to evaluate at each trace point. + These expressions may denote objects in memory, in which case those + objects' contents are recorded as the program runs, or computed + values, in which case the values themselves are recorded. + + * GDB transmits the tracepoints and their associated expressions to + the GDB agent, running on the debugging target. + + * The agent arranges to be notified when a trace point is hit. + + * When execution on the target reaches a trace point, the agent + evaluates the expressions associated with that trace point, and + records the resulting values and memory ranges. + + * Later, when the user selects a given trace event and inspects the + objects and expression values recorded, GDB talks to the agent to + retrieve recorded data as necessary to meet the user's requests. + If the user asks to see an object whose contents have not been + recorded, GDB reports an error. + + +File: gdb.info, Node: Varying Target Capabilities, Next: Rationale, Prev: Using Agent Expressions, Up: Agent Expressions + +F.4 Varying Target Capabilities +=============================== + +Some targets don't support floating-point, and some would rather not +have to deal with 'long long' operations. Also, different targets will +have different stack sizes, and different bytecode buffer lengths. + + Thus, GDB needs a way to ask the target about itself. We haven't +worked out the details yet, but in general, GDB should be able to send +the target a packet asking it to describe itself. The reply should be a +packet whose length is explicit, so we can add new information to the +packet in future revisions of the agent, without confusing old versions +of GDB, and it should contain a version number. It should contain at +least the following information: + + * whether floating point is supported + + * whether 'long long' is supported + + * maximum acceptable size of bytecode stack + + * maximum acceptable length of bytecode expressions + + * which registers are actually available for collection + + * whether the target supports disabled tracepoints + + +File: gdb.info, Node: Rationale, Prev: Varying Target Capabilities, Up: Agent Expressions + +F.5 Rationale +============= + +Some of the design decisions apparent above are arguable. + +What about stack overflow/underflow? + GDB should be able to query the target to discover its stack size. + Given that information, GDB can determine at translation time + whether a given expression will overflow the stack. But this spec + isn't about what kinds of error-checking GDB ought to do. + +Why are you doing everything in LONGEST? + + Speed isn't important, but agent code size is; using LONGEST brings + in a bunch of support code to do things like division, etc. So + this is a serious concern. + + First, note that you don't need different bytecodes for different + operand sizes. You can generate code without _knowing_ how big the + stack elements actually are on the target. If the target only + supports 32-bit ints, and you don't send any 64-bit bytecodes, + everything just works. The observation here is that the MIPS and + the Alpha have only fixed-size registers, and you can still get C's + semantics even though most instructions only operate on full-sized + words. You just need to make sure everything is properly + sign-extended at the right times. So there is no need for 32- and + 64-bit variants of the bytecodes. Just implement everything using + the largest size you support. + + GDB should certainly check to see what sizes the target supports, + so the user can get an error earlier, rather than later. But this + information is not necessary for correctness. + +Why don't you have '>' or '<=' operators? + I want to keep the interpreter small, and we don't need them. We + can combine the 'less_' opcodes with 'log_not', and swap the order + of the operands, yielding all four asymmetrical comparison + operators. For example, '(x <= y)' is '! (x > y)', which is '! (y + < x)'. + +Why do you have 'log_not'? +Why do you have 'ext'? +Why do you have 'zero_ext'? + These are all easily synthesized from other instructions, but I + expect them to be used frequently, and they're simple, so I include + them to keep bytecode strings short. + + 'log_not' is equivalent to 'const8 0 equal'; it's used in half the + relational operators. + + 'ext N' is equivalent to 'const8 S-N lsh const8 S-N rsh_signed', + where S is the size of the stack elements; it follows 'refM' and + REG bytecodes when the value should be signed. See the next + bulleted item. + + 'zero_ext N' is equivalent to 'constM MASK log_and'; it's used + whenever we push the value of a register, because we can't assume + the upper bits of the register aren't garbage. + +Why not have sign-extending variants of the 'ref' operators? + Because that would double the number of 'ref' operators, and we + need the 'ext' bytecode anyway for accessing bitfields. + +Why not have constant-address variants of the 'ref' operators? + Because that would double the number of 'ref' operators again, and + 'const32 ADDRESS ref32' is only one byte longer. + +Why do the 'refN' operators have to support unaligned fetches? + GDB will generate bytecode that fetches multi-byte values at + unaligned addresses whenever the executable's debugging information + tells it to. Furthermore, GDB does not know the value the pointer + will have when GDB generates the bytecode, so it cannot determine + whether a particular fetch will be aligned or not. + + In particular, structure bitfields may be several bytes long, but + follow no alignment rules; members of packed structures are not + necessarily aligned either. + + In general, there are many cases where unaligned references occur + in correct C code, either at the programmer's explicit request, or + at the compiler's discretion. Thus, it is simpler to make the GDB + agent bytecodes work correctly in all circumstances than to make + GDB guess in each case whether the compiler did the usual thing. + +Why are there no side-effecting operators? + Because our current client doesn't want them? That's a cheap + answer. I think the real answer is that I'm afraid of implementing + function calls. We should re-visit this issue after the present + contract is delivered. + +Why aren't the 'goto' ops PC-relative? + The interpreter has the base address around anyway for PC bounds + checking, and it seemed simpler. + +Why is there only one offset size for the 'goto' ops? + Offsets are currently sixteen bits. I'm not happy with this + situation either: + + Suppose we have multiple branch ops with different offset sizes. + As I generate code left-to-right, all my jumps are forward jumps + (there are no loops in expressions), so I never know the target + when I emit the jump opcode. Thus, I have to either always assume + the largest offset size, or do jump relaxation on the code after I + generate it, which seems like a big waste of time. + + I can imagine a reasonable expression being longer than 256 bytes. + I can't imagine one being longer than 64k. Thus, we need 16-bit + offsets. This kind of reasoning is so bogus, but relaxation is + pathetic. + + The other approach would be to generate code right-to-left. Then + I'd always know my offset size. That might be fun. + +Where is the function call bytecode? + + When we add side-effects, we should add this. + +Why does the 'reg' bytecode take a 16-bit register number? + + Intel's IA-64 architecture has 128 general-purpose registers, and + 128 floating-point registers, and I'm sure it has some random + control registers. + +Why do we need 'trace' and 'trace_quick'? + Because GDB needs to record all the memory contents and registers + an expression touches. If the user wants to evaluate an expression + 'x->y->z', the agent must record the values of 'x' and 'x->y' as + well as the value of 'x->y->z'. + +Don't the 'trace' bytecodes make the interpreter less general? + They do mean that the interpreter contains special-purpose code, + but that doesn't mean the interpreter can only be used for that + purpose. If an expression doesn't use the 'trace' bytecodes, they + don't get in its way. + +Why doesn't 'trace_quick' consume its arguments the way everything else does? + In general, you do want your operators to consume their arguments; + it's consistent, and generally reduces the amount of stack + rearrangement necessary. However, 'trace_quick' is a kludge to + save space; it only exists so we needn't write 'dup const8 SIZE + trace' before every memory reference. Therefore, it's okay for it + not to consume its arguments; it's meant for a specific context in + which we know exactly what it should do with the stack. If we're + going to have a kludge, it should be an effective kludge. + +Why does 'trace16' exist? + That opcode was added by the customer that contracted Cygnus for + the data tracing work. I personally think it is unnecessary; + objects that large will be quite rare, so it is okay to use 'dup + const16 SIZE trace' in those cases. + + Whatever we decide to do with 'trace16', we should at least leave + opcode 0x30 reserved, to remain compatible with the customer who + added it. + + +File: gdb.info, Node: Target Descriptions, Next: Operating System Information, Prev: Agent Expressions, Up: Top + +Appendix G Target Descriptions +****************************** + +One of the challenges of using GDB to debug embedded systems is that +there are so many minor variants of each processor architecture in use. +It is common practice for vendors to start with a standard processor +core -- ARM, PowerPC, or MIPS, for example -- and then make changes to +adapt it to a particular market niche. Some architectures have hundreds +of variants, available from dozens of vendors. This leads to a number +of problems: + + * With so many different customized processors, it is difficult for + the GDB maintainers to keep up with the changes. + * Since individual variants may have short lifetimes or limited + audiences, it may not be worthwhile to carry information about + every variant in the GDB source tree. + * When GDB does support the architecture of the embedded system at + hand, the task of finding the correct architecture name to give the + 'set architecture' command can be error-prone. + + To address these problems, the GDB remote protocol allows a target +system to not only identify itself to GDB, but to actually describe its +own features. This lets GDB support processor variants it has never +seen before -- to the extent that the descriptions are accurate, and +that GDB understands them. + + GDB must be linked with the Expat library to support XML target +descriptions. *Note Expat::. + +* Menu: + +* Retrieving Descriptions:: How descriptions are fetched from a target. +* Target Description Format:: The contents of a target description. +* Predefined Target Types:: Standard types available for target + descriptions. +* Enum Target Types:: How to define enum target types. +* Standard Target Features:: Features GDB knows about. + + +File: gdb.info, Node: Retrieving Descriptions, Next: Target Description Format, Up: Target Descriptions + +G.1 Retrieving Descriptions +=========================== + +Target descriptions can be read from the target automatically, or +specified by the user manually. The default behavior is to read the +description from the target. GDB retrieves it via the remote protocol +using 'qXfer' requests (*note qXfer: General Query Packets.). The ANNEX +in the 'qXfer' packet will be 'target.xml'. The contents of the +'target.xml' annex are an XML document, of the form described in *note +Target Description Format::. + + Alternatively, you can specify a file to read for the target +description. If a file is set, the target will not be queried. The +commands to specify a file are: + +'set tdesc filename PATH' + Read the target description from PATH. + +'unset tdesc filename' + Do not read the XML target description from a file. GDB will use + the description supplied by the current target. + +'show tdesc filename' + Show the filename to read for a target description, if any. + + +File: gdb.info, Node: Target Description Format, Next: Predefined Target Types, Prev: Retrieving Descriptions, Up: Target Descriptions + +G.2 Target Description Format +============================= + +A target description annex is an XML (http://www.w3.org/XML/) document +which complies with the Document Type Definition provided in the GDB +sources in 'gdb/features/gdb-target.dtd'. This means you can use +generally available tools like 'xmllint' to check that your feature +descriptions are well-formed and valid. However, to help people +unfamiliar with XML write descriptions for their targets, we also +describe the grammar here. + + Target descriptions can identify the architecture of the remote +target and (for some architectures) provide information about custom +register sets. They can also identify the OS ABI of the remote target. +GDB can use this information to autoconfigure for your target, or to +warn you if you connect to an unsupported target. + + Here is a simple target description: + + + i386:x86-64 + + +This minimal description only says that the target uses the x86-64 +architecture. + + A target description has the following overall form, with [ ] marking +optional elements and ... marking repeatable elements. The elements are +explained further below. + + + + + [ARCHITECTURE] + [OSABI] + [COMPATIBLE] + [FEATURE...] + + +The description is generally insensitive to whitespace and line breaks, +under the usual common-sense rules. The XML version declaration and +document type declaration can generally be omitted (GDB does not require +them), but specifying them may be useful for XML validation tools. The +'version' attribute for '' may also be omitted, but we recommend +including it; if future versions of GDB use an incompatible revision of +'gdb-target.dtd', they will detect and report the version mismatch. + +G.2.1 Inclusion +--------------- + +It can sometimes be valuable to split a target description up into +several different annexes, either for organizational purposes, or to +share files between different possible target descriptions. You can +divide a description into multiple files by replacing any element of the +target description with an inclusion directive of the form: + + + +When GDB encounters an element of this form, it will retrieve the named +XML DOCUMENT, and replace the inclusion directive with the contents of +that document. If the current description was read using 'qXfer', then +so will be the included document; DOCUMENT will be interpreted as the +name of an annex. If the current description was read from a file, GDB +will look for DOCUMENT as a file in the same directory where it found +the original description. + +G.2.2 Architecture +------------------ + +An '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + +G.2.3 OS ABI +------------ + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + An '' element has this form: + + ABI-NAME + + ABI-NAME is an OS ABI name from the same selection accepted by +'set osabi' (*note Configuring the Current ABI: ABI.). + +G.2.4 Compatible Architecture +----------------------------- + +This optional field was introduced in GDB version 7.0. Previous +versions of GDB ignore it. + + A '' element has this form: + + ARCH + + ARCH is one of the architectures from the set accepted by 'set +architecture' (*note Specifying a Debugging Target: Targets.). + + A '' element is used to specify that the target is able +to run binaries in some other than the main target architecture given by +the '' element. For example, on the Cell Broadband +Engine, the main architecture is 'powerpc:common' or 'powerpc:common64', +but the system is able to run binaries in the 'spu' architecture as +well. The way to describe this capability with '' is as +follows: + + powerpc:common + spu + +G.2.5 Features +-------------- + +Each '' describes some logical portion of the target system. +Features are currently used to describe available CPU registers and the +types of their contents. A '' element has this form: + + + [TYPE...] + REG... + + +Each feature's name should be unique within the description. The name +of a feature does not matter unless GDB has some special knowledge of +the contents of that feature; if it does, the feature should have its +standard name. *Note Standard Target Features::. + +G.2.6 Types +----------- + +Any register's value is a collection of bits which GDB must interpret. +The default interpretation is a two's complement integer, but other +types can be requested by name in the register description. Some +predefined types are provided by GDB (*note Predefined Target Types::), +and the description can define additional composite and enum types. + + Each type element must have an 'id' attribute, which gives a unique +(within the containing '') name to the type. Types must be +defined before they are used. + + Some targets offer vector registers, which can be treated as arrays +of scalar elements. These types are written as '' elements, +specifying the array element type, TYPE, and the number of elements, +COUNT: + + + + If a register's value is usefully viewed in multiple ways, define it +with a union type containing the useful representations. The '' +element contains one or more '' elements, each of which has a +NAME and a TYPE: + + + + ... + + + If a register's value is composed from several separate values, +define it with either a structure type or a flags type. A flags type +may only contain bitfields. A structure type may either contain only +bitfields or contain no bitfields. If the value contains only +bitfields, its total size in bytes must be specified. + + Non-bitfield values have a NAME and TYPE. + + + + ... + + + Both NAME and TYPE values are required. No implicit padding is +added. + + Bitfield values have a NAME, START, END and TYPE. + + + + ... + + + + + ... + + + The NAME value is required. Bitfield values may be named with the +empty string, '""', in which case the field is "filler" and its value is +not printed. Not all bits need to be specified, so "filler" fields are +optional. + + The START and END values are required, and TYPE is optional. The +field's START must be less than or equal to its END, and zero represents +the least significant bit. + + The default value of TYPE is 'bool' for single bit fields, and an +unsigned integer otherwise. + + Which to choose? Structures or flags? + + Registers defined with 'flags' have these advantages over defining +them with 'struct': + + * Arithmetic may be performed on them as if they were integers. + * They are printed in a more readable fashion. + + Registers defined with 'struct' have one advantage over defining them +with 'flags': + + * One can fetch individual fields like in 'C'. + + (gdb) print $my_struct_reg.field3 + $1 = 42 + +G.2.7 Registers +--------------- + +Each register is represented as an element with this form: + + + +The components are as follows: + +NAME + The register's name; it must be unique within the target + description. + +BITSIZE + The register's size, in bits. + +REGNUM + The register's number. If omitted, a register's number is one + greater than that of the previous register (either in the current + feature or in a preceding feature); the first register in the + target description defaults to zero. This register number is used + to read or write the register; e.g. it is used in the remote 'p' + and 'P' packets, and registers appear in the 'g' and 'G' packets in + order of increasing register number. + +SAVE-RESTORE + Whether the register should be preserved across inferior function + calls; this must be either 'yes' or 'no'. The default is 'yes', + which is appropriate for most registers except for some system + control registers; this is not related to the target's ABI. + +TYPE + The type of the register. It may be a predefined type, a type + defined in the current feature, or one of the special types 'int' + and 'float'. 'int' is an integer type of the correct size for + BITSIZE, and 'float' is a floating point type (in the + architecture's normal floating point format) of the correct size + for BITSIZE. The default is 'int'. + +GROUP + The register group to which this register belongs. It can be one + of the standard register groups 'general', 'float', 'vector' or an + arbitrary string. Group names should be limited to alphanumeric + characters. If a group name is made up of multiple words the words + may be separated by hyphens; e.g. 'special-group' or + 'ultra-special-group'. If no GROUP is specified, GDB will not + display the register in 'info registers'. + + +File: gdb.info, Node: Predefined Target Types, Next: Enum Target Types, Prev: Target Description Format, Up: Target Descriptions + +G.3 Predefined Target Types +=========================== + +Type definitions in the self-description can build up composite types +from basic building blocks, but can not define fundamental types. +Instead, standard identifiers are provided by GDB for the fundamental +types. The currently supported types are: + +'bool' + Boolean type, occupying a single bit. + +'int8' +'int16' +'int24' +'int32' +'int64' +'int128' + Signed integer types holding the specified number of bits. + +'uint8' +'uint16' +'uint24' +'uint32' +'uint64' +'uint128' + Unsigned integer types holding the specified number of bits. + +'code_ptr' +'data_ptr' + Pointers to unspecified code and data. The program counter and any + dedicated return address register may be marked as code pointers; + printing a code pointer converts it into a symbolic address. The + stack pointer and any dedicated address registers may be marked as + data pointers. + +'ieee_half' + Half precision IEEE floating point. + +'ieee_single' + Single precision IEEE floating point. + +'ieee_double' + Double precision IEEE floating point. + +'bfloat16' + The 16-bit "brain floating point" format used e.g. by x86 and ARM. + +'arm_fpa_ext' + The 12-byte extended precision format used by ARM FPA registers. + +'i387_ext' + The 10-byte extended precision format used by x87 registers. + +'i386_eflags' + 32bit EFLAGS register used by x86. + +'i386_mxcsr' + 32bit MXCSR register used by x86. + + +File: gdb.info, Node: Enum Target Types, Next: Standard Target Features, Prev: Predefined Target Types, Up: Target Descriptions + +G.4 Enum Target Types +===================== + +Enum target types are useful in 'struct' and 'flags' register +descriptions. *Note Target Description Format::. + + Enum types have a name, size and a list of name/value pairs. + + + + ... + + + Enums must be defined before they are used. + + + + + + + + + + + + Given that description, a value of 3 for the 'flags' register would +be printed as: + + (gdb) info register flags + flags 0x3 [ X LEVEL=high ] + + +File: gdb.info, Node: Standard Target Features, Prev: Enum Target Types, Up: Target Descriptions + +G.5 Standard Target Features +============================ + +A target description must contain either no registers or all the +target's registers. If the description contains no registers, then GDB +will assume a default register layout, selected based on the +architecture. If the description contains any registers, the default +layout will not be used; the standard registers must be described in the +target description, in such a way that GDB can recognize them. + + This is accomplished by giving specific names to feature elements +which contain standard registers. GDB will look for features with those +names and verify that they contain the expected registers; if any known +feature is missing required registers, or if any required feature is +missing, GDB will reject the target description. You can add additional +registers to any of the standard features -- GDB will display them just +as if they were added to an unrecognized feature. + + This section lists the known features and their expected contents. +Sample XML documents for these features are included in the GDB source +tree, in the directory 'gdb/features'. + + Names recognized by GDB should include the name of the company or +organization which selected the name, and the overall architecture to +which the feature applies; so e.g. the feature containing ARM core +registers is named 'org.gnu.gdb.arm.core'. + + The names of registers are not case sensitive for the purpose of +recognizing standard features, but GDB will only display registers using +the capitalization used in the description. + +* Menu: + +* AArch64 Features:: +* ARC Features:: +* ARM Features:: +* i386 Features:: +* LoongArch Features:: +* MicroBlaze Features:: +* MIPS Features:: +* M68K Features:: +* NDS32 Features:: +* OpenRISC 1000 Features:: +* PowerPC Features:: +* RISC-V Features:: +* RX Features:: +* S/390 and System z Features:: +* Sparc Features:: +* TIC6x Features:: + + +File: gdb.info, Node: AArch64 Features, Next: ARC Features, Up: Standard Target Features + +G.5.1 AArch64 Features +---------------------- + +G.5.1.1 AArch64 core registers feature +...................................... + +The 'org.gnu.gdb.aarch64.core' feature is required for AArch64 targets. +It must contain the following: + + - 'x0' through 'x30', the general purpose registers, with size of 64 + bits. Register 'x30' is also known as the "link register", or + 'lr'. + - 'sp', the stack pointer register or 'x31'. It is 64 bits in size + and has a type of 'data_ptr'. + - 'pc', the program counter register. It is 64 bits in size and has + a type of 'code_ptr'. + - 'cpsr', the current program status register. It is 32 bits in size + and has a custom flags type. + + The semantics of the individual flags and fields in 'cpsr' can change +as new architectural features are added. The current layout can be +found in the aarch64-core.xml file. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.1.2 AArch64 floating-point registers feature +................................................ + +The 'org.gnu.gdb.aarch64.fpu' feature is optional. If present, it must +contain the following registers: + + - 'v0' through 'v31', the vector registers with size of 128 bits. + The type is a custom vector type. + - 'fpsr', the floating-point status register. It is 32 bits in size + and has a custom flags type. + - 'fpcr', the floating-point control register. It is 32 bits in size + and has a custom flags type. + + The semantics of the individual flags and fields in 'fpsr' and 'fpcr' +can change as new architectural features are added. + + The types for the vector registers, 'fpsr' and 'fpcr' registers can +be found in the aarch64-fpu.xml file. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.1.3 AArch64 SVE registers feature +..................................... + +The 'org.gnu.gdb.aarch64.sve' feature is optional. If present, it means +the target supports the Scalable Vector Extension and must contain the +following registers: + + - 'z0' through 'z31', the scalable vector registers. Their sizes are + variable and a multiple of 128 bits up to a maximum of 2048 bit. + Their type is a custom union type that helps visualize different + sizes of sub-vectors. + - 'fpsr', the floating-point status register. It is 32 bits in size + and has a custom flags type. + - 'fpcr', the floating-point control register. It is 32 bits in size + and has a custom flags type. + - 'p0' through 'p15', the predicate registers. Their sizes are + variable, based on the current vector length, and a multiple of 16 + bits. Their types are a custom union to help visualize + sub-elements. + - 'ffr', the First Fault register. It has a variable size based on + the current vector length and is a multiple of 16 bits. The type + is the same as the predicate registers. + - 'vg', the vector granule. It represents the number of 64 bits + chunks in a 'z' register. It is closely associated with the + current vector length. It has a type of 'int'. + + When GDB sees the SVE feature, it will assume the Scalable Vector +Extension is supported, and will adjust the sizes of the 'z', 'p' and +'ffr' registers accordingly, based on the value of 'vg'. + + GDB will also create pseudo-registers equivalent to the 'v' vector +registers from the 'org.gnu.gdb.aarch64.fpu' feature. + + The first 128 bits of the 'z' registers overlap the 128 bits of the +'v' registers, so changing one will trigger a change to the other. + + For the types of the 'z', 'p' and 'ffr' registers, please check the +aarch64-sve.c file. No XML file is available for this feature because +it is dynamically generated based on the current vector length. + + The semantics of the individual flags and fields in 'fpsr' and 'fpcr' +can change as new architectural features are added. + + The types for the 'fpsr' and 'fpcr' registers can be found in the +aarch64-sve.c file, and should match what is described in +aarch64-fpu.xml. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.1.4 AArch64 Pointer Authentication registers feature +........................................................ + +The 'org.gnu.gdb.aarch64.pauth' optional feature was introduced so GDB +could detect support for the Pointer Authentication extension. If +present, it must contain one of two possible register sets. + + Pointer Authentication masks for user-mode: + + - 'pauth_dmask', the user-mode pointer authentication mask for data + pointers. It is 64 bits in size. + - 'pauth_cmask', the user-mode pointer authentication mask for code + pointers. It is 64 bits in size. + + Pointer Authentication masks for user-mode and kernel-mode: + + - 'pauth_dmask', the user-mode pointer authentication mask for data + pointers. It is 64 bits in size. + - 'pauth_cmask', the user-mode pointer authentication mask for code + pointers. It is 64 bits in size. + - 'pauth_dmask_high', the kernel-mode pointer authentication mask for + data pointers. It is 64 bits in size. + - 'pauth_cmask_high', the kernel-mode pointer authentication mask for + code pointers. It is 64 bits in size. + + If GDB sees any of the two sets of registers in this feature, it will +assume the target is capable of signing pointers. If so, GDB will +decorate backtraces with a '[PAC]' marker alongside a function that has +a signed link register value that needs to be unmasked/decoded. + + GDB will also use the masks to remove non-address bits from pointers. + + Extra registers are allowed in this feature, but they will not affect +GDB. + + Please note the 'org.gnu.gdb.aarch64.pauth' feature string is +deprecated and must only be used for backwards compatibility with older +releases of GDB and 'gdbserver'. Targets that support Pointer +Authentication must advertise such capability by using the +'org.gnu.gdb.aarch64.pauth_v2' feature string instead. + + The 'org.gnu.gdb.aarch64.pauth_v2' feature has the exact same +contents as feature 'org.gnu.gdb.aarch64.pauth'. + + The reason for having feature 'org.gnu.gdb.aarch64.pauth_v2' is a bug +in previous versions of GDB (versions 9, 10, 11 and 12). This bug +caused GDB to crash whenever the target reported support for Pointer +Authentication (using feature string 'org.gnu.gdb.aarch64.pauth') and +also reported additional system registers that were not accounted for by +GDB. This is more common when using emulators and on bare-metal +debugging scenarios. + + It can also happen if a newer gdbserver is used with an old GDB that +has the bug. In such a case, the newer gdbserver might report Pointer +Authentication support via the 'org.gnu.gdb.aarch64.pauth' feature +string and also report additional registers the older GDB does not know +about, potentially leading to a crash. + +G.5.1.5 AArch64 TLS registers feature +..................................... + +The 'org.gnu.gdb.aarch64.tls' optional feature was introduced to expose +the TLS registers to GDB. If present, it must contain either one of the +following register sets. + + Only 'tpidr': + + - 'tpidr', the software thread id register. It is 64 bits in size + and has a type of 'data_ptr'. + + Both 'tpidr' and 'tpidr2'. + + - 'tpidr', the software thread id register. It is 64 bits in size + and has a type of 'data_ptr'. + - 'tpidr2', the second software thread id register. It is 64 bits in + size and has a type of 'data_ptr'. It may be used in the future + alongside the Scalable Matrix Extension for a lazy restore scheme. + + If GDB sees this feature, it will attempt to find one of the +variations of the register set. If 'tpidr2' is available, GDB may act +on it to display additional data in the future. + + There is no XML for this feature as the presence of 'tpidr2' is +determined dynamically at runtime. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.1.6 AArch64 MTE registers feature +..................................... + +The 'org.gnu.gdb.aarch64.mte' optional feature was introduced so GDB +could detect support for the Memory Tagging Extension and control memory +tagging settings. If present, this feature must have the following +register: + + - 'tag_ctl', the tag control register. It is 64 bits in size and has + a type of 'uint64'. + + Memory Tagging detection is done via a runtime check though, so the +presence of this feature and register is not enough to enable memory +tagging support. + + This restriction may be lifted in the future. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.1.7 AArch64 SME registers feature +..................................... + +The 'org.gnu.gdb.aarch64.sme' feature is optional. If present, it +should contain registers 'ZA', 'SVG' and 'SVCR'. *Note AArch64 SME::. + + - 'ZA' is a register represented by a vector of SVLxSVL bytes. *Note + svl::. + + - 'SVG' is a 64-bit register containing the value of SVG. *Note + svg::. + + - 'SVCR' is a 64-bit status pseudo-register with two valid bits. Bit + 0 (SM) shows whether the streaming SVE mode is enabled or disabled. + Bit 1 (ZA) shows whether the 'ZA' register state is active (in use) + or not. *Note aarch64 sme svcr::. + + The rest of the unused bits of the 'SVCR' pseudo-register is + undefined and reserved. Such bits should not be used and may be + defined by future extensions of the architecture. + + Extra registers are allowed in this feature, but they will not affect +GDB. + + The 'org.gnu.gdb.aarch64.sme' feature is required when the target +also reports support for the 'org.gnu.gdb.aarch64.sme2' feature. + +G.5.1.8 AArch64 SME2 registers feature +...................................... + +The 'org.gnu.gdb.aarch64.sme2' feature is optional. If present, then +the 'org.gnu.gdb.aarch64.sme' feature must also be present. The +'org.gnu.gdb.aarch64.sme2' feature should contain the following: *Note +AArch64 SME2::. + + - 'ZT0' is a register of 512 bits (64 bytes). It is defined as a + vector of bytes. + + Extra registers are allowed in this feature, but they will not affect +GDB. + + +File: gdb.info, Node: ARC Features, Next: ARM Features, Prev: AArch64 Features, Up: Standard Target Features + +G.5.2 ARC Features +------------------ + +ARC processors are so configurable that even core registers and their +numbers are not predetermined completely. Moreover, _flags_ and _PC_ +registers, which are important to GDB, are not "core" registers in ARC. +Therefore, there are two features that their presence is mandatory: +'org.gnu.gdb.arc.core' and 'org.gnu.gdb.arc.aux'. + + The 'org.gnu.gdb.arc.core' feature is required for all targets. It +must contain registers: + + - 'r0' through 'r25' for normal register file targets. + - 'r0' through 'r3', and 'r10' through 'r15' for reduced register + file targets. + - 'gp', 'fp', 'sp', 'r30'(1), 'blink', 'lp_count', 'pcl'. + + In case of an ARCompact target (ARCv1 ISA), the +'org.gnu.gdb.arc.core' feature may contain registers 'ilink1' and +'ilink2'. While in case of ARC EM and ARC HS targets (ARCv2 ISA), +register 'ilink' may be present. The difference between ARCv1 and ARCv2 +is the naming of registers _29th_ and _30th_. They are called 'ilink1' +and 'ilink2' for ARCv1 and are optional. For ARCv2, they are called +'ilink' and 'r30' and only 'ilink' is optional. The optionality of +'ilink*' registers is because of their inaccessibility during user space +debugging sessions. + + Extension core registers 'r32' through 'r59' are optional and their +existence depends on the configuration. When debugging GNU/Linux +applications, i.e. user space debugging, these core registers are not +available. + + The 'org.gnu.gdb.arc.aux' feature is required for all ARC targets. +Here is the list of registers pertinent to this feature: + + - mandatory: 'pc' and 'status32'. + - optional: 'lp_start', 'lp_end', and 'bta'. + + ---------- Footnotes ---------- + + (1) Not necessary for ARCv1. + + +File: gdb.info, Node: ARM Features, Next: i386 Features, Prev: ARC Features, Up: Standard Target Features + +G.5.3 ARM Features +------------------ + +G.5.3.1 Core register set for non-M-profile +........................................... + +The 'org.gnu.gdb.arm.core' feature is required for non-M-profile ARM +targets. It must contain the following registers: + + - 'r0' through 'r12'. The general purpose registers. They are 32 + bits in size and have a type of 'uint32'. + - 'sp', the stack pointer register, also known as 'r13'. It is 32 + bits in size and has a type of 'data_ptr'. + - 'lr', the link register. It is 32 bits in size. + - 'pc', the program counter register. It is 32 bit in size and of + type 'code_ptr'. + - 'cpsr', the current program status register containing all the + status bits. It is 32 bits in size. Historically this register + was hardwired to number 25, but debugging stubs that report XML do + not need to use this number anymore. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.2 Core register set for M-profile +....................................... + +For M-profile targets (e.g. Cortex-M3), the 'org.gnu.gdb.arm.core' +feature is replaced by 'org.gnu.gdb.arm.m-profile', and it is a required +feature. It must contain the following registers: + + - 'r0' through 'r12', the general purpose registers. They have a + size of 32 bits and a type of 'uint32'. + - 'sp', the stack pointer register, also known as 'r13'. It has a + size of 32 bits and a type of 'data_ptr'. + - 'lr', the link register. It has a size of 32 bits. + - 'pc', the program counter register. It has a size of 32 bits and a + type of 'code_ptr'. + - 'xpsr', the program status register containing all the status bits. + It has a size of 32 bits. Historically this register was hardwired + to number 25, but debugging stubs that report XML do not need to + use this number anymore. + + Upon seeing this feature, GDB will acknowledge that it is dealing +with an M-profile target. This means GDB will use hooks and +configurations that are meaningful to M-profiles. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.3 FPA registers feature (obsolete) +........................................ + +The 'org.gnu.gdb.arm.fpa' feature is obsolete and should not be +advertised by debugging stubs anymore. It used to advertise registers +for the old FPA architecture that has long been discontinued in +toolchains. + + It is kept in GDB for backward compatibility purposes so older +debugging stubs that don't support XML target descriptions still work +correctly. One such example is the KGDB debugging stub from Linux or +BSD kernels. + + The description below is for historical purposes only. This feature +used to contain the following registers: + + - 'f0' through 'f8'. The floating point registers. They are 96 bits + in size and of type 'arm_fpa_ext'. 'f0' is pinned to register + number 16. + - 'fps', the status register. It has a size of 32 bits. + +G.5.3.4 M-profile Vector Extension (MVE) +........................................ + +Also known as Helium, the M-profile Vector Extension is advertised via +the optional 'org.gnu.gdb.arm.m-profile-mve' feature. + + It must contain the following: + + - 'vpr', the vector predication status and control register. It is + 32 bits in size and has a custom flags type. The flags type is + laid out in a way that exposes the 'P0' field from bits 0 to 15, + the 'MASK01' field from bits 16 to 19 and the 'MASK23' field from + bits 20 to 23. + + Bits 24 through 31 are reserved. + + When this feature is available, GDB will synthesize the 'p0' +pseudo-register from 'vpr' contents. + + This feature must only be advertised if the target is M-profile. +Advertising this feature for targets that are not M-profile may cause +GDB to assume the target is M-profile when it isn't. + + If the 'org.gnu.gdb.arm.vfp' feature is available alongside the +'org.gnu.gdb.arm.m-profile-mve' feature, GDB will synthesize the 'q' +pseudo-registers from 'd' register contents. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.5 XScale iwMMXt feature +............................. + +The XScale 'org.gnu.gdb.xscale.iwmmxt' feature is optional. If present, +it must contain the following: + + - 'wR0' through 'wR15', registers with size 64 bits and a custom type + 'iwmmxt_vec64i'. 'iwmmxt_vec64i' is a union of four other types: + 'uint64', a 2-element vector of 'uint32', a 4-element vector of + 'uint16' and a 8-element vector of 'uint8'. + - 'wCGR0' through 'wCGR3', registers with size 32 bits and type + 'int'. + + The following registers are optional: + + - 'wCID', register with size of 32 bits and type 'int'. + - 'wCon', register with size 32 bits and type 'int'. + - 'wCSSF', register with size 32 bits and type 'int'. + - 'wCASF', register with size 32 bit and type 'int'. + + This feature should only be reported if the target is XScale. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.6 Vector Floating-Point (VFP) feature +........................................... + +The 'org.gnu.gdb.arm.vfp' feature is optional. If present, it should +contain one of two possible sets of values depending on whether VFP +version 2 or VFP version 3 is in use. + + For VFP v2: + + - 'd0' through 'd15'. The double-precision registers. They are 64 + bits in size and have type 'ieee_double'. + - 'fpscr', the floating-point status and control register. It has a + size of 32 bits and a type of 'int'. + + For VFP v3: + + - 'd0' through 'd31'. The double-precision registers. They are 64 + bits in size and have type 'ieee_double'. + - 'fpscr', the floating-point status and control register. It has a + size of 32 bits and a type of 'int'. + + If this feature is available, GDB will synthesize the +single-precision floating-point registers from halves of the +double-precision registers as pseudo-registers. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.7 NEON architecture feature +................................. + +The 'org.gnu.gdb.arm.neon' feature is optional. It does not need to +contain registers; it instructs GDB to display the VFP double-precision +registers as vectors and to synthesize the quad-precision registers from +pairs of double-precision registers. If this feature is present, +'org.gnu.gdb.arm.vfp' must also be present and include 32 +double-precision registers. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.8 M-profile Pointer Authentication and Branch Target Identification feature +................................................................................. + +The 'org.gnu.gdb.arm.m-profile-pacbti' feature is optional, and +acknowledges support for the ARMv8.1-m PACBTI extensions. + + This feature doesn't contain any required registers, and it only +serves as a hint to GDB that the debugging stub supports the ARMv8.1-m +PACBTI extensions. + + When GDB sees this feature, it will track return address signing +states and will decorate backtraces using the [PAC] marker, similar to +AArch64's PAC extension. *Note AArch64 PAC::. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.9 M-profile system registers feature +.......................................... + +The 'org.gnu.gdb.arm.m-system' optional feature was introduced as a way +to inform GDB about additional system registers. + + At the moment this feature must contain the following: + + - 'msp', the main stack pointer register. It is 32 bits in size with + type 'data_ptr'. + - 'psp', the process stack pointer register. It is 32 bits in size + with type 'data_ptr'. + + This feature must only be advertised for M-profile targets. When GDB +sees this feature, it will attempt to track the values of 'msp' and +'psp' across frames. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.10 M-profile Security Extensions feature +.............................................. + +The 'org.gnu.gdb.arm.secext' optional feature was introduced so GDB +could better support the switching of stack pointers and secure states +in the Security Extensions. + + At the moment this feature must contain the following: + + - 'msp_ns', the main stack pointer register (non-secure state). It + is 32 bits in size with type 'data_ptr'. + - 'psp_ns', the process stack pointer register (non-secure state). + It is 32 bits in size with type 'data_ptr'. + - 'msp_s', the main stack pointer register (secure state). It is 32 + bits in size with type 'data_ptr'. + - 'psp_s', the process stack pointer register (secure state). It is + 32 bits in size with type 'data_ptr'. + + When GDB sees this feature, it will attempt to track the values of +all 4 stack pointers across secure state transitions, potentially +improving unwinding when applications switch between security states. + + Extra registers are allowed in this feature, but they will not affect +GDB. + +G.5.3.11 TLS registers feature +.............................. + +The optional 'org.gnu.gdb.arm.tls' feature contains TLS registers. + + Currently it contains the following: + + - 'tpidruro', the user read-only thread id register. It is 32 bits + in size and has type 'data_ptr'. + + At the moment GDB looks for this feature, but doesn't do anything +with it other than displaying it. + + Extra registers are allowed in this feature, but they will not affect +GDB. + + +File: gdb.info, Node: i386 Features, Next: LoongArch Features, Prev: ARM Features, Up: Standard Target Features + +G.5.4 i386 Features +------------------- + +The 'org.gnu.gdb.i386.core' feature is required for i386/amd64 targets. +It should describe the following registers: + + - 'eax' through 'edi' plus 'eip' for i386 + - 'rax' through 'r15' plus 'rip' for amd64 + - 'eflags', 'cs', 'ss', 'ds', 'es', 'fs', 'gs' + - 'st0' through 'st7' + - 'fctrl', 'fstat', 'ftag', 'fiseg', 'fioff', 'foseg', 'fooff' and + 'fop' + + The register sets may be different, depending on the target. + + The 'org.gnu.gdb.i386.sse' feature is optional. It should describe +registers: + + - 'xmm0' through 'xmm7' for i386 + - 'xmm0' through 'xmm15' for amd64 + - 'mxcsr' + + The 'org.gnu.gdb.i386.avx' feature is optional and requires the +'org.gnu.gdb.i386.sse' feature. It should describe the upper 128 bits +of YMM registers: + + - 'ymm0h' through 'ymm7h' for i386 + - 'ymm0h' through 'ymm15h' for amd64 + + The 'org.gnu.gdb.i386.linux' feature is optional. It should describe +a single register, 'orig_eax'. + + The 'org.gnu.gdb.i386.segments' feature is optional. It should +describe two system registers: 'fs_base' and 'gs_base'. + + The 'org.gnu.gdb.i386.avx512' feature is optional and requires the +'org.gnu.gdb.i386.avx' feature. It should describe additional XMM +registers: + + - 'xmm16' through 'xmm31', only valid for amd64. + + It should describe the upper 128 bits of additional YMM registers: + + - 'ymm16h' through 'ymm31h', only valid for amd64. + + It should describe the upper 256 bits of ZMM registers: + + - 'zmm0h' through 'zmm7h' for i386. + - 'zmm0h' through 'zmm15h' for amd64. + + It should describe the additional ZMM registers: + + - 'zmm16h' through 'zmm31h', only valid for amd64. + + It should describe the additional 64-bit K registers: + + - 'k0' through 'k7', valid for amd64 and i386. + + The 'org.gnu.gdb.i386.pkeys' feature is optional. It should describe +a single register, 'pkru'. It is a 32-bit register valid for i386 and +amd64. + + +File: gdb.info, Node: LoongArch Features, Next: MicroBlaze Features, Prev: i386 Features, Up: Standard Target Features + +G.5.5 LoongArch Features +------------------------ + +The 'org.gnu.gdb.loongarch.base' feature is required for LoongArch +targets. It should contain the registers 'r0' through 'r31', 'pc', and +'badv'. Either the architectural names ('r0', 'r1', etc) can be used, +or the ABI names ('zero', 'ra', etc). + + The 'org.gnu.gdb.loongarch.fpu' feature is optional. If present, it +should contain registers 'f0' through 'f31', 'fcc', and 'fcsr'. + + +File: gdb.info, Node: MicroBlaze Features, Next: MIPS Features, Prev: LoongArch Features, Up: Standard Target Features + +G.5.6 MicroBlaze Features +------------------------- + +The 'org.gnu.gdb.microblaze.core' feature is required for MicroBlaze +targets. It should contain registers 'r0' through 'r31', 'rpc', 'rmsr', +'rear', 'resr', 'rfsr', 'rbtr', 'rpvr', 'rpvr1' through 'rpvr11', +'redr', 'rpid', 'rzpr', 'rtlbx', 'rtlbsx', 'rtlblo', and 'rtlbhi'. + + The 'org.gnu.gdb.microblaze.stack-protect' feature is optional. If +present, it should contain registers 'rshr' and 'rslr' + + +File: gdb.info, Node: MIPS Features, Next: M68K Features, Prev: MicroBlaze Features, Up: Standard Target Features + +G.5.7 MIPS Features +------------------- + +The 'org.gnu.gdb.mips.cpu' feature is required for MIPS targets. It +should contain registers 'r0' through 'r31', 'lo', 'hi', and 'pc'. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.cp0' feature is also required. It should +contain at least the 'status', 'badvaddr', and 'cause' registers. They +may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.mips.fpu' feature is currently required, though it +may be optional in a future version of GDB. It should contain registers +'f0' through 'f31', 'fcsr', and 'fir'. They may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.dsp' feature is optional. It should contain +registers 'hi1' through 'hi3', 'lo1' through 'lo3', and 'dspctl'. The +'dspctl' register should be 32-bit and the rest may be 32-bit or 64-bit +depending on the target. + + The 'org.gnu.gdb.mips.linux' feature is optional. It should contain +a single register, 'restart', which is used by the Linux kernel to +control restartable syscalls. + + +File: gdb.info, Node: M68K Features, Next: NDS32 Features, Prev: MIPS Features, Up: Standard Target Features + +G.5.8 M68K Features +------------------- + +''org.gnu.gdb.m68k.core'' +''org.gnu.gdb.coldfire.core'' +''org.gnu.gdb.fido.core'' + One of those features must be always present. The feature that is + present determines which flavor of m68k is used. The feature that + is present should contain registers 'd0' through 'd7', 'a0' through + 'a5', 'fp', 'sp', 'ps' and 'pc'. + +''org.gnu.gdb.coldfire.fp'' + This feature is optional. If present, it should contain registers + 'fp0' through 'fp7', 'fpcontrol', 'fpstatus' and 'fpiaddr'. + + Note that, despite the fact that this feature's name says + 'coldfire', it is used to describe any floating point registers. + The size of the registers must match the main m68k flavor; so, for + example, if the primary feature is reported as 'coldfire', then + 64-bit floating point registers are required. + + +File: gdb.info, Node: NDS32 Features, Next: OpenRISC 1000 Features, Prev: M68K Features, Up: Standard Target Features + +G.5.9 NDS32 Features +-------------------- + +The 'org.gnu.gdb.nds32.core' feature is required for NDS32 targets. It +should contain at least registers 'r0' through 'r10', 'r15', 'fp', 'gp', +'lp', 'sp', and 'pc'. + + The 'org.gnu.gdb.nds32.fpu' feature is optional. If present, it +should contain 64-bit double-precision floating-point registers 'fd0' +through _fdN_, which should be 'fd3', 'fd7', 'fd15', or 'fd31' based on +the FPU configuration implemented. + + _Note:_ The first sixteen 64-bit double-precision floating-point +registers are overlapped with the thirty-two 32-bit single-precision +floating-point registers. The 32-bit single-precision registers, if not +being listed explicitly, will be synthesized from halves of the +overlapping 64-bit double-precision registers. Listing 32-bit +single-precision registers explicitly is deprecated, and the support to +it could be totally removed some day. + + +File: gdb.info, Node: OpenRISC 1000 Features, Next: PowerPC Features, Prev: NDS32 Features, Up: Standard Target Features + +G.5.10 Openrisc 1000 Features +----------------------------- + +The 'org.gnu.gdb.or1k.group0' feature is required for OpenRISC 1000 +targets. It should contain the 32 general purpose registers ('r0' +through 'r31'), 'ppc', 'npc' and 'sr'. + + +File: gdb.info, Node: PowerPC Features, Next: RISC-V Features, Prev: OpenRISC 1000 Features, Up: Standard Target Features + +G.5.11 PowerPC Features +----------------------- + +The 'org.gnu.gdb.power.core' feature is required for PowerPC targets. +It should contain registers 'r0' through 'r31', 'pc', 'msr', 'cr', 'lr', +'ctr', and 'xer'. They may be 32-bit or 64-bit depending on the target. + + The 'org.gnu.gdb.power.fpu' feature is optional. It should contain +registers 'f0' through 'f31' and 'fpscr'. + + The 'org.gnu.gdb.power.altivec' feature is optional. It should +contain registers 'vr0' through 'vr31', 'vscr', and 'vrsave'. GDB will +define pseudo-registers 'v0' through 'v31' as aliases for the +corresponding 'vrX' registers. + + The 'org.gnu.gdb.power.vsx' feature is optional. It should contain +registers 'vs0h' through 'vs31h'. GDB will combine these registers with +the floating point registers ('f0' through 'f31') and the altivec +registers ('vr0' through 'vr31') to present the 128-bit wide registers +'vs0' through 'vs63', the set of vector-scalar registers for POWER7. +Therefore, this feature requires both 'org.gnu.gdb.power.fpu' and +'org.gnu.gdb.power.altivec'. + + The 'org.gnu.gdb.power.spe' feature is optional. It should contain +registers 'ev0h' through 'ev31h', 'acc', and 'spefscr'. SPE targets +should provide 32-bit registers in 'org.gnu.gdb.power.core' and provide +the upper halves in 'ev0h' through 'ev31h'. GDB will combine these to +present registers 'ev0' through 'ev31' to the user. + + The 'org.gnu.gdb.power.ppr' feature is optional. It should contain +the 64-bit register 'ppr'. + + The 'org.gnu.gdb.power.dscr' feature is optional. It should contain +the 64-bit register 'dscr'. + + The 'org.gnu.gdb.power.tar' feature is optional. It should contain +the 64-bit register 'tar'. + + The 'org.gnu.gdb.power.ebb' feature is optional. It should contain +registers 'bescr', 'ebbhr' and 'ebbrr', all 64-bit wide. + + The 'org.gnu.gdb.power.linux.pmu' feature is optional. It should +contain registers 'mmcr0', 'mmcr2', 'siar', 'sdar' and 'sier', all +64-bit wide. This is the subset of the isa 2.07 server PMU registers +provided by GNU/Linux. + + The 'org.gnu.gdb.power.htm.spr' feature is optional. It should +contain registers 'tfhar', 'texasr' and 'tfiar', all 64-bit wide. + + The 'org.gnu.gdb.power.htm.core' feature is optional. It should +contain the checkpointed general-purpose registers 'cr0' through 'cr31', +as well as the checkpointed registers 'clr' and 'cctr'. These registers +may all be either 32-bit or 64-bit depending on the target. It should +also contain the checkpointed registers 'ccr' and 'cxer', which should +both be 32-bit wide. + + The 'org.gnu.gdb.power.htm.fpu' feature is optional. It should +contain the checkpointed 64-bit floating-point registers 'cf0' through +'cf31', as well as the checkpointed 64-bit register 'cfpscr'. + + The 'org.gnu.gdb.power.htm.altivec' feature is optional. It should +contain the checkpointed altivec registers 'cvr0' through 'cvr31', all +128-bit wide. It should also contain the checkpointed registers 'cvscr' +and 'cvrsave', both 32-bit wide. + + The 'org.gnu.gdb.power.htm.vsx' feature is optional. It should +contain registers 'cvs0h' through 'cvs31h'. GDB will combine these +registers with the checkpointed floating point registers ('cf0' through +'cf31') and the checkpointed altivec registers ('cvr0' through 'cvr31') +to present the 128-bit wide checkpointed vector-scalar registers 'cvs0' +through 'cvs63'. Therefore, this feature requires both +'org.gnu.gdb.power.htm.altivec' and 'org.gnu.gdb.power.htm.fpu'. + + The 'org.gnu.gdb.power.htm.ppr' feature is optional. It should +contain the 64-bit checkpointed register 'cppr'. + + The 'org.gnu.gdb.power.htm.dscr' feature is optional. It should +contain the 64-bit checkpointed register 'cdscr'. + + The 'org.gnu.gdb.power.htm.tar' feature is optional. It should +contain the 64-bit checkpointed register 'ctar'. + + +File: gdb.info, Node: RISC-V Features, Next: RX Features, Prev: PowerPC Features, Up: Standard Target Features + +G.5.12 RISC-V Features +---------------------- + +The 'org.gnu.gdb.riscv.cpu' feature is required for RISC-V targets. It +should contain the registers 'x0' through 'x31', and 'pc'. Either the +architectural names ('x0', 'x1', etc) can be used, or the ABI names +('zero', 'ra', etc). + + The 'org.gnu.gdb.riscv.fpu' feature is optional. If present, it +should contain registers 'f0' through 'f31', 'fflags', 'frm', and +'fcsr'. As with the cpu feature, either the architectural register +names, or the ABI names can be used. + + The 'org.gnu.gdb.riscv.virtual' feature is optional. If present, it +should contain registers that are not backed by real registers on the +target, but are instead virtual, where the register value is derived +from other target state. In many ways these are like GDBs +pseudo-registers, except implemented by the target. Currently the only +register expected in this set is the one byte 'priv' register that +contains the target's privilege level in the least significant two bits. + + The 'org.gnu.gdb.riscv.csr' feature is optional. If present, it +should contain all of the target's standard CSRs. Standard CSRs are +those defined in the RISC-V specification documents. There is some +overlap between this feature and the fpu feature; the 'fflags', 'frm', +and 'fcsr' registers could be in either feature. The expectation is +that these registers will be in the fpu feature if the target has +floating point hardware, but can be moved into the csr feature if the +target has the floating point control registers, but no other floating +point hardware. + + The 'org.gnu.gdb.riscv.vector' feature is optional. If present, it +should contain registers 'v0' through 'v31', all of which must be the +same size. + + +File: gdb.info, Node: RX Features, Next: S/390 and System z Features, Prev: RISC-V Features, Up: Standard Target Features + +G.5.13 RX Features +------------------ + +The 'org.gnu.gdb.rx.core' feature is required for RX targets. It should +contain the registers 'r0' through 'r15', 'usp', 'isp', 'psw', 'pc', +'intb', 'bpsw', 'bpc', 'fintv', 'fpsw', and 'acc'. + + +File: gdb.info, Node: S/390 and System z Features, Next: Sparc Features, Prev: RX Features, Up: Standard Target Features + +G.5.14 S/390 and System z Features +---------------------------------- + +The 'org.gnu.gdb.s390.core' feature is required for S/390 and System z +targets. It should contain the PSW and the 16 general registers. In +particular, System z targets should provide the 64-bit registers 'pswm', +'pswa', and 'r0' through 'r15'. S/390 targets should provide the 32-bit +versions of these registers. A System z target that runs in 31-bit +addressing mode should provide 32-bit versions of 'pswm' and 'pswa', as +well as the general register's upper halves 'r0h' through 'r15h', and +their lower halves 'r0l' through 'r15l'. + + The 'org.gnu.gdb.s390.fpr' feature is required. It should contain +the 64-bit registers 'f0' through 'f15', and 'fpc'. + + The 'org.gnu.gdb.s390.acr' feature is required. It should contain +the 32-bit registers 'acr0' through 'acr15'. + + The 'org.gnu.gdb.s390.linux' feature is optional. It should contain +the register 'orig_r2', which is 64-bit wide on System z targets and +32-bit otherwise. In addition, the feature may contain the 'last_break' +register, whose width depends on the addressing mode, as well as the +'system_call' register, which is always 32-bit wide. + + The 'org.gnu.gdb.s390.tdb' feature is optional. It should contain +the 64-bit registers 'tdb0', 'tac', 'tct', 'atia', and 'tr0' through +'tr15'. + + The 'org.gnu.gdb.s390.vx' feature is optional. It should contain +64-bit wide registers 'v0l' through 'v15l', which will be combined by +GDB with the floating point registers 'f0' through 'f15' to present the +128-bit wide vector registers 'v0' through 'v15'. In addition, this +feature should contain the 128-bit wide vector registers 'v16' through +'v31'. + + The 'org.gnu.gdb.s390.gs' feature is optional. It should contain the +64-bit wide guarded-storage-control registers 'gsd', 'gssm', and +'gsepla'. + + The 'org.gnu.gdb.s390.gsbc' feature is optional. It should contain +the 64-bit wide guarded-storage broadcast control registers 'bc_gsd', +'bc_gssm', and 'bc_gsepla'. + + +File: gdb.info, Node: Sparc Features, Next: TIC6x Features, Prev: S/390 and System z Features, Up: Standard Target Features + +G.5.15 Sparc Features +--------------------- + +The 'org.gnu.gdb.sparc.cpu' feature is required for sparc32/sparc64 +targets. It should describe the following registers: + + - 'g0' through 'g7' + - 'o0' through 'o7' + - 'l0' through 'l7' + - 'i0' through 'i7' + + They may be 32-bit or 64-bit depending on the target. + + Also the 'org.gnu.gdb.sparc.fpu' feature is required for +sparc32/sparc64 targets. It should describe the following registers: + + - 'f0' through 'f31' + - 'f32' through 'f62' for sparc64 + + The 'org.gnu.gdb.sparc.cp0' feature is required for sparc32/sparc64 +targets. It should describe the following registers: + + - 'y', 'psr', 'wim', 'tbr', 'pc', 'npc', 'fsr', and 'csr' for sparc32 + - 'pc', 'npc', 'state', 'fsr', 'fprs', and 'y' for sparc64 + + +File: gdb.info, Node: TIC6x Features, Prev: Sparc Features, Up: Standard Target Features + +G.5.16 TMS320C6x Features +------------------------- + +The 'org.gnu.gdb.tic6x.core' feature is required for TMS320C6x targets. +It should contain registers 'A0' through 'A15', registers 'B0' through +'B15', 'CSR' and 'PC'. + + The 'org.gnu.gdb.tic6x.gp' feature is optional. It should contain +registers 'A16' through 'A31' and 'B16' through 'B31'. + + The 'org.gnu.gdb.tic6x.c6xp' feature is optional. It should contain +registers 'TSR', 'ILC' and 'RILC'. + + +File: gdb.info, Node: Operating System Information, Next: Trace File Format, Prev: Target Descriptions, Up: Top + +Appendix H Operating System Information +*************************************** + +Users of GDB often wish to obtain information about the state of the +operating system running on the target--for example the list of +processes, or the list of open files. This section describes the +mechanism that makes it possible. This mechanism is similar to the +target features mechanism (*note Target Descriptions::), but focuses on +a different aspect of target. + + Operating system information is retrieved from the target via the +remote protocol, using 'qXfer' requests (*note qXfer osdata read::). +The object name in the request should be 'osdata', and the ANNEX +identifies the data to be fetched. + +* Menu: + +* Process list:: + + +File: gdb.info, Node: Process list, Up: Operating System Information + +H.1 Process list +================ + +When requesting the process list, the ANNEX field in the 'qXfer' request +should be 'processes'. The returned data is an XML document. The +formal syntax of this document is defined in 'gdb/features/osdata.dtd'. + + An example document is: + + + + + + 1 + root + /sbin/init + 1,2,3 + + + + Each item should include a column whose name is 'pid'. The value of +that column should identify the process on the target. The 'user' and +'command' columns are optional, and will be displayed by GDB. The +'cores' column, if present, should contain a comma-separated list of +cores that this process is running on. Target may provide additional +columns, which GDB currently ignores. + + +File: gdb.info, Node: Trace File Format, Next: Index Section Format, Prev: Operating System Information, Up: Top + +Appendix I Trace File Format +**************************** + +The trace file comes in three parts: a header, a textual description +section, and a trace frame section with binary data. + + The header has the form '\x7fTRACE0\n'. The first byte is '0x7f' so +as to indicate that the file contains binary data, while the '0' is a +version number that may have different values in the future. + + The description section consists of multiple lines of ASCII text +separated by newline characters ('0xa'). The lines may include a +variety of optional descriptive or context-setting information, such as +tracepoint definitions or register set size. GDB will ignore any line +that it does not recognize. An empty line marks the end of this +section. + +'R SIZE' + Specifies the size of a register block in bytes. This is equal to + the size of a 'g' packet payload in the remote protocol. SIZE is + an ascii decimal number. There should be only one such line in a + single trace file. + +'status STATUS' + Trace status. STATUS has the same format as a 'qTStatus' remote + packet reply. There should be only one such line in a single trace + file. + +'tp PAYLOAD' + Tracepoint definition. The PAYLOAD has the same format as + 'qTfP'/'qTsP' remote packet reply payload. A single tracepoint may + take multiple lines of definition, corresponding to the multiple + reply packets. + +'tsv PAYLOAD' + Trace state variable definition. The PAYLOAD has the same format + as 'qTfV'/'qTsV' remote packet reply payload. A single variable + may take multiple lines of definition, corresponding to the + multiple reply packets. + +'tdesc PAYLOAD' + Target description in XML format. The PAYLOAD is a single line of + the XML file. All such lines should be concatenated together to + get the original XML file. This file is in the same format as + 'qXfer' 'features' payload, and corresponds to the main + 'target.xml' file. Includes are not allowed. + + The trace frame section consists of a number of consecutive frames. +Each frame begins with a two-byte tracepoint number, followed by a +four-byte size giving the amount of data in the frame. The data in the +frame consists of a number of blocks, each introduced by a character +indicating its type (at least register, memory, and trace state +variable). The data in this section is raw binary, not a hexadecimal or +other encoding; its endianness matches the target's endianness. + +'R BYTES' + Register block. The number and ordering of bytes matches that of a + 'g' packet in the remote protocol. Note that these are the actual + bytes, in target order, not a hexadecimal encoding. + +'M ADDRESS LENGTH BYTES...' + Memory block. This is a contiguous block of memory, at the 8-byte + address ADDRESS, with a 2-byte length LENGTH, followed by LENGTH + bytes. + +'V NUMBER VALUE' + Trace state variable block. This records the 8-byte signed value + VALUE of trace state variable numbered NUMBER. + + Future enhancements of the trace file format may include additional +types of blocks. + + +File: gdb.info, Node: Index Section Format, Next: Debuginfod, Prev: Trace File Format, Up: Top + +Appendix J '.gdb_index' section format +************************************** + +This section documents the index section that is created by 'save +gdb-index' (*note Index Files::). The index section is DWARF-specific; +some knowledge of DWARF is assumed in this description. + + The mapped index file format is designed to be directly 'mmap'able on +any architecture. In most cases, a datum is represented using a +little-endian 32-bit integer value, called an 'offset_type'. Big endian +machines must byte-swap the values before using them. Exceptions to +this rule are noted. The data is laid out such that alignment is always +respected. + + A mapped index consists of several areas, laid out in order. + + 1. The file header. This is a sequence of values, of 'offset_type' + unless otherwise noted: + + 1. The version number, currently 9. Versions 1, 2 and 3 are + obsolete. Version 4 uses a different hashing function from + versions 5 and 6. Version 6 includes symbols for inlined + functions, whereas versions 4 and 5 do not. Version 7 adds + attributes to the CU indices in the symbol table. Version 8 + specifies that symbols from DWARF type units + ('DW_TAG_type_unit') refer to the type unit's symbol table and + not the compilation unit ('DW_TAG_comp_unit') using the type. + Version 9 adds the name and the language of the main function + to the index. + + GDB will only read version 4, 5, or 6 indices by specifying + 'set use-deprecated-index-sections on'. GDB has a workaround + for potentially broken version 7 indices so it is currently + not flagged as deprecated. + + 2. The offset, from the start of the file, of the CU list. + + 3. The offset, from the start of the file, of the types CU list. + Note that this area can be empty, in which case this offset + will be equal to the next offset. + + 4. The offset, from the start of the file, of the address area. + + 5. The offset, from the start of the file, of the symbol table. + + 6. The offset, from the start of the file, of the shortcut table. + + 7. The offset, from the start of the file, of the constant pool. + + 2. The CU list. This is a sequence of pairs of 64-bit little-endian + values, sorted by the CU offset. The first element in each pair is + the offset of a CU in the '.debug_info' section. The second + element in each pair is the length of that CU. References to a CU + elsewhere in the map are done using a CU index, which is just the + 0-based index into this table. Note that if there are type CUs, + then conceptually CUs and type CUs form a single list for the + purposes of CU indices. + + 3. The types CU list. This is a sequence of triplets of 64-bit + little-endian values. In a triplet, the first value is the CU + offset, the second value is the type offset in the CU, and the + third value is the type signature. The types CU list is not + sorted. + + 4. The address area. The address area consists of a sequence of + address entries. Each address entry has three elements: + + 1. The low address. This is a 64-bit little-endian value. + + 2. The high address. This is a 64-bit little-endian value. Like + 'DW_AT_high_pc', the value is one byte beyond the end. + + 3. The CU index. This is an 'offset_type' value. + + 5. The symbol table. This is an open-addressed hash table. The size + of the hash table is always a power of 2. + + Each slot in the hash table consists of a pair of 'offset_type' + values. The first value is the offset of the symbol's name in the + constant pool. The second value is the offset of the CU vector in + the constant pool. + + If both values are 0, then this slot in the hash table is empty. + This is ok because while 0 is a valid constant pool index, it + cannot be a valid index for both a string and a CU vector. + + The hash value for a table entry is computed by applying an + iterative hash function to the symbol's name. Starting with an + initial value of 'r = 0', each (unsigned) character 'c' in the + string is incorporated into the hash using the formula depending on + the index version: + + Version 4 + The formula is 'r = r * 67 + c - 113'. + + Versions 5 to 7 + The formula is 'r = r * 67 + tolower (c) - 113'. + + The terminating '\0' is not incorporated into the hash. + + The step size used in the hash table is computed via '((hash * 17) + & (size - 1)) | 1', where 'hash' is the hash value, and 'size' is + the size of the hash table. The step size is used to find the next + candidate slot when handling a hash collision. + + The names of C++ symbols in the hash table are canonicalized. We + don't currently have a simple description of the canonicalization + algorithm; if you intend to create new index sections, you must + read the code. + + 6. The shortcut table This is a data structure with the following + fields: + + Language of main + An 'offset_type' value indicating the language of the main + function as a 'DW_LANG_' constant. This value will be zero if + main function information is not present. + + Name of main + An 'offset_type' value indicating the offset of the main + function's name in the constant pool. This value must be + ignored if the value for the language of main is zero. + + 7. The constant pool. This is simply a bunch of bytes. It is + organized so that alignment is correct: CU vectors are stored + first, followed by strings. + + A CU vector in the constant pool is a sequence of 'offset_type' + values. The first value is the number of CU indices in the vector. + Each subsequent value is the index and symbol attributes of a CU in + the CU list. This element in the hash table is used to indicate + which CUs define the symbol and how the symbol is used. See below + for the format of each CU index+attributes entry. + + A string in the constant pool is zero-terminated. + + Attributes were added to CU index values in '.gdb_index' version 7. +If a symbol has multiple uses within a CU then there is one CU +index+attributes value for each use. + + The format of each CU index+attributes entry is as follows (bit 0 = +LSB): + +Bits 0-23 + This is the index of the CU in the CU list. +Bits 24-27 + These bits are reserved for future purposes and must be zero. +Bits 28-30 + The kind of the symbol in the CU. + + 0 + This value is reserved and should not be used. By reserving + zero the full 'offset_type' value is backwards compatible with + previous versions of the index. + 1 + The symbol is a type. + 2 + The symbol is a variable or an enum value. + 3 + The symbol is a function. + 4 + Any other kind of symbol. + 5,6,7 + These values are reserved. + +Bit 31 + This bit is zero if the value is global and one if it is static. + + The determination of whether a symbol is global or static is + complicated. The authoritative reference is the file + 'dwarf2read.c' in GDB sources. + + This pseudo-code describes the computation of a symbol's kind and +global/static attributes in the index. + + is_external = get_attribute (die, DW_AT_external); + language = get_attribute (cu_die, DW_AT_language); + switch (die->tag) + { + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = language != CPLUS; + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = language != CPLUS; + break; + default: + assert (0); + } + + +File: gdb.info, Node: Debuginfod, Next: Man Pages, Prev: Index Section Format, Up: Top + +Appendix K Download debugging resources with Debuginfod +******************************************************* + +'debuginfod' is an HTTP server for distributing ELF, DWARF and source +files. + + With the 'debuginfod' client library, 'libdebuginfod', GDB can query +servers using the build IDs associated with missing debug info, +executables and source files in order to download them on demand. + + For instructions on building GDB with 'libdebuginfod', *note +-with-debuginfod: Configure Options. 'debuginfod' is packaged with +'elfutils', starting with version 0.178. See + for more information +regarding 'debuginfod'. + +* Menu: + +* Debuginfod Settings:: Configuring debuginfod with GDB + + +File: gdb.info, Node: Debuginfod Settings, Up: Debuginfod + +K.1 Debuginfod Settings +======================= + +GDB provides the following commands for configuring 'debuginfod'. + +'set debuginfod enabled' +'set debuginfod enabled on' + GDB may query 'debuginfod' servers for missing debug info and + source files. GDB may also download individual ELF/DWARF sections + such as '.gdb_index' to help reduce the total amount of data + downloaded from 'debuginfod' servers; this can be controlled by + 'maint set debuginfod download-sections' (*note maint set + debuginfod download-sections: Maintenance Commands.). + +'set debuginfod enabled off' + GDB will not attempt to query 'debuginfod' servers when missing + debug info or source files. By default, 'debuginfod enabled' is + set to 'off' for non-interactive sessions. + +'set debuginfod enabled ask' + GDB will prompt the user to enable or disable 'debuginfod' before + attempting to perform the next query. By default, 'debuginfod + enabled' is set to 'ask' for interactive sessions. + +'show debuginfod enabled' + Display whether 'debuginfod enabled' is set to 'on', 'off' or + 'ask'. + +'set debuginfod urls' +'set debuginfod urls URLS' + Set the space-separated list of URLs that 'debuginfod' will attempt + to query. Only 'http://', 'https://' and 'file://' protocols + should be used. The default value of 'debuginfod urls' is copied + from the DEBUGINFOD_URLS environment variable. + +'show debuginfod urls' + Display the list of URLs that 'debuginfod' will attempt to query. + +'set debuginfod verbose' +'set debuginfod verbose N' + Enable or disable 'debuginfod'-related output. Use a non-zero + value to enable and '0' to disable. 'debuginfod' output is shown + by default. + +'show debuginfod verbose' + Show the current verbosity setting. + + +File: gdb.info, Node: Man Pages, Next: Copying, Prev: Debuginfod, Up: Top + +Appendix L Manual pages +*********************** + +* Menu: + +* gdb man:: The GNU Debugger man page +* gdbserver man:: Remote Server for the GNU Debugger man page +* gcore man:: Generate a core file of a running program +* gstack man:: Print a stack trace of a running program +* gdbinit man:: gdbinit scripts +* gdb-add-index man:: Add index files to speed up GDB + + +File: gdb.info, Node: gdb man, Next: gdbserver man, Up: Man Pages + +gdb man +======= + +gdb [OPTIONS] [PROG|PROG PROCID|PROG CORE] + + The purpose of a debugger such as GDB is to allow you to see what is +going on "inside" another program while it executes - or what another +program was doing at the moment it crashed. + + GDB can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + + * Start your program, specifying anything that might affect its + behavior. + + * Make your program stop on specified conditions. + + * Examine what has happened, when your program has stopped. + + * Change things in your program, so you can experiment with + correcting the effects of one bug and go on to learn about another. + + You can use GDB to debug programs written in C, C++, Fortran and +Modula-2. + + GDB is invoked with the shell command 'gdb'. Once started, it reads +commands from the terminal until you tell it to exit with the GDB +command 'quit' or 'exit'. You can get online help from GDB itself by +using the command 'help'. + + You can run 'gdb' with no arguments or options; but the most usual +way to start GDB is with one argument or two, specifying an executable +program as the argument: + + gdb program + + You can also start with both an executable program and a core file +specified: + + gdb program core + + You can, instead, specify a process ID as a second argument or use +option '-p', if you want to debug a running process: + + gdb program 1234 + gdb -p 1234 + +would attach GDB to process '1234'. With option '-p' you can omit the +PROGRAM filename. + + Here are some of the most frequently needed GDB commands: + +'break [FILE:][FUNCTION|LINE]' + Set a breakpoint at FUNCTION or LINE (in FILE). + +'run [ARGLIST]' + Start your program (with ARGLIST, if specified). + +'bt' + Backtrace: display the program stack. + +'print EXPR' + Display the value of an expression. + +'c' + Continue running your program (after stopping, e.g. at a + breakpoint). + +'next' + Execute next program line (after stopping); step _over_ any + function calls in the line. + +'edit [FILE:]FUNCTION' + look at the program line where it is presently stopped. + +'list [FILE:]FUNCTION' + type the text of the program in the vicinity of where it is + presently stopped. + +'step' + Execute next program line (after stopping); step _into_ any + function calls in the line. + +'help [NAME]' + Show information about GDB command NAME, or general information + about using GDB. + +'quit' +'exit' + Exit from GDB. + + Any arguments other than options specify an executable file and core +file (or process ID); that is, the first argument encountered with no +associated option flag is equivalent to a '--se' option, and the second, +if any, is equivalent to a '-c' option if it's the name of a file. Many +options have both long and abbreviated forms; both are shown here. The +long forms are also recognized if you truncate them, so long as enough +of the option is present to be unambiguous. + + The abbreviated forms are shown here with '-' and long forms are +shown with '--' to reflect how they are shown in '--help'. However, GDB +recognizes all of the following conventions for most options: + +'--option=VALUE' +'--option VALUE' +'-option=VALUE' +'-option VALUE' +'--o=VALUE' +'--o VALUE' +'-o=VALUE' +'-o VALUE' + + All the options and command line arguments you give are processed in +sequential order. The order makes a difference when the '-x' option is +used. + +'--help' +'-h' + List all options, with brief explanations. + +'--symbols=FILE' +'-s FILE' + Read symbol table from FILE. + +'--write' + Enable writing into executable and core files. + +'--exec=FILE' +'-e FILE' + Use FILE as the executable file to execute when appropriate, and + for examining pure data in conjunction with a core dump. + +'--se=FILE' + Read symbol table from FILE and use it as the executable file. + +'--core=FILE' +'-c FILE' + Use FILE as a core dump to examine. + +'--command=FILE' +'-x FILE' + Execute GDB commands from FILE. + +'--eval-command=COMMAND' +'-ex COMMAND' + Execute given GDB COMMAND. + +'--init-eval-command=COMMAND' +'-iex' + Execute GDB COMMAND before loading the inferior. + +'--directory=DIRECTORY' +'-d DIRECTORY' + Add DIRECTORY to the path to search for source files. + +'--nh' + Do not execute commands from '~/.config/gdb/gdbinit', '~/.gdbinit', + '~/.config/gdb/gdbearlyinit', or '~/.gdbearlyinit' + +'--nx' +'-n' + Do not execute commands from any '.gdbinit' or '.gdbearlyinit' + initialization files. + +'--quiet' +'--silent' +'-q' + "Quiet". Do not print the introductory and copyright messages. + These messages are also suppressed in batch mode. + +'--batch' + Run in batch mode. Exit with status '0' after processing all the + command files specified with '-x' (and '.gdbinit', if not + inhibited). Exit with nonzero status if an error occurs in + executing the GDB commands in the command files. + + Batch mode may be useful for running GDB as a filter, for example + to download and run a program on another computer; in order to make + this more useful, the message + + Program exited normally. + + (which is ordinarily issued whenever a program running under GDB + control terminates) is not issued when running in batch mode. + +'--batch-silent' + Run in batch mode, just like '--batch', but totally silent. All + GDB output is suppressed (stderr is unaffected). This is much + quieter than '--silent' and would be useless for an interactive + session. + + This is particularly useful when using targets that give 'Loading + section' messages, for example. + + Note that targets that give their output via GDB, as opposed to + writing directly to 'stdout', will also be made silent. + +'--args PROG [ARGLIST]' + Change interpretation of command line so that arguments following + this option are passed as arguments to the inferior. As an + example, take the following command: + + gdb ./a.out -q + + It would start GDB with '-q', not printing the introductory + message. On the other hand, using: + + gdb --args ./a.out -q + + starts GDB with the introductory message, and passes the option to + the inferior. + +'--pid=PID' + Attach GDB to an already running program, with the PID PID. + +'--tui' + Open the terminal user interface. + +'--readnow' + Read all symbols from the given symfile on the first access. + +'--readnever' + Do not read symbol files. + +'--return-child-result' + GDB's exit code will be the same as the child's exit code. + +'--configuration' + Print details about GDB configuration and then exit. + +'--version' + Print version information and then exit. + +'--cd=DIRECTORY' + Run GDB using DIRECTORY as its working directory, instead of the + current directory. + +'--data-directory=DIRECTORY' +'-D' + Run GDB using DIRECTORY as its data directory. The data directory + is where GDB searches for its auxiliary files. + +'--fullname' +'-f' + Emacs sets this option when it runs GDB as a subprocess. It tells + GDB to output the full file name and line number in a standard, + recognizable fashion each time a stack frame is displayed (which + includes each time the program stops). This recognizable format + looks like two '\032' characters, followed by the file name, line + number and character position separated by colons, and a newline. + The Emacs-to-GDB interface program uses the two '\032' characters + as a signal to display the source code for the frame. + +'-b BAUDRATE' + Set the line speed (baud rate or bits per second) of any serial + interface used by GDB for remote debugging. + +'-l TIMEOUT' + Set timeout, in seconds, for remote debugging. + +'--tty=DEVICE' + Run using DEVICE for your program's standard input and output. + + +File: gdb.info, Node: gdbserver man, Next: gcore man, Prev: gdb man, Up: Man Pages + +gdbserver man +============= + +gdbserver COMM PROG [ARGS...] + +gdbserver -attach COMM PID + +gdbserver -multi COMM + + 'gdbserver' is a program that allows you to run GDB on a different +machine than the one which is running the program being debugged. + +Usage (server (target) side) +---------------------------- + +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, +as 'gdbserver' doesn't care about symbols. All symbol handling is taken +care of by the GDB running on the host system. + + To use the server, you log on to the target system, and run the +'gdbserver' program. You must tell it (a) how to communicate with GDB, +(b) the name of your program, and (c) its arguments. The general syntax +is: + + target> gdbserver COMM PROGRAM [ARGS ...] + + For example, using a serial port, you might say: + + target> gdbserver /dev/com1 emacs foo.txt + + This tells 'gdbserver' to debug emacs with an argument of foo.txt, +and to communicate with GDB via '/dev/com1'. 'gdbserver' now waits +patiently for the host GDB to communicate with it. + + To use a TCP connection, you could say: + + target> gdbserver host:2345 emacs foo.txt + + This says pretty much the same thing as the last example, except that +we are going to communicate with the 'host' GDB via TCP. The 'host:2345' +argument means that we are expecting to see a TCP connection from 'host' +to local TCP port 2345. (Currently, the 'host' part is ignored.) You +can choose any number you want for the port number as long as it does +not conflict with any existing TCP ports on the target system. This +same port number must be used in the host GDBs 'target remote' command, +which will be described shortly. Note that if you chose a port number +that conflicts with another service, 'gdbserver' will print an error +message and exit. + + 'gdbserver' can also attach to running programs. This is +accomplished via the '--attach' argument. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't +necessary to point 'gdbserver' at a binary for the running process. + + To start 'gdbserver' without supplying an initial command to run or +process ID to attach, use the '--multi' command line option. In such +case you should connect using 'target extended-remote' to start the +program you want to debug. + + target> gdbserver --multi COMM + +Usage (host side) +----------------- + +You need an unstripped copy of the target program on your host system, +since GDB needs to examine its symbol tables and such. Start up GDB as +you normally would, with the target program as the first argument. (You +may need to use the '--baud' option if the serial line is running at +anything except 9600 baud.) That is 'gdb TARGET-PROG', or 'gdb --baud +BAUD TARGET-PROG'. After that, the only new command you need to know +about is 'target remote' (or 'target extended-remote'). Its argument is +either a device name (usually a serial device, like '/dev/ttyb'), or a +'HOST:PORT' descriptor. For example: + + (gdb) target remote /dev/ttyb + +communicates with the server via serial line '/dev/ttyb', and: + + (gdb) target remote the-target:2345 + +communicates via a TCP connection to port 2345 on host 'the-target', +where you previously started up 'gdbserver' with the same port number. +Note that for TCP connections, you must start up 'gdbserver' prior to +using the 'target remote' command, otherwise you may get an error that +looks something like 'Connection refused'. + + 'gdbserver' can also debug multiple inferiors at once, described in +*note Inferiors Connections and Programs::. In such case use the +'extended-remote' GDB command variant: + + (gdb) target extended-remote the-target:2345 + + The 'gdbserver' option '--multi' may or may not be used in such case. + + There are three different modes for invoking 'gdbserver': + + * Debug a specific program specified by its program name: + + gdbserver COMM PROG [ARGS...] + + The COMM parameter specifies how should the server communicate with + GDB; it is either a device name (to use a serial line), a TCP port + number (':1234'), or '-' or 'stdio' to use stdin/stdout of + 'gdbserver'. Specify the name of the program to debug in PROG. + Any remaining arguments will be passed to the program verbatim. + When the program exits, GDB will close the connection, and + 'gdbserver' will exit. + + * Debug a specific program by specifying the process ID of a running + program: + + gdbserver --attach COMM PID + + The COMM parameter is as described above. Supply the process ID of + a running program in PID; GDB will do everything else. Like with + the previous mode, when the process PID exits, GDB will close the + connection, and 'gdbserver' will exit. + + * Multi-process mode - debug more than one program/process: + + gdbserver --multi COMM + + In this mode, GDB can instruct 'gdbserver' which command(s) to run. + Unlike the other 2 modes, GDB will not close the connection when a + process being debugged exits, so you can debug several processes in + the same session. + + In each of the modes you may specify these options: + +'--help' + List all options, with brief explanations. + +'--version' + This option causes 'gdbserver' to print its version number and + exit. + +'--attach' + 'gdbserver' will attach to a running program. The syntax is: + + target> gdbserver --attach COMM PID + + PID is the process ID of a currently running process. It isn't + necessary to point 'gdbserver' at a binary for the running process. + +'--multi' + To start 'gdbserver' without supplying an initial command to run or + process ID to attach, use this command line option. Then you can + connect using 'target extended-remote' and start the program you + want to debug. The syntax is: + + target> gdbserver --multi COMM + +'--debug[=option1,option2,...]' + Instruct 'gdbserver' to display extra status information about the + debugging process. This option is intended for 'gdbserver' + development and for bug reports to the developers. + + Each OPTION is the name of a component for which debugging should + be enabled. The list of possible options is 'all', 'threads', + 'event-loop', 'remote'. The special option 'all' enables all + components. The option list is processed left to right, and an + option can be prefixed with the '-' character to disable output for + that component, so you could write: + + target> gdbserver --debug=all,-event-loop + + to turn on debug output for all components except 'event-loop'. If + no options are passed to '--debug' then this is treated as + equivalent to '--debug=threads'. This could change in future + releases of 'gdbserver'. + +'--debug-file=FILENAME' + Instruct 'gdbserver' to send any debug output to the given + FILENAME. This option is intended for 'gdbserver' development and + for bug reports to the developers. + +'--debug-format=option1[,option2,...]' + Instruct 'gdbserver' to include extra information in each line of + debugging output. *Note Other Command-Line Arguments for + gdbserver::. + +'--wrapper' + Specify a wrapper to launch programs for debugging. The option + should be followed by the name of the wrapper, then any + command-line arguments to pass to the wrapper, then '--' indicating + the end of the wrapper arguments. + +'--once' + By default, 'gdbserver' keeps the listening TCP port open, so that + additional connections are possible. However, if you start + 'gdbserver' with the '--once' option, it will stop listening for + any further connection attempts after connecting to the first GDB + session. + + +File: gdb.info, Node: gcore man, Next: gstack man, Prev: gdbserver man, Up: Man Pages + +gcore +===== + +gcore [-a] [-o PREFIX] [-d DIRECTORY] PID1 [PID2...PIDN] + + Generate core dumps of one or more running programs with process IDs +PID1, PID2, etc. A core file produced by 'gcore' is equivalent to one +produced by the kernel when the process crashes (and when 'ulimit -c' +was used to set up an appropriate core dump limit). However, unlike +after a crash, after 'gcore' finishes its job the program remains +running without any change. + +'-a' + Dump all memory mappings. The actual effect of this option depends + on the Operating System. On GNU/Linux, it will disable + 'use-coredump-filter' (*note set use-coredump-filter::) and enable + 'dump-excluded-mappings' (*note set dump-excluded-mappings::). + +'-o PREFIX' + The optional argument PREFIX specifies the prefix to be used when + composing the file names of the core dumps. The file name is + composed as 'PREFIX.PID', where PID is the process ID of the + running program being analyzed by 'gcore'. If not specified, + PREFIX defaults to GCORE. + +'-d DIRECTORY' + Use DIRECTORY as the data directory when invoking GDB for running + the gcore command. This argument is optional. + + +File: gdb.info, Node: gstack man, Next: gdbinit man, Prev: gcore man, Up: Man Pages + +gstack +====== + +gstack [-h | -help] [-v | -version] PID + + Print a stack trace of a running program with process ID PID. If the +process is multi-threaded, 'gstack' outputs backtraces for every thread +which exists in the process. + + The script invokes GDB, attaches to the given process ID, prints the +stack trace, and detaches from the process. + + 'gstack' exits with non-zero status if 'gdb' was unable to attach to +the given process ID for any reason, such as a non-existent process ID +or insufficient privileges to attach to the process. + +'--help' +'-h' + List all options, with brief explanations. + +'--version' +'-v' + Print version information and then exit. + +'AWK' + Full file name for an Awk interpreter to use. If not set, 'PATH' + will be searched for an 'awk' program. + +'GDB' + Full file name for a GDB executable to use to generate stack + backtraces. If not set, 'PATH' will be searched for a 'gdb' + program. + +'GDBARGS' + Optional arguments to be passed to the 'gdb' program. + + +File: gdb.info, Node: gdbinit man, Next: gdb-add-index man, Prev: gstack man, Up: Man Pages + +gdbinit +======= + + + +~/.config/gdb/gdbinit + +~/.gdbinit + +./.gdbinit + + These files contain GDB commands to automatically execute during GDB +startup. The lines of contents are canned sequences of commands, +described in *note Sequences::. + + Please read more in *note Startup::. + +'(not enabled with --with-system-gdbinit during compilation)' + System-wide initialization file. It is executed unless user + specified GDB option '-nx' or '-n'. See more in +'(not enabled with --with-system-gdbinit-dir during compilation)' + System-wide initialization directory. All files in this directory + are executed on startup unless user specified GDB option '-nx' or + '-n', as long as they have a recognized file extension. See more + in *note System-wide configuration::. + +'~/.config/gdb/gdbinit or ~/.gdbinit' + User initialization file. It is executed unless user specified GDB + options '-nx', '-n' or '-nh'. + +'.gdbinit' + Initialization file for current directory. It may need to be + enabled with GDB security command 'set auto-load local-gdbinit'. + See more in *note Init File in the Current Directory::. + + +File: gdb.info, Node: gdb-add-index man, Prev: gdbinit man, Up: Man Pages + +gdb-add-index +============= + +gdb-add-index [-dwarf-5] FILENAME + + When GDB finds a symbol file, it scans the symbols in the file in +order to construct an internal symbol table. This lets most GDB +operations work quickly-at the cost of a delay early on. For large +programs, this delay can be quite lengthy, so GDB provides a way to +build an index, which speeds up startup. + + To determine whether a file contains such an index, use the command +'readelf -S filename': the index is stored in a section named +'.gdb_index' (pre-DWARF 5) or '.debug_names' and '.debug_str' (DWARF 5). +Indexes can only be produced on systems which use ELF binaries and DWARF +debug information (i.e., sections named '.debug_*'). + + By default 'gdb-add-index' will add a pre-DWARF 5 '.gdb_index' +section to FILENAME. With '-dwarf-5' DWARF 5 sections are added +instead. + + FILENAME must be writable. + + 'gdb-add-index' uses GDB, 'objcopy', and 'readelf' found in the +'PATH' environment variable. If you want to use different versions of +these programs, you can specify them through the appropriate environment +variables (see below). + + 'gdb-add-index' exits with status 0 if it succeeds in creating the +index for FILENAME or greater than 0 if an error occurs. + + See more in *note Index Files::. + +'-dwarf-5' + Add DWARF 5 sections instead of previous '.debug_index' section. + +'GDB' + Full file name of the 'gdb' program to use for index generation. + If not set, the 'PATH' will be searched for a 'gdb' program. + +'OBJCOPY' + Full file name of the 'objcopy' program to use to copy section + information into the given file. If not set, the 'PATH' will be + searched for a 'objcopy' program. + +'READELF' + Full file name of the 'readelf' program to use to inspect + properties of the given file. If not set, the 'PATH' will be + searched for a 'readelf' program. + + +File: gdb.info, Node: Copying, Next: GNU Free Documentation License, Prev: Man Pages, Up: Top + +Appendix M GNU GENERAL PUBLIC LICENSE +************************************* + + Version 3, 29 June 2007 + + Copyright (C) 2007 Free Software Foundation, Inc. + + Everyone is permitted to copy and distribute verbatim copies of this + license document, but changing it is not allowed. + +Preamble +======== + +The GNU General Public License is a free, copyleft license for software +and other kinds of works. + + The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom to +share and change all versions of a program--to make sure it remains free +software for all its users. We, the Free Software Foundation, use the +GNU General Public License for most of our software; it applies also to +any other work released this way by its authors. You can apply it to +your programs, too. + + When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + + To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you have +certain responsibilities if you distribute copies of the software, or if +you modify it: responsibilities to respect the freedom of others. + + For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, receive +or can get the source code. And you must show them these terms so they +know their rights. + + Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + + For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + + Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the manufacturer +can do so. This is fundamentally incompatible with the aim of +protecting users' freedom to change the software. The systematic +pattern of such abuse occurs in the area of products for individuals to +use, which is precisely where it is most unacceptable. Therefore, we +have designed this version of the GPL to prohibit the practice for those +products. If such problems arise substantially in other domains, we +stand ready to extend this provision to those domains in future versions +of the GPL, as needed to protect the freedom of users. + + Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish to +avoid the special danger that patents applied to a free program could +make it effectively proprietary. To prevent this, the GPL assures that +patents cannot be used to render the program non-free. + + The precise terms and conditions for copying, distribution and +modification follow. + +TERMS AND CONDITIONS +==================== + + 0. Definitions. + + "This License" refers to version 3 of the GNU General Public + License. + + "Copyright" also means copyright-like laws that apply to other + kinds of works, such as semiconductor masks. + + "The Program" refers to any copyrightable work licensed under this + License. Each licensee is addressed as "you". "Licensees" and + "recipients" may be individuals or organizations. + + To "modify" a work means to copy from or adapt all or part of the + work in a fashion requiring copyright permission, other than the + making of an exact copy. The resulting work is called a "modified + version" of the earlier work or a work "based on" the earlier work. + + A "covered work" means either the unmodified Program or a work + based on the Program. + + To "propagate" a work means to do anything with it that, without + permission, would make you directly or secondarily liable for + infringement under applicable copyright law, except executing it on + a computer or modifying a private copy. Propagation includes + copying, distribution (with or without modification), making + available to the public, and in some countries other activities as + well. + + To "convey" a work means any kind of propagation that enables other + parties to make or receive copies. Mere interaction with a user + through a computer network, with no transfer of a copy, is not + conveying. + + An interactive user interface displays "Appropriate Legal Notices" + to the extent that it includes a convenient and prominently visible + feature that (1) displays an appropriate copyright notice, and (2) + tells the user that there is no warranty for the work (except to + the extent that warranties are provided), that licensees may convey + the work under this License, and how to view a copy of this + License. If the interface presents a list of user commands or + options, such as a menu, a prominent item in the list meets this + criterion. + + 1. Source Code. + + The "source code" for a work means the preferred form of the work + for making modifications to it. "Object code" means any non-source + form of a work. + + A "Standard Interface" means an interface that either is an + official standard defined by a recognized standards body, or, in + the case of interfaces specified for a particular programming + language, one that is widely used among developers working in that + language. + + The "System Libraries" of an executable work include anything, + other than the work as a whole, that (a) is included in the normal + form of packaging a Major Component, but which is not part of that + Major Component, and (b) serves only to enable use of the work with + that Major Component, or to implement a Standard Interface for + which an implementation is available to the public in source code + form. A "Major Component", in this context, means a major + essential component (kernel, window system, and so on) of the + specific operating system (if any) on which the executable work + runs, or a compiler used to produce the work, or an object code + interpreter used to run it. + + The "Corresponding Source" for a work in object code form means all + the source code needed to generate, install, and (for an executable + work) run the object code and to modify the work, including scripts + to control those activities. However, it does not include the + work's System Libraries, or general-purpose tools or generally + available free programs which are used unmodified in performing + those activities but which are not part of the work. For example, + Corresponding Source includes interface definition files associated + with source files for the work, and the source code for shared + libraries and dynamically linked subprograms that the work is + specifically designed to require, such as by intimate data + communication or control flow between those subprograms and other + parts of the work. + + The Corresponding Source need not include anything that users can + regenerate automatically from other parts of the Corresponding + Source. + + The Corresponding Source for a work in source code form is that + same work. + + 2. Basic Permissions. + + All rights granted under this License are granted for the term of + copyright on the Program, and are irrevocable provided the stated + conditions are met. This License explicitly affirms your unlimited + permission to run the unmodified Program. The output from running + a covered work is covered by this License only if the output, given + its content, constitutes a covered work. This License acknowledges + your rights of fair use or other equivalent, as provided by + copyright law. + + You may make, run and propagate covered works that you do not + convey, without conditions so long as your license otherwise + remains in force. You may convey covered works to others for the + sole purpose of having them make modifications exclusively for you, + or provide you with facilities for running those works, provided + that you comply with the terms of this License in conveying all + material for which you do not control copyright. Those thus making + or running the covered works for you must do so exclusively on your + behalf, under your direction and control, on terms that prohibit + them from making any copies of your copyrighted material outside + their relationship with you. + + Conveying under any other circumstances is permitted solely under + the conditions stated below. Sublicensing is not allowed; section + 10 makes it unnecessary. + + 3. Protecting Users' Legal Rights From Anti-Circumvention Law. + + No covered work shall be deemed part of an effective technological + measure under any applicable law fulfilling obligations under + article 11 of the WIPO copyright treaty adopted on 20 December + 1996, or similar laws prohibiting or restricting circumvention of + such measures. + + When you convey a covered work, you waive any legal power to forbid + circumvention of technological measures to the extent such + circumvention is effected by exercising rights under this License + with respect to the covered work, and you disclaim any intention to + limit operation or modification of the work as a means of + enforcing, against the work's users, your or third parties' legal + rights to forbid circumvention of technological measures. + + 4. Conveying Verbatim Copies. + + You may convey verbatim copies of the Program's source code as you + receive it, in any medium, provided that you conspicuously and + appropriately publish on each copy an appropriate copyright notice; + keep intact all notices stating that this License and any + non-permissive terms added in accord with section 7 apply to the + code; keep intact all notices of the absence of any warranty; and + give all recipients a copy of this License along with the Program. + + You may charge any price or no price for each copy that you convey, + and you may offer support or warranty protection for a fee. + + 5. Conveying Modified Source Versions. + + You may convey a work based on the Program, or the modifications to + produce it from the Program, in the form of source code under the + terms of section 4, provided that you also meet all of these + conditions: + + a. The work must carry prominent notices stating that you + modified it, and giving a relevant date. + + b. The work must carry prominent notices stating that it is + released under this License and any conditions added under + section 7. This requirement modifies the requirement in + section 4 to "keep intact all notices". + + c. You must license the entire work, as a whole, under this + License to anyone who comes into possession of a copy. This + License will therefore apply, along with any applicable + section 7 additional terms, to the whole of the work, and all + its parts, regardless of how they are packaged. This License + gives no permission to license the work in any other way, but + it does not invalidate such permission if you have separately + received it. + + d. If the work has interactive user interfaces, each must display + Appropriate Legal Notices; however, if the Program has + interactive interfaces that do not display Appropriate Legal + Notices, your work need not make them do so. + + A compilation of a covered work with other separate and independent + works, which are not by their nature extensions of the covered + work, and which are not combined with it such as to form a larger + program, in or on a volume of a storage or distribution medium, is + called an "aggregate" if the compilation and its resulting + copyright are not used to limit the access or legal rights of the + compilation's users beyond what the individual works permit. + Inclusion of a covered work in an aggregate does not cause this + License to apply to the other parts of the aggregate. + + 6. Conveying Non-Source Forms. + + You may convey a covered work in object code form under the terms + of sections 4 and 5, provided that you also convey the + machine-readable Corresponding Source under the terms of this + License, in one of these ways: + + a. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by the + Corresponding Source fixed on a durable physical medium + customarily used for software interchange. + + b. Convey the object code in, or embodied in, a physical product + (including a physical distribution medium), accompanied by a + written offer, valid for at least three years and valid for as + long as you offer spare parts or customer support for that + product model, to give anyone who possesses the object code + either (1) a copy of the Corresponding Source for all the + software in the product that is covered by this License, on a + durable physical medium customarily used for software + interchange, for a price no more than your reasonable cost of + physically performing this conveying of source, or (2) access + to copy the Corresponding Source from a network server at no + charge. + + c. Convey individual copies of the object code with a copy of the + written offer to provide the Corresponding Source. This + alternative is allowed only occasionally and noncommercially, + and only if you received the object code with such an offer, + in accord with subsection 6b. + + d. Convey the object code by offering access from a designated + place (gratis or for a charge), and offer equivalent access to + the Corresponding Source in the same way through the same + place at no further charge. You need not require recipients + to copy the Corresponding Source along with the object code. + If the place to copy the object code is a network server, the + Corresponding Source may be on a different server (operated by + you or a third party) that supports equivalent copying + facilities, provided you maintain clear directions next to the + object code saying where to find the Corresponding Source. + Regardless of what server hosts the Corresponding Source, you + remain obligated to ensure that it is available for as long as + needed to satisfy these requirements. + + e. Convey the object code using peer-to-peer transmission, + provided you inform other peers where the object code and + Corresponding Source of the work are being offered to the + general public at no charge under subsection 6d. + + A separable portion of the object code, whose source code is + excluded from the Corresponding Source as a System Library, need + not be included in conveying the object code work. + + A "User Product" is either (1) a "consumer product", which means + any tangible personal property which is normally used for personal, + family, or household purposes, or (2) anything designed or sold for + incorporation into a dwelling. In determining whether a product is + a consumer product, doubtful cases shall be resolved in favor of + coverage. For a particular product received by a particular user, + "normally used" refers to a typical or common use of that class of + product, regardless of the status of the particular user or of the + way in which the particular user actually uses, or expects or is + expected to use, the product. A product is a consumer product + regardless of whether the product has substantial commercial, + industrial or non-consumer uses, unless such uses represent the + only significant mode of use of the product. + + "Installation Information" for a User Product means any methods, + procedures, authorization keys, or other information required to + install and execute modified versions of a covered work in that + User Product from a modified version of its Corresponding Source. + The information must suffice to ensure that the continued + functioning of the modified object code is in no case prevented or + interfered with solely because modification has been made. + + If you convey an object code work under this section in, or with, + or specifically for use in, a User Product, and the conveying + occurs as part of a transaction in which the right of possession + and use of the User Product is transferred to the recipient in + perpetuity or for a fixed term (regardless of how the transaction + is characterized), the Corresponding Source conveyed under this + section must be accompanied by the Installation Information. But + this requirement does not apply if neither you nor any third party + retains the ability to install modified object code on the User + Product (for example, the work has been installed in ROM). + + The requirement to provide Installation Information does not + include a requirement to continue to provide support service, + warranty, or updates for a work that has been modified or installed + by the recipient, or for the User Product in which it has been + modified or installed. Access to a network may be denied when the + modification itself materially and adversely affects the operation + of the network or violates the rules and protocols for + communication across the network. + + Corresponding Source conveyed, and Installation Information + provided, in accord with this section must be in a format that is + publicly documented (and with an implementation available to the + public in source code form), and must require no special password + or key for unpacking, reading or copying. + + 7. Additional Terms. + + "Additional permissions" are terms that supplement the terms of + this License by making exceptions from one or more of its + conditions. Additional permissions that are applicable to the + entire Program shall be treated as though they were included in + this License, to the extent that they are valid under applicable + law. If additional permissions apply only to part of the Program, + that part may be used separately under those permissions, but the + entire Program remains governed by this License without regard to + the additional permissions. + + When you convey a copy of a covered work, you may at your option + remove any additional permissions from that copy, or from any part + of it. (Additional permissions may be written to require their own + removal in certain cases when you modify the work.) You may place + additional permissions on material, added by you to a covered work, + for which you have or can give appropriate copyright permission. + + Notwithstanding any other provision of this License, for material + you add to a covered work, you may (if authorized by the copyright + holders of that material) supplement the terms of this License with + terms: + + a. Disclaiming warranty or limiting liability differently from + the terms of sections 15 and 16 of this License; or + + b. Requiring preservation of specified reasonable legal notices + or author attributions in that material or in the Appropriate + Legal Notices displayed by works containing it; or + + c. Prohibiting misrepresentation of the origin of that material, + or requiring that modified versions of such material be marked + in reasonable ways as different from the original version; or + + d. Limiting the use for publicity purposes of names of licensors + or authors of the material; or + + e. Declining to grant rights under trademark law for use of some + trade names, trademarks, or service marks; or + + f. Requiring indemnification of licensors and authors of that + material by anyone who conveys the material (or modified + versions of it) with contractual assumptions of liability to + the recipient, for any liability that these contractual + assumptions directly impose on those licensors and authors. + + All other non-permissive additional terms are considered "further + restrictions" within the meaning of section 10. If the Program as + you received it, or any part of it, contains a notice stating that + it is governed by this License along with a term that is a further + restriction, you may remove that term. If a license document + contains a further restriction but permits relicensing or conveying + under this License, you may add to a covered work material governed + by the terms of that license document, provided that the further + restriction does not survive such relicensing or conveying. + + If you add terms to a covered work in accord with this section, you + must place, in the relevant source files, a statement of the + additional terms that apply to those files, or a notice indicating + where to find the applicable terms. + + Additional terms, permissive or non-permissive, may be stated in + the form of a separately written license, or stated as exceptions; + the above requirements apply either way. + + 8. Termination. + + You may not propagate or modify a covered work except as expressly + provided under this License. Any attempt otherwise to propagate or + modify it is void, and will automatically terminate your rights + under this License (including any patent licenses granted under the + third paragraph of section 11). + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, you do not qualify to receive new licenses + for the same material under section 10. + + 9. Acceptance Not Required for Having Copies. + + You are not required to accept this License in order to receive or + run a copy of the Program. Ancillary propagation of a covered work + occurring solely as a consequence of using peer-to-peer + transmission to receive a copy likewise does not require + acceptance. However, nothing other than this License grants you + permission to propagate or modify any covered work. These actions + infringe copyright if you do not accept this License. Therefore, + by modifying or propagating a covered work, you indicate your + acceptance of this License to do so. + + 10. Automatic Licensing of Downstream Recipients. + + Each time you convey a covered work, the recipient automatically + receives a license from the original licensors, to run, modify and + propagate that work, subject to this License. You are not + responsible for enforcing compliance by third parties with this + License. + + An "entity transaction" is a transaction transferring control of an + organization, or substantially all assets of one, or subdividing an + organization, or merging organizations. If propagation of a + covered work results from an entity transaction, each party to that + transaction who receives a copy of the work also receives whatever + licenses to the work the party's predecessor in interest had or + could give under the previous paragraph, plus a right to possession + of the Corresponding Source of the work from the predecessor in + interest, if the predecessor has it or can get it with reasonable + efforts. + + You may not impose any further restrictions on the exercise of the + rights granted or affirmed under this License. For example, you + may not impose a license fee, royalty, or other charge for exercise + of rights granted under this License, and you may not initiate + litigation (including a cross-claim or counterclaim in a lawsuit) + alleging that any patent claim is infringed by making, using, + selling, offering for sale, or importing the Program or any portion + of it. + + 11. Patents. + + A "contributor" is a copyright holder who authorizes use under this + License of the Program or a work on which the Program is based. + The work thus licensed is called the contributor's "contributor + version". + + A contributor's "essential patent claims" are all patent claims + owned or controlled by the contributor, whether already acquired or + hereafter acquired, that would be infringed by some manner, + permitted by this License, of making, using, or selling its + contributor version, but do not include claims that would be + infringed only as a consequence of further modification of the + contributor version. For purposes of this definition, "control" + includes the right to grant patent sublicenses in a manner + consistent with the requirements of this License. + + Each contributor grants you a non-exclusive, worldwide, + royalty-free patent license under the contributor's essential + patent claims, to make, use, sell, offer for sale, import and + otherwise run, modify and propagate the contents of its contributor + version. + + In the following three paragraphs, a "patent license" is any + express agreement or commitment, however denominated, not to + enforce a patent (such as an express permission to practice a + patent or covenant not to sue for patent infringement). To "grant" + such a patent license to a party means to make such an agreement or + commitment not to enforce a patent against the party. + + If you convey a covered work, knowingly relying on a patent + license, and the Corresponding Source of the work is not available + for anyone to copy, free of charge and under the terms of this + License, through a publicly available network server or other + readily accessible means, then you must either (1) cause the + Corresponding Source to be so available, or (2) arrange to deprive + yourself of the benefit of the patent license for this particular + work, or (3) arrange, in a manner consistent with the requirements + of this License, to extend the patent license to downstream + recipients. "Knowingly relying" means you have actual knowledge + that, but for the patent license, your conveying the covered work + in a country, or your recipient's use of the covered work in a + country, would infringe one or more identifiable patents in that + country that you have reason to believe are valid. + + If, pursuant to or in connection with a single transaction or + arrangement, you convey, or propagate by procuring conveyance of, a + covered work, and grant a patent license to some of the parties + receiving the covered work authorizing them to use, propagate, + modify or convey a specific copy of the covered work, then the + patent license you grant is automatically extended to all + recipients of the covered work and works based on it. + + A patent license is "discriminatory" if it does not include within + the scope of its coverage, prohibits the exercise of, or is + conditioned on the non-exercise of one or more of the rights that + are specifically granted under this License. You may not convey a + covered work if you are a party to an arrangement with a third + party that is in the business of distributing software, under which + you make payment to the third party based on the extent of your + activity of conveying the work, and under which the third party + grants, to any of the parties who would receive the covered work + from you, a discriminatory patent license (a) in connection with + copies of the covered work conveyed by you (or copies made from + those copies), or (b) primarily for and in connection with specific + products or compilations that contain the covered work, unless you + entered into that arrangement, or that patent license was granted, + prior to 28 March 2007. + + Nothing in this License shall be construed as excluding or limiting + any implied license or other defenses to infringement that may + otherwise be available to you under applicable patent law. + + 12. No Surrender of Others' Freedom. + + If conditions are imposed on you (whether by court order, agreement + or otherwise) that contradict the conditions of this License, they + do not excuse you from the conditions of this License. If you + cannot convey a covered work so as to satisfy simultaneously your + obligations under this License and any other pertinent obligations, + then as a consequence you may not convey it at all. For example, + if you agree to terms that obligate you to collect a royalty for + further conveying from those to whom you convey the Program, the + only way you could satisfy both those terms and this License would + be to refrain entirely from conveying the Program. + + 13. Use with the GNU Affero General Public License. + + Notwithstanding any other provision of this License, you have + permission to link or combine any covered work with a work licensed + under version 3 of the GNU Affero General Public License into a + single combined work, and to convey the resulting work. The terms + of this License will continue to apply to the part which is the + covered work, but the special requirements of the GNU Affero + General Public License, section 13, concerning interaction through + a network will apply to the combination as such. + + 14. Revised Versions of this License. + + The Free Software Foundation may publish revised and/or new + versions of the GNU General Public License from time to time. Such + new versions will be similar in spirit to the present version, but + may differ in detail to address new problems or concerns. + + Each version is given a distinguishing version number. If the + Program specifies that a certain numbered version of the GNU + General Public License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that numbered version or of any later version published by the Free + Software Foundation. If the Program does not specify a version + number of the GNU General Public License, you may choose any + version ever published by the Free Software Foundation. + + If the Program specifies that a proxy can decide which future + versions of the GNU General Public License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Program. + + Later license versions may give you additional or different + permissions. However, no additional obligations are imposed on any + author or copyright holder as a result of your choosing to follow a + later version. + + 15. Disclaimer of Warranty. + + THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY + APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE + COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" + WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, + INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF + MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE + RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. + SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL + NECESSARY SERVICING, REPAIR OR CORRECTION. + + 16. Limitation of Liability. + + IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN + WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES + AND/OR CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR + DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR + CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE + THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA + BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD + PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER + PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF + THE POSSIBILITY OF SUCH DAMAGES. + + 17. Interpretation of Sections 15 and 16. + + If the disclaimer of warranty and limitation of liability provided + above cannot be given local legal effect according to their terms, + reviewing courts shall apply local law that most closely + approximates an absolute waiver of all civil liability in + connection with the Program, unless a warranty or assumption of + liability accompanies a copy of the Program in return for a fee. + +END OF TERMS AND CONDITIONS +=========================== + +How to Apply These Terms to Your New Programs +============================================= + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + + To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least the +"copyright" line and a pointer to where the full notice is found. + + ONE LINE TO GIVE THE PROGRAM'S NAME AND A BRIEF IDEA OF WHAT IT DOES. + Copyright (C) YEAR NAME OF AUTHOR + + This program is free software: you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation, either version 3 of the License, or (at + your option) any later version. + + This program is distributed in the hope that it will be useful, but + WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + General Public License for more details. + + You should have received a copy of the GNU General Public License + along with this program. If not, see . + + Also add information on how to contact you by electronic and paper +mail. + + If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + + PROGRAM Copyright (C) YEAR NAME OF AUTHOR + This program comes with ABSOLUTELY NO WARRANTY; for details type 'show w'. + This is free software, and you are welcome to redistribute it + under certain conditions; type 'show c' for details. + + The hypothetical commands 'show w' and 'show c' should show the +appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an "about box". + + You should also get your employer (if you work as a programmer) or +school, if any, to sign a "copyright disclaimer" for the program, if +necessary. For more information on this, and how to apply and follow +the GNU GPL, see . + + The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use the +GNU Lesser General Public License instead of this License. But first, +please read . + + +File: gdb.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Copying, Up: Top + +Appendix N GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: gdb.info, Node: Concept Index, Next: Command and Variable Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* ! packet: Packets. (line 49) +* "No symbol "foo" in current context": Variables. (line 122) +* # in Modula-2: GDB/M2. (line 18) +* $: Value History. (line 13) +* $$: Value History. (line 13) +* $_ and info breakpoints: Set Breaks. (line 244) +* $_ and info line: Machine Code. (line 35) +* $_, $__, and value history: Memory. (line 136) +* &, background execution of commands: Background Execution. + (line 16) +* --annotate: Mode Options. (line 110) +* --args: Mode Options. (line 123) +* --attach, gdbserver option: Server. (line 86) +* --batch: Mode Options. (line 33) +* --batch-silent: Mode Options. (line 51) +* --baud: Mode Options. (line 129) +* --cd: Mode Options. (line 90) +* --command: File Options. (line 56) +* --configuration: Mode Options. (line 173) +* --core: File Options. (line 48) +* --data-directory: Mode Options. (line 95) +* --debug, gdbserver option: Server. (line 146) +* --debug-file, gdbserver option: Server. (line 174) +* --debug-format, gdbserver option: Server. (line 178) +* --directory: File Options. (line 92) +* --early-init-command: File Options. (line 82) +* --early-init-eval-command: File Options. (line 87) +* --eval-command: File Options. (line 62) +* --exec: File Options. (line 40) +* --fullname: Mode Options. (line 100) +* --init-command: File Options. (line 72) +* --init-eval-command: File Options. (line 77) +* --interpreter: Mode Options. (line 148) +* --multi, gdbserver option: Connecting. (line 45) +* --nh: Mode Options. (line 15) +* --nowindows: Mode Options. (line 80) +* --nx: Mode Options. (line 11) +* --once, gdbserver option: Server. (line 126) +* --pid: File Options. (line 52) +* --quiet: Mode Options. (line 23) +* --readnever, command-line option: File Options. (line 102) +* --readnow: File Options. (line 96) +* --return-child-result: Mode Options. (line 63) +* --se: File Options. (line 44) +* --selftest: Server. (line 212) +* --silent: Mode Options. (line 23) +* --statistics: Mode Options. (line 165) +* --symbols: File Options. (line 36) +* --tty: Mode Options. (line 138) +* --tui: Mode Options. (line 141) +* --version: Mode Options. (line 169) +* --windows: Mode Options. (line 86) +* --with-gdb-datadir: Data Files. (line 19) +* --with-relocated-sources: Source Path. (line 149) +* --with-sysroot: Files. (line 479) +* --wrapper, gdbserver option: Server. (line 191) +* --write: Mode Options. (line 160) +* -b: Mode Options. (line 129) +* -c: File Options. (line 48) +* -d: File Options. (line 92) +* -D: Mode Options. (line 95) +* -e: File Options. (line 40) +* -eiex: File Options. (line 87) +* -eix: File Options. (line 82) +* -ex: File Options. (line 62) +* -f: Mode Options. (line 100) +* -iex: File Options. (line 77) +* -info-gdb-mi-command: GDB/MI Support Commands. + (line 11) +* -ix: File Options. (line 72) +* -l: Mode Options. (line 133) +* -n: Mode Options. (line 11) +* -nw: Mode Options. (line 80) +* -p: File Options. (line 52) +* -q: Mode Options. (line 23) +* -r: File Options. (line 96) +* -readnever, option for symbol-file command: Files. (line 110) +* -s: File Options. (line 36) +* -t: Mode Options. (line 138) +* -w: Mode Options. (line 86) +* -x: File Options. (line 56) +* ., Modula-2 scope operator: M2 Scope. (line 6) +* .build-id directory: Separate Debug Files. + (line 6) +* .debug subdirectories: Separate Debug Files. + (line 6) +* .debug_gdb_scripts section: dotdebug_gdb_scripts section. + (line 6) +* .debug_names section: Debug Names. (line 6) +* .gdbinit: Initialization Files. + (line 107) +* .gdb_index section: Index Files. (line 6) +* .gdb_index section format: Index Section Format. + (line 6) +* .gnu_debugdata section: MiniDebugInfo. (line 6) +* .gnu_debuglink sections: Separate Debug Files. + (line 86) +* .note.gnu.build-id sections: Separate Debug Files. + (line 102) +* .o files, reading symbols from: Files. (line 158) +* /proc: Process Information. + (line 6) +* : Target Description Format. + (line 72) +* : Target Description Format. + (line 95) +* : Target Description Format. + (line 119) +* : Target Description Format. + (line 163) +* values: Registers. (line 106) +* : Target Description Format. + (line 82) +* : Target Description Format. + (line 222) +* : Target Description Format. + (line 163) +* : Target Description Format. + (line 153) +* : Target Description Format. + (line 146) +* ? packet: Packets. (line 58) +* _NSPrintForDebugger, and printing Objective-C objects: The Print Command with Objective-C. + (line 11) +* {TYPE}: Expressions. (line 41) +* A packet: Packets. (line 66) +* AArch64 Memory Tagging Extension.: AArch64. (line 266) +* AArch64 Pointer Authentication.: AArch64. (line 256) +* AArch64 SME: AArch64. (line 46) +* AArch64 SME2: AArch64. (line 220) +* AArch64 support: AArch64. (line 6) +* AArch64 SVE.: AArch64. (line 19) +* abbreviation: Command Syntax. (line 13) +* acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* active targets: Active Targets. (line 6) +* Ada: Ada. (line 6) +* Ada exception catching: Set Catchpoints. (line 66) +* Ada exception handlers catching: Set Catchpoints. (line 92) +* Ada mode, general: Ada Mode Intro. (line 6) +* Ada task switching: Ada Tasks. (line 129) +* Ada tasking and core file debugging: Ada Tasks and Core Files. + (line 6) +* Ada, deviations from: Additions to Ada. (line 6) +* Ada, omissions from: Omissions from Ada. (line 6) +* Ada, problems: Ada Glitches. (line 6) +* Ada, source character set: Ada Source Character Set. + (line 6) +* Ada, tasking: Ada Tasks. (line 6) +* add new commands for external monitor: Connecting. (line 279) +* address locations: Address Locations. (line 6) +* address of a symbol: Symbols. (line 98) +* address size for remote targets: Remote Configuration. + (line 12) +* addressable memory unit: Memory. (line 150) +* aggregates (Ada): Omissions from Ada. (line 46) +* AIX threads: Debugging Output. (line 33) +* aliases for commands: Aliases. (line 6) +* aliases for commands, default arguments: Command aliases default args. + (line 6) +* alignment of remote memory accesses: Packets. (line 243) +* alignment of remote memory accesses <1>: Packets. (line 532) +* all-stop mode: All-Stop Mode. (line 6) +* Alpha stack: MIPS. (line 6) +* always-read-ctf: Symbols. (line 763) +* ambiguous expressions: Ambiguous Expressions. + (line 6) +* AMD GPU debugging info: Debugging Output. (line 38) +* AMD GPU precise memory event reporting: AMD GPU. (line 165) +* AMD GPU precise memory event reporting <1>: AMD GPU. (line 186) +* AMD GPU support: AMD GPU. (line 6) +* annotations: Annotations Overview. + (line 6) +* annotations for errors, warnings and interrupts: Errors. (line 6) +* annotations for invalidation messages: Invalidation. (line 6) +* annotations for prompts: Prompting. (line 6) +* annotations for running programs: Annotations for Running. + (line 6) +* annotations for source display: Source Annotations. (line 6) +* append data to a file: Dump/Restore Files. (line 6) +* Application Data Integrity: Sparc64. (line 5) +* apply a command to all frames (ignoring errors and empty output): Frame Apply. + (line 96) +* apply a command to all frames of all threads (ignoring errors and empty output): Threads. + (line 236) +* apply command to all threads (ignoring errors and empty output): Threads. + (line 229) +* apply command to several frames: Frame Apply. (line 6) +* apply command to several threads: Threads. (line 194) +* ARC EM: ARC. (line 6) +* ARC HS: ARC. (line 6) +* ARC specific commands: ARC. (line 6) +* ARC600: ARC. (line 6) +* ARC700: ARC. (line 6) +* architecture debugging info: Debugging Output. (line 26) +* argument count in user-defined commands: Define. (line 34) +* arguments (to your program): Arguments. (line 6) +* arguments, to gdbserver: Server. (line 34) +* arguments, to user-defined commands: Define. (line 6) +* ARM 32-bit mode: ARM. (line 16) +* ARM AArch64: Debugging Output. (line 19) +* array aggregates (Ada): Omissions from Ada. (line 46) +* arrays: Arrays. (line 6) +* arrays in expressions: Expressions. (line 13) +* arrays slices (Fortran): Special Fortran Commands. + (line 13) +* artificial array: Arrays. (line 6) +* assembly instructions: Machine Code. (line 44) +* assignment: Assignment. (line 6) +* async output in GDB/MI: GDB/MI Output Syntax. + (line 98) +* async records in GDB/MI: GDB/MI Async Records. + (line 6) +* asynchronous execution: Background Execution. + (line 6) +* asynchronous execution <1>: Asynchronous and non-stop modes. + (line 15) +* asynchronous execution, and process record and replay: Process Record and Replay. + (line 104) +* AT&T disassembly flavor: Machine Code. (line 273) +* attach: Attach. (line 6) +* attach to a program, gdbserver: Server. (line 86) +* auto-loading: Auto-loading. (line 6) +* auto-loading extensions: Auto-loading extensions. + (line 6) +* auto-loading init file in the current directory: Init File in the Current Directory. + (line 6) +* auto-loading libthread_db.so.1: libthread_db.so.1 file. + (line 6) +* auto-loading safe-path: Auto-loading safe path. + (line 6) +* auto-loading verbose mode: Auto-loading verbose mode. + (line 6) +* auto-retry, for remote TCP target: Remote Configuration. + (line 131) +* automatic display: Auto Display. (line 6) +* automatic hardware breakpoints: Set Breaks. (line 405) +* automatic overlay debugging: Automatic Overlay Debugging. + (line 6) +* automatic symbol index cache: Index Files. (line 76) +* automatic thread selection: All-Stop Mode. (line 28) +* auxiliary vector: OS Information. (line 9) +* AVR: AVR. (line 6) +* b packet: Packets. (line 75) +* B packet: Packets. (line 90) +* background execution: Background Execution. + (line 6) +* background execution <1>: Asynchronous and non-stop modes. + (line 15) +* backtrace beyond main function: Backtrace. (line 155) +* backtrace limit: Backtrace. (line 192) +* base name differences: Files. (line 546) +* baud rate for remote targets: Remote Configuration. + (line 21) +* bc packet: Packets. (line 95) +* bcache statistics: Maintenance Commands. + (line 584) +* bits in remote address: Remote Configuration. + (line 12) +* blocks in guile: Blocks In Guile. (line 6) +* blocks in python: Blocks In Python. (line 6) +* bookmark: Checkpoint/Restart. (line 6) +* branch trace configuration format: Branch Trace Configuration Format. + (line 6) +* branch trace format: Branch Trace Format. + (line 6) +* branch trace store: Process Record and Replay. + (line 73) +* break in overloaded functions: Debugging C Plus Plus. + (line 9) +* break on a system call.: Set Catchpoints. (line 120) +* break on fork/exec: Set Catchpoints. (line 116) +* BREAK signal instead of Ctrl-C: Remote Configuration. + (line 36) +* breakpoint address adjusted: Breakpoint-related Warnings. + (line 6) +* breakpoint at static probe point: Linespec Locations. (line 65) +* breakpoint commands: Break Commands. (line 6) +* breakpoint commands for GDB/MI: GDB/MI Breakpoint Commands. + (line 6) +* breakpoint commands, in remote protocol: General Query Packets. + (line 1072) +* breakpoint conditions: Conditions. (line 6) +* breakpoint debugging info: Debugging Output. (line 326) +* breakpoint kinds, ARM: ARM Breakpoint Kinds. + (line 6) +* breakpoint kinds, MIPS: MIPS Breakpoint Kinds. + (line 6) +* breakpoint lists: Breakpoints. (line 45) +* breakpoint numbers: Breakpoints. (line 38) +* breakpoint on events: Breakpoints. (line 30) +* breakpoint on memory address: Breakpoints. (line 17) +* breakpoint on variable modification: Breakpoints. (line 17) +* breakpoint ranges: Breakpoints. (line 45) +* breakpoint subroutine, remote: Stub Contents. (line 31) +* breakpointing Ada elaboration code: Stopping Before Main Program. + (line 6) +* breakpoints: Breakpoints. (line 6) +* breakpoints and inferiors: Inferior-Specific Breakpoints. + (line 9) +* breakpoints and tasks, in Ada: Ada Tasks. (line 181) +* breakpoints and threads: Thread-Specific Breakpoints. + (line 10) +* breakpoints at functions matching a regexp: Set Breaks. (line 201) +* breakpoints in guile: Breakpoints In Guile. + (line 6) +* breakpoints in overlays: Overlay Commands. (line 91) +* breakpoints in python: Breakpoints In Python. + (line 6) +* breakpoints, multiple locations: Set Breaks. (line 311) +* bs packet: Packets. (line 101) +* bug criteria: Bug Criteria. (line 6) +* bug reports: Bug Reporting. (line 6) +* bugs in GDB: GDB Bugs. (line 6) +* build ID sections: Separate Debug Files. + (line 102) +* build ID, and separate debugging files: Separate Debug Files. + (line 6) +* building GDB, requirements for: Requirements. (line 6) +* built-in simulator target: Target Commands. (line 79) +* builtin Go functions: Go. (line 31) +* builtin Go types: Go. (line 28) +* C and C++: C. (line 6) +* C and C++ checks: C Checks. (line 6) +* C and C++ constants: C Constants. (line 6) +* C and C++ defaults: C Defaults. (line 6) +* C and C++ operators: C Operators. (line 6) +* c packet: Packets. (line 108) +* C packet: Packets. (line 117) +* C++: C. (line 10) +* C++ compilers: C Plus Plus Expressions. + (line 8) +* C++ demangling: Debugging C Plus Plus. + (line 36) +* C++ exception handling: Debugging C Plus Plus. + (line 20) +* C++ overload debugging info: Debugging Output. (line 221) +* C++ scope resolution: Variables. (line 90) +* C++ symbol decoding style: Print Settings. (line 587) +* C++ symbol display: Debugging C Plus Plus. + (line 40) +* caching data of targets: Caching Target Data. + (line 6) +* caching of bfd objects: File Caching. (line 6) +* caching of opened files: File Caching. (line 6) +* call dummy stack unwinding: Calling. (line 36) +* call dummy stack unwinding on timeout.: Calling. (line 65) +* call dummy stack unwinding on unhandled exception.: Calling. + (line 53) +* call overloaded functions: C Plus Plus Expressions. + (line 26) +* call stack: Stack. (line 9) +* call stack traces: Backtrace. (line 6) +* call-clobbered registers: Registers. (line 106) +* caller-saved registers: Registers. (line 106) +* calling functions: Calling. (line 6) +* calling functions in the program, disabling: Calling. (line 76) +* calling make: Shell Commands. (line 25) +* case sensitivity in symbol names: Symbols. (line 27) +* case-insensitive symbol names: Symbols. (line 27) +* casts, in expressions: Expressions. (line 26) +* casts, to view memory: Expressions. (line 41) +* catch Ada exceptions: Set Catchpoints. (line 66) +* catch Ada exceptions when handled: Set Catchpoints. (line 92) +* catch syscalls from inferior, remote request: General Query Packets. + (line 439) +* catchpoints: Breakpoints. (line 30) +* catchpoints, setting: Set Catchpoints. (line 6) +* change GDB's working directory: Working Directory. (line 32) +* change inferior's working directory: Working Directory. (line 13) +* character sets: Character Sets. (line 6) +* charset: Character Sets. (line 6) +* check if a given address is in a memory tagged region: General Query Packets. + (line 332) +* checkpoint: Checkpoint/Restart. (line 6) +* checkpoints and process id: Checkpoint/Restart. (line 76) +* checks, range: Type Checking. (line 44) +* checks, type: Checks. (line 23) +* checksum, for GDB remote: Overview. (line 21) +* choosing target byte order: Byte Order. (line 6) +* circular trace buffer: Starting and Stopping Trace Experiments. + (line 80) +* clearing breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* CLI commands in python: CLI Commands In Python. + (line 6) +* close, file-i/o system call: close. (line 6) +* closest symbol and offset for an address: Symbols. (line 108) +* code address and its source line: Machine Code. (line 29) +* code compression, MIPS: MIPS. (line 49) +* code location: Location Specifications. + (line 6) +* COFF/PE exported symbols: Debugging Output. (line 82) +* collected data discarded: Starting and Stopping Trace Experiments. + (line 6) +* colon, doubled as scope operator: M2 Scope. (line 6) +* colon-colon, context for variables/functions: Variables. (line 44) +* colors: Output Styling. (line 6) +* command editing: Readline Bare Essentials. + (line 6) +* command files: Command Files. (line 6) +* command history: Command History. (line 6) +* command hooks: Hooks. (line 6) +* command interpreters: Interpreters. (line 6) +* command line editing: Editing. (line 6) +* command options: Command Options. (line 6) +* command options, boolean: Command Options. (line 21) +* command options, raw input: Command Options. (line 13) +* command scripts, debugging: Messages/Warnings. (line 65) +* command tracing: Messages/Warnings. (line 60) +* commands for C++: Debugging C Plus Plus. + (line 6) +* commands in guile: Commands In Guile. (line 6) +* commands in python, CLI: CLI Commands In Python. + (line 6) +* commands in python, GDB/MI: GDB/MI Commands In Python. + (line 6) +* commands to access guile: Guile Commands. (line 6) +* commands to access python: Python Commands. (line 6) +* comment: Command Syntax. (line 37) +* COMMON blocks, Fortran: Special Fortran Commands. + (line 9) +* common targets: Target Commands. (line 46) +* compatibility, GDB/MI and CLI: GDB/MI Compatibility with CLI. + (line 6) +* compilation directory: Source Path. (line 40) +* compile C++ type conversion: Compiling and Injecting Code. + (line 93) +* compile command debugging info: Compiling and Injecting Code. + (line 85) +* compile command driver filename override: Compiling and Injecting Code. + (line 303) +* compile command options override: Compiling and Injecting Code. + (line 128) +* compiling code: Compiling and Injecting Code. + (line 6) +* completion: Completion. (line 6) +* completion of Guile commands: Commands In Guile. (line 100) +* completion of Python commands: CLI Commands In Python. + (line 72) +* completion of quoted strings: Completion. (line 94) +* completion of structure field names: Completion. (line 146) +* completion of union field names: Completion. (line 146) +* compressed debug sections: Requirements. (line 113) +* conditional breakpoints: Conditions. (line 6) +* conditional tracepoints: Tracepoint Conditions. + (line 6) +* configure debuginfod URLs: Debuginfod Settings. + (line 31) +* configuring GDB: Running Configure. (line 6) +* confirmation: Messages/Warnings. (line 49) +* connection timeout, for remote TCP target: Remote Configuration. + (line 147) +* connections in python: Connections In Python. + (line 6) +* console i/o as part of file-i/o: Console I/O. (line 6) +* console interpreter: Interpreters. (line 21) +* console output in GDB/MI: GDB/MI Output Syntax. + (line 106) +* constants, in file-i/o protocol: Constants. (line 6) +* continuing: Continuing and Stepping. + (line 6) +* continuing threads: Thread Stops. (line 6) +* control C, and remote debugging: Bootstrapping. (line 25) +* controlling terminal: Input/Output. (line 23) +* convenience functions: Convenience Funs. (line 6) +* convenience functions in python: Functions In Python. + (line 6) +* convenience variables: Convenience Vars. (line 6) +* convenience variables for tracepoints: Tracepoint Variables. + (line 6) +* convenience variables, and trace state variables: Trace State Variables. + (line 17) +* convenience variables, initializing: Convenience Vars. (line 42) +* core dump file: Files. (line 6) +* core dump file target: Target Commands. (line 57) +* crash of debugger: Bug Criteria. (line 9) +* CRC algorithm definition: Separate Debug Files. + (line 147) +* CRC of memory block, remote request: General Query Packets. + (line 65) +* CRIS: CRIS. (line 6) +* CRIS mode: CRIS. (line 26) +* CRIS version: CRIS. (line 10) +* CTF info, when to read: Symbols. (line 763) +* Ctrl-BREAK, MS-Windows: Cygwin Native. (line 9) +* ctrl-c message, in file-i/o protocol: The Ctrl-C Message. (line 6) +* current Ada task ID: Ada Tasks. (line 119) +* current directory: Source Path. (line 40) +* current Go package: Go. (line 11) +* current thread: Threads. (line 29) +* current thread, remote request: General Query Packets. + (line 55) +* custom JIT debug info: Custom Debug Info. (line 6) +* Cygwin DLL, debugging: Cygwin Native. (line 60) +* Cygwin-specific commands: Cygwin Native. (line 6) +* D: D. (line 6) +* d packet: Packets. (line 126) +* D packet: Packets. (line 133) +* DAP: Interpreters. (line 26) +* Darwin: Darwin. (line 6) +* data breakpoints: Breakpoints. (line 17) +* data manipulation, in GDB/MI: GDB/MI Data Manipulation. + (line 6) +* dcache line-size: Caching Target Data. + (line 60) +* dcache size: Caching Target Data. + (line 57) +* dcache, flushing: Caching Target Data. + (line 71) +* dead names, GNU Hurd: Hurd Native. (line 84) +* debug expression parser: Debugging Output. (line 228) +* debug formats and C++: C Plus Plus Expressions. + (line 8) +* debug link sections: Separate Debug Files. + (line 86) +* debug remote protocol: Debugging Output. (line 236) +* Debugger Adapter Protocol: Interpreters. (line 26) +* debugger crash: Bug Criteria. (line 9) +* debugging agent: In-Process Agent. (line 6) +* debugging C++ programs: C Plus Plus Expressions. + (line 8) +* debugging information directory, global: Separate Debug Files. + (line 6) +* debugging information in separate files: Separate Debug Files. + (line 6) +* debugging libthread_db: Threads. (line 338) +* debugging multiple processes: Forks. (line 55) +* debugging optimized code: Optimized Code. (line 6) +* debugging stub, example: Remote Stub. (line 6) +* debugging target: Targets. (line 6) +* debugging the Cygwin DLL: Cygwin Native. (line 60) +* debugging threads: Threads. (line 343) +* debuginfod: Debuginfod. (line 6) +* debuginfod verbosity: Debuginfod Settings. + (line 41) +* debuginfod, maintenance commands: Maintenance Commands. + (line 241) +* decimal floating point format: Decimal Floating Point. + (line 6) +* default behavior of commands, changing: Command Settings. (line 6) +* default collection action: Tracepoint Actions. (line 142) +* default data directory: Data Files. (line 19) +* default settings, changing: Command Settings. (line 6) +* default source path substitution: Source Path. (line 149) +* default system root: Files. (line 479) +* define trace state variable, remote request: Tracepoint Packets. + (line 117) +* defining macros interactively: Macros. (line 60) +* definition of a macro, showing: Macros. (line 47) +* delete breakpoints: Delete Breaks. (line 56) +* deleting breakpoints, watchpoints, catchpoints: Delete Breaks. + (line 6) +* deliver a signal to a program: Signaling. (line 6) +* demangle: Symbols. (line 127) +* demangler crashes: Maintenance Commands. + (line 190) +* demangler crashes <1>: Maintenance Commands. + (line 217) +* demangler crashes <2>: Maintenance Commands. + (line 249) +* demangling C++ names: Print Settings. (line 568) +* deprecated commands: Maintenance Commands. + (line 204) +* derived type of an object, printing: Print Settings. (line 599) +* descriptor tables display: DJGPP Native. (line 24) +* detach from task, GNU Hurd: Hurd Native. (line 59) +* detach from thread, GNU Hurd: Hurd Native. (line 109) +* direct memory access (DMA) on MS-DOS: DJGPP Native. (line 74) +* directories for source files: Source Path. (line 6) +* directory, compilation: Source Path. (line 40) +* directory, current: Source Path. (line 40) +* disable address space randomization, remote request: General Query Packets. + (line 82) +* disabling calling functions in the program: Calling. (line 76) +* disassembler in Python, global vs. specific: Disassembly In Python. + (line 466) +* disassembler options: Machine Code. (line 258) +* disconnected tracing: Starting and Stopping Trace Experiments. + (line 45) +* displaced stepping debugging info: Debugging Output. (line 111) +* displaced stepping support: Maintenance Commands. + (line 156) +* displaced stepping, and process record and replay: Process Record and Replay. + (line 99) +* display command history: Command History. (line 110) +* display derived types: Print Settings. (line 599) +* display disabled out of scope: Auto Display. (line 86) +* display GDB copyright: Help. (line 174) +* display of expressions: Auto Display. (line 6) +* display remote monitor communications: Target Commands. (line 113) +* display remote packets: Debugging Output. (line 236) +* DJGPP debugging: DJGPP Native. (line 6) +* DLLs with no debugging symbols: Non-debug DLL Symbols. + (line 6) +* do not print frame arguments: Print Settings. (line 200) +* documentation: Formatting Documentation. + (line 22) +* don't repeat command: Define. (line 127) +* don't repeat Guile command: Commands In Guile. (line 67) +* don't repeat Python command: CLI Commands In Python. + (line 42) +* DOS file-name semantics of file names.: Files. (line 502) +* DOS serial data link, remote debugging: DJGPP Native. (line 118) +* DOS serial port status: DJGPP Native. (line 139) +* DPMI: DJGPP Native. (line 6) +* dprintf: Dynamic Printf. (line 6) +* dump all data collected at tracepoint: tdump. (line 6) +* dump core from inferior: Core File Generation. + (line 6) +* dump data to a file: Dump/Restore Files. (line 6) +* dump/restore files: Dump/Restore Files. (line 6) +* DVC register: PowerPC Embedded. (line 6) +* DWARF compilation units cache: Maintenance Commands. + (line 662) +* DWARF DIEs: Debugging Output. (line 89) +* DWARF frame unwinders: Maintenance Commands. + (line 693) +* DWARF Line Tables: Debugging Output. (line 95) +* DWARF Reading: Debugging Output. (line 103) +* DWARF-2 CFI and CRIS: CRIS. (line 18) +* dynamic linking: Files. (line 132) +* dynamic printf: Dynamic Printf. (line 6) +* dynamic varobj: GDB/MI Variable Objects. + (line 163) +* early initialization: Initialization Files. + (line 14) +* early initialization file: Startup. (line 10) +* editing: Editing. (line 15) +* editing command lines: Readline Bare Essentials. + (line 6) +* editing source files: Edit. (line 6) +* eight-bit characters in strings: Print Settings. (line 513) +* elaboration phase: Starting. (line 92) +* ELinOS system-wide configuration script: System-wide Configuration Scripts. + (line 15) +* Emacs: Emacs. (line 6) +* empty response, for unsupported packets: Standard Replies. (line 11) +* enable debuginfod: Debuginfod Settings. + (line 10) +* enable/disable a breakpoint: Disabling. (line 6) +* enabling and disabling probes: Static Probe Points. + (line 52) +* entering numbers: Numbers. (line 6) +* environment (of your program): Environment. (line 6) +* errno values, in file-i/o protocol: Errno Values. (line 6) +* error on valid input: Bug Criteria. (line 12) +* event debugging info: Debugging Output. (line 118) +* event designators: Event Designators. (line 6) +* event handling: Set Catchpoints. (line 6) +* event-loop debugging: Debugging Output. (line 124) +* examine process image: Process Information. + (line 6) +* examining data: Data. (line 6) +* examining memory: Memory. (line 9) +* exception handlers: Set Catchpoints. (line 6) +* exceptions, guile: Guile Exception Handling. + (line 6) +* exceptions, python: Exception Handling. (line 6) +* exec events, remote reply: Stop Reply Packets. (line 141) +* executable file: Files. (line 16) +* executable file target: Target Commands. (line 50) +* executable file, for remote target: Remote Configuration. + (line 102) +* execute commands from a file: Command Files. (line 17) +* execute forward or backward in time: Reverse Execution. (line 92) +* execute remote command, remote request: General Query Packets. + (line 613) +* execution, foreground, background and asynchronous: Background Execution. + (line 6) +* execution, foreground, background and asynchronous <1>: Asynchronous and non-stop modes. + (line 15) +* exit status of shell commands: Convenience Vars. (line 192) +* exiting GDB: Quitting GDB. (line 6) +* expand macro once: Macros. (line 38) +* expanding preprocessor macros: Macros. (line 29) +* explicit locations: Explicit Locations. (line 6) +* explore type: Data. (line 254) +* explore value: Data. (line 247) +* exploring hierarchical data structures: Data. (line 145) +* expression debugging info: Debugging Output. (line 133) +* expression parser, debugging info: Debugging Output. (line 228) +* expressions: Expressions. (line 6) +* expressions in Ada: Ada. (line 11) +* expressions in C or C++: C. (line 6) +* expressions in C++: C Plus Plus Expressions. + (line 6) +* expressions in Modula-2: Modula-2. (line 12) +* extend GDB for remote targets: Connecting. (line 279) +* extending GDB: Extending GDB. (line 6) +* extra signal information: Signals. (line 158) +* F packet: Packets. (line 147) +* F reply packet: The F Reply Packet. (line 6) +* F request packet: The F Request Packet. + (line 6) +* fast tracepoints: Set Tracepoints. (line 24) +* fast tracepoints, setting: Create and Delete Tracepoints. + (line 50) +* fatal signal: Bug Criteria. (line 9) +* fatal signals: Signals. (line 15) +* features of the remote protocol: General Query Packets. + (line 659) +* fetch memory tags: General Query Packets. + (line 312) +* file name canonicalization: Files. (line 546) +* file names, quoting and escaping: Filename Arguments. (line 6) +* file transfer: File Transfer. (line 6) +* file transfer, remote protocol: Host I/O Packets. (line 6) +* file-i/o examples: File-I/O Examples. (line 6) +* file-i/o overview: File-I/O Overview. (line 6) +* File-I/O remote protocol extension: File-I/O Remote Protocol Extension. + (line 6) +* file-i/o reply packet: The F Reply Packet. (line 6) +* file-i/o request packet: The F Request Packet. + (line 6) +* filename-display: Backtrace. (line 202) +* find trace snapshot: tfind. (line 6) +* flinching: Messages/Warnings. (line 49) +* float promotion: ABI. (line 34) +* floating point: Floating Point Hardware. + (line 6) +* floating point registers: Registers. (line 15) +* floating point, MIPS remote: MIPS Embedded. (line 13) +* focus of debugging: Threads. (line 29) +* foo: Symbol Errors. (line 54) +* foreground execution: Background Execution. + (line 6) +* foreground execution <1>: Asynchronous and non-stop modes. + (line 15) +* fork events, remote reply: Stop Reply Packets. (line 104) +* fork, debugging programs which call: Forks. (line 6) +* format options: Print Settings. (line 6) +* formatted output: Output Formats. (line 6) +* Fortran: Summary. (line 40) +* fortran array slicing debugging info: Debugging Output. (line 151) +* Fortran Defaults: Fortran. (line 14) +* Fortran Intrinsics: Fortran Intrinsics. (line 6) +* Fortran modules, information about: Symbols. (line 589) +* Fortran operators and expressions: Fortran Operators. (line 6) +* Fortran Types: Fortran Types. (line 6) +* Fortran-specific support in GDB: Fortran. (line 6) +* frame debugging info: Debugging Output. (line 159) +* frame decorator api: Frame Decorator API. + (line 6) +* frame filters api: Frame Filter API. (line 6) +* frame information, printing: Print Settings. (line 360) +* frame level: Frames. (line 28) +* frame number: Frames. (line 28) +* frame pointer: Frames. (line 21) +* frame pointer register: Registers. (line 31) +* frame, definition: Frames. (line 6) +* frameless execution: Frames. (line 34) +* frames in guile: Frames In Guile. (line 6) +* frames in python: Frames In Python. (line 6) +* frames of inlined functions: Maintenance Commands. + (line 369) +* free memory information (MS-DOS): DJGPP Native. (line 19) +* FreeBSD: FreeBSD. (line 6) +* FreeBSD LWP debug messages: Debugging Output. (line 140) +* FreeBSD native target debug messages: Debugging Output. (line 146) +* fstat, file-i/o system call: stat/fstat. (line 6) +* Fujitsu: Remote Stub. (line 68) +* full symbol tables, listing GDB's internal: Symbols. (line 684) +* function call arguments, optimized out: Backtrace. (line 133) +* function entry/exit, wrong values of variables: Variables. (line 106) +* functions and variables by Fortran module: Symbols. (line 589) +* functions without line info, and stepping: Continuing and Stepping. + (line 92) +* g packet: Packets. (line 152) +* G packet: Packets. (line 187) +* g++, GNU C++ compiler: C. (line 10) +* garbled pointers: DJGPP Native. (line 42) +* GCC and C++: C Plus Plus Expressions. + (line 8) +* GDB bugs, reporting: Bug Reporting. (line 6) +* GDB internal error: Maintenance Commands. + (line 249) +* gdb module: Basic Python. (line 31) +* gdb objects: GDB Scheme Data Types. + (line 6) +* GDB reference card: Formatting Documentation. + (line 6) +* GDB startup: Startup. (line 6) +* GDB version number: Help. (line 164) +* gdb.ini: Initialization Files. + (line 107) +* gdb.printing: gdb.printing. (line 6) +* gdb.prompt: gdb.prompt. (line 6) +* gdb.ptwrite: gdb.ptwrite. (line 6) +* gdb.types: gdb.types. (line 6) +* gdb.Value: Values From Inferior. + (line 6) +* GDB/MI development: GDB/MI Development and Front Ends. + (line 6) +* GDB/MI General Design: GDB/MI General Design. + (line 6) +* GDB/MI, async records: GDB/MI Async Records. + (line 6) +* GDB/MI, breakpoint commands: GDB/MI Breakpoint Commands. + (line 6) +* GDB/MI, compatibility with CLI: GDB/MI Compatibility with CLI. + (line 6) +* GDB/MI, data manipulation: GDB/MI Data Manipulation. + (line 6) +* GDB/MI, input syntax: GDB/MI Input Syntax. + (line 6) +* GDB/MI, its purpose: GDB/MI. (line 36) +* GDB/MI, output syntax: GDB/MI Output Syntax. + (line 6) +* GDB/MI, result records: GDB/MI Result Records. + (line 6) +* GDB/MI, simple examples: GDB/MI Simple Examples. + (line 6) +* GDB/MI, stream records: GDB/MI Stream Records. + (line 6) +* gdbarch debugging info: Debugging Output. (line 26) +* GDBHISTFILE, environment variable: Command History. (line 26) +* GDBHISTSIZE, environment variable: Command History. (line 56) +* gdbinit: Initialization Files. + (line 107) +* gdbserver, command-line arguments: Server. (line 34) +* gdbserver, connecting: Connecting. (line 6) +* gdbserver, search path for libthread_db: Server. (line 295) +* gdbserver, send all debug output to a single file: Server. (line 174) +* gdbserver, target extended-remote mode: Connecting. (line 6) +* gdbserver, target remote mode: Connecting. (line 6) +* gdbserver, types of connections: Connecting. (line 6) +* GDT: DJGPP Native. (line 24) +* general initialization: Initialization Files. + (line 30) +* get thread information block address: General Query Packets. + (line 281) +* get thread-local storage address, remote request: General Query Packets. + (line 257) +* gettimeofday, file-i/o system call: gettimeofday. (line 6) +* getting structure elements using gdb.Field objects as subscripts: Values From Inferior. + (line 40) +* global debugging information directories: Separate Debug Files. + (line 6) +* global thread identifier (GDB): Threads. (line 88) +* global thread number: Threads. (line 88) +* GNAT descriptive types: Ada Glitches. (line 57) +* GNAT encoding: Ada Glitches. (line 57) +* GNU C++: C. (line 10) +* GNU Emacs: Emacs. (line 6) +* GNU Hurd debugging: Hurd Native. (line 6) +* GNU/Hurd debug messages: Debugging Output. (line 165) +* GNU/Linux namespaces debug messages: Debugging Output. (line 195) +* GNU/Linux native target debug messages: Debugging Output. (line 189) +* Go (programming language): Go. (line 6) +* guile api: Guile API. (line 6) +* guile architectures: Architectures In Guile. + (line 6) +* guile auto-loading: Guile Auto-loading. (line 6) +* guile commands: Guile Commands. (line 6) +* guile commands <1>: Commands In Guile. (line 6) +* guile configuration: Guile Configuration. + (line 6) +* guile exceptions: Guile Exception Handling. + (line 6) +* guile gdb module: Basic Guile. (line 37) +* guile iterators: Iterators In Guile. (line 6) +* guile modules: Guile Modules. (line 6) +* guile pagination: Basic Guile. (line 6) +* guile parameters: Parameters In Guile. + (line 6) +* guile pretty printing api: Guile Pretty Printing API. + (line 6) +* guile scripting: Guile. (line 6) +* guile scripts directory: Guile Introduction. (line 15) +* guile stdout: Basic Guile. (line 6) +* guile, working with types: Types In Guile. (line 6) +* guile, working with values from inferior: Values From Inferior In Guile. + (line 6) +* H packet: Packets. (line 195) +* handling signals: Signals. (line 27) +* hardware breakpoints: Set Breaks. (line 172) +* hardware debug registers: Maintenance Commands. + (line 743) +* hardware watchpoints: Set Watchpoints. (line 31) +* hash mark while downloading: Target Commands. (line 104) +* heuristic-fence-post (Alpha, MIPS): MIPS. (line 14) +* history events: Event Designators. (line 8) +* history expansion: History Interaction. + (line 6) +* history expansion, turn on/off: Command History. (line 85) +* history file: Command History. (line 26) +* history number: Value History. (line 13) +* history of values printed by GDB: Value History. (line 6) +* history size: Command History. (line 56) +* history substitution: Command History. (line 26) +* hooks, for commands: Hooks. (line 6) +* hooks, post-command: Hooks. (line 11) +* hooks, pre-command: Hooks. (line 6) +* host character set: Character Sets. (line 6) +* Host I/O, remote protocol: Host I/O Packets. (line 6) +* how many arguments (user-defined commands): Define. (line 34) +* HPPA support: HPPA. (line 6) +* i packet: Packets. (line 207) +* I packet: Packets. (line 212) +* i/o: Input/Output. (line 6) +* I/O registers (Atmel AVR): AVR. (line 10) +* i386: Remote Stub. (line 56) +* i386-stub.c: Remote Stub. (line 56) +* ID list: Inferiors Connections and Programs. + (line 25) +* IDT: DJGPP Native. (line 24) +* ignore count (of breakpoint): Conditions. (line 85) +* in-process agent protocol: In-Process Agent Protocol. + (line 6) +* incomplete type: Symbols. (line 367) +* indentation in structure display: Print Settings. (line 475) +* index files: Index Files. (line 6) +* index files <1>: Debug Names. (line 6) +* index section format: Index Section Format. + (line 6) +* inferior: Inferiors Connections and Programs. + (line 15) +* inferior debugging info: Debugging Output. (line 170) +* inferior events in Python: Events In Python. (line 6) +* inferior function call debugging info: Debugging Output. (line 178) +* inferior functions, calling: Calling. (line 6) +* inferior tty: Input/Output. (line 44) +* inferior-specific breakpoints: Inferior-Specific Breakpoints. + (line 9) +* inferiors in Python: Inferiors In Python. + (line 6) +* infinite recursion in user-defined commands: Define. (line 144) +* info for known .debug_gdb_scripts-loaded scripts: Maintenance Commands. + (line 577) +* info for known object files: Maintenance Commands. + (line 562) +* info line, repeated calls: Machine Code. (line 41) +* info proc cmdline: Process Information. + (line 41) +* info proc cwd: Process Information. + (line 45) +* info proc exe: Process Information. + (line 49) +* info proc files: Process Information. + (line 53) +* information about static tracepoint markers: Listing Static Tracepoint Markers. + (line 6) +* information about tracepoints: Listing Tracepoints. + (line 6) +* inheritance: Debugging C Plus Plus. + (line 26) +* init file: Startup. (line 23) +* init file name: Initialization Files. + (line 6) +* initial frame: Frames. (line 12) +* initialization file: Initialization Files. + (line 34) +* initialization file, readline: Readline Init File. (line 6) +* injecting code: Compiling and Injecting Code. + (line 6) +* inline functions, debugging: Inline Functions. (line 6) +* innermost frame: Frames. (line 12) +* input syntax for GDB/MI: GDB/MI Input Syntax. + (line 6) +* installation: Installing GDB. (line 6) +* instructions, assembly: Machine Code. (line 44) +* integral datatypes, in file-i/o protocol: Integral Datatypes. + (line 6) +* Intel: Remote Stub. (line 56) +* Intel disassembly flavor: Machine Code. (line 273) +* Intel Processor Trace: Process Record and Replay. + (line 78) +* interaction, readline: Readline Interaction. + (line 6) +* internal commands: Maintenance Commands. + (line 6) +* internal errors, control of GDB behavior: Maintenance Commands. + (line 249) +* internal GDB breakpoints: Set Breaks. (line 483) +* interrupt: Quitting GDB. (line 15) +* interrupt debuggee on MS-Windows: Cygwin Native. (line 9) +* interrupt remote programs: Remote Configuration. + (line 36) +* interrupt remote programs <1>: Remote Configuration. + (line 108) +* interrupting remote programs: Connecting. (line 246) +* interrupting remote targets: Bootstrapping. (line 25) +* interrupts (remote protocol): Interrupts. (line 6) +* invalid input: Bug Criteria. (line 16) +* invoke another interpreter: Interpreters. (line 44) +* ipa protocol commands: IPA Protocol Commands. + (line 6) +* ipa protocol objects: IPA Protocol Objects. + (line 6) +* isatty, file-i/o system call: isatty. (line 6) +* JIT compilation interface: JIT Interface. (line 6) +* JIT debug info reader: Custom Debug Info. (line 6) +* just-in-time compilation: JIT Interface. (line 6) +* just-in-time compilation, debugging messages: Debugging Output. + (line 184) +* k packet: Packets. (line 216) +* kernel crash dump: BSD libkvm Interface. + (line 6) +* kernel memory image: BSD libkvm Interface. + (line 6) +* kill ring: Readline Killing Commands. + (line 18) +* killing text: Readline Killing Commands. + (line 6) +* languages: Languages. (line 6) +* last tracepoint number: Create and Delete Tracepoints. + (line 124) +* latest breakpoint: Set Breaks. (line 6) +* lazy strings in guile: Lazy Strings In Guile. + (line 6) +* lazy strings in python: Lazy Strings In Python. + (line 6) +* LDT: DJGPP Native. (line 24) +* leaving GDB: Quitting GDB. (line 6) +* libkvm: BSD libkvm Interface. + (line 6) +* library list format, remote protocol: Library List Format. + (line 6) +* library list format, remote protocol <1>: Library List Format for SVR4 Targets. + (line 6) +* limit hardware breakpoints and watchpoints: Remote Configuration. + (line 79) +* limit hardware watchpoints length: Remote Configuration. + (line 91) +* limit on number of printed array elements: Print Settings. (line 179) +* limit on number of printed string characters: Print Settings. + (line 159) +* limits, in file-i/o protocol: Limits. (line 6) +* line tables in python: Line Tables In Python. + (line 6) +* line tables, listing GDB's internal: Symbols. (line 731) +* linespec locations: Linespec Locations. (line 6) +* Linux native targets: Debugging Output. (line 189) +* list active threads, remote request: General Query Packets. + (line 224) +* list of supported file-i/o calls: List of Supported Calls. + (line 6) +* list output in GDB/MI: GDB/MI Output Syntax. + (line 117) +* list, how many lines to display: List. (line 40) +* listing GDB's internal line tables: Symbols. (line 731) +* listing GDB's internal symbol tables: Symbols. (line 684) +* listing machine instructions: Machine Code. (line 44) +* listing mapped overlays: Overlay Commands. (line 60) +* lists of breakpoints: Breakpoints. (line 45) +* load address, overlay's: How Overlays Work. (line 6) +* load shared library: Files. (line 353) +* load symbols from memory: Files. (line 210) +* local socket, target remote: Connecting. (line 147) +* local variables: Symbols. (line 436) +* locate address: Output Formats. (line 36) +* location resolution: Location Specifications. + (line 14) +* location spec: Location Specifications. + (line 6) +* lock scheduler: All-Stop Mode. (line 37) +* locspec: Location Specifications. + (line 6) +* log output in GDB/MI: GDB/MI Output Syntax. + (line 113) +* logging file name: Logging Output. (line 10) +* logging GDB output: Logging Output. (line 6) +* look up of disassembler in Python: Disassembly In Python. + (line 466) +* lseek flags, in file-i/o protocol: Lseek Flags. (line 6) +* lseek, file-i/o system call: lseek. (line 6) +* m packet: Packets. (line 239) +* M packet: Packets. (line 264) +* m680x0: Remote Stub. (line 59) +* m68k-stub.c: Remote Stub. (line 59) +* Mach-O symbols processing: Debugging Output. (line 201) +* machine instructions: Machine Code. (line 44) +* macro definition, showing: Macros. (line 47) +* macro expansion, showing the results of preprocessor: Macros. + (line 29) +* macros, example of debugging with: Macros. (line 84) +* macros, from debug info: Macros. (line 47) +* macros, user-defined: Macros. (line 60) +* mailing lists: GDB/MI Development and Front Ends. + (line 93) +* maintenance commands: Maintenance Commands. + (line 6) +* Man pages: Man Pages. (line 6) +* managing frame filters: Frame Filter Management. + (line 6) +* manual overlay debugging: Overlay Commands. (line 23) +* map an overlay: Overlay Commands. (line 30) +* mapped address: How Overlays Work. (line 6) +* mapped overlays: How Overlays Work. (line 6) +* markers, static tracepoints: Set Tracepoints. (line 28) +* maximum value for offset of closest symbol: Print Settings. + (line 70) +* member functions: C Plus Plus Expressions. + (line 16) +* memory address space mappings: Process Information. + (line 80) +* memory address space mappings <1>: Maintenance Commands. + (line 332) +* memory map format: Memory Map Format. (line 6) +* memory region attributes: Memory Region Attributes. + (line 6) +* memory tag types, ARM: ARM Memory Tag Types. + (line 6) +* memory tracing: Breakpoints. (line 17) +* memory transfer, in file-i/o protocol: Memory Transfer. (line 6) +* memory used by commands: Maintenance Commands. + (line 895) +* memory used for symbol tables: Files. (line 341) +* memory, alignment and size of remote accesses: Packets. (line 243) +* memory, alignment and size of remote accesses <1>: Packets. + (line 532) +* memory, viewing as typed object: Expressions. (line 41) +* MI commands in python: GDB/MI Commands In Python. + (line 6) +* mi interpreter: Interpreters. (line 34) +* MI notifications in python: GDB/MI Notifications In Python. + (line 6) +* mi2 interpreter: Interpreters. (line 42) +* mi3 interpreter: Interpreters. (line 39) +* minimal language: Unsupported Languages. + (line 6) +* minimal symbol dump: Symbols. (line 658) +* Minimal symbols and DLLs: Non-debug DLL Symbols. + (line 6) +* MIPS addresses, masking: MIPS. (line 80) +* MIPS remote floating point: MIPS Embedded. (line 13) +* MIPS stack: MIPS. (line 6) +* miscellaneous settings: Other Misc Settings. + (line 6) +* MMX registers (x86): Registers. (line 76) +* mode_t values, in file-i/o protocol: mode_t Values. (line 6) +* Modula-2: Summary. (line 29) +* Modula-2 built-ins: Built-In Func/Proc. (line 6) +* Modula-2 checks: M2 Checks. (line 6) +* Modula-2 constants: Built-In Func/Proc. (line 117) +* Modula-2 defaults: M2 Defaults. (line 6) +* Modula-2 operators: M2 Operators. (line 6) +* Modula-2 types: M2 Types. (line 6) +* Modula-2, deviations from: Deviations. (line 6) +* Modula-2, GDB support: Modula-2. (line 6) +* module functions and variables: Symbols. (line 589) +* modules: Symbols. (line 581) +* monitor commands, for gdbserver: Server. (line 243) +* Motorola 680x0: Remote Stub. (line 59) +* MS Windows debugging: Cygwin Native. (line 6) +* MS-DOS system info: DJGPP Native. (line 19) +* MS-DOS-specific commands: DJGPP Native. (line 6) +* multiple locations, breakpoints: Set Breaks. (line 311) +* multiple processes: Forks. (line 6) +* multiple targets: Active Targets. (line 6) +* multiple threads: Threads. (line 6) +* multiple threads, backtrace: Backtrace. (line 97) +* multiple-symbols menu: Ambiguous Expressions. + (line 51) +* multiprocess extensions, in remote protocol: General Query Packets. + (line 1002) +* name a thread: Threads. (line 254) +* names of symbols: Symbols. (line 14) +* namespace in C++: C Plus Plus Expressions. + (line 20) +* native Cygwin debugging: Cygwin Native. (line 6) +* native DJGPP debugging: DJGPP Native. (line 6) +* native script auto-loading: Auto-loading sequences. + (line 6) +* native target: Target Commands. (line 91) +* negative breakpoint numbers: Set Breaks. (line 483) +* never read symbols: Files. (line 110) +* New SYSTAG message: Threads. (line 35) +* new user interface: Interpreters. (line 73) +* Newlib OS ABI and its influence on the longjmp handling: ABI. + (line 11) +* no debug info functions: Calling. (line 181) +* no debug info variables: Variables. (line 142) +* non-member C++ functions, set breakpoint in: Set Breaks. (line 224) +* non-stop mode: Non-Stop Mode. (line 6) +* non-stop mode, and process record and replay: Process Record and Replay. + (line 104) +* non-stop mode, and set displaced-stepping: Maintenance Commands. + (line 173) +* non-stop mode, remote request: General Query Packets. + (line 425) +* noninvasive task options: Hurd Native. (line 72) +* notation, readline: Readline Bare Essentials. + (line 6) +* notational conventions, for GDB/MI: GDB/MI. (line 52) +* notification packets: Notification Packets. + (line 6) +* notifications in python, GDB/MI: GDB/MI Notifications In Python. + (line 6) +* notify output in GDB/MI: GDB/MI Output Syntax. + (line 102) +* NULL elements in arrays: Print Settings. (line 466) +* number of array elements to print: Print Settings. (line 179) +* number of string characters to print: Print Settings. (line 159) +* number representation: Numbers. (line 6) +* numbers for breakpoints: Breakpoints. (line 38) +* object files, relocatable, reading symbols from: Files. (line 158) +* Objective-C: Objective-C. (line 6) +* Objective-C, classes and selectors: Symbols. (line 609) +* Objective-C, print objects: The Print Command with Objective-C. + (line 6) +* OBJFILE-gdb.gdb: objfile-gdbdotext file. + (line 6) +* OBJFILE-gdb.py: objfile-gdbdotext file. + (line 6) +* OBJFILE-gdb.scm: objfile-gdbdotext file. + (line 6) +* objfiles in guile: Objfiles In Guile. (line 6) +* objfiles in python: Objfiles In Python. (line 6) +* observer debugging info: Debugging Output. (line 215) +* octal escapes in strings: Print Settings. (line 513) +* online documentation: Help. (line 6) +* opaque data types: Symbols. (line 621) +* open flags, in file-i/o protocol: Open Flags. (line 6) +* open, file-i/o system call: open. (line 6) +* OpenCL C: OpenCL C. (line 6) +* OpenCL C Datatypes: OpenCL C Datatypes. (line 6) +* OpenCL C Expressions: OpenCL C Expressions. + (line 6) +* OpenCL C Operators: OpenCL C Operators. (line 6) +* OpenRISC 1000: OpenRISC 1000. (line 6) +* operate-and-get-next: Editing. (line 32) +* operating system information: Operating System Information. + (line 6) +* operating system information, process list: Process list. (line 6) +* optimized code, debugging: Optimized Code. (line 6) +* optimized code, wrong values of variables: Variables. (line 106) +* optimized out value in guile: Values From Inferior In Guile. + (line 102) +* optimized out value in Python: Values From Inferior. + (line 75) +* optimized out, in backtrace: Backtrace. (line 133) +* optional debugging messages: Debugging Output. (line 6) +* optional warnings: Messages/Warnings. (line 6) +* OS ABI: ABI. (line 11) +* OS information: OS Information. (line 6) +* out-of-line single-stepping: Maintenance Commands. + (line 156) +* outermost frame: Frames. (line 12) +* output formats: Output Formats. (line 6) +* output syntax of GDB/MI: GDB/MI Output Syntax. + (line 6) +* overlay area: How Overlays Work. (line 6) +* overlay example program: Overlay Sample Program. + (line 6) +* overlays: Overlays. (line 6) +* overlays, setting breakpoints in: Overlay Commands. (line 91) +* overloaded functions, calling: C Plus Plus Expressions. + (line 26) +* overloaded functions, overload resolution: Debugging C Plus Plus. + (line 59) +* overloading in C++: Debugging C Plus Plus. + (line 15) +* overloading, Ada: Overloading support for Ada. + (line 6) +* p packet: Packets. (line 274) +* P packet: Packets. (line 283) +* packet acknowledgment, for GDB remote: Packet Acknowledgment. + (line 6) +* packet size, remote protocol: General Query Packets. + (line 908) +* packet size, remote, configuring: Remote Configuration. + (line 349) +* packets, notification: Notification Packets. + (line 6) +* packets, reporting on stdout: Debugging Output. (line 236) +* packets, tracepoint: Tracepoint Packets. (line 6) +* page size: Screen Size. (line 6) +* page tables display (MS-DOS): DJGPP Native. (line 55) +* pagination: Screen Size. (line 6) +* parameters in guile: Parameters In Guile. + (line 6) +* parameters in python: Parameters In Python. + (line 6) +* partial symbol dump: Symbols. (line 658) +* partial symbol tables, listing GDB's internal: Symbols. (line 684) +* Pascal: Summary. (line 35) +* Pascal objects, static members display: Print Settings. (line 628) +* Pascal support in GDB, limitations: Pascal. (line 6) +* pass signals to inferior, remote request: General Query Packets. + (line 471) +* patching binaries: Patching. (line 6) +* patching object files: Files. (line 29) +* pause current task (GNU Hurd): Hurd Native. (line 48) +* pause current thread (GNU Hurd): Hurd Native. (line 90) +* pauses in output: Screen Size. (line 6) +* pending breakpoints: Set Breaks. (line 353) +* physical address from linear address: DJGPP Native. (line 80) +* physname: Debugging Output. (line 72) +* pipe, target remote to: Connecting. (line 234) +* pipes: Starting. (line 64) +* pointer values, in file-i/o protocol: Pointer Values. (line 6) +* pointer, finding referent: Print Settings. (line 80) +* port rights, GNU Hurd: Hurd Native. (line 84) +* port sets, GNU Hurd: Hurd Native. (line 84) +* PowerPC architecture: PowerPC. (line 6) +* prefix for data files: Data Files. (line 6) +* prefix for executable and shared library file names: Files. + (line 412) +* premature return from system calls: Interrupted System Calls. + (line 6) +* preprocessor macro expansion, showing the results of: Macros. + (line 29) +* pretty print arrays: Print Settings. (line 115) +* pretty print C++ virtual function tables: Print Settings. (line 639) +* pretty-printer commands: Pretty-Printer Commands. + (line 6) +* print all frame argument values: Print Settings. (line 200) +* print an Objective-C object description: The Print Command with Objective-C. + (line 11) +* print array indexes: Print Settings. (line 125) +* print binary values in groups of four bits: Print Settings. + (line 141) +* print frame argument values for scalars only: Print Settings. + (line 200) +* print list of auto-loaded canned sequences of commands scripts: Auto-loading sequences. + (line 21) +* print list of auto-loaded Guile scripts: Guile Auto-loading. + (line 23) +* print list of auto-loaded Python scripts: Python Auto-loading. + (line 23) +* print messages on inferior start and exit: Inferiors Connections and Programs. + (line 188) +* print messages on thread start and exit: Threads. (line 279) +* print messages when symbols are loaded: Symbols. (line 639) +* print settings: Print Settings. (line 6) +* print structures in indented form: Print Settings. (line 475) +* print/don't print memory addresses: Print Settings. (line 13) +* printing byte arrays: Output Formats. (line 62) +* printing data: Data. (line 6) +* printing frame argument values: Print Settings. (line 200) +* printing frame information: Print Settings. (line 360) +* printing memory tag violation information: Print Settings. (line 453) +* printing nested structures: Print Settings. (line 408) +* printing strings: Output Formats. (line 62) +* probe static tracepoint marker: Create and Delete Tracepoints. + (line 75) +* probing markers, static tracepoints: Set Tracepoints. (line 28) +* process detailed status information: Process Information. + (line 89) +* process ID: Process Information. + (line 25) +* process info via /proc: Process Information. + (line 6) +* process record and replay: Process Record and Replay. + (line 6) +* process status register: Registers. (line 31) +* processes, multiple: Forks. (line 6) +* procfs API calls: Process Information. + (line 106) +* profiling GDB: Maintenance Commands. + (line 727) +* program counter register: Registers. (line 31) +* program entry point: Backtrace. (line 155) +* programming in guile: Guile API. (line 6) +* programming in python: Python API. (line 6) +* progspaces in guile: Progspaces In Guile. + (line 6) +* progspaces in python: Progspaces In Python. + (line 6) +* prologue-end: Symbols. (line 794) +* prompt: Prompt. (line 6) +* protocol basics, file-i/o: Protocol Basics. (line 6) +* protocol, GDB remote serial: Overview. (line 14) +* protocol-specific representation of datatypes, in file-i/o protocol: Protocol-specific Representation of Datatypes. + (line 6) +* python api: Python API. (line 6) +* Python architectures: Architectures In Python. + (line 6) +* Python auto-loading: Python Auto-loading. + (line 6) +* python commands: Python Commands. (line 6) +* python commands, CLI: CLI Commands In Python. + (line 6) +* python commands, GDB/MI: GDB/MI Commands In Python. + (line 6) +* python convenience functions: Functions In Python. + (line 6) +* python directory: Python. (line 10) +* python exceptions: Exception Handling. (line 6) +* python finish breakpoints: Finish Breakpoints in Python. + (line 6) +* python functions: Basic Python. (line 31) +* python instruction disassembly: Disassembly In Python. + (line 6) +* python module: Basic Python. (line 31) +* python modules: Python modules. (line 6) +* python notifications, GDB/MI: GDB/MI Notifications In Python. + (line 6) +* python pagination: Basic Python. (line 6) +* python parameters: Parameters In Python. + (line 6) +* python pretty printing api: Pretty Printing API. + (line 6) +* python scripting: Python. (line 6) +* python stdout: Basic Python. (line 6) +* Python TUI Windows: TUI Windows In Python. + (line 6) +* python, handle missing debug information: Missing Debug Info In Python. + (line 6) +* python, handle missing objfiles: Missing Objfiles In Python. + (line 6) +* Python, working with types: Types In Python. (line 6) +* python, working with values from inferior: Values From Inferior. + (line 6) +* q packet: Packets. (line 293) +* Q packet: Packets. (line 293) +* QAllow packet: General Query Packets. + (line 44) +* qAttached packet: General Query Packets. + (line 1493) +* qC packet: General Query Packets. + (line 55) +* QCatchSyscalls packet: General Query Packets. + (line 439) +* qCRC packet: General Query Packets. + (line 65) +* QDisableRandomization packet: General Query Packets. + (line 82) +* QEnvironmentHexEncoded packet: General Query Packets. + (line 130) +* QEnvironmentReset packet: General Query Packets. + (line 183) +* QEnvironmentUnset packet: General Query Packets. + (line 159) +* qfThreadInfo packet: General Query Packets. + (line 224) +* qGetTIBAddr packet: General Query Packets. + (line 281) +* qGetTLSAddr packet: General Query Packets. + (line 257) +* qIsAddressTagged packet: General Query Packets. + (line 332) +* qMemTags packet: General Query Packets. + (line 312) +* QMemTags packet: General Query Packets. + (line 350) +* QNonStop packet: General Query Packets. + (line 425) +* qOffsets packet: General Query Packets. + (line 388) +* qP packet: General Query Packets. + (line 415) +* QPassSignals packet: General Query Packets. + (line 471) +* QProgramSignals packet: General Query Packets. + (line 492) +* qRcmd packet: General Query Packets. + (line 613) +* qSearch memory packet: General Query Packets. + (line 637) +* QSetWorkingDir packet: General Query Packets. + (line 205) +* QStartNoAckMode packet: General Query Packets. + (line 648) +* QStartupWithShell packet: General Query Packets. + (line 104) +* qsThreadInfo packet: General Query Packets. + (line 224) +* qSupported packet: General Query Packets. + (line 659) +* qSymbol packet: General Query Packets. + (line 1159) +* qTBuffer packet: Tracepoint Packets. (line 380) +* QTBuffer size packet: Tracepoint Packets. (line 393) +* QTDisable packet: Tracepoint Packets. (line 202) +* QTDisconnected packet: Tracepoint Packets. (line 221) +* QTDP packet: Tracepoint Packets. (line 10) +* QTDPsrc packet: Tracepoint Packets. (line 86) +* QTDV packet: Tracepoint Packets. (line 117) +* QTEnable packet: Tracepoint Packets. (line 197) +* qTfP packet: Tracepoint Packets. (line 328) +* QTFrame packet: Tracepoint Packets. (line 129) +* qTfSTM packet: Tracepoint Packets. (line 345) +* qTfV packet: Tracepoint Packets. (line 336) +* QThreadEvents packet: General Query Packets. + (line 524) +* qThreadExtraInfo packet: General Query Packets. + (line 1202) +* QThreadOptions packet: General Query Packets. + (line 548) +* QTinit packet: Tracepoint Packets. (line 207) +* qTMinFTPILen packet: Tracepoint Packets. (line 167) +* QTNotes packet: Tracepoint Packets. (line 398) +* qTP packet: Tracepoint Packets. (line 300) +* QTro packet: Tracepoint Packets. (line 210) +* QTSave packet: Tracepoint Packets. (line 374) +* qTsP packet: Tracepoint Packets. (line 329) +* qTsSTM packet: Tracepoint Packets. (line 345) +* QTStart packet: Tracepoint Packets. (line 188) +* qTStatus packet: Tracepoint Packets. (line 227) +* qTSTMat packet: Tracepoint Packets. (line 368) +* QTStop packet: Tracepoint Packets. (line 194) +* qTsV packet: Tracepoint Packets. (line 337) +* qTV packet: Tracepoint Packets. (line 311) +* qualified thread ID: Threads. (line 52) +* query attached, remote request: General Query Packets. + (line 1493) +* quotes in commands: Completion. (line 94) +* quoting Ada internal identifiers: Additions to Ada. (line 86) +* quoting names: Symbols. (line 14) +* qXfer packet: General Query Packets. + (line 1239) +* r packet: Packets. (line 297) +* R packet: Packets. (line 302) +* range checking: Type Checking. (line 45) +* range stepping: Continuing and Stepping. + (line 217) +* ranged breakpoint: PowerPC Embedded. (line 33) +* ranges of breakpoints: Breakpoints. (line 45) +* Ravenscar Profile: Ravenscar Profile. (line 6) +* Ravenscar thread: Ravenscar Profile. (line 26) +* raw printing: Output Formats. (line 77) +* read special object, remote request: General Query Packets. + (line 1239) +* read, file-i/o system call: read. (line 6) +* read-only sections: Files. (line 292) +* reading symbols from relocatable object files: Files. (line 158) +* reading symbols immediately: Files. (line 103) +* readline: Editing. (line 6) +* Readline application name: Editing. (line 29) +* receive rights, GNU Hurd: Hurd Native. (line 84) +* recent tracepoint number: Create and Delete Tracepoints. + (line 124) +* record aggregates (Ada): Omissions from Ada. (line 46) +* record mode: Process Record and Replay. + (line 19) +* record serial communications on file: Remote Configuration. + (line 64) +* recording a session script: Bug Reporting. (line 93) +* recording inferior's execution and replaying it: Process Record and Replay. + (line 6) +* recordings in python: Recordings In Python. + (line 6) +* redirection: Input/Output. (line 6) +* reference card: Formatting Documentation. + (line 6) +* reference declarations: C Plus Plus Expressions. + (line 50) +* register cache, flushing: Maintenance Commands. + (line 544) +* register packet format, MIPS: MIPS Register packet Format. + (line 6) +* registers: Registers. (line 6) +* Registers In Python: Registers In Python. + (line 6) +* regular expression: Set Breaks. (line 201) +* reloading the overlay table: Overlay Commands. (line 52) +* relocatable object files, reading symbols from: Files. (line 158) +* remote async notification debugging info: Debugging Output. + (line 208) +* remote connection commands: Connecting. (line 127) +* remote connection without stubs: Server. (line 6) +* remote debugging: Remote Debugging. (line 6) +* remote debugging, connecting: Connecting. (line 6) +* remote debugging, detach and program exit: Connecting. (line 19) +* remote debugging, symbol files: Connecting. (line 97) +* remote debugging, types of connections: Connecting. (line 6) +* remote memory comparison: Memory. (line 159) +* remote packets, enabling and disabling: Remote Configuration. + (line 159) +* remote packets, standard replies: Standard Replies. (line 6) +* remote programs, interrupting: Connecting. (line 246) +* remote protocol debugging: Debugging Output. (line 236) +* remote protocol, binary data: Overview. (line 63) +* remote protocol, field separator: Overview. (line 55) +* remote query requests: General Query Packets. + (line 6) +* remote serial debugging summary: Debug Session. (line 6) +* remote serial debugging, overview: Remote Stub. (line 14) +* remote serial protocol: Overview. (line 14) +* remote serial stub: Stub Contents. (line 6) +* remote serial stub list: Remote Stub. (line 53) +* remote serial stub, initialization: Stub Contents. (line 10) +* remote serial stub, main routine: Stub Contents. (line 15) +* remote stub, example: Remote Stub. (line 6) +* remote stub, support routines: Bootstrapping. (line 6) +* remote target: Target Commands. (line 64) +* remote target, file transfer: File Transfer. (line 6) +* remote target, limit break- and watchpoints: Remote Configuration. + (line 79) +* remote target, limit watchpoints length: Remote Configuration. + (line 91) +* remote timeout: Remote Configuration. + (line 72) +* remove actions from a tracepoint: Tracepoint Actions. (line 21) +* remove duplicate history: Command History. (line 69) +* rename, file-i/o system call: rename. (line 6) +* Renesas: Remote Stub. (line 62) +* repeated array elements: Print Settings. (line 394) +* repeating command sequences: Command Syntax. (line 41) +* repeating commands: Command Syntax. (line 21) +* replay log events, remote reply: Stop Reply Packets. (line 70) +* replay mode: Process Record and Replay. + (line 10) +* reporting bugs in GDB: GDB Bugs. (line 6) +* reprint the last value: Data. (line 128) +* reprint the last value <1>: Compiling and Injecting Code. + (line 77) +* reset environment, remote request: General Query Packets. + (line 183) +* resolution of location spec: Location Specifications. + (line 14) +* resources used by commands: Maintenance Commands. + (line 807) +* response time, MIPS debugging: MIPS. (line 10) +* restart: Checkpoint/Restart. (line 6) +* restore data from a file: Dump/Restore Files. (line 6) +* restrictions on Go expressions: Go. (line 35) +* result records in GDB/MI: GDB/MI Result Records. + (line 6) +* resume threads of multiple processes simultaneously: All-Stop Mode. + (line 68) +* resuming execution: Continuing and Stepping. + (line 6) +* returning from a function: Returning. (line 6) +* reverse execution: Reverse Execution. (line 6) +* rewind program state: Checkpoint/Restart. (line 6) +* run to first instruction: Starting. (line 114) +* run to main procedure: Starting. (line 81) +* run until specified location: Continuing and Stepping. + (line 124) +* running: Starting. (line 6) +* running programs backward: Reverse Execution. (line 6) +* s packet: Packets. (line 309) +* S packet: Packets. (line 318) +* S12Z support: S12Z. (line 6) +* save breakpoints to a file for future sessions: Save Breakpoints. + (line 9) +* save command history: Command History. (line 44) +* save GDB output to a file: Logging Output. (line 6) +* save tracepoints for future sessions: save tracepoints. (line 6) +* Scalable Matrix Extension: AArch64. (line 46) +* Scalable Matrix Extension 2: AArch64. (line 220) +* scheduler locking mode: All-Stop Mode. (line 37) +* scheduler-locking: All-Stop Mode. (line 37) +* scope: M2 Scope. (line 6) +* screen size: Screen Size. (line 6) +* scripting commands: Command Files. (line 6) +* scripting with guile: Guile. (line 6) +* scripting with python: Python. (line 6) +* search for a thread: Threads. (line 265) +* search order for disassembler in Python: Disassembly In Python. + (line 466) +* search path for libthread_db: Threads. (line 300) +* searching memory: Searching Memory. (line 6) +* searching memory, in remote debugging: General Query Packets. + (line 637) +* searching source files: Search. (line 6) +* section offsets, remote request: General Query Packets. + (line 388) +* segment descriptor tables: DJGPP Native. (line 24) +* select Ctrl-C, BREAK or BREAK-g: Remote Configuration. + (line 108) +* select trace snapshot: tfind. (line 6) +* selected frame: Stack. (line 19) +* selecting guile pretty-printers: Selecting Guile Pretty-Printers. + (line 6) +* selecting python pretty-printers: Selecting Pretty-Printers. + (line 6) +* self tests: Maintenance Commands. + (line 624) +* self tests <1>: Maintenance Commands. + (line 630) +* self tests <2>: Maintenance Commands. + (line 634) +* semaphores on static probe points: Static Probe Points. + (line 20) +* send command to remote monitor: Connecting. (line 279) +* send command to simulator: Embedded Processors. + (line 9) +* send interrupt-sequence on start: Remote Configuration. + (line 121) +* send rights, GNU Hurd: Hurd Native. (line 84) +* send the output of a gdb command to a shell command: Shell Commands. + (line 29) +* sending files to remote systems: File Transfer. (line 6) +* separate debug sections: MiniDebugInfo. (line 6) +* separate debugging information files: Separate Debug Files. + (line 6) +* sequence-id, for GDB remote: Overview. (line 30) +* serial connections, debugging: Debugging Output. (line 236) +* serial line, target remote: Connecting. (line 136) +* serial protocol, GDB remote: Overview. (line 14) +* server prefix: Server Prefix. (line 6) +* server, command prefix: Command History. (line 20) +* set ABI for MIPS: MIPS. (line 32) +* set breakpoints in many functions: Set Breaks. (line 201) +* set breakpoints on all functions: Set Breaks. (line 228) +* set environment variable, remote request: General Query Packets. + (line 130) +* set exec-file-mismatch: Attach. (line 34) +* set fast tracepoint: Create and Delete Tracepoints. + (line 50) +* set inferior controlling terminal: Input/Output. (line 44) +* set static tracepoint: Create and Delete Tracepoints. + (line 75) +* set tdesc filename: Retrieving Descriptions. + (line 18) +* set tracepoint: Create and Delete Tracepoints. + (line 6) +* set working directory, remote request: General Query Packets. + (line 205) +* setting variables: Assignment. (line 6) +* setting watchpoints: Set Watchpoints. (line 6) +* settings: Command Settings. (line 39) +* SH: Remote Stub. (line 62) +* sh-stub.c: Remote Stub. (line 62) +* shared libraries: Files. (line 314) +* shared library events, remote reply: Stop Reply Packets. (line 65) +* shell command, exit code: Convenience Vars. (line 192) +* shell command, exit signal: Convenience Vars. (line 192) +* shell escape: Shell Commands. (line 10) +* show all convenience functions: Convenience Funs. (line 280) +* show all user variables and functions: Convenience Vars. (line 37) +* show exec-file-mismatch: Attach. (line 44) +* show inferior's working directory: Working Directory. (line 27) +* show last commands: Command History. (line 110) +* show screen characteristics: Maintenance Commands. + (line 891) +* show tdesc filename: Retrieving Descriptions. + (line 25) +* signals: Signals. (line 6) +* signals the inferior may see, remote request: General Query Packets. + (line 492) +* SIGQUIT signal, dump core of GDB: Maintenance Commands. + (line 213) +* SingleKey keymap name: TUI Single Key Mode. + (line 71) +* size of remote memory accesses: Packets. (line 243) +* size of remote memory accesses <1>: Packets. (line 532) +* size of screen: Screen Size. (line 6) +* skipping over files via glob-style patterns: Skipping Over Functions and Files. + (line 55) +* skipping over functions and files: Skipping Over Functions and Files. + (line 6) +* skipping over functions via regular expressions: Skipping Over Functions and Files. + (line 68) +* SME: AArch64. (line 46) +* SME2: AArch64. (line 220) +* snapshot of a process: Checkpoint/Restart. (line 6) +* software watchpoints: Set Watchpoints. (line 31) +* source code, caching: Maintenance Commands. + (line 551) +* source code, disable access: Disable Reading Source. + (line 6) +* source file and line of a symbol: Print Settings. (line 50) +* source line and its code address: Machine Code. (line 6) +* source location: Location Specifications. + (line 6) +* source path: Source Path. (line 6) +* Sparc: Remote Stub. (line 65) +* sparc-stub.c: Remote Stub. (line 65) +* Sparc64 support: Sparc64. (line 6) +* sparcl-stub.c: Remote Stub. (line 68) +* SparcLite: Remote Stub. (line 68) +* Special Fortran commands: Special Fortran Commands. + (line 6) +* specifying location: Location Specifications. + (line 6) +* SSE registers (x86): Registers. (line 76) +* stack frame: Frames. (line 6) +* stack on Alpha: MIPS. (line 6) +* stack on MIPS: MIPS. (line 6) +* stack pointer register: Registers. (line 31) +* stacking targets: Active Targets. (line 6) +* standard registers: Registers. (line 31) +* standard responses for remote packets: Standard Replies. (line 6) +* start a new independent interpreter: Interpreters. (line 57) +* start a new trace experiment: Starting and Stopping Trace Experiments. + (line 6) +* starting: Starting. (line 6) +* startup code, and backtrace: Backtrace. (line 155) +* startup with shell, remote request: General Query Packets. + (line 104) +* stat, file-i/o system call: stat/fstat. (line 6) +* static members of C++ objects: Print Settings. (line 617) +* static members of Pascal objects: Print Settings. (line 628) +* static probe point, DTrace: Static Probe Points. + (line 6) +* static probe point, SystemTap: Static Probe Points. + (line 6) +* static tracepoints: Set Tracepoints. (line 28) +* static tracepoints, in remote protocol: General Query Packets. + (line 1050) +* static tracepoints, setting: Create and Delete Tracepoints. + (line 75) +* status of trace data collection: Starting and Stopping Trace Experiments. + (line 27) +* status output in GDB/MI: GDB/MI Output Syntax. + (line 94) +* stepping: Continuing and Stepping. + (line 6) +* stepping and signal handlers: Signals. (line 108) +* stepping into functions with no line info: Continuing and Stepping. + (line 92) +* stop a running trace experiment: Starting and Stopping Trace Experiments. + (line 16) +* stop on C++ exceptions: Set Catchpoints. (line 16) +* stop reply packets: Stop Reply Packets. (line 6) +* stopped threads: Thread Stops. (line 6) +* store memory tags: General Query Packets. + (line 350) +* stream records in GDB/MI: GDB/MI Stream Records. + (line 6) +* string tracing, in remote protocol: General Query Packets. + (line 1067) +* struct gdb_reader_funcs: Writing JIT Debug Info Readers. + (line 22) +* struct gdb_symbol_callbacks: Writing JIT Debug Info Readers. + (line 43) +* struct gdb_unwind_callbacks: Writing JIT Debug Info Readers. + (line 43) +* struct return convention: x86. (line 7) +* struct stat, in file-i/o protocol: struct stat. (line 6) +* struct timeval, in file-i/o protocol: struct timeval. (line 6) +* struct/union returned in registers: x86. (line 7) +* structure field name completion: Completion. (line 146) +* stub example, remote debugging: Remote Stub. (line 6) +* stupid questions: Messages/Warnings. (line 49) +* styling: Output Styling. (line 6) +* Super-H: Super-H. (line 6) +* supported GDB/MI features, list: GDB/MI Support Commands. + (line 54) +* supported packets, remote query: General Query Packets. + (line 659) +* svg: AArch64. (line 88) +* svl: AArch64. (line 81) +* svq: AArch64. (line 85) +* switching threads: Threads. (line 6) +* switching threads automatically: All-Stop Mode. (line 28) +* symbol cache size: Symbols. (line 770) +* symbol cache, flushing: Symbols. (line 786) +* symbol cache, printing its contents: Symbols. (line 778) +* symbol cache, printing usage statistics: Symbols. (line 782) +* symbol decoding style, C++: Print Settings. (line 587) +* symbol dump: Symbols. (line 658) +* symbol file functions: Debugging Output. (line 284) +* symbol files, remote debugging: Connecting. (line 97) +* symbol from address: Symbols. (line 108) +* symbol lookup: Debugging Output. (line 276) +* symbol lookup, remote request: General Query Packets. + (line 1159) +* symbol names: Symbols. (line 14) +* symbol table: Files. (line 6) +* symbol table creation: Debugging Output. (line 290) +* symbol tables in guile: Symbol Tables In Guile. + (line 6) +* symbol tables in python: Symbol Tables In Python. + (line 6) +* symbol tables, listing GDB's internal: Symbols. (line 684) +* symbol, source file and line: Print Settings. (line 50) +* symbols in guile: Symbols In Guile. (line 6) +* symbols in python: Symbols In Python. (line 6) +* symbols, never read: Files. (line 110) +* symbols, reading from relocatable object files: Files. (line 158) +* symbols, reading immediately: Files. (line 103) +* Synopsys ARC: ARC. (line 6) +* syscall DSO: Files. (line 210) +* system calls and thread breakpoints: Interrupted System Calls. + (line 6) +* system root, alternate: Files. (line 412) +* system, file-i/o system call: system. (line 6) +* system-wide configuration scripts: System-wide Configuration Scripts. + (line 6) +* system-wide init file: System-wide configuration. + (line 6) +* t packet: Packets. (line 328) +* T packet: Packets. (line 333) +* T packet reply: Stop Reply Packets. (line 26) +* tail call frames, debugging: Tail Call Frames. (line 6) +* target architecture: Targets. (line 17) +* target byte order: Byte Order. (line 6) +* target character set: Character Sets. (line 6) +* target debugging info: Debugging Output. (line 298) +* target descriptions: Target Descriptions. + (line 6) +* target descriptions, AArch64 features: AArch64 Features. (line 5) +* target descriptions, ARC Features: ARC Features. (line 6) +* target descriptions, ARM features: ARM Features. (line 5) +* target descriptions, enum types: Enum Target Types. (line 6) +* target descriptions, i386 features: i386 Features. (line 6) +* target descriptions, inclusion: Target Description Format. + (line 53) +* target descriptions, LoongArch Features: LoongArch Features. + (line 6) +* target descriptions, M68K features: M68K Features. (line 6) +* target descriptions, MicroBlaze features: MicroBlaze Features. + (line 6) +* target descriptions, MIPS features: MIPS Features. (line 6) +* target descriptions, NDS32 features: NDS32 Features. (line 6) +* target descriptions, OpenRISC 1000 features: OpenRISC 1000 Features. + (line 6) +* target descriptions, PowerPC features: PowerPC Features. (line 6) +* target descriptions, predefined types: Predefined Target Types. + (line 6) +* target descriptions, RISC-V Features: RISC-V Features. (line 6) +* target descriptions, RX Features: RX Features. (line 6) +* target descriptions, S/390 features: S/390 and System z Features. + (line 6) +* target descriptions, sparc32 features: Sparc Features. (line 6) +* target descriptions, sparc64 features: Sparc Features. (line 6) +* target descriptions, standard features: Standard Target Features. + (line 6) +* target descriptions, System z features: S/390 and System z Features. + (line 6) +* target descriptions, TIC6x features: TIC6x Features. (line 6) +* target descriptions, TMS320C6x features: TIC6x Features. (line 6) +* target descriptions, XML format: Target Description Format. + (line 6) +* target memory comparison: Memory. (line 159) +* target output in GDB/MI: GDB/MI Output Syntax. + (line 110) +* target stack description: Maintenance Commands. + (line 597) +* target-assisted range stepping: Continuing and Stepping. + (line 217) +* task attributes (GNU Hurd): Hurd Native. (line 48) +* task breakpoints, in Ada: Ada Tasks. (line 181) +* task exception port, GNU Hurd: Hurd Native. (line 67) +* task suspend count: Hurd Native. (line 59) +* task switching with program using Ravenscar Profile: Ravenscar Profile. + (line 10) +* TCP port, target remote: Connecting. (line 173) +* temporarily change settings: Command Settings. (line 39) +* terminal: Input/Output. (line 6) +* Text User Interface: TUI. (line 6) +* thread attributes info, remote request: General Query Packets. + (line 1202) +* thread breakpoints: Thread-Specific Breakpoints. + (line 10) +* thread breakpoints and system calls: Interrupted System Calls. + (line 6) +* thread clone events, remote reply: Stop Reply Packets. (line 152) +* thread create event, remote reply: Stop Reply Packets. (line 161) +* thread create/exit events, remote request: General Query Packets. + (line 524) +* thread default settings, GNU Hurd: Hurd Native. (line 130) +* thread exit event, remote reply: Stop Reply Packets. (line 190) +* thread ID lists: Threads. (line 65) +* thread identifier (GDB): Threads. (line 47) +* thread identifier (system): Threads. (line 35) +* thread info (Solaris): Threads. (line 174) +* thread information, remote request: General Query Packets. + (line 415) +* thread list format: Thread List Format. (line 6) +* thread number, per inferior: Threads. (line 47) +* thread options, remote request: General Query Packets. + (line 548) +* thread properties, GNU Hurd: Hurd Native. (line 90) +* thread suspend count, GNU Hurd: Hurd Native. (line 109) +* THREAD-ID, in remote protocol: Packets. (line 20) +* threads and watchpoints: Set Watchpoints. (line 182) +* threads in python: Threads In Python. (line 6) +* threads of execution: Threads. (line 6) +* threads, automatic switching: All-Stop Mode. (line 28) +* threads, continuing: Thread Stops. (line 6) +* threads, stopped: Thread Stops. (line 6) +* time of command execution: Maintenance Commands. + (line 899) +* timeout for called functions: Calling. (line 138) +* timeout for called functions <1>: Calling. (line 151) +* timeout for called functions <2>: Calling. (line 160) +* timeout for called functions <3>: Calling. (line 175) +* timeout for commands: Maintenance Commands. + (line 989) +* timeout for serial communications: Remote Configuration. + (line 72) +* timeout, for remote target connection: Remote Configuration. + (line 147) +* timestamping debugging info: Debugging Output. (line 306) +* trace experiment, status of: Starting and Stopping Trace Experiments. + (line 27) +* trace file format: Trace File Format. (line 6) +* trace files: Trace Files. (line 6) +* trace state variable value, remote request: Tracepoint Packets. + (line 311) +* trace state variables: Trace State Variables. + (line 6) +* traceback: Backtrace. (line 6) +* traceframe info format: Traceframe Info Format. + (line 6) +* tracepoint actions: Tracepoint Actions. (line 6) +* tracepoint conditions: Tracepoint Conditions. + (line 6) +* tracepoint data, display: tdump. (line 6) +* tracepoint deletion: Create and Delete Tracepoints. + (line 127) +* tracepoint number: Create and Delete Tracepoints. + (line 124) +* tracepoint packets: Tracepoint Packets. (line 6) +* tracepoint pass count: Tracepoint Passcounts. + (line 6) +* tracepoint restrictions: Tracepoint Restrictions. + (line 6) +* tracepoint status, remote request: Tracepoint Packets. (line 300) +* tracepoint variables: Tracepoint Variables. + (line 6) +* tracepoints: Tracepoints. (line 6) +* tracepoints support in gdbserver: Server. (line 313) +* trailing underscore, in Fortran symbols: Fortran. (line 9) +* translating between character sets: Character Sets. (line 6) +* TUI: TUI. (line 6) +* TUI commands: TUI Commands. (line 6) +* TUI configuration variables: TUI Configuration. (line 6) +* TUI key bindings: TUI Keys. (line 6) +* TUI mouse support: TUI Mouse Support. (line 6) +* TUI single key mode: TUI Single Key Mode. + (line 6) +* type casting memory: Expressions. (line 41) +* type chain of a data type: Maintenance Commands. + (line 609) +* type checking: Checks. (line 24) +* type conversions in C++: C Plus Plus Expressions. + (line 26) +* type printer: Type Printing API. (line 9) +* type printing API for Python: Type Printing API. (line 6) +* types in guile: Types In Guile. (line 6) +* types in Python: Types In Python. (line 6) +* UDP port, target remote: Connecting. (line 222) +* union field name completion: Completion. (line 146) +* unions in structures, printing: Print Settings. (line 527) +* Unix domain socket: Connecting. (line 147) +* unknown address, locating: Output Formats. (line 36) +* unknown type: Symbols. (line 384) +* unlink, file-i/o system call: unlink. (line 6) +* unlinked object files: Files. (line 29) +* unload symbols from shared libraries: Files. (line 374) +* unmap an overlay: Overlay Commands. (line 39) +* unmapped overlays: How Overlays Work. (line 6) +* unset environment variable, remote request: General Query Packets. + (line 159) +* unset tdesc filename: Retrieving Descriptions. + (line 21) +* unsupported languages: Unsupported Languages. + (line 6) +* unsupported packets, empty response for: Standard Replies. (line 11) +* unwind stack in called functions: Calling. (line 36) +* unwind stack in called functions when timing out: Calling. (line 65) +* unwind stack in called functions with unhandled exceptions: Calling. + (line 53) +* unwinding frames in Python: Unwinding Frames in Python. + (line 6) +* use only software watchpoints: Set Watchpoints. (line 111) +* user registers: Maintenance Commands. + (line 568) +* user-defined command: Define. (line 6) +* user-defined macros: Macros. (line 60) +* user-defined variables: Convenience Vars. (line 6) +* value history: Value History. (line 6) +* values from inferior, in guile: Values From Inferior In Guile. + (line 6) +* values from inferior, with Python: Values From Inferior. + (line 6) +* variable name conflict: Variables. (line 36) +* variable object debugging info: Debugging Output. (line 314) +* variable objects in GDB/MI: GDB/MI Variable Objects. + (line 9) +* variable values, wrong: Variables. (line 106) +* variables, readline: Readline Init File Syntax. + (line 34) +* variables, setting: Assignment. (line 16) +* vAttach packet: Packets. (line 345) +* vCont packet: Packets. (line 361) +* vCont? packet: Packets. (line 428) +* vCtrlC packet: Packets. (line 436) +* vector unit: Vector Unit. (line 6) +* vector, auxiliary: OS Information. (line 9) +* verbose operation: Messages/Warnings. (line 6) +* verify remote memory image: Memory. (line 159) +* verify target memory image: Memory. (line 159) +* vFile packet: Packets. (line 448) +* vFlashDone packet: Packets. (line 483) +* vFlashErase packet: Packets. (line 452) +* vFlashWrite packet: Packets. (line 465) +* vfork events, remote reply: Stop Reply Packets. (line 116) +* vforkdone events, remote reply: Stop Reply Packets. (line 128) +* vg: AArch64. (line 41) +* virtual functions (C++) display: Print Settings. (line 639) +* vKill packet: Packets. (line 490) +* vl: AArch64. (line 35) +* vMustReplyEmpty packet: Packets. (line 500) +* volatile registers: Registers. (line 106) +* vq: AArch64. (line 38) +* vRun packet: Packets. (line 512) +* vStopped packet: Packets. (line 525) +* VTBL display: Print Settings. (line 639) +* watchdog timer: Maintenance Commands. + (line 989) +* watchpoints: Breakpoints. (line 17) +* watchpoints and threads: Set Watchpoints. (line 182) +* wavefronts: AMD GPU. (line 40) +* where to look for shared libraries: Files. (line 407) +* wild pointer, interpreting: Print Settings. (line 80) +* Wind River Linux system-wide configuration script: System-wide Configuration Scripts. + (line 22) +* word completion: Completion. (line 6) +* working directory: Source Path. (line 40) +* working directory (of your program): Working Directory. (line 6) +* working language: Languages. (line 13) +* write data into object, remote request: General Query Packets. + (line 1461) +* write, file-i/o system call: write. (line 6) +* writing a frame filter: Writing a Frame Filter. + (line 6) +* writing a Guile pretty-printer: Writing a Guile Pretty-Printer. + (line 6) +* writing a pretty-printer: Writing a Pretty-Printer. + (line 6) +* writing convenience functions: Functions In Python. + (line 6) +* writing into corefiles: Patching. (line 6) +* writing into executables: Patching. (line 6) +* writing into executables <1>: Compiling and Injecting Code. + (line 6) +* writing JIT debug info readers: Writing JIT Debug Info Readers. + (line 6) +* writing xmethods in Python: Writing an Xmethod. (line 6) +* wrong values: Variables. (line 106) +* x command, default address: Machine Code. (line 35) +* x packet: Packets. (line 528) +* X packet: Packets. (line 552) +* Xilinx MicroBlaze: MicroBlaze. (line 6) +* XInclude: Target Description Format. + (line 53) +* XMD, Xilinx Microprocessor Debugger: MicroBlaze. (line 6) +* xmethod API: Xmethod API. (line 6) +* xmethods in Python: Xmethods In Python. (line 6) +* XML parser debugging: Debugging Output. (line 321) +* yanking text: Readline Killing Commands. + (line 6) +* z packet: Packets. (line 563) +* Z packets: Packets. (line 563) +* z0 packet: Packets. (line 578) +* Z0 packet: Packets. (line 578) +* z1 packet: Packets. (line 629) +* Z1 packet: Packets. (line 629) +* z2 packet: Packets. (line 646) +* Z2 packet: Packets. (line 646) +* z3 packet: Packets. (line 655) +* Z3 packet: Packets. (line 655) +* z4 packet: Packets. (line 664) +* Z4 packet: Packets. (line 664) + Binary files 16.3-5/gdb/doc/gdb.info-9 and 16.3-5ubuntu1/gdb/doc/gdb.info-9 differ diff -pruN 16.3-5/gdb/doc/gdb.texinfo 16.3-5ubuntu1/gdb/doc/gdb.texinfo --- 16.3-5/gdb/doc/gdb.texinfo 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdb.texinfo 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,51588 @@ +\input texinfo @c -*-texinfo-*- +@c Copyright (C) 1988--2024 Free Software Foundation, Inc. +@c +@c %**start of header +@c makeinfo ignores cmds prev to setfilename, so its arg cannot make use +@c of @set vars. However, you can override filename with makeinfo -o. +@setfilename gdb.info +@c +@c man begin INCLUDE +@include gdb-cfg.texi +@c man end +@c +@settitle Debugging with @value{GDBN} +@setchapternewpage odd +@c %**end of header +@iftex +@c @smallbook +@c @cropmarks +@end iftex + +@finalout +@c To avoid file-name clashes between index.html and Index.html, when +@c the manual is produced on a Posix host and then moved to a +@c case-insensitive filesystem (e.g., MS-Windows), we separate the +@c indices into two: Concept Index and all the rest. +@syncodeindex ky fn +@syncodeindex tp fn + +@c readline appendices use @vindex, @findex and @ftable, +@c annotate.texi and gdbmi use @findex. +@syncodeindex vr fn + +@c !!set GDB manual's edition---not the same as GDB version! +@c This is updated by GNU Press. +@set EDITION Tenth + +@c !!set GDB edit command default editor +@set EDITOR /bin/ex + +@c THIS MANUAL REQUIRES TEXINFO 4.0 OR LATER. + +@c This is a dir.info fragment to support semi-automated addition of +@c manuals to an info tree. +@dircategory Software development +@direntry +* Gdb: (gdb). The GNU debugger. +* gdbserver: (gdb) Server. The GNU debugging server. +@end direntry + +@copying +@c man begin COPYRIGHT +Copyright @copyright{} 1988-2024 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being ``Free Software'' and ``Free Software Needs +Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' +and with the Back-Cover Texts as in (a) below. + +(a) The FSF's Back-Cover Text is: ``You are free to copy and modify +this GNU Manual. Buying copies from GNU Press supports the FSF in +developing GNU and promoting software freedom.'' +@c man end +@end copying + +@ifnottex +This file documents the @sc{gnu} debugger @value{GDBN}. + +This is the @value{EDITION} Edition, of @cite{Debugging with +@value{GDBN}: the @sc{gnu} Source-Level Debugger} for @value{GDBN} +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +Version @value{GDBVN}. + +@insertcopying +@end ifnottex + +@titlepage +@title Debugging with @value{GDBN} +@subtitle The @sc{gnu} Source-Level Debugger +@sp 1 +@subtitle @value{EDITION} Edition, for @value{GDBN} version @value{GDBVN} +@ifset VERSION_PACKAGE +@sp 1 +@subtitle @value{VERSION_PACKAGE} +@end ifset +@author Richard Stallman, Roland Pesch, Stan Shebs, et al. +@page +@tex +{\parskip=0pt +\hfill (Send bugs and comments on @value{GDBN} to @value{BUGURL}.)\par +\hfill {\it Debugging with @value{GDBN}}\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +Published by the Free Software Foundation @* +51 Franklin Street, Fifth Floor, +Boston, MA 02110-1301, USA@* +ISBN 978-0-9831592-3-0 @* + +@insertcopying +@end titlepage +@page + +@ifnottex +@node Top, Summary + +@top Debugging with @value{GDBN} + +This file describes @value{GDBN}, the @sc{gnu} symbolic debugger. + +This is the @value{EDITION} Edition, for @value{GDBN} +@ifset VERSION_PACKAGE +@value{VERSION_PACKAGE} +@end ifset +Version @value{GDBVN}. + +Copyright (C) 1988-2024 Free Software Foundation, Inc. + +This edition of the GDB manual is dedicated to the memory of Fred +Fish. Fred was a long-standing contributor to GDB and to Free +software in general. We will miss him. + +@menu +* Summary:: Summary of @value{GDBN} +* Sample Session:: A sample @value{GDBN} session + +* Invocation:: Getting in and out of @value{GDBN} +* Commands:: @value{GDBN} commands +* Running:: Running programs under @value{GDBN} +* Stopping:: Stopping and continuing +* Reverse Execution:: Running programs backward +* Process Record and Replay:: Recording inferior's execution and replaying it +* Stack:: Examining the stack +* Source:: Examining source files +* Data:: Examining data +* Optimized Code:: Debugging optimized code +* Macros:: Preprocessor Macros +* Tracepoints:: Debugging remote targets non-intrusively +* Overlays:: Debugging programs that use overlays + +* Languages:: Using @value{GDBN} with different languages + +* Symbols:: Examining the symbol table +* Altering:: Altering execution +* GDB Files:: @value{GDBN} files +* Targets:: Specifying a debugging target +* Remote Debugging:: Debugging remote programs +* Configurations:: Configuration-specific information +* Controlling GDB:: Controlling @value{GDBN} +* Extending GDB:: Extending @value{GDBN} +* Interpreters:: Command Interpreters +* TUI:: @value{GDBN} Text User Interface +* Emacs:: Using @value{GDBN} under @sc{gnu} Emacs +* GDB/MI:: @value{GDBN}'s Machine Interface. +* Annotations:: @value{GDBN}'s annotation interface. +* Debugger Adapter Protocol:: The Debugger Adapter Protocol. +* JIT Interface:: Using the JIT debugging interface. +* In-Process Agent:: In-Process Agent + +* GDB Bugs:: Reporting bugs in @value{GDBN} + +@ifset SYSTEM_READLINE +* Command Line Editing: (rluserman). Command Line Editing +* Using History Interactively: (history). Using History Interactively +@end ifset +@ifclear SYSTEM_READLINE +* Command Line Editing:: Command Line Editing +* Using History Interactively:: Using History Interactively +@end ifclear +* In Memoriam:: In Memoriam +* Formatting Documentation:: How to format and print @value{GDBN} documentation +* Installing GDB:: Installing @value{GDBN} +* Maintenance Commands:: Maintenance Commands +* Remote Protocol:: GDB Remote Serial Protocol +* Agent Expressions:: The @value{GDBN} Agent Expression Mechanism +* Target Descriptions:: How targets can describe themselves to + @value{GDBN} +* Operating System Information:: Getting additional information from + the operating system +* Trace File Format:: @value{GDBN} trace file format +* Index Section Format:: .gdb_index section format +* Debuginfod:: Download debugging resources with @code{debuginfod} +* Man Pages:: Manual pages +* Copying:: GNU General Public License says + how you can copy and share @value{GDBN} +* GNU Free Documentation License:: The license for this documentation +* Concept Index:: Index of @value{GDBN} concepts +* Command and Variable Index:: Index of @value{GDBN} commands, variables, + functions, and Python data types +@end menu + +@end ifnottex + +@contents + +@node Summary +@unnumbered Summary of @value{GDBN} + +The purpose of a debugger such as @value{GDBN} is to allow you to see what is +going on ``inside'' another program while it executes---or what another +program was doing at the moment it crashed. + +@value{GDBN} can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + +@itemize @bullet +@item +Start your program, specifying anything that might affect its behavior. + +@item +Make your program stop on specified conditions. + +@item +Examine what has happened, when your program has stopped. + +@item +Change things in your program, so you can experiment with correcting the +effects of one bug and go on to learn about another. +@end itemize + +You can use @value{GDBN} to debug programs written in C and C@t{++}. +For more information, see @ref{Supported Languages,,Supported Languages}. +For more information, see @ref{C,,C and C++}. + +Support for D is partial. For information on D, see +@ref{D,,D}. + +@cindex Modula-2 +Support for Modula-2 is partial. For information on Modula-2, see +@ref{Modula-2,,Modula-2}. + +Support for OpenCL C is partial. For information on OpenCL C, see +@ref{OpenCL C,,OpenCL C}. + +@cindex Pascal +Debugging Pascal programs which use sets, subranges, file variables, or +nested functions does not currently work. @value{GDBN} does not support +entering expressions, printing values, or similar features using Pascal +syntax. + +@cindex Fortran +@value{GDBN} can be used to debug programs written in Fortran, although +it may be necessary to refer to some variables with a trailing +underscore. + +@value{GDBN} can be used to debug programs written in Objective-C, +using either the Apple/NeXT or the GNU Objective-C runtime. + +@menu +* Free Software:: Freely redistributable software +* Free Documentation:: Free Software Needs Free Documentation +* Contributors:: Contributors to GDB +@end menu + +@node Free Software +@unnumberedsec Free Software + +@value{GDBN} is @dfn{free software}, protected by the @sc{gnu} +General Public License +(GPL). The GPL gives you the freedom to copy or adapt a licensed +program---but every person getting a copy also gets with it the +freedom to modify that copy (which means that they must get access to +the source code), and the freedom to distribute further copies. +Typical software companies use copyrights to limit your freedoms; the +Free Software Foundation uses the GPL to preserve these freedoms. + +Fundamentally, the General Public License is a license which says that +you have these freedoms and that you cannot take these freedoms away +from anyone else. + +@node Free Documentation +@unnumberedsec Free Software Needs Free Documentation + +The biggest deficiency in the free software community today is not in +the software---it is the lack of good free documentation that we can +include with the free software. Many of our most important +programs do not come with free reference manuals and free introductory +texts. Documentation is an essential part of any software package; +when an important free software package does not come with a free +manual and a free tutorial, that is a major gap. We have many such +gaps today. + +Consider Perl, for instance. The tutorial manuals that people +normally use are non-free. How did this come about? Because the +authors of those manuals published them with restrictive terms---no +copying, no modification, source files not available---which exclude +them from the free software world. + +That wasn't the first time this sort of thing happened, and it was far +from the last. Many times we have heard a GNU user eagerly describe a +manual that he is writing, his intended contribution to the community, +only to learn that he had ruined everything by signing a publication +contract to make it non-free. + +Free documentation, like free software, is a matter of freedom, not +price. The problem with the non-free manual is not that publishers +charge a price for printed copies---that in itself is fine. (The Free +Software Foundation sells printed copies of manuals, too.) The +problem is the restrictions on the use of the manual. Free manuals +are available in source code form, and give you permission to copy and +modify. Non-free manuals do not allow this. + +The criteria of freedom for a free manual are roughly the same as for +free software. Redistribution (including the normal kinds of +commercial redistribution) must be permitted, so that the manual can +accompany every copy of the program, both on-line and on paper. + +Permission for modification of the technical content is crucial too. +When people modify the software, adding or changing features, if they +are conscientious they will change the manual too---so they can +provide accurate and clear documentation for the modified program. A +manual that leaves you no choice but to write a new manual to document +a changed version of the program is not really available to our +community. + +Some kinds of limits on the way modification is handled are +acceptable. For example, requirements to preserve the original +author's copyright notice, the distribution terms, or the list of +authors, are ok. It is also no problem to require modified versions +to include notice that they were modified. Even entire sections that +may not be deleted or changed are acceptable, as long as they deal +with nontechnical topics (like this one). These kinds of restrictions +are acceptable because they don't obstruct the community's normal use +of the manual. + +However, it must be possible to modify all the @emph{technical} +content of the manual, and then distribute the result in all the usual +media, through all the usual channels. Otherwise, the restrictions +obstruct the use of the manual, it is not free, and we need another +manual to replace it. + +Please spread the word about this issue. Our community continues to +lose manuals to proprietary publishing. If we spread the word that +free software needs free reference manuals and free tutorials, perhaps +the next person who wants to contribute by writing documentation will +realize, before it is too late, that only free manuals contribute to +the free software community. + +If you are writing documentation, please insist on publishing it under +the GNU Free Documentation License or another free documentation +license. Remember that this decision requires your approval---you +don't have to let the publisher decide. Some commercial publishers +will use a free license if you insist, but they will not propose the +option; it is up to you to raise the issue and say firmly that this is +what you want. If the publisher you are dealing with refuses, please +try other publishers. If you're not sure whether a proposed license +is free, write to @email{licensing@@gnu.org}. + +You can encourage commercial publishers to sell more free, copylefted +manuals and tutorials by buying them, and particularly by buying +copies from the publishers that paid for their writing or for major +improvements. Meanwhile, try to avoid buying non-free documentation +at all. Check the distribution terms of a manual before you buy it, +and insist that whoever seeks your business must respect your freedom. +Check the history of the book, and try to reward the publishers that +have paid or pay the authors to work on it. + +The Free Software Foundation maintains a list of free documentation +published by other publishers, at +@url{http://www.fsf.org/doc/other-free-books.html}. + +@node Contributors +@unnumberedsec Contributors to @value{GDBN} + +Richard Stallman was the original author of @value{GDBN}, and of many +other @sc{gnu} programs. Many others have contributed to its +development. This section attempts to credit major contributors. One +of the virtues of free software is that everyone is free to contribute +to it; with regret, we cannot actually acknowledge everyone here. The +file @file{ChangeLog} in the @value{GDBN} distribution approximates a +blow-by-blow account. + +Changes much prior to version 2.0 are lost in the mists of time. + +@quotation +@emph{Plea:} Additions to this section are particularly welcome. If you +or your friends (or enemies, to be evenhanded) have been unfairly +omitted from this list, we would like to add your names! +@end quotation + +So that they may not regard their many labors as thankless, we +particularly thank those who shepherded @value{GDBN} through major +releases: +Andrew Cagney (releases 6.3, 6.2, 6.1, 6.0, 5.3, 5.2, 5.1 and 5.0); +Jim Blandy (release 4.18); +Jason Molenda (release 4.17); +Stan Shebs (release 4.14); +Fred Fish (releases 4.16, 4.15, 4.13, 4.12, 4.11, 4.10, and 4.9); +Stu Grossman and John Gilmore (releases 4.8, 4.7, 4.6, 4.5, and 4.4); +John Gilmore (releases 4.3, 4.2, 4.1, 4.0, and 3.9); +Jim Kingdon (releases 3.5, 3.4, and 3.3); +and Randy Smith (releases 3.2, 3.1, and 3.0). + +Richard Stallman, assisted at various times by Peter TerMaat, Chris +Hanson, and Richard Mlynarik, handled releases through 2.8. + +Michael Tiemann is the author of most of the @sc{gnu} C@t{++} support +in @value{GDBN}, with significant additional contributions from Per +Bothner and Daniel Berlin. James Clark wrote the @sc{gnu} C@t{++} +demangler. Early work on C@t{++} was by Peter TerMaat (who also did +much general update work leading to release 3.0). + +@value{GDBN} uses the BFD subroutine library to examine multiple +object-file formats; BFD was a joint project of David V. +Henkel-Wallace, Rich Pixley, Steve Chamberlain, and John Gilmore. + +David Johnson wrote the original COFF support; Pace Willison did +the original support for encapsulated COFF. + +Brent Benson of Harris Computer Systems contributed DWARF 2 support. + +Adam de Boor and Bradley Davis contributed the ISI Optimum V support. +Per Bothner, Noboyuki Hikichi, and Alessandro Forin contributed MIPS +support. +Jean-Daniel Fekete contributed Sun 386i support. +Chris Hanson improved the HP9000 support. +Noboyuki Hikichi and Tomoyuki Hasei contributed Sony/News OS 3 support. +David Johnson contributed Encore Umax support. +Jyrki Kuoppala contributed Altos 3068 support. +Jeff Law contributed HP PA and SOM support. +Keith Packard contributed NS32K support. +Doug Rabson contributed Acorn Risc Machine support. +Bob Rusk contributed Harris Nighthawk CX-UX support. +Chris Smith contributed Convex support (and Fortran debugging). +Jonathan Stone contributed Pyramid support. +Michael Tiemann contributed SPARC support. +Tim Tucker contributed support for the Gould NP1 and Gould Powernode. +Pace Willison contributed Intel 386 support. +Jay Vosburgh contributed Symmetry support. +Marko Mlinar contributed OpenRISC 1000 support. + +Andreas Schwab contributed M68K @sc{gnu}/Linux support. + +Rich Schaefer and Peter Schauer helped with support of SunOS shared +libraries. + +Jay Fenlason and Roland McGrath ensured that @value{GDBN} and GAS agree +about several machine instruction sets. + +Patrick Duval, Ted Goldstein, Vikram Koka and Glenn Engel helped develop +remote debugging. Intel Corporation, Wind River Systems, AMD, and ARM +contributed remote debugging modules for the i960, VxWorks, A29K UDI, +and RDI targets, respectively. + +Brian Fox is the author of the readline libraries providing +command-line editing and command history. + +Andrew Beers of SUNY Buffalo wrote the language-switching code, the +Modula-2 support, and contributed the Languages chapter of this manual. + +Fred Fish wrote most of the support for Unix System Vr4. +He also enhanced the command-completion support to cover C@t{++} overloaded +symbols. + +Hitachi America (now Renesas America), Ltd. sponsored the support for +H8/300, H8/500, and Super-H processors. + +NEC sponsored the support for the v850, Vr4xxx, and Vr5xxx processors. + +Mitsubishi (now Renesas) sponsored the support for D10V, D30V, and M32R/D +processors. + +Toshiba sponsored the support for the TX39 Mips processor. + +Matsushita sponsored the support for the MN10200 and MN10300 processors. + +Fujitsu sponsored the support for SPARClite and FR30 processors. + +Kung Hsu, Jeff Law, and Rick Sladkey added support for hardware +watchpoints. + +Michael Snyder added support for tracepoints. + +Stu Grossman wrote gdbserver. + +Jim Kingdon, Peter Schauer, Ian Taylor, and Stu Grossman made +nearly innumerable bug fixes and cleanups throughout @value{GDBN}. + +The following people at the Hewlett-Packard Company contributed +support for the PA-RISC 2.0 architecture, HP-UX 10.20, 10.30, and 11.0 +(narrow mode), HP's implementation of kernel threads, HP's aC@t{++} +compiler, and the Text User Interface (nee Terminal User Interface): +Ben Krepp, Richard Title, John Bishop, Susan Macchia, Kathy Mann, +Satish Pai, India Paul, Steve Rehrauer, and Elena Zannoni. Kim Haase +provided HP-specific information in this manual. + +DJ Delorie ported @value{GDBN} to MS-DOS, for the DJGPP project. +Robert Hoehne made significant contributions to the DJGPP port. + +Cygnus Solutions has sponsored @value{GDBN} maintenance and much of its +development since 1991. Cygnus engineers who have worked on @value{GDBN} +fulltime include Mark Alexander, Jim Blandy, Per Bothner, Kevin +Buettner, Edith Epstein, Chris Faylor, Fred Fish, Martin Hunt, Jim +Ingham, John Gilmore, Stu Grossman, Kung Hsu, Jim Kingdon, John Metzler, +Fernando Nasser, Geoffrey Noer, Dawn Perchik, Rich Pixley, Zdenek +Radouch, Keith Seitz, Stan Shebs, David Taylor, and Elena Zannoni. In +addition, Dave Brolley, Ian Carmichael, Steve Chamberlain, Nick Clifton, +JT Conklin, Stan Cox, DJ Delorie, Ulrich Drepper, Frank Eigler, Doug +Evans, Sean Fagan, David Henkel-Wallace, Richard Henderson, Jeff +Holcomb, Jeff Law, Jim Lemke, Tom Lord, Bob Manson, Michael Meissner, +Jason Merrill, Catherine Moore, Drew Moseley, Ken Raeburn, Gavin +Romig-Koch, Rob Savoye, Jamie Smith, Mike Stump, Ian Taylor, Angela +Thomas, Michael Tiemann, Tom Tromey, Ron Unrau, Jim Wilson, and David +Zuhn have made contributions both large and small. + +Andrew Cagney, Fernando Nasser, and Elena Zannoni, while working for +Cygnus Solutions, implemented the original @sc{gdb/mi} interface. + +Jim Blandy added support for preprocessor macros, while working for Red +Hat. + +Andrew Cagney designed @value{GDBN}'s architecture vector. Many +people including Andrew Cagney, Stephane Carrez, Randolph Chung, Nick +Duffek, Richard Henderson, Mark Kettenis, Grace Sainsbury, Kei +Sakamoto, Yoshinori Sato, Michael Snyder, Andreas Schwab, Jason +Thorpe, Corinna Vinschen, Ulrich Weigand, and Elena Zannoni, helped +with the migration of old architectures to this new framework. + +Andrew Cagney completely re-designed and re-implemented @value{GDBN}'s +unwinder framework, this consisting of a fresh new design featuring +frame IDs, independent frame sniffers, and the sentinel frame. Mark +Kettenis implemented the @sc{dwarf 2} unwinder, Jeff Johnston the +libunwind unwinder, and Andrew Cagney the dummy, sentinel, tramp, and +trad unwinders. The architecture-specific changes, each involving a +complete rewrite of the architecture's frame code, were carried out by +Jim Blandy, Joel Brobecker, Kevin Buettner, Andrew Cagney, Stephane +Carrez, Randolph Chung, Orjan Friberg, Richard Henderson, Daniel +Jacobowitz, Jeff Johnston, Mark Kettenis, Theodore A. Roth, Kei +Sakamoto, Yoshinori Sato, Michael Snyder, Corinna Vinschen, and Ulrich +Weigand. + +Christian Zankel, Ross Morley, Bob Wilson, and Maxim Grigoriev from +Tensilica, Inc.@: contributed support for Xtensa processors. Others +who have worked on the Xtensa port of @value{GDBN} in the past include +Steve Tjiang, John Newlin, and Scott Foehner. + +Michael Eager and staff of Xilinx, Inc., contributed support for the +Xilinx MicroBlaze architecture. + +Initial support for the FreeBSD/mips target and native configuration +was developed by SRI International and the University of Cambridge +Computer Laboratory under DARPA/AFRL contract FA8750-10-C-0237 +("CTSRD"), as part of the DARPA CRASH research programme. + +Initial support for the FreeBSD/riscv target and native configuration +was developed by SRI International and the University of Cambridge +Computer Laboratory (Department of Computer Science and Technology) +under DARPA contract HR0011-18-C-0016 ("ECATS"), as part of the DARPA +SSITH research programme. + +The original port to the OpenRISC 1000 is believed to be due to +Alessandro Forin and Per Bothner. More recent ports have been the work +of Jeremy Bennett, Franck Jullien, Stefan Wallentowitz and +Stafford Horne. + +Weimin Pan, David Faust and Jose E. Marchesi contributed support for +the Linux kernel BPF virtual architecture. This work was sponsored by +Oracle. + +@node Sample Session +@chapter A Sample @value{GDBN} Session + +You can use this manual at your leisure to read all about @value{GDBN}. +However, a handful of commands are enough to get started using the +debugger. This chapter illustrates those commands. + +@iftex +In this sample session, we emphasize user input like this: @b{input}, +to make it easier to pick out from the surrounding output. +@end iftex + +@c FIXME: this example may not be appropriate for some configs, where +@c FIXME...primary interest is in remote use. + +One of the preliminary versions of @sc{gnu} @code{m4} (a generic macro +processor) exhibits the following bug: sometimes, when we change its +quote strings from the default, the commands used to capture one macro +definition within another stop working. In the following short @code{m4} +session, we define a macro @code{foo} which expands to @code{0000}; we +then use the @code{m4} built-in @code{defn} to define @code{bar} as the +same thing. However, when we change the open quote string to +@code{} and the close quote string to @code{}, the same +procedure fails to define a new synonym @code{baz}: + +@smallexample +$ @b{cd gnu/m4} +$ @b{./m4} +@b{define(foo,0000)} + +@b{foo} +0000 +@b{define(bar,defn(`foo'))} + +@b{bar} +0000 +@b{changequote(,)} + +@b{define(baz,defn(foo))} +@b{baz} +@b{Ctrl-d} +m4: End of input: 0: fatal error: EOF in string +@end smallexample + +@noindent +Let us use @value{GDBN} to try to see what is going on. + +@smallexample +$ @b{@value{GDBP} m4} +@c FIXME: this falsifies the exact text played out, to permit smallbook +@c FIXME... format to come out better. +@value{GDBN} is free software and you are welcome to distribute copies + of it under certain conditions; type "show copying" to see + the conditions. +There is absolutely no warranty for @value{GDBN}; type "show warranty" + for details. + +@value{GDBN} @value{GDBVN}, Copyright 1999 Free Software Foundation, Inc... +(@value{GDBP}) +@end smallexample + +@noindent +@value{GDBN} reads only enough symbol data to know where to find the +rest when needed; as a result, the first prompt comes up very quickly. +We now tell @value{GDBN} to use a narrower display width than usual, so +that examples fit in this manual. + +@smallexample +(@value{GDBP}) @b{set width 70} +@end smallexample + +@noindent +We need to see how the @code{m4} built-in @code{changequote} works. +Having looked at the source, we know the relevant subroutine is +@code{m4_changequote}, so we set a breakpoint there with the @value{GDBN} +@code{break} command. + +@smallexample +(@value{GDBP}) @b{break m4_changequote} +Breakpoint 1 at 0x62f4: file builtin.c, line 879. +@end smallexample + +@noindent +Using the @code{run} command, we start @code{m4} running under @value{GDBN} +control; as long as control does not reach the @code{m4_changequote} +subroutine, the program runs as usual: + +@smallexample +(@value{GDBP}) @b{run} +Starting program: /work/Editorial/gdb/gnu/m4/m4 +@b{define(foo,0000)} + +@b{foo} +0000 +@end smallexample + +@noindent +To trigger the breakpoint, we call @code{changequote}. @value{GDBN} +suspends execution of @code{m4}, displaying information about the +context where it stops. + +@smallexample +@b{changequote(,)} + +Breakpoint 1, m4_changequote (argc=3, argv=0x33c70) + at builtin.c:879 +879 if (bad_argc(TOKEN_DATA_TEXT(argv[0]),argc,1,3)) +@end smallexample + +@noindent +Now we use the command @code{n} (@code{next}) to advance execution to +the next line of the current function. + +@smallexample +(@value{GDBP}) @b{n} +882 set_quotes((argc >= 2) ? TOKEN_DATA_TEXT(argv[1])\ + : nil, +@end smallexample + +@noindent +@code{set_quotes} looks like a promising subroutine. We can go into it +by using the command @code{s} (@code{step}) instead of @code{next}. +@code{step} goes to the next line to be executed in @emph{any} +subroutine, so it steps into @code{set_quotes}. + +@smallexample +(@value{GDBP}) @b{s} +set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 +530 if (lquote != def_lquote) +@end smallexample + +@noindent +The display that shows the subroutine where @code{m4} is now +suspended (and its arguments) is called a stack frame display. It +shows a summary of the stack. We can use the @code{backtrace} +command (which can also be spelled @code{bt}), to see where we are +in the stack as a whole: the @code{backtrace} command displays a +stack frame for each active subroutine. + +@smallexample +(@value{GDBP}) @b{bt} +#0 set_quotes (lq=0x34c78 "", rq=0x34c88 "") + at input.c:530 +#1 0x6344 in m4_changequote (argc=3, argv=0x33c70) + at builtin.c:882 +#2 0x8174 in expand_macro (sym=0x33320) at macro.c:242 +#3 0x7a88 in expand_token (obs=0x0, t=209696, td=0xf7fffa30) + at macro.c:71 +#4 0x79dc in expand_input () at macro.c:40 +#5 0x2930 in main (argc=0, argv=0xf7fffb20) at m4.c:195 +@end smallexample + +@noindent +We step through a few more lines to see what happens. The first two +times, we can use @samp{s}; the next two times we use @code{n} to avoid +falling into the @code{xstrdup} subroutine. + +@smallexample +(@value{GDBP}) @b{s} +0x3b5c 532 if (rquote != def_rquote) +(@value{GDBP}) @b{s} +0x3b80 535 lquote = (lq == nil || *lq == '\0') ? \ +def_lquote : xstrdup(lq); +(@value{GDBP}) @b{n} +536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup(rq); +(@value{GDBP}) @b{n} +538 len_lquote = strlen(rquote); +@end smallexample + +@noindent +The last line displayed looks a little odd; we can examine the variables +@code{lquote} and @code{rquote} to see if they are in fact the new left +and right quotes we specified. We use the command @code{p} +(@code{print}) to see their values. + +@smallexample +(@value{GDBP}) @b{p lquote} +$1 = 0x35d40 "" +(@value{GDBP}) @b{p rquote} +$2 = 0x35d50 "" +@end smallexample + +@noindent +@code{lquote} and @code{rquote} are indeed the new left and right quotes. +To look at some context, we can display ten lines of source +surrounding the current line with the @code{l} (@code{list}) command. + +@smallexample +(@value{GDBP}) @b{l} +533 xfree(rquote); +534 +535 lquote = (lq == nil || *lq == '\0') ? def_lquote\ + : xstrdup (lq); +536 rquote = (rq == nil || *rq == '\0') ? def_rquote\ + : xstrdup (rq); +537 +538 len_lquote = strlen(rquote); +539 len_rquote = strlen(lquote); +540 @} +541 +542 void +@end smallexample + +@noindent +Let us step past the two lines that set @code{len_lquote} and +@code{len_rquote}, and then examine the values of those variables. + +@smallexample +(@value{GDBP}) @b{n} +539 len_rquote = strlen(lquote); +(@value{GDBP}) @b{n} +540 @} +(@value{GDBP}) @b{p len_lquote} +$3 = 9 +(@value{GDBP}) @b{p len_rquote} +$4 = 7 +@end smallexample + +@noindent +That certainly looks wrong, assuming @code{len_lquote} and +@code{len_rquote} are meant to be the lengths of @code{lquote} and +@code{rquote} respectively. We can set them to better values using +the @code{p} command, since it can print the value of +any expression---and that expression can include subroutine calls and +assignments. + +@smallexample +(@value{GDBP}) @b{p len_lquote=strlen(lquote)} +$5 = 7 +(@value{GDBP}) @b{p len_rquote=strlen(rquote)} +$6 = 9 +@end smallexample + +@noindent +Is that enough to fix the problem of using the new quotes with the +@code{m4} built-in @code{defn}? We can allow @code{m4} to continue +executing with the @code{c} (@code{continue}) command, and then try the +example that caused trouble initially: + +@smallexample +(@value{GDBP}) @b{c} +Continuing. + +@b{define(baz,defn(foo))} + +baz +0000 +@end smallexample + +@noindent +Success! The new quotes now work just as well as the default ones. The +problem seems to have been just the two typos defining the wrong +lengths. We allow @code{m4} exit by giving it an EOF as input: + +@smallexample +@b{Ctrl-d} +Program exited normally. +@end smallexample + +@noindent +The message @samp{Program exited normally.} is from @value{GDBN}; it +indicates @code{m4} has finished executing. We can end our @value{GDBN} +session with the @value{GDBN} @code{quit} command. + +@smallexample +(@value{GDBP}) @b{quit} +@end smallexample + +@node Invocation +@chapter Getting In and Out of @value{GDBN} + +This chapter discusses how to start @value{GDBN}, and how to get out of it. +The essentials are: +@itemize @bullet +@item +type @samp{@value{GDBP}} to start @value{GDBN}. +@item +type @kbd{quit}, @kbd{exit} or @kbd{Ctrl-d} to exit. +@end itemize + +@menu +* Invoking GDB:: How to start @value{GDBN} +* Quitting GDB:: How to quit @value{GDBN} +* Shell Commands:: How to use shell commands inside @value{GDBN} +* Logging Output:: How to log @value{GDBN}'s output to a file +@end menu + +@node Invoking GDB +@section Invoking @value{GDBN} + +Invoke @value{GDBN} by running the program @code{@value{GDBP}}. Once started, +@value{GDBN} reads commands from the terminal until you tell it to exit. + +You can also run @code{@value{GDBP}} with a variety of arguments and options, +to specify more of your debugging environment at the outset. + +The command-line options described here are designed +to cover a variety of situations; in some environments, some of these +options may effectively be unavailable. + +The most usual way to start @value{GDBN} is with one argument, +specifying an executable program: + +@smallexample +@value{GDBP} @var{program} +@end smallexample + +@noindent +You can also start with both an executable program and a core file +specified: + +@smallexample +@value{GDBP} @var{program} @var{core} +@end smallexample + +You can, instead, specify a process ID as a second argument or use option +@code{-p}, if you want to debug a running process: + +@smallexample +@value{GDBP} @var{program} 1234 +@value{GDBP} -p 1234 +@end smallexample + +@noindent +would attach @value{GDBN} to process @code{1234}. With option @option{-p} you +can omit the @var{program} filename. + +Taking advantage of the second command-line argument requires a fairly +complete operating system; when you use @value{GDBN} as a remote +debugger attached to a bare board, there may not be any notion of +``process'', and there is often no way to get a core dump. @value{GDBN} +will warn you if it is unable to attach or to read core dumps. + +You can optionally have @code{@value{GDBP}} pass any arguments after the +executable file to the inferior using @code{--args}. This option stops +option processing. +@smallexample +@value{GDBP} --args gcc -O2 -c foo.c +@end smallexample +This will cause @code{@value{GDBP}} to debug @code{gcc}, and to set +@code{gcc}'s command-line arguments (@pxref{Arguments}) to @samp{-O2 -c foo.c}. + +You can run @code{@value{GDBP}} without printing the front material, which describes +@value{GDBN}'s non-warranty, by specifying @code{--silent} +(or @code{-q}/@code{--quiet}): + +@smallexample +@value{GDBP} --silent +@end smallexample + +@noindent +You can further control how @value{GDBN} starts up by using command-line +options. @value{GDBN} itself can remind you of the options available. + +@noindent +Type + +@smallexample +@value{GDBP} -help +@end smallexample + +@noindent +to display all available options and briefly describe their use +(@samp{@value{GDBP} -h} is a shorter equivalent). + +All options and command line arguments you give are processed +in sequential order. The order makes a difference when the +@samp{-x} option is used. + + +@menu +* File Options:: Choosing files +* Mode Options:: Choosing modes +* Startup:: What @value{GDBN} does during startup +* Initialization Files:: Initialization Files +@end menu + +@node File Options +@subsection Choosing Files + +When @value{GDBN} starts, it reads any arguments other than options as +specifying an executable file and core file (or process ID). This is +the same as if the arguments were specified by the @samp{-se} and +@samp{-c} (or @samp{-p}) options respectively. (@value{GDBN} reads the +first argument that does not have an associated option flag as +equivalent to the @samp{-se} option followed by that argument; and the +second argument that does not have an associated option flag, if any, as +equivalent to the @samp{-c}/@samp{-p} option followed by that argument.) +If the second argument begins with a decimal digit, @value{GDBN} will +first attempt to attach to it as a process, and if that fails, attempt +to open it as a corefile. If you have a corefile whose name begins with +a digit, you can prevent @value{GDBN} from treating it as a pid by +prefixing it with @file{./}, e.g.@: @file{./12345}. + +If @value{GDBN} has not been configured to included core file support, +such as for most embedded targets, then it will complain about a second +argument and ignore it. + +For the @samp{-s}, @samp{-e}, and @samp{-se} options, and their long +form equivalents, the method used to search the file system for the +symbol and/or executable file is the same as that used by the +@code{file} command. @xref{Files, ,file}. + +Many options have both long and short forms; both are shown in the +following list. @value{GDBN} also recognizes the long forms if you truncate +them, so long as enough of the option is present to be unambiguous. +(If you prefer, you can flag option arguments with @samp{--} rather +than @samp{-}, though we illustrate the more usual convention.) + +@c NOTE: the @cindex entries here use double dashes ON PURPOSE. This +@c way, both those who look for -foo and --foo in the index, will find +@c it. + +@table @code +@item -symbols @var{file} +@itemx -s @var{file} +@cindex @code{--symbols} +@cindex @code{-s} +Read symbol table from file @var{file}. + +@item -exec @var{file} +@itemx -e @var{file} +@cindex @code{--exec} +@cindex @code{-e} +Use file @var{file} as the executable file to execute when appropriate, +and for examining pure data in conjunction with a core dump. + +@item -se @var{file} +@cindex @code{--se} +Read symbol table from file @var{file} and use it as the executable +file. + +@item -core @var{file} +@itemx -c @var{file} +@cindex @code{--core} +@cindex @code{-c} +Use file @var{file} as a core dump to examine. + +@item -pid @var{number} +@itemx -p @var{number} +@cindex @code{--pid} +@cindex @code{-p} +Connect to process ID @var{number}, as with the @code{attach} command. + +@item -command @var{file} +@itemx -x @var{file} +@cindex @code{--command} +@cindex @code{-x} +Execute commands from file @var{file}. The contents of this file is +evaluated exactly as the @code{source} command would. +@xref{Command Files,, Command files}. + +@item -eval-command @var{command} +@itemx -ex @var{command} +@cindex @code{--eval-command} +@cindex @code{-ex} +Execute a single @value{GDBN} command. + +This option may be used multiple times to call multiple commands. It may +also be interleaved with @samp{-command} as required. + +@smallexample +@value{GDBP} -ex 'target sim' -ex 'load' \ + -x setbreakpoints -ex 'run' a.out +@end smallexample + +@item -init-command @var{file} +@itemx -ix @var{file} +@cindex @code{--init-command} +@cindex @code{-ix} +Execute commands from file @var{file} before loading the inferior (but +after loading gdbinit files). +@xref{Startup}. + +@item -init-eval-command @var{command} +@itemx -iex @var{command} +@cindex @code{--init-eval-command} +@cindex @code{-iex} +Execute a single @value{GDBN} command before loading the inferior (but +after loading gdbinit files). +@xref{Startup}. + +@item -early-init-command @var{file} +@itemx -eix @var{file} +@cindex @code{--early-init-command} +@cindex @code{-eix} +Execute commands from @var{file} very early in the initialization +process, before any output is produced. @xref{Startup}. + +@item -early-init-eval-command @var{command} +@itemx -eiex @var{command} +@cindex @code{--early-init-eval-command} +@cindex @code{-eiex} +Execute a single @value{GDBN} command very early in the initialization +process, before any output is produced. + +@item -directory @var{directory} +@itemx -d @var{directory} +@cindex @code{--directory} +@cindex @code{-d} +Add @var{directory} to the path to search for source and script files. + +@item -r +@itemx -readnow +@cindex @code{--readnow} +@cindex @code{-r} +Read each symbol file's entire symbol table immediately, rather than +the default, which is to read it incrementally as it is needed. +This makes startup slower, but makes future operations faster. + +@item --readnever +@anchor{--readnever} +@cindex @code{--readnever}, command-line option +Do not read each symbol file's symbolic debug information. This makes +startup faster but at the expense of not being able to perform +symbolic debugging. DWARF unwind information is also not read, +meaning backtraces may become incomplete or inaccurate. One use of +this is when a user simply wants to do the following sequence: attach, +dump core, detach. Loading the debugging information in this case is +an unnecessary cause of delay. +@end table + +@node Mode Options +@subsection Choosing Modes + +You can run @value{GDBN} in various alternative modes---for example, in +batch mode or quiet mode. + +@table @code +@anchor{-nx} +@item -nx +@itemx -n +@cindex @code{--nx} +@cindex @code{-n} +Do not execute commands found in any initialization files +(@pxref{Initialization Files}). + +@anchor{-nh} +@item -nh +@cindex @code{--nh} +Do not execute commands found in any home directory initialization +file (@pxref{Initialization Files,,Home directory initialization +file}). The system wide and current directory initialization files +are still loaded. + +@item -quiet +@itemx -silent +@itemx -q +@cindex @code{--quiet} +@cindex @code{--silent} +@cindex @code{-q} +``Quiet''. Do not print the introductory and copyright messages. These +messages are also suppressed in batch mode. + +@kindex set startup-quietly +@kindex show startup-quietly +This can also be enabled using @code{set startup-quietly on}. The +default is @code{off}. Use @code{show startup-quietly} to see the +current setting. Place @code{set startup-quietly on} into your early +initialization file (@pxref{Initialization Files,,Initialization +Files}) to have future @value{GDBN} sessions startup quietly. + +@item -batch +@cindex @code{--batch} +Run in batch mode. Exit with status @code{0} after processing all the +command files specified with @samp{-x} (and all commands from +initialization files, if not inhibited with @samp{-n}). Exit with +nonzero status if an error occurs in executing the @value{GDBN} commands +in the command files. Batch mode also disables pagination, sets unlimited +terminal width and height @pxref{Screen Size}, and acts as if @kbd{set confirm +off} were in effect (@pxref{Messages/Warnings}). + +Batch mode may be useful for running @value{GDBN} as a filter, for +example to download and run a program on another computer; in order to +make this more useful, the message + +@smallexample +Program exited normally. +@end smallexample + +@noindent +(which is ordinarily issued whenever a program running under +@value{GDBN} control terminates) is not issued when running in batch +mode. + +@item -batch-silent +@cindex @code{--batch-silent} +Run in batch mode exactly like @samp{-batch}, but totally silently. All +@value{GDBN} output to @code{stdout} is prevented (@code{stderr} is +unaffected). This is much quieter than @samp{-silent} and would be useless +for an interactive session. + +This is particularly useful when using targets that give @samp{Loading section} +messages, for example. + +Note that targets that give their output via @value{GDBN}, as opposed to +writing directly to @code{stdout}, will also be made silent. + +@item -return-child-result +@cindex @code{--return-child-result} +The return code from @value{GDBN} will be the return code from the child +process (the process being debugged), with the following exceptions: + +@itemize @bullet +@item +@value{GDBN} exits abnormally. E.g., due to an incorrect argument or an +internal error. In this case the exit code is the same as it would have been +without @samp{-return-child-result}. +@item +The user quits with an explicit value. E.g., @samp{quit 1}. +@item +The child process never runs, or is not allowed to terminate, in which case +the exit code will be -1. +@end itemize + +This option is useful in conjunction with @samp{-batch} or @samp{-batch-silent}, +when @value{GDBN} is being used as a remote program loader or simulator +interface. + +@item -nowindows +@itemx -nw +@cindex @code{--nowindows} +@cindex @code{-nw} +``No windows''. If @value{GDBN} comes with a graphical user interface +(GUI) built in, then this option tells @value{GDBN} to only use the command-line +interface. If no GUI is available, this option has no effect. + +@item -windows +@itemx -w +@cindex @code{--windows} +@cindex @code{-w} +If @value{GDBN} includes a GUI, then this option requires it to be +used if possible. + +@item -cd @var{directory} +@cindex @code{--cd} +Run @value{GDBN} using @var{directory} as its working directory, +instead of the current directory. + +@item -data-directory @var{directory} +@itemx -D @var{directory} +@cindex @code{--data-directory} +@cindex @code{-D} +Run @value{GDBN} using @var{directory} as its data directory. +The data directory is where @value{GDBN} searches for its +auxiliary files. @xref{Data Files}. + +@item -fullname +@itemx -f +@cindex @code{--fullname} +@cindex @code{-f} +@sc{gnu} Emacs sets this option when it runs @value{GDBN} as a +subprocess. It tells @value{GDBN} to output the full file name and line +number in a standard, recognizable fashion each time a stack frame is +displayed (which includes each time your program stops). This +recognizable format looks like two @samp{\032} characters, followed by +the file name, line number and character position separated by colons, +and a newline. The Emacs-to-@value{GDBN} interface program uses the two +@samp{\032} characters as a signal to display the source code for the +frame. + +@item -annotate @var{level} +@cindex @code{--annotate} +This option sets the @dfn{annotation level} inside @value{GDBN}. Its +effect is identical to using @samp{set annotate @var{level}} +(@pxref{Annotations}). The annotation @var{level} controls how much +information @value{GDBN} prints together with its prompt, values of +expressions, source lines, and other types of output. Level 0 is the +normal, level 1 is for use when @value{GDBN} is run as a subprocess of +@sc{gnu} Emacs, level 3 is the maximum annotation suitable for programs +that control @value{GDBN}, and level 2 has been deprecated. + +The annotation mechanism has largely been superseded by @sc{gdb/mi} +(@pxref{GDB/MI}). + +@item --args +@cindex @code{--args} +Change interpretation of command line so that arguments following the +executable file are passed as command line arguments to the inferior. +This option stops option processing. + +@item -baud @var{bps} +@itemx -b @var{bps} +@cindex @code{--baud} +@cindex @code{-b} +Set the line speed (baud rate or bits per second) of any serial +interface used by @value{GDBN} for remote debugging. + +@item -l @var{timeout} +@cindex @code{-l} +Set the timeout (in seconds) of any communication used by @value{GDBN} +for remote debugging. + +@item -tty @var{device} +@itemx -t @var{device} +@cindex @code{--tty} +@cindex @code{-t} +Run using @var{device} for your program's standard input and output. +@c FIXME: kingdon thinks there is more to -tty. Investigate. + +@c resolve the situation of these eventually +@item -tui +@cindex @code{--tui} +Activate the @dfn{Text User Interface} when starting. The Text User +Interface manages several text windows on the terminal, showing +source, assembly, registers and @value{GDBN} command outputs +(@pxref{TUI, ,@value{GDBN} Text User Interface}). Do not use this +option if you run @value{GDBN} from Emacs (@pxref{Emacs, , +Using @value{GDBN} under @sc{gnu} Emacs}). + +@item -interpreter @var{interp} +@cindex @code{--interpreter} +Use the interpreter @var{interp} for interface with the controlling +program or device. This option is meant to be set by programs which +communicate with @value{GDBN} using it as a back end. +@xref{Interpreters, , Command Interpreters}. + +@samp{--interpreter=mi} (or @samp{--interpreter=mi3}) causes +@value{GDBN} to use the @dfn{@sc{gdb/mi} interface} version 3 (@pxref{GDB/MI, , +The @sc{gdb/mi} Interface}) included since @value{GDBN} version 9.1. @sc{gdb/mi} +version 2 (@code{mi2}), included in @value{GDBN} 6.0 and version 1 (@code{mi1}), +included in @value{GDBN} 5.3, are also available. Earlier @sc{gdb/mi} +interfaces are no longer supported. + +@item -write +@cindex @code{--write} +Open the executable and core files for both reading and writing. This +is equivalent to the @samp{set write on} command inside @value{GDBN} +(@pxref{Patching}). + +@item -statistics +@cindex @code{--statistics} +This option causes @value{GDBN} to print statistics about time and +memory usage after it completes each command and returns to the prompt. + +@item -version +@cindex @code{--version} +This option causes @value{GDBN} to print its version number and +no-warranty blurb, and exit. + +@item -configuration +@cindex @code{--configuration} +This option causes @value{GDBN} to print details about its build-time +configuration parameters, and then exit. These details can be +important when reporting @value{GDBN} bugs (@pxref{GDB Bugs}). + +@end table + +@node Startup +@subsection What @value{GDBN} Does During Startup +@cindex @value{GDBN} startup + +Here's the description of what @value{GDBN} does during session startup: + +@enumerate + +@item +Performs minimal setup required to initialize basic internal state. + +@item +@cindex early initialization file +Reads commands from the early initialization file (if any) in your +home directory. Only a restricted set of commands can be placed into +an early initialization file, see @ref{Initialization Files}, for +details. + +@item +Executes commands and command files specified by the @samp{-eiex} and +@samp{-eix} command line options in their specified order. Only a +restricted set of commands can be used with @samp{-eiex} and +@samp{eix}, see @ref{Initialization Files}, for details. + +@item +Sets up the command interpreter as specified by the command line +(@pxref{Mode Options, interpreter}). + +@item +@cindex init file +Reads the system wide initialization file and the files from the +system wide initialization directory, @pxref{System Wide Init Files}. + +@item +Reads the initialization file (if any) in your home directory and +executes all the commands in that file, @pxref{Home Directory Init +File}. + +@anchor{Option -init-eval-command} +@item +Executes commands and command files specified by the @samp{-iex} and +@samp{-ix} options in their specified order. Usually you should use the +@samp{-ex} and @samp{-x} options instead, but this way you can apply +settings before @value{GDBN} init files get executed and before inferior +gets loaded. + +@item +Processes command line options and operands. + +@item +Reads and executes the commands from the initialization file (if any) +in the current working directory as long as @samp{set auto-load +local-gdbinit} is set to @samp{on} (@pxref{Init File in the Current +Directory}). This is only done if the current directory is different +from your home directory. Thus, you can have more than one init file, +one generic in your home directory, and another, specific to the +program you are debugging, in the directory where you invoke +@value{GDBN}. @xref{Init File in the Current Directory during +Startup}. + +@item +If the command line specified a program to debug, or a process to +attach to, or a core file, @value{GDBN} loads any auto-loaded +scripts provided for the program or for its loaded shared libraries. +@xref{Auto-loading}. + +If you wish to disable the auto-loading during startup, +you must do something like the following: + +@smallexample +$ gdb -iex "set auto-load python-scripts off" myprogram +@end smallexample + +Option @samp{-ex} does not work because the auto-loading is then turned +off too late. + +@item +Executes commands and command files specified by the @samp{-ex} and +@samp{-x} options in their specified order. @xref{Command Files}, for +more details about @value{GDBN} command files. + +@item +Reads the command history recorded in the @dfn{history file}. +@xref{Command History}, for more details about the command history and the +files where @value{GDBN} records it. +@end enumerate + +@node Initialization Files +@subsection Initialization Files +@cindex init file name + +During startup (@pxref{Startup}) @value{GDBN} will execute commands +from several initialization files. These initialization files use the +same syntax as @dfn{command files} (@pxref{Command Files}) and are +processed by @value{GDBN} in the same way. + +To display the list of initialization files loaded by @value{GDBN} at +startup, in the order they will be loaded, you can use @kbd{gdb +--help}. + +@cindex early initialization +The @dfn{early initialization} file is loaded very early in +@value{GDBN}'s initialization process, before the interpreter +(@pxref{Interpreters}) has been initialized, and before the default +target (@pxref{Targets}) is initialized. Only @code{set} or +@code{source} commands should be placed into an early initialization +file, and the only @code{set} commands that can be used are those that +control how @value{GDBN} starts up. + +Commands that can be placed into an early initialization file will be +documented as such throughout this manual. Any command that is not +documented as being suitable for an early initialization file should +instead be placed into a general initialization file. Command files +passed to @code{--early-init-command} or @code{-eix} are also early +initialization files, with the same command restrictions. Only +commands that can appear in an early initialization file should be +passed to @code{--early-init-eval-command} or @code{-eiex}. + +@cindex general initialization +In contrast, the @dfn{general initialization} files are processed +later, after @value{GDBN} has finished its own internal initialization +process, any valid command can be used in these files. + +@cindex initialization file +Throughout the rest of this document the term @dfn{initialization +file} refers to one of the general initialization files, not the early +initialization file. Any discussion of the early initialization file +will specifically mention that it is the early initialization file +being discussed. + +As the system wide and home directory initialization files are +processed before most command line options, changes to settings +(e.g.@: @samp{set complaints}) can affect subsequent processing of +command line options and operands. + +The following sections describe where @value{GDBN} looks for the early +initialization and initialization files, and the order that the files +are searched for. + +@subsubsection Home directory early initialization files + +@value{GDBN} initially looks for an early initialization file in the +users home directory@footnote{On DOS/Windows systems, the home +directory is the one pointed to by the @env{HOME} environment +variable.}. There are a number of locations that @value{GDBN} will +search in the home directory, these locations are searched in order +and @value{GDBN} will load the first file that it finds, and +subsequent locations will not be checked. + +On non-macOS hosts the locations searched are: +@itemize +@item +The file @file{gdb/gdbearlyinit} within the directory pointed to by the +environment variable @env{XDG_CONFIG_HOME}, if it is defined. +@item +The file @file{.config/gdb/gdbearlyinit} within the directory pointed to +by the environment variable @env{HOME}, if it is defined. +@item +The file @file{.gdbearlyinit} within the directory pointed to by the +environment variable @env{HOME}, if it is defined. +@end itemize + +By contrast, on macOS hosts the locations searched are: +@itemize +@item +The file @file{Library/Preferences/gdb/gdbearlyinit} within the +directory pointed to by the environment variable @env{HOME}, if it is +defined. +@item +The file @file{.gdbearlyinit} within the directory pointed to by the +environment variable @env{HOME}, if it is defined. +@end itemize + +It is possible to prevent the home directory early initialization file +from being loaded using the @samp{-nx} or @samp{-nh} command line +options, @pxref{Mode Options,,Choosing Modes}. + +@anchor{System Wide Init Files} +@subsubsection System wide initialization files + +There are two locations that are searched for system wide +initialization files. Both of these locations are always checked: + +@table @code + +@item @file{system.gdbinit} +This is a single system-wide initialization file. Its location is +specified with the @code{--with-system-gdbinit} configure option +(@pxref{System-wide configuration}). It is loaded first when +@value{GDBN} starts, before command line options have been processed. + +@item @file{system.gdbinit.d} +This is the system-wide initialization directory. Its location is +specified with the @code{--with-system-gdbinit-dir} configure option +(@pxref{System-wide configuration}). Files in this directory are +loaded in alphabetical order immediately after @file{system.gdbinit} +(if enabled) when @value{GDBN} starts, before command line options +have been processed. Files need to have a recognized scripting +language extension (@file{.py}/@file{.scm}) or be named with a +@file{.gdb} extension to be interpreted as regular @value{GDBN} +commands. @value{GDBN} will not recurse into any subdirectories of +this directory. + +@end table + +It is possible to prevent the system wide initialization files from +being loaded using the @samp{-nx} command line option, @pxref{Mode +Options,,Choosing Modes}. + +@anchor{Home Directory Init File} +@subsubsection Home directory initialization file +@cindex @file{gdbinit} +@cindex @file{.gdbinit} +@cindex @file{gdb.ini} + +After loading the system wide initialization files @value{GDBN} will +look for an initialization file in the users home +directory@footnote{On DOS/Windows systems, the home directory is the +one pointed to by the @env{HOME} environment variable.}. There are a +number of locations that @value{GDBN} will search in the home +directory, these locations are searched in order and @value{GDBN} will +load the first file that it finds, and subsequent locations will not +be checked. + +On non-Apple hosts the locations searched are: +@table @file +@item $XDG_CONFIG_HOME/gdb/gdbinit +@item $HOME/.config/gdb/gdbinit +@item $HOME/.gdbinit +@end table + +While on Apple hosts the locations searched are: +@table @file +@item $HOME/Library/Preferences/gdb/gdbinit +@item $HOME/.gdbinit +@end table + +It is possible to prevent the home directory initialization file from +being loaded using the @samp{-nx} or @samp{-nh} command line options, +@pxref{Mode Options,,Choosing Modes}. + +The DJGPP port of @value{GDBN} uses the name @file{gdb.ini} instead of +@file{.gdbinit} or @file{gdbinit}, due to the limitations of file +names imposed by DOS filesystems. The Windows port of @value{GDBN} +uses the standard name, but if it finds a @file{gdb.ini} file in your +home directory, it warns you about that and suggests to rename the +file to the standard name. + +@anchor{Init File in the Current Directory during Startup} +@subsubsection Local directory initialization file + +@value{GDBN} will check the current directory for a file called +@file{.gdbinit}. It is loaded last, after command line options +other than @samp{-x} and @samp{-ex} have been processed. The command +line options @samp{-x} and @samp{-ex} are processed last, after +@file{.gdbinit} has been loaded, @pxref{File Options,,Choosing +Files}. + +If the file in the current directory was already loaded as the home +directory initialization file then it will not be loaded a second +time. + +It is possible to prevent the local directory initialization file from +being loaded using the @samp{-nx} command line option, @pxref{Mode +Options,,Choosing Modes}. + +@node Quitting GDB +@section Quitting @value{GDBN} +@cindex exiting @value{GDBN} +@cindex leaving @value{GDBN} + +@table @code +@kindex quit @r{[}@var{expression}@r{]} +@kindex exit @r{[}@var{expression}@r{]} +@kindex q @r{(@code{quit})} +@item quit @r{[}@var{expression}@r{]} +@itemx exit @r{[}@var{expression}@r{]} +@itemx q +To exit @value{GDBN}, use the @code{quit} command (abbreviated +@code{q}), the @code{exit} command, or type an end-of-file +character (usually @kbd{Ctrl-d}). If you do not supply @var{expression}, +@value{GDBN} will terminate normally; otherwise it will terminate using +the result of @var{expression} as the error code. +@end table + +@cindex interrupt +An interrupt (often @kbd{Ctrl-c}) does not exit from @value{GDBN}, but rather +terminates the action of any @value{GDBN} command that is in progress and +returns to @value{GDBN} command level. It is safe to type the interrupt +character at any time because @value{GDBN} does not allow it to take effect +until a time when it is safe. + +If you have been using @value{GDBN} to control an attached process or +device, you can release it with the @code{detach} command +(@pxref{Attach, ,Debugging an Already-running Process}). + +@node Shell Commands +@section Shell Commands + +If you need to execute occasional shell commands during your +debugging session, there is no need to leave or suspend @value{GDBN}; you can +just use the @code{shell} command. + +@table @code +@kindex shell +@kindex ! +@cindex shell escape +@item shell @var{command-string} +@itemx !@var{command-string} +Invoke a shell to execute @var{command-string}. +Note that no space is needed between @code{!} and @var{command-string}. +On GNU and Unix systems, the environment variable @env{SHELL}, if it +exists, determines which shell to run. Otherwise @value{GDBN} uses +the default shell (@file{/bin/sh} on GNU and Unix systems, +@file{cmd.exe} on MS-Windows, @file{COMMAND.COM} on MS-DOS, etc.). +@end table + +You may also invoke shell commands from expressions, using the +@code{$_shell} convenience function. @xref{$_shell convenience +function}. + +The utility @code{make} is often needed in development environments. +You do not have to use the @code{shell} command for this purpose in +@value{GDBN}: + +@table @code +@kindex make +@cindex calling make +@item make @var{make-args} +Execute the @code{make} program with the specified +arguments. This is equivalent to @samp{shell make @var{make-args}}. +@end table + +@table @code +@kindex pipe +@kindex | +@cindex send the output of a gdb command to a shell command +@anchor{pipe} +@item pipe [@var{command}] | @var{shell_command} +@itemx | [@var{command}] | @var{shell_command} +@itemx pipe -d @var{delim} @var{command} @var{delim} @var{shell_command} +@itemx | -d @var{delim} @var{command} @var{delim} @var{shell_command} +Executes @var{command} and sends its output to @var{shell_command}. +Note that no space is needed around @code{|}. +If no @var{command} is provided, the last command executed is repeated. + +In case the @var{command} contains a @code{|}, the option @code{-d @var{delim}} +can be used to specify an alternate delimiter string @var{delim} that separates +the @var{command} from the @var{shell_command}. + +Example: +@smallexample +@group +(@value{GDBP}) p var +$1 = @{ + black = 144, + red = 233, + green = 377, + blue = 610, + white = 987 +@} +@end group +@group +(@value{GDBP}) pipe p var|wc + 7 19 80 +(@value{GDBP}) |p var|wc -l +7 +@end group +@group +(@value{GDBP}) p /x var +$4 = @{ + black = 0x90, + red = 0xe9, + green = 0x179, + blue = 0x262, + white = 0x3db +@} +(@value{GDBP}) ||grep red + red => 0xe9, +@end group +@group +(@value{GDBP}) | -d ! echo this contains a | char\n ! sed -e 's/|/PIPE/' +this contains a PIPE char +(@value{GDBP}) | -d xxx echo this contains a | char!\n xxx sed -e 's/|/PIPE/' +this contains a PIPE char! +(@value{GDBP}) +@end group +@end smallexample +@end table + +The convenience variables @code{$_shell_exitcode} and @code{$_shell_exitsignal} +can be used to examine the exit status of the last shell command launched +by @code{shell}, @code{make}, @code{pipe} and @code{|}. +@xref{Convenience Vars,, Convenience Variables}. + +@node Logging Output +@section Logging Output +@cindex logging @value{GDBN} output +@cindex save @value{GDBN} output to a file + +You may want to save the output of @value{GDBN} commands to a file. +There are several commands to control @value{GDBN}'s logging. + +@table @code +@kindex set logging enabled +@item set logging enabled [on|off] +Enable or disable logging. +@cindex logging file name +@item set logging file @var{file} +Change the name of the current logfile. The default logfile is @file{gdb.txt}. +@item set logging overwrite [on|off] +By default, @value{GDBN} will append to the logfile. Set @code{overwrite} if +you want @code{set logging enabled on} to overwrite the logfile instead. +@item set logging redirect [on|off] +By default, @value{GDBN} output will go to both the terminal and the logfile. +Set @code{redirect} if you want output to go only to the log file. +@item set logging debugredirect [on|off] +By default, @value{GDBN} debug output will go to both the terminal and the logfile. +Set @code{debugredirect} if you want debug output to go only to the log file. +@kindex show logging +@item show logging +Show the current values of the logging settings. +@end table + +You can also redirect the output of a @value{GDBN} command to a +shell command. @xref{pipe}. +@node Commands +@chapter @value{GDBN} Commands + +You can abbreviate a @value{GDBN} command to the first few letters of the command +name, if that abbreviation is unambiguous; and you can repeat certain +@value{GDBN} commands by typing just @key{RET}. You can also use the @key{TAB} +key to get @value{GDBN} to fill out the rest of a word in a command (or to +show you the alternatives available, if there is more than one possibility). + +@menu +* Command Syntax:: How to give commands to @value{GDBN} +* Command Settings:: How to change default behavior of commands +* Completion:: Command completion +* Filename Arguments:: Filenames As Command Arguments +* Command Options:: Command options +* Help:: How to ask @value{GDBN} for help +@end menu + +@node Command Syntax +@section Command Syntax + +A @value{GDBN} command is a single line of input. There is no limit on +how long it can be. It starts with a command name, which is followed by +arguments whose meaning depends on the command name. For example, the +command @code{step} accepts an argument which is the number of times to +step, as in @samp{step 5}. You can also use the @code{step} command +with no arguments. Some commands do not allow any arguments. + +@cindex abbreviation +@value{GDBN} command names may always be truncated if that abbreviation is +unambiguous. Other possible command abbreviations are listed in the +documentation for individual commands. In some cases, even ambiguous +abbreviations are allowed; for example, @code{s} is specially defined as +equivalent to @code{step} even though there are other commands whose +names start with @code{s}. You can test abbreviations by using them as +arguments to the @code{help} command. + +@cindex repeating commands +@kindex RET @r{(repeat last command)} +A blank line as input to @value{GDBN} (typing just @key{RET}) means to +repeat the previous command. Certain commands (for example, @code{run}) +will not repeat this way; these are commands whose unintentional +repetition might cause trouble and which you are unlikely to want to +repeat. User-defined commands can disable this feature; see +@ref{Define, dont-repeat}. + +The @code{list} and @code{x} commands, when you repeat them with +@key{RET}, construct new arguments rather than repeating +exactly as typed. This permits easy scanning of source or memory. + +@value{GDBN} can also use @key{RET} in another way: to partition lengthy +output, in a way similar to the common utility @code{more} +(@pxref{Screen Size,,Screen Size}). Since it is easy to press one +@key{RET} too many in this situation, @value{GDBN} disables command +repetition after any command that generates this sort of display. + +@kindex # @r{(a comment)} +@cindex comment +Any text from a @kbd{#} to the end of the line is a comment; it does +nothing. This is useful mainly in command files (@pxref{Command +Files,,Command Files}). + +@cindex repeating command sequences +@kindex Ctrl-o @r{(operate-and-get-next)} +The @kbd{Ctrl-o} binding is useful for repeating a complex sequence of +commands. This command accepts the current line, like @key{RET}, and +then fetches the next line relative to the current line from the history +for editing. + + +@node Command Settings +@section Command Settings +@cindex default behavior of commands, changing +@cindex default settings, changing + +Many commands change their behavior according to command-specific +variables or settings. These settings can be changed with the +@code{set} subcommands. For example, the @code{print} command +(@pxref{Data, ,Examining Data}) prints arrays differently depending on +settings changeable with the commands @code{set print elements +NUMBER-OF-ELEMENTS} and @code{set print array-indexes}, among others. + +You can change these settings to your preference in the gdbinit files +loaded at @value{GDBN} startup. @xref{Startup}. + +The settings can also be changed interactively during the debugging +session. For example, to change the limit of array elements to print, +you can do the following: +@smallexample +(@value{GDBP}) set print elements 10 +(@value{GDBP}) print some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +The above @code{set print elements 10} command changes the number of +elements to print from the default of 200 to 10. If you only intend +this limit of 10 to be used for printing @code{some_array}, then you +must restore the limit back to 200, with @code{set print elements +200}. + +Some commands allow overriding settings with command options. For +example, the @code{print} command supports a number of options that +allow overriding relevant global print settings as set by @code{set +print} subcommands. @xref{print options}. The example above could be +rewritten as: +@smallexample +(@value{GDBP}) print -elements 10 -- some_array +$1 = @{0, 10, 20, 30, 40, 50, 60, 70, 80, 90...@} +@end smallexample + +Alternatively, you can use the @code{with} command to change a setting +temporarily, for the duration of a command invocation. + +@table @code +@kindex with command +@kindex w @r{(@code{with})} +@cindex settings +@cindex temporarily change settings +@item with @var{setting} [@var{value}] [-- @var{command}] +@itemx w @var{setting} [@var{value}] [-- @var{command}] +Temporarily set @var{setting} to @var{value} for the duration of +@var{command}. + +@var{setting} is any setting you can change with the @code{set} +subcommands. @var{value} is the value to assign to @code{setting} +while running @code{command}. + +If no @var{command} is provided, the last command executed is +repeated. + +If a @var{command} is provided, it must be preceded by a double dash +(@code{--}) separator. This is required because some settings accept +free-form arguments, such as expressions or filenames. + +For example, the command +@smallexample +(@value{GDBP}) with print array on -- print some_array +@end smallexample +@noindent +is equivalent to the following 3 commands: +@smallexample +(@value{GDBP}) set print array on +(@value{GDBP}) print some_array +(@value{GDBP}) set print array off +@end smallexample + +The @code{with} command is particularly useful when you want to +override a setting while running user-defined commands, or commands +defined in Python or Guile. @xref{Extending GDB,, Extending GDB}. + +@smallexample +(@value{GDBP}) with print pretty on -- my_complex_command +@end smallexample + +To change several settings for the same command, you can nest +@code{with} commands. For example, @code{with language ada -- with +print elements 10} temporarily changes the language to Ada and sets a +limit of 10 elements to print for arrays and strings. + +@end table + +@node Completion +@section Command Completion + +@cindex completion +@cindex word completion +@value{GDBN} can fill in the rest of a word in a command for you, if there is +only one possibility; it can also show you what the valid possibilities +are for the next word in a command, at any time. This works for @value{GDBN} +commands, @value{GDBN} subcommands, command options, and the names of symbols +in your program. + +Press the @key{TAB} key whenever you want @value{GDBN} to fill out the rest +of a word. If there is only one possibility, @value{GDBN} fills in the +word, and waits for you to finish the command (or press @key{RET} to +enter it). For example, if you type + +@c FIXME "@key" does not distinguish its argument sufficiently to permit +@c complete accuracy in these examples; space introduced for clarity. +@c If texinfo enhancements make it unnecessary, it would be nice to +@c replace " @key" by "@key" in the following... +@smallexample +(@value{GDBP}) info bre@key{TAB} +@end smallexample + +@noindent +@value{GDBN} fills in the rest of the word @samp{breakpoints}, since that is +the only @code{info} subcommand beginning with @samp{bre}: + +@smallexample +(@value{GDBP}) info breakpoints +@end smallexample + +@noindent +You can either press @key{RET} at this point, to run the @code{info +breakpoints} command, or backspace and enter something else, if +@samp{breakpoints} does not look like the command you expected. (If you +were sure you wanted @code{info breakpoints} in the first place, you +might as well just type @key{RET} immediately after @samp{info bre}, +to exploit command abbreviations rather than command completion). + +If there is more than one possibility for the next word when you press +@key{TAB}, @value{GDBN} sounds a bell. You can either supply more +characters and try again, or just press @key{TAB} a second time; +@value{GDBN} displays all the possible completions for that word. For +example, you might want to set a breakpoint on a subroutine whose name +begins with @samp{make_}, but when you type @kbd{b make_@key{TAB}} @value{GDBN} +just sounds the bell. Typing @key{TAB} again displays all the +function names in your program that begin with those characters, for +example: + +@smallexample +(@value{GDBP}) b make_@key{TAB} +@exdent @value{GDBN} sounds bell; press @key{TAB} again, to see: +make_a_section_from_file make_environ +make_abs_section make_function_type +make_blockvector make_pointer_type +make_cleanup make_reference_type +make_command make_symbol_completion_list +(@value{GDBP}) b make_ +@end smallexample + +@noindent +After displaying the available possibilities, @value{GDBN} copies your +partial input (@samp{b make_} in the example) so you can finish the +command. + +If the command you are trying to complete expects either a keyword or a +number to follow, then @samp{NUMBER} will be shown among the available +completions, for example: + +@smallexample +(@value{GDBP}) print -elements @key{TAB}@key{TAB} +NUMBER unlimited +(@value{GDBP}) print -elements@tie{} +@end smallexample + +@noindent +Here, the option expects a number (e.g., @code{100}), not literal +@code{NUMBER}. Such metasyntactical arguments are always presented in +uppercase. + +If you just want to see the list of alternatives in the first place, you +can press @kbd{M-?} rather than pressing @key{TAB} twice. @kbd{M-?} +means @kbd{@key{META} ?}. You can type this either by holding down a +key designated as the @key{META} shift on your keyboard (if there is +one) while typing @kbd{?}, or as @key{ESC} followed by @kbd{?}. + +If the number of possible completions is large, @value{GDBN} will +print as much of the list as it has collected, as well as a message +indicating that the list may be truncated. + +@smallexample +(@value{GDBP}) b m@key{TAB}@key{TAB} +main +<... the rest of the possible completions ...> +*** List may be truncated, max-completions reached. *** +(@value{GDBP}) b m +@end smallexample + +@noindent +This behavior can be controlled with the following commands: + +@table @code +@kindex set max-completions +@item set max-completions @var{limit} +@itemx set max-completions unlimited +Set the maximum number of completion candidates. @value{GDBN} will +stop looking for more completions once it collects this many candidates. +This is useful when completing on things like function names as collecting +all the possible candidates can be time consuming. +The default value is 200. A value of zero disables tab-completion. +Note that setting either no limit or a very large limit can make +completion slow. +@kindex show max-completions +@item show max-completions +Show the maximum number of candidates that @value{GDBN} will collect and show +during completion. +@end table + +@cindex quotes in commands +@cindex completion of quoted strings +Sometimes the string you need, while logically a ``word'', may contain +parentheses or other characters that @value{GDBN} normally excludes from +its notion of a word. To permit word completion to work in this +situation, you may enclose words in @code{'} (single quote marks) in +@value{GDBN} commands. + +A likely situation where you might need this is in typing an +expression that involves a C@t{++} symbol name with template +parameters. This is because when completing expressions, GDB treats +the @samp{<} character as word delimiter, assuming that it's the +less-than comparison operator (@pxref{C Operators, , C and C@t{++} +Operators}). + +For example, when you want to call a C@t{++} template function +interactively using the @code{print} or @code{call} commands, you may +need to distinguish whether you mean the version of @code{name} that +was specialized for @code{int}, @code{name()}, or the version +that was specialized for @code{float}, @code{name()}. To use +the word-completion facilities in this situation, type a single quote +@code{'} at the beginning of the function name. This alerts +@value{GDBN} that it may need to consider more information than usual +when you press @key{TAB} or @kbd{M-?} to request word completion: + +@smallexample +(@value{GDBP}) p 'func<@kbd{M-?} +func() func() +(@value{GDBP}) p 'func< +@end smallexample + +When setting breakpoints however (@pxref{Location Specifications}), you don't +usually need to type a quote before the function name, because +@value{GDBN} understands that you want to set a breakpoint on a +function: + +@smallexample +(@value{GDBP}) b func<@kbd{M-?} +func() func() +(@value{GDBP}) b func< +@end smallexample + +This is true even in the case of typing the name of C@t{++} overloaded +functions (multiple definitions of the same function, distinguished by +argument type). For example, when you want to set a breakpoint you +don't need to distinguish whether you mean the version of @code{name} +that takes an @code{int} parameter, @code{name(int)}, or the version +that takes a @code{float} parameter, @code{name(float)}. + +@smallexample +(@value{GDBP}) b bubble(@kbd{M-?} +bubble(int) bubble(double) +(@value{GDBP}) b bubble(dou@kbd{M-?} +bubble(double) +@end smallexample + +See @ref{quoting names} for a description of other scenarios that +require quoting. + +For more information about overloaded functions, see @ref{C Plus Plus +Expressions, ,C@t{++} Expressions}. You can use the command @code{set +overload-resolution off} to disable overload resolution; +see @ref{Debugging C Plus Plus, ,@value{GDBN} Features for C@t{++}}. + +@cindex completion of structure field names +@cindex structure field name completion +@cindex completion of union field names +@cindex union field name completion +When completing in an expression which looks up a field in a +structure, @value{GDBN} also tries@footnote{The completer can be +confused by certain kinds of invalid expressions. Also, it only +examines the static type of the expression, not the dynamic type.} to +limit completions to the field names available in the type of the +left-hand-side: + +@smallexample +(@value{GDBP}) p gdb_stdout.@kbd{M-?} +magic to_fputs to_rewind +to_data to_isatty to_write +to_delete to_put to_write_async_safe +to_flush to_read +@end smallexample + +@noindent +This is because the @code{gdb_stdout} is a variable of the type +@code{struct ui_file} that is defined in @value{GDBN} sources as +follows: + +@smallexample +struct ui_file +@{ + int *magic; + ui_file_flush_ftype *to_flush; + ui_file_write_ftype *to_write; + ui_file_write_async_safe_ftype *to_write_async_safe; + ui_file_fputs_ftype *to_fputs; + ui_file_read_ftype *to_read; + ui_file_delete_ftype *to_delete; + ui_file_isatty_ftype *to_isatty; + ui_file_rewind_ftype *to_rewind; + ui_file_put_ftype *to_put; + void *to_data; +@} +@end smallexample + +@node Filename Arguments +@section Filenames As Command Arguments +@cindex file names, quoting and escaping + +When passing filenames (or directory names) as arguments to a command, +if the filename argument does not include any whitespace, double +quotes, or single quotes, then for all commands the filename can be +written as a simple string, for example: + +@smallexample +(@value{GDBP}) file /path/to/some/file +@end smallexample + +If the filename does include whitespace, double quotes, or single +quotes, then @value{GDBN} has two approaches for how these filenames +should be formatted; which format to use depends on which command is +being used. + +Most @value{GDBN} commands don't require, or support, quoting and +escaping. These commands treat any text after the command name, that +is not a command option (@pxref{Command Options}), as the filename, +even if the filename contains whitespace or quote characters. In the +following example the user is adding @w{@file{/path/that contains/two +spaces/}} to the auto-load safe-path (@pxref{add-auto-load-safe-path}): + +@smallexample +(@value{GDBP}) add-auto-load-safe-path /path/that contains/two spaces/ +@end smallexample + +A small number of commands require that filenames containing +whitespace or quote characters are either quoted, or have the special +characters escaped with a backslash. Commands that support this style +are marked as such in the manual, any command not marked as accepting +quoting and escaping of its filename argument, does not accept this +filename argument style. + +For example, to load the file @w{@file{/path/with spaces/to/a file}} +with the @code{file} command (@pxref{Files, ,Commands to Specify +Files}), you can escape the whitespace characters with a backslash: + +@smallexample +(@value{GDBP}) file /path/with\ spaces/to/a\ file +@end smallexample + +Alternatively the entire filename can be wrapped in either single or +double quotes, in which case no backlsashes are needed, for example: + +@smallexample +(@value{GDBP}) symbol-file "/path/with spaces/to/a file" +(@value{GDBP}) exec-file '/path/with spaces/to/a file' +@end smallexample + +It is possible to include a quote character within a quoted filename +by escaping it with a backslash, for example, within a filename +surrounded by double quotes, a double quote character should be +escaped with a backslash, but a single quote character should not be +escaped. Within a single quoted string a single quote character needs +to be escaped, but a double quote character does not. + +A literal backslash character can also be included by escaping it with +a backslash. + +@node Command Options +@section Command options + +@cindex command options +Some commands accept options starting with a leading dash. For +example, @code{print -pretty}. Similarly to command names, you can +abbreviate a @value{GDBN} option to the first few letters of the +option name, if that abbreviation is unambiguous, and you can also use +the @key{TAB} key to get @value{GDBN} to fill out the rest of a word +in an option (or to show you the alternatives available, if there is +more than one possibility). + +@cindex command options, raw input +Some commands take raw input as argument. For example, the print +command processes arbitrary expressions in any of the languages +supported by @value{GDBN}. With such commands, because raw input may +start with a leading dash that would be confused with an option or any +of its abbreviations, e.g.@: @code{print -p} (short for @code{print +-pretty} or printing negative @code{p}?), if you specify any command +option, then you must use a double-dash (@code{--}) delimiter to +indicate the end of options. + +@cindex command options, boolean + +Some options are described as accepting an argument which can be +either @code{on} or @code{off}. These are known as @dfn{boolean +options}. Similarly to boolean settings commands---@code{on} and +@code{off} are the typical values, but any of @code{1}, @code{yes} and +@code{enable} can also be used as ``true'' value, and any of @code{0}, +@code{no} and @code{disable} can also be used as ``false'' value. You +can also omit a ``true'' value, as it is implied by default. + +For example, these are equivalent: + +@smallexample +(@value{GDBP}) print -object on -pretty off -element unlimited -- *myptr +(@value{GDBP}) p -o -p 0 -e u -- *myptr +@end smallexample + +You can discover the set of options some command accepts by completing +on @code{-} after the command name. For example: + +@smallexample +(@value{GDBP}) print -@key{TAB}@key{TAB} +-address -max-depth -object -static-members +-array -memory-tag-violations -pretty -symbol +-array-indexes -nibbles -raw-values -union +-elements -null-stop -repeats -vtbl +@end smallexample + +Completion will in some cases guide you with a suggestion of what kind +of argument an option expects. For example: + +@smallexample +(@value{GDBP}) print -elements @key{TAB}@key{TAB} +NUMBER unlimited +@end smallexample + +@noindent +Here, the option expects a number (e.g., @code{100}), not literal +@code{NUMBER}. Such metasyntactical arguments are always presented in +uppercase. + +(For more on using the @code{print} command, see @ref{Data, ,Examining +Data}.) + +@node Help +@section Getting Help +@cindex online documentation +@kindex help + +You can always ask @value{GDBN} itself for information on its commands, +using the command @code{help}. + +@table @code +@kindex h @r{(@code{help})} +@item help +@itemx h +You can use @code{help} (abbreviated @code{h}) with no arguments to +display a short list of named classes of commands: + +@smallexample +(@value{GDBP}) help +List of classes of commands: + +aliases -- User-defined aliases of other commands +breakpoints -- Making program stop at certain points +data -- Examining data +files -- Specifying and examining files +internals -- Maintenance commands +obscure -- Obscure features +running -- Running the program +stack -- Examining the stack +status -- Status inquiries +support -- Support facilities +tracepoints -- Tracing of program execution without + stopping the program +user-defined -- User-defined commands + +Type "help" followed by a class name for a list of +commands in that class. +Type "help" followed by command name for full +documentation. +Command name abbreviations are allowed if unambiguous. +(@value{GDBP}) +@end smallexample +@c the above line break eliminates huge line overfull... + +@item help @var{class} +Using one of the general help classes as an argument, you can get a +list of the individual commands in that class. If a command has +aliases, the aliases are given after the command name, separated by +commas. If an alias has default arguments, the full definition of +the alias is given after the first line. +For example, here is the help display for the class @code{status}: + +@smallexample +(@value{GDBP}) help status +Status inquiries. + +List of commands: + +@c Line break in "show" line falsifies real output, but needed +@c to fit in smallbook page size. +info, inf, i -- Generic command for showing things + about the program being debugged +info address, iamain -- Describe where symbol SYM is stored. + alias iamain = info address main +info all-registers -- List of all registers and their contents, + for selected stack frame. +... +show, info set -- Generic command for showing things + about the debugger + +Type "help" followed by command name for full +documentation. +Command name abbreviations are allowed if unambiguous. +(@value{GDBP}) +@end smallexample + +@item help @var{command} +With a command name as @code{help} argument, @value{GDBN} displays a +short paragraph on how to use that command. If that command has +one or more aliases, @value{GDBN} will display a first line with +the command name and all its aliases separated by commas. +This first line will be followed by the full definition of all aliases +having default arguments. +When asking the help for an alias, the documentation for the aliased +command is shown. + +A user-defined alias can optionally be documented using the +@code{document} command (@pxref{Define, document}). @value{GDBN} then +considers this alias as different from the aliased command: this alias +is not listed in the aliased command help output, and asking help for +this alias will show the documentation provided for the alias instead of +the documentation of the aliased command. + +@kindex apropos +@item apropos [-v] @var{regexp} +The @code{apropos} command searches through all of the @value{GDBN} +commands and aliases, and their documentation, for the regular expression specified in +@var{args}. It prints out all matches found. The optional flag @samp{-v}, +which stands for @samp{verbose}, indicates to output the full documentation +of the matching commands and highlight the parts of the documentation +matching @var{regexp}. For example: + +@smallexample +apropos alias +@end smallexample + +@noindent +results in: + +@smallexample +@group +alias -- Define a new command that is an alias of an existing command +aliases -- User-defined aliases of other commands +@end group +@end smallexample + +@noindent +while + +@smallexample +apropos -v cut.*thread apply +@end smallexample + +@noindent +results in the below output, where @samp{cut for 'thread apply} +is highlighted if styling is enabled. + +@smallexample +@group +taas -- Apply a command to all threads (ignoring errors +and empty output). +Usage: taas COMMAND +shortcut for 'thread apply all -s COMMAND' + +tfaas -- Apply a command to all frames of all threads +(ignoring errors and empty output). +Usage: tfaas COMMAND +shortcut for 'thread apply all -s frame apply all -s COMMAND' +@end group +@end smallexample + +@kindex complete +@item complete @var{args} +The @code{complete @var{args}} command lists all the possible completions +for the beginning of a command. Use @var{args} to specify the beginning of the +command you want completed. For example: + +@smallexample +complete i +@end smallexample + +@noindent results in: + +@smallexample +@group +if +ignore +info +inspect +@end group +@end smallexample + +@noindent This is intended for use by @sc{gnu} Emacs. +@end table + +In addition to @code{help}, you can use the @value{GDBN} commands @code{info} +and @code{show} to inquire about the state of your program, or the state +of @value{GDBN} itself. Each command supports many topics of inquiry; this +manual introduces each of them in the appropriate context. The listings +under @code{info} and under @code{show} in the Command, Variable, and +Function Index point to all the sub-commands. @xref{Command and Variable +Index}. + +@c @group +@table @code +@kindex info +@kindex i @r{(@code{info})} +@item info +This command (abbreviated @code{i}) is for describing the state of your +program. For example, you can show the arguments passed to a function +with @code{info args}, list the registers currently in use with @code{info +registers}, or list the breakpoints you have set with @code{info breakpoints}. +You can get a complete list of the @code{info} sub-commands with +@w{@code{help info}}. + +@kindex set +@item set +You can assign the result of an expression to an environment variable with +@code{set}. For example, you can set the @value{GDBN} prompt to a $-sign with +@code{set prompt $}. + +@kindex show +@item show +In contrast to @code{info}, @code{show} is for describing the state of +@value{GDBN} itself. +You can change most of the things you can @code{show}, by using the +related command @code{set}; for example, you can control what number +system is used for displays with @code{set radix}, or simply inquire +which is currently in use with @code{show radix}. + +@kindex info set +To display all the settable parameters and their current +values, you can use @code{show} with no arguments; you may also use +@code{info set}. Both commands produce the same display. +@c FIXME: "info set" violates the rule that "info" is for state of +@c FIXME...program. Ck w/ GNU: "info set" to be called something else, +@c FIXME...or change desc of rule---eg "state of prog and debugging session"? +@end table +@c @end group + +Here are several miscellaneous @code{show} subcommands, all of which are +exceptional in lacking corresponding @code{set} commands: + +@table @code +@kindex show version +@cindex @value{GDBN} version number +@item show version +Show what version of @value{GDBN} is running. You should include this +information in @value{GDBN} bug-reports. If multiple versions of +@value{GDBN} are in use at your site, you may need to determine which +version of @value{GDBN} you are running; as @value{GDBN} evolves, new +commands are introduced, and old ones may wither away. Also, many +system vendors ship variant versions of @value{GDBN}, and there are +variant versions of @value{GDBN} in @sc{gnu}/Linux distributions as well. +The version number is the same as the one announced when you start +@value{GDBN}. + +@kindex show copying +@kindex info copying +@cindex display @value{GDBN} copyright +@item show copying +@itemx info copying +Display information about permission for copying @value{GDBN}. + +@kindex show warranty +@kindex info warranty +@item show warranty +@itemx info warranty +Display the @sc{gnu} ``NO WARRANTY'' statement, or a warranty, +if your version of @value{GDBN} comes with one. + +@anchor{show configuration} +@kindex show configuration +@item show configuration +Display detailed information about the way @value{GDBN} was configured +when it was built. This displays the optional arguments passed to the +@file{configure} script and also configuration parameters detected +automatically by @command{configure}. When reporting a @value{GDBN} +bug (@pxref{GDB Bugs}), it is important to include this information in +your report. + +This commands also displays the version number of the Readline library +that @value{GDBN} is using. After the version number will appear +either @samp{(system)} indicating @value{GDBN} is using the shared +system Readline library, or @samp{(internal)} indicating @value{GDBN} +is using a statically linked in version of the Readline library. +@end table + +@node Running +@chapter Running Programs Under @value{GDBN} + +When you run a program under @value{GDBN}, you must first generate +debugging information when you compile it. + +You may start @value{GDBN} with its arguments, if any, in an environment +of your choice. If you are doing native debugging, you may redirect +your program's input and output, debug an already running process, or +kill a child process. + +@menu +* Compilation:: Compiling for debugging +* Starting:: Starting your program +* Arguments:: Your program's arguments +* Environment:: Your program's environment + +* Working Directory:: Your program's working directory +* Input/Output:: Your program's input and output +* Attach:: Debugging an already-running process +* Kill Process:: Killing the child process +* Inferiors Connections and Programs:: Debugging multiple inferiors + connections and programs +* Threads:: Debugging programs with multiple threads +* Forks:: Debugging forks +* Checkpoint/Restart:: Setting a @emph{bookmark} to return to later +@end menu + +@node Compilation +@section Compiling for Debugging + +In order to debug a program effectively, you need to generate +debugging information when you compile it. This debugging information +is stored in the object file; it describes the data type of each +variable or function and the correspondence between source line numbers +and addresses in the executable code. + +To request debugging information, specify the @samp{-g} option when you run +the compiler. + +Programs that are to be shipped to your customers are compiled with +optimizations, using the @samp{-O} compiler option. However, some +compilers are unable to handle the @samp{-g} and @samp{-O} options +together. Using those compilers, you cannot generate optimized +executables containing debugging information. + +@value{NGCC}, the @sc{gnu} C/C@t{++} compiler, supports @samp{-g} with or +without @samp{-O}, making it possible to debug optimized code. We +recommend that you @emph{always} use @samp{-g} whenever you compile a +program. You may think your program is correct, but there is no sense +in pushing your luck. For more information, see @ref{Optimized Code}. + +Older versions of the @sc{gnu} C compiler permitted a variant option +@w{@samp{-gg}} for debugging information. @value{GDBN} no longer supports this +format; if your @sc{gnu} C compiler has this option, do not use it. + +@value{GDBN} knows about preprocessor macros and can show you their +expansion (@pxref{Macros}). Most compilers do not include information +about preprocessor macros in the debugging information if you specify +the @option{-g} flag alone. Version 3.1 and later of @value{NGCC}, +the @sc{gnu} C compiler, provides macro information if you are using +the DWARF debugging format, and specify the option @option{-g3}. + +@xref{Debugging Options,,Options for Debugging Your Program or GCC, +gcc, Using the @sc{gnu} Compiler Collection (GCC)}, for more +information on @value{NGCC} options affecting debug information. + +You will have the best debugging experience if you use the latest +version of the DWARF debugging format that your compiler supports. +DWARF is currently the most expressive and best supported debugging +format in @value{GDBN}. + +@need 2000 +@node Starting +@section Starting your Program +@cindex starting +@cindex running + +@table @code +@kindex run +@kindex r @r{(@code{run})} +@item run +@itemx r +Use the @code{run} command to start your program under @value{GDBN}. +You must first specify the program name with an argument to +@value{GDBN} (@pxref{Invocation, ,Getting In and Out of +@value{GDBN}}), or by using the @code{file} or @code{exec-file} +command (@pxref{Files, ,Commands to Specify Files}). + +@end table + +If you are running your program in an execution environment that +supports processes, @code{run} creates an inferior process and makes +that process run your program. In some environments without processes, +@code{run} jumps to the start of your program. Other targets, +like @samp{remote}, are always running. If you get an error +message like this one: + +@smallexample +The "remote" target does not support "run". +Try "help target" or "continue". +@end smallexample + +@noindent +then use @code{continue} to run your program. You may need @code{load} +first (@pxref{load}). + +The execution of a program is affected by certain information it +receives from its superior. @value{GDBN} provides ways to specify this +information, which you must do @emph{before} starting your program. (You +can change it after starting your program, but such changes only affect +your program the next time you start it.) This information may be +divided into four categories: + +@table @asis +@item The @emph{arguments.} +Specify the arguments to give your program as the arguments of the +@code{run} command. If a shell is available on your target, the shell +is used to pass the arguments, so that you may use normal conventions +(such as wildcard expansion or variable substitution) in describing +the arguments. +In Unix systems, you can control which shell is used with the +@env{SHELL} environment variable. If you do not define @env{SHELL}, +@value{GDBN} uses the default shell (@file{/bin/sh}). You can disable +use of any shell with the @code{set startup-with-shell} command (see +below for details). + +@item The @emph{environment.} +Your program normally inherits its environment from @value{GDBN}, but you can +use the @value{GDBN} commands @code{set environment} and @code{unset +environment} to change parts of the environment that affect +your program. @xref{Environment, ,Your Program's Environment}. + +@item The @emph{working directory.} +You can set your program's working directory with the command +@kbd{set cwd}. If you do not set any working directory with this +command, your program will inherit @value{GDBN}'s working directory if +native debugging, or the remote server's working directory if remote +debugging. @xref{Working Directory, ,Your Program's Working +Directory}. + +@item The @emph{standard input and output.} +Your program normally uses the same device for standard input and +standard output as @value{GDBN} is using. You can redirect input and output +in the @code{run} command line, or you can use the @code{tty} command to +set a different device for your program. +@xref{Input/Output, ,Your Program's Input and Output}. + +@cindex pipes +@emph{Warning:} While input and output redirection work, you cannot use +pipes to pass the output of the program you are debugging to another +program; if you attempt this, @value{GDBN} is likely to wind up debugging the +wrong program. +@end table + +When you issue the @code{run} command, your program begins to execute +immediately. @xref{Stopping, ,Stopping and Continuing}, for discussion +of how to arrange for your program to stop. Once your program has +stopped, you may call functions in your program, using the @code{print} +or @code{call} commands. @xref{Data, ,Examining Data}. + +If the modification time of your symbol file has changed since the last +time @value{GDBN} read its symbols, @value{GDBN} discards its symbol +table, and reads it again. When it does this, @value{GDBN} tries to retain +your current breakpoints. + +@table @code +@kindex start +@item start +@cindex run to main procedure +The name of the main procedure can vary from language to language. +With C or C@t{++}, the main procedure name is always @code{main}, but +other languages such as Ada do not require a specific name for their +main procedure. The debugger provides a convenient way to start the +execution of the program and to stop at the beginning of the main +procedure, depending on the language used. + +The @samp{start} command does the equivalent of setting a temporary +breakpoint at the beginning of the main procedure and then invoking +the @samp{run} command. + +@cindex elaboration phase +Some programs contain an @dfn{elaboration} phase where some startup code is +executed before the main procedure is called. This depends on the +languages used to write your program. In C@t{++}, for instance, +constructors for static and global objects are executed before +@code{main} is called. It is therefore possible that the debugger stops +before reaching the main procedure. However, the temporary breakpoint +will remain to halt execution. + +Specify the arguments to give to your program as arguments to the +@samp{start} command. These arguments will be given verbatim to the +underlying @samp{run} command. Note that the same arguments will be +reused if no argument is provided during subsequent calls to +@samp{start} or @samp{run}. + +It is sometimes necessary to debug the program during elaboration. In +these cases, using the @code{start} command would stop the execution +of your program too late, as the program would have already completed +the elaboration phase. Under these circumstances, either insert +breakpoints in your elaboration code before running your program or +use the @code{starti} command. + +@kindex starti +@item starti +@cindex run to first instruction +The @samp{starti} command does the equivalent of setting a temporary +breakpoint at the first instruction of a program's execution and then +invoking the @samp{run} command. For programs containing an +elaboration phase, the @code{starti} command will stop execution at +the start of the elaboration phase. + +@anchor{set exec-wrapper} +@kindex set exec-wrapper +@item set exec-wrapper @var{wrapper} +@itemx show exec-wrapper +@itemx unset exec-wrapper +When @samp{exec-wrapper} is set, the specified wrapper is used to +launch programs for debugging. @value{GDBN} starts your program +with a shell command of the form @kbd{exec @var{wrapper} +@var{program}}. Quoting is added to @var{program} and its +arguments, but not to @var{wrapper}, so you should add quotes if +appropriate for your shell. The wrapper runs until it executes +your program, and then @value{GDBN} takes control. + +You can use any program that eventually calls @code{execve} with +its arguments as a wrapper. Several standard Unix utilities do +this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending +with @code{exec "$@@"} will also work. + +For example, you can use @code{env} to pass an environment variable to +the debugged program, without setting the variable in your shell's +environment: + +@smallexample +(@value{GDBP}) set exec-wrapper env 'LD_PRELOAD=libtest.so' +(@value{GDBP}) run +@end smallexample + +This command is available when debugging locally on most targets, excluding +@sc{djgpp}, Cygwin, and MS Windows. + +@kindex set startup-with-shell +@anchor{set startup-with-shell} +@item set startup-with-shell +@itemx set startup-with-shell on +@itemx set startup-with-shell off +@itemx show startup-with-shell +On Unix systems, by default, if a shell is available on your target, +@value{GDBN}) uses it to start your program. Arguments of the +@code{run} command are passed to the shell, which does variable +substitution, expands wildcard characters and performs redirection of +I/O. In some circumstances, it may be useful to disable such use of a +shell, for example, when debugging the shell itself or diagnosing +startup failures such as: + +@smallexample +(@value{GDBP}) run +Starting program: ./a.out +During startup program terminated with signal SIGSEGV, Segmentation fault. +@end smallexample + +@noindent +which indicates the shell or the wrapper specified with +@samp{exec-wrapper} crashed, not your program. Most often, this is +caused by something odd in your shell's non-interactive mode +initialization file---such as @file{.cshrc} for C-shell, +$@file{.zshenv} for the Z shell, or the file specified in the +@env{BASH_ENV} environment variable for BASH. + +@anchor{set auto-connect-native-target} +@kindex set auto-connect-native-target +@item set auto-connect-native-target +@itemx set auto-connect-native-target on +@itemx set auto-connect-native-target off +@itemx show auto-connect-native-target + +By default, if the current inferior is not connected to any target yet +(e.g., with @code{target remote}), the @code{run} command starts your +program as a native process under @value{GDBN}, on your local machine. +If you're sure you don't want to debug programs on your local machine, +you can tell @value{GDBN} to not connect to the native target +automatically with the @code{set auto-connect-native-target off} +command. + +If @code{on}, which is the default, and if the current inferior is not +connected to a target already, the @code{run} command automatically +connects to the native target, if one is available. + +If @code{off}, and if the current inferior is not connected to a +target already, the @code{run} command fails with an error: + +@smallexample +(@value{GDBP}) run +Don't know how to run. Try "help target". +@end smallexample + +If the current inferior is already connected to a target, @value{GDBN} +always uses it with the @code{run} command. + +In any case, you can explicitly connect to the native target with the +@code{target native} command. For example, + +@smallexample +(@value{GDBP}) set auto-connect-native-target off +(@value{GDBP}) run +Don't know how to run. Try "help target". +(@value{GDBP}) target native +(@value{GDBP}) run +Starting program: ./a.out +[Inferior 1 (process 10421) exited normally] +@end smallexample + +In case you connected explicitly to the @code{native} target, +@value{GDBN} remains connected even if all inferiors exit, ready for +the next @code{run} command. Use the @code{disconnect} command to +disconnect. + +Examples of other commands that likewise respect the +@code{auto-connect-native-target} setting: @code{attach}, @code{info +proc}, @code{info os}. + +@kindex set disable-randomization +@item set disable-randomization +@itemx set disable-randomization on +This option (enabled by default in @value{GDBN}) will turn off the native +randomization of the virtual address space of the started program. This option +is useful for multiple debugging sessions to make the execution better +reproducible and memory addresses reusable across debugging sessions. + +This feature is implemented only on certain targets, including @sc{gnu}/Linux. +On @sc{gnu}/Linux you can get the same behavior using + +@smallexample +(@value{GDBP}) set exec-wrapper setarch `uname -m` -R +@end smallexample + +@item set disable-randomization off +Leave the behavior of the started executable unchanged. Some bugs rear their +ugly heads only when the program is loaded at certain addresses. If your bug +disappears when you run the program under @value{GDBN}, that might be because +@value{GDBN} by default disables the address randomization on platforms, such +as @sc{gnu}/Linux, which do that for stand-alone programs. Use @kbd{set +disable-randomization off} to try to reproduce such elusive bugs. + +On targets where it is available, virtual address space randomization +protects the programs against certain kinds of security attacks. In these +cases the attacker needs to know the exact location of a concrete executable +code. Randomizing its location makes it impossible to inject jumps misusing +a code at its expected addresses. + +Prelinking shared libraries provides a startup performance advantage but it +makes addresses in these libraries predictable for privileged processes by +having just unprivileged access at the target system. Reading the shared +library binary gives enough information for assembling the malicious code +misusing it. Still even a prelinked shared library can get loaded at a new +random address just requiring the regular relocation process during the +startup. Shared libraries not already prelinked are always loaded at +a randomly chosen address. + +Position independent executables (PIE) contain position independent code +similar to the shared libraries and therefore such executables get loaded at +a randomly chosen address upon startup. PIE executables always load even +already prelinked shared libraries at a random address. You can build such +executable using @command{gcc -fPIE -pie}. + +Heap (malloc storage), stack and custom mmap areas are always placed randomly +(as long as the randomization is enabled). + +@item show disable-randomization +Show the current setting of the explicit disable of the native randomization of +the virtual address space of the started program. + +@end table + +@node Arguments +@section Your Program's Arguments + +@cindex arguments (to your program) +The arguments to your program can be specified by the arguments of the +@code{run} command. +They are passed to a shell, which expands wildcard characters and +performs redirection of I/O, and thence to your program. Your +@env{SHELL} environment variable (if it exists) specifies what shell +@value{GDBN} uses. If you do not define @env{SHELL}, @value{GDBN} uses +the default shell (@file{/bin/sh} on Unix). + +On non-Unix systems, the program is usually invoked directly by +@value{GDBN}, which emulates I/O redirection via the appropriate system +calls, and the wildcard characters are expanded by the startup code of +the program, not by the shell. + +@code{run} with no arguments uses the same arguments used by the previous +@code{run}, or those set by the @code{set args} command. + +@table @code +@kindex set args +@item set args +Specify the arguments to be used the next time your program is run. If +@code{set args} has no arguments, @code{run} executes your program +with no arguments. Once you have run your program with arguments, +using @code{set args} before the next @code{run} is the only way to run +it again without arguments. + +@kindex show args +@item show args +Show the arguments to give your program when it is started. +@end table + +@node Environment +@section Your Program's Environment + +@cindex environment (of your program) +The @dfn{environment} consists of a set of environment variables and +their values. Environment variables conventionally record such things as +your user name, your home directory, your terminal type, and your search +path for programs to run. Usually you set up environment variables with +the shell and they are inherited by all the other programs you run. When +debugging, it can be useful to try running your program with a modified +environment without having to start @value{GDBN} over again. + +@table @code +@kindex path +@item path @var{directory} +Add @var{directory} to the front of the @env{PATH} environment variable +(the search path for executables) that will be passed to your program. +The value of @env{PATH} used by @value{GDBN} does not change. +You may specify several directory names, separated by whitespace or by a +system-dependent separator character (@samp{:} on Unix, @samp{;} on +MS-DOS and MS-Windows). If @var{directory} is already in the path, it +is moved to the front, so it is searched sooner. + +You can use the string @samp{$cwd} to refer to whatever is the current +working directory at the time @value{GDBN} searches the path. If you +use @samp{.} instead, it refers to the directory where you executed the +@code{path} command. @value{GDBN} replaces @samp{.} in the +@var{directory} argument (with the current path) before adding +@var{directory} to the search path. +@c 'path' is explicitly nonrepeatable, but RMS points out it is silly to +@c document that, since repeating it would be a no-op. + +@kindex show paths +@item show paths +Display the list of search paths for executables (the @env{PATH} +environment variable). + +@kindex show environment +@item show environment @r{[}@var{varname}@r{]} +Print the value of environment variable @var{varname} to be given to +your program when it starts. If you do not supply @var{varname}, +print the names and values of all environment variables to be given to +your program. You can abbreviate @code{environment} as @code{env}. + +@kindex set environment +@anchor{set environment} +@item set environment @var{varname} @r{[}=@var{value}@r{]} +Set environment variable @var{varname} to @var{value}. The value +changes for your program (and the shell @value{GDBN} uses to launch +it), not for @value{GDBN} itself. The @var{value} may be any string; the +values of environment variables are just strings, and any +interpretation is supplied by your program itself. The @var{value} +parameter is optional; if it is eliminated, the variable is set to a +null value. +@c "any string" here does not include leading, trailing +@c blanks. Gnu asks: does anyone care? + +For example, this command: + +@smallexample +set env USER = foo +@end smallexample + +@noindent +tells the debugged program, when subsequently run, that its user is named +@samp{foo}. (The spaces around @samp{=} are used for clarity here; they +are not actually required.) + +Note that on Unix systems, @value{GDBN} runs your program via a shell, +which also inherits the environment set with @code{set environment}. +If necessary, you can avoid that by using the @samp{env} program as a +wrapper instead of using @code{set environment}. @xref{set +exec-wrapper}, for an example doing just that. + +Environment variables that are set by the user are also transmitted to +@command{gdbserver} to be used when starting the remote inferior. +@pxref{QEnvironmentHexEncoded}. + +@kindex unset environment +@anchor{unset environment} +@item unset environment @var{varname} +Remove variable @var{varname} from the environment to be passed to your +program. This is different from @samp{set env @var{varname} =}; +@code{unset environment} removes the variable from the environment, +rather than assigning it an empty value. + +Environment variables that are unset by the user are also unset on +@command{gdbserver} when starting the remote inferior. +@pxref{QEnvironmentUnset}. +@end table + +@emph{Warning:} On Unix systems, @value{GDBN} runs your program using +the shell indicated by your @env{SHELL} environment variable if it +exists (or @code{/bin/sh} if not). If your @env{SHELL} variable +names a shell that runs an initialization file when started +non-interactively---such as @file{.cshrc} for C-shell, $@file{.zshenv} +for the Z shell, or the file specified in the @env{BASH_ENV} +environment variable for BASH---any variables you set in that file +affect your program. You may wish to move setting of environment +variables to files that are only run when you sign on, such as +@file{.login} or @file{.profile}. + +@node Working Directory +@section Your Program's Working Directory + +@cindex working directory (of your program) +Each time you start your program with @code{run}, the inferior will be +initialized with the current working directory specified by the +@kbd{set cwd} command. If no directory has been specified by this +command, then the inferior will inherit @value{GDBN}'s current working +directory as its working directory if native debugging, or it will +inherit the remote server's current working directory if remote +debugging. + +@table @code +@kindex set cwd +@cindex change inferior's working directory +@anchor{set cwd command} +@item set cwd @r{[}@var{directory}@r{]} +Set the inferior's working directory to @var{directory}, which will be +@code{glob}-expanded in order to resolve tildes (@file{~}). If no +argument has been specified, the command clears the setting and resets +it to an empty state. This setting has no effect on @value{GDBN}'s +working directory, and it only takes effect the next time you start +the inferior. The @file{~} in @var{directory} is a short for the +@dfn{home directory}, usually pointed to by the @env{HOME} environment +variable. On MS-Windows, if @env{HOME} is not defined, @value{GDBN} +uses the concatenation of @env{HOMEDRIVE} and @env{HOMEPATH} as +fallback. + +You can also change @value{GDBN}'s current working directory by using +the @code{cd} command. +@xref{cd command}. + +@kindex show cwd +@cindex show inferior's working directory +@item show cwd +Show the inferior's working directory. If no directory has been +specified by @kbd{set cwd}, then the default inferior's working +directory is the same as @value{GDBN}'s working directory. + +@kindex cd +@cindex change @value{GDBN}'s working directory +@anchor{cd command} +@item cd @r{[}@var{directory}@r{]} +Set the @value{GDBN} working directory to @var{directory}. If not +given, @var{directory} uses @file{'~'}. + +The @value{GDBN} working directory serves as a default for the +commands that specify files for @value{GDBN} to operate on. +@xref{Files, ,Commands to Specify Files}. +@xref{set cwd command}. + +@kindex pwd +@item pwd +Print the @value{GDBN} working directory. +@end table + +It is generally impossible to find the current working directory of +the process being debugged (since a program can change its directory +during its run). If you work on a system where @value{GDBN} supports +the @code{info proc} command (@pxref{Process Information}), you can +use the @code{info proc} command to find out the +current working directory of the debuggee. + +@node Input/Output +@section Your Program's Input and Output + +@cindex redirection +@cindex i/o +@cindex terminal +By default, the program you run under @value{GDBN} does input and output to +the same terminal that @value{GDBN} uses. @value{GDBN} switches the terminal +to its own terminal modes to interact with you, but it records the terminal +modes your program was using and switches back to them when you continue +running your program. + +@table @code +@kindex info terminal +@item info terminal +Displays information recorded by @value{GDBN} about the terminal modes your +program is using. +@end table + +You can redirect your program's input and/or output using shell +redirection with the @code{run} command. For example, + +@smallexample +run > outfile +@end smallexample + +@noindent +starts your program, diverting its output to the file @file{outfile}. + +@kindex tty +@cindex controlling terminal +Another way to specify where your program should do input and output is +with the @code{tty} command. This command accepts a file name as +argument, and causes this file to be the default for future @code{run} +commands. It also resets the controlling terminal for the child +process, for future @code{run} commands. For example, + +@smallexample +tty /dev/ttyb +@end smallexample + +@noindent +directs that processes started with subsequent @code{run} commands +default to do input and output on the terminal @file{/dev/ttyb} and have +that as their controlling terminal. + +An explicit redirection in @code{run} overrides the @code{tty} command's +effect on the input/output device, but not its effect on the controlling +terminal. + +When you use the @code{tty} command or redirect input in the @code{run} +command, only the input @emph{for your program} is affected. The input +for @value{GDBN} still comes from your terminal. @code{tty} is an alias +for @code{set inferior-tty}. + +@cindex inferior tty +@cindex set inferior controlling terminal +You can use the @code{show inferior-tty} command to tell @value{GDBN} to +display the name of the terminal that will be used for future runs of your +program. + +@table @code +@item set inferior-tty [ @var{tty} ] +@kindex set inferior-tty +Set the tty for the program being debugged to @var{tty}. Omitting @var{tty} +restores the default behavior, which is to use the same terminal as +@value{GDBN}. + +@item show inferior-tty +@kindex show inferior-tty +Show the current tty for the program being debugged. +@end table + +@node Attach +@section Debugging an Already-running Process +@kindex attach +@cindex attach + +@table @code +@item attach @var{process-id} +This command attaches to a running process---one that was started +outside @value{GDBN}. (@code{info files} shows your active +targets.) The command takes as argument a process ID. The usual way to +find out the @var{process-id} of a Unix process is with the @code{ps} utility, +or with the @samp{jobs -l} shell command. + +@code{attach} does not repeat if you press @key{RET} a second time after +executing the command. +@end table + +To use @code{attach}, your program must be running in an environment +which supports processes; for example, @code{attach} does not work for +programs on bare-board targets that lack an operating system. You must +also have permission to send the process a signal. + +When you use @code{attach}, the debugger finds the program running in +the process first by looking in the current working directory, then (if +the program is not found) by using the source file search path +(@pxref{Source Path, ,Specifying Source Directories}). You can also use +the @code{file} command to load the program. @xref{Files, ,Commands to +Specify Files}. + +@anchor{set exec-file-mismatch} +If the debugger can determine that the executable file running in the +process it is attaching to does not match the current exec-file loaded +by @value{GDBN}, the option @code{exec-file-mismatch} specifies how to +handle the mismatch. @value{GDBN} tries to compare the files by +comparing their build IDs (@pxref{build ID}), if available. + +@table @code +@kindex exec-file-mismatch +@cindex set exec-file-mismatch +@item set exec-file-mismatch @samp{ask|warn|off} + +Whether to detect mismatch between the current executable file loaded +by @value{GDBN} and the executable file used to start the process. If +@samp{ask}, the default, display a warning and ask the user whether to +load the process executable file; if @samp{warn}, just display a +warning; if @samp{off}, don't attempt to detect a mismatch. +If the user confirms loading the process executable file, then its symbols +will be loaded as well. + +@cindex show exec-file-mismatch +@item show exec-file-mismatch +Show the current value of @code{exec-file-mismatch}. + +@end table + +The first thing @value{GDBN} does after arranging to debug the specified +process is to stop it. You can examine and modify an attached process +with all the @value{GDBN} commands that are ordinarily available when +you start processes with @code{run}. You can insert breakpoints; you +can step and continue; you can modify storage. If you would rather the +process continue running, you may use the @code{continue} command after +attaching @value{GDBN} to the process. + +@table @code +@kindex detach +@item detach +When you have finished debugging the attached process, you can use the +@code{detach} command to release it from @value{GDBN} control. Detaching +the process continues its execution. After the @code{detach} command, +that process and @value{GDBN} become completely independent once more, and you +are ready to @code{attach} another process or start one with @code{run}. +@code{detach} does not repeat if you press @key{RET} again after +executing the command. +@end table + +If you exit @value{GDBN} while you have an attached process, you detach +that process. If you use the @code{run} command, you kill that process. +By default, @value{GDBN} asks for confirmation if you try to do either of these +things; you can control whether or not you need to confirm by using the +@code{set confirm} command (@pxref{Messages/Warnings, ,Optional Warnings and +Messages}). + +@node Kill Process +@section Killing the Child Process + +@table @code +@kindex kill +@item kill +Kill the child process in which your program is running under @value{GDBN}. +@end table + +This command is useful if you wish to debug a core dump instead of a +running process. @value{GDBN} ignores any core dump file while your program +is running. + +On some operating systems, a program cannot be executed outside @value{GDBN} +while you have breakpoints set on it inside @value{GDBN}. You can use the +@code{kill} command in this situation to permit running your program +outside the debugger. + +The @code{kill} command is also useful if you wish to recompile and +relink your program, since on many systems it is impossible to modify an +executable file while it is running in a process. In this case, when you +next type @code{run}, @value{GDBN} notices that the file has changed, and +reads the symbol table again (while trying to preserve your current +breakpoint settings). + +@node Inferiors Connections and Programs +@section Debugging Multiple Inferiors Connections and Programs + +@value{GDBN} lets you run and debug multiple programs in a single +session. In addition, @value{GDBN} on some systems may let you run +several programs simultaneously (otherwise you have to exit from one +before starting another). On some systems @value{GDBN} may even let +you debug several programs simultaneously on different remote systems. +In the most general case, you can have multiple threads of execution +in each of multiple processes, launched from multiple executables, +running on different machines. + +@cindex inferior +@value{GDBN} represents the state of each program execution with an +object called an @dfn{inferior}. An inferior typically corresponds to +a process, but is more general and applies also to targets that do not +have processes. Inferiors may be created before a process runs, and +may be retained after a process exits. Inferiors have unique +identifiers that are different from process ids. Usually each +inferior will also have its own distinct address space, although some +embedded targets may have several inferiors running in different parts +of a single address space. Each inferior may in turn have multiple +threads running in it. + +@cindex ID list +The commands @code{info inferiors} and @code{info connections}, which will be +introduced below, accept a space-separated @dfn{ID list} as their argument +specifying one or more elements on which to operate. A list element can be +either a single non-negative number, like @samp{5}, or an ascending range of +such numbers, like @samp{5-7}. A list can consist of any combination of such +elements, even duplicates or overlapping ranges are valid. E.g.@: +@samp{1 4-6 5 4-4} or @samp{1 2 4-7}. + +To find out what inferiors exist at any moment, use @w{@code{info +inferiors}}: + +@table @code +@kindex info inferiors [ @var{id}@dots{} ] +@item info inferiors +Print a list of all inferiors currently being managed by @value{GDBN}. +By default all inferiors are printed, but the ID list @var{id}@dots{} can be +used to limit the display to just the requested inferiors. + +@value{GDBN} displays for each inferior (in this order): + +@enumerate +@item +the inferior number assigned by @value{GDBN} + +@item +the target system's inferior identifier + +@item +the target connection the inferior is bound to, including the unique +connection number assigned by @value{GDBN}, and the protocol used by +the connection. + +@item +the name of the executable the inferior is running. + +@end enumerate + +@noindent +An asterisk @samp{*} preceding the @value{GDBN} inferior number +indicates the current inferior. + +For example, +@end table +@c end table here to get a little more width for example + +@smallexample +(@value{GDBP}) info inferiors + Num Description Connection Executable +* 1 process 3401 1 (native) goodbye + 2 process 2307 2 (extended-remote host:10000) hello +@end smallexample + +To get information about the current inferior, use @code{inferior}: + +@table @code +@kindex inferior +@item inferior +Shows information about the current inferior. + +For example, +@end table +@c end table here to get a little more width for example + +@smallexample +(@value{GDBP}) inferior +[Current inferior is 1 [process 3401] (helloworld)] +@end smallexample + +To find out what open target connections exist at any moment, use +@w{@code{info connections}}: + +@table @code +@kindex info connections [ @var{id}@dots{} ] +@item info connections +Print a list of all open target connections currently being managed by +@value{GDBN}. By default all connections are printed, but the ID list +@var{id}@dots{} can be used to limit the display to just the requested +connections. + +@value{GDBN} displays for each connection (in this order): + +@enumerate +@item +the connection number assigned by @value{GDBN}. + +@item +the protocol used by the connection. + +@item +a textual description of the protocol used by the connection. + +@end enumerate + +@noindent +An asterisk @samp{*} preceding the connection number indicates the +connection of the current inferior. + +For example, +@end table +@c end table here to get a little more width for example + +@smallexample +(@value{GDBP}) info connections + Num What Description +* 1 extended-remote host:10000 Extended remote serial target in gdb-specific protocol + 2 native Native process + 3 core Local core dump file +@end smallexample + +To switch focus between inferiors, use the @code{inferior} command: + +@table @code +@kindex inferior @var{infno} +@item inferior @var{infno} +Make inferior number @var{infno} the current inferior. The argument +@var{infno} is the inferior number assigned by @value{GDBN}, as shown +in the first field of the @samp{info inferiors} display. +@end table + +@vindex $_inferior@r{, convenience variable} +The debugger convenience variable @samp{$_inferior} contains the +number of the current inferior. You may find this useful in writing +breakpoint conditional expressions, command scripts, and so forth. +@xref{Convenience Vars,, Convenience Variables}, for general +information on convenience variables. + +You can get multiple executables into a debugging session via the +@code{add-inferior} and @w{@code{clone-inferior}} commands. On some +systems @value{GDBN} can add inferiors to the debug session +automatically by following calls to @code{fork} and @code{exec}. To +remove inferiors from the debugging session use the +@w{@code{remove-inferiors}} command. + +@table @code +@anchor{add_inferior_cli} +@kindex add-inferior +@item add-inferior [ -copies @var{n} ] [ -exec @var{executable} ] [-no-connection ] +Adds @var{n} inferiors to be run using @var{executable} as the +executable; @var{n} defaults to 1. If no executable is specified, +the inferiors begins empty, with no program. You can still assign or +change the program assigned to the inferior at any time by using the +@code{file} command with the executable name as its argument. + +By default, the new inferior begins connected to the same target +connection as the current inferior. For example, if the current +inferior was connected to @code{gdbserver} with @code{target remote}, +then the new inferior will be connected to the same @code{gdbserver} +instance. The @samp{-no-connection} option starts the new inferior +with no connection yet. You can then for example use the @code{target +remote} command to connect to some other @code{gdbserver} instance, +use @code{run} to spawn a local program, etc. + +@kindex clone-inferior +@item clone-inferior [ -copies @var{n} ] [ @var{infno} ] +Adds @var{n} inferiors ready to execute the same program as inferior +@var{infno}; @var{n} defaults to 1, and @var{infno} defaults to the +number of the current inferior. This command copies the values of the +@var{args}, @w{@var{inferior-tty}} and @var{cwd} properties from the +current inferior to the new one. It also propagates changes the user +made to environment variables using the @w{@code{set environment}} and +@w{@code{unset environment}} commands. This is a convenient command +when you want to run another instance of the inferior you are debugging. + +@smallexample +(@value{GDBP}) info inferiors + Num Description Connection Executable +* 1 process 29964 1 (native) helloworld +(@value{GDBP}) clone-inferior +Added inferior 2. +1 inferiors added. +(@value{GDBP}) info inferiors + Num Description Connection Executable +* 1 process 29964 1 (native) helloworld + 2 1 (native) helloworld +@end smallexample + +You can now simply switch focus to inferior 2 and run it. + +@anchor{remove_inferiors_cli} +@kindex remove-inferiors +@item remove-inferiors @var{infno}@dots{} +Removes the inferior or inferiors @var{infno}@dots{}. It is not +possible to remove an inferior that is running with this command. For +those, use the @code{kill} or @code{detach} command first. + +@end table + +To quit debugging one of the running inferiors that is not the current +inferior, you can either detach from it by using the @w{@code{detach +inferior}} command (allowing it to run independently), or kill it +using the @w{@code{kill inferiors}} command: + +@table @code +@kindex detach inferiors @var{infno}@dots{} +@item detach inferior @var{infno}@dots{} +Detach from the inferior or inferiors identified by @value{GDBN} +inferior number(s) @var{infno}@dots{}. Note that the inferior's entry +still stays on the list of inferiors shown by @code{info inferiors}, +but its Description will show @samp{}. + +@kindex kill inferiors @var{infno}@dots{} +@item kill inferiors @var{infno}@dots{} +Kill the inferior or inferiors identified by @value{GDBN} inferior +number(s) @var{infno}@dots{}. Note that the inferior's entry still +stays on the list of inferiors shown by @code{info inferiors}, but its +Description will show @samp{}. +@end table + +After the successful completion of a command such as @code{detach}, +@code{detach inferiors}, @code{kill} or @code{kill inferiors}, or after +a normal process exit, the inferior is still valid and listed with +@code{info inferiors}, ready to be restarted. + + +To be notified when inferiors are started or exit under @value{GDBN}'s +control use @w{@code{set print inferior-events}}: + +@table @code +@kindex set print inferior-events +@cindex print messages on inferior start and exit +@item set print inferior-events +@itemx set print inferior-events on +@itemx set print inferior-events off +The @code{set print inferior-events} command allows you to enable or +disable printing of messages when @value{GDBN} notices that new +inferiors have started or that inferiors have exited or have been +detached. By default, these messages will be printed. + +@kindex show print inferior-events +@item show print inferior-events +Show whether messages will be printed when @value{GDBN} detects that +inferiors have started, exited or have been detached. +@end table + +Many commands will work the same with multiple programs as with a +single program: e.g., @code{print myglobal} will simply display the +value of @code{myglobal} in the current inferior. + + +Occasionally, when debugging @value{GDBN} itself, it may be useful to +get more info about the relationship of inferiors, programs, address +spaces in a debug session. You can do that with the @w{@code{maint +info program-spaces}} command. + +@table @code +@kindex maint info program-spaces +@item maint info program-spaces +Print a list of all program spaces currently being managed by +@value{GDBN}. + +@value{GDBN} displays for each program space (in this order): + +@enumerate +@item +the program space number assigned by @value{GDBN} + +@item +the name of the executable loaded into the program space, with e.g., +the @code{file} command. + +@item +the name of the core file loaded into the program space, with e.g., +the @code{core-file} command. + +@end enumerate + +@noindent +An asterisk @samp{*} preceding the @value{GDBN} program space number +indicates the current program space. + +In addition, below each program space line, @value{GDBN} prints extra +information that isn't suitable to display in tabular form. For +example, the list of inferiors bound to the program space. + +@smallexample +(@value{GDBP}) maint info program-spaces + Id Executable Core File +* 1 hello + 2 goodbye + Bound inferiors: ID 1 (process 21561) +@end smallexample + +Here we can see that no inferior is running the program @code{hello}, +while @code{process 21561} is running the program @code{goodbye}. On +some targets, it is possible that multiple inferiors are bound to the +same program space. The most common example is that of debugging both +the parent and child processes of a @code{vfork} call. For example, + +@smallexample +(@value{GDBP}) maint info program-spaces + Id Executable Core File +* 1 vfork-test + Bound inferiors: ID 2 (process 18050), ID 1 (process 18045) +@end smallexample + +Here, both inferior 2 and inferior 1 are running in the same program +space as a result of inferior 1 having executed a @code{vfork} call. +@end table + +@menu +* Inferior-Specific Breakpoints:: Controlling breakpoints +@end menu + +@node Inferior-Specific Breakpoints +@subsection Inferior-Specific Breakpoints + +When debugging multiple inferiors, you can choose whether to set +breakpoints for all inferiors, or for a particular inferior. + +@table @code +@cindex breakpoints and inferiors +@cindex inferior-specific breakpoints +@kindex break @dots{} inferior @var{inferior-id} +@item break @var{locspec} inferior @var{inferior-id} +@itemx break @var{locspec} inferior @var{inferior-id} if @dots{} +@var{locspec} specifies a code location or locations in your program. +@xref{Location Specifications}, for details. + +Use the qualifier @samp{inferior @var{inferior-id}} with a breakpoint +command to specify that you only want @value{GDBN} to stop when a +particular inferior reaches this breakpoint. The @var{inferior-id} +specifier is one of the inferior identifiers assigned by @value{GDBN}, +shown in the first column of the @samp{info inferiors} output. + +If you do not specify @samp{inferior @var{inferior-id}} when you set a +breakpoint, the breakpoint applies to @emph{all} inferiors of your +program. + +You can use the @code{inferior} qualifier on conditional breakpoints as +well; in this case, place @samp{inferior @var{inferior-id}} before or +after the breakpoint condition, like this: + +@smallexample +(@value{GDBP}) break frik.c:13 inferior 2 if bartab > lim +@end smallexample +@end table + +Inferior-specific breakpoints are automatically deleted when the +corresponding inferior is removed from @value{GDBN}. For example: + +@smallexample +(@value{GDBP}) remove-inferiors 2 +Inferior-specific breakpoint 3 deleted - inferior 2 has been removed. +@end smallexample + +A breakpoint can't be both inferior-specific and thread-specific +(@pxref{Thread-Specific Breakpoints}), or task-specific (@pxref{Ada +Tasks}); using more than one of the @code{inferior}, @code{thread}, or +@code{task} keywords when creating a breakpoint will give an error. + +@node Threads +@section Debugging Programs with Multiple Threads + +@cindex threads of execution +@cindex multiple threads +@cindex switching threads +In some operating systems, such as GNU/Linux and Solaris, a single program +may have more than one @dfn{thread} of execution. The precise semantics +of threads differ from one operating system to another, but in general +the threads of a single program are akin to multiple processes---except +that they share one address space (that is, they can all examine and +modify the same variables). On the other hand, each thread has its own +registers and execution stack, and perhaps private memory. + +@value{GDBN} provides these facilities for debugging multi-thread +programs: + +@itemize @bullet +@item automatic notification of new threads +@item @samp{thread @var{thread-id}}, a command to switch among threads +@item @samp{info threads}, a command to inquire about existing threads +@item @samp{thread apply [@var{thread-id-list} | all] @var{args}}, +a command to apply a command to a list of threads +@item thread-specific breakpoints +@item @samp{set print thread-events}, which controls printing of +messages on thread start and exit. +@item @samp{set libthread-db-search-path @var{path}}, which lets +the user specify which @code{libthread_db} to use if the default choice +isn't compatible with the program. +@end itemize + +@cindex focus of debugging +@cindex current thread +The @value{GDBN} thread debugging facility allows you to observe all +threads while your program runs---but whenever @value{GDBN} takes +control, one thread in particular is always the focus of debugging. +This thread is called the @dfn{current thread}. Debugging commands show +program information from the perspective of the current thread. + +@cindex @code{New} @var{systag} message +@cindex thread identifier (system) +@c FIXME-implementors!! It would be more helpful if the [New...] message +@c included GDB's numeric thread handle, so you could just go to that +@c thread without first checking `info threads'. +Whenever @value{GDBN} detects a new thread in your program, it displays +the target system's identification for the thread with a message in the +form @samp{[New @var{systag}]}, where @var{systag} is a thread identifier +whose form varies depending on the particular system. For example, on +@sc{gnu}/Linux, you might see + +@smallexample +[New Thread 0x41e02940 (LWP 25582)] +@end smallexample + +@noindent +when @value{GDBN} notices a new thread. In contrast, on other systems, +the @var{systag} is simply something like @samp{process 368}, with no +further qualifier. + +@c FIXME!! (1) Does the [New...] message appear even for the very first +@c thread of a program, or does it only appear for the +@c second---i.e.@: when it becomes obvious we have a multithread +@c program? +@c (2) *Is* there necessarily a first thread always? Or do some +@c multithread systems permit starting a program with multiple +@c threads ab initio? + +@anchor{thread numbers} +@cindex thread number, per inferior +@cindex thread identifier (GDB) +For debugging purposes, @value{GDBN} associates its own thread number +---always a single integer---with each thread of an inferior. This +number is unique between all threads of an inferior, but not unique +between threads of different inferiors. + +@cindex qualified thread ID +You can refer to a given thread in an inferior using the qualified +@var{inferior-num}.@var{thread-num} syntax, also known as +@dfn{qualified thread ID}, with @var{inferior-num} being the inferior +number and @var{thread-num} being the thread number of the given +inferior. For example, thread @code{2.3} refers to thread number 3 of +inferior 2. If you omit @var{inferior-num} (e.g., @code{thread 3}), +then @value{GDBN} infers you're referring to a thread of the current +inferior. + +Until you create a second inferior, @value{GDBN} does not show the +@var{inferior-num} part of thread IDs, even though you can always use +the full @var{inferior-num}.@var{thread-num} form to refer to threads +of inferior 1, the initial inferior. + +@anchor{thread ID lists} +@cindex thread ID lists +Some commands accept a space-separated @dfn{thread ID list} as +argument. A list element can be: + +@enumerate +@item +A thread ID as shown in the first field of the @samp{info threads} +display, with or without an inferior qualifier. E.g., @samp{2.1} or +@samp{1}. + +@item +A range of thread numbers, again with or without an inferior +qualifier, as in @var{inf}.@var{thr1}-@var{thr2} or +@var{thr1}-@var{thr2}. E.g., @samp{1.2-4} or @samp{2-4}. + +@item +All threads of an inferior, specified with a star wildcard, with or +without an inferior qualifier, as in @var{inf}.@code{*} (e.g., +@samp{1.*}) or @code{*}. The former refers to all threads of the +given inferior, and the latter form without an inferior qualifier +refers to all threads of the current inferior. + +@end enumerate + +For example, if the current inferior is 1, and inferior 7 has one +thread with ID 7.1, the thread list @samp{1 2-3 4.5 6.7-9 7.*} +includes threads 1 to 3 of inferior 1, thread 5 of inferior 4, threads +7 to 9 of inferior 6 and all threads of inferior 7. That is, in +expanded qualified form, the same as @samp{1.1 1.2 1.3 4.5 6.7 6.8 6.9 +7.1}. + + +@anchor{global thread numbers} +@cindex global thread number +@cindex global thread identifier (GDB) +In addition to a @emph{per-inferior} number, each thread is also +assigned a unique @emph{global} number, also known as @dfn{global +thread ID}, a single integer. Unlike the thread number component of +the thread ID, no two threads have the same global ID, even when +you're debugging multiple inferiors. + +From @value{GDBN}'s perspective, a process always has at least one +thread. In other words, @value{GDBN} assigns a thread number to the +program's ``main thread'' even if the program is not multi-threaded. + +@vindex $_thread@r{, convenience variable} +@vindex $_gthread@r{, convenience variable} +@vindex $_inferior_thread_count@r{, convenience variable} +The debugger convenience variables @samp{$_thread} and +@samp{$_gthread} contain, respectively, the per-inferior thread number +and the global thread number of the current thread. You may find this +useful in writing breakpoint conditional expressions, command scripts, +and so forth. The convenience variable @samp{$_inferior_thread_count} +contains the number of live threads in the current inferior. +@xref{Convenience Vars,, Convenience Variables}, for general +information on convenience variables. + +When running in non-stop mode (@pxref{Non-Stop Mode}), where new +threads can be created, and existing threads exit, at any time, +@samp{$_inferior_thread_count} could return a different value each +time it is evaluated. + +If @value{GDBN} detects the program is multi-threaded, it augments the +usual message about stopping at a breakpoint with the ID and name of +the thread that hit the breakpoint. + +@smallexample +Thread 2 "client" hit Breakpoint 1, send_message () at client.c:68 +@end smallexample + +Likewise when the program receives a signal: + +@smallexample +Thread 1 "main" received signal SIGINT, Interrupt. +@end smallexample + +@table @code +@anchor{info_threads} +@kindex info threads +@item info threads @r{[}-gid@r{]} @r{[}@var{thread-id-list}@r{]} + +Display information about one or more threads. With no arguments +displays information about all threads. You can specify the list of +threads that you want to display using the thread ID list syntax +(@pxref{thread ID lists}). + +@value{GDBN} displays for each thread (in this order): + +@enumerate +@item +the per-inferior thread number assigned by @value{GDBN} + +@item +the global thread number assigned by @value{GDBN}, if the @samp{-gid} +option was specified + +@item +the target system's thread identifier (@var{systag}) + +@item +the thread's name, if one is known. A thread can either be named by +the user (see @code{thread name}, below), or, in some cases, by the +program itself. + +@item +the current stack frame summary for that thread +@end enumerate + +@noindent +An asterisk @samp{*} to the left of the @value{GDBN} thread number +indicates the current thread. + +For example, +@end table +@c end table here to get a little more width for example + +@smallexample +(@value{GDBP}) info threads + Id Target Id Frame +* 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 2 process 35 thread 23 0x34e5 in sigpause () + 3 process 35 thread 27 0x34e5 in sigpause () + at threadtest.c:68 +@end smallexample + +If you're debugging multiple inferiors, @value{GDBN} displays thread +IDs using the qualified @var{inferior-num}.@var{thread-num} format. +Otherwise, only @var{thread-num} is shown. + +If you specify the @samp{-gid} option, @value{GDBN} displays a column +indicating each thread's global thread ID: + +@smallexample +(@value{GDBP}) info threads + Id GId Target Id Frame + 1.1 1 process 35 thread 13 main (argc=1, argv=0x7ffffff8) + 1.2 3 process 35 thread 23 0x34e5 in sigpause () + 1.3 4 process 35 thread 27 0x34e5 in sigpause () +* 2.1 2 process 65 thread 1 main (argc=1, argv=0x7ffffff8) +@end smallexample + +On Solaris, you can display more information about user threads with a +Solaris-specific command: + +@table @code +@item maint info sol-threads +@kindex maint info sol-threads +@cindex thread info (Solaris) +Display info on Solaris user threads. +@end table + +@table @code +@kindex thread @var{thread-id} +@item thread @var{thread-id} +Make thread ID @var{thread-id} the current thread. The command +argument @var{thread-id} is the @value{GDBN} thread ID, as shown in +the first field of the @samp{info threads} display, with or without an +inferior qualifier (e.g., @samp{2.1} or @samp{1}). + +@value{GDBN} responds by displaying the system identifier of the +thread you selected, and its current stack frame summary: + +@smallexample +(@value{GDBP}) thread 2 +[Switching to thread 2 (Thread 0xb7fdab70 (LWP 12747))] +#0 some_function (ignore=0x0) at example.c:8 +8 printf ("hello\n"); +@end smallexample + +@noindent +As with the @samp{[New @dots{}]} message, the form of the text after +@samp{Switching to} depends on your system's conventions for identifying +threads. + +@anchor{thread apply all} +@kindex thread apply +@cindex apply command to several threads +@item thread apply [@var{thread-id-list} | all [-ascending]] [@var{flag}]@dots{} @var{command} +The @code{thread apply} command allows you to apply the named +@var{command} to one or more threads. Specify the threads that you +want affected using the thread ID list syntax (@pxref{thread ID +lists}), or specify @code{all} to apply to all threads. To apply a +command to all threads in descending order, type @kbd{thread apply all +@var{command}}. To apply a command to all threads in ascending order, +type @kbd{thread apply all -ascending @var{command}}. + +The @var{flag} arguments control what output to produce and how to handle +errors raised when applying @var{command} to a thread. @var{flag} +must start with a @code{-} directly followed by one letter in +@code{qcs}. If several flags are provided, they must be given +individually, such as @code{-c -q}. + +By default, @value{GDBN} displays some thread information before the +output produced by @var{command}, and an error raised during the +execution of a @var{command} will abort @code{thread apply}. The +following flags can be used to fine-tune this behavior: + +@table @code +@item -c +The flag @code{-c}, which stands for @samp{continue}, causes any +errors in @var{command} to be displayed, and the execution of +@code{thread apply} then continues. +@item -s +The flag @code{-s}, which stands for @samp{silent}, causes any errors +or empty output produced by a @var{command} to be silently ignored. +That is, the execution continues, but the thread information and errors +are not printed. +@item -q +The flag @code{-q} (@samp{quiet}) disables printing the thread +information. +@end table + +Flags @code{-c} and @code{-s} cannot be used together. + +@kindex taas +@cindex apply command to all threads (ignoring errors and empty output) +@item taas [@var{option}]@dots{} @var{command} +Shortcut for @code{thread apply all -s [@var{option}]@dots{} @var{command}}. +Applies @var{command} on all threads, ignoring errors and empty output. + +The @code{taas} command accepts the same options as the @code{thread +apply all} command. @xref{thread apply all}. + +@kindex tfaas +@cindex apply a command to all frames of all threads (ignoring errors and empty output) +@item tfaas [@var{option}]@dots{} @var{command} +Shortcut for @code{thread apply all -s -- frame apply all -s [@var{option}]@dots{} @var{command}}. +Applies @var{command} on all frames of all threads, ignoring errors +and empty output. Note that the flag @code{-s} is specified twice: +The first @code{-s} ensures that @code{thread apply} only shows the thread +information of the threads for which @code{frame apply} produces +some output. The second @code{-s} is needed to ensure that @code{frame +apply} shows the frame information of a frame only if the +@var{command} successfully produced some output. + +It can for example be used to print a local variable or a function +argument without knowing the thread or frame where this variable or argument +is, using: +@smallexample +(@value{GDBP}) tfaas p some_local_var_i_do_not_remember_where_it_is +@end smallexample + +The @code{tfaas} command accepts the same options as the @code{frame +apply} command. @xref{Frame Apply,,frame apply}. + +@kindex thread name +@cindex name a thread +@item thread name [@var{name}] +This command assigns a name to the current thread. If no argument is +given, any existing user-specified name is removed. The thread name +appears in the @samp{info threads} display. + +On some systems, such as @sc{gnu}/Linux, @value{GDBN} is able to +determine the name of the thread as given by the OS. On these +systems, a name specified with @samp{thread name} will override the +system-give name, and removing the user-specified name will cause +@value{GDBN} to once again display the system-specified name. + +@kindex thread find +@cindex search for a thread +@item thread find [@var{regexp}] +Search for and display thread ids whose name or @var{systag} +matches the supplied regular expression. + +As well as being the complement to the @samp{thread name} command, +this command also allows you to identify a thread by its target +@var{systag}. For instance, on @sc{gnu}/Linux, the target @var{systag} +is the LWP id. + +@smallexample +(@value{GDBP}) thread find 26688 +Thread 4 has target id 'Thread 0x41e02940 (LWP 26688)' +(@value{GDBP}) info thread 4 + Id Target Id Frame + 4 Thread 0x41e02940 (LWP 26688) 0x00000031ca6cd372 in select () +@end smallexample + +@kindex set print thread-events +@cindex print messages on thread start and exit +@item set print thread-events +@itemx set print thread-events on +@itemx set print thread-events off +The @code{set print thread-events} command allows you to enable or +disable printing of messages when @value{GDBN} notices that new threads have +started or that threads have exited. By default, these messages will +be printed if detection of these events is supported by the target. +Note that these messages cannot be disabled on all targets. + +@kindex show print thread-events +@item show print thread-events +Show whether messages will be printed when @value{GDBN} detects that threads +have started and exited. +@end table + +@xref{Thread Stops,,Stopping and Starting Multi-thread Programs}, for +more information about how @value{GDBN} behaves when you stop and start +programs with multiple threads. + +@xref{Set Watchpoints,,Setting Watchpoints}, for information about +watchpoints in programs with multiple threads. + +@anchor{set libthread-db-search-path} +@table @code +@kindex set libthread-db-search-path +@cindex search path for @code{libthread_db} +@item set libthread-db-search-path @r{[}@var{path}@r{]} +If this variable is set, @var{path} is a colon-separated list of +directories @value{GDBN} will use to search for @code{libthread_db}. +If you omit @var{path}, @samp{libthread-db-search-path} will be reset to +its default value (@code{$sdir:$pdir} on @sc{gnu}/Linux and Solaris systems). +Internally, the default value comes from the @code{LIBTHREAD_DB_SEARCH_PATH} +macro. + +On @sc{gnu}/Linux and Solaris systems, @value{GDBN} uses a ``helper'' +@code{libthread_db} library to obtain information about threads in the +inferior process. @value{GDBN} will use @samp{libthread-db-search-path} +to find @code{libthread_db}. @value{GDBN} also consults first if inferior +specific thread debugging library loading is enabled +by @samp{set auto-load libthread-db} (@pxref{libthread_db.so.1 file}). + +A special entry @samp{$sdir} for @samp{libthread-db-search-path} +refers to the default system directories that are +normally searched for loading shared libraries. The @samp{$sdir} entry +is the only kind not needing to be enabled by @samp{set auto-load libthread-db} +(@pxref{libthread_db.so.1 file}). + +A special entry @samp{$pdir} for @samp{libthread-db-search-path} +refers to the directory from which @code{libpthread} +was loaded in the inferior process. + +For any @code{libthread_db} library @value{GDBN} finds in above directories, +@value{GDBN} attempts to initialize it with the current inferior process. +If this initialization fails (which could happen because of a version +mismatch between @code{libthread_db} and @code{libpthread}), @value{GDBN} +will unload @code{libthread_db}, and continue with the next directory. +If none of @code{libthread_db} libraries initialize successfully, +@value{GDBN} will issue a warning and thread debugging will be disabled. + +Setting @code{libthread-db-search-path} is currently implemented +only on some platforms. + +@kindex show libthread-db-search-path +@item show libthread-db-search-path +Display current libthread_db search path. + +@kindex set debug libthread-db +@kindex show debug libthread-db +@cindex debugging @code{libthread_db} +@item set debug libthread-db +@itemx show debug libthread-db +Turns on or off display of @code{libthread_db}-related events. +Use @code{1} to enable, @code{0} to disable. + +@kindex set debug threads +@kindex show debug threads +@cindex debugging @code{threads} +@item set debug threads @r{[}on@r{|}off@r{]} +@itemx show debug threads +When @samp{on} @value{GDBN} will print additional messages when +threads are created and deleted. +@end table + +@node Forks +@section Debugging Forks + +@cindex fork, debugging programs which call +@cindex multiple processes +@cindex processes, multiple +On most systems, @value{GDBN} has no special support for debugging +programs which create additional processes using the @code{fork} +function. When a program forks, @value{GDBN} will continue to debug the +parent process and the child process will run unimpeded. If you have +set a breakpoint in any code which the child then executes, the child +will get a @code{SIGTRAP} signal which (unless it catches the signal) +will cause it to terminate. + +However, if you want to debug the child process there is a workaround +which isn't too painful. Put a call to @code{sleep} in the code which +the child process executes after the fork. It may be useful to sleep +only if a certain environment variable is set, or a certain file exists, +so that the delay need not occur when you don't want to run @value{GDBN} +on the child. While the child is sleeping, use the @code{ps} program to +get its process ID. Then tell @value{GDBN} (a new invocation of +@value{GDBN} if you are also debugging the parent process) to attach to +the child process (@pxref{Attach}). From that point on you can debug +the child process just like any other process which you attached to. + +On some systems, @value{GDBN} provides support for debugging programs +that create additional processes using the @code{fork} or @code{vfork} +functions. On @sc{gnu}/Linux platforms, this feature is supported +with kernel version 2.5.46 and later. + +The fork debugging commands are supported in native mode and when +connected to @code{gdbserver} in either @code{target remote} mode or +@code{target extended-remote} mode. + +By default, when a program forks, @value{GDBN} will continue to debug +the parent process and the child process will run unimpeded. + +If you want to follow the child process instead of the parent process, +use the command @w{@code{set follow-fork-mode}}. + +@table @code +@kindex set follow-fork-mode +@item set follow-fork-mode @var{mode} +Set the debugger response to a program call of @code{fork} or +@code{vfork}. A call to @code{fork} or @code{vfork} creates a new +process. The @var{mode} argument can be: + +@table @code +@item parent +The original process is debugged after a fork. The child process runs +unimpeded. This is the default. + +@item child +The new process is debugged after a fork. The parent process runs +unimpeded. + +@end table + +@kindex show follow-fork-mode +@item show follow-fork-mode +Display the current debugger response to a @code{fork} or @code{vfork} call. +@end table + +@cindex debugging multiple processes +On Linux, if you want to debug both the parent and child processes, use the +command @w{@code{set detach-on-fork}}. + +@table @code +@kindex set detach-on-fork +@item set detach-on-fork @var{mode} +Tells gdb whether to detach one of the processes after a fork, or +retain debugger control over them both. + +@table @code +@item on +The child process (or parent process, depending on the value of +@code{follow-fork-mode}) will be detached and allowed to run +independently. This is the default. + +@item off +Both processes will be held under the control of @value{GDBN}. +One process (child or parent, depending on the value of +@code{follow-fork-mode}) is debugged as usual, while the other +is held suspended. + +@end table + +@kindex show detach-on-fork +@item show detach-on-fork +Show whether detach-on-fork mode is on/off. +@end table + +If you choose to set @samp{detach-on-fork} mode off, then @value{GDBN} +will retain control of all forked processes (including nested forks). +You can list the forked processes under the control of @value{GDBN} by +using the @w{@code{info inferiors}} command, and switch from one fork +to another by using the @code{inferior} command (@pxref{Inferiors Connections and +Programs, ,Debugging Multiple Inferiors Connections and Programs}). + +To quit debugging one of the forked processes, you can either detach +from it by using the @w{@code{detach inferiors}} command (allowing it +to run independently), or kill it using the @w{@code{kill inferiors}} +command. @xref{Inferiors Connections and Programs, ,Debugging +Multiple Inferiors Connections and Programs}. + +If you ask to debug a child process and a @code{vfork} is followed by an +@code{exec}, @value{GDBN} executes the new target up to the first +breakpoint in the new target. If you have a breakpoint set on +@code{main} in your original program, the breakpoint will also be set on +the child process's @code{main}. + +On some systems, when a child process is spawned by @code{vfork}, you +cannot debug the child or parent until an @code{exec} call completes. + +If you issue a @code{run} command to @value{GDBN} after an @code{exec} +call executes, the new target restarts. To restart the parent +process, use the @code{file} command with the parent executable name +as its argument. By default, after an @code{exec} call executes, +@value{GDBN} discards the symbols of the previous executable image. +You can change this behavior with the @w{@code{set follow-exec-mode}} +command. + +@table @code +@kindex set follow-exec-mode +@item set follow-exec-mode @var{mode} + +Set debugger response to a program call of @code{exec}. An +@code{exec} call replaces the program image of a process. + +@code{follow-exec-mode} can be: + +@table @code +@item new +@value{GDBN} creates a new inferior and rebinds the process to this +new inferior. The program the process was running before the +@code{exec} call can be restarted afterwards by restarting the +original inferior. + +For example: + +@smallexample +(@value{GDBP}) info inferiors +(@value{GDBP}) info inferior + Id Description Executable +* 1 prog1 +(@value{GDBP}) run +process 12020 is executing new program: prog2 +Program exited normally. +(@value{GDBP}) info inferiors + Id Description Executable + 1 prog1 +* 2 prog2 +@end smallexample + +@item same +@value{GDBN} keeps the process bound to the same inferior. The new +executable image replaces the previous executable loaded in the +inferior. Restarting the inferior after the @code{exec} call, with +e.g., the @code{run} command, restarts the executable the process was +running after the @code{exec} call. This is the default mode. + +For example: + +@smallexample +(@value{GDBP}) info inferiors + Id Description Executable +* 1 prog1 +(@value{GDBP}) run +process 12020 is executing new program: prog2 +Program exited normally. +(@value{GDBP}) info inferiors + Id Description Executable +* 1 prog2 +@end smallexample + +@end table +@end table + +@code{follow-exec-mode} is supported in native mode and +@code{target extended-remote} mode. + +You can use the @code{catch} command to make @value{GDBN} stop whenever +a @code{fork}, @code{vfork}, or @code{exec} call is made. @xref{Set +Catchpoints, ,Setting Catchpoints}. + +@node Checkpoint/Restart +@section Setting a @emph{Bookmark} to Return to Later + +@cindex checkpoint +@cindex restart +@cindex bookmark +@cindex snapshot of a process +@cindex rewind program state + +On certain operating systems@footnote{Currently, only +@sc{gnu}/Linux.}, @value{GDBN} is able to save a @dfn{snapshot} of a +program's state, called a @dfn{checkpoint}, and come back to it +later. + +Returning to a checkpoint effectively undoes everything that has +happened in the program since the @code{checkpoint} was saved. This +includes changes in memory, registers, and even (within some limits) +system state. Effectively, it is like going back in time to the +moment when the checkpoint was saved. + +Thus, if you're stepping through a program and you think you're +getting close to the point where things go wrong, you can save +a checkpoint. Then, if you accidentally go too far and miss +the critical statement, instead of having to restart your program +from the beginning, you can just go back to the checkpoint and +start again from there. + +This can be especially useful if it takes a lot of time or +steps to reach the point where you think the bug occurs. + +To use the @code{checkpoint}/@code{restart} method of debugging: + +@table @code +@kindex checkpoint +@item checkpoint +Save a snapshot of the debugged program's current execution state. +The @code{checkpoint} command takes no arguments, but each checkpoint +is assigned a small integer id, similar to a breakpoint id. + +@kindex info checkpoints +@item info checkpoints +List the checkpoints that have been saved in the current debugging +session. For each checkpoint, the following information will be +listed: + +@table @code +@item Checkpoint ID +@item Process ID +@item Code Address +@item Source line, or label +@end table + +@kindex restart @var{checkpoint-id} +@item restart @var{checkpoint-id} +Restore the program state that was saved as checkpoint number +@var{checkpoint-id}. All program variables, registers, stack frames +etc.@: will be returned to the values that they had when the checkpoint +was saved. In essence, gdb will ``wind back the clock'' to the point +in time when the checkpoint was saved. + +Note that breakpoints, @value{GDBN} variables, command history etc. +are not affected by restoring a checkpoint. In general, a checkpoint +only restores things that reside in the program being debugged, not in +the debugger. + +@kindex delete checkpoint @var{checkpoint-id} +@item delete checkpoint @var{checkpoint-id} +Delete the previously-saved checkpoint identified by @var{checkpoint-id}. + +@end table + +Returning to a previously saved checkpoint will restore the user state +of the program being debugged, plus a significant subset of the system +(OS) state, including file pointers. It won't ``un-write'' data from +a file, but it will rewind the file pointer to the previous location, +so that the previously written data can be overwritten. For files +opened in read mode, the pointer will also be restored so that the +previously read data can be read again. + +Of course, characters that have been sent to a printer (or other +external device) cannot be ``snatched back'', and characters received +from eg.@: a serial device can be removed from internal program buffers, +but they cannot be ``pushed back'' into the serial pipeline, ready to +be received again. Similarly, the actual contents of files that have +been changed cannot be restored (at this time). + +However, within those constraints, you actually can ``rewind'' your +program to a previously saved point in time, and begin debugging it +again --- and you can change the course of events so as to debug a +different execution path this time. + +@cindex checkpoints and process id +Finally, there is one bit of internal program state that will be +different when you return to a checkpoint --- the program's process +id. Each checkpoint will have a unique process id (or @var{pid}), +and each will be different from the program's original @var{pid}. +If your program has saved a local copy of its process id, this could +potentially pose a problem. + +@subsection A Non-obvious Benefit of Using Checkpoints + +On some systems such as @sc{gnu}/Linux, address space randomization +is performed on new processes for security reasons. This makes it +difficult or impossible to set a breakpoint, or watchpoint, on an +absolute address if you have to restart the program, since the +absolute location of a symbol will change from one execution to the +next. + +A checkpoint, however, is an @emph{identical} copy of a process. +Therefore if you create a checkpoint at (eg.@:) the start of main, +and simply return to that checkpoint instead of restarting the +process, you can avoid the effects of address randomization and +your symbols will all stay in the same place. + +@node Stopping +@chapter Stopping and Continuing + +The principal purposes of using a debugger are so that you can stop your +program before it terminates; or so that, if your program runs into +trouble, you can investigate and find out why. + +Inside @value{GDBN}, your program may stop for any of several reasons, +such as a signal, a breakpoint, or reaching a new line after a +@value{GDBN} command such as @code{step}. You may then examine and +change variables, set new breakpoints or remove old ones, and then +continue execution. Usually, the messages shown by @value{GDBN} provide +ample explanation of the status of your program---but you can also +explicitly request this information at any time. + +@table @code +@kindex info program +@item info program +Display information about the status of your program: whether it is +running or not, what process it is, and why it stopped. +@end table + +@menu +* Breakpoints:: Breakpoints, watchpoints, tracepoints, + and catchpoints +* Continuing and Stepping:: Resuming execution +* Skipping Over Functions and Files:: + Skipping over functions and files +* Signals:: Signals +* Thread Stops:: Stopping and starting multi-thread programs +@end menu + +@node Breakpoints +@section Breakpoints, Watchpoints, and Catchpoints + +@cindex breakpoints +A @dfn{breakpoint} makes your program stop whenever a certain point in +the program is reached. For each breakpoint, you can add conditions to +control in finer detail whether your program stops. You can set +breakpoints with the @code{break} command and its variants (@pxref{Set +Breaks, ,Setting Breakpoints}), to specify the place where your program +should stop by line number, function name or exact address in the +program. + +On some systems, you can set breakpoints in shared libraries before +the executable is run. + +@cindex watchpoints +@cindex data breakpoints +@cindex memory tracing +@cindex breakpoint on memory address +@cindex breakpoint on variable modification +A @dfn{watchpoint} is a special breakpoint that stops your program +when the value of an expression changes. The expression may be a value +of a variable, or it could involve values of one or more variables +combined by operators, such as @samp{a + b}. This is sometimes called +@dfn{data breakpoints}. You must use a different command to set +watchpoints (@pxref{Set Watchpoints, ,Setting Watchpoints}), but aside +from that, you can manage a watchpoint like any other breakpoint: you +enable, disable, and delete both breakpoints and watchpoints using the +same commands. + +You can arrange to have values from your program displayed automatically +whenever @value{GDBN} stops at a breakpoint. @xref{Auto Display,, +Automatic Display}. + +@cindex catchpoints +@cindex breakpoint on events +A @dfn{catchpoint} is another special breakpoint that stops your program +when a certain kind of event occurs, such as the throwing of a C@t{++} +exception or the loading of a library. As with watchpoints, you use a +different command to set a catchpoint (@pxref{Set Catchpoints, ,Setting +Catchpoints}), but aside from that, you can manage a catchpoint like any +other breakpoint. (To stop when your program receives a signal, use the +@code{handle} command; see @ref{Signals, ,Signals}.) + +@cindex breakpoint numbers +@cindex numbers for breakpoints +@value{GDBN} assigns a number to each breakpoint, watchpoint, or +catchpoint when you create it; these numbers are successive integers +starting with one. In many of the commands for controlling various +features of breakpoints you use the breakpoint number to say which +breakpoint you want to change. Each breakpoint may be @dfn{enabled} or +@dfn{disabled}; if disabled, it has no effect on your program until you +enable it again. + +@cindex breakpoint ranges +@cindex breakpoint lists +@cindex ranges of breakpoints +@cindex lists of breakpoints +Some @value{GDBN} commands accept a space-separated list of breakpoints +on which to operate. A list element can be either a single breakpoint number, +like @samp{5}, or a range of such numbers, like @samp{5-7}. +When a breakpoint list is given to a command, all breakpoints in that list +are operated on. + +@menu +* Set Breaks:: Setting breakpoints +* Set Watchpoints:: Setting watchpoints +* Set Catchpoints:: Setting catchpoints +* Delete Breaks:: Deleting breakpoints +* Disabling:: Disabling breakpoints +* Conditions:: Break conditions +* Break Commands:: Breakpoint command lists +* Dynamic Printf:: Dynamic printf +* Save Breakpoints:: How to save breakpoints in a file +* Static Probe Points:: Listing static probe points +* Error in Breakpoints:: ``Cannot insert breakpoints'' +* Breakpoint-related Warnings:: ``Breakpoint address adjusted...'' +@end menu + +@node Set Breaks +@subsection Setting Breakpoints + +@c FIXME LMB what does GDB do if no code on line of breakpt? +@c consider in particular declaration with/without initialization. +@c +@c FIXME 2 is there stuff on this already? break at fun start, already init? + +@kindex break +@kindex b @r{(@code{break})} +@vindex $bpnum@r{, convenience variable} +@cindex latest breakpoint +Breakpoints are set with the @code{break} command (abbreviated +@code{b}). The debugger convenience variable @samp{$bpnum} records the +number of the breakpoint you've set most recently: +@smallexample +(gdb) b main +Breakpoint 1 at 0x11c6: file zeoes.c, line 24. +(gdb) p $bpnum +$1 = 1 +@end smallexample + +A breakpoint may be mapped to multiple code locations for example with +inlined functions, Ada generics, C@t{++} templates or overloaded function names. +@value{GDBN} then indicates the number of code locations in the breakpoint +command output: +@smallexample +(gdb) b some_func +Breakpoint 2 at 0x1179: some_func. (3 locations) +(gdb) p $bpnum +$2 = 2 +(gdb) +@end smallexample + +@vindex $_hit_bpnum@r{, convenience variable} +@vindex $_hit_locno@r{, convenience variable} +When your program stops on a breakpoint, the convenience variables +@samp{$_hit_bpnum} and @samp{$_hit_locno} are respectively set to the number of +the encountered breakpoint and the number of the breakpoint's code location: +@smallexample +Thread 1 "zeoes" hit Breakpoint 2.1, some_func () at zeoes.c:8 +8 printf("some func\n"); +(gdb) p $_hit_bpnum +$5 = 2 +(gdb) p $_hit_locno +$6 = 1 +(gdb) +@end smallexample + +Note that @samp{$_hit_bpnum} and @samp{$bpnum} are not equivalent: +@samp{$_hit_bpnum} is set to the breakpoint number @b{last hit}, while +@samp{$bpnum} is set to the breakpoint number @b{last set}. + + +If the encountered breakpoint has only one code location, @samp{$_hit_locno} +is set to 1: +@smallexample +Breakpoint 1, main (argc=1, argv=0x7fffffffe018) at zeoes.c:24 +24 if (argc > 1) +(gdb) p $_hit_bpnum +$3 = 1 +(gdb) p $_hit_locno +$4 = 1 +(gdb) +@end smallexample + +The @samp{$_hit_bpnum} and @samp{$_hit_locno} variables can typically be used +in a breakpoint command list. +(@pxref{Break Commands, ,Breakpoint Command Lists}). For example, as +part of the breakpoint command list, you can disable completely the +encountered breakpoint using @kbd{disable $_hit_bpnum} or disable the +specific encountered breakpoint location using +@kbd{disable $_hit_bpnum.$_hit_locno}. +If a breakpoint has only one location, @samp{$_hit_locno} is set to 1 +and the commands @kbd{disable $_hit_bpnum} and +@kbd{disable $_hit_bpnum.$_hit_locno} both disable the breakpoint. + +You can also define aliases to easily disable the last hit location or +last hit breakpoint: +@smallexample +(gdb) alias lld = disable $_hit_bpnum.$_hit_locno +(gdb) alias lbd = disable $_hit_bpnum +@end smallexample + +@table @code +@item break @var{locspec} +Set a breakpoint at all the code locations in your program that result +from resolving the given @var{locspec}. @var{locspec} can specify a +function name, a line number, an address of an instruction, and more. +@xref{Location Specifications}, for the various forms of +@var{locspec}. The breakpoint will stop your program just before it +executes the instruction at the address of any of the breakpoint's +code locations. + +When using source languages that permit overloading of symbols, such +as C@t{++}, a function name may refer to more than one symbol, and +thus more than one place to break. @xref{Ambiguous +Expressions,,Ambiguous Expressions}, for a discussion of that +situation. + +It is also possible to insert a breakpoint that will stop the program +only if a specific thread (@pxref{Thread-Specific Breakpoints}), +specific inferior (@pxref{Inferior-Specific Breakpoints}), or a +specific task (@pxref{Ada Tasks}) hits that breakpoint. + +@item break +When called without any arguments, @code{break} sets a breakpoint at +the next instruction to be executed in the selected stack frame +(@pxref{Stack, ,Examining the Stack}). In any selected frame but the +innermost, this makes your program stop as soon as control +returns to that frame. This is similar to the effect of a +@code{finish} command in the frame inside the selected frame---except +that @code{finish} does not leave an active breakpoint. If you use +@code{break} without an argument in the innermost frame, @value{GDBN} stops +the next time it reaches the current location; this may be useful +inside loops. + +@value{GDBN} normally ignores breakpoints when it resumes execution, until at +least one instruction has been executed. If it did not do this, you +would be unable to proceed past a breakpoint without first disabling the +breakpoint. This rule applies whether or not the breakpoint already +existed when your program stopped. + +@item break @dots{} if @var{cond} +Set a breakpoint with condition @var{cond}; evaluate the expression +@var{cond} each time the breakpoint is reached, and stop only if the +value is nonzero---that is, if @var{cond} evaluates as true. +@samp{@dots{}} stands for one of the possible arguments described +above (or no argument) specifying where to break. @xref{Conditions, +,Break Conditions}, for more information on breakpoint conditions. + +The breakpoint may be mapped to multiple locations. If the breakpoint +condition @var{cond} is invalid at some but not all of the locations, +the locations for which the condition is invalid are disabled. For +example, @value{GDBN} reports below that two of the three locations +are disabled. + +@smallexample +(@value{GDBP}) break func if a == 10 +warning: failed to validate condition at location 0x11ce, disabling: + No symbol "a" in current context. +warning: failed to validate condition at location 0x11b6, disabling: + No symbol "a" in current context. +Breakpoint 1 at 0x11b6: func. (3 locations) +@end smallexample + +Locations that are disabled because of the condition are denoted by an +uppercase @code{N} in the output of the @code{info breakpoints} +command: + +@smallexample +(@value{GDBP}) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep y + stop only if a == 10 +1.1 N* 0x00000000000011b6 in ... +1.2 y 0x00000000000011c2 in ... +1.3 N* 0x00000000000011ce in ... +(*): Breakpoint condition is invalid at this location. +@end smallexample + +If the breakpoint condition @var{cond} is invalid in the context of +@emph{all} the locations of the breakpoint, @value{GDBN} refuses to +define the breakpoint. For example, if variable @code{foo} is an +undefined variable: + +@smallexample +(@value{GDBP}) break func if foo +No symbol "foo" in current context. +@end smallexample + +@item break @dots{} -force-condition if @var{cond} +There may be cases where the condition @var{cond} is invalid at all +the current locations, but the user knows that it will be valid at a +future location; for example, because of a library load. In such +cases, by using the @code{-force-condition} keyword before @samp{if}, +@value{GDBN} can be forced to define the breakpoint with the given +condition expression instead of refusing it. + +@smallexample +(@value{GDBP}) break func -force-condition if foo +warning: failed to validate condition at location 1, disabling: + No symbol "foo" in current context. +warning: failed to validate condition at location 2, disabling: + No symbol "foo" in current context. +warning: failed to validate condition at location 3, disabling: + No symbol "foo" in current context. +Breakpoint 1 at 0x1158: test.c:18. (3 locations) +@end smallexample + +This causes all the present locations where the breakpoint would +otherwise be inserted, to be disabled, as seen in the example above. +However, if there exist locations at which the condition is valid, the +@code{-force-condition} keyword has no effect. + +@kindex tbreak +@item tbreak @var{args} +Set a breakpoint enabled only for one stop. The @var{args} are the +same as for the @code{break} command, and the breakpoint is set in the same +way, but the breakpoint is automatically deleted after the first time your +program stops there. @xref{Disabling, ,Disabling Breakpoints}. + +@kindex hbreak +@cindex hardware breakpoints +@item hbreak @var{args} +Set a hardware-assisted breakpoint. The @var{args} are the same as for the +@code{break} command and the breakpoint is set in the same way, but the +breakpoint requires hardware support and some target hardware may not +have this support. The main purpose of this is EPROM/ROM code +debugging, so you can set a breakpoint at an instruction without +changing the instruction. This can be used with the new trap-generation +provided by SPARClite DSU and most x86-based targets. These targets +will generate traps when a program accesses some data or instruction +address that is assigned to the debug registers. However the hardware +breakpoint registers can take a limited number of breakpoints. For +example, on the DSU, only two data breakpoints can be set at a time, and +@value{GDBN} will reject this command if more than two are used. Delete +or disable unused hardware breakpoints before setting new ones +(@pxref{Disabling, ,Disabling Breakpoints}). +@xref{Conditions, ,Break Conditions}. +For remote targets, you can restrict the number of hardware +breakpoints @value{GDBN} will use, see @ref{set remote +hardware-breakpoint-limit}. + +@kindex thbreak +@item thbreak @var{args} +Set a hardware-assisted breakpoint enabled only for one stop. The @var{args} +are the same as for the @code{hbreak} command and the breakpoint is set in +the same way. However, like the @code{tbreak} command, +the breakpoint is automatically deleted after the +first time your program stops there. Also, like the @code{hbreak} +command, the breakpoint requires hardware support and some target hardware +may not have this support. @xref{Disabling, ,Disabling Breakpoints}. +See also @ref{Conditions, ,Break Conditions}. + +@kindex rbreak +@cindex regular expression +@cindex breakpoints at functions matching a regexp +@cindex set breakpoints in many functions +@item rbreak @var{regex} +Set breakpoints on all functions matching the regular expression +@var{regex}. This command sets an unconditional breakpoint on all +matches, printing a list of all breakpoints it set. Once these +breakpoints are set, they are treated just like the breakpoints set with +the @code{break} command. You can delete them, disable them, or make +them conditional the same way as any other breakpoint. + +In programs using different languages, @value{GDBN} chooses the syntax +to print the list of all breakpoints it sets according to the +@samp{set language} value: using @samp{set language auto} +(see @ref{Automatically, ,Set Language Automatically}) means to use the +language of the breakpoint's function, other values mean to use +the manually specified language (see @ref{Manually, ,Set Language Manually}). + +The syntax of the regular expression is the standard one used with tools +like @file{grep}. Note that this is different from the syntax used by +shells, so for instance @code{foo*} matches all functions that include +an @code{fo} followed by zero or more @code{o}s. There is an implicit +@code{.*} leading and trailing the regular expression you supply, so to +match only functions that begin with @code{foo}, use @code{^foo}. + +@cindex non-member C@t{++} functions, set breakpoint in +When debugging C@t{++} programs, @code{rbreak} is useful for setting +breakpoints on overloaded functions that are not members of any special +classes. + +@cindex set breakpoints on all functions +The @code{rbreak} command can be used to set breakpoints in +@strong{all} the functions in a program, like this: + +@smallexample +(@value{GDBP}) rbreak . +@end smallexample + +@item rbreak @var{file}:@var{regex} +If @code{rbreak} is called with a filename qualification, it limits +the search for functions matching the given regular expression to the +specified @var{file}. This can be used, for example, to set breakpoints on +every function in a given file: + +@smallexample +(@value{GDBP}) rbreak file.c:. +@end smallexample + +The colon separating the filename qualifier from the regex may +optionally be surrounded by spaces. + +@kindex info breakpoints +@cindex @code{$_} and @code{info breakpoints} +@item info breakpoints @r{[}@var{list}@dots{}@r{]} +@itemx info break @r{[}@var{list}@dots{}@r{]} +Print a table of all breakpoints, watchpoints, tracepoints, and catchpoints set +and not deleted. Optional argument @var{n} means print information only about +the specified breakpoint(s) (or watchpoint(s) or tracepoint(s) or catchpoint(s)). +For each breakpoint, following columns are printed: + +@table @emph +@item Breakpoint Numbers +@item Type +Breakpoint, watchpoint, tracepoint, or catchpoint. +@item Disposition +Whether the breakpoint is marked to be disabled or deleted when hit. +@item Enabled or Disabled +Enabled breakpoints are marked with @samp{y}. @samp{n} marks breakpoints +that are not enabled. +@item Address +Where the breakpoint is in your program, as a memory address. For a +pending breakpoint whose address is not yet known, this field will +contain @samp{}. Such breakpoint won't fire until a shared +library that has the symbol or line referred by breakpoint is loaded. +See below for details. A breakpoint with several locations will +have @samp{} in this field---see below for details. +@item What +Where the breakpoint is in the source for your program, as a file and +line number. For a pending breakpoint, the original string passed to +the breakpoint command will be listed as it cannot be resolved until +the appropriate shared library is loaded in the future. +@end table + +@noindent +If a breakpoint is conditional, there are two evaluation modes: ``host'' and +``target''. If mode is ``host'', breakpoint condition evaluation is done by +@value{GDBN} on the host's side. If it is ``target'', then the condition +is evaluated by the target. The @code{info break} command shows +the condition on the line following the affected breakpoint, together with +its condition evaluation mode in between parentheses. + +Breakpoint commands, if any, are listed after that. A pending breakpoint is +allowed to have a condition specified for it. The condition is not parsed for +validity until a shared library is loaded that allows the pending +breakpoint to resolve to a valid location. + +@noindent +@code{info break} with a breakpoint +number @var{n} as argument lists only that breakpoint. The +convenience variable @code{$_} and the default examining-address for +the @code{x} command are set to the address of the last breakpoint +listed (@pxref{Memory, ,Examining Memory}). + +@noindent +@code{info break} displays a count of the number of times the breakpoint +has been hit. This is especially useful in conjunction with the +@code{ignore} command. You can ignore a large number of breakpoint +hits, look at the breakpoint info to see how many times the breakpoint +was hit, and then run again, ignoring one less than that number. This +will get you quickly to the last hit of that breakpoint. + +@noindent +For a breakpoints with an enable count (xref) greater than 1, +@code{info break} also displays that count. + +@end table + +@value{GDBN} allows you to set any number of breakpoints at the same place in +your program. There is nothing silly or meaningless about this. When +the breakpoints are conditional, this is even useful +(@pxref{Conditions, ,Break Conditions}). + +@cindex multiple locations, breakpoints +@cindex breakpoints, multiple locations +It is possible that a single logical breakpoint is set at several code +locations in your program. @xref{Location Specifications}, for +examples. + +A breakpoint with multiple code locations is displayed in the +breakpoint table using several rows---one header row, followed by one +row for each code location. The header row has @samp{} in +the address column. Each code location row contains the actual +address, source file, source line and function of its code location. +The number column for a code location is of the form +@var{breakpoint-number}.@var{location-number}. + +For example: + +@smallexample +Num Type Disp Enb Address What +1 breakpoint keep y + stop only if i==1 + breakpoint already hit 1 time +1.1 y 0x080486a2 in void foo() at t.cc:8 +1.2 y 0x080486ca in void foo() at t.cc:8 +@end smallexample + +You cannot delete the individual locations from a breakpoint. However, +each location can be individually enabled or disabled by passing +@var{breakpoint-number}.@var{location-number} as argument to the +@code{enable} and @code{disable} commands. It's also possible to +@code{enable} and @code{disable} a range of @var{location-number} +locations using a @var{breakpoint-number} and two @var{location-number}s, +in increasing order, separated by a hyphen, like +@kbd{@var{breakpoint-number}.@var{location-number1}-@var{location-number2}}, +in which case @value{GDBN} acts on all the locations in the range (inclusive). +Disabling or enabling the parent breakpoint (@pxref{Disabling}) affects +all of the locations that belong to that breakpoint. + +Locations that are enabled while their parent breakpoint is disabled +won't trigger a break, and are denoted by @code{y-} in the @code{Enb} +column. For example: + +@smallexample +(@value{GDBP}) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep n +1.1 y- 0x00000000000011b6 in ... +1.2 y- 0x00000000000011c2 in ... +1.3 n 0x00000000000011ce in ... +@end smallexample + +@cindex pending breakpoints +It's quite common to have a breakpoint inside a shared library. +Shared libraries can be loaded and unloaded explicitly, +and possibly repeatedly, as the program is executed. To support +this use case, @value{GDBN} updates breakpoint locations whenever +any shared library is loaded or unloaded. Typically, you would +set a breakpoint in a shared library at the beginning of your +debugging session, when the library is not loaded, and when the +symbols from the library are not available. When you try to set +breakpoint, @value{GDBN} will ask you if you want to set +a so called @dfn{pending breakpoint}---breakpoint whose address +is not yet resolved. + +After the program is run, whenever a new shared library is loaded, +@value{GDBN} reevaluates all the breakpoints. When a newly loaded +shared library contains the symbol or line referred to by some +pending breakpoint, that breakpoint is resolved and becomes an +ordinary breakpoint. When a library is unloaded, all breakpoints +that refer to its symbols or source lines become pending again. + +This logic works for breakpoints with multiple locations, too. For +example, if you have a breakpoint in a C@t{++} template function, and +a newly loaded shared library has an instantiation of that template, +a new location is added to the list of locations for the breakpoint. + +Except for having unresolved address, pending breakpoints do not +differ from regular breakpoints. You can set conditions or commands, +enable and disable them and perform other breakpoint operations. + +@value{GDBN} provides some additional commands for controlling what +happens when the @samp{break} command cannot resolve the location spec +to any code location in your program (@pxref{Location +Specifications}): + +@kindex set breakpoint pending +@kindex show breakpoint pending +@table @code +@item set breakpoint pending auto +This is the default behavior. When @value{GDBN} cannot resolve the +location spec, it queries you whether a pending breakpoint should be +created. + +@item set breakpoint pending on +This indicates that when @value{GDBN} cannot resolve the location +spec, it should create a pending breakpoint without confirmation. + +@item set breakpoint pending off +This indicates that pending breakpoints are not to be created. If +@value{GDBN} cannot resolve the location spec, it aborts the +breakpoint creation with an error. This setting does not affect any +pending breakpoints previously created. + +@item show breakpoint pending +Show the current behavior setting for creating pending breakpoints. +@end table + +The settings above only affect the @code{break} command and its +variants. Once a breakpoint is set, it will be automatically updated +as shared libraries are loaded and unloaded. + +@cindex automatic hardware breakpoints +For some targets, @value{GDBN} can automatically decide if hardware or +software breakpoints should be used, depending on whether the +breakpoint address is read-only or read-write. This applies to +breakpoints set with the @code{break} command as well as to internal +breakpoints set by commands like @code{next} and @code{finish}. For +breakpoints set with @code{hbreak}, @value{GDBN} will always use hardware +breakpoints. + +You can control this automatic behavior with the following commands: + +@kindex set breakpoint auto-hw +@kindex show breakpoint auto-hw +@table @code +@item set breakpoint auto-hw on +This is the default behavior. When @value{GDBN} sets a breakpoint, it +will try to use the target memory map to decide if software or hardware +breakpoint must be used. + +@item set breakpoint auto-hw off +This indicates @value{GDBN} should not automatically select breakpoint +type. If the target provides a memory map, @value{GDBN} will warn when +trying to set software breakpoint at a read-only address. +@end table + +@value{GDBN} normally implements breakpoints by replacing the program code +at the breakpoint address with a special instruction, which, when +executed, given control to the debugger. By default, the program +code is so modified only when the program is resumed. As soon as +the program stops, @value{GDBN} restores the original instructions. This +behavior guards against leaving breakpoints inserted in the +target should gdb abrubptly disconnect. However, with slow remote +targets, inserting and removing breakpoint can reduce the performance. +This behavior can be controlled with the following commands:: + +@kindex set breakpoint always-inserted +@kindex show breakpoint always-inserted +@table @code +@item set breakpoint always-inserted off +All breakpoints, including newly added by the user, are inserted in +the target only when the target is resumed. All breakpoints are +removed from the target when it stops. This is the default mode. + +@item set breakpoint always-inserted on +Causes all breakpoints to be inserted in the target at all times. If +the user adds a new breakpoint, or changes an existing breakpoint, the +breakpoints in the target are updated immediately. A breakpoint is +removed from the target only when breakpoint itself is deleted. +@end table + +@value{GDBN} handles conditional breakpoints by evaluating these conditions +when a breakpoint breaks. If the condition is true, then the process being +debugged stops, otherwise the process is resumed. + +If the target supports evaluating conditions on its end, @value{GDBN} may +download the breakpoint, together with its conditions, to it. + +This feature can be controlled via the following commands: + +@kindex set breakpoint condition-evaluation +@kindex show breakpoint condition-evaluation +@table @code +@item set breakpoint condition-evaluation host +This option commands @value{GDBN} to evaluate the breakpoint +conditions on the host's side. Unconditional breakpoints are sent to +the target which in turn receives the triggers and reports them back to GDB +for condition evaluation. This is the standard evaluation mode. + +@item set breakpoint condition-evaluation target +This option commands @value{GDBN} to download breakpoint conditions +to the target at the moment of their insertion. The target +is responsible for evaluating the conditional expression and reporting +breakpoint stop events back to @value{GDBN} whenever the condition +is true. Due to limitations of target-side evaluation, some conditions +cannot be evaluated there, e.g., conditions that depend on local data +that is only known to the host. Examples include +conditional expressions involving convenience variables, complex types +that cannot be handled by the agent expression parser and expressions +that are too long to be sent over to the target, specially when the +target is a remote system. In these cases, the conditions will be +evaluated by @value{GDBN}. + +@item set breakpoint condition-evaluation auto +This is the default mode. If the target supports evaluating breakpoint +conditions on its end, @value{GDBN} will download breakpoint conditions to +the target (limitations mentioned previously apply). If the target does +not support breakpoint condition evaluation, then @value{GDBN} will fallback +to evaluating all these conditions on the host's side. +@end table + + +@cindex negative breakpoint numbers +@cindex internal @value{GDBN} breakpoints +@value{GDBN} itself sometimes sets breakpoints in your program for +special purposes, such as proper handling of @code{longjmp} (in C +programs). These internal breakpoints are assigned negative numbers, +starting with @code{-1}; @samp{info breakpoints} does not display them. +You can see these breakpoints with the @value{GDBN} maintenance command +@samp{maint info breakpoints} (@pxref{maint info breakpoints}). + + +@node Set Watchpoints +@subsection Setting Watchpoints + +@cindex setting watchpoints +You can use a watchpoint to stop execution whenever the value of an +expression changes, without having to predict a particular place where +this may happen. (This is sometimes called a @dfn{data breakpoint}.) +The expression may be as simple as the value of a single variable, or +as complex as many variables combined by operators. Examples include: + +@itemize @bullet +@item +A reference to the value of a single variable. + +@item +An address cast to an appropriate data type. For example, +@samp{*(int *)0x12345678} will watch a 4-byte region at the specified +address (assuming an @code{int} occupies 4 bytes). + +@item +An arbitrarily complex expression, such as @samp{a*b + c/d}. The +expression can use any operators valid in the program's native +language (@pxref{Languages}). +@end itemize + +You can set a watchpoint on an expression even if the expression can +not be evaluated yet. For instance, you can set a watchpoint on +@samp{*global_ptr} before @samp{global_ptr} is initialized. +@value{GDBN} will stop when your program sets @samp{global_ptr} and +the expression produces a valid value. If the expression becomes +valid in some other way than changing a variable (e.g.@: if the memory +pointed to by @samp{*global_ptr} becomes readable as the result of a +@code{malloc} call), @value{GDBN} may not stop until the next time +the expression changes. + +@cindex software watchpoints +@cindex hardware watchpoints +Depending on your system, watchpoints may be implemented in software or +hardware. @value{GDBN} does software watchpointing by single-stepping your +program and testing the variable's value each time, which is hundreds of +times slower than normal execution. (But this may still be worth it, to +catch errors where you have no clue what part of your program is the +culprit.) + +On some systems, such as most PowerPC or x86-based targets, +@value{GDBN} includes support for hardware watchpoints, which do not +slow down the running of your program. + +@table @code +@kindex watch +@item watch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} @r{[}task @var{task-id}@r{]} +Set a watchpoint for an expression. @value{GDBN} will break when the +expression @var{expr} is written into by the program and its value +changes. The simplest (and the most popular) use of this command is +to watch the value of a single variable: + +@smallexample +(@value{GDBP}) watch foo +@end smallexample + +If the command includes a @code{@r{[}thread @var{thread-id}@r{]}} +argument, @value{GDBN} breaks only when the thread identified by +@var{thread-id} changes the value of @var{expr}. If any other threads +change the value of @var{expr}, @value{GDBN} will not break. Note +that watchpoints restricted to a single thread in this way only work +with Hardware Watchpoints. + +Similarly, if the @code{task} argument is given, then the watchpoint +will be specific to the indicated Ada task (@pxref{Ada Tasks}). + +Ordinarily a watchpoint respects the scope of variables in @var{expr} +(see below). The @code{-location} argument tells @value{GDBN} to +instead watch the memory referred to by @var{expr}. In this case, +@value{GDBN} will evaluate @var{expr}, take the address of the result, +and watch the memory at that address. The type of the result is used +to determine the size of the watched memory. If the expression's +result does not have an address, then @value{GDBN} will print an +error. + +The @code{@r{[}mask @var{maskvalue}@r{]}} argument allows creation +of masked watchpoints, if the current architecture supports this +feature (e.g., PowerPC Embedded architecture, see @ref{PowerPC +Embedded}.) A @dfn{masked watchpoint} specifies a mask in addition +to an address to watch. The mask specifies that some bits of an address +(the bits which are reset in the mask) should be ignored when matching +the address accessed by the inferior against the watchpoint address. +Thus, a masked watchpoint watches many addresses simultaneously---those +addresses whose unmasked bits are identical to the unmasked bits in the +watchpoint address. The @code{mask} argument implies @code{-location}. +Examples: + +@smallexample +(@value{GDBP}) watch foo mask 0xffff00ff +(@value{GDBP}) watch *0xdeadbeef mask 0xffffff00 +@end smallexample + +@kindex rwatch +@item rwatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} +Set a watchpoint that will break when the value of @var{expr} is read +by the program. + +@kindex awatch +@item awatch @r{[}-l@r{|}-location@r{]} @var{expr} @r{[}thread @var{thread-id}@r{]} @r{[}mask @var{maskvalue}@r{]} +Set a watchpoint that will break when @var{expr} is either read from +or written into by the program. + +@kindex info watchpoints @r{[}@var{list}@dots{}@r{]} +@item info watchpoints @r{[}@var{list}@dots{}@r{]} +This command prints a list of watchpoints, using the same format as +@code{info break} (@pxref{Set Breaks}). +@end table + +If you watch for a change in a numerically entered address you need to +dereference it, as the address itself is just a constant number which will +never change. @value{GDBN} refuses to create a watchpoint that watches +a never-changing value: + +@smallexample +(@value{GDBP}) watch 0x600850 +Cannot watch constant value 0x600850. +(@value{GDBP}) watch *(int *) 0x600850 +Watchpoint 1: *(int *) 6293584 +@end smallexample + +@value{GDBN} sets a @dfn{hardware watchpoint} if possible. Hardware +watchpoints execute very quickly, and the debugger reports a change in +value at the exact instruction where the change occurs. If @value{GDBN} +cannot set a hardware watchpoint, it sets a software watchpoint, which +executes more slowly and reports the change in value at the next +@emph{statement}, not the instruction, after the change occurs. + +@cindex use only software watchpoints +You can force @value{GDBN} to use only software watchpoints with the +@kbd{set can-use-hw-watchpoints 0} command. With this variable set to +zero, @value{GDBN} will never try to use hardware watchpoints, even if +the underlying system supports them. (Note that hardware-assisted +watchpoints that were set @emph{before} setting +@code{can-use-hw-watchpoints} to zero will still use the hardware +mechanism of watching expression values.) + +@table @code +@item set can-use-hw-watchpoints +@kindex set can-use-hw-watchpoints +Set whether or not to use hardware watchpoints. + +@item show can-use-hw-watchpoints +@kindex show can-use-hw-watchpoints +Show the current mode of using hardware watchpoints. +@end table + +For remote targets, you can restrict the number of hardware +watchpoints @value{GDBN} will use, see @ref{set remote +hardware-breakpoint-limit}. + +When you issue the @code{watch} command, @value{GDBN} reports + +@smallexample +Hardware watchpoint @var{num}: @var{expr} +@end smallexample + +@noindent +if it was able to set a hardware watchpoint. + +Currently, the @code{awatch} and @code{rwatch} commands can only set +hardware watchpoints, because accesses to data that don't change the +value of the watched expression cannot be detected without examining +every instruction as it is being executed, and @value{GDBN} does not do +that currently. If @value{GDBN} finds that it is unable to set a +hardware breakpoint with the @code{awatch} or @code{rwatch} command, it +will print a message like this: + +@smallexample +Expression cannot be implemented with read/access watchpoint. +@end smallexample + +Sometimes, @value{GDBN} cannot set a hardware watchpoint because the +data type of the watched expression is wider than what a hardware +watchpoint on the target machine can handle. For example, some systems +can only watch regions that are up to 4 bytes wide; on such systems you +cannot set hardware watchpoints for an expression that yields a +double-precision floating-point number (which is typically 8 bytes +wide). As a work-around, it might be possible to break the large region +into a series of smaller ones and watch them with separate watchpoints. + +If you set too many hardware watchpoints, @value{GDBN} might be unable +to insert all of them when you resume the execution of your program. +Since the precise number of active watchpoints is unknown until such +time as the program is about to be resumed, @value{GDBN} might not be +able to warn you about this when you set the watchpoints, and the +warning will be printed only when the program is resumed: + +@smallexample +Hardware watchpoint @var{num}: Could not insert watchpoint +@end smallexample + +@noindent +If this happens, delete or disable some of the watchpoints. + +Watching complex expressions that reference many variables can also +exhaust the resources available for hardware-assisted watchpoints. +That's because @value{GDBN} needs to watch every variable in the +expression with separately allocated resources. + +If you call a function interactively using @code{print} or @code{call}, +any watchpoints you have set will be inactive until @value{GDBN} reaches another +kind of breakpoint or the call completes. + +@value{GDBN} automatically deletes watchpoints that watch local +(automatic) variables, or expressions that involve such variables, when +they go out of scope, that is, when the execution leaves the block in +which these variables were defined. In particular, when the program +being debugged terminates, @emph{all} local variables go out of scope, +and so only watchpoints that watch global variables remain set. If you +rerun the program, you will need to set all such watchpoints again. One +way of doing that would be to set a code breakpoint at the entry to the +@code{main} function and when it breaks, set all the watchpoints. + +@cindex watchpoints and threads +@cindex threads and watchpoints +In multi-threaded programs, watchpoints will detect changes to the +watched expression from every thread. + +@quotation +@emph{Warning:} In multi-threaded programs, software watchpoints +have only limited usefulness. If @value{GDBN} creates a software +watchpoint, it can only watch the value of an expression @emph{in a +single thread}. If you are confident that the expression can only +change due to the current thread's activity (and if you are also +confident that no other thread can become current), then you can use +software watchpoints as usual. However, @value{GDBN} may not notice +when a non-current thread's activity changes the expression. (Hardware +watchpoints, in contrast, watch an expression in all threads.) +@end quotation + +@xref{set remote hardware-watchpoint-limit}. + +@node Set Catchpoints +@subsection Setting Catchpoints +@cindex catchpoints, setting +@cindex exception handlers +@cindex event handling + +You can use @dfn{catchpoints} to cause the debugger to stop for certain +kinds of program events, such as C@t{++} exceptions or the loading of a +shared library. Use the @code{catch} command to set a catchpoint. + +@table @code +@kindex catch +@item catch @var{event} +Stop when @var{event} occurs. The @var{event} can be any of the following: + +@table @code +@item throw @r{[}@var{regexp}@r{]} +@itemx rethrow @r{[}@var{regexp}@r{]} +@itemx catch @r{[}@var{regexp}@r{]} +@kindex catch throw +@kindex catch rethrow +@kindex catch catch +@cindex stop on C@t{++} exceptions +The throwing, re-throwing, or catching of a C@t{++} exception. + +If @var{regexp} is given, then only exceptions whose type matches the +regular expression will be caught. + +@vindex $_exception@r{, convenience variable} +The convenience variable @code{$_exception} is available at an +exception-related catchpoint, on some systems. This holds the +exception being thrown. + +There are currently some limitations to C@t{++} exception handling in +@value{GDBN}: + +@itemize @bullet +@item +The support for these commands is system-dependent. Currently, only +systems using the @samp{gnu-v3} C@t{++} ABI (@pxref{ABI}) are +supported. + +@item +The regular expression feature and the @code{$_exception} convenience +variable rely on the presence of some SDT probes in @code{libstdc++}. +If these probes are not present, then these features cannot be used. +These probes were first available in the GCC 4.8 release, but whether +or not they are available in your GCC also depends on how it was +built. + +@item +The @code{$_exception} convenience variable is only valid at the +instruction at which an exception-related catchpoint is set. + +@item +When an exception-related catchpoint is hit, @value{GDBN} stops at a +location in the system library which implements runtime exception +support for C@t{++}, usually @code{libstdc++}. You can use @code{up} +(@pxref{Selection}) to get to your code. + +@item +If you call a function interactively, @value{GDBN} normally returns +control to you when the function has finished executing. If the call +raises an exception, however, the call may bypass the mechanism that +returns control to you and cause your program either to abort or to +simply continue running until it hits a breakpoint, catches a signal +that @value{GDBN} is listening for, or exits. This is the case even if +you set a catchpoint for the exception; catchpoints on exceptions are +disabled within interactive calls. @xref{Calling}, for information on +controlling this with @code{set unwind-on-terminating-exception}. + +@item +You cannot raise an exception interactively. + +@item +You cannot install an exception handler interactively. +@end itemize + +@item exception @r{[}@var{name}@r{]} +@kindex catch exception +@cindex Ada exception catching +@cindex catch Ada exceptions +An Ada exception being raised. If an exception name is specified +at the end of the command (eg @code{catch exception Program_Error}), +the debugger will stop only when this specific exception is raised. +Otherwise, the debugger stops execution when any Ada exception is raised. + +When inserting an exception catchpoint on a user-defined exception whose +name is identical to one of the exceptions defined by the language, the +fully qualified name must be used as the exception name. Otherwise, +@value{GDBN} will assume that it should stop on the pre-defined exception +rather than the user-defined one. For instance, assuming an exception +called @code{Constraint_Error} is defined in package @code{Pck}, then +the command to use to catch such exceptions is @kbd{catch exception +Pck.Constraint_Error}. + +@vindex $_ada_exception@r{, convenience variable} +The convenience variable @code{$_ada_exception} holds the address of +the exception being thrown. This can be useful when setting a +condition for such a catchpoint. + +@item exception unhandled +@kindex catch exception unhandled +An exception that was raised but is not handled by the program. The +convenience variable @code{$_ada_exception} is set as for @code{catch +exception}. + +@item handlers @r{[}@var{name}@r{]} +@kindex catch handlers +@cindex Ada exception handlers catching +@cindex catch Ada exceptions when handled +An Ada exception being handled. If an exception name is +specified at the end of the command + (eg @kbd{catch handlers Program_Error}), the debugger will stop +only when this specific exception is handled. +Otherwise, the debugger stops execution when any Ada exception is handled. + +When inserting a handlers catchpoint on a user-defined +exception whose name is identical to one of the exceptions +defined by the language, the fully qualified name must be used +as the exception name. Otherwise, @value{GDBN} will assume that it +should stop on the pre-defined exception rather than the +user-defined one. For instance, assuming an exception called + @code{Constraint_Error} is defined in package @code{Pck}, then the +command to use to catch such exceptions handling is +@kbd{catch handlers Pck.Constraint_Error}. + +The convenience variable @code{$_ada_exception} is set as for +@code{catch exception}. + +@item assert +@kindex catch assert +A failed Ada assertion. Note that the convenience variable +@code{$_ada_exception} is @emph{not} set by this catchpoint. + +@item exec +@kindex catch exec +@cindex break on fork/exec +A call to @code{exec}. + +@anchor{catch syscall} +@item syscall +@itemx syscall @r{[}@var{name} @r{|} @var{number} @r{|} @r{group:}@var{groupname} @r{|} @r{g:}@var{groupname}@r{]} @dots{} +@kindex catch syscall +@cindex break on a system call. +A call to or return from a system call, a.k.a.@: @dfn{syscall}. A +syscall is a mechanism for application programs to request a service +from the operating system (OS) or one of the OS system services. +@value{GDBN} can catch some or all of the syscalls issued by the +debuggee, and show the related information for each syscall. If no +argument is specified, calls to and returns from all system calls +will be caught. + +@var{name} can be any system call name that is valid for the +underlying OS. Just what syscalls are valid depends on the OS. On +GNU and Unix systems, you can find the full list of valid syscall +names on @file{/usr/include/asm/unistd.h}. + +@c For MS-Windows, the syscall names and the corresponding numbers +@c can be found, e.g., on this URL: +@c http://www.metasploit.com/users/opcode/syscalls.html +@c but we don't support Windows syscalls yet. + +Normally, @value{GDBN} knows in advance which syscalls are valid for +each OS, so you can use the @value{GDBN} command-line completion +facilities (@pxref{Completion,, command completion}) to list the +available choices. + +You may also specify the system call numerically. A syscall's +number is the value passed to the OS's syscall dispatcher to +identify the requested service. When you specify the syscall by its +name, @value{GDBN} uses its database of syscalls to convert the name +into the corresponding numeric code, but using the number directly +may be useful if @value{GDBN}'s database does not have the complete +list of syscalls on your system (e.g., because @value{GDBN} lags +behind the OS upgrades). + +You may specify a group of related syscalls to be caught at once using +the @code{group:} syntax (@code{g:} is a shorter equivalent). For +instance, on some platforms @value{GDBN} allows you to catch all +network related syscalls, by passing the argument @code{group:network} +to @code{catch syscall}. Note that not all syscall groups are +available in every system. You can use the command completion +facilities (@pxref{Completion,, command completion}) to list the +syscall groups available on your environment. + +The example below illustrates how this command works if you don't provide +arguments to it: + +@smallexample +(@value{GDBP}) catch syscall +Catchpoint 1 (syscall) +(@value{GDBP}) r +Starting program: /tmp/catch-syscall + +Catchpoint 1 (call to syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () +(@value{GDBP}) c +Continuing. + +Catchpoint 1 (returned from syscall 'close'), \ + 0xffffe424 in __kernel_vsyscall () +(@value{GDBP}) +@end smallexample + +Here is an example of catching a system call by name: + +@smallexample +(@value{GDBP}) catch syscall chroot +Catchpoint 1 (syscall 'chroot' [61]) +(@value{GDBP}) r +Starting program: /tmp/catch-syscall + +Catchpoint 1 (call to syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () +(@value{GDBP}) c +Continuing. + +Catchpoint 1 (returned from syscall 'chroot'), \ + 0xffffe424 in __kernel_vsyscall () +(@value{GDBP}) +@end smallexample + +An example of specifying a system call numerically. In the case +below, the syscall number has a corresponding entry in the XML +file, so @value{GDBN} finds its name and prints it: + +@smallexample +(@value{GDBP}) catch syscall 252 +Catchpoint 1 (syscall(s) 'exit_group') +(@value{GDBP}) r +Starting program: /tmp/catch-syscall + +Catchpoint 1 (call to syscall 'exit_group'), \ + 0xffffe424 in __kernel_vsyscall () +(@value{GDBP}) c +Continuing. + +Program exited normally. +(@value{GDBP}) +@end smallexample + +Here is an example of catching a syscall group: + +@smallexample +(@value{GDBP}) catch syscall group:process +Catchpoint 1 (syscalls 'exit' [1] 'fork' [2] 'waitpid' [7] +'execve' [11] 'wait4' [114] 'clone' [120] 'vfork' [190] +'exit_group' [252] 'waitid' [284] 'unshare' [310]) +(@value{GDBP}) r +Starting program: /tmp/catch-syscall + +Catchpoint 1 (call to syscall fork), 0x00007ffff7df4e27 in open64 () + from /lib64/ld-linux-x86-64.so.2 + +(@value{GDBP}) c +Continuing. +@end smallexample + +However, there can be situations when there is no corresponding name +in XML file for that syscall number. In this case, @value{GDBN} prints +a warning message saying that it was not able to find the syscall name, +but the catchpoint will be set anyway. See the example below: + +@smallexample +(@value{GDBP}) catch syscall 764 +warning: The number '764' does not represent a known syscall. +Catchpoint 2 (syscall 764) +(@value{GDBP}) +@end smallexample + +If you configure @value{GDBN} using the @samp{--without-expat} option, +it will not be able to display syscall names. Also, if your +architecture does not have an XML file describing its system calls, +you will not be able to see the syscall names. It is important to +notice that these two features are used for accessing the syscall +name database. In either case, you will see a warning like this: + +@smallexample +(@value{GDBP}) catch syscall +warning: Could not open "syscalls/i386-linux.xml" +warning: Could not load the syscall XML file 'syscalls/i386-linux.xml'. +GDB will not be able to display syscall names. +Catchpoint 1 (syscall) +(@value{GDBP}) +@end smallexample + +Of course, the file name will change depending on your architecture and system. + +Still using the example above, you can also try to catch a syscall by its +number. In this case, you would see something like: + +@smallexample +(@value{GDBP}) catch syscall 252 +Catchpoint 1 (syscall(s) 252) +@end smallexample + +Again, in this case @value{GDBN} would not be able to display syscall's names. + +@item fork +@kindex catch fork +A call to @code{fork}. + +@item vfork +@kindex catch vfork +A call to @code{vfork}. + +@item load @r{[}@var{regexp}@r{]} +@itemx unload @r{[}@var{regexp}@r{]} +@kindex catch load +@kindex catch unload +The loading or unloading of a shared library. If @var{regexp} is +given, then the catchpoint will stop only if the regular expression +matches one of the affected libraries. + +@item signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} +@kindex catch signal +The delivery of a signal. + +With no arguments, this catchpoint will catch any signal that is not +used internally by @value{GDBN}, specifically, all signals except +@samp{SIGTRAP} and @samp{SIGINT}. + +With the argument @samp{all}, all signals, including those used by +@value{GDBN}, will be caught. This argument cannot be used with other +signal names. + +Otherwise, the arguments are a list of signal names as given to +@code{handle} (@pxref{Signals}). Only signals specified in this list +will be caught. + +One reason that @code{catch signal} can be more useful than +@code{handle} is that you can attach commands and conditions to the +catchpoint. + +When a signal is caught by a catchpoint, the signal's @code{stop} and +@code{print} settings, as specified by @code{handle}, are ignored. +However, whether the signal is still delivered to the inferior depends +on the @code{pass} setting; this can be changed in the catchpoint's +commands. + +@end table + +@item tcatch @var{event} +@kindex tcatch +Set a catchpoint that is enabled only for one stop. The catchpoint is +automatically deleted after the first time the event is caught. + +@end table + +Use the @code{info break} command to list the current catchpoints. + + +@node Delete Breaks +@subsection Deleting Breakpoints + +@cindex clearing breakpoints, watchpoints, catchpoints +@cindex deleting breakpoints, watchpoints, catchpoints +It is often necessary to eliminate a breakpoint, watchpoint, or +catchpoint once it has done its job and you no longer want your program +to stop there. This is called @dfn{deleting} the breakpoint. A +breakpoint that has been deleted no longer exists; it is forgotten. + +With the @code{clear} command you can delete breakpoints according to +where they are in your program. With the @code{delete} command you can +delete individual breakpoints, watchpoints, or catchpoints by specifying +their breakpoint numbers. + +It is not necessary to delete a breakpoint to proceed past it. @value{GDBN} +automatically ignores breakpoints on the first instruction to be executed +when you continue execution without changing the execution address. + +@table @code +@kindex clear +@item clear +Delete any breakpoints at the next instruction to be executed in the +selected stack frame (@pxref{Selection, ,Selecting a Frame}). When +the innermost frame is selected, this is a good way to delete a +breakpoint where your program just stopped. + +@item clear @var{locspec} +Delete any breakpoint with a code location that corresponds to +@var{locspec}. @xref{Location Specifications}, for the various forms +of @var{locspec}. Which code locations correspond to @var{locspec} +depends on the form used in the location specification @var{locspec}: + +@table @code +@item @var{linenum} +@itemx @var{filename}:@var{linenum} +@itemx -line @var{linenum} +@itemx -source @var{filename} -line @var{linenum} +If @var{locspec} specifies a line number, with or without a file name, +the command deletes any breakpoint with a code location that is at or +within the specified line @var{linenum} in files that match the +specified @var{filename}. If @var{filename} is omitted, it defaults +to the current source file. + +@item *@var{address} +If @var{locspec} specifies an address, the command deletes any +breakpoint with a code location that is at the given @var{address}. + +@item @var{function} +@itemx -function @var{function} +If @var{locspec} specifies a function, the command deletes any +breakpoint with a code location that is at the entry to any function +whose name matches @var{function}. +@end table + +Ambiguity in names of files and functions can be resolved as described +in @ref{Location Specifications}. + +@cindex delete breakpoints +@kindex delete +@kindex d @r{(@code{delete})} +@item delete @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} +Delete the breakpoints, watchpoints, tracepoints, or catchpoints of the +breakpoint list specified as argument. If no argument is specified, delete +all breakpoints, watchpoints, tracepoints, and catchpoints (@value{GDBN} asks +confirmation, unless you have @code{set confirm off}). You can abbreviate this +command as @code{d}. +@end table + +@node Disabling +@subsection Disabling Breakpoints + +@cindex enable/disable a breakpoint +Rather than deleting a breakpoint, watchpoint, or catchpoint, you might +prefer to @dfn{disable} it. This makes the breakpoint inoperative as if +it had been deleted, but remembers the information on the breakpoint so +that you can @dfn{enable} it again later. + +You disable and enable breakpoints, watchpoints, tracepoints, and catchpoints +with the @code{enable} and @code{disable} commands, optionally specifying +one or more breakpoint numbers as arguments. Use @code{info break} to print +a list of all breakpoints, watchpoints, tracepoints, and catchpoints if you +do not know which numbers to use. + +Disabling and enabling a breakpoint that has multiple locations +affects all of its locations. + +A breakpoint, watchpoint, or catchpoint can have any of several +different states of enablement: + +@itemize @bullet +@item +Enabled. The breakpoint stops your program. A breakpoint set +with the @code{break} command starts out in this state. +@item +Disabled. The breakpoint has no effect on your program. +@item +Enabled once. The breakpoint stops your program, but then becomes +disabled. +@item +Enabled for a count. The breakpoint stops your program for the next +N times, then becomes disabled. +@item +Enabled for deletion. The breakpoint stops your program, but +immediately after it does so it is deleted permanently. A breakpoint +set with the @code{tbreak} command starts out in this state. +@end itemize + +You can use the following commands to enable or disable breakpoints, +watchpoints, tracepoints, and catchpoints: + +@table @code +@kindex disable +@kindex dis @r{(@code{disable})} +@item disable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} +Disable the specified breakpoints---or all breakpoints, if none are +listed. A disabled breakpoint has no effect but is not forgotten. All +options such as ignore-counts, conditions and commands are remembered in +case the breakpoint is enabled again later. You may abbreviate +@code{disable} as @code{dis}. + +@kindex enable +@item enable @r{[}breakpoints@r{]} @r{[}@var{list}@dots{}@r{]} +Enable the specified breakpoints (or all defined breakpoints). They +become effective once again in stopping your program. + +@item enable @r{[}breakpoints@r{]} once @var{list}@dots{} +Enable the specified breakpoints temporarily. @value{GDBN} disables any +of these breakpoints immediately after stopping your program. + +@item enable @r{[}breakpoints@r{]} count @var{count} @var{list}@dots{} +Enable the specified breakpoints temporarily. @value{GDBN} records +@var{count} with each of the specified breakpoints, and decrements a +breakpoint's count when it is hit. When any count reaches 0, +@value{GDBN} disables that breakpoint. If a breakpoint has an ignore +count (@pxref{Conditions, ,Break Conditions}), that will be +decremented to 0 before @var{count} is affected. + +@item enable @r{[}breakpoints@r{]} delete @var{list}@dots{} +Enable the specified breakpoints to work once, then die. @value{GDBN} +deletes any of these breakpoints as soon as your program stops there. +Breakpoints set by the @code{tbreak} command start out in this state. +@end table + +@c FIXME: I think the following ``Except for [...] @code{tbreak}'' is +@c confusing: tbreak is also initially enabled. +Except for a breakpoint set with @code{tbreak} (@pxref{Set Breaks, +,Setting Breakpoints}), breakpoints that you set are initially enabled; +subsequently, they become disabled or enabled only when you use one of +the commands above. (The command @code{until} can set and delete a +breakpoint of its own, but it does not change the state of your other +breakpoints; see @ref{Continuing and Stepping, ,Continuing and +Stepping}.) + +@node Conditions +@subsection Break Conditions +@cindex conditional breakpoints +@cindex breakpoint conditions + +@c FIXME what is scope of break condition expr? Context where wanted? +@c in particular for a watchpoint? +The simplest sort of breakpoint breaks every time your program reaches a +specified place. You can also specify a @dfn{condition} for a +breakpoint. A condition is just a Boolean expression in your +programming language (@pxref{Expressions, ,Expressions}). A breakpoint with +a condition evaluates the expression each time your program reaches it, +and your program stops only if the condition is @emph{true}. + +This is the converse of using assertions for program validation; in that +situation, you want to stop when the assertion is violated---that is, +when the condition is false. In C, if you want to test an assertion expressed +by the condition @var{assert}, you should set the condition +@samp{! @var{assert}} on the appropriate breakpoint. + +Conditions are also accepted for watchpoints; you may not need them, +since a watchpoint is inspecting the value of an expression anyhow---but +it might be simpler, say, to just set a watchpoint on a variable name, +and specify a condition that tests whether the new value is an interesting +one. + +Break conditions can have side effects, and may even call functions in +your program. This can be useful, for example, to activate functions +that log program progress, or to use your own print functions to +format special data structures. The effects are completely predictable +unless there is another enabled breakpoint at the same address. (In +that case, @value{GDBN} might see the other breakpoint first and stop your +program without checking the condition of this one.) Note that +breakpoint commands are usually more convenient and flexible than break +conditions for the +purpose of performing side effects when a breakpoint is reached +(@pxref{Break Commands, ,Breakpoint Command Lists}). + +Breakpoint conditions can also be evaluated on the target's side if +the target supports it. Instead of evaluating the conditions locally, +@value{GDBN} encodes the expression into an agent expression +(@pxref{Agent Expressions}) suitable for execution on the target, +independently of @value{GDBN}. Global variables become raw memory +locations, locals become stack accesses, and so forth. + +In this case, @value{GDBN} will only be notified of a breakpoint trigger +when its condition evaluates to true. This mechanism may provide faster +response times depending on the performance characteristics of the target +since it does not need to keep @value{GDBN} informed about +every breakpoint trigger, even those with false conditions. + +Break conditions can be specified when a breakpoint is set, by using +@samp{if} in the arguments to the @code{break} command. @xref{Set +Breaks, ,Setting Breakpoints}. They can also be changed at any time +with the @code{condition} command. + +You can also use the @code{if} keyword with the @code{watch} command. +The @code{catch} command does not recognize the @code{if} keyword; +@code{condition} is the only way to impose a further condition on a +catchpoint. + +@table @code +@kindex condition +@item condition @var{bnum} @var{expression} +Specify @var{expression} as the break condition for breakpoint, +watchpoint, or catchpoint number @var{bnum}. After you set a condition, +breakpoint @var{bnum} stops your program only if the value of +@var{expression} is true (nonzero, in C). When you use +@code{condition}, @value{GDBN} checks @var{expression} immediately for +syntactic correctness, and to determine whether symbols in it have +referents in the context of your breakpoint. If @var{expression} uses +symbols not referenced in the context of the breakpoint, @value{GDBN} +prints an error message: + +@smallexample +No symbol "foo" in current context. +@end smallexample + +@noindent +@value{GDBN} does +not actually evaluate @var{expression} at the time the @code{condition} +command (or a command that sets a breakpoint with a condition, like +@code{break if @dots{}}) is given, however. @xref{Expressions, ,Expressions}. + +@item condition -force @var{bnum} @var{expression} +When the @code{-force} flag is used, define the condition even if +@var{expression} is invalid at all the current locations of breakpoint +@var{bnum}. This is similar to the @code{-force-condition} option +of the @code{break} command. + +@item condition @var{bnum} +Remove the condition from breakpoint number @var{bnum}. It becomes +an ordinary unconditional breakpoint. +@end table + +@cindex ignore count (of breakpoint) +A special case of a breakpoint condition is to stop only when the +breakpoint has been reached a certain number of times. This is so +useful that there is a special way to do it, using the @dfn{ignore +count} of the breakpoint. Every breakpoint has an ignore count, which +is an integer. Most of the time, the ignore count is zero, and +therefore has no effect. But if your program reaches a breakpoint whose +ignore count is positive, then instead of stopping, it just decrements +the ignore count by one and continues. As a result, if the ignore count +value is @var{n}, the breakpoint does not stop the next @var{n} times +your program reaches it. + +@table @code +@kindex ignore +@item ignore @var{bnum} @var{count} +Set the ignore count of breakpoint number @var{bnum} to @var{count}. +The next @var{count} times the breakpoint is reached, your program's +execution does not stop; other than to decrement the ignore count, @value{GDBN} +takes no action. + +To make the breakpoint stop the next time it is reached, specify +a count of zero. + +When you use @code{continue} to resume execution of your program from a +breakpoint, you can specify an ignore count directly as an argument to +@code{continue}, rather than using @code{ignore}. @xref{Continuing and +Stepping,,Continuing and Stepping}. + +If a breakpoint has a positive ignore count and a condition, the +condition is not checked. Once the ignore count reaches zero, +@value{GDBN} resumes checking the condition. + +You could achieve the effect of the ignore count with a condition such +as @w{@samp{$foo-- <= 0}} using a debugger convenience variable that +is decremented each time. @xref{Convenience Vars, ,Convenience +Variables}. +@end table + +Ignore counts apply to breakpoints, watchpoints, tracepoints, and catchpoints. + + +@node Break Commands +@subsection Breakpoint Command Lists + +@cindex breakpoint commands +You can give any breakpoint (or watchpoint or catchpoint) a series of +commands to execute when your program stops due to that breakpoint. For +example, you might want to print the values of certain expressions, or +enable other breakpoints. + +@table @code +@kindex commands +@kindex end@r{ (breakpoint commands)} +@item commands @r{[}@var{list}@dots{}@r{]} +@itemx @dots{} @var{command-list} @dots{} +@itemx end +Specify a list of commands for the given breakpoints. The commands +themselves appear on the following lines. Type a line containing just +@code{end} to terminate the commands. + +To remove all commands from a breakpoint, type @code{commands} and +follow it immediately with @code{end}; that is, give no commands. + +With no argument, @code{commands} refers to the last breakpoint, +watchpoint, or catchpoint set (not to the breakpoint most recently +encountered). If the most recent breakpoints were set with a single +command, then the @code{commands} will apply to all the breakpoints +set by that command. This applies to breakpoints set by +@code{rbreak}, and also applies when a single @code{break} command +creates multiple breakpoints (@pxref{Ambiguous Expressions,,Ambiguous +Expressions}). +@end table + +Pressing @key{RET} as a means of repeating the last @value{GDBN} command is +disabled within a @var{command-list}. + +Inside a command list, you can use the command +@kbd{disable $_hit_bpnum} to disable the encountered breakpoint. + +If your breakpoint has several code locations, the command +@kbd{disable $_hit_bpnum.$_hit_locno} will disable the specific breakpoint +code location encountered. If the breakpoint has only one location, +this command will disable the encountered breakpoint. + +You can use breakpoint commands to start your program up again. Simply +use the @code{continue} command, or @code{step}, or any other command +that resumes execution. + +Any other commands in the command list, after a command that resumes +execution, are ignored. This is because any time you resume execution +(even with a simple @code{next} or @code{step}), you may encounter +another breakpoint---which could have its own command list, leading to +ambiguities about which list to execute. + +@kindex silent +If the first command you specify in a command list is @code{silent}, the +usual message about stopping at a breakpoint is not printed. This may +be desirable for breakpoints that are to print a specific message and +then continue. If none of the remaining commands print anything, you +see no sign that the breakpoint was reached. @code{silent} is +meaningful only at the beginning of a breakpoint command list. + +The commands @code{echo}, @code{output}, and @code{printf} allow you to +print precisely controlled output, and are often useful in silent +breakpoints. @xref{Output, ,Commands for Controlled Output}. + +For example, here is how you could use breakpoint commands to print the +value of @code{x} at entry to @code{foo} whenever @code{x} is positive. + +@smallexample +break foo if x>0 +commands +silent +printf "x is %d\n",x +cont +end +@end smallexample + +One application for breakpoint commands is to compensate for one bug so +you can test for another. Put a breakpoint just after the erroneous line +of code, give it a condition to detect the case in which something +erroneous has been done, and give it commands to assign correct values +to any variables that need them. End with the @code{continue} command +so that your program does not stop, and start with the @code{silent} +command so that no output is produced. Here is an example: + +@smallexample +break 403 +commands +silent +set x = y + 4 +cont +end +@end smallexample + +@node Dynamic Printf +@subsection Dynamic Printf + +@cindex dynamic printf +@cindex dprintf +The dynamic printf command @code{dprintf} combines a breakpoint with +formatted printing of your program's data to give you the effect of +inserting @code{printf} calls into your program on-the-fly, without +having to recompile it. + +In its most basic form, the output goes to the GDB console. However, +you can set the variable @code{dprintf-style} for alternate handling. +For instance, you can ask to format the output by calling your +program's @code{printf} function. This has the advantage that the +characters go to the program's output device, so they can recorded in +redirects to files and so forth. + +If you are doing remote debugging with a stub or agent, you can also +ask to have the printf handled by the remote agent. In addition to +ensuring that the output goes to the remote program's device along +with any other output the program might produce, you can also ask that +the dprintf remain active even after disconnecting from the remote +target. Using the stub/agent is also more efficient, as it can do +everything without needing to communicate with @value{GDBN}. + +@table @code +@kindex dprintf +@item dprintf @var{locspec},@var{template},@var{expression}[,@var{expression}@dots{}] +Whenever execution reaches a code location that results from resolving +@var{locspec}, print the values of one or more @var{expressions} under +the control of the string @var{template}. To print several values, +separate them with commas. + +@item set dprintf-style @var{style} +Set the dprintf output to be handled in one of several different +styles enumerated below. A change of style affects all existing +dynamic printfs immediately. (If you need individual control over the +print commands, simply define normal breakpoints with +explicitly-supplied command lists.) + +@table @code +@item gdb +@kindex dprintf-style gdb +Handle the output using the @value{GDBN} @code{printf} command. When +using this style, it is possible to use the @samp{%V} format specifier +(@pxref{%V Format Specifier}). + +@item call +@kindex dprintf-style call +Handle the output by calling a function in your program (normally +@code{printf}). When using this style the supported format specifiers +depend entirely on the function being called. + +Most of @value{GDBN}'s format specifiers align with those supported by +the @code{printf} function, however, @value{GDBN}'s @samp{%V} format +specifier extension is not supported by @code{printf}. When using +@samp{call} style dprintf, care should be taken to ensure that only +format specifiers supported by the output function are used, otherwise +the results will be undefined. + +@item agent +@kindex dprintf-style agent +Have the remote debugging agent (such as @code{gdbserver}) handle the +output itself. This style is only available for agents that support +running commands on the target. This style does not support the +@samp{%V} format specifier. +@end table + +@item set dprintf-function @var{function} +Set the function to call if the dprintf style is @code{call}. By +default its value is @code{printf}. You may set it to any expression +that @value{GDBN} can evaluate to a function, as per the @code{call} +command. + +@item set dprintf-channel @var{channel} +Set a ``channel'' for dprintf. If set to a non-empty value, +@value{GDBN} will evaluate it as an expression and pass the result as +a first argument to the @code{dprintf-function}, in the manner of +@code{fprintf} and similar functions. Otherwise, the dprintf format +string will be the first argument, in the manner of @code{printf}. + +As an example, if you wanted @code{dprintf} output to go to a logfile +that is a standard I/O stream assigned to the variable @code{mylog}, +you could do the following: + +@example +(@value{GDBP}) set dprintf-style call +(@value{GDBP}) set dprintf-function fprintf +(@value{GDBP}) set dprintf-channel mylog +(@value{GDBP}) dprintf 25,"at line 25, glob=%d\n",glob +Dprintf 1 at 0x123456: file main.c, line 25. +(@value{GDBP}) info break +1 dprintf keep y 0x00123456 in main at main.c:25 + call (void) fprintf (mylog,"at line 25, glob=%d\n",glob) + continue +(@value{GDBP}) +@end example + +Note that the @code{info break} displays the dynamic printf commands +as normal breakpoint commands; you can thus easily see the effect of +the variable settings. + +@item set disconnected-dprintf on +@itemx set disconnected-dprintf off +@kindex set disconnected-dprintf +Choose whether @code{dprintf} commands should continue to run if +@value{GDBN} has disconnected from the target. This only applies +if the @code{dprintf-style} is @code{agent}. + +@item show disconnected-dprintf off +@kindex show disconnected-dprintf +Show the current choice for disconnected @code{dprintf}. + +@end table + +@value{GDBN} does not check the validity of function and channel, +relying on you to supply values that are meaningful for the contexts +in which they are being used. For instance, the function and channel +may be the values of local variables, but if that is the case, then +all enabled dynamic prints must be at locations within the scope of +those locals. If evaluation fails, @value{GDBN} will report an error. + +@node Save Breakpoints +@subsection How to save breakpoints to a file + +To save breakpoint definitions to a file use the @w{@code{save +breakpoints}} command. + +@table @code +@kindex save breakpoints +@cindex save breakpoints to a file for future sessions +@item save breakpoints [@var{filename}] +This command saves all current breakpoint definitions together with +their commands and ignore counts, into a file @file{@var{filename}} +suitable for use in a later debugging session. This includes all +types of breakpoints (breakpoints, watchpoints, catchpoints, +tracepoints). To read the saved breakpoint definitions, use the +@code{source} command (@pxref{Command Files}). Note that watchpoints +with expressions involving local variables may fail to be recreated +because it may not be possible to access the context where the +watchpoint is valid anymore. Because the saved breakpoint definitions +are simply a sequence of @value{GDBN} commands that recreate the +breakpoints, you can edit the file in your favorite editing program, +and remove the breakpoint definitions you're not interested in, or +that can no longer be recreated. +@end table + +@node Static Probe Points +@subsection Static Probe Points + +@cindex static probe point, SystemTap +@cindex static probe point, DTrace +@value{GDBN} supports @dfn{SDT} probes in the code. @acronym{SDT} stands +for Statically Defined Tracing, and the probes are designed to have a tiny +runtime code and data footprint, and no dynamic relocations. + +Currently, the following types of probes are supported on +ELF-compatible systems: + +@itemize @bullet + +@item @code{SystemTap} (@uref{http://sourceware.org/systemtap/}) +@acronym{SDT} probes@footnote{See +@uref{http://sourceware.org/systemtap/wiki/AddingUserSpaceProbingToApps} +for more information on how to add @code{SystemTap} @acronym{SDT} +probes in your applications.}. @code{SystemTap} probes are usable +from assembly, C and C@t{++} languages@footnote{See +@uref{http://sourceware.org/systemtap/wiki/UserSpaceProbeImplementation} +for a good reference on how the @acronym{SDT} probes are implemented.}. + +@item @code{DTrace} (@uref{http://oss.oracle.com/projects/DTrace}) +@acronym{USDT} probes. @code{DTrace} probes are usable from C and +C@t{++} languages. +@end itemize + +@cindex semaphores on static probe points +Some @code{SystemTap} probes have an associated semaphore variable; +for instance, this happens automatically if you defined your probe +using a DTrace-style @file{.d} file. If your probe has a semaphore, +@value{GDBN} will automatically enable it when you specify a +breakpoint using the @samp{-probe-stap} notation. But, if you put a +breakpoint at a probe's location by some other method (e.g., +@code{break file:line}), then @value{GDBN} will not automatically set +the semaphore. @code{DTrace} probes do not support semaphores. + +You can examine the available static static probes using @code{info +probes}, with optional arguments: + +@table @code +@kindex info probes +@item info probes @r{[}@var{type}@r{]} @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} +If given, @var{type} is either @code{stap} for listing +@code{SystemTap} probes or @code{dtrace} for listing @code{DTrace} +probes. If omitted all probes are listed regardless of their types. + +If given, @var{provider} is a regular expression used to match against provider +names when selecting which probes to list. If omitted, probes by all +probes from all providers are listed. + +If given, @var{name} is a regular expression to match against probe names +when selecting which probes to list. If omitted, probe names are not +considered when deciding whether to display them. + +If given, @var{objfile} is a regular expression used to select which +object files (executable or shared libraries) to examine. If not +given, all object files are considered. + +@item info probes all +List the available static probes, from all types. +@end table + +@cindex enabling and disabling probes +Some probe points can be enabled and/or disabled. The effect of +enabling or disabling a probe depends on the type of probe being +handled. Some @code{DTrace} probes can be enabled or +disabled, but @code{SystemTap} probes cannot be disabled. + +You can enable (or disable) one or more probes using the following +commands, with optional arguments: + +@anchor{enable probes} +@table @code +@kindex enable probes +@item enable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} +If given, @var{provider} is a regular expression used to match against +provider names when selecting which probes to enable. If omitted, +all probes from all providers are enabled. + +If given, @var{name} is a regular expression to match against probe +names when selecting which probes to enable. If omitted, probe names +are not considered when deciding whether to enable them. + +If given, @var{objfile} is a regular expression used to select which +object files (executable or shared libraries) to examine. If not +given, all object files are considered. + +@kindex disable probes +@item disable probes @r{[}@var{provider} @r{[}@var{name} @r{[}@var{objfile}@r{]}@r{]}@r{]} +See the @code{enable probes} command above for a description of the +optional arguments accepted by this command. +@end table + +@vindex $_probe_arg@r{, convenience variable} +A probe may specify up to twelve arguments. These are available at the +point at which the probe is defined---that is, when the current PC is +at the probe's location. The arguments are available using the +convenience variables (@pxref{Convenience Vars}) +@code{$_probe_arg0}@dots{}@code{$_probe_arg11}. In @code{SystemTap} +probes each probe argument is an integer of the appropriate size; +types are not preserved. In @code{DTrace} probes types are preserved +provided that they are recognized as such by @value{GDBN}; otherwise +the value of the probe argument will be a long integer. The +convenience variable @code{$_probe_argc} holds the number of arguments +at the current probe point. + +These variables are always available, but attempts to access them at +any location other than a probe point will cause @value{GDBN} to give +an error message. + + +@c @ifclear BARETARGET +@node Error in Breakpoints +@subsection ``Cannot insert breakpoints'' + +If you request too many active hardware-assisted breakpoints and +watchpoints, you will see this error message: + +@c FIXME: the precise wording of this message may change; the relevant +@c source change is not committed yet (Sep 3, 1999). +@smallexample +Stopped; cannot insert breakpoints. +You may have requested too many hardware breakpoints and watchpoints. +@end smallexample + +@noindent +This message is printed when you attempt to resume the program, since +only then @value{GDBN} knows exactly how many hardware breakpoints and +watchpoints it needs to insert. + +When this message is printed, you need to disable or remove some of the +hardware-assisted breakpoints and watchpoints, and then continue. + +@node Breakpoint-related Warnings +@subsection ``Breakpoint address adjusted...'' +@cindex breakpoint address adjusted + +Some processor architectures place constraints on the addresses at +which breakpoints may be placed. For architectures thus constrained, +@value{GDBN} will attempt to adjust the breakpoint's address to comply +with the constraints dictated by the architecture. + +One example of such an architecture is the Fujitsu FR-V. The FR-V is +a VLIW architecture in which a number of RISC-like instructions may be +bundled together for parallel execution. The FR-V architecture +constrains the location of a breakpoint instruction within such a +bundle to the instruction with the lowest address. @value{GDBN} +honors this constraint by adjusting a breakpoint's address to the +first in the bundle. + +It is not uncommon for optimized code to have bundles which contain +instructions from different source statements, thus it may happen that +a breakpoint's address will be adjusted from one source statement to +another. Since this adjustment may significantly alter @value{GDBN}'s +breakpoint related behavior from what the user expects, a warning is +printed when the breakpoint is first set and also when the breakpoint +is hit. + +A warning like the one below is printed when setting a breakpoint +that's been subject to address adjustment: + +@smallexample +warning: Breakpoint address adjusted from 0x00010414 to 0x00010410. +@end smallexample + +Such warnings are printed both for user settable and @value{GDBN}'s +internal breakpoints. If you see one of these warnings, you should +verify that a breakpoint set at the adjusted address will have the +desired affect. If not, the breakpoint in question may be removed and +other breakpoints may be set which will have the desired behavior. +E.g., it may be sufficient to place the breakpoint at a later +instruction. A conditional breakpoint may also be useful in some +cases to prevent the breakpoint from triggering too often. + +@value{GDBN} will also issue a warning when stopping at one of these +adjusted breakpoints: + +@smallexample +warning: Breakpoint 1 address previously adjusted from 0x00010414 +to 0x00010410. +@end smallexample + +When this warning is encountered, it may be too late to take remedial +action except in cases where the breakpoint is hit earlier or more +frequently than expected. + +@node Continuing and Stepping +@section Continuing and Stepping + +@cindex stepping +@cindex continuing +@cindex resuming execution +@dfn{Continuing} means resuming program execution until your program +completes normally. In contrast, @dfn{stepping} means executing just +one more ``step'' of your program, where ``step'' may mean either one +line of source code, or one machine instruction (depending on what +particular command you use). Either when continuing or when stepping, +your program may stop even sooner, due to a breakpoint or a signal. (If +it stops due to a signal, you may want to use @code{handle}, or use +@samp{signal 0} to resume execution (@pxref{Signals, ,Signals}), +or you may step into the signal's handler (@pxref{stepping and signal +handlers}).) + +@table @code +@kindex continue +@kindex c @r{(@code{continue})} +@kindex fg @r{(resume foreground execution)} +@item continue @r{[}@var{ignore-count}@r{]} +@itemx c @r{[}@var{ignore-count}@r{]} +@itemx fg @r{[}@var{ignore-count}@r{]} +Resume program execution, at the address where your program last stopped; +any breakpoints set at that address are bypassed. The optional argument +@var{ignore-count} allows you to specify a further number of times to +ignore a breakpoint at this location; its effect is like that of +@code{ignore} (@pxref{Conditions, ,Break Conditions}). + +The argument @var{ignore-count} is meaningful only when your program +stopped due to a breakpoint. At other times, the argument to +@code{continue} is ignored. + +The synonyms @code{c} and @code{fg} (for @dfn{foreground}, as the +debugged program is deemed to be the foreground program) are provided +purely for convenience, and have exactly the same behavior as +@code{continue}. +@end table + +To resume execution at a different place, you can use @code{return} +(@pxref{Returning, ,Returning from a Function}) to go back to the +calling function; or @code{jump} (@pxref{Jumping, ,Continuing at a +Different Address}) to go to an arbitrary location in your program. + +A typical technique for using stepping is to set a breakpoint +(@pxref{Breakpoints, ,Breakpoints; Watchpoints; and Catchpoints}) at the +beginning of the function or the section of your program where a problem +is believed to lie, run your program until it stops at that breakpoint, +and then step through the suspect area, examining the variables that are +interesting, until you see the problem happen. + +@table @code +@kindex step +@kindex s @r{(@code{step})} +@item step +Continue running your program until control reaches a different source +line, then stop it and return control to @value{GDBN}. This command is +abbreviated @code{s}. + +@quotation +@c "without debugging information" is imprecise; actually "without line +@c numbers in the debugging information". (gcc -g1 has debugging info but +@c not line numbers). But it seems complex to try to make that +@c distinction here. +@emph{Warning:} If you use the @code{step} command while control is +within a function that was compiled without debugging information, +execution proceeds until control reaches a function that does have +debugging information. Likewise, it will not step into a function which +is compiled without debugging information. To step through functions +without debugging information, use the @code{stepi} command, described +below. +@end quotation + +The @code{step} command only stops at the first instruction of a source +line. This prevents the multiple stops that could otherwise occur in +@code{switch} statements, @code{for} loops, etc. @code{step} continues +to stop if a function that has debugging information is called within +the line. In other words, @code{step} @emph{steps inside} any functions +called within the line. + +Also, the @code{step} command only enters a function if there is line +number information for the function. Otherwise it acts like the +@code{next} command. This avoids problems when using @code{cc -gl} +on @acronym{MIPS} machines. Previously, @code{step} entered subroutines if there +was any debugging information about the routine. + +@item step @var{count} +Continue running as in @code{step}, but do so @var{count} times. If a +breakpoint is reached, or a signal not related to stepping occurs before +@var{count} steps, stepping stops right away. + +@kindex next +@kindex n @r{(@code{next})} +@item next @r{[}@var{count}@r{]} +Continue to the next source line in the current (innermost) stack frame. +This is similar to @code{step}, but function calls that appear within +the line of code are executed without stopping. Execution stops when +control reaches a different line of code at the original stack level +that was executing when you gave the @code{next} command. This command +is abbreviated @code{n}. + +An argument @var{count} is a repeat count, as for @code{step}. + + +@c FIX ME!! Do we delete this, or is there a way it fits in with +@c the following paragraph? --- Vctoria +@c +@c @code{next} within a function that lacks debugging information acts like +@c @code{step}, but any function calls appearing within the code of the +@c function are executed without stopping. + +The @code{next} command only stops at the first instruction of a +source line. This prevents multiple stops that could otherwise occur in +@code{switch} statements, @code{for} loops, etc. + +@kindex set step-mode +@item set step-mode +@cindex functions without line info, and stepping +@cindex stepping into functions with no line info +@itemx set step-mode on +The @code{set step-mode on} command causes the @code{step} command to +stop at the first instruction of a function which contains no debug line +information rather than stepping over it. + +This is useful in cases where you may be interested in inspecting the +machine instructions of a function which has no symbolic info and do not +want @value{GDBN} to automatically skip over this function. + +@item set step-mode off +Causes the @code{step} command to step over any functions which contains no +debug information. This is the default. + +@item show step-mode +Show whether @value{GDBN} will stop in or step over functions without +source line debug information. + +@kindex finish +@kindex fin @r{(@code{finish})} +@item finish +Continue running until just after function in the selected stack frame +returns. Print the returned value (if any). This command can be +abbreviated as @code{fin}. + +Contrast this with the @code{return} command (@pxref{Returning, +,Returning from a Function}). + +@kindex set print finish +@kindex show print finish +@item set print finish @r{[}on|off@r{]} +@itemx show print finish +By default the @code{finish} command will show the value that is +returned by the function. This can be disabled using @code{set print +finish off}. When disabled, the value is still entered into the value +history (@pxref{Value History}), but not displayed. + +@kindex until +@kindex u @r{(@code{until})} +@cindex run until specified location +@item until +@itemx u +Continue running until a source line past the current line, in the +current stack frame, is reached. This command is used to avoid single +stepping through a loop more than once. It is like the @code{next} +command, except that when @code{until} encounters a jump, it +automatically continues execution until the program counter is greater +than the address of the jump. + +This means that when you reach the end of a loop after single stepping +though it, @code{until} makes your program continue execution until it +exits the loop. In contrast, a @code{next} command at the end of a loop +simply steps back to the beginning of the loop, which forces you to step +through the next iteration. + +@code{until} always stops your program if it attempts to exit the current +stack frame. + +@code{until} may produce somewhat counterintuitive results if the order +of machine code does not match the order of the source lines. For +example, in the following excerpt from a debugging session, the @code{f} +(@code{frame}) command shows that execution is stopped at line +@code{206}; yet when we use @code{until}, we get to line @code{195}: + +@smallexample +(@value{GDBP}) f +#0 main (argc=4, argv=0xf7fffae8) at m4.c:206 +206 expand_input(); +(@value{GDBP}) until +195 for ( ; argc > 0; NEXTARG) @{ +@end smallexample + +This happened because, for execution efficiency, the compiler had +generated code for the loop closure test at the end, rather than the +start, of the loop---even though the test in a C @code{for}-loop is +written before the body of the loop. The @code{until} command appeared +to step back to the beginning of the loop when it advanced to this +expression; however, it has not really gone to an earlier +statement---not in terms of the actual machine code. + +@code{until} with no argument works by means of single +instruction stepping, and hence is slower than @code{until} with an +argument. + +@item until @var{locspec} +@itemx u @var{locspec} +Continue running your program until either it reaches a code location +that results from resolving @var{locspec}, or the current stack frame +returns. @var{locspec} is any of the forms described in @ref{Location +Specifications}. +This form of the command uses temporary breakpoints, and +hence is quicker than @code{until} without an argument. The specified +location is actually reached only if it is in the current frame. This +implies that @code{until} can be used to skip over recursive function +invocations. For instance in the code below, if the current location is +line @code{96}, issuing @code{until 99} will execute the program up to +line @code{99} in the same invocation of factorial, i.e., after the inner +invocations have returned. + +@smallexample +94 int factorial (int value) +95 @{ +96 if (value > 1) @{ +97 value *= factorial (value - 1); +98 @} +99 return (value); +100 @} +@end smallexample + + +@kindex advance @var{locspec} +@item advance @var{locspec} +Continue running your program until either it reaches a code location +that results from resolving @var{locspec}, or the current stack frame +returns. @var{locspec} is any of the forms described in @ref{Location +Specifications}. This command is similar to @code{until}, but +@code{advance} will not skip over recursive function calls, and the +target code location doesn't have to be in the same frame as the +current one. + + +@kindex stepi +@kindex si @r{(@code{stepi})} +@item stepi +@itemx stepi @var{arg} +@itemx si +Execute one machine instruction, then stop and return to the debugger. + +It is often useful to do @samp{display/i $pc} when stepping by machine +instructions. This makes @value{GDBN} automatically display the next +instruction to be executed, each time your program stops. @xref{Auto +Display,, Automatic Display}. + +An argument is a repeat count, as in @code{step}. + +@need 750 +@kindex nexti +@kindex ni @r{(@code{nexti})} +@item nexti +@itemx nexti @var{arg} +@itemx ni +Execute one machine instruction, but if it is a function call, +proceed until the function returns. + +An argument is a repeat count, as in @code{next}. + +@end table + +@anchor{range stepping} +@cindex range stepping +@cindex target-assisted range stepping +By default, and if available, @value{GDBN} makes use of +target-assisted @dfn{range stepping}. In other words, whenever you +use a stepping command (e.g., @code{step}, @code{next}), @value{GDBN} +tells the target to step the corresponding range of instruction +addresses instead of issuing multiple single-steps. This speeds up +line stepping, particularly for remote targets. Ideally, there should +be no reason you would want to turn range stepping off. However, it's +possible that a bug in the debug info, a bug in the remote stub (for +remote targets), or even a bug in @value{GDBN} could make line +stepping behave incorrectly when target-assisted range stepping is +enabled. You can use the following command to turn off range stepping +if necessary: + +@table @code +@kindex set range-stepping +@kindex show range-stepping +@item set range-stepping +@itemx show range-stepping +Control whether range stepping is enabled. + +If @code{on}, and the target supports it, @value{GDBN} tells the +target to step a range of addresses itself, instead of issuing +multiple single-steps. If @code{off}, @value{GDBN} always issues +single-steps, even if range stepping is supported by the target. The +default is @code{on}. + +@end table + +@node Skipping Over Functions and Files +@section Skipping Over Functions and Files +@cindex skipping over functions and files + +The program you are debugging may contain some functions which are +uninteresting to debug. The @code{skip} command lets you tell @value{GDBN} to +skip a function, all functions in a file or a particular function in +a particular file when stepping. + +For example, consider the following C function: + +@smallexample +101 int func() +102 @{ +103 foo(boring()); +104 bar(boring()); +105 @} +@end smallexample + +@noindent +Suppose you wish to step into the functions @code{foo} and @code{bar}, but you +are not interested in stepping through @code{boring}. If you run @code{step} +at line 103, you'll enter @code{boring()}, but if you run @code{next}, you'll +step over both @code{foo} and @code{boring}! + +One solution is to @code{step} into @code{boring} and use the @code{finish} +command to immediately exit it. But this can become tedious if @code{boring} +is called from many places. + +A more flexible solution is to execute @kbd{skip boring}. This instructs +@value{GDBN} never to step into @code{boring}. Now when you execute +@code{step} at line 103, you'll step over @code{boring} and directly into +@code{foo}. + +Functions may be skipped by providing either a function name, linespec +(@pxref{Location Specifications}), regular expression that matches the function's +name, file name or a @code{glob}-style pattern that matches the file name. + +On Posix systems the form of the regular expression is +``Extended Regular Expressions''. See for example @samp{man 7 regex} +on @sc{gnu}/Linux systems. On non-Posix systems the form of the regular +expression is whatever is provided by the @code{regcomp} function of +the underlying system. +See for example @samp{man 7 glob} on @sc{gnu}/Linux systems for a +description of @code{glob}-style patterns. + +@table @code +@kindex skip +@item skip @r{[}@var{options}@r{]} +The basic form of the @code{skip} command takes zero or more options +that specify what to skip. +The @var{options} argument is any useful combination of the following: + +@table @code +@item -file @var{file} +@itemx -fi @var{file} +Functions in @var{file} will be skipped over when stepping. + +@item -gfile @var{file-glob-pattern} +@itemx -gfi @var{file-glob-pattern} +@cindex skipping over files via glob-style patterns +Functions in files matching @var{file-glob-pattern} will be skipped +over when stepping. + +@smallexample +(@value{GDBP}) skip -gfi utils/*.c +@end smallexample + +@item -function @var{linespec} +@itemx -fu @var{linespec} +Functions named by @var{linespec} or the function containing the line +named by @var{linespec} will be skipped over when stepping. +@xref{Location Specifications}. + +@item -rfunction @var{regexp} +@itemx -rfu @var{regexp} +@cindex skipping over functions via regular expressions +Functions whose name matches @var{regexp} will be skipped over when stepping. + +This form is useful for complex function names. +For example, there is generally no need to step into C@t{++} @code{std::string} +constructors or destructors. Plus with C@t{++} templates it can be hard to +write out the full name of the function, and often it doesn't matter what +the template arguments are. Specifying the function to be skipped as a +regular expression makes this easier. + +@smallexample +(@value{GDBP}) skip -rfu ^std::(allocator|basic_string)<.*>::~?\1 *\( +@end smallexample + +If you want to skip every templated C@t{++} constructor and destructor +in the @code{std} namespace you can do: + +@smallexample +(@value{GDBP}) skip -rfu ^std::([a-zA-z0-9_]+)<.*>::~?\1 *\( +@end smallexample +@end table + +If no options are specified, the function you're currently debugging +will be skipped. + +@kindex skip function +@item skip function @r{[}@var{linespec}@r{]} +After running this command, the function named by @var{linespec} or the +function containing the line named by @var{linespec} will be skipped over when +stepping. @xref{Location Specifications}. + +If you do not specify @var{linespec}, the function you're currently debugging +will be skipped. + +(If you have a function called @code{file} that you want to skip, use +@kbd{skip function file}.) + +@kindex skip file +@item skip file @r{[}@var{filename}@r{]} +After running this command, any function whose source lives in @var{filename} +will be skipped over when stepping. + +@smallexample +(@value{GDBP}) skip file boring.c +File boring.c will be skipped when stepping. +@end smallexample + +If you do not specify @var{filename}, functions whose source lives in the file +you're currently debugging will be skipped. +@end table + +Skips can be listed, deleted, disabled, and enabled, much like breakpoints. +These are the commands for managing your list of skips: + +@table @code +@kindex info skip +@item info skip @r{[}@var{range}@r{]} +Print details about the specified skip(s). If @var{range} is not specified, +print a table with details about all functions and files marked for skipping. +@code{info skip} prints the following information about each skip: + +@table @emph +@item Identifier +A number identifying this skip. +@item Enabled or Disabled +Enabled skips are marked with @samp{y}. +Disabled skips are marked with @samp{n}. +@item Glob +If the file name is a @samp{glob} pattern this is @samp{y}. +Otherwise it is @samp{n}. +@item File +The name or @samp{glob} pattern of the file to be skipped. +If no file is specified this is @samp{}. +@item RE +If the function name is a @samp{regular expression} this is @samp{y}. +Otherwise it is @samp{n}. +@item Function +The name or regular expression of the function to skip. +If no function is specified this is @samp{}. +@end table + +@kindex skip delete +@item skip delete @r{[}@var{range}@r{]} +Delete the specified skip(s). If @var{range} is not specified, delete all +skips. + +@kindex skip enable +@item skip enable @r{[}@var{range}@r{]} +Enable the specified skip(s). If @var{range} is not specified, enable all +skips. + +@kindex skip disable +@item skip disable @r{[}@var{range}@r{]} +Disable the specified skip(s). If @var{range} is not specified, disable all +skips. + +@kindex set debug skip +@item set debug skip @r{[}on|off@r{]} +Set whether to print the debug output about skipping files and functions. + +@kindex show debug skip +@item show debug skip +Show whether the debug output about skipping files and functions is printed. + +@end table + +@node Signals +@section Signals +@cindex signals + +A signal is an asynchronous event that can happen in a program. The +operating system defines the possible kinds of signals, and gives each +kind a name and a number. For example, in Unix @code{SIGINT} is the +signal a program gets when you type an interrupt character (often @kbd{Ctrl-c}); +@code{SIGSEGV} is the signal a program gets from referencing a place in +memory far away from all the areas in use; @code{SIGALRM} occurs when +the alarm clock timer goes off (which happens only if your program has +requested an alarm). + +@cindex fatal signals +Some signals, including @code{SIGALRM}, are a normal part of the +functioning of your program. Others, such as @code{SIGSEGV}, indicate +errors; these signals are @dfn{fatal} (they kill your program immediately) if the +program has not specified in advance some other way to handle the signal. +@code{SIGINT} does not indicate an error in your program, but it is normally +fatal so it can carry out the purpose of the interrupt: to kill the program. + +@value{GDBN} has the ability to detect any occurrence of a signal in your +program. You can tell @value{GDBN} in advance what to do for each kind of +signal. + +@cindex handling signals +Normally, @value{GDBN} is set up to let the non-erroneous signals like +@code{SIGALRM} be silently passed to your program +(so as not to interfere with their role in the program's functioning) +but to stop your program immediately whenever an error signal happens. +You can change these settings with the @code{handle} command. + +@table @code +@kindex info signals +@kindex info handle +@item info signals +@itemx info handle +Print a table of all the kinds of signals and how @value{GDBN} has been told to +handle each one. You can use this to see the signal numbers of all +the defined types of signals. + +@item info signals @var{sig} +Similar, but print information only about the specified signal number. + +@code{info handle} is an alias for @code{info signals}. + +@item catch signal @r{[}@var{signal}@dots{} @r{|} @samp{all}@r{]} +Set a catchpoint for the indicated signals. @xref{Set Catchpoints}, +for details about this command. + +@kindex handle +@item handle @var{signal} @r{[} @var{signal} @dots{} @r{]} @r{[}@var{keywords}@dots{}@r{]} +Change the way @value{GDBN} handles each @var{signal}. Each +@var{signal} can be the number of a signal or its name (with or +without the @samp{SIG} at the beginning); a list of signal numbers of +the form @samp{@var{low}-@var{high}}; or the word @samp{all}, meaning +all the known signals, except @code{SIGINT} and @code{SIGTRAP}, which +are used by @value{GDBN}. Optional argument @var{keywords}, described +below, say what changes to make to all of the specified signals. +@end table + +@c @group +The keywords allowed by the @code{handle} command can be abbreviated. +Their full names are: + +@table @code +@item nostop +@value{GDBN} should not stop your program when this signal happens. It may +still print a message telling you that the signal has come in. + +@item stop +@value{GDBN} should stop your program when this signal happens. This implies +the @code{print} keyword as well. + +@item print +@value{GDBN} should print a message when this signal happens. + +@item noprint +@value{GDBN} should not mention the occurrence of the signal at all. This +implies the @code{nostop} keyword as well. + +@item pass +@itemx noignore +@value{GDBN} should allow your program to see this signal; your program +can handle the signal, or else it may terminate if the signal is fatal +and not handled. @code{pass} and @code{noignore} are synonyms. + +@item nopass +@itemx ignore +@value{GDBN} should not allow your program to see this signal. +@code{nopass} and @code{ignore} are synonyms. +@end table +@c @end group + +When a signal stops your program, the signal is not visible to the +program until you +continue. Your program sees the signal then, if @code{pass} is in +effect for the signal in question @emph{at that time}. In other words, +after @value{GDBN} reports a signal, you can use the @code{handle} +command with @code{pass} or @code{nopass} to control whether your +program sees that signal when you continue. + +The default is set to @code{nostop}, @code{noprint}, @code{pass} for +non-erroneous signals such as @code{SIGALRM}, @code{SIGWINCH} and +@code{SIGCHLD}, and to @code{stop}, @code{print}, @code{pass} for the +erroneous signals. + +You can also use the @code{signal} command to prevent your program from +seeing a signal, or cause it to see a signal it normally would not see, +or to give it any signal at any time. For example, if your program stopped +due to some sort of memory reference error, you might store correct +values into the erroneous variables and continue, hoping to see more +execution; but your program would probably terminate immediately as +a result of the fatal signal once it saw the signal. To prevent this, +you can continue with @samp{signal 0}. @xref{Signaling, ,Giving your +Program a Signal}. + +@cindex stepping and signal handlers +@anchor{stepping and signal handlers} + +@value{GDBN} optimizes for stepping the mainline code. If a signal +that has @code{handle nostop} and @code{handle pass} set arrives while +a stepping command (e.g., @code{stepi}, @code{step}, @code{next}) is +in progress, @value{GDBN} lets the signal handler run and then resumes +stepping the mainline code once the signal handler returns. In other +words, @value{GDBN} steps over the signal handler. This prevents +signals that you've specified as not interesting (with @code{handle +nostop}) from changing the focus of debugging unexpectedly. Note that +the signal handler itself may still hit a breakpoint, stop for another +signal that has @code{handle stop} in effect, or for any other event +that normally results in stopping the stepping command sooner. Also +note that @value{GDBN} still informs you that the program received a +signal if @code{handle print} is set. + +@anchor{stepping into signal handlers} + +If you set @code{handle pass} for a signal, and your program sets up a +handler for it, then issuing a stepping command, such as @code{step} +or @code{stepi}, when your program is stopped due to the signal will +step @emph{into} the signal handler (if the target supports that). + +Likewise, if you use the @code{queue-signal} command to queue a signal +to be delivered to the current thread when execution of the thread +resumes (@pxref{Signaling, ,Giving your Program a Signal}), then a +stepping command will step into the signal handler. + +Here's an example, using @code{stepi} to step to the first instruction +of @code{SIGUSR1}'s handler: + +@smallexample +(@value{GDBP}) handle SIGUSR1 +Signal Stop Print Pass to program Description +SIGUSR1 Yes Yes Yes User defined signal 1 +(@value{GDBP}) c +Continuing. + +Program received signal SIGUSR1, User defined signal 1. +main () sigusr1.c:28 +28 p = 0; +(@value{GDBP}) si +sigusr1_handler () at sigusr1.c:9 +9 @{ +@end smallexample + +The same, but using @code{queue-signal} instead of waiting for the +program to receive the signal first: + +@smallexample +(@value{GDBP}) n +28 p = 0; +(@value{GDBP}) queue-signal SIGUSR1 +(@value{GDBP}) si +sigusr1_handler () at sigusr1.c:9 +9 @{ +(@value{GDBP}) +@end smallexample + +@cindex extra signal information +@anchor{extra signal information} + +On some targets, @value{GDBN} can inspect extra signal information +associated with the intercepted signal, before it is actually +delivered to the program being debugged. This information is exported +by the convenience variable @code{$_siginfo}, and consists of data +that is passed by the kernel to the signal handler at the time of the +receipt of a signal. The data type of the information itself is +target dependent. You can see the data type using the @code{ptype +$_siginfo} command. On Unix systems, it typically corresponds to the +standard @code{siginfo_t} type, as defined in the @file{signal.h} +system header. + +Here's an example, on a @sc{gnu}/Linux system, printing the stray +referenced address that raised a segmentation fault. + +@smallexample +@group +(@value{GDBP}) continue +Program received signal SIGSEGV, Segmentation fault. +0x0000000000400766 in main () +69 *(int *)p = 0; +(@value{GDBP}) ptype $_siginfo +type = struct @{ + int si_signo; + int si_errno; + int si_code; + union @{ + int _pad[28]; + struct @{...@} _kill; + struct @{...@} _timer; + struct @{...@} _rt; + struct @{...@} _sigchld; + struct @{...@} _sigfault; + struct @{...@} _sigpoll; + @} _sifields; +@} +(@value{GDBP}) ptype $_siginfo._sifields._sigfault +type = struct @{ + void *si_addr; +@} +(@value{GDBP}) p $_siginfo._sifields._sigfault.si_addr +$1 = (void *) 0x7ffff7ff7000 +@end group +@end smallexample + +Depending on target support, @code{$_siginfo} may also be writable. + +@node Thread Stops +@section Stopping and Starting Multi-thread Programs + +@cindex stopped threads +@cindex threads, stopped + +@cindex continuing threads +@cindex threads, continuing + +@value{GDBN} supports debugging programs with multiple threads +(@pxref{Threads,, Debugging Programs with Multiple Threads}). There +are two modes of controlling execution of your program within the +debugger. In the default mode, referred to as @dfn{all-stop mode}, +when any thread in your program stops (for example, at a breakpoint +or while being stepped), all other threads in the program are also stopped by +@value{GDBN}. On some targets, @value{GDBN} also supports +@dfn{non-stop mode}, in which other threads can continue to run freely while +you examine the stopped thread in the debugger. + +@menu +* All-Stop Mode:: All threads stop when GDB takes control +* Non-Stop Mode:: Other threads continue to execute +* Background Execution:: Running your program asynchronously +* Thread-Specific Breakpoints:: Controlling breakpoints +* Interrupted System Calls:: GDB may interfere with system calls +* Observer Mode:: GDB does not alter program behavior +@end menu + +@node All-Stop Mode +@subsection All-Stop Mode + +@cindex all-stop mode + +In all-stop mode, whenever your program stops under @value{GDBN} for any reason, +@emph{all} threads of execution stop, not just the current thread. This +allows you to examine the overall state of the program, including +switching between threads, without worrying that things may change +underfoot. + +Conversely, whenever you restart the program, @emph{all} threads start +executing. @emph{This is true even when single-stepping} with commands +like @code{step} or @code{next}. + +In particular, @value{GDBN} cannot single-step all threads in lockstep. +Since thread scheduling is up to your debugging target's operating +system (not controlled by @value{GDBN}), other threads may +execute more than one statement while the current thread completes a +single step. Moreover, in general other threads stop in the middle of a +statement, rather than at a clean statement boundary, when the program +stops. + +You might even find your program stopped in another thread after +continuing or even single-stepping. This happens whenever some other +thread runs into a breakpoint, a signal, or an exception before the +first thread completes whatever you requested. + +@cindex automatic thread selection +@cindex switching threads automatically +@cindex threads, automatic switching +Whenever @value{GDBN} stops your program, due to a breakpoint or a +signal, it automatically selects the thread where that breakpoint or +signal happened. @value{GDBN} alerts you to the context switch with a +message such as @samp{[Switching to Thread @var{n}]} to identify the +thread. + +@anchor{set scheduler-locking} + +On some OSes, you can modify @value{GDBN}'s default behavior by +locking the OS scheduler to allow only a single thread to run. + +@table @code +@item set scheduler-locking @var{mode} +@cindex scheduler-locking +@cindex scheduler locking mode +@cindex lock scheduler +Set the scheduler locking mode. It applies to normal execution, +record mode, and replay mode. @var{mode} can be one of +the following: + +@table @code +@item off +There is no locking and any thread may run at any time. + +@item on +Only the current thread may run when the inferior is resumed. New +threads created by the resumed thread are held stopped at their entry +point, before they execute any instruction. + +@item step +Behaves like @code{on} when stepping, and @code{off} otherwise. +Threads other than the current never get a chance to run when you +step, and they are completely free to run when you use commands like +@samp{continue}, @samp{until}, or @samp{finish}. + +This mode optimizes for single-stepping; it prevents other threads +from preempting the current thread while you are stepping, so that the +focus of debugging does not change unexpectedly. However, unless +another thread hits a breakpoint during its timeslice, @value{GDBN} +does not change the current thread away from the thread that you are +debugging. + +@item replay +Behaves like @code{on} in replay mode, and @code{off} in either record +mode or during normal execution. This is the default mode. +@end table + +@item show scheduler-locking +Display the current scheduler locking mode. +@end table + +@cindex resume threads of multiple processes simultaneously +By default, when you issue one of the execution commands such as +@code{continue}, @code{next} or @code{step}, @value{GDBN} allows only +threads of the current inferior to run. For example, if @value{GDBN} +is attached to two inferiors, each with two threads, the +@code{continue} command resumes only the two threads of the current +inferior. This is useful, for example, when you debug a program that +forks and you want to hold the parent stopped (so that, for instance, +it doesn't run to exit), while you debug the child. In other +situations, you may not be interested in inspecting the current state +of any of the processes @value{GDBN} is attached to, and you may want +to resume them all until some breakpoint is hit. In the latter case, +you can instruct @value{GDBN} to allow all threads of all the +inferiors to run with the @w{@code{set schedule-multiple}} command. + +@table @code +@kindex set schedule-multiple +@item set schedule-multiple +Set the mode for allowing threads of multiple processes to be resumed +when an execution command is issued. When @code{on}, all threads of +all processes are allowed to run. When @code{off}, only the threads +of the current process are resumed. The default is @code{off}. The +@code{scheduler-locking} mode takes precedence when set to @code{on}, +or while you are stepping and set to @code{step}. + +@item show schedule-multiple +Display the current mode for resuming the execution of threads of +multiple processes. +@end table + +@node Non-Stop Mode +@subsection Non-Stop Mode + +@cindex non-stop mode + +@c This section is really only a place-holder, and needs to be expanded +@c with more details. + +For some multi-threaded targets, @value{GDBN} supports an optional +mode of operation in which you can examine stopped program threads in +the debugger while other threads continue to execute freely. This +minimizes intrusion when debugging live systems, such as programs +where some threads have real-time constraints or must continue to +respond to external events. This is referred to as @dfn{non-stop} mode. + +In non-stop mode, when a thread stops to report a debugging event, +@emph{only} that thread is stopped; @value{GDBN} does not stop other +threads as well, in contrast to the all-stop mode behavior. Additionally, +execution commands such as @code{continue} and @code{step} apply by default +only to the current thread in non-stop mode, rather than all threads as +in all-stop mode. This allows you to control threads explicitly in +ways that are not possible in all-stop mode --- for example, stepping +one thread while allowing others to run freely, stepping +one thread while holding all others stopped, or stepping several threads +independently and simultaneously. + +To enter non-stop mode, use this sequence of commands before you run +or attach to your program: + +@smallexample +# If using the CLI, pagination breaks non-stop. +set pagination off + +# Finally, turn it on! +set non-stop on +@end smallexample + +You can use these commands to manipulate the non-stop mode setting: + +@table @code +@kindex set non-stop +@item set non-stop on +Enable selection of non-stop mode. +@item set non-stop off +Disable selection of non-stop mode. +@kindex show non-stop +@item show non-stop +Show the current non-stop enablement setting. +@end table + +Note these commands only reflect whether non-stop mode is enabled, +not whether the currently-executing program is being run in non-stop mode. +In particular, the @code{set non-stop} preference is only consulted when +@value{GDBN} starts or connects to the target program, and it is generally +not possible to switch modes once debugging has started. Furthermore, +since not all targets support non-stop mode, even when you have enabled +non-stop mode, @value{GDBN} may still fall back to all-stop operation by +default. + +In non-stop mode, all execution commands apply only to the current thread +by default. That is, @code{continue} only continues one thread. +To continue all threads, issue @code{continue -a} or @code{c -a}. + +You can use @value{GDBN}'s background execution commands +(@pxref{Background Execution}) to run some threads in the background +while you continue to examine or step others from @value{GDBN}. +The MI execution commands (@pxref{GDB/MI Program Execution}) are +always executed asynchronously in non-stop mode. + +Suspending execution is done with the @code{interrupt} command when +running in the background, or @kbd{Ctrl-c} during foreground execution. +In all-stop mode, this stops the whole process; +but in non-stop mode the interrupt applies only to the current thread. +To stop the whole program, use @code{interrupt -a}. + +Other execution commands do not currently support the @code{-a} option. + +In non-stop mode, when a thread stops, @value{GDBN} doesn't automatically make +that thread current, as it does in all-stop mode. This is because the +thread stop notifications are asynchronous with respect to @value{GDBN}'s +command interpreter, and it would be confusing if @value{GDBN} unexpectedly +changed to a different thread just as you entered a command to operate on the +previously current thread. + +@node Background Execution +@subsection Background Execution + +@cindex foreground execution +@cindex background execution +@cindex asynchronous execution +@cindex execution, foreground, background and asynchronous + +@value{GDBN}'s execution commands have two variants: the normal +foreground (synchronous) behavior, and a background +(asynchronous) behavior. In foreground execution, @value{GDBN} waits for +the program to report that some thread has stopped before prompting for +another command. In background execution, @value{GDBN} immediately gives +a command prompt so that you can issue other commands while your program runs. + +If the target doesn't support async mode, @value{GDBN} issues an error +message if you attempt to use the background execution commands. + +@cindex @code{&}, background execution of commands +To specify background execution, add a @code{&} to the command. For example, +the background form of the @code{continue} command is @code{continue&}, or +just @code{c&}. The execution commands that accept background execution +are: + +@table @code +@kindex run& +@item run +@xref{Starting, , Starting your Program}. + +@item attach +@kindex attach& +@xref{Attach, , Debugging an Already-running Process}. + +@item step +@kindex step& +@xref{Continuing and Stepping, step}. + +@item stepi +@kindex stepi& +@xref{Continuing and Stepping, stepi}. + +@item next +@kindex next& +@xref{Continuing and Stepping, next}. + +@item nexti +@kindex nexti& +@xref{Continuing and Stepping, nexti}. + +@item continue +@kindex continue& +@xref{Continuing and Stepping, continue}. + +@item finish +@kindex finish& +@xref{Continuing and Stepping, finish}. + +@item until +@kindex until& +@xref{Continuing and Stepping, until}. + +@end table + +Background execution is especially useful in conjunction with non-stop +mode for debugging programs with multiple threads; see @ref{Non-Stop Mode}. +However, you can also use these commands in the normal all-stop mode with +the restriction that you cannot issue another execution command until the +previous one finishes. Examples of commands that are valid in all-stop +mode while the program is running include @code{help} and @code{info break}. + +You can interrupt your program while it is running in the background by +using the @code{interrupt} command. + +@table @code +@kindex interrupt +@item interrupt +@itemx interrupt -a + +Suspend execution of the running program. In all-stop mode, +@code{interrupt} stops the whole process, but in non-stop mode, it stops +only the current thread. To stop the whole program in non-stop mode, +use @code{interrupt -a}. +@end table + +@node Thread-Specific Breakpoints +@subsection Thread-Specific Breakpoints + +When your program has multiple threads (@pxref{Threads,, Debugging +Programs with Multiple Threads}), you can choose whether to set +breakpoints on all threads, or on a particular thread. + +@table @code +@cindex breakpoints and threads +@cindex thread breakpoints +@kindex break @dots{} thread @var{thread-id} +@item break @var{locspec} thread @var{thread-id} +@itemx break @var{locspec} thread @var{thread-id} if @dots{} +@var{locspec} specifies a code location or locations in your program. +@xref{Location Specifications}, for details. + +Use the qualifier @samp{thread @var{thread-id}} with a breakpoint command +to specify that you only want @value{GDBN} to stop the program when a +particular thread reaches this breakpoint. The @var{thread-id} specifier +is one of the thread identifiers assigned by @value{GDBN}, shown +in the first column of the @samp{info threads} display. + +If you do not specify @samp{thread @var{thread-id}} when you set a +breakpoint, the breakpoint applies to @emph{all} threads of your +program. + +You can use the @code{thread} qualifier on conditional breakpoints as +well; in this case, place @samp{thread @var{thread-id}} before or +after the breakpoint condition, like this: + +@smallexample +(@value{GDBP}) break frik.c:13 thread 28 if bartab > lim +@end smallexample + +@end table + +Thread-specific breakpoints are automatically deleted when +@value{GDBN} detects the corresponding thread is no longer in the +thread list. For example: + +@smallexample +(@value{GDBP}) c +Thread-specific breakpoint 3 deleted - thread 28 no longer in the thread list. +@end smallexample + +There are several ways for a thread to disappear, such as a regular +thread exit, but also when you detach from the process with the +@code{detach} command (@pxref{Attach, ,Debugging an Already-running +Process}), or if @value{GDBN} loses the remote connection +(@pxref{Remote Debugging}), etc. Note that with some targets, +@value{GDBN} is only able to detect a thread has exited when the user +explicitly asks for the thread list with the @code{info threads} +command. + +A breakpoint can't be both thread-specific and inferior-specific +(@pxref{Inferior-Specific Breakpoints}), or task-specific (@pxref{Ada +Tasks}); using more than one of the @code{thread}, @code{inferior}, or +@code{task} keywords when creating a breakpoint will give an error. + +@node Interrupted System Calls +@subsection Interrupted System Calls + +@cindex thread breakpoints and system calls +@cindex system calls and thread breakpoints +@cindex premature return from system calls +There is an unfortunate side effect when using @value{GDBN} to debug +multi-threaded programs. If one thread stops for a +breakpoint, or for some other reason, and another thread is blocked in a +system call, then the system call may return prematurely. This is a +consequence of the interaction between multiple threads and the signals +that @value{GDBN} uses to implement breakpoints and other events that +stop execution. + +To handle this problem, your program should check the return value of +each system call and react appropriately. This is good programming +style anyways. + +For example, do not write code like this: + +@smallexample + sleep (10); +@end smallexample + +The call to @code{sleep} will return early if a different thread stops +at a breakpoint or for some other reason. + +Instead, write this: + +@smallexample + int unslept = 10; + while (unslept > 0) + unslept = sleep (unslept); +@end smallexample + +A system call is allowed to return early, so the system is still +conforming to its specification. But @value{GDBN} does cause your +multi-threaded program to behave differently than it would without +@value{GDBN}. + +Also, @value{GDBN} uses internal breakpoints in the thread library to +monitor certain events such as thread creation and thread destruction. +When such an event happens, a system call in another thread may return +prematurely, even though your program does not appear to stop. + +@node Observer Mode +@subsection Observer Mode + +If you want to build on non-stop mode and observe program behavior +without any chance of disruption by @value{GDBN}, you can set +variables to disable all of the debugger's attempts to modify state, +whether by writing memory, inserting breakpoints, etc. These operate +at a low level, intercepting operations from all commands. + +When all of these are set to @code{off}, then @value{GDBN} is said to +be @dfn{observer mode}. As a convenience, the variable +@code{observer} can be set to disable these, plus enable non-stop +mode. + +Note that @value{GDBN} will not prevent you from making nonsensical +combinations of these settings. For instance, if you have enabled +@code{may-insert-breakpoints} but disabled @code{may-write-memory}, +then breakpoints that work by writing trap instructions into the code +stream will still not be able to be placed. + +@table @code + +@kindex observer +@item set observer on +@itemx set observer off +When set to @code{on}, this disables all the permission variables +below (except for @code{insert-fast-tracepoints}), plus enables +non-stop debugging. Setting this to @code{off} switches back to +normal debugging, though remaining in non-stop mode. + +@item show observer +Show whether observer mode is on or off. + +@kindex may-write-registers +@item set may-write-registers on +@itemx set may-write-registers off +This controls whether @value{GDBN} will attempt to alter the values of +registers, such as with assignment expressions in @code{print}, or the +@code{jump} command. It defaults to @code{on}. + +@item show may-write-registers +Show the current permission to write registers. + +@kindex may-write-memory +@item set may-write-memory on +@itemx set may-write-memory off +This controls whether @value{GDBN} will attempt to alter the contents +of memory, such as with assignment expressions in @code{print}. It +defaults to @code{on}. + +@item show may-write-memory +Show the current permission to write memory. + +@kindex may-insert-breakpoints +@item set may-insert-breakpoints on +@itemx set may-insert-breakpoints off +This controls whether @value{GDBN} will attempt to insert breakpoints. +This affects all breakpoints, including internal breakpoints defined +by @value{GDBN}. It defaults to @code{on}. + +@item show may-insert-breakpoints +Show the current permission to insert breakpoints. + +@kindex may-insert-tracepoints +@item set may-insert-tracepoints on +@itemx set may-insert-tracepoints off +This controls whether @value{GDBN} will attempt to insert (regular) +tracepoints at the beginning of a tracing experiment. It affects only +non-fast tracepoints, fast tracepoints being under the control of +@code{may-insert-fast-tracepoints}. It defaults to @code{on}. + +@item show may-insert-tracepoints +Show the current permission to insert tracepoints. + +@kindex may-insert-fast-tracepoints +@item set may-insert-fast-tracepoints on +@itemx set may-insert-fast-tracepoints off +This controls whether @value{GDBN} will attempt to insert fast +tracepoints at the beginning of a tracing experiment. It affects only +fast tracepoints, regular (non-fast) tracepoints being under the +control of @code{may-insert-tracepoints}. It defaults to @code{on}. + +@item show may-insert-fast-tracepoints +Show the current permission to insert fast tracepoints. + +@kindex may-interrupt +@item set may-interrupt on +@itemx set may-interrupt off +This controls whether @value{GDBN} will attempt to interrupt or stop +program execution. When this variable is @code{off}, the +@code{interrupt} command will have no effect, nor will +@kbd{Ctrl-c}. It defaults to @code{on}. + +@item show may-interrupt +Show the current permission to interrupt or stop the program. + +@end table + +@node Reverse Execution +@chapter Running programs backward +@cindex reverse execution +@cindex running programs backward + +When you are debugging a program, it is not unusual to realize that +you have gone too far, and some event of interest has already happened. +If the target environment supports it, @value{GDBN} can allow you to +``rewind'' the program by running it backward. + +A target environment that supports reverse execution should be able +to ``undo'' the changes in machine state that have taken place as the +program was executing normally. Variables, registers etc.@: should +revert to their previous values. Obviously this requires a great +deal of sophistication on the part of the target environment; not +all target environments can support reverse execution. + +When a program is executed in reverse, the instructions that +have most recently been executed are ``un-executed'', in reverse +order. The program counter runs backward, following the previous +thread of execution in reverse. As each instruction is ``un-executed'', +the values of memory and/or registers that were changed by that +instruction are reverted to their previous states. After executing +a piece of source code in reverse, all side effects of that code +should be ``undone'', and all variables should be returned to their +prior values@footnote{ +Note that some side effects are easier to undo than others. For instance, +memory and registers are relatively easy, but device I/O is hard. Some +targets may be able undo things like device I/O, and some may not. + +The contract between @value{GDBN} and the reverse executing target +requires only that the target do something reasonable when +@value{GDBN} tells it to execute backwards, and then report the +results back to @value{GDBN}. Whatever the target reports back to +@value{GDBN}, @value{GDBN} will report back to the user. @value{GDBN} +assumes that the memory and registers that the target reports are in a +consistent state, but @value{GDBN} accepts whatever it is given. +}. + +On some platforms, @value{GDBN} has built-in support for reverse +execution, activated with the @code{record} or @code{record btrace} +commands. @xref{Process Record and Replay}. Some remote targets, +typically full system emulators, support reverse execution directly +without requiring any special command. + +If you are debugging in a target environment that supports +reverse execution, @value{GDBN} provides the following commands. + +@table @code +@kindex reverse-continue +@kindex rc @r{(@code{reverse-continue})} +@item reverse-continue @r{[}@var{ignore-count}@r{]} +@itemx rc @r{[}@var{ignore-count}@r{]} +Beginning at the point where your program last stopped, start executing +in reverse. Reverse execution will stop for breakpoints and synchronous +exceptions (signals), just like normal execution. Behavior of +asynchronous signals depends on the target environment. + +@kindex reverse-step +@kindex rs @r{(@code{step})} +@item reverse-step @r{[}@var{count}@r{]} +Run the program backward until control reaches the start of a +different source line; then stop it, and return control to @value{GDBN}. + +Like the @code{step} command, @code{reverse-step} will only stop +at the beginning of a source line. It ``un-executes'' the previously +executed source line. If the previous source line included calls to +debuggable functions, @code{reverse-step} will step (backward) into +the called function, stopping at the beginning of the @emph{last} +statement in the called function (typically a return statement). + +Also, as with the @code{step} command, if non-debuggable functions are +called, @code{reverse-step} will run through them backward without stopping. + +@kindex reverse-stepi +@kindex rsi @r{(@code{reverse-stepi})} +@item reverse-stepi @r{[}@var{count}@r{]} +Reverse-execute one machine instruction. Note that the instruction +to be reverse-executed is @emph{not} the one pointed to by the program +counter, but the instruction executed prior to that one. For instance, +if the last instruction was a jump, @code{reverse-stepi} will take you +back from the destination of the jump to the jump instruction itself. + +@kindex reverse-next +@kindex rn @r{(@code{reverse-next})} +@item reverse-next @r{[}@var{count}@r{]} +Run backward to the beginning of the previous line executed in +the current (innermost) stack frame. If the line contains function +calls, they will be ``un-executed'' without stopping. Starting from +the first line of a function, @code{reverse-next} will take you back +to the caller of that function, @emph{before} the function was called, +just as the normal @code{next} command would take you from the last +line of a function back to its return to its caller +@footnote{Unless the code is too heavily optimized.}. + +@kindex reverse-nexti +@kindex rni @r{(@code{reverse-nexti})} +@item reverse-nexti @r{[}@var{count}@r{]} +Like @code{nexti}, @code{reverse-nexti} executes a single instruction +in reverse, except that called functions are ``un-executed'' atomically. +That is, if the previously executed instruction was a return from +another function, @code{reverse-nexti} will continue to execute +in reverse until the call to that function (from the current stack +frame) is reached. + +@kindex reverse-finish +@item reverse-finish +Just as the @code{finish} command takes you to the point where the +current function returns, @code{reverse-finish} takes you to the point +where it was called. Instead of ending up at the end of the current +function invocation, you end up at the beginning. + +@kindex set exec-direction +@item set exec-direction +Set the direction of target execution. +@item set exec-direction reverse +@cindex execute forward or backward in time +@value{GDBN} will perform all execution commands in reverse, until the +exec-direction mode is changed to ``forward''. Affected commands include +@code{step, stepi, next, nexti, continue, and finish}. The @code{return} +command cannot be used in reverse mode. +@item set exec-direction forward +@value{GDBN} will perform all execution commands in the normal fashion. +This is the default. +@end table + + +@node Process Record and Replay +@chapter Recording Inferior's Execution and Replaying It +@cindex process record and replay +@cindex recording inferior's execution and replaying it + +On some platforms, @value{GDBN} provides a special @dfn{process record +and replay} target that can record a log of the process execution, and +replay it later with both forward and reverse execution commands. + +@cindex replay mode +When this target is in use, if the execution log includes the record +for the next instruction, @value{GDBN} will debug in @dfn{replay +mode}. In the replay mode, the inferior does not really execute code +instructions. Instead, all the events that normally happen during +code execution are taken from the execution log. While code is not +really executed in replay mode, the values of registers (including the +program counter register) and the memory of the inferior are still +changed as they normally would. Their contents are taken from the +execution log. + +@cindex record mode +If the record for the next instruction is not in the execution log, +@value{GDBN} will debug in @dfn{record mode}. In this mode, the +inferior executes normally, and @value{GDBN} records the execution log +for future replay. + +The process record and replay target supports reverse execution +(@pxref{Reverse Execution}), even if the platform on which the +inferior runs does not. However, the reverse execution is limited in +this case by the range of the instructions recorded in the execution +log. In other words, reverse execution on platforms that don't +support it directly can only be done in the replay mode. + +When debugging in the reverse direction, @value{GDBN} will work in +replay mode as long as the execution log includes the record for the +previous instruction; otherwise, it will work in record mode, if the +platform supports reverse execution, or stop if not. + +Currently, process record and replay is supported on ARM, Aarch64, +LoongArch, Moxie, PowerPC, PowerPC64, S/390, and x86 (i386/amd64) running +GNU/Linux. Process record and replay can be used both when native +debugging, and when remote debugging via @code{gdbserver}. + +When recording an inferior, @value{GDBN} may print auxiliary information +during stepping commands and commands displaying the execution history. + +For architecture environments that support process record and replay, +@value{GDBN} provides the following commands: + +@table @code +@kindex target record +@kindex target record-full +@kindex target record-btrace +@kindex record +@kindex record full +@kindex record btrace +@kindex record btrace bts +@kindex record btrace pt +@kindex record bts +@kindex record pt +@kindex rec +@kindex rec full +@kindex rec btrace +@kindex rec btrace bts +@kindex rec btrace pt +@kindex rec bts +@kindex rec pt +@item record @var{method} +This command starts the process record and replay target. The +recording method can be specified as parameter. Without a parameter +the command uses the @code{full} recording method. The following +recording methods are available: + +@table @code +@item full +Full record/replay recording using @value{GDBN}'s software record and +replay implementation. This method allows replaying and reverse +execution. + +@item btrace @var{format} +Hardware-supported instruction recording, supported on Intel +processors. This method does not record data. Further, the data is +collected in a ring buffer so old data will be overwritten when the +buffer is full. It allows limited reverse execution. Variables and +registers are not available during reverse execution. In remote +debugging, recording continues on disconnect. Recorded data can be +inspected after reconnecting. The recording may be stopped using +@code{record stop}. + +The recording format can be specified as parameter. Without a parameter +the command chooses the recording format. The following recording +formats are available: + +@table @code +@item bts +@cindex branch trace store +Use the @dfn{Branch Trace Store} (@acronym{BTS}) recording format. In +this format, the processor stores a from/to record for each executed +branch in the btrace ring buffer. + +@item pt +@cindex Intel Processor Trace +Use the @dfn{Intel Processor Trace} recording format. In this +format, the processor stores the execution trace in a compressed form +that is afterwards decoded by @value{GDBN}. + +The trace can be recorded with very low overhead. The compressed +trace format also allows small trace buffers to already contain a big +number of instructions compared to @acronym{BTS}. + +Decoding the recorded execution trace, on the other hand, is more +expensive than decoding @acronym{BTS} trace. This is mostly due to the +increased number of instructions to process. You should increase the +buffer-size with care. +@end table + +Not all recording formats may be available on all processors. +@end table + +The process record and replay target can only debug a process that is +already running. Therefore, you need first to start the process with +the @kbd{run} or @kbd{start} commands, and then start the recording +with the @kbd{record @var{method}} command. + +@cindex displaced stepping, and process record and replay +Displaced stepping (@pxref{Maintenance Commands,, displaced stepping}) +will be automatically disabled when process record and replay target +is started. That's because the process record and replay target +doesn't support displaced stepping. + +@cindex non-stop mode, and process record and replay +@cindex asynchronous execution, and process record and replay +If the inferior is in the non-stop mode (@pxref{Non-Stop Mode}) or in +the asynchronous execution mode (@pxref{Background Execution}), not +all recording methods are available. The @code{full} recording method +does not support these two modes. + +@kindex record stop +@kindex rec s +@item record stop +Stop the process record and replay target. When process record and +replay target stops, the entire execution log will be deleted and the +inferior will either be terminated, or will remain in its final state. + +When you stop the process record and replay target in record mode (at +the end of the execution log), the inferior will be stopped at the +next instruction that would have been recorded. In other words, if +you record for a while and then stop recording, the inferior process +will be left in the same state as if the recording never happened. + +On the other hand, if the process record and replay target is stopped +while in replay mode (that is, not at the end of the execution log, +but at some earlier point), the inferior process will become ``live'' +at that earlier state, and it will then be possible to continue the +usual ``live'' debugging of the process from that state. + +When the inferior process exits, or @value{GDBN} detaches from it, +process record and replay target will automatically stop itself. + +@kindex record goto +@item record goto +Go to a specific location in the execution log. There are several +ways to specify the location to go to: + +@table @code +@item record goto begin +@itemx record goto start +Go to the beginning of the execution log. + +@item record goto end +Go to the end of the execution log. + +@item record goto @var{n} +Go to instruction number @var{n} in the execution log. +@end table + +@kindex record save +@item record save @var{filename} +Save the execution log to a file @file{@var{filename}}. +Default filename is @file{gdb_record.@var{process_id}}, where +@var{process_id} is the process ID of the inferior. + +This command may not be available for all recording methods. + +@kindex record restore +@item record restore @var{filename} +Restore the execution log from a file @file{@var{filename}}. +File must have been created with @code{record save}. + +@kindex set record full +@item set record full insn-number-max @var{limit} +@itemx set record full insn-number-max unlimited +Set the limit of instructions to be recorded for the @code{full} +recording method. Default value is 200000. + +If @var{limit} is a positive number, then @value{GDBN} will start +deleting instructions from the log once the number of the record +instructions becomes greater than @var{limit}. For every new recorded +instruction, @value{GDBN} will delete the earliest recorded +instruction to keep the number of recorded instructions at the limit. +(Since deleting recorded instructions loses information, @value{GDBN} +lets you control what happens when the limit is reached, by means of +the @code{stop-at-limit} option, described below.) + +If @var{limit} is @code{unlimited} or zero, @value{GDBN} will never +delete recorded instructions from the execution log. The number of +recorded instructions is limited only by the available memory. + +@kindex show record full +@item show record full insn-number-max +Show the limit of instructions to be recorded with the @code{full} +recording method. + +@item set record full stop-at-limit +Control the behavior of the @code{full} recording method when the +number of recorded instructions reaches the limit. If ON (the +default), @value{GDBN} will stop when the limit is reached for the +first time and ask you whether you want to stop the inferior or +continue running it and recording the execution log. If you decide +to continue recording, each new recorded instruction will cause the +oldest one to be deleted. + +If this option is OFF, @value{GDBN} will automatically delete the +oldest record to make room for each new one, without asking. + +@item show record full stop-at-limit +Show the current setting of @code{stop-at-limit}. + +@item set record full memory-query +Control the behavior when @value{GDBN} is unable to record memory +changes caused by an instruction for the @code{full} recording method. +If ON, @value{GDBN} will query whether to stop the inferior in that +case. + +If this option is OFF (the default), @value{GDBN} will automatically +ignore the effect of such instructions on memory. Later, when +@value{GDBN} replays this execution log, it will mark the log of this +instruction as not accessible, and it will not affect the replay +results. + +@item show record full memory-query +Show the current setting of @code{memory-query}. + +@kindex set record btrace +The @code{btrace} record target does not trace data. As a +convenience, when replaying, @value{GDBN} reads read-only memory off +the live program directly, assuming that the addresses of the +read-only areas don't change. This for example makes it possible to +disassemble code while replaying, but not to print variables. +In some cases, being able to inspect variables might be useful. +You can use the following command for that: + +@item set record btrace replay-memory-access +Control the behavior of the @code{btrace} recording method when +accessing memory during replay. If @code{read-only} (the default), +@value{GDBN} will only allow accesses to read-only memory. +If @code{read-write}, @value{GDBN} will allow accesses to read-only +and to read-write memory. Beware that the accessed memory corresponds +to the live target and not necessarily to the current replay +position. + +@item set record btrace cpu @var{identifier} +Set the processor to be used for enabling workarounds for processor +errata when decoding the trace. + +Processor errata are defects in processor operation, caused by its +design or manufacture. They can cause a trace not to match the +specification. This, in turn, may cause trace decode to fail. +@value{GDBN} can detect erroneous trace packets and correct them, thus +avoiding the decoding failures. These corrections are known as +@dfn{errata workarounds}, and are enabled based on the processor on +which the trace was recorded. + +By default, @value{GDBN} attempts to detect the processor +automatically, and apply the necessary workarounds for it. However, +you may need to specify the processor if @value{GDBN} does not yet +support it. This command allows you to do that, and also allows to +disable the workarounds. + +The argument @var{identifier} identifies the @sc{cpu} and is of the +form: @code{@var{vendor}:@var{processor identifier}}. In addition, +there are two special identifiers, @code{none} and @code{auto} +(default). + +The following vendor identifiers and corresponding processor +identifiers are currently supported: + +@multitable @columnfractions .1 .9 + +@item @code{intel} +@tab @var{family}/@var{model}[/@var{stepping}] + +@end multitable + +On GNU/Linux systems, the processor @var{family}, @var{model}, and +@var{stepping} can be obtained from @code{/proc/cpuinfo}. + +If @var{identifier} is @code{auto}, enable errata workarounds for the +processor on which the trace was recorded. If @var{identifier} is +@code{none}, errata workarounds are disabled. + +For example, when using an old @value{GDBN} on a new system, decode +may fail because @value{GDBN} does not support the new processor. It +often suffices to specify an older processor that @value{GDBN} +supports. + +@smallexample +(@value{GDBP}) info record +Active record target: record-btrace +Recording format: Intel Processor Trace. +Buffer size: 16kB. +Failed to configure the Intel Processor Trace decoder: unknown cpu. +(@value{GDBP}) set record btrace cpu intel:6/158 +(@value{GDBP}) info record +Active record target: record-btrace +Recording format: Intel Processor Trace. +Buffer size: 16kB. +Recorded 84872 instructions in 3189 functions (0 gaps) for thread 1 (...). +@end smallexample + +@kindex show record btrace +@item show record btrace replay-memory-access +Show the current setting of @code{replay-memory-access}. + +@item show record btrace cpu +Show the processor to be used for enabling trace decode errata +workarounds. + +@kindex set record btrace bts +@item set record btrace bts buffer-size @var{size} +@itemx set record btrace bts buffer-size unlimited +Set the requested ring buffer size for branch tracing in @acronym{BTS} +format. Default is 64KB. + +If @var{size} is a positive number, then @value{GDBN} will try to +allocate a buffer of at least @var{size} bytes for each new thread +that uses the btrace recording method and the @acronym{BTS} format. +The actually obtained buffer size may differ from the requested +@var{size}. Use the @code{info record} command to see the actual +buffer size for each thread that uses the btrace recording method and +the @acronym{BTS} format. + +If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to +allocate a buffer of 4MB. + +Bigger buffers mean longer traces. On the other hand, @value{GDBN} will +also need longer to process the branch trace data before it can be used. + +@item show record btrace bts buffer-size @var{size} +Show the current setting of the requested ring buffer size for branch +tracing in @acronym{BTS} format. + +@kindex set record btrace pt +@item set record btrace pt buffer-size @var{size} +@itemx set record btrace pt buffer-size unlimited +Set the requested ring buffer size for branch tracing in Intel +Processor Trace format. Default is 16KB. + +If @var{size} is a positive number, then @value{GDBN} will try to +allocate a buffer of at least @var{size} bytes for each new thread +that uses the btrace recording method and the Intel Processor Trace +format. The actually obtained buffer size may differ from the +requested @var{size}. Use the @code{info record} command to see the +actual buffer size for each thread. + +If @var{limit} is @code{unlimited} or zero, @value{GDBN} will try to +allocate a buffer of 4MB. + +Bigger buffers mean longer traces. On the other hand, @value{GDBN} will +also need longer to process the branch trace data before it can be used. + +@item show record btrace pt buffer-size @var{size} +Show the current setting of the requested ring buffer size for branch +tracing in Intel Processor Trace format. + +@item set record btrace pt event-tracing +Enable or disable event tracing for branch tracing in Intel Processor +Trace format. When enabled, events are recorded during execution as +auxiliary information and will be printed during stepping commands and +commands displaying the execution history. Changing this setting has no +effect on an active recording. The default is off. + +@item show record btrace pt event-tracing +Show the current setting of Intel Processor Trace event tracing. + +@kindex info record +@item info record +Show various statistics about the recording depending on the recording +method: + +@table @code +@item full +For the @code{full} recording method, it shows the state of process +record and its in-memory execution log buffer, including: + +@itemize @bullet +@item +Whether in record mode or replay mode. +@item +Lowest recorded instruction number (counting from when the current execution log started recording instructions). +@item +Highest recorded instruction number. +@item +Current instruction about to be replayed (if in replay mode). +@item +Number of instructions contained in the execution log. +@item +Maximum number of instructions that may be contained in the execution log. +@end itemize + +@item btrace +For the @code{btrace} recording method, it shows: + +@itemize @bullet +@item +Recording format. +@item +Number of instructions that have been recorded. +@item +Number of blocks of sequential control-flow formed by the recorded +instructions. +@item +Whether in record mode or replay mode. +@end itemize + +For the @code{bts} recording format, it also shows: +@itemize @bullet +@item +Size of the perf ring buffer. +@end itemize + +For the @code{pt} recording format, it also shows: +@itemize @bullet +@item +Size of the perf ring buffer. +@end itemize +@end table + +@kindex record delete +@kindex rec del +@item record delete +When record target runs in replay mode (``in the past''), delete the +subsequent execution log and begin to record a new execution log starting +from the current address. This means you will abandon the previously +recorded ``future'' and begin recording a new ``future''. + +@kindex record instruction-history +@kindex rec instruction-history +@item record instruction-history +Disassembles instructions from the recorded execution log. By +default, ten instructions are disassembled. This can be changed using +the @code{set record instruction-history-size} command. Instructions +are printed in execution order. + +It can also print mixed source+disassembly if you specify the the +@code{/m} or @code{/s} modifier, and print the raw instructions in hex +as well as in symbolic form by specifying the @code{/r} or @code{/b} +modifier. The behavior of the @code{/m}, @code{/s}, @code{/r}, and +@code{/b} modifiers are the same as for the @kbd{disassemble} command +(@pxref{disassemble,,@kbd{disassemble}}). + +The current position marker is printed for the instruction at the +current program counter value. This instruction can appear multiple +times in the trace and the current position marker will be printed +every time. To omit the current position marker, specify the +@code{/p} modifier. + +To better align the printed instructions when the trace contains +instructions from more than one function, the function name may be +omitted by specifying the @code{/f} modifier. + +Printing auxiliary information is enabled by default and can be +omitted with the @code{/a} modifier. + +Speculatively executed instructions are prefixed with @samp{?}. This +feature is not available for all recording formats. + +There are several ways to specify what part of the execution log to +disassemble: + +@table @code +@item record instruction-history @var{insn} +Disassembles ten instructions starting from instruction number +@var{insn}. + +@item record instruction-history @var{insn}, +/-@var{n} +Disassembles @var{n} instructions around instruction number +@var{insn}. If @var{n} is preceded with @code{+}, disassembles +@var{n} instructions after instruction number @var{insn}. If +@var{n} is preceded with @code{-}, disassembles @var{n} +instructions before instruction number @var{insn}. + +@item record instruction-history +Disassembles ten more instructions after the last disassembly. + +@item record instruction-history - +Disassembles ten more instructions before the last disassembly. + +@item record instruction-history @var{begin}, @var{end} +Disassembles instructions beginning with instruction number +@var{begin} until instruction number @var{end}. The instruction +number @var{end} is included. +@end table + +This command may not be available for all recording methods. + +@kindex set record +@item set record instruction-history-size @var{size} +@itemx set record instruction-history-size unlimited +Define how many instructions to disassemble in the @code{record +instruction-history} command. The default value is 10. +A @var{size} of @code{unlimited} means unlimited instructions. + +@kindex show record +@item show record instruction-history-size +Show how many instructions to disassemble in the @code{record +instruction-history} command. + +@kindex record function-call-history +@kindex rec function-call-history +@item record function-call-history +Prints the execution history at function granularity. For each sequence +of instructions that belong to the same function, it prints the name of +that function, the source lines for this instruction sequence (if the +@code{/l} modifier is specified), and the instructions numbers that form +the sequence (if the @code{/i} modifier is specified). The function names +are indented to reflect the call stack depth if the @code{/c} modifier is +specified. Printing auxiliary information is enabled by default and can be +omitted with the @code{/a} modifier. The @code{/l}, @code{/i}, @code{/a}, +and @code{/c} modifiers can be given together. + +@smallexample +(@value{GDBP}) @b{list 1, 10} +1 void foo (void) +2 @{ +3 @} +4 +5 void bar (void) +6 @{ +7 ... +8 foo (); +9 ... +10 @} +(@value{GDBP}) @b{record function-call-history /ilc} +1 bar inst 1,4 at foo.c:6,8 +2 foo inst 5,10 at foo.c:2,3 +3 bar inst 11,13 at foo.c:9,10 +@end smallexample + +By default, ten functions are printed. This can be changed using the +@code{set record function-call-history-size} command. Functions are +printed in execution order. There are several ways to specify what +to print: + +@table @code +@item record function-call-history @var{func} +Prints ten functions starting from function number @var{func}. + +@item record function-call-history @var{func}, +/-@var{n} +Prints @var{n} functions around function number @var{func}. If +@var{n} is preceded with @code{+}, prints @var{n} functions after +function number @var{func}. If @var{n} is preceded with @code{-}, +prints @var{n} functions before function number @var{func}. + +@item record function-call-history +Prints ten more functions after the last ten-function print. + +@item record function-call-history - +Prints ten more functions before the last ten-function print. + +@item record function-call-history @var{begin}, @var{end} +Prints functions beginning with function number @var{begin} until +function number @var{end}. The function number @var{end} is included. +@end table + +This command may not be available for all recording methods. + +@item set record function-call-history-size @var{size} +@itemx set record function-call-history-size unlimited +Define how many functions to print in the +@code{record function-call-history} command. The default value is 10. +A size of @code{unlimited} means unlimited functions. + +@item show record function-call-history-size +Show how many functions to print in the +@code{record function-call-history} command. +@end table + + +@node Stack +@chapter Examining the Stack + +When your program has stopped, the first thing you need to know is where it +stopped and how it got there. + +@cindex call stack +Each time your program performs a function call, information about the call +is generated. +That information includes the location of the call in your program, +the arguments of the call, +and the local variables of the function being called. +The information is saved in a block of data called a @dfn{stack frame}. +The stack frames are allocated in a region of memory called the @dfn{call +stack}. + +When your program stops, the @value{GDBN} commands for examining the +stack allow you to see all of this information. + +@cindex selected frame +One of the stack frames is @dfn{selected} by @value{GDBN} and many +@value{GDBN} commands refer implicitly to the selected frame. In +particular, whenever you ask @value{GDBN} for the value of a variable in +your program, the value is found in the selected frame. There are +special @value{GDBN} commands to select whichever frame you are +interested in. @xref{Selection, ,Selecting a Frame}. + +When your program stops, @value{GDBN} automatically selects the +currently executing frame and describes it briefly, similar to the +@code{frame} command (@pxref{Frame Info, ,Information about a Frame}). + +@menu +* Frames:: Stack frames +* Backtrace:: Backtraces +* Selection:: Selecting a frame +* Frame Info:: Information on a frame +* Frame Apply:: Applying a command to several frames +* Frame Filter Management:: Managing frame filters + +@end menu + +@node Frames +@section Stack Frames + +@cindex frame, definition +@cindex stack frame +The call stack is divided up into contiguous pieces called @dfn{stack +frames}, or @dfn{frames} for short; each frame is the data associated +with one call to one function. The frame contains the arguments given +to the function, the function's local variables, and the address at +which the function is executing. + +@cindex initial frame +@cindex outermost frame +@cindex innermost frame +When your program is started, the stack has only one frame, that of the +function @code{main}. This is called the @dfn{initial} frame or the +@dfn{outermost} frame. Each time a function is called, a new frame is +made. Each time a function returns, the frame for that function invocation +is eliminated. If a function is recursive, there can be many frames for +the same function. The frame for the function in which execution is +actually occurring is called the @dfn{innermost} frame. This is the most +recently created of all the stack frames that still exist. + +@cindex frame pointer +Inside your program, stack frames are identified by their addresses. A +stack frame consists of many bytes, each of which has its own address; each +kind of computer has a convention for choosing one byte whose +address serves as the address of the frame. Usually this address is kept +in a register called the @dfn{frame pointer register} +(@pxref{Registers, $fp}) while execution is going on in that frame. + +@cindex frame level +@cindex frame number +@value{GDBN} labels each existing stack frame with a @dfn{level}, a +number that is zero for the innermost frame, one for the frame that +called it, and so on upward. These level numbers give you a way of +designating stack frames in @value{GDBN} commands. The terms +@dfn{frame number} and @dfn{frame level} can be used interchangeably to +describe this number. + +@c The -fomit-frame-pointer below perennially causes hbox overflow +@c underflow problems. +@cindex frameless execution +Some compilers provide a way to compile functions so that they operate +without stack frames. (For example, the @value{NGCC} option +@smallexample +@samp{-fomit-frame-pointer} +@end smallexample +generates functions without a frame.) +This is occasionally done with heavily used library functions to save +the frame setup time. @value{GDBN} has limited facilities for dealing +with these function invocations. If the innermost function invocation +has no stack frame, @value{GDBN} nevertheless regards it as though +it had a separate frame, which is numbered zero as usual, allowing +correct tracing of the function call chain. However, @value{GDBN} has +no provision for frameless functions elsewhere in the stack. + +@node Backtrace +@section Backtraces + +@cindex traceback +@cindex call stack traces +A backtrace is a summary of how your program got where it is. It shows one +line per frame, for many frames, starting with the currently executing +frame (frame zero), followed by its caller (frame one), and on up the +stack. + +@anchor{backtrace-command} +@kindex backtrace +@kindex bt @r{(@code{backtrace})} +To print a backtrace of the entire stack, use the @code{backtrace} +command, or its alias @code{bt}. This command will print one line per +frame for frames in the stack. By default, all stack frames are +printed. You can stop the backtrace at any time by typing the system +interrupt character, normally @kbd{Ctrl-c}. + +@table @code +@item backtrace [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] +@itemx bt [@var{option}]@dots{} [@var{qualifier}]@dots{} [@var{count}] +Print the backtrace of the entire stack. + +The optional @var{count} can be one of the following: + +@table @code +@item @var{n} +@itemx @var{n} +Print only the innermost @var{n} frames, where @var{n} is a positive +number. + +@item -@var{n} +@itemx -@var{n} +Print only the outermost @var{n} frames, where @var{n} is a positive +number. +@end table + +Options: + +@table @code +@item -full +Print the values of the local variables also. This can be combined +with the optional @var{count} to limit the number of frames shown. + +@item -no-filters +Do not run Python frame filters on this backtrace. @xref{Frame +Filter API}, for more information. Additionally use @ref{disable +frame-filter all} to turn off all frame filters. This is only +relevant when @value{GDBN} has been configured with @code{Python} +support. + +@item -hide +A Python frame filter might decide to ``elide'' some frames. Normally +such elided frames are still printed, but they are indented relative +to the filtered frames that cause them to be elided. The @code{-hide} +option causes elided frames to not be printed at all. +@end table + +The @code{backtrace} command also supports a number of options that +allow overriding relevant global print settings as set by @code{set +backtrace} and @code{set print} subcommands: + +@table @code +@item -past-main [@code{on}|@code{off}] +Set whether backtraces should continue past @code{main}. Related setting: +@ref{set backtrace past-main}. + +@item -past-entry [@code{on}|@code{off}] +Set whether backtraces should continue past the entry point of a program. +Related setting: @ref{set backtrace past-entry}. + +@item -entry-values @code{no}|@code{only}|@code{preferred}|@code{if-needed}|@code{both}|@code{compact}|@code{default} +Set printing of function arguments at function entry. +Related setting: @ref{set print entry-values}. + +@item -frame-arguments @code{all}|@code{scalars}|@code{none} +Set printing of non-scalar frame arguments. +Related setting: @ref{set print frame-arguments}. + +@item -raw-frame-arguments [@code{on}|@code{off}] +Set whether to print frame arguments in raw form. +Related setting: @ref{set print raw-frame-arguments}. + +@item -frame-info @code{auto}|@code{source-line}|@code{location}|@code{source-and-location}|@code{location-and-address}|@code{short-location} +Set printing of frame information. +Related setting: @ref{set print frame-info}. +@end table + +The optional @var{qualifier} is maintained for backward compatibility. +It can be one of the following: + +@table @code +@item full +Equivalent to the @code{-full} option. + +@item no-filters +Equivalent to the @code{-no-filters} option. + +@item hide +Equivalent to the @code{-hide} option. +@end table + +@end table + +@kindex where +@kindex info stack +The names @code{where} and @code{info stack} (abbreviated @code{info s}) +are additional aliases for @code{backtrace}. + +@cindex multiple threads, backtrace +In a multi-threaded program, @value{GDBN} by default shows the +backtrace only for the current thread. To display the backtrace for +several or all of the threads, use the command @code{thread apply} +(@pxref{Threads, thread apply}). For example, if you type @kbd{thread +apply all backtrace}, @value{GDBN} will display the backtrace for all +the threads; this is handy when you debug a core dump of a +multi-threaded program. + +Each line in the backtrace shows the frame number and the function name. +The program counter value is also shown---unless you use @code{set +print address off}. The backtrace also shows the source file name and +line number, as well as the arguments to the function. The program +counter value is omitted if it is at the beginning of the code for that +line number. + +Here is an example of a backtrace. It was made with the command +@samp{bt 3}, so it shows the innermost three frames. + +@smallexample +@group +#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 +#1 0x6e38 in expand_macro (sym=0x2b600, data=...) at macro.c:242 +#2 0x6840 in expand_token (obs=0x0, t=177664, td=0xf7fffb08) + at macro.c:71 +(More stack frames follow...) +@end group +@end smallexample + +@noindent +The display for frame zero does not begin with a program counter +value, indicating that your program has stopped at the beginning of the +code for line @code{993} of @code{builtin.c}. + +@noindent +The value of parameter @code{data} in frame 1 has been replaced by +@code{@dots{}}. By default, @value{GDBN} prints the value of a parameter +only if it is a scalar (integer, pointer, enumeration, etc). See command +@kbd{set print frame-arguments} in @ref{Print Settings} for more details +on how to configure the way function parameter values are printed. +The command @kbd{set print frame-info} (@pxref{Print Settings}) controls +what frame information is printed. + +@cindex optimized out, in backtrace +@cindex function call arguments, optimized out +If your program was compiled with optimizations, some compilers will +optimize away arguments passed to functions if those arguments are +never used after the call. Such optimizations generate code that +passes arguments through registers, but doesn't store those arguments +in the stack frame. @value{GDBN} has no way of displaying such +arguments in stack frames other than the innermost one. Here's what +such a backtrace might look like: + +@smallexample +@group +#0 m4_traceon (obs=0x24eb0, argc=1, argv=0x2b8c8) + at builtin.c:993 +#1 0x6e38 in expand_macro (sym=) at macro.c:242 +#2 0x6840 in expand_token (obs=0x0, t=, td=0xf7fffb08) + at macro.c:71 +(More stack frames follow...) +@end group +@end smallexample + +@noindent +The values of arguments that were not saved in their stack frames are +shown as @samp{}. + +If you need to display the values of such optimized-out arguments, +either deduce that from other variables whose values depend on the one +you are interested in, or recompile without optimizations. + +@cindex backtrace beyond @code{main} function +@cindex program entry point +@cindex startup code, and backtrace +Most programs have a standard user entry point---a place where system +libraries and startup code transition into user code. For C this is +@code{main}@footnote{ +Note that embedded programs (the so-called ``free-standing'' +environment) are not required to have a @code{main} function as the +entry point. They could even have multiple entry points.}. +When @value{GDBN} finds the entry function in a backtrace +it will terminate the backtrace, to avoid tracing into highly +system-specific (and generally uninteresting) code. + +If you need to examine the startup code, or limit the number of levels +in a backtrace, you can change this behavior: + +@table @code +@item set backtrace past-main +@itemx set backtrace past-main on +@anchor{set backtrace past-main} +@kindex set backtrace +Backtraces will continue past the user entry point. + +@item set backtrace past-main off +Backtraces will stop when they encounter the user entry point. This is the +default. + +@item show backtrace past-main +@kindex show backtrace +Display the current user entry point backtrace policy. + +@item set backtrace past-entry +@itemx set backtrace past-entry on +@anchor{set backtrace past-entry} +Backtraces will continue past the internal entry point of an application. +This entry point is encoded by the linker when the application is built, +and is likely before the user entry point @code{main} (or equivalent) is called. + +@item set backtrace past-entry off +Backtraces will stop when they encounter the internal entry point of an +application. This is the default. + +@item show backtrace past-entry +Display the current internal entry point backtrace policy. + +@item set backtrace limit @var{n} +@itemx set backtrace limit 0 +@itemx set backtrace limit unlimited +@anchor{set backtrace limit} +@cindex backtrace limit +Limit the backtrace to @var{n} levels. A value of @code{unlimited} +or zero means unlimited levels. + +@item show backtrace limit +Display the current limit on backtrace levels. +@end table + +You can control how file names are displayed. + +@table @code +@item set filename-display +@itemx set filename-display relative +@cindex filename-display +Display file names relative to the compilation directory. This is the default. + +@item set filename-display basename +Display only basename of a filename. + +@item set filename-display absolute +Display an absolute filename. + +@item show filename-display +Show the current way to display filenames. +@end table + +@node Selection +@section Selecting a Frame + +Most commands for examining the stack and other data in your program work on +whichever stack frame is selected at the moment. Here are the commands for +selecting a stack frame; all of them finish by printing a brief description +of the stack frame just selected. + +@table @code +@kindex frame@r{, selecting} +@kindex f @r{(@code{frame})} +@item frame @r{[} @var{frame-selection-spec} @r{]} +@item f @r{[} @var{frame-selection-spec} @r{]} +The @command{frame} command allows different stack frames to be +selected. The @var{frame-selection-spec} can be any of the following: + +@table @code +@kindex frame level +@item @var{num} +@item level @var{num} +Select frame level @var{num}. Recall that frame zero is the innermost +(currently executing) frame, frame one is the frame that called the +innermost one, and so on. The highest level frame is usually the one +for @code{main}. + +As this is the most common method of navigating the frame stack, the +string @command{level} can be omitted. For example, the following two +commands are equivalent: + +@smallexample +(@value{GDBP}) frame 3 +(@value{GDBP}) frame level 3 +@end smallexample + +@kindex frame address +@item address @var{stack-address} +Select the frame with stack address @var{stack-address}. The +@var{stack-address} for a frame can be seen in the output of +@command{info frame}, for example: + +@smallexample +(@value{GDBP}) info frame +Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 +@end smallexample + +The @var{stack-address} for this frame is @code{0x7fffffffda30} as +indicated by the line: + +@smallexample +Stack level 1, frame at 0x7fffffffda30: +@end smallexample + +@kindex frame function +@item function @var{function-name} +Select the stack frame for function @var{function-name}. If there are +multiple stack frames for function @var{function-name} then the inner +most stack frame is selected. + +@kindex frame view +@item view @var{stack-address} @r{[} @var{pc-addr} @r{]} +View a frame that is not part of @value{GDBN}'s backtrace. The frame +viewed has stack address @var{stack-addr}, and optionally, a program +counter address of @var{pc-addr}. + +This is useful mainly if the chaining of stack frames has been +damaged by a bug, making it impossible for @value{GDBN} to assign +numbers properly to all frames. In addition, this can be useful +when your program has multiple stacks and switches between them. + +When viewing a frame outside the current backtrace using +@command{frame view} then you can always return to the original +stack using one of the previous stack frame selection instructions, +for example @command{frame level 0}. + +@end table + +@kindex up +@item up @var{n} +Move @var{n} frames up the stack; @var{n} defaults to 1. For positive +numbers @var{n}, this advances toward the outermost frame, to higher +frame numbers, to frames that have existed longer. + +@kindex down +@kindex do @r{(@code{down})} +@item down @var{n} +Move @var{n} frames down the stack; @var{n} defaults to 1. For +positive numbers @var{n}, this advances toward the innermost frame, to +lower frame numbers, to frames that were created more recently. +You may abbreviate @code{down} as @code{do}. +@end table + +All of these commands end by printing two lines of output describing the +frame. The first line shows the frame number, the function name, the +arguments, and the source file and line number of execution in that +frame. The second line shows the text of that source line. + +@need 1000 +For example: + +@smallexample +@group +(@value{GDBP}) up +#1 0x22f0 in main (argc=1, argv=0xf7fffbf4, env=0xf7fffbfc) + at env.c:10 +10 read_input_file (argv[i]); +@end group +@end smallexample + +After such a printout, the @code{list} command with no arguments +prints ten lines centered on the point of execution in the frame. +You can also edit the program at the point of execution with your favorite +editing program by typing @code{edit}. +@xref{List, ,Printing Source Lines}, +for details. + +@table @code +@kindex select-frame +@item select-frame @r{[} @var{frame-selection-spec} @r{]} +The @code{select-frame} command is a variant of @code{frame} that does +not display the new frame after selecting it. This command is +intended primarily for use in @value{GDBN} command scripts, where the +output might be unnecessary and distracting. The +@var{frame-selection-spec} is as for the @command{frame} command +described in @ref{Selection, ,Selecting a Frame}. + +@kindex down-silently +@kindex up-silently +@item up-silently @var{n} +@itemx down-silently @var{n} +These two commands are variants of @code{up} and @code{down}, +respectively; they differ in that they do their work silently, without +causing display of the new frame. They are intended primarily for use +in @value{GDBN} command scripts, where the output might be unnecessary and +distracting. +@end table + +@node Frame Info +@section Information About a Frame + +There are several other commands to print information about the selected +stack frame. + +@table @code +@item frame +@itemx f +When used without any argument, this command does not change which +frame is selected, but prints a brief description of the currently +selected stack frame. It can be abbreviated @code{f}. With an +argument, this command is used to select a stack frame. +@xref{Selection, ,Selecting a Frame}. + +@kindex info frame +@kindex info f @r{(@code{info frame})} +@item info frame +@itemx info f +This command prints a verbose description of the selected stack frame, +including: + +@itemize @bullet +@item +the address of the frame +@item +the address of the next frame down (called by this frame) +@item +the address of the next frame up (caller of this frame) +@item +the language in which the source code corresponding to this frame is written +@item +the address of the frame's arguments +@item +the address of the frame's local variables +@item +the program counter saved in it (the address of execution in the caller frame) +@item +which registers were saved in the frame +@end itemize + +@noindent The verbose description is useful when +something has gone wrong that has made the stack format fail to fit +the usual conventions. + +@item info frame @r{[} @var{frame-selection-spec} @r{]} +@itemx info f @r{[} @var{frame-selection-spec} @r{]} +Print a verbose description of the frame selected by +@var{frame-selection-spec}. The @var{frame-selection-spec} is the +same as for the @command{frame} command (@pxref{Selection, ,Selecting +a Frame}). The selected frame remains unchanged by this command. + +@kindex info args +@item info args [-q] +Print the arguments of the selected frame, each on a separate line. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no argument +have been printed. + +@item info args [-q] [-t @var{type_regexp}] [@var{regexp}] +Like @kbd{info args}, but only print the arguments selected +with the provided regexp(s). + +If @var{regexp} is provided, print only the arguments whose names +match the regular expression @var{regexp}. + +If @var{type_regexp} is provided, print only the arguments whose +types, as printed by the @code{whatis} command, match +the regular expression @var{type_regexp}. +If @var{type_regexp} contains space(s), it should be enclosed in +quote characters. If needed, use backslash to escape the meaning +of special characters or quotes. + +If both @var{regexp} and @var{type_regexp} are provided, an argument +is printed only if its name matches @var{regexp} and its type matches +@var{type_regexp}. + +@item info locals [-q] +@kindex info locals +Print the local variables of the selected frame, each on a separate +line. These are all variables (declared either static or automatic) +accessible at the point of execution of the selected frame. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no local variables +have been printed. + +@item info locals [-q] [-t @var{type_regexp}] [@var{regexp}] +Like @kbd{info locals}, but only print the local variables selected +with the provided regexp(s). + +If @var{regexp} is provided, print only the local variables whose names +match the regular expression @var{regexp}. + +If @var{type_regexp} is provided, print only the local variables whose +types, as printed by the @code{whatis} command, match +the regular expression @var{type_regexp}. +If @var{type_regexp} contains space(s), it should be enclosed in +quote characters. If needed, use backslash to escape the meaning +of special characters or quotes. + +If both @var{regexp} and @var{type_regexp} are provided, a local variable +is printed only if its name matches @var{regexp} and its type matches +@var{type_regexp}. + +The command @kbd{info locals -q -t @var{type_regexp}} can usefully be +combined with the commands @kbd{frame apply} and @kbd{thread apply}. +For example, your program might use Resource Acquisition Is +Initialization types (RAII) such as @code{lock_something_t}: each +local variable of type @code{lock_something_t} automatically places a +lock that is destroyed when the variable goes out of scope. You can +then list all acquired locks in your program by doing +@smallexample +thread apply all -s frame apply all -s info locals -q -t lock_something_t +@end smallexample +@noindent +or the equivalent shorter form +@smallexample +tfaas i lo -q -t lock_something_t +@end smallexample + +@end table + +@node Frame Apply +@section Applying a Command to Several Frames. +@kindex frame apply +@cindex apply command to several frames +@table @code +@item frame apply [all | @var{count} | @var{-count} | level @var{level}@dots{}] [@var{option}]@dots{} @var{command} +The @code{frame apply} command allows you to apply the named +@var{command} to one or more frames. + +@table @code +@item @code{all} +Specify @code{all} to apply @var{command} to all frames. + +@item @var{count} +Use @var{count} to apply @var{command} to the innermost @var{count} +frames, where @var{count} is a positive number. + +@item @var{-count} +Use @var{-count} to apply @var{command} to the outermost @var{count} +frames, where @var{count} is a positive number. + +@item @code{level} +Use @code{level} to apply @var{command} to the set of frames identified +by the @var{level} list. @var{level} is a frame level or a range of frame +levels as @var{level1}-@var{level2}. The frame level is the number shown +in the first field of the @samp{backtrace} command output. +E.g., @samp{2-4 6-8 3} indicates to apply @var{command} for the frames +at levels 2, 3, 4, 6, 7, 8, and then again on frame at level 3. + +@end table + +Note that the frames on which @code{frame apply} applies a command are +also influenced by the @code{set backtrace} settings such as @code{set +backtrace past-main} and @code{set backtrace limit N}. +@xref{Backtrace,,Backtraces}. + +The @code{frame apply} command also supports a number of options that +allow overriding relevant @code{set backtrace} settings: + +@table @code +@item -past-main [@code{on}|@code{off}] +Whether backtraces should continue past @code{main}. +Related setting: @ref{set backtrace past-main}. + +@item -past-entry [@code{on}|@code{off}] +Whether backtraces should continue past the entry point of a program. +Related setting: @ref{set backtrace past-entry}. +@end table + +By default, @value{GDBN} displays some frame information before the +output produced by @var{command}, and an error raised during the +execution of a @var{command} will abort @code{frame apply}. The +following options can be used to fine-tune these behaviors: + +@table @code +@item -c +The flag @code{-c}, which stands for @samp{continue}, causes any +errors in @var{command} to be displayed, and the execution of +@code{frame apply} then continues. +@item -s +The flag @code{-s}, which stands for @samp{silent}, causes any errors +or empty output produced by a @var{command} to be silently ignored. +That is, the execution continues, but the frame information and errors +are not printed. +@item -q +The flag @code{-q} (@samp{quiet}) disables printing the frame +information. +@end table + +The following example shows how the flags @code{-c} and @code{-s} are +working when applying the command @code{p j} to all frames, where +variable @code{j} can only be successfully printed in the outermost +@code{#1 main} frame. + +@smallexample +@group +(@value{GDBP}) frame apply all p j +#0 some_function (i=5) at fun.c:4 +No symbol "j" in current context. +(@value{GDBP}) frame apply all -c p j +#0 some_function (i=5) at fun.c:4 +No symbol "j" in current context. +#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 +$1 = 5 +(@value{GDBP}) frame apply all -s p j +#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 +$2 = 5 +(@value{GDBP}) +@end group +@end smallexample + +By default, @samp{frame apply}, prints the frame location +information before the command output: + +@smallexample +@group +(@value{GDBP}) frame apply all p $sp +#0 some_function (i=5) at fun.c:4 +$4 = (void *) 0xffffd1e0 +#1 0x565555fb in main (argc=1, argv=0xffffd2c4) at fun.c:11 +$5 = (void *) 0xffffd1f0 +(@value{GDBP}) +@end group +@end smallexample + +If the flag @code{-q} is given, no frame information is printed: +@smallexample +@group +(@value{GDBP}) frame apply all -q p $sp +$12 = (void *) 0xffffd1e0 +$13 = (void *) 0xffffd1f0 +(@value{GDBP}) +@end group +@end smallexample + +@end table + +@table @code + +@kindex faas +@cindex apply a command to all frames (ignoring errors and empty output) +@item faas @var{command} +Shortcut for @code{frame apply all -s @var{command}}. +Applies @var{command} on all frames, ignoring errors and empty output. + +It can for example be used to print a local variable or a function +argument without knowing the frame where this variable or argument +is, using: +@smallexample +(@value{GDBP}) faas p some_local_var_i_do_not_remember_where_it_is +@end smallexample + +The @code{faas} command accepts the same options as the @code{frame +apply} command. @xref{Frame Apply,,frame apply}. + +Note that the command @code{tfaas @var{command}} applies @var{command} +on all frames of all threads. See @xref{Threads,,Threads}. +@end table + + +@node Frame Filter Management +@section Management of Frame Filters. +@cindex managing frame filters + +Frame filters are Python based utilities to manage and decorate the +output of frames. @xref{Frame Filter API}, for further information. + +Managing frame filters is performed by several commands available +within @value{GDBN}, detailed here. + +@table @code +@kindex info frame-filter +@item info frame-filter +Print a list of installed frame filters from all dictionaries, showing +their name, priority and enabled status. + +@kindex disable frame-filter +@anchor{disable frame-filter all} +@item disable frame-filter @var{filter-dictionary} @var{filter-name} +Disable a frame filter in the dictionary matching +@var{filter-dictionary} and @var{filter-name}. The +@var{filter-dictionary} may be @code{all}, @code{global}, +@code{progspace}, or the name of the object file where the frame filter +dictionary resides. When @code{all} is specified, all frame filters +across all dictionaries are disabled. The @var{filter-name} is the name +of the frame filter and is used when @code{all} is not the option for +@var{filter-dictionary}. A disabled frame-filter is not deleted, it +may be enabled again later. + +@kindex enable frame-filter +@item enable frame-filter @var{filter-dictionary} @var{filter-name} +Enable a frame filter in the dictionary matching +@var{filter-dictionary} and @var{filter-name}. The +@var{filter-dictionary} may be @code{all}, @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. When @code{all} is specified, all frame filters across +all dictionaries are enabled. The @var{filter-name} is the name of the frame +filter and is used when @code{all} is not the option for +@var{filter-dictionary}. + +Example: + +@smallexample +(@value{GDBP}) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 Yes BuildProgramFilter + +(@value{GDBP}) disable frame-filter /build/test BuildProgramFilter +(@value{GDBP}) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 No PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +(@value{GDBP}) enable frame-filter global PrimaryFunctionFilter +(@value{GDBP}) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter +@end smallexample + +@kindex set frame-filter priority +@item set frame-filter priority @var{filter-dictionary} @var{filter-name} @var{priority} +Set the @var{priority} of a frame filter in the dictionary matching +@var{filter-dictionary}, and the frame filter name matching +@var{filter-name}. The @var{filter-dictionary} may be @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. The @var{priority} is an integer. + +@kindex show frame-filter priority +@item show frame-filter priority @var{filter-dictionary} @var{filter-name} +Show the @var{priority} of a frame filter in the dictionary matching +@var{filter-dictionary}, and the frame filter name matching +@var{filter-name}. The @var{filter-dictionary} may be @code{global}, +@code{progspace} or the name of the object file where the frame filter +dictionary resides. + +Example: + +@smallexample +(@value{GDBP}) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 100 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter + +(@value{GDBP}) set frame-filter priority global Reverse 50 +(@value{GDBP}) info frame-filter + +global frame-filters: + Priority Enabled Name + 1000 Yes PrimaryFunctionFilter + 50 Yes Reverse + +progspace /build/test frame-filters: + Priority Enabled Name + 100 Yes ProgspaceFilter + +objfile /build/test frame-filters: + Priority Enabled Name + 999 No BuildProgramFilter +@end smallexample +@end table + +@node Source +@chapter Examining Source Files + +@value{GDBN} can print parts of your program's source, since the debugging +information recorded in the program tells @value{GDBN} what source files were +used to build it. When your program stops, @value{GDBN} spontaneously prints +the line where it stopped. Likewise, when you select a stack frame +(@pxref{Selection, ,Selecting a Frame}), @value{GDBN} prints the line where +execution in that frame has stopped. You can print other portions of +source files by explicit command. + +If you use @value{GDBN} through its @sc{gnu} Emacs interface, you may +prefer to use Emacs facilities to view source; see @ref{Emacs, ,Using +@value{GDBN} under @sc{gnu} Emacs}. + +@menu +* List:: Printing source lines +* Location Specifications:: How to specify code locations +* Edit:: Editing source files +* Search:: Searching source files +* Source Path:: Specifying source directories +* Machine Code:: Source and machine code +* Disable Reading Source:: Disable Reading Source Code +@end menu + +@node List +@section Printing Source Lines + +@kindex list +@kindex l @r{(@code{list})} +To print lines from a source file, use the @code{list} command +(abbreviated @code{l}). By default, ten lines are printed. +There are several ways to specify what part of the file you want to +print; see @ref{Location Specifications}, for the full list. + +Here are the forms of the @code{list} command most commonly used: + +@table @code +@item list @var{linenum} +Print lines centered around line number @var{linenum} in the +current source file. + +@item list @var{function} +Print lines centered around the beginning of function +@var{function}. + +@item list +Print more lines. If the last lines printed were printed with a +@code{list} command, this prints lines following the last lines +printed; however, if the last line printed was a solitary line printed +as part of displaying a stack frame (@pxref{Stack, ,Examining the +Stack}), this prints lines centered around that line. If no +@code{list} command has been used and no solitary line was printed, +it prints the lines around the function @code{main}. + +@item list + +Same as using with no arguments. + +@item list - +Print lines just before the lines last printed. + +@item list . +Print the lines surrounding the point of execution within the +currently selected frame. If the inferior is not running, print lines +around the start of the main function instead. +@end table + +@cindex @code{list}, how many lines to display +By default, @value{GDBN} prints ten source lines with any of these forms of +the @code{list} command. You can change this using @code{set listsize}: + +@table @code +@kindex set listsize +@item set listsize @var{count} +@itemx set listsize unlimited +Make the @code{list} command display @var{count} source lines (unless +the @code{list} argument explicitly specifies some other number). +Setting @var{count} to @code{unlimited} or 0 means there's no limit. + +@kindex show listsize +@item show listsize +Display the number of lines that @code{list} prints. +@end table + +Repeating a @code{list} command with @key{RET} discards the argument, +so it is equivalent to typing just @code{list}. This is more useful +than listing the same lines again. An exception is made for an +argument of @samp{-}; that argument is preserved in repetition so that +each repetition moves up in the source file. + +In general, the @code{list} command expects you to supply zero, one or +two location specs. These location specs are interpreted to resolve +to source code lines; there are several ways of writing them +(@pxref{Location Specifications}), but the effect is always to resolve +to some source lines to display. + +Here is a complete description of the possible arguments for @code{list}: + +@table @code +@item list @var{locspec} +Print lines centered around the line or lines of all the code +locations that result from resolving @var{locspec}. + +@item list @var{first},@var{last} +Print lines from @var{first} to @var{last}. Both arguments are +location specs. When a @code{list} command has two location specs, +and the source file of the second location spec is omitted, this +refers to the same source file as the first location spec. If either +@var{first} or @var{last} resolve to more than one source line in the +program, then the list command shows the list of resolved source +lines and does not proceed with the source code listing. + +@item list ,@var{last} +Print lines ending with @var{last}. + +Likewise, if @var{last} resolves to more than one source line in the +program, then the list command prints the list of resolved source +lines and does not proceed with the source code listing. + +@item list @var{first}, +Print lines starting with @var{first}. + +@item list + +Print lines just after the lines last printed. + +@item list - +Print lines just before the lines last printed. + +@item list +As described in the preceding table. +@end table + +@node Location Specifications +@section Location Specifications +@cindex specifying location +@cindex locspec +@cindex source location +@cindex code location + +@cindex location spec +Several @value{GDBN} commands accept arguments that specify a location +or locations of your program's code. Many times locations are +specified using a source line number, but they can also be specified +by a function name, an address, a label, etc. The different +forms of specifying a location that @value{GDBN} recognizes are +collectively known as forms of @dfn{location specification}, or +@dfn{location spec}. This section documents the forms of specifying +locations that @value{GDBN} recognizes. + +@cindex location resolution +@cindex resolution of location spec +When you specify a location, @value{GDBN} needs to find the place in +your program, known as @dfn{code location}, that corresponds to the +given location spec. We call this process of finding actual code +locations corresponding to a location spec @dfn{location resolution}. + +A concrete code location in your program is uniquely identifiable by a +set of several attributes: its source line number, the name of its +source file, the fully-qualified and prototyped function in which it +is defined, and an instruction address. Because each inferior has its +own address space, the inferior number is also a necessary part of +these attributes. + +By contrast, location specs you type will many times omit some of +these attributes. For example, it is customary to specify just the +source line number to mean a line in the current source file, or +specify just the basename of the file, omitting its directories. In +other words, a location spec is usually incomplete, a kind of +blueprint, and @value{GDBN} needs to complete the missing attributes +by using the implied defaults, and by considering the source code and +the debug information available to it. This is what location +resolution is about. + +The resolution of an incomplete location spec can produce more than a +single code location, if the spec doesn't allow distinguishing between +them. Here are some examples of situations that result in a location +spec matching multiple code locations in your program: + +@itemize @bullet +@item +The location spec specifies a function name, and there are several +functions in the program which have that name. (To distinguish +between them, you can specify a fully-qualified and prototyped +function name, such as @code{A::func(int)} instead of just +@code{func}.) + +@item +The location spec specifies a source file name, and there are several +source files in the program that share the same name, for example +several files with the same basename in different subdirectories. (To +distinguish between them, specify enough leading directories with the +file name.) + +@item +For a C@t{++} constructor, the @value{NGCC} compiler generates several +instances of the function body, used in different cases, but their +source-level names are identical. + +@item +For a C@t{++} template function, a given line in the function can +correspond to any number of instantiations. + +@item +For an inlined function, a given source line can correspond to several +actual code locations with that function's inlined code. +@end itemize + +Resolution of a location spec can also fail to produce a complete code +location, or even fail to produce any code location. Here are some +examples of such situations: + +@itemize @bullet +@item +Some parts of the program lack detailed enough debug info, so the +resolved code location lacks some attributes, like source file name +and line number, leaving just the instruction address and perhaps also +a function name. Such an incomplete code location is only usable in +contexts that work with addresses and/or function names. Some +commands can only work with complete code locations. + +@item +The location spec specifies a function name, and there are no +functions in the program by that name, or they only exist in a +yet-unloaded shared library. + +@item +The location spec specifies a source file name, and there are no +source files in the program by that name, or they only exist in a +yet-unloaded shared library. + +@item +The location spec specifies both a source file name and a source line +number, and even though there are source files in the program that +match the file name, none of those files has the specified line +number. +@end itemize + +Locations may be specified using three different formats: linespec +locations, explicit locations, or address locations. The following +subsections describe these formats. + +@menu +* Linespec Locations:: Linespec locations +* Explicit Locations:: Explicit locations +* Address Locations:: Address locations +@end menu + +@node Linespec Locations +@subsection Linespec Locations +@cindex linespec locations + +A @dfn{linespec} is a colon-separated list of source location parameters such +as file name, function name, etc. Here are all the different ways of +specifying a linespec: + +@table @code +@item @var{linenum} +Specifies the line number @var{linenum} of the current source file. + +@item -@var{offset} +@itemx +@var{offset} +Specifies the line @var{offset} lines before or after the @dfn{current +line}. For the @code{list} command, the current line is the last one +printed; for the breakpoint commands, this is the line at which +execution stopped in the currently selected @dfn{stack frame} +(@pxref{Frames, ,Frames}, for a description of stack frames.) When +used as the second of the two linespecs in a @code{list} command, +this specifies the line @var{offset} lines up or down from the first +linespec. + +@item @var{filename}:@var{linenum} +Specifies the line @var{linenum} in the source file @var{filename}. +If @var{filename} is a relative file name, then it will match any +source file name with the same trailing components. For example, if +@var{filename} is @samp{gcc/expr.c}, then it will match source file +name of @file{/build/trunk/gcc/expr.c}, but not +@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}. + +@item @var{function} +Specifies the line that begins the body of the function @var{function}. +For example, in C, this is the line with the open brace. + +By default, in C@t{++} and Ada, @var{function} is interpreted as +specifying all functions named @var{function} in all scopes. For +C@t{++}, this means in all namespaces and classes. For Ada, this +means in all packages. + +For example, assuming a program with C@t{++} symbols named +@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break +func}} and @w{@kbd{break B::func}} set a breakpoint on both symbols. + +Commands that accept a linespec let you override this with the +@code{-qualified} option. For example, @w{@kbd{break -qualified +func}} sets a breakpoint on a free-function named @code{func} ignoring +any C@t{++} class methods and namespace functions called @code{func}. + +@xref{Explicit Locations}. + +@item @var{function}:@var{label} +Specifies the line where @var{label} appears in @var{function}. + +@item @var{filename}:@var{function} +Specifies the line that begins the body of the function @var{function} +in the file @var{filename}. You only need the file name with a +function name to avoid ambiguity when there are identically named +functions in different source files. + +@item @var{label} +Specifies the line at which the label named @var{label} appears +in the function corresponding to the currently selected stack frame. +If there is no current selected stack frame (for instance, if the inferior +is not running), then @value{GDBN} will not search for a label. + +@cindex breakpoint at static probe point +@item -pstap|-probe-stap @r{[}@var{objfile}:@r{[}@var{provider}:@r{]}@r{]}@var{name} +The @sc{gnu}/Linux tool @code{SystemTap} provides a way for +applications to embed static probes. @xref{Static Probe Points}, for more +information on finding and using static probes. This form of linespec +specifies the location of such a static probe. + +If @var{objfile} is given, only probes coming from that shared library +or executable matching @var{objfile} as a regular expression are considered. +If @var{provider} is given, then only probes from that provider are considered. +If several probes match the spec, @value{GDBN} will insert a breakpoint at +each one of those probes. +@end table + +@node Explicit Locations +@subsection Explicit Locations +@cindex explicit locations + +@dfn{Explicit locations} allow the user to directly specify the source +location's parameters using option-value pairs. + +Explicit locations are useful when several functions, labels, or +file names have the same name (base name for files) in the program's +sources. In these cases, explicit locations point to the source +line you meant more accurately and unambiguously. Also, using +explicit locations might be faster in large programs. + +For example, the linespec @samp{foo:bar} may refer to a function @code{bar} +defined in the file named @file{foo} or the label @code{bar} in a function +named @code{foo}. @value{GDBN} must search either the file system or +the symbol table to know. + +The list of valid explicit location options is summarized in the +following table: + +@table @code +@item -source @var{filename} +The value specifies the source file name. To differentiate between +files with the same base name, prepend as many directories as is necessary +to uniquely identify the desired file, e.g., @file{foo/bar/baz.c}. Otherwise +@value{GDBN} will use the first file it finds with the given base +name. This option requires the use of either @code{-function} or @code{-line}. + +@item -function @var{function} +The value specifies the name of a function. Operations +on function locations unmodified by other options (such as @code{-label} +or @code{-line}) refer to the line that begins the body of the function. +In C, for example, this is the line with the open brace. + +By default, in C@t{++} and Ada, @var{function} is interpreted as +specifying all functions named @var{function} in all scopes. For +C@t{++}, this means in all namespaces and classes. For Ada, this +means in all packages. + +For example, assuming a program with C@t{++} symbols named +@code{A::B::func} and @code{B::func}, both commands @w{@kbd{break +-function func}} and @w{@kbd{break -function B::func}} set a +breakpoint on both symbols. + +You can use the @kbd{-qualified} flag to override this (see below). + +@item -qualified + +This flag makes @value{GDBN} interpret a function name specified with +@kbd{-function} as a complete fully-qualified name. + +For example, assuming a C@t{++} program with symbols named +@code{A::B::func} and @code{B::func}, the @w{@kbd{break -qualified +-function B::func}} command sets a breakpoint on @code{B::func}, only. + +(Note: the @kbd{-qualified} option can precede a linespec as well +(@pxref{Linespec Locations}), so the particular example above could be +simplified as @w{@kbd{break -qualified B::func}}.) + +@item -label @var{label} +The value specifies the name of a label. When the function +name is not specified, the label is searched in the function of the currently +selected stack frame. + +@item -line @var{number} +The value specifies a line offset for the location. The offset may either +be absolute (@code{-line 3}) or relative (@code{-line +3}), depending on +the command. When specified without any other options, the line offset is +relative to the current line. +@end table + +Explicit location options may be abbreviated by omitting any non-unique +trailing characters from the option name, e.g., @w{@kbd{break -s main.c -li 3}}. + +@node Address Locations +@subsection Address Locations +@cindex address locations + +@dfn{Address locations} indicate a specific program address. They have +the generalized form *@var{address}. + +For line-oriented commands, such as @code{list} and @code{edit}, this +specifies a source line that contains @var{address}. For @code{break} and +other breakpoint-oriented commands, this can be used to set breakpoints in +parts of your program which do not have debugging information or +source files. + +Here @var{address} may be any expression valid in the current working +language (@pxref{Languages, working language}) that specifies a code +address. In addition, as a convenience, @value{GDBN} extends the +semantics of expressions used in locations to cover several situations +that frequently occur during debugging. Here are the various forms +of @var{address}: + +@table @code +@item @var{expression} +Any expression valid in the current working language. + +@item @var{funcaddr} +An address of a function or procedure derived from its name. In C, +C@t{++}, Objective-C, Fortran, minimal, and assembly, this is +simply the function's name @var{function} (and actually a special case +of a valid expression). In Pascal and Modula-2, this is +@code{&@var{function}}. In Ada, this is @code{@var{function}'Address} +(although the Pascal form also works). + +This form specifies the address of the function's first instruction, +before the stack frame and arguments have been set up. + +@item '@var{filename}':@var{funcaddr} +Like @var{funcaddr} above, but also specifies the name of the source +file explicitly. This is useful if the name of the function does not +specify the function unambiguously, e.g., if there are several +functions with identical names in different source files. +@end table + +@node Edit +@section Editing Source Files +@cindex editing source files + +@kindex edit +@kindex e @r{(@code{edit})} +To edit the lines in a source file, use the @code{edit} command. +The editing program of your choice +is invoked with the current line set to +the active line in the program. +Alternatively, there are several ways to specify what part of the file you +want to print if you want to see other parts of the program: + +@table @code +@item edit @var{locspec} +Edit the source file of the code location that results from resolving +@code{locspec}. Editing starts at the source file and source line +@code{locspec} resolves to. +@xref{Location Specifications}, for all the possible forms of the +@var{locspec} argument. + +If @code{locspec} resolves to more than one source line in your +program, then the command prints the list of resolved source lines and +does not proceed with the editing. + +Here are the forms of the @code{edit} command most commonly used: + +@table @code +@item edit @var{number} +Edit the current source file with @var{number} as the active line number. + +@item edit @var{function} +Edit the file containing @var{function} at the beginning of its definition. +@end table + +@end table + +@subsection Choosing your Editor +You can customize @value{GDBN} to use any editor you want +@footnote{ +The only restriction is that your editor (say @code{ex}), recognizes the +following command-line syntax: +@smallexample +ex +@var{number} file +@end smallexample +The optional numeric value +@var{number} specifies the number of the line in +the file where to start editing.}. +By default, it is @file{@value{EDITOR}}, but you can change this +by setting the environment variable @env{EDITOR} before using +@value{GDBN}. For example, to configure @value{GDBN} to use the +@code{vi} editor, you could use these commands with the @code{sh} shell: +@smallexample +EDITOR=/usr/bin/vi +export EDITOR +gdb @dots{} +@end smallexample +or in the @code{csh} shell, +@smallexample +setenv EDITOR /usr/bin/vi +gdb @dots{} +@end smallexample + +@node Search +@section Searching Source Files +@cindex searching source files + +There are two commands for searching through the current source file for a +regular expression. + +@table @code +@kindex search +@kindex forward-search +@kindex fo @r{(@code{forward-search})} +@item forward-search @var{regexp} +@itemx search @var{regexp} +The command @samp{forward-search @var{regexp}} checks each line, +starting with the one following the last line listed, for a match for +@var{regexp}. It lists the line that is found. You can use the +synonym @samp{search @var{regexp}} or abbreviate the command name as +@code{fo}. + +@kindex reverse-search +@item reverse-search @var{regexp} +The command @samp{reverse-search @var{regexp}} checks each line, starting +with the one before the last line listed and going backward, for a match +for @var{regexp}. It lists the line that is found. You can abbreviate +this command as @code{rev}. +@end table + +@node Source Path +@section Specifying Source Directories + +@cindex source path +@cindex directories for source files +Executable programs sometimes do not record the directories of the source +files from which they were compiled, just the names. Even when they do, +the directories could be moved between the compilation and your debugging +session. @value{GDBN} has a list of directories to search for source files; +this is called the @dfn{source path}. Each time @value{GDBN} wants a source file, +it tries all the directories in the list, in the order they are present +in the list, until it finds a file with the desired name. + +For example, suppose an executable references the file +@file{/usr/src/foo-1.0/lib/foo.c}, does not record a compilation +directory, and the @dfn{source path} is @file{/mnt/cross}. +@value{GDBN} would look for the source file in the following +locations: + +@enumerate + +@item @file{/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/foo.c} + +@end enumerate + +If the source file is not present at any of the above locations then +an error is printed. @value{GDBN} does not look up the parts of the +source file name, such as @file{/mnt/cross/src/foo-1.0/lib/foo.c}. +Likewise, the subdirectories of the source path are not searched: if +the source path is @file{/mnt/cross}, and the binary refers to +@file{foo.c}, @value{GDBN} would not find it under +@file{/mnt/cross/usr/src/foo-1.0/lib}. + +Plain file names, relative file names with leading directories, file +names containing dots, etc.@: are all treated as described above, +except that non-absolute file names are not looked up literally. If +the @dfn{source path} is @file{/mnt/cross}, the source file is +recorded as @file{../lib/foo.c}, and no compilation directory is +recorded, then @value{GDBN} will search in the following locations: + +@enumerate + +@item @file{/mnt/cross/../lib/foo.c} +@item @file{/mnt/cross/foo.c} + +@end enumerate + +@kindex cdir +@kindex cwd +@vindex $cdir@r{, convenience variable} +@vindex $cwd@r{, convenience variable} +@cindex compilation directory +@cindex current directory +@cindex working directory +@cindex directory, current +@cindex directory, compilation +The @dfn{source path} will always include two special entries +@samp{$cdir} and @samp{$cwd}, these refer to the compilation directory +(if one is recorded) and the current working directory respectively. + +@samp{$cdir} causes @value{GDBN} to search within the compilation +directory, if one is recorded in the debug information. If no +compilation directory is recorded in the debug information then +@samp{$cdir} is ignored. + +@samp{$cwd} is not the same as @samp{.}---the former tracks the +current working directory as it changes during your @value{GDBN} +session, while the latter is immediately expanded to the current +directory at the time you add an entry to the source path. + +If a compilation directory is recorded in the debug information, and +@value{GDBN} has not found the source file after the first search +using @dfn{source path}, then @value{GDBN} will combine the +compilation directory and the filename, and then search for the source +file again using the @dfn{source path}. + +For example, if the executable records the source file as +@file{/usr/src/foo-1.0/lib/foo.c}, the compilation directory is +recorded as @file{/project/build}, and the @dfn{source path} is +@file{/mnt/cross:$cdir:$cwd} while the current working directory of +the @value{GDBN} session is @file{/home/user}, then @value{GDBN} will +search for the source file in the following locations: + +@enumerate + +@item @file{/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/usr/src/foo-1.0/lib/foo.c} +@item @file{/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/home/user/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/project/build/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/home/user/project/build/usr/src/foo-1.0/lib/foo.c} +@item @file{/mnt/cross/foo.c} +@item @file{/project/build/foo.c} +@item @file{/home/user/foo.c} + +@end enumerate + +If the file name in the previous example had been recorded in the +executable as a relative path rather than an absolute path, then the +first look up would not have occurred, but all of the remaining steps +would be similar. + +When searching for source files on MS-DOS and MS-Windows, where +absolute paths start with a drive letter (e.g.@: +@file{C:/project/foo.c}), @value{GDBN} will remove the drive letter +from the file name before appending it to a search directory from +@dfn{source path}; for instance if the executable references the +source file @file{C:/project/foo.c} and @dfn{source path} is set to +@file{D:/mnt/cross}, then @value{GDBN} will search in the following +locations for the source file: + +@enumerate + +@item @file{C:/project/foo.c} +@item @file{D:/mnt/cross/project/foo.c} +@item @file{D:/mnt/cross/foo.c} + +@end enumerate + +Note that the executable search path is @emph{not} used to locate the +source files. + +Whenever you reset or rearrange the source path, @value{GDBN} clears out +any information it has cached about where source files are found and where +each line is in the file. + +@kindex directory +@kindex dir +When you start @value{GDBN}, its source path includes only @samp{$cdir} +and @samp{$cwd}, in that order. +To add other directories, use the @code{directory} command. + +The search path is used to find both program source files and @value{GDBN} +script files (read using the @samp{-command} option and @samp{source} command). + +In addition to the source path, @value{GDBN} provides a set of commands +that manage a list of source path substitution rules. A @dfn{substitution +rule} specifies how to rewrite source directories stored in the program's +debug information in case the sources were moved to a different +directory between compilation and debugging. A rule is made of +two strings, the first specifying what needs to be rewritten in +the path, and the second specifying how it should be rewritten. +In @ref{set substitute-path}, we name these two parts @var{from} and +@var{to} respectively. @value{GDBN} does a simple string replacement +of @var{from} with @var{to} at the start of the directory part of the +source file name, and uses that result instead of the original file +name to look up the sources. + +Using the previous example, suppose the @file{foo-1.0} tree has been +moved from @file{/usr/src} to @file{/mnt/cross}, then you can tell +@value{GDBN} to replace @file{/usr/src} in all source path names with +@file{/mnt/cross}. The first lookup will then be +@file{/mnt/cross/foo-1.0/lib/foo.c} in place of the original location +of @file{/usr/src/foo-1.0/lib/foo.c}. To define a source path +substitution rule, use the @code{set substitute-path} command +(@pxref{set substitute-path}). + +To avoid unexpected substitution results, a rule is applied only if the +@var{from} part of the directory name ends at a directory separator. +For instance, a rule substituting @file{/usr/source} into +@file{/mnt/cross} will be applied to @file{/usr/source/foo-1.0} but +not to @file{/usr/sourceware/foo-2.0}. And because the substitution +is applied only at the beginning of the directory name, this rule will +not be applied to @file{/root/usr/source/baz.c} either. + +In many cases, you can achieve the same result using the @code{directory} +command. However, @code{set substitute-path} can be more efficient in +the case where the sources are organized in a complex tree with multiple +subdirectories. With the @code{directory} command, you need to add each +subdirectory of your project. If you moved the entire tree while +preserving its internal organization, then @code{set substitute-path} +allows you to direct the debugger to all the sources with one single +command. + +@code{set substitute-path} is also more than just a shortcut command. +The source path is only used if the file at the original location no +longer exists. On the other hand, @code{set substitute-path} modifies +the debugger behavior to look at the rewritten location instead. So, if +for any reason a source file that is not relevant to your executable is +located at the original location, a substitution rule is the only +method available to point @value{GDBN} at the new location. + +@cindex @samp{--with-relocated-sources} +@cindex default source path substitution +You can configure a default source path substitution rule by +configuring @value{GDBN} with the +@samp{--with-relocated-sources=@var{dir}} option. The @var{dir} +should be the name of a directory under @value{GDBN}'s configured +prefix (set with @samp{--prefix} or @samp{--exec-prefix}), and +directory names in debug information under @var{dir} will be adjusted +automatically if the installed @value{GDBN} is moved to a new +location. This is useful if @value{GDBN}, libraries or executables +with debug information and corresponding source code are being moved +together. + +@table @code +@item directory @var{dirname} @dots{} +@item dir @var{dirname} @dots{} +Add directory @var{dirname} to the front of the source path. Several +directory names may be given to this command, separated by @samp{:} +(@samp{;} on MS-DOS and MS-Windows, where @samp{:} usually appears as +part of absolute file names) or +whitespace. You may specify a directory that is already in the source +path; this moves it forward, so @value{GDBN} searches it sooner. + +The special strings @samp{$cdir} (to refer to the compilation +directory, if one is recorded), and @samp{$cwd} (to refer to the +current working directory) can also be included in the list of +directories @var{dirname}. Though these will already be in the source +path they will be moved forward in the list so @value{GDBN} searches +them sooner. + +@item directory +Reset the source path to its default value (@samp{$cdir:$cwd} on Unix systems). This requires confirmation. + +@c RET-repeat for @code{directory} is explicitly disabled, but since +@c repeating it would be a no-op we do not say that. (thanks to RMS) + +@item set directories @var{path-list} +@kindex set directories +Set the source path to @var{path-list}. +@samp{$cdir:$cwd} are added if missing. + +@item show directories +@kindex show directories +Print the source path: show which directories it contains. + +@anchor{set substitute-path} +@item set substitute-path @var{from} @var{to} +@kindex set substitute-path +Define a source path substitution rule, and add it at the end of the +current list of existing substitution rules. If a rule with the same +@var{from} was already defined, then the old rule is also deleted. + +For example, if the file @file{/foo/bar/baz.c} was moved to +@file{/mnt/cross/baz.c}, then the command + +@smallexample +(@value{GDBP}) set substitute-path /foo/bar /mnt/cross +@end smallexample + +@noindent +will tell @value{GDBN} to replace @samp{/foo/bar} with +@samp{/mnt/cross}, which will allow @value{GDBN} to find the file +@file{baz.c} even though it was moved. + +In the case when more than one substitution rule have been defined, +the rules are evaluated one by one in the order where they have been +defined. The first one matching, if any, is selected to perform +the substitution. + +For instance, if we had entered the following commands: + +@smallexample +(@value{GDBP}) set substitute-path /usr/src/include /mnt/include +(@value{GDBP}) set substitute-path /usr/src /mnt/src +@end smallexample + +@noindent +@value{GDBN} would then rewrite @file{/usr/src/include/defs.h} into +@file{/mnt/include/defs.h} by using the first rule. However, it would +use the second rule to rewrite @file{/usr/src/lib/foo.c} into +@file{/mnt/src/lib/foo.c}. + + +@item unset substitute-path [path] +@kindex unset substitute-path +If a path is specified, search the current list of substitution rules +for a rule that would rewrite that path. Delete that rule if found. +A warning is emitted by the debugger if no rule could be found. + +If no path is specified, then all substitution rules are deleted. + +@item show substitute-path [path] +@kindex show substitute-path +If a path is specified, then print the source path substitution rule +which would rewrite that path, if any. + +If no path is specified, then print all existing source path substitution +rules. + +@end table + +If your source path is cluttered with directories that are no longer of +interest, @value{GDBN} may sometimes cause confusion by finding the wrong +versions of source. You can correct the situation as follows: + +@enumerate +@item +Use @code{directory} with no argument to reset the source path to its default value. + +@item +Use @code{directory} with suitable arguments to reinstall the +directories you want in the source path. You can add all the +directories in one command. +@end enumerate + +@node Machine Code +@section Source and Machine Code +@cindex source line and its code address + +You can use the command @code{info line} to map source lines to program +addresses (and vice versa), and the command @code{disassemble} to display +a range of addresses as machine instructions. You can use the command +@code{set disassemble-next-line} to set whether to disassemble next +source line when execution stops. When run under @sc{gnu} Emacs +mode, the @code{info line} command causes the arrow to point to the +line specified. Also, @code{info line} prints addresses in symbolic form as +well as hex. + +@table @code +@kindex info line +@item info line +@itemx info line @var{locspec} +Print the starting and ending addresses of the compiled code for the +source lines of the code locations that result from resolving +@var{locspec}. @xref{Location Specifications}, for the various forms +of @var{locspec}. +With no @var{locspec}, information about the current source line is +printed. +@end table + +For example, we can use @code{info line} to discover the location of +the object code for the first line of function +@code{m4_changequote}: + +@smallexample +(@value{GDBP}) info line m4_changequote +Line 895 of "builtin.c" starts at pc 0x634c and \ + ends at 0x6350 . +@end smallexample + +@noindent +@cindex code address and its source line +We can also inquire, using @code{*@var{addr}} as the form for +@var{locspec}, what source line covers a particular address +@var{addr}: +@smallexample +(@value{GDBP}) info line *0x63ff +Line 926 of "builtin.c" starts at pc 0x63e4 and \ + ends at 0x6404 . +@end smallexample + +@cindex @code{$_} and @code{info line} +@cindex @code{x} command, default address +@kindex x@r{(examine), and} info line +After @code{info line}, the default address for the @code{x} command +is changed to the starting address of the line, so that @samp{x/i} is +sufficient to begin examining the machine code (@pxref{Memory, +,Examining Memory}). Also, this address is saved as the value of the +convenience variable @code{$_} (@pxref{Convenience Vars, ,Convenience +Variables}). + +@cindex info line, repeated calls +After @code{info line}, using @code{info line} again without +specifying a location will display information about the next source +line. + +@anchor{disassemble} +@table @code +@kindex disassemble +@cindex assembly instructions +@cindex instructions, assembly +@cindex machine instructions +@cindex listing machine instructions +@item disassemble +@itemx disassemble /m +@itemx disassemble /s +@itemx disassemble /r +@itemx disassemble /b +This specialized command dumps a range of memory as machine +instructions. It can also print mixed source+disassembly by specifying +the @code{/m} or @code{/s} modifier and print the raw instructions in +hex as well as in symbolic form by specifying the @code{/r} or @code{/b} +modifier. + +Only one of @code{/m} and @code{/s} can be used, attempting to use +both flag will give an error. + +Only one of @code{/r} and @code{/b} can be used, attempting to use +both flag will give an error. + +The default memory range is the function surrounding the program +counter of the selected frame. A single argument to this command is a +program counter value; @value{GDBN} dumps the function surrounding +this value. When two arguments are given, they should be separated by +a comma, possibly surrounded by whitespace. The arguments specify a +range of addresses to dump, in one of two forms: + +@table @code +@item @var{start},@var{end} +the addresses from @var{start} (inclusive) to @var{end} (exclusive) +@item @var{start},+@var{length} +the addresses from @var{start} (inclusive) to +@code{@var{start}+@var{length}} (exclusive). +@end table + +@noindent +When 2 arguments are specified, the name of the function is also +printed (since there could be several functions in the given range). + +The argument(s) can be any expression yielding a numeric value, such as +@samp{0x32c4}, @samp{&main+10} or @samp{$pc - 8}. + +If the range of memory being disassembled contains current program counter, +the instruction at that location is shown with a @code{=>} marker. +@end table + +The following example shows the disassembly of a range of addresses of +HP PA-RISC 2.0 code: + +@smallexample +(@value{GDBP}) disas 0x32c4, 0x32e4 +Dump of assembler code from 0x32c4 to 0x32e4: + 0x32c4 : addil 0,dp + 0x32c8 : ldw 0x22c(sr0,r1),r26 + 0x32cc : ldil 0x3000,r31 + 0x32d0 : ble 0x3f8(sr4,r31) + 0x32d4 : ldo 0(r31),rp + 0x32d8 : addil -0x800,dp + 0x32dc : ldo 0x588(r1),r26 + 0x32e0 : ldil 0x3000,r31 +End of assembler dump. +@end smallexample + +The following two examples are for RISC-V, and demonstrates the +difference between the @code{/r} and @code{/b} modifiers. First with +@code{/b}, the bytes of the instruction are printed, in hex, in memory +order: + +@smallexample +(@value{GDBP}) disassemble /b 0x00010150,0x0001015c +Dump of assembler code from 0x10150 to 0x1015c: + 0x00010150 : 22 dc sw s0,56(sp) + 0x00010152 : 80 00 addi s0,sp,64 + 0x00010154 : 23 26 a4 fe sw a0,-20(s0) + 0x00010158 : 23 24 b4 fe sw a1,-24(s0) +End of assembler dump. +@end smallexample + +In contrast, with @code{/r} the bytes of the instruction are displayed +in the instruction order, for RISC-V this means that the bytes have been +swapped to little-endian order: + +@smallexample +(@value{GDBP}) disassemble /r 0x00010150,0x0001015c +Dump of assembler code from 0x10150 to 0x1015c: + 0x00010150 : dc22 sw s0,56(sp) + 0x00010152 : 0080 addi s0,sp,64 + 0x00010154 : fea42623 sw a0,-20(s0) + 0x00010158 : feb42423 sw a1,-24(s0) +End of assembler dump. +@end smallexample + +Here is an example showing mixed source+assembly for Intel x86 +with @code{/m} or @code{/s}, when the program is stopped just after +function prologue in a non-optimized function with no inline code. + +@smallexample +(@value{GDBP}) disas /m main +Dump of assembler code for function main: +5 @{ + 0x08048330 <+0>: push %ebp + 0x08048331 <+1>: mov %esp,%ebp + 0x08048333 <+3>: sub $0x8,%esp + 0x08048336 <+6>: and $0xfffffff0,%esp + 0x08048339 <+9>: sub $0x10,%esp + +6 printf ("Hello.\n"); +=> 0x0804833c <+12>: movl $0x8048440,(%esp) + 0x08048343 <+19>: call 0x8048284 + +7 return 0; +8 @} + 0x08048348 <+24>: mov $0x0,%eax + 0x0804834d <+29>: leave + 0x0804834e <+30>: ret + +End of assembler dump. +@end smallexample + +The @code{/m} option is deprecated as its output is not useful when +there is either inlined code or re-ordered code. +The @code{/s} option is the preferred choice. +Here is an example for AMD x86-64 showing the difference between +@code{/m} output and @code{/s} output. +This example has one inline function defined in a header file, +and the code is compiled with @samp{-O2} optimization. +Note how the @code{/m} output is missing the disassembly of +several instructions that are present in the @code{/s} output. + +@file{foo.h}: + +@smallexample +int +foo (int a) +@{ + if (a < 0) + return a * 2; + if (a == 0) + return 1; + return a + 10; +@} +@end smallexample + +@file{foo.c}: + +@smallexample +#include "foo.h" +volatile int x, y; +int +main () +@{ + x = foo (y); + return 0; +@} +@end smallexample + +@smallexample +(@value{GDBP}) disas /m main +Dump of assembler code for function main: +5 @{ + +6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + +7 return 0; +8 @} + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 + +End of assembler dump. +(@value{GDBP}) disas /s main +Dump of assembler code for function main: +foo.c: +5 @{ +6 x = foo (y); + 0x0000000000400400 <+0>: mov 0x200c2e(%rip),%eax # 0x601034 + +foo.h: +4 if (a < 0) + 0x0000000000400406 <+6>: test %eax,%eax + 0x0000000000400408 <+8>: js 0x400420 + +6 if (a == 0) +7 return 1; +8 return a + 10; + 0x000000000040040a <+10>: lea 0xa(%rax),%edx + 0x000000000040040d <+13>: test %eax,%eax + 0x000000000040040f <+15>: mov $0x1,%eax + 0x0000000000400414 <+20>: cmovne %edx,%eax + +foo.c: +6 x = foo (y); + 0x0000000000400417 <+23>: mov %eax,0x200c13(%rip) # 0x601030 + +7 return 0; +8 @} + 0x000000000040041d <+29>: xor %eax,%eax + 0x000000000040041f <+31>: retq + +foo.h: +5 return a * 2; + 0x0000000000400420 <+32>: add %eax,%eax + 0x0000000000400422 <+34>: jmp 0x400417 +End of assembler dump. +@end smallexample + +Here is another example showing raw instructions in hex for AMD x86-64, + +@smallexample +(@value{GDBP}) disas /r 0x400281,+10 +Dump of assembler code from 0x400281 to 0x40028b: + 0x0000000000400281: 38 36 cmp %dh,(%rsi) + 0x0000000000400283: 2d 36 34 2e 73 sub $0x732e3436,%eax + 0x0000000000400288: 6f outsl %ds:(%rsi),(%dx) + 0x0000000000400289: 2e 32 00 xor %cs:(%rax),%al +End of assembler dump. +@end smallexample + +Note that the @samp{disassemble} command's address arguments are +specified using expressions in your programming language +(@pxref{Expressions, ,Expressions}), not location specs +(@pxref{Location Specifications}). So, for example, if you want to +disassemble function @code{bar} in file @file{foo.c}, you must type +@samp{disassemble 'foo.c'::bar} and not @samp{disassemble foo.c:bar}. + +Some architectures have more than one commonly-used set of instruction +mnemonics or other syntax. + +For programs that were dynamically linked and use shared libraries, +instructions that call functions or branch to locations in the shared +libraries might show a seemingly bogus location---it's actually a +location of the relocation table. On some architectures, @value{GDBN} +might be able to resolve these to actual function names. + +@table @code +@kindex set disassembler-options +@cindex disassembler options +@item set disassembler-options @var{option1}[,@var{option2}@dots{}] +This command controls the passing of target specific information to +the disassembler. For a list of valid options, please refer to the +@code{-M}/@code{--disassembler-options} section of the @samp{objdump} +manual and/or the output of @kbd{objdump --help} +(@pxref{objdump,,objdump,binutils,The GNU Binary Utilities}). +The default value is the empty string. + +If it is necessary to specify more than one disassembler option, then +multiple options can be placed together into a comma separated list. +Currently this command is only supported on targets ARC, ARM, MIPS, +PowerPC and S/390. + +@kindex show disassembler-options +@item show disassembler-options +Show the current setting of the disassembler options. +@end table + +@table @code +@kindex set disassembly-flavor +@cindex Intel disassembly flavor +@cindex AT&T disassembly flavor +@item set disassembly-flavor @var{instruction-set} +Select the instruction set to use when disassembling the +program via the @code{disassemble} or @code{x/i} commands. + +Currently this command is only defined for the Intel x86 family. You +can set @var{instruction-set} to either @code{intel} or @code{att}. +The default is @code{att}, the AT&T flavor used by default by Unix +assemblers for x86-based targets. + +@kindex show disassembly-flavor +@item show disassembly-flavor +Show the current setting of the disassembly flavor. +@end table + +@table @code +@kindex set disassemble-next-line +@kindex show disassemble-next-line +@item set disassemble-next-line +@itemx show disassemble-next-line +Control whether or not @value{GDBN} will disassemble the next source +line or instruction when execution stops. If ON, @value{GDBN} will +display disassembly of the next source line when execution of the +program being debugged stops. This is @emph{in addition} to +displaying the source line itself, which @value{GDBN} always does if +possible. If the next source line cannot be displayed for some reason +(e.g., if @value{GDBN} cannot find the source file, or there's no line +info in the debug info), @value{GDBN} will display disassembly of the +next @emph{instruction} instead of showing the next source line. If +AUTO, @value{GDBN} will display disassembly of next instruction only +if the source line cannot be displayed. This setting causes +@value{GDBN} to display some feedback when you step through a function +with no line info or whose source file is unavailable. The default is +OFF, which means never display the disassembly of the next line or +instruction. +@end table + +@node Disable Reading Source +@section Disable Reading Source Code +@cindex source code, disable access + +In some cases it can be desirable to prevent @value{GDBN} from +accessing source code files. One case where this might be desirable +is if the source code files are located over a slow network +connection. + +The following command can be used to control whether @value{GDBN} +should access source code files or not: + +@table @code +@kindex set source open +@kindex show source open +@item set source open @r{[}on@r{|}off@r{]} +@itemx show source open +When this option is @code{on}, which is the default, @value{GDBN} will +access source code files when needed, for example to print source +lines when @value{GDBN} stops, or in response to the @code{list} +command. + +When this option is @code{off}, @value{GDBN} will not access source +code files. +@end table + +@node Data +@chapter Examining Data + +@cindex printing data +@cindex examining data +@kindex print +@kindex inspect +The usual way to examine data in your program is with the @code{print} +command (abbreviated @code{p}), or its synonym @code{inspect}. It +evaluates and prints the value of an expression of the language your +program is written in (@pxref{Languages, ,Using @value{GDBN} with +Different Languages}). It may also print the expression using a +Python-based pretty-printer (@pxref{Pretty Printing}). + +@table @code +@item print [[@var{options}] --] @var{expr} +@itemx print [[@var{options}] --] /@var{f} @var{expr} +@var{expr} is an expression (in the source language). By default the +value of @var{expr} is printed in a format appropriate to its data type; +you can choose a different format by specifying @samp{/@var{f}}, where +@var{f} is a letter specifying the format; see @ref{Output Formats,,Output +Formats}. + +@anchor{print options} +The @code{print} command supports a number of options that allow +overriding relevant global print settings as set by @code{set print} +subcommands: + +@table @code +@item -address [@code{on}|@code{off}] +Set printing of addresses. +Related setting: @ref{set print address}. + +@item -array [@code{on}|@code{off}] +Pretty formatting of arrays. +Related setting: @ref{set print array}. + +@item -array-indexes [@code{on}|@code{off}] +Set printing of array indexes. +Related setting: @ref{set print array-indexes}. + +@item -characters @var{number-of-characters}|@code{elements}|@code{unlimited} +Set limit on string characters to print. The value @code{elements} +causes the limit on array elements to print to be used. The value +@code{unlimited} causes there to be no limit. Related setting: +@ref{set print characters}. + +@item -elements @var{number-of-elements}|@code{unlimited} +Set limit on array elements and optionally string characters to print. +See @ref{set print characters}, and the @code{-characters} option above +for when this option applies to strings. The value @code{unlimited} +causes there to be no limit. @xref{set print elements}, for a related +CLI command. + +@item -max-depth @var{depth}|@code{unlimited} +Set the threshold after which nested structures are replaced with +ellipsis. Related setting: @ref{set print max-depth}. + +@item -nibbles [@code{on}|@code{off}] +Set whether to print binary values in groups of four bits, known +as ``nibbles''. @xref{set print nibbles}. + +@item -memory-tag-violations [@code{on}|@code{off}] +Set printing of additional information about memory tag violations. +@xref{set print memory-tag-violations}. + +@item -null-stop [@code{on}|@code{off}] +Set printing of char arrays to stop at first null char. Related +setting: @ref{set print null-stop}. + +@item -object [@code{on}|@code{off}] +Set printing C@t{++} virtual function tables. Related setting: +@ref{set print object}. + +@item -pretty [@code{on}|@code{off}] +Set pretty formatting of structures. Related setting: @ref{set print +pretty}. + +@item -raw-values [@code{on}|@code{off}] +Set whether to print values in raw form, bypassing any +pretty-printers for that value. Related setting: @ref{set print +raw-values}. + +@item -repeats @var{number-of-repeats}|@code{unlimited} +Set threshold for repeated print elements. @code{unlimited} causes +all elements to be individually printed. Related setting: @ref{set +print repeats}. + +@item -static-members [@code{on}|@code{off}] +Set printing C@t{++} static members. Related setting: @ref{set print +static-members}. + +@item -symbol [@code{on}|@code{off}] +Set printing of symbol names when printing pointers. Related setting: +@ref{set print symbol}. + +@item -union [@code{on}|@code{off}] +Set printing of unions interior to structures. Related setting: +@ref{set print union}. + +@item -vtbl [@code{on}|@code{off}] +Set printing of C++ virtual function tables. Related setting: +@ref{set print vtbl}. +@end table + +Because the @code{print} command accepts arbitrary expressions which +may look like options (including abbreviations), if you specify any +command option, then you must use a double dash (@code{--}) to mark +the end of option processing. + +For example, this prints the value of the @code{-p} expression: + +@smallexample +(@value{GDBP}) print -p +@end smallexample + +While this repeats the last value in the value history (see below) +with the @code{-pretty} option in effect: + +@smallexample +(@value{GDBP}) print -p -- +@end smallexample + +Here is an example including both on option and an expression: + +@smallexample +@group +(@value{GDBP}) print -pretty -- *myptr +$1 = @{ + next = 0x0, + flags = @{ + sweet = 1, + sour = 1 + @}, + meat = 0x54 "Pork" +@} +@end group +@end smallexample + +@item print [@var{options}] +@itemx print [@var{options}] /@var{f} +@cindex reprint the last value +If you omit @var{expr}, @value{GDBN} displays the last value again (from the +@dfn{value history}; @pxref{Value History, ,Value History}). This allows you to +conveniently inspect the same value in an alternative format. +@end table + +If the architecture supports memory tagging, the @code{print} command will +display pointer/memory tag mismatches if what is being printed is a pointer +or reference type. @xref{Memory Tagging}. + +A more low-level way of examining data is with the @code{x} command. +It examines data in memory at a specified address and prints it in a +specified format. @xref{Memory, ,Examining Memory}. + +If you are interested in information about types, or about how the +fields of a struct or a class are declared, use the @code{ptype @var{expr}} +command rather than @code{print}. @xref{Symbols, ,Examining the Symbol +Table}. + +@cindex exploring hierarchical data structures +@kindex explore +Another way of examining values of expressions and type information is +through the Python extension command @code{explore} (available only if +the @value{GDBN} build is configured with @code{--with-python}). It +offers an interactive way to start at the highest level (or, the most +abstract level) of the data type of an expression (or, the data type +itself) and explore all the way down to leaf scalar values/fields +embedded in the higher level data types. + +@table @code +@item explore @var{arg} +@var{arg} is either an expression (in the source language), or a type +visible in the current context of the program being debugged. +@end table + +The working of the @code{explore} command can be illustrated with an +example. If a data type @code{struct ComplexStruct} is defined in your +C program as + +@smallexample +struct SimpleStruct +@{ + int i; + double d; +@}; + +struct ComplexStruct +@{ + struct SimpleStruct *ss_p; + int arr[10]; +@}; +@end smallexample + +@noindent +followed by variable declarations as + +@smallexample +struct SimpleStruct ss = @{ 10, 1.11 @}; +struct ComplexStruct cs = @{ &ss, @{ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9 @} @}; +@end smallexample + +@noindent +then, the value of the variable @code{cs} can be explored using the +@code{explore} command as follows. + +@smallexample +(@value{GDBP}) explore cs +The value of `cs' is a struct/class of type `struct ComplexStruct' with +the following fields: + + ss_p = + arr = + +Enter the field number of choice: +@end smallexample + +@noindent +Since the fields of @code{cs} are not scalar values, you are being +prompted to chose the field you want to explore. Let's say you choose +the field @code{ss_p} by entering @code{0}. Then, since this field is a +pointer, you will be asked if it is pointing to a single value. From +the declaration of @code{cs} above, it is indeed pointing to a single +value, hence you enter @code{y}. If you enter @code{n}, then you will +be asked if it were pointing to an array of values, in which case this +field will be explored as if it were an array. + +@smallexample +`cs.ss_p' is a pointer to a value of type `struct SimpleStruct' +Continue exploring it as a pointer to a single value [y/n]: y +The value of `*(cs.ss_p)' is a struct/class of type `struct +SimpleStruct' with the following fields: + + i = 10 .. (Value of type `int') + d = 1.1100000000000001 .. (Value of type `double') + +Press enter to return to parent value: +@end smallexample + +@noindent +If the field @code{arr} of @code{cs} was chosen for exploration by +entering @code{1} earlier, then since it is as array, you will be +prompted to enter the index of the element in the array that you want +to explore. + +@smallexample +`cs.arr' is an array of `int'. +Enter the index of the element you want to explore in `cs.arr': 5 + +`(cs.arr)[5]' is a scalar value of type `int'. + +(cs.arr)[5] = 4 + +Press enter to return to parent value: +@end smallexample + +In general, at any stage of exploration, you can go deeper towards the +leaf values by responding to the prompts appropriately, or hit the +return key to return to the enclosing data structure (the @i{higher} +level data structure). + +Similar to exploring values, you can use the @code{explore} command to +explore types. Instead of specifying a value (which is typically a +variable name or an expression valid in the current context of the +program being debugged), you specify a type name. If you consider the +same example as above, your can explore the type +@code{struct ComplexStruct} by passing the argument +@code{struct ComplexStruct} to the @code{explore} command. + +@smallexample +(@value{GDBP}) explore struct ComplexStruct +@end smallexample + +@noindent +By responding to the prompts appropriately in the subsequent interactive +session, you can explore the type @code{struct ComplexStruct} in a +manner similar to how the value @code{cs} was explored in the above +example. + +The @code{explore} command also has two sub-commands, +@code{explore value} and @code{explore type}. The former sub-command is +a way to explicitly specify that value exploration of the argument is +being invoked, while the latter is a way to explicitly specify that type +exploration of the argument is being invoked. + +@table @code +@item explore value @var{expr} +@cindex explore value +This sub-command of @code{explore} explores the value of the +expression @var{expr} (if @var{expr} is an expression valid in the +current context of the program being debugged). The behavior of this +command is identical to that of the behavior of the @code{explore} +command being passed the argument @var{expr}. + +@item explore type @var{arg} +@cindex explore type +This sub-command of @code{explore} explores the type of @var{arg} (if +@var{arg} is a type visible in the current context of program being +debugged), or the type of the value/expression @var{arg} (if @var{arg} +is an expression valid in the current context of the program being +debugged). If @var{arg} is a type, then the behavior of this command is +identical to that of the @code{explore} command being passed the +argument @var{arg}. If @var{arg} is an expression, then the behavior of +this command will be identical to that of the @code{explore} command +being passed the type of @var{arg} as the argument. +@end table + +@menu +* Expressions:: Expressions +* Ambiguous Expressions:: Ambiguous Expressions +* Variables:: Program variables +* Arrays:: Artificial arrays +* Output Formats:: Output formats +* Memory:: Examining memory +* Memory Tagging:: Memory Tagging +* Auto Display:: Automatic display +* Print Settings:: Print settings +* Pretty Printing:: Python pretty printing +* Value History:: Value history +* Convenience Vars:: Convenience variables +* Convenience Funs:: Convenience functions +* Registers:: Registers +* Floating Point Hardware:: Floating point hardware +* Vector Unit:: Vector Unit +* OS Information:: Auxiliary data provided by operating system +* Memory Region Attributes:: Memory region attributes +* Dump/Restore Files:: Copy between memory and a file +* Core File Generation:: Cause a program dump its core +* Character Sets:: Debugging programs that use a different + character set than GDB does +* Caching Target Data:: Data caching for targets +* Searching Memory:: Searching memory for a sequence of bytes +* Value Sizes:: Managing memory allocated for values +@end menu + +@node Expressions +@section Expressions + +@cindex expressions +@code{print} and many other @value{GDBN} commands accept an expression and +compute its value. Any kind of constant, variable or operator defined +by the programming language you are using is valid in an expression in +@value{GDBN}. This includes conditional expressions, function calls, +casts, and string constants. It also includes preprocessor macros, if +you compiled your program to include this information; see +@ref{Compilation}. + +@cindex arrays in expressions +@value{GDBN} supports array constants in expressions input by +the user. The syntax is @{@var{element}, @var{element}@dots{}@}. For example, +you can use the command @code{print @{1, 2, 3@}} to create an array +of three integers. If you pass an array to a function or assign it +to a program variable, @value{GDBN} copies the array to memory that +is @code{malloc}ed in the target program. + +Because C is so widespread, most of the expressions shown in examples in +this manual are in C. @xref{Languages, , Using @value{GDBN} with Different +Languages}, for information on how to use expressions in other +languages. + +In this section, we discuss operators that you can use in @value{GDBN} +expressions regardless of your programming language. + +@cindex casts, in expressions +Casts are supported in all languages, not just in C, because it is so +useful to cast a number into a pointer in order to examine a structure +at that address in memory. +@c FIXME: casts supported---Mod2 true? + +@value{GDBN} supports these operators, in addition to those common +to programming languages: + +@table @code +@item @@ +@samp{@@} is a binary operator for treating parts of memory as arrays. +@xref{Arrays, ,Artificial Arrays}, for more information. + +@item :: +@samp{::} allows you to specify a variable in terms of the file or +function where it is defined. @xref{Variables, ,Program Variables}. + +@cindex @{@var{type}@} +@cindex type casting memory +@cindex memory, viewing as typed object +@cindex casts, to view memory +@item @{@var{type}@} @var{addr} +Refers to an object of type @var{type} stored at address @var{addr} in +memory. The address @var{addr} may be any expression whose value is +an integer or pointer (but parentheses are required around binary +operators, just as in a cast). This construct is allowed regardless +of what kind of data is normally supposed to reside at @var{addr}. +@end table + +@node Ambiguous Expressions +@section Ambiguous Expressions +@cindex ambiguous expressions + +Expressions can sometimes contain some ambiguous elements. For instance, +some programming languages (notably Ada, C@t{++} and Objective-C) permit +a single function name to be defined several times, for application in +different contexts. This is called @dfn{overloading}. Another example +involving Ada is generics. A @dfn{generic package} is similar to C@t{++} +templates and is typically instantiated several times, resulting in +the same function name being defined in different contexts. + +In some cases and depending on the language, it is possible to adjust +the expression to remove the ambiguity. For instance in C@t{++}, you +can specify the signature of the function you want to break on, as in +@kbd{break @var{function}(@var{types})}. In Ada, using the fully +qualified name of your function often makes the expression unambiguous +as well. + +When an ambiguity that needs to be resolved is detected, the debugger +has the capability to display a menu of numbered choices for each +possibility, and then waits for the selection with the prompt @samp{>}. +The first option is always @samp{[0] cancel}, and typing @kbd{0 @key{RET}} +aborts the current command. If the command in which the expression was +used allows more than one choice to be selected, the next option in the +menu is @samp{[1] all}, and typing @kbd{1 @key{RET}} selects all possible +choices. + +For example, the following session excerpt shows an attempt to set a +breakpoint at the overloaded symbol @code{String::after}. +We choose three particular definitions of that function name: + +@c FIXME! This is likely to change to show arg type lists, at least +@smallexample +@group +(@value{GDBP}) b String::after +[0] cancel +[1] all +[2] file:String.cc; line number:867 +[3] file:String.cc; line number:860 +[4] file:String.cc; line number:875 +[5] file:String.cc; line number:853 +[6] file:String.cc; line number:846 +[7] file:String.cc; line number:735 +> 2 4 6 +Breakpoint 1 at 0xb26c: file String.cc, line 867. +Breakpoint 2 at 0xb344: file String.cc, line 875. +Breakpoint 3 at 0xafcc: file String.cc, line 846. +Multiple breakpoints were set. +Use the "delete" command to delete unwanted + breakpoints. +(@value{GDBP}) +@end group +@end smallexample + +@table @code +@kindex set multiple-symbols +@item set multiple-symbols @var{mode} +@cindex multiple-symbols menu + +This option allows you to adjust the debugger behavior when an expression +is ambiguous. + +By default, @var{mode} is set to @code{all}. If the command with which +the expression is used allows more than one choice, then @value{GDBN} +automatically selects all possible choices. For instance, inserting +a breakpoint on a function using an ambiguous name results in a breakpoint +inserted on each possible match. However, if a unique choice must be made, +then @value{GDBN} uses the menu to help you disambiguate the expression. +For instance, printing the address of an overloaded function will result +in the use of the menu. + +When @var{mode} is set to @code{ask}, the debugger always uses the menu +when an ambiguity is detected. + +Finally, when @var{mode} is set to @code{cancel}, the debugger reports +an error due to the ambiguity and the command is aborted. + +@kindex show multiple-symbols +@item show multiple-symbols +Show the current value of the @code{multiple-symbols} setting. +@end table + +@node Variables +@section Program Variables + +The most common kind of expression to use is the name of a variable +in your program. + +Variables in expressions are understood in the selected stack frame +(@pxref{Selection, ,Selecting a Frame}); they must be either: + +@itemize @bullet +@item +global (or file-static) +@end itemize + +@noindent or + +@itemize @bullet +@item +visible according to the scope rules of the +programming language from the point of execution in that frame +@end itemize + +@noindent This means that in the function + +@smallexample +foo (a) + int a; +@{ + bar (a); + @{ + int b = test (); + bar (b); + @} +@} +@end smallexample + +@noindent +you can examine and use the variable @code{a} whenever your program is +executing within the function @code{foo}, but you can only use or +examine the variable @code{b} while your program is executing inside +the block where @code{b} is declared. + +@cindex variable name conflict +There is an exception: you can refer to a variable or function whose +scope is a single source file even if the current execution point is not +in this file. But it is possible to have more than one such variable or +function with the same name (in different source files). If that +happens, referring to that name has unpredictable effects. If you wish, +you can specify a static variable in a particular function or file by +using the colon-colon (@code{::}) notation: + +@cindex colon-colon, context for variables/functions +@ifnotinfo +@c info cannot cope with a :: index entry, but why deprive hard copy readers? +@cindex @code{::}, context for variables/functions +@end ifnotinfo +@smallexample +@var{file}::@var{variable} +@var{function}::@var{variable} +@end smallexample + +@noindent +Here @var{file} or @var{function} is the name of the context for the +static @var{variable}. In the case of file names, you can use quotes to +make sure @value{GDBN} parses the file name as a single word---for example, +to print a global value of @code{x} defined in @file{f2.c}: + +@smallexample +(@value{GDBP}) p 'f2.c'::x +@end smallexample + +The @code{::} notation is normally used for referring to +static variables, since you typically disambiguate uses of local variables +in functions by selecting the appropriate frame and using the +simple name of the variable. However, you may also use this notation +to refer to local variables in frames enclosing the selected frame: + +@smallexample +void +foo (int a) +@{ + if (a < 10) + bar (a); + else + process (a); /* Stop here */ +@} + +int +bar (int a) +@{ + foo (a + 5); +@} +@end smallexample + +@noindent +For example, if there is a breakpoint at the commented line, +here is what you might see +when the program stops after executing the call @code{bar(0)}: + +@smallexample +(@value{GDBP}) p a +$1 = 10 +(@value{GDBP}) p bar::a +$2 = 5 +(@value{GDBP}) up 2 +#2 0x080483d0 in foo (a=5) at foobar.c:12 +(@value{GDBP}) p a +$3 = 5 +(@value{GDBP}) p bar::a +$4 = 0 +@end smallexample + +@cindex C@t{++} scope resolution +These uses of @samp{::} are very rarely in conflict with the very +similar use of the same notation in C@t{++}. When they are in +conflict, the C@t{++} meaning takes precedence; however, this can be +overridden by quoting the file or function name with single quotes. + +For example, suppose the program is stopped in a method of a class +that has a field named @code{includefile}, and there is also an +include file named @file{includefile} that defines a variable, +@code{some_global}. + +@smallexample +(@value{GDBP}) p includefile +$1 = 23 +(@value{GDBP}) p includefile::some_global +A syntax error in expression, near `'. +(@value{GDBP}) p 'includefile'::some_global +$2 = 27 +@end smallexample + +@cindex wrong values +@cindex variable values, wrong +@cindex function entry/exit, wrong values of variables +@cindex optimized code, wrong values of variables +@quotation +@emph{Warning:} Occasionally, a local variable may appear to have the +wrong value at certain points in a function---just after entry to a new +scope, and just before exit. +@end quotation +You may see this problem when you are stepping by machine instructions. +This is because, on most machines, it takes more than one instruction to +set up a stack frame (including local variable definitions); if you are +stepping by machine instructions, variables may appear to have the wrong +values until the stack frame is completely built. On exit, it usually +also takes more than one machine instruction to destroy a stack frame; +after you begin stepping through that group of instructions, local +variable definitions may be gone. + +This may also happen when the compiler does significant optimizations. +To be sure of always seeing accurate values, turn off all optimization +when compiling. + +@cindex ``No symbol "foo" in current context'' +Another possible effect of compiler optimizations is to optimize +unused variables out of existence, or assign variables to registers (as +opposed to memory addresses). Depending on the support for such cases +offered by the debug info format used by the compiler, @value{GDBN} +might not be able to display values for such local variables. If that +happens, @value{GDBN} will print a message like this: + +@smallexample +No symbol "foo" in current context. +@end smallexample + +To solve such problems, either recompile without optimizations, or use a +different debug info format, if the compiler supports several such +formats. @xref{Compilation}, for more information on choosing compiler +options. @xref{C, ,C and C@t{++}}, for more information about debug +info formats that are best suited to C@t{++} programs. + +If you ask to print an object whose contents are unknown to +@value{GDBN}, e.g., because its data type is not completely specified +by the debug information, @value{GDBN} will say @samp{}. @xref{Symbols, incomplete type}, for more about this. + +@cindex no debug info variables +If you try to examine or use the value of a (global) variable for +which @value{GDBN} has no type information, e.g., because the program +includes no debug information, @value{GDBN} displays an error message. +@xref{Symbols, unknown type}, for more about unknown types. If you +cast the variable to its declared type, @value{GDBN} gets the +variable's value using the cast-to type as the variable's type. For +example, in a C program: + +@smallexample + (@value{GDBP}) p var + 'var' has unknown type; cast it to its declared type + (@value{GDBP}) p (float) var + $1 = 3.14 +@end smallexample + +If you append @kbd{@@entry} string to a function parameter name you get its +value at the time the function got called. If the value is not available an +error message is printed. Entry values are available only with some compilers. +Entry values are normally also printed at the function parameter list according +to @ref{set print entry-values}. + +@smallexample +Breakpoint 1, d (i=30) at gdb.base/entry-value.c:29 +29 i++; +(@value{GDBP}) next +30 e (i); +(@value{GDBP}) print i +$1 = 31 +(@value{GDBP}) print i@@entry +$2 = 30 +@end smallexample + +Strings are identified as arrays of @code{char} values without specified +signedness. Arrays of either @code{signed char} or @code{unsigned char} get +printed as arrays of 1 byte sized integers. @code{-fsigned-char} or +@code{-funsigned-char} @value{NGCC} options have no effect as @value{GDBN} +defines literal string type @code{"char"} as @code{char} without a sign. +For program code + +@smallexample +char var0[] = "A"; +signed char var1[] = "A"; +@end smallexample + +You get during debugging +@smallexample +(@value{GDBP}) print var0 +$1 = "A" +(@value{GDBP}) print var1 +$2 = @{65 'A', 0 '\0'@} +@end smallexample + +@node Arrays +@section Artificial Arrays + +@cindex artificial array +@cindex arrays +@kindex @@@r{, referencing memory as an array} +It is often useful to print out several successive objects of the +same type in memory; a section of an array, or an array of +dynamically determined size for which only a pointer exists in the +program. + +You can do this by referring to a contiguous span of memory as an +@dfn{artificial array}, using the binary operator @samp{@@}. The left +operand of @samp{@@} should be the first element of the desired array +and be an individual object. The right operand should be the desired length +of the array. The result is an array value whose elements are all of +the type of the left argument. The first element is actually the left +argument; the second element comes from bytes of memory immediately +following those that hold the first element, and so on. Here is an +example. If a program says + +@smallexample +int *array = (int *) malloc (len * sizeof (int)); +@end smallexample + +@noindent +you can print the contents of @code{array} with + +@smallexample +p *array@@len +@end smallexample + +The left operand of @samp{@@} must reside in memory. Array values made +with @samp{@@} in this way behave just like other arrays in terms of +subscripting, and are coerced to pointers when used in expressions. +Artificial arrays most often appear in expressions via the value history +(@pxref{Value History, ,Value History}), after printing one out. + +Another way to create an artificial array is to use a cast. +This re-interprets a value as if it were an array. +The value need not be in memory: +@smallexample +(@value{GDBP}) p/x (short[2])0x12345678 +$1 = @{0x1234, 0x5678@} +@end smallexample + +As a convenience, if you leave the array length out (as in +@samp{(@var{type}[])@var{value}}) @value{GDBN} calculates the size to fill +the value (as @samp{sizeof(@var{value})/sizeof(@var{type})}: +@smallexample +(@value{GDBP}) p/x (short[])0x12345678 +$2 = @{0x1234, 0x5678@} +@end smallexample + +Sometimes the artificial array mechanism is not quite enough; in +moderately complex data structures, the elements of interest may not +actually be adjacent---for example, if you are interested in the values +of pointers in an array. One useful work-around in this situation is +to use a convenience variable (@pxref{Convenience Vars, ,Convenience +Variables}) as a counter in an expression that prints the first +interesting value, and then repeat that expression via @key{RET}. For +instance, suppose you have an array @code{dtab} of pointers to +structures, and you are interested in the values of a field @code{fv} +in each structure. Here is an example of what you might type: + +@smallexample +set $i = 0 +p dtab[$i++]->fv +@key{RET} +@key{RET} +@dots{} +@end smallexample + +@node Output Formats +@section Output Formats + +@cindex formatted output +@cindex output formats +By default, @value{GDBN} prints a value according to its data type. Sometimes +this is not what you want. For example, you might want to print a number +in hex, or a pointer in decimal. Or you might want to view data in memory +at a certain address as a character string or as an instruction. To do +these things, specify an @dfn{output format} when you print a value. + +The simplest use of output formats is to say how to print a value +already computed. This is done by starting the arguments of the +@code{print} command with a slash and a format letter. The format +letters supported are: + +@table @code +@item x +Print the binary representation of the value in hexadecimal. + +@item d +Print the binary representation of the value in decimal. + +@item u +Print the binary representation of the value as an decimal, as if it +were unsigned. + +@item o +Print the binary representation of the value in octal. + +@item t +Print the binary representation of the value in binary. The letter +@samp{t} stands for ``two''. @footnote{@samp{b} cannot be used +because these format letters are also used with the @code{x} command, +where @samp{b} stands for ``byte''; see @ref{Memory,,Examining +Memory}.} + +@item a +@cindex unknown address, locating +@cindex locate address +Print as an address, both absolute in hexadecimal and as an offset from +the nearest preceding symbol. You can use this format used to discover +where (in what function) an unknown address is located: + +@smallexample +(@value{GDBP}) p/a 0x54320 +$3 = 0x54320 <_initialize_vx+396> +@end smallexample + +@noindent +The command @code{info symbol 0x54320} yields similar results. +@xref{Symbols, info symbol}. + +@item c +Cast the value to an integer (unlike other formats, this does not just +reinterpret the underlying bits) and print it as a character constant. +This prints both the numerical value and its character representation. +The character representation is replaced with the octal escape +@samp{\nnn} for characters outside the 7-bit @sc{ascii} range. + +Without this format, @value{GDBN} displays @code{char}, +@w{@code{unsigned char}}, and @w{@code{signed char}} data as character +constants. Single-byte members of vectors are displayed as integer +data. + +@item f +Regard the bits of the value as a floating point number and print +using typical floating point syntax. + +@item s +@cindex printing strings +@cindex printing byte arrays +Regard as a string, if possible. With this format, pointers to single-byte +data are displayed as null-terminated strings and arrays of single-byte data +are displayed as fixed-length strings. Other values are displayed in their +natural types. + +Without this format, @value{GDBN} displays pointers to and arrays of +@code{char}, @w{@code{unsigned char}}, and @w{@code{signed char}} as +strings. Single-byte members of a vector are displayed as an integer +array. + +@item z +Like @samp{x} formatting, the value is treated as an integer and +printed as hexadecimal, but leading zeros are printed to pad the value +to the size of the integer type. + +@item r +@cindex raw printing +Print using the @samp{raw} formatting. By default, @value{GDBN} will +use a Python-based pretty-printer, if one is available (@pxref{Pretty +Printing}). This typically results in a higher-level display of the +value's contents. The @samp{r} format bypasses any Python +pretty-printer which might exist. +@end table + +For example, to print the program counter in hex (@pxref{Registers}), type + +@smallexample +p/x $pc +@end smallexample + +@noindent +Note that no space is required before the slash; this is because command +names in @value{GDBN} cannot contain a slash. + +To reprint the last value in the value history with a different format, +you can use the @code{print} command with just a format and no +expression. For example, @samp{p/x} reprints the last value in hex. + +@node Memory +@section Examining Memory + +You can use the command @code{x} (for ``examine'') to examine memory in +any of several formats, independently of your program's data types. + +@cindex examining memory +@table @code +@kindex x @r{(examine memory)} +@item x/@var{nfu} @var{addr} +@itemx x @var{addr} +@itemx x +Use the @code{x} command to examine memory. +@end table + +@var{n}, @var{f}, and @var{u} are all optional parameters that specify how +much memory to display and how to format it; @var{addr} is an +expression giving the address where you want to start displaying memory. +If you use defaults for @var{nfu}, you need not type the slash @samp{/}. +Several commands set convenient defaults for @var{addr}. + +@table @r +@item @var{n}, the repeat count +The repeat count is a decimal integer; the default is 1. It specifies +how much memory (counting by units @var{u}) to display. If a negative +number is specified, memory is examined backward from @var{addr}. +@c This really is **decimal**; unaffected by 'set radix' as of GDB +@c 4.1.2. + +@item @var{f}, the display format +The display format is one of the formats used by @code{print} +(@samp{x}, @samp{d}, @samp{u}, @samp{o}, @samp{t}, @samp{a}, @samp{c}, +@samp{f}, @samp{s}), @samp{i} (for machine instructions) and +@samp{m} (for displaying memory tags). +The default is @samp{x} (hexadecimal) initially. The default changes +each time you use either @code{x} or @code{print}. + +@item @var{u}, the unit size +The unit size is any of + +@table @code +@item b +Bytes. +@item h +Halfwords (two bytes). +@item w +Words (four bytes). This is the initial default. +@item g +Giant words (eight bytes). +@end table + +Each time you specify a unit size with @code{x}, that size becomes the +default unit the next time you use @code{x}. For the @samp{i} format, +the unit size is ignored and is normally not written. For the @samp{s} format, +the unit size defaults to @samp{b}, unless it is explicitly given. +Use @kbd{x /hs} to display 16-bit char strings and @kbd{x /ws} to display +32-bit strings. The next use of @kbd{x /s} will again display 8-bit strings. +Note that the results depend on the programming language of the +current compilation unit. If the language is C, the @samp{s} +modifier will use the UTF-16 encoding while @samp{w} will use +UTF-32. The encoding is set by the programming language and cannot +be altered. + +@item @var{addr}, starting display address +@var{addr} is the address where you want @value{GDBN} to begin displaying +memory. The expression need not have a pointer value (though it may); +it is always interpreted as an integer address of a byte of memory. +@xref{Expressions, ,Expressions}, for more information on expressions. The default for +@var{addr} is usually just after the last address examined---but several +other commands also set the default address: @code{info breakpoints} (to +the address of the last breakpoint listed), @code{info line} (to the +starting address of a line), and @code{print} (if you use it to display +a value from memory). +@end table + +For example, @samp{x/3uh 0x54320} is a request to display three halfwords +(@code{h}) of memory, formatted as unsigned decimal integers (@samp{u}), +starting at address @code{0x54320}. @samp{x/4xw $sp} prints the four +words (@samp{w}) of memory above the stack pointer (here, @samp{$sp}; +@pxref{Registers, ,Registers}) in hexadecimal (@samp{x}). + +You can also specify a negative repeat count to examine memory backward +from the given address. For example, @samp{x/-3uh 0x54320} prints three +halfwords (@code{h}) at @code{0x5431a}, @code{0x5431c}, and @code{0x5431e}. + +Since the letters indicating unit sizes are all distinct from the +letters specifying output formats, you do not have to remember whether +unit size or format comes first; either order works. The output +specifications @samp{4xw} and @samp{4wx} mean exactly the same thing. +(However, the count @var{n} must come first; @samp{wx4} does not work.) + +Even though the unit size @var{u} is ignored for the formats @samp{s} +and @samp{i}, you might still want to use a count @var{n}; for example, +@samp{3i} specifies that you want to see three machine instructions, +including any operands. For convenience, especially when used with +the @code{display} command, the @samp{i} format also prints branch delay +slot instructions, if any, beyond the count specified, which immediately +follow the last instruction that is within the count. The command +@code{disassemble} gives an alternative way of inspecting machine +instructions; see @ref{Machine Code,,Source and Machine Code}. + +If a negative repeat count is specified for the formats @samp{s} or @samp{i}, +the command displays null-terminated strings or instructions before the given +address as many as the absolute value of the given number. For the @samp{i} +format, we use line number information in the debug info to accurately locate +instruction boundaries while disassembling backward. If line info is not +available, the command stops examining memory with an error message. + +All the defaults for the arguments to @code{x} are designed to make it +easy to continue scanning memory with minimal specifications each time +you use @code{x}. For example, after you have inspected three machine +instructions with @samp{x/3i @var{addr}}, you can inspect the next seven +with just @samp{x/7}. If you use @key{RET} to repeat the @code{x} command, +the repeat count @var{n} is used again; the other arguments default as +for successive uses of @code{x}. + +When examining machine instructions, the instruction at current program +counter is shown with a @code{=>} marker. For example: + +@smallexample +(@value{GDBP}) x/5i $pc-6 + 0x804837f : mov %esp,%ebp + 0x8048381 : push %ecx + 0x8048382 : sub $0x4,%esp +=> 0x8048385 : movl $0x8048460,(%esp) + 0x804838c : call 0x80482d4 +@end smallexample + +If the architecture supports memory tagging, the tags can be displayed by +using @samp{m}. @xref{Memory Tagging}. + +The information will be displayed once per granule size +(the amount of bytes a particular memory tag covers). For example, AArch64 +has a granule size of 16 bytes, so it will display a tag every 16 bytes. + +Due to the way @value{GDBN} prints information with the @code{x} command (not +aligned to a particular boundary), the tag information will refer to the +initial address displayed on a particular line. If a memory tag boundary +is crossed in the middle of a line displayed by the @code{x} command, it +will be displayed on the next line. + +The @samp{m} format doesn't affect any other specified formats that were +passed to the @code{x} command. + +@cindex @code{$_}, @code{$__}, and value history +The addresses and contents printed by the @code{x} command are not saved +in the value history because there is often too much of them and they +would get in the way. Instead, @value{GDBN} makes these values available for +subsequent use in expressions as values of the convenience variables +@code{$_} and @code{$__}. After an @code{x} command, the last address +examined is available for use in expressions in the convenience variable +@code{$_}. The contents of that address, as examined, are available in +the convenience variable @code{$__}. + +If the @code{x} command has a repeat count, the address and contents saved +are from the last memory unit printed; this is not the same as the last +address printed if several units were printed on the last line of output. + +@anchor{addressable memory unit} +@cindex addressable memory unit +Most targets have an addressable memory unit size of 8 bits. This means +that to each memory address are associated 8 bits of data. Some +targets, however, have other addressable memory unit sizes. +Within @value{GDBN} and this document, the term +@dfn{addressable memory unit} (or @dfn{memory unit} for short) is used +when explicitly referring to a chunk of data of that size. The word +@dfn{byte} is used to refer to a chunk of data of 8 bits, regardless of +the addressable memory unit size of the target. For most systems, +addressable memory unit is a synonym of byte. + +@cindex remote memory comparison +@cindex target memory comparison +@cindex verify remote memory image +@cindex verify target memory image +When you are debugging a program running on a remote target machine +(@pxref{Remote Debugging}), you may wish to verify the program's image +in the remote machine's memory against the executable file you +downloaded to the target. Or, on any target, you may want to check +whether the program has corrupted its own read-only sections. The +@code{compare-sections} command is provided for such situations. + +@table @code +@kindex compare-sections +@item compare-sections @r{[}@var{section-name}@r{|}@code{-r}@r{]} +Compare the data of a loadable section @var{section-name} in the +executable file of the program being debugged with the same section in +the target machine's memory, and report any mismatches. With no +arguments, compares all loadable sections. With an argument of +@code{-r}, compares all loadable read-only sections. + +Note: for remote targets, this command can be accelerated if the +target supports computing the CRC checksum of a block of memory +(@pxref{qCRC packet}). +@end table + +@node Memory Tagging +@section Memory Tagging + +Memory tagging is a memory protection technology that uses a pair of tags to +validate memory accesses through pointers. The tags are integer values +usually comprised of a few bits, depending on the architecture. + +There are two types of tags that are used in this setup: logical and +allocation. A logical tag is stored in the pointers themselves, usually at the +higher bits of the pointers. An allocation tag is the tag associated +with particular ranges of memory in the physical address space, against which +the logical tags from pointers are compared. + +The pointer tag (logical tag) must match the memory tag (allocation tag) +for the memory access to be valid. If the logical tag does not match the +allocation tag, that will raise a memory violation. + +Allocation tags cover multiple contiguous bytes of physical memory. This +range of bytes is called a memory tag granule and is architecture-specific. +For example, AArch64 has a tag granule of 16 bytes, meaning each allocation +tag spans 16 bytes of memory. + +If the underlying architecture supports memory tagging, like AArch64 MTE +or SPARC ADI do, @value{GDBN} can make use of it to validate pointers +against memory allocation tags. + +The @code{print} (@pxref{Data}) and @code{x} (@pxref{Memory}) commands will +display tag information when appropriate, and a command prefix of +@code{memory-tag} gives access to the various memory tagging commands. + +The @code{memory-tag} commands are the following: + +@table @code +@kindex memory-tag print-logical-tag +@item memory-tag print-logical-tag @var{pointer_expression} +Print the logical tag stored in @var{pointer_expression}. +@kindex memory-tag with-logical-tag +@item memory-tag with-logical-tag @var{pointer_expression} @var{tag_bytes} +Print the pointer given by @var{pointer_expression}, augmented with a logical +tag of @var{tag_bytes}. +@kindex memory-tag print-allocation-tag +@item memory-tag print-allocation-tag @var{address_expression} +Print the allocation tag associated with the memory address given by +@var{address_expression}. +@kindex memory-tag setatag +@item memory-tag setatag @var{starting_address} @var{length} @var{tag_bytes} +Set the allocation tag(s) for memory range @r{[}@var{starting_address}, +@var{starting_address} + @var{length}@r{)} to @var{tag_bytes}. +@kindex memory-tag check +@item memory-tag check @var{pointer_expression} +Check if the logical tag in the pointer given by @var{pointer_expression} +matches the allocation tag for the memory referenced by the pointer. + +This essentially emulates the hardware validation that is done when tagged +memory is accessed through a pointer, but does not cause a memory fault as +it would during hardware validation. + +It can be used to inspect potential memory tagging violations in the running +process, before any faults get triggered. +@end table + +@node Auto Display +@section Automatic Display +@cindex automatic display +@cindex display of expressions + +If you find that you want to print the value of an expression frequently +(to see how it changes), you might want to add it to the @dfn{automatic +display list} so that @value{GDBN} prints its value each time your program stops. +Each expression added to the list is given a number to identify it; +to remove an expression from the list, you specify that number. +The automatic display looks like this: + +@smallexample +2: foo = 38 +3: bar[5] = (struct hack *) 0x3804 +@end smallexample + +@noindent +This display shows item numbers, expressions and their current values. As with +displays you request manually using @code{x} or @code{print}, you can +specify the output format you prefer; in fact, @code{display} decides +whether to use @code{print} or @code{x} depending your format +specification---it uses @code{x} if you specify either the @samp{i} +or @samp{s} format, or a unit size; otherwise it uses @code{print}. + +@table @code +@kindex display +@item display @var{expr} +Add the expression @var{expr} to the list of expressions to display +each time your program stops. @xref{Expressions, ,Expressions}. + +@code{display} does not repeat if you press @key{RET} again after using it. + +@item display/@var{fmt} @var{expr} +For @var{fmt} specifying only a display format and not a size or +count, add the expression @var{expr} to the auto-display list but +arrange to display it each time in the specified format @var{fmt}. +@xref{Output Formats,,Output Formats}. + +@item display/@var{fmt} @var{addr} +For @var{fmt} @samp{i} or @samp{s}, or including a unit-size or a +number of units, add the expression @var{addr} as a memory address to +be examined each time your program stops. Examining means in effect +doing @samp{x/@var{fmt} @var{addr}}. @xref{Memory, ,Examining Memory}. +@end table + +For example, @samp{display/i $pc} can be helpful, to see the machine +instruction about to be executed each time execution stops (@samp{$pc} +is a common name for the program counter; @pxref{Registers, ,Registers}). + +@table @code +@kindex delete display +@kindex undisplay +@item undisplay @var{dnums}@dots{} +@itemx delete display @var{dnums}@dots{} +Remove items from the list of expressions to display. Specify the +numbers of the displays that you want affected with the command +argument @var{dnums}. It can be a single display number, one of the +numbers shown in the first field of the @samp{info display} display; +or it could be a range of display numbers, as in @code{2-4}. + +@code{undisplay} does not repeat if you press @key{RET} after using it. +(Otherwise you would just get the error @samp{No display number @dots{}}.) + +@kindex disable display +@item disable display @var{dnums}@dots{} +Disable the display of item numbers @var{dnums}. A disabled display +item is not printed automatically, but is not forgotten. It may be +enabled again later. Specify the numbers of the displays that you +want affected with the command argument @var{dnums}. It can be a +single display number, one of the numbers shown in the first field of +the @samp{info display} display; or it could be a range of display +numbers, as in @code{2-4}. + +@kindex enable display +@item enable display @var{dnums}@dots{} +Enable display of item numbers @var{dnums}. It becomes effective once +again in auto display of its expression, until you specify otherwise. +Specify the numbers of the displays that you want affected with the +command argument @var{dnums}. It can be a single display number, one +of the numbers shown in the first field of the @samp{info display} +display; or it could be a range of display numbers, as in @code{2-4}. + +@item display +Display the current values of the expressions on the list, just as is +done when your program stops. + +@kindex info display +@item info display +Print the list of expressions previously set up to display +automatically, each one with its item number, but without showing the +values. This includes disabled expressions, which are marked as such. +It also includes expressions which would not be displayed right now +because they refer to automatic variables not currently available. +@end table + +@cindex display disabled out of scope +If a display expression refers to local variables, then it does not make +sense outside the lexical context for which it was set up. Such an +expression is disabled when execution enters a context where one of its +variables is not defined. For example, if you give the command +@code{display last_char} while inside a function with an argument +@code{last_char}, @value{GDBN} displays this argument while your program +continues to stop inside that function. When it stops elsewhere---where +there is no variable @code{last_char}---the display is disabled +automatically. The next time your program stops where @code{last_char} +is meaningful, you can enable the display expression once again. + +@node Print Settings +@section Print Settings + +@cindex format options +@cindex print settings +@value{GDBN} provides the following ways to control how arrays, structures, +and symbols are printed. + +@noindent +These settings are useful for debugging programs in any language: + +@table @code +@kindex set print +@anchor{set print address} +@item set print address +@itemx set print address on +@cindex print/don't print memory addresses +@value{GDBN} prints memory addresses showing the location of stack +traces, structure values, pointer values, breakpoints, and so forth, +even when it also displays the contents of those addresses. The default +is @code{on}. For example, this is what a stack frame display looks like with +@code{set print address on}: + +@smallexample +@group +(@value{GDBP}) f +#0 set_quotes (lq=0x34c78 "<<", rq=0x34c88 ">>") + at input.c:530 +530 if (lquote != def_lquote) +@end group +@end smallexample + +@item set print address off +Do not print addresses when displaying their contents. For example, +this is the same stack frame displayed with @code{set print address off}: + +@smallexample +@group +(@value{GDBP}) set print addr off +(@value{GDBP}) f +#0 set_quotes (lq="<<", rq=">>") at input.c:530 +530 if (lquote != def_lquote) +@end group +@end smallexample + +You can use @samp{set print address off} to eliminate all machine +dependent displays from the @value{GDBN} interface. For example, with +@code{print address off}, you should get the same text for backtraces on +all machines---whether or not they involve pointer arguments. + +@kindex show print +@item show print address +Show whether or not addresses are to be printed. +@end table + +When @value{GDBN} prints a symbolic address, it normally prints the +closest earlier symbol plus an offset. If that symbol does not uniquely +identify the address (for example, it is a name whose scope is a single +source file), you may need to clarify. One way to do this is with +@code{info line}, for example @samp{info line *0x4537}. Alternately, +you can set @value{GDBN} to print the source file and line number when +it prints a symbolic address: + +@table @code +@item set print symbol-filename on +@cindex source file and line of a symbol +@cindex symbol, source file and line +Tell @value{GDBN} to print the source file name and line number of a +symbol in the symbolic form of an address. + +@item set print symbol-filename off +Do not print source file name and line number of a symbol. This is the +default. + +@item show print symbol-filename +Show whether or not @value{GDBN} will print the source file name and +line number of a symbol in the symbolic form of an address. +@end table + +Another situation where it is helpful to show symbol filenames and line +numbers is when disassembling code; @value{GDBN} shows you the line +number and source file that corresponds to each instruction. + +Also, you may wish to see the symbolic form only if the address being +printed is reasonably close to the closest earlier symbol: + +@table @code +@item set print max-symbolic-offset @var{max-offset} +@itemx set print max-symbolic-offset unlimited +@cindex maximum value for offset of closest symbol +Tell @value{GDBN} to only display the symbolic form of an address if the +offset between the closest earlier symbol and the address is less than +@var{max-offset}. The default is @code{unlimited}, which tells @value{GDBN} +to always print the symbolic form of an address if any symbol precedes +it. Zero is equivalent to @code{unlimited}. + +@item show print max-symbolic-offset +Ask how large the maximum offset is that @value{GDBN} prints in a +symbolic address. +@end table + +@cindex wild pointer, interpreting +@cindex pointer, finding referent +If you have a pointer and you are not sure where it points, try +@samp{set print symbol-filename on}. Then you can determine the name +and source file location of the variable where it points, using +@samp{p/a @var{pointer}}. This interprets the address in symbolic form. +For example, here @value{GDBN} shows that a variable @code{ptt} points +at another variable @code{t}, defined in @file{hi2.c}: + +@smallexample +(@value{GDBP}) set print symbol-filename on +(@value{GDBP}) p/a ptt +$4 = 0xe008 +@end smallexample + +@quotation +@emph{Warning:} For pointers that point to a local variable, @samp{p/a} +does not show the symbol name and filename of the referent, even with +the appropriate @code{set print} options turned on. +@end quotation + +You can also enable @samp{/a}-like formatting all the time using +@samp{set print symbol on}: + +@anchor{set print symbol} +@table @code +@item set print symbol on +Tell @value{GDBN} to print the symbol corresponding to an address, if +one exists. + +@item set print symbol off +Tell @value{GDBN} not to print the symbol corresponding to an +address. In this mode, @value{GDBN} will still print the symbol +corresponding to pointers to functions. This is the default. + +@item show print symbol +Show whether @value{GDBN} will display the symbol corresponding to an +address. +@end table + +Other settings control how different kinds of objects are printed: + +@table @code +@anchor{set print array} +@item set print array +@itemx set print array on +@cindex pretty print arrays +Pretty print arrays. This format is more convenient to read, +but uses more space. The default is off. + +@item set print array off +Return to compressed format for arrays. + +@item show print array +Show whether compressed or pretty format is selected for displaying +arrays. + +@cindex print array indexes +@anchor{set print array-indexes} +@item set print array-indexes +@itemx set print array-indexes on +Print the index of each element when displaying arrays. May be more +convenient to locate a given element in the array or quickly find the +index of a given element in that printed array. The default is off. + +@item set print array-indexes off +Stop printing element indexes when displaying arrays. + +@item show print array-indexes +Show whether the index of each element is printed when displaying +arrays. + +@anchor{set print nibbles} +@item set print nibbles +@itemx set print nibbles on +@cindex print binary values in groups of four bits +Print binary values in groups of four bits, known as @dfn{nibbles}, +when using the print command of @value{GDBN} with the option @samp{/t}. +For example, this is what it looks like with @code{set print nibbles on}: + +@smallexample +@group +(@value{GDBP}) print val_flags +$1 = 1230 +(@value{GDBP}) print/t val_flags +$2 = 0100 1100 1110 +@end group +@end smallexample + +@item set print nibbles off +Don't printing binary values in groups. This is the default. + +@item show print nibbles +Show whether to print binary values in groups of four bits. + +@anchor{set print characters} +@item set print characters @var{number-of-characters} +@itemx set print characters elements +@itemx set print characters unlimited +@cindex number of string characters to print +@cindex limit on number of printed string characters +Set a limit on how many characters of a string @value{GDBN} will print. +If @value{GDBN} is printing a large string, it stops printing after it +has printed the number of characters set by the @code{set print +characters} command. This equally applies to multi-byte and wide +character strings, that is for strings whose character type is +@code{wchar_t}, @code{char16_t}, or @code{char32_t} it is the number of +actual characters rather than underlying bytes the encoding uses that +this setting controls. +Setting @var{number-of-characters} to @code{elements} means that the +limit on the number of characters to print follows one for array +elements; see @ref{set print elements}. +Setting @var{number-of-characters} to @code{unlimited} means that the +number of characters to print is unlimited. +When @value{GDBN} starts, this limit is set to @code{elements}. + +@item show print characters +Display the number of characters of a large string that @value{GDBN} +will print. + +@anchor{set print elements} +@item set print elements @var{number-of-elements} +@itemx set print elements unlimited +@cindex number of array elements to print +@cindex limit on number of printed array elements +Set a limit on how many elements of an array @value{GDBN} will print. +If @value{GDBN} is printing a large array, it stops printing after it has +printed the number of elements set by the @code{set print elements} command. +By default this limit also applies to the display of strings; see +@ref{set print characters}. +When @value{GDBN} starts, this limit is set to 200. +Setting @var{number-of-elements} to @code{unlimited} or zero means +that the number of elements to print is unlimited. + +When printing very large arrays, whose size is greater than +@code{max-value-size} (@pxref{set max-value-size,,max-value-size}), +if the @code{print elements} is set such that the size of the elements +being printed is less than or equal to @code{max-value-size}, then +@value{GDBN} will print the array (up to the @code{print elements} limit), +and only @code{max-value-size} worth of data will be added into the value +history (@pxref{Value History, ,Value History}). + +@item show print elements +Display the number of elements of a large array that @value{GDBN} will print. + +@anchor{set print frame-arguments} +@item set print frame-arguments @var{value} +@kindex set print frame-arguments +@cindex printing frame argument values +@cindex print all frame argument values +@cindex print frame argument values for scalars only +@cindex do not print frame arguments +This command allows to control how the values of arguments are printed +when the debugger prints a frame (@pxref{Frames}). The possible +values are: + +@table @code +@item all +The values of all arguments are printed. + +@item scalars +Print the value of an argument only if it is a scalar. The value of more +complex arguments such as arrays, structures, unions, etc, is replaced +by @code{@dots{}}. This is the default. Here is an example where +only scalar arguments are shown: + +@smallexample +#1 0x08048361 in call_me (i=3, s=@dots{}, ss=0xbf8d508c, u=@dots{}, e=green) + at frame-args.c:23 +@end smallexample + +@item none +None of the argument values are printed. Instead, the value of each argument +is replaced by @code{@dots{}}. In this case, the example above now becomes: + +@smallexample +#1 0x08048361 in call_me (i=@dots{}, s=@dots{}, ss=@dots{}, u=@dots{}, e=@dots{}) + at frame-args.c:23 +@end smallexample + +@item presence +Only the presence of arguments is indicated by @code{@dots{}}. +The @code{@dots{}} are not printed for function without any arguments. +None of the argument names and values are printed. +In this case, the example above now becomes: + +@smallexample +#1 0x08048361 in call_me (@dots{}) at frame-args.c:23 +@end smallexample + +@end table + +By default, only scalar arguments are printed. This command can be used +to configure the debugger to print the value of all arguments, regardless +of their type. However, it is often advantageous to not print the value +of more complex parameters. For instance, it reduces the amount of +information printed in each frame, making the backtrace more readable. +Also, it improves performance when displaying Ada frames, because +the computation of large arguments can sometimes be CPU-intensive, +especially in large applications. Setting @code{print frame-arguments} +to @code{scalars} (the default), @code{none} or @code{presence} avoids +this computation, thus speeding up the display of each Ada frame. + +@item show print frame-arguments +Show how the value of arguments should be displayed when printing a frame. + +@anchor{set print raw-frame-arguments} +@item set print raw-frame-arguments on +Print frame arguments in raw, non pretty-printed, form. + +@item set print raw-frame-arguments off +Print frame arguments in pretty-printed form, if there is a pretty-printer +for the value (@pxref{Pretty Printing}), +otherwise print the value in raw form. +This is the default. + +@item show print raw-frame-arguments +Show whether to print frame arguments in raw form. + +@anchor{set print entry-values} +@item set print entry-values @var{value} +@kindex set print entry-values +Set printing of frame argument values at function entry. In some cases +@value{GDBN} can determine the value of function argument which was passed by +the function caller, even if the value was modified inside the called function +and therefore is different. With optimized code, the current value could be +unavailable, but the entry value may still be known. + +The default value is @code{default} (see below for its description). Older +@value{GDBN} behaved as with the setting @code{no}. Compilers not supporting +this feature will behave in the @code{default} setting the same way as with the +@code{no} setting. + +This functionality is currently supported only by DWARF 2 debugging format and +the compiler has to produce @samp{DW_TAG_call_site} tags. With +@value{NGCC}, you need to specify @option{-O -g} during compilation, to get +this information. + +The @var{value} parameter can be one of the following: + +@table @code +@item no +Print only actual parameter values, never print values from function entry +point. +@smallexample +#0 equal (val=5) +#0 different (val=6) +#0 lost (val=) +#0 born (val=10) +#0 invalid (val=) +@end smallexample + +@item only +Print only parameter values from function entry point. The actual parameter +values are never printed. +@smallexample +#0 equal (val@@entry=5) +#0 different (val@@entry=5) +#0 lost (val@@entry=5) +#0 born (val@@entry=) +#0 invalid (val@@entry=) +@end smallexample + +@item preferred +Print only parameter values from function entry point. If value from function +entry point is not known while the actual value is known, print the actual +value for such parameter. +@smallexample +#0 equal (val@@entry=5) +#0 different (val@@entry=5) +#0 lost (val@@entry=5) +#0 born (val=10) +#0 invalid (val@@entry=) +@end smallexample + +@item if-needed +Print actual parameter values. If actual parameter value is not known while +value from function entry point is known, print the entry point value for such +parameter. +@smallexample +#0 equal (val=5) +#0 different (val=6) +#0 lost (val@@entry=5) +#0 born (val=10) +#0 invalid (val=) +@end smallexample + +@item both +Always print both the actual parameter value and its value from function entry +point, even if values of one or both are not available due to compiler +optimizations. +@smallexample +#0 equal (val=5, val@@entry=5) +#0 different (val=6, val@@entry=5) +#0 lost (val=, val@@entry=5) +#0 born (val=10, val@@entry=) +#0 invalid (val=, val@@entry=) +@end smallexample + +@item compact +Print the actual parameter value if it is known and also its value from +function entry point if it is known. If neither is known, print for the actual +value @code{}. If not in MI mode (@pxref{GDB/MI}) and if both +values are known and identical, print the shortened +@code{param=param@@entry=VALUE} notation. +@smallexample +#0 equal (val=val@@entry=5) +#0 different (val=6, val@@entry=5) +#0 lost (val@@entry=5) +#0 born (val=10) +#0 invalid (val=) +@end smallexample + +@item default +Always print the actual parameter value. Print also its value from function +entry point, but only if it is known. If not in MI mode (@pxref{GDB/MI}) and +if both values are known and identical, print the shortened +@code{param=param@@entry=VALUE} notation. +@smallexample +#0 equal (val=val@@entry=5) +#0 different (val=6, val@@entry=5) +#0 lost (val=, val@@entry=5) +#0 born (val=10) +#0 invalid (val=) +@end smallexample +@end table + +For analysis messages on possible failures of frame argument values at function +entry resolution see @ref{set debug entry-values}. + +@item show print entry-values +Show the method being used for printing of frame argument values at function +entry. + +@anchor{set print frame-info} +@item set print frame-info @var{value} +@kindex set print frame-info +@cindex printing frame information +@cindex frame information, printing +This command allows to control the information printed when +the debugger prints a frame. See @ref{Frames}, @ref{Backtrace}, +for a general explanation about frames and frame information. +Note that some other settings (such as @code{set print frame-arguments} +and @code{set print address}) are also influencing if and how some frame +information is displayed. In particular, the frame program counter is never +printed if @code{set print address} is off. + +The possible values for @code{set print frame-info} are: +@table @code +@item short-location +Print the frame level, the program counter (if not at the +beginning of the location source line), the function, the function +arguments. +@item location +Same as @code{short-location} but also print the source file and source line +number. +@item location-and-address +Same as @code{location} but print the program counter even if located at the +beginning of the location source line. +@item source-line +Print the program counter (if not at the beginning of the location +source line), the line number and the source line. +@item source-and-location +Print what @code{location} and @code{source-line} are printing. +@item auto +The information printed for a frame is decided automatically +by the @value{GDBN} command that prints a frame. +For example, @code{frame} prints the information printed by +@code{source-and-location} while @code{stepi} will switch between +@code{source-line} and @code{source-and-location} depending on the program +counter. +The default value is @code{auto}. +@end table + +@anchor{set print repeats} +@item set print repeats @var{number-of-repeats} +@itemx set print repeats unlimited +@cindex repeated array elements +Set the threshold for suppressing display of repeated array +elements. When the number of consecutive identical elements of an +array exceeds the threshold, @value{GDBN} prints the string +@code{""}, where @var{n} is the number of +identical repetitions, instead of displaying the identical elements +themselves. Setting the threshold to @code{unlimited} or zero will +cause all elements to be individually printed. The default threshold +is 10. + +@item show print repeats +Display the current threshold for printing repeated identical +elements. + +@anchor{set print max-depth} +@item set print max-depth @var{depth} +@item set print max-depth unlimited +@cindex printing nested structures +Set the threshold after which nested structures are replaced with +ellipsis, this can make visualising deeply nested structures easier. + +For example, given this C code + +@smallexample +typedef struct s1 @{ int a; @} s1; +typedef struct s2 @{ s1 b; @} s2; +typedef struct s3 @{ s2 c; @} s3; +typedef struct s4 @{ s3 d; @} s4; + +s4 var = @{ @{ @{ @{ 3 @} @} @} @}; +@end smallexample + +The following table shows how different values of @var{depth} will +effect how @code{var} is printed by @value{GDBN}: + +@multitable @columnfractions .3 .7 +@headitem @var{depth} setting @tab Result of @samp{p var} +@item unlimited +@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} +@item @code{0} +@tab @code{$1 = @{...@}} +@item @code{1} +@tab @code{$1 = @{d = @{...@}@}} +@item @code{2} +@tab @code{$1 = @{d = @{c = @{...@}@}@}} +@item @code{3} +@tab @code{$1 = @{d = @{c = @{b = @{...@}@}@}@}} +@item @code{4} +@tab @code{$1 = @{d = @{c = @{b = @{a = 3@}@}@}@}} +@end multitable + +To see the contents of structures that have been hidden the user can +either increase the print max-depth, or they can print the elements of +the structure that are visible, for example + +@smallexample +(@value{GDBP}) set print max-depth 2 +(@value{GDBP}) p var +$1 = @{d = @{c = @{...@}@}@} +(@value{GDBP}) p var.d +$2 = @{c = @{b = @{...@}@}@} +(@value{GDBP}) p var.d.c +$3 = @{b = @{a = 3@}@} +@end smallexample + +The pattern used to replace nested structures varies based on +language, for most languages @code{@{...@}} is used, but Fortran uses +@code{(...)}. + +@item show print max-depth +Display the current threshold after which nested structures are +replaces with ellipsis. + +@anchor{set print memory-tag-violations} +@cindex printing memory tag violation information +@item set print memory-tag-violations +@itemx set print memory-tag-violations on +Cause @value{GDBN} to display additional information about memory tag violations +when printing pointers and addresses. + +@item set print memory-tag-violations off +Stop printing memory tag violation information. + +@item show print memory-tag-violations +Show whether memory tag violation information is displayed when printing +pointers and addresses. + +@anchor{set print null-stop} +@item set print null-stop +@cindex @sc{null} elements in arrays +Cause @value{GDBN} to stop printing the characters of an array when the first +@sc{null} is encountered. This is useful when large arrays actually +contain only short strings. +The default is off. + +@item show print null-stop +Show whether @value{GDBN} stops printing an array on the first +@sc{null} character. + +@anchor{set print pretty} +@item set print pretty on +@cindex print structures in indented form +@cindex indentation in structure display +Cause @value{GDBN} to print structures in an indented format with one member +per line, like this: + +@smallexample +@group +$1 = @{ + next = 0x0, + flags = @{ + sweet = 1, + sour = 1 + @}, + meat = 0x54 "Pork" +@} +@end group +@end smallexample + +@item set print pretty off +Cause @value{GDBN} to print structures in a compact format, like this: + +@smallexample +@group +$1 = @{next = 0x0, flags = @{sweet = 1, sour = 1@}, \ +meat = 0x54 "Pork"@} +@end group +@end smallexample + +@noindent +This is the default format. + +@item show print pretty +Show which format @value{GDBN} is using to print structures. + +@anchor{set print raw-values} +@item set print raw-values on +Print values in raw form, without applying the pretty +printers for the value. + +@item set print raw-values off +Print values in pretty-printed form, if there is a pretty-printer +for the value (@pxref{Pretty Printing}), +otherwise print the value in raw form. + +The default setting is ``off''. + +@item show print raw-values +Show whether to print values in raw form. + +@item set print sevenbit-strings on +@cindex eight-bit characters in strings +@cindex octal escapes in strings +Print using only seven-bit characters; if this option is set, +@value{GDBN} displays any eight-bit characters (in strings or +character values) using the notation @code{\}@var{nnn}. This setting is +best if you are working in English (@sc{ascii}) and you use the +high-order bit of characters as a marker or ``meta'' bit. + +@item set print sevenbit-strings off +Print full eight-bit characters. This allows the use of more +international character sets, and is the default. + +@item show print sevenbit-strings +Show whether or not @value{GDBN} is printing only seven-bit characters. + +@anchor{set print union} +@item set print union on +@cindex unions in structures, printing +Tell @value{GDBN} to print unions which are contained in structures +and other unions. This is the default setting. + +@item set print union off +Tell @value{GDBN} not to print unions which are contained in +structures and other unions. @value{GDBN} will print @code{"@{...@}"} +instead. + +@item show print union +Ask @value{GDBN} whether or not it will print unions which are contained in +structures and other unions. + +For example, given the declarations + +@smallexample +typedef enum @{Tree, Bug@} Species; +typedef enum @{Big_tree, Acorn, Seedling@} Tree_forms; +typedef enum @{Caterpillar, Cocoon, Butterfly@} + Bug_forms; + +struct thing @{ + Species it; + union @{ + Tree_forms tree; + Bug_forms bug; + @} form; +@}; + +struct thing foo = @{Tree, @{Acorn@}@}; +@end smallexample + +@noindent +with @code{set print union on} in effect @samp{p foo} would print + +@smallexample +$1 = @{it = Tree, form = @{tree = Acorn, bug = Cocoon@}@} +@end smallexample + +@noindent +and with @code{set print union off} in effect it would print + +@smallexample +$1 = @{it = Tree, form = @{...@}@} +@end smallexample + +@noindent +@code{set print union} affects programs written in C-like languages +and in Pascal. +@end table + +@need 1000 +@noindent +These settings are of interest when debugging C@t{++} programs: + +@table @code +@cindex demangling C@t{++} names +@item set print demangle +@itemx set print demangle on +Print C@t{++} names in their source form rather than in the encoded +(``mangled'') form passed to the assembler and linker for type-safe +linkage. The default is on. + +@item show print demangle +Show whether C@t{++} names are printed in mangled or demangled form. + +@item set print asm-demangle +@itemx set print asm-demangle on +Print C@t{++} names in their source form rather than their mangled form, even +in assembler code printouts such as instruction disassemblies. +The default is off. + +@item show print asm-demangle +Show whether C@t{++} names in assembly listings are printed in mangled +or demangled form. + +@cindex C@t{++} symbol decoding style +@cindex symbol decoding style, C@t{++} +@kindex set demangle-style +@item set demangle-style @var{style} +Choose among several encoding schemes used by different compilers to represent +C@t{++} names. If you omit @var{style}, you will see a list of possible +formats. The default value is @var{auto}, which lets @value{GDBN} choose a +decoding style by inspecting your program. + +@item show demangle-style +Display the encoding style currently in use for decoding C@t{++} symbols. + +@anchor{set print object} +@item set print object +@itemx set print object on +@cindex derived type of an object, printing +@cindex display derived types +When displaying a pointer to an object, identify the @emph{actual} +(derived) type of the object rather than the @emph{declared} type, using +the virtual function table. Note that the virtual function table is +required---this feature can only work for objects that have run-time +type identification; a single virtual method in the object's declared +type is sufficient. Note that this setting is also taken into account when +working with variable objects via MI (@pxref{GDB/MI}). + +@item set print object off +Display only the declared type of objects, without reference to the +virtual function table. This is the default setting. + +@item show print object +Show whether actual, or declared, object types are displayed. + +@anchor{set print static-members} +@item set print static-members +@itemx set print static-members on +@cindex static members of C@t{++} objects +Print static members when displaying a C@t{++} object. The default is on. + +@item set print static-members off +Do not print static members when displaying a C@t{++} object. + +@item show print static-members +Show whether C@t{++} static members are printed or not. + +@item set print pascal_static-members +@itemx set print pascal_static-members on +@cindex static members of Pascal objects +@cindex Pascal objects, static members display +Print static members when displaying a Pascal object. The default is on. + +@item set print pascal_static-members off +Do not print static members when displaying a Pascal object. + +@item show print pascal_static-members +Show whether Pascal static members are printed or not. + +@c These don't work with HP ANSI C++ yet. +@anchor{set print vtbl} +@item set print vtbl +@itemx set print vtbl on +@cindex pretty print C@t{++} virtual function tables +@cindex virtual functions (C@t{++}) display +@cindex VTBL display +Pretty print C@t{++} virtual function tables. The default is off. +(The @code{vtbl} commands do not work on programs compiled with the HP +ANSI C@t{++} compiler (@code{aCC}).) + +@item set print vtbl off +Do not pretty print C@t{++} virtual function tables. + +@item show print vtbl +Show whether C@t{++} virtual function tables are pretty printed, or not. +@end table + +@node Pretty Printing +@section Pretty Printing + +@value{GDBN} provides a mechanism to allow pretty-printing of values using +Python code. It greatly simplifies the display of complex objects. This +mechanism works for both MI and the CLI. + +@menu +* Pretty-Printer Introduction:: Introduction to pretty-printers +* Pretty-Printer Example:: An example pretty-printer +* Pretty-Printer Commands:: Pretty-printer commands +@end menu + +@node Pretty-Printer Introduction +@subsection Pretty-Printer Introduction + +When @value{GDBN} prints a value, it first sees if there is a pretty-printer +registered for the value. If there is then @value{GDBN} invokes the +pretty-printer to print the value. Otherwise the value is printed normally. + +Pretty-printers are normally named. This makes them easy to manage. +The @samp{info pretty-printer} command will list all the installed +pretty-printers with their names. +If a pretty-printer can handle multiple data types, then its +@dfn{subprinters} are the printers for the individual data types. +Each such subprinter has its own name. +The format of the name is @var{printer-name};@var{subprinter-name}. + +Pretty-printers are installed by @dfn{registering} them with @value{GDBN}. +Typically they are automatically loaded and registered when the corresponding +debug information is loaded, thus making them available without having to +do anything special. + +There are three places where a pretty-printer can be registered. + +@itemize @bullet +@item +Pretty-printers registered globally are available when debugging +all inferiors. + +@item +Pretty-printers registered with a program space are available only +when debugging that program. +@xref{Progspaces In Python}, for more details on program spaces in Python. + +@item +Pretty-printers registered with an objfile are loaded and unloaded +with the corresponding objfile (e.g., shared library). +@xref{Objfiles In Python}, for more details on objfiles in Python. +@end itemize + +@xref{Selecting Pretty-Printers}, for further information on how +pretty-printers are selected, + +@xref{Writing a Pretty-Printer}, for implementing pretty printers +for new types. + +@node Pretty-Printer Example +@subsection Pretty-Printer Example + +Here is how a C@t{++} @code{std::string} looks without a pretty-printer: + +@smallexample +(@value{GDBP}) print s +$1 = @{ + static npos = 4294967295, + _M_dataplus = @{ + > = @{ + <__gnu_cxx::new_allocator> = @{ + @}, + @}, + members of std::basic_string, + std::allocator >::_Alloc_hider: + _M_p = 0x804a014 "abcd" + @} +@} +@end smallexample + +With a pretty-printer for @code{std::string} only the contents are printed: + +@smallexample +(@value{GDBP}) print s +$2 = "abcd" +@end smallexample + +@node Pretty-Printer Commands +@subsection Pretty-Printer Commands +@cindex pretty-printer commands + +@table @code +@kindex info pretty-printer +@item info pretty-printer [@var{object-regexp} [@var{name-regexp}]] +Print the list of installed pretty-printers. +This includes disabled pretty-printers, which are marked as such. + +@var{object-regexp} is a regular expression matching the objects +whose pretty-printers to list. +Objects can be @code{global}, the program space's file +(@pxref{Progspaces In Python}), +and the object files within that program space (@pxref{Objfiles In Python}). +@xref{Selecting Pretty-Printers}, for details on how @value{GDBN} +looks up a printer from these three objects. + +@var{name-regexp} is a regular expression matching the name of the printers +to list. + +@kindex disable pretty-printer +@item disable pretty-printer [@var{object-regexp} [@var{name-regexp}]] +Disable pretty-printers matching @var{object-regexp} and @var{name-regexp}. +A disabled pretty-printer is not forgotten, it may be enabled again later. + +@kindex enable pretty-printer +@item enable pretty-printer [@var{object-regexp} [@var{name-regexp}]] +Enable pretty-printers matching @var{object-regexp} and @var{name-regexp}. +@end table + +Example: + +Suppose we have three pretty-printers installed: one from library1.so +named @code{foo} that prints objects of type @code{foo}, and +another from library2.so named @code{bar} that prints two types of objects, +@code{bar1} and @code{bar2}. + +@smallexample +@group +(@value{GDBP}) info pretty-printer +library1.so: + foo +library2.so: + bar + bar1 + bar2 +@end group +@group +(@value{GDBP}) info pretty-printer library2 +library2.so: + bar + bar1 + bar2 +@end group +@group +(@value{GDBP}) disable pretty-printer library1 +1 printer disabled +2 of 3 printers enabled +(@value{GDBP}) info pretty-printer +library1.so: + foo [disabled] +library2.so: + bar + bar1 + bar2 +@end group +@group +(@value{GDBP}) disable pretty-printer library2 bar;bar1 +1 printer disabled +1 of 3 printers enabled +(@value{GDBP}) info pretty-printer library2 +library2.so: + bar + bar1 [disabled] + bar2 +@end group +@group +(@value{GDBP}) disable pretty-printer library2 bar +1 printer disabled +0 of 3 printers enabled +(@value{GDBP}) info pretty-printer +library1.so: + foo [disabled] +library2.so: + bar [disabled] + bar1 [disabled] + bar2 +@end group +@end smallexample + +Note that for @code{bar} the entire printer can be disabled, +as can each individual subprinter. + +Printing values and frame arguments is done by default using +the enabled pretty printers. + +The print option @code{-raw-values} and @value{GDBN} setting +@code{set print raw-values} (@pxref{set print raw-values}) can be +used to print values without applying the enabled pretty printers. + +Similarly, the backtrace option @code{-raw-frame-arguments} and +@value{GDBN} setting @code{set print raw-frame-arguments} +(@pxref{set print raw-frame-arguments}) can be used to ignore the +enabled pretty printers when printing frame argument values. + +@node Value History +@section Value History + +@cindex value history +@cindex history of values printed by @value{GDBN} +Values printed by the @code{print} command are saved in the @value{GDBN} +@dfn{value history}. This allows you to refer to them in other expressions. +Values are kept until the symbol table is re-read or discarded +(for example with the @code{file} or @code{symbol-file} commands). +When the symbol table changes, the value history is discarded, +since the values may contain pointers back to the types defined in the +symbol table. + +@cindex @code{$} +@cindex @code{$$} +@cindex history number +The values printed are given @dfn{history numbers} by which you can +refer to them. These are successive integers starting with one. +@code{print} shows you the history number assigned to a value by +printing @samp{$@var{num} = } before the value; here @var{num} is the +history number. + +To refer to any previous value, use @samp{$} followed by the value's +history number. The way @code{print} labels its output is designed to +remind you of this. Just @code{$} refers to the most recent value in +the history, and @code{$$} refers to the value before that. +@code{$$@var{n}} refers to the @var{n}th value from the end; @code{$$2} +is the value just prior to @code{$$}, @code{$$1} is equivalent to +@code{$$}, and @code{$$0} is equivalent to @code{$}. + +For example, suppose you have just printed a pointer to a structure and +want to see the contents of the structure. It suffices to type + +@smallexample +p *$ +@end smallexample + +If you have a chain of structures where the component @code{next} points +to the next one, you can print the contents of the next one with this: + +@smallexample +p *$.next +@end smallexample + +@noindent +You can print successive links in the chain by repeating this +command---which you can do by just typing @key{RET}. + +Note that the history records values, not expressions. If the value of +@code{x} is 4 and you type these commands: + +@smallexample +print x +set x=5 +@end smallexample + +@noindent +then the value recorded in the value history by the @code{print} command +remains 4 even though the value of @code{x} has changed. + +@table @code +@kindex show values +@item show values +Print the last ten values in the value history, with their item numbers. +This is like @samp{p@ $$9} repeated ten times, except that @code{show +values} does not change the history. + +@item show values @var{n} +Print ten history values centered on history item number @var{n}. + +@item show values + +Print ten history values just after the values last printed. If no more +values are available, @code{show values +} produces no display. +@end table + +Pressing @key{RET} to repeat @code{show values @var{n}} has exactly the +same effect as @samp{show values +}. + +@node Convenience Vars +@section Convenience Variables + +@cindex convenience variables +@cindex user-defined variables +@value{GDBN} provides @dfn{convenience variables} that you can use within +@value{GDBN} to hold on to a value and refer to it later. These variables +exist entirely within @value{GDBN}; they are not part of your program, and +setting a convenience variable has no direct effect on further execution +of your program. That is why you can use them freely. + +Convenience variables are prefixed with @samp{$}. Any name preceded by +@samp{$} can be used for a convenience variable, unless it is one of +the predefined machine-specific register names (@pxref{Registers, ,Registers}). +(Value history references, in contrast, are @emph{numbers} preceded +by @samp{$}. @xref{Value History, ,Value History}.) + +You can save a value in a convenience variable with an assignment +expression, just as you would set a variable in your program. +For example: + +@smallexample +set $foo = *object_ptr +@end smallexample + +@noindent +would save in @code{$foo} the value contained in the object pointed to by +@code{object_ptr}. + +Using a convenience variable for the first time creates it, but its +value is @code{void} until you assign a new value. You can alter the +value with another assignment at any time. + +Convenience variables have no fixed types. You can assign a convenience +variable any type of value, including structures and arrays, even if +that variable already has a value of a different type. The convenience +variable, when used as an expression, has the type of its current value. + +@table @code +@kindex show convenience +@cindex show all user variables and functions +@item show convenience +Print a list of convenience variables used so far, and their values, +as well as a list of the convenience functions. +Abbreviated @code{show conv}. + +@kindex init-if-undefined +@cindex convenience variables, initializing +@item init-if-undefined $@var{variable} = @var{expression} +Set a convenience variable if it has not already been set. This is useful +for user-defined commands that keep some state. It is similar, in concept, +to using local static variables with initializers in C (except that +convenience variables are global). It can also be used to allow users to +override default values used in a command script. + +If the variable is already defined then the expression is not evaluated so +any side-effects do not occur. +@end table + +One of the ways to use a convenience variable is as a counter to be +incremented or a pointer to be advanced. For example, to print +a field from successive elements of an array of structures: + +@smallexample +set $i = 0 +print bar[$i++]->contents +@end smallexample + +@noindent +Repeat that command by typing @key{RET}. + +Some convenience variables are created automatically by @value{GDBN} and given +values likely to be useful. + +@table @code +@vindex $_@r{, convenience variable} +@item $_ +The variable @code{$_} is automatically set by the @code{x} command to +the last address examined (@pxref{Memory, ,Examining Memory}). Other +commands which provide a default address for @code{x} to examine also +set @code{$_} to that address; these commands include @code{info line} +and @code{info breakpoint}. The type of @code{$_} is @code{void *} +except when set by the @code{x} command, in which case it is a pointer +to the type of @code{$__}. + +@vindex $__@r{, convenience variable} +@item $__ +The variable @code{$__} is automatically set by the @code{x} command +to the value found in the last address examined. Its type is chosen +to match the format in which the data was printed. + +@item $_exitcode +@vindex $_exitcode@r{, convenience variable} +When the program being debugged terminates normally, @value{GDBN} +automatically sets this variable to the exit code of the program, and +resets @code{$_exitsignal} to @code{void}. + +@item $_exitsignal +@vindex $_exitsignal@r{, convenience variable} +When the program being debugged dies due to an uncaught signal, +@value{GDBN} automatically sets this variable to that signal's number, +and resets @code{$_exitcode} to @code{void}. + +To distinguish between whether the program being debugged has exited +(i.e., @code{$_exitcode} is not @code{void}) or signalled (i.e., +@code{$_exitsignal} is not @code{void}), the convenience function +@code{$_isvoid} can be used (@pxref{Convenience Funs,, Convenience +Functions}). For example, considering the following source code: + +@smallexample +#include + +int +main (int argc, char *argv[]) +@{ + raise (SIGALRM); + return 0; +@} +@end smallexample + +A valid way of telling whether the program being debugged has exited +or signalled would be: + +@smallexample +(@value{GDBP}) define has_exited_or_signalled +Type commands for definition of ``has_exited_or_signalled''. +End with a line saying just ``end''. +>if $_isvoid ($_exitsignal) + >echo The program has exited\n + >else + >echo The program has signalled\n + >end +>end +(@value{GDBP}) run +Starting program: + +Program terminated with signal SIGALRM, Alarm clock. +The program no longer exists. +(@value{GDBP}) has_exited_or_signalled +The program has signalled +@end smallexample + +As can be seen, @value{GDBN} correctly informs that the program being +debugged has signalled, since it calls @code{raise} and raises a +@code{SIGALRM} signal. If the program being debugged had not called +@code{raise}, then @value{GDBN} would report a normal exit: + +@smallexample +(@value{GDBP}) has_exited_or_signalled +The program has exited +@end smallexample + +@item $_exception +The variable @code{$_exception} is set to the exception object being +thrown at an exception-related catchpoint. @xref{Set Catchpoints}. + +@item $_ada_exception +The variable @code{$_ada_exception} is set to the address of the +exception being caught or thrown at an Ada exception-related +catchpoint. @xref{Set Catchpoints}. + +@item $_probe_argc +@itemx $_probe_arg0@dots{}$_probe_arg11 +Arguments to a static probe. @xref{Static Probe Points}. + +@item $_sdata +@vindex $_sdata@r{, inspect, convenience variable} +The variable @code{$_sdata} contains extra collected static tracepoint +data. @xref{Tracepoint Actions,,Tracepoint Action Lists}. Note that +@code{$_sdata} could be empty, if not inspecting a trace buffer, or +if extra static tracepoint data has not been collected. + +@item $_siginfo +@vindex $_siginfo@r{, convenience variable} +The variable @code{$_siginfo} contains extra signal information +(@pxref{extra signal information}). Note that @code{$_siginfo} +could be empty, if the application has not yet received any signals. +For example, it will be empty before you execute the @code{run} command. + +@item $_tlb +@vindex $_tlb@r{, convenience variable} +The variable @code{$_tlb} is automatically set when debugging +applications running on MS-Windows in native mode or connected to +gdbserver that supports the @code{qGetTIBAddr} request. +@xref{General Query Packets}. +This variable contains the address of the thread information block. + +@item $_inferior +The number of the current inferior. @xref{Inferiors Connections and +Programs, ,Debugging Multiple Inferiors Connections and Programs}. + +@item $_thread +The thread number of the current thread. @xref{thread numbers}. + +@item $_gthread +The global number of the current thread. @xref{global thread numbers}. + +@item $_inferior_thread_count +The number of live threads in the current inferior. @xref{Threads}. + +@item $_gdb_major +@itemx $_gdb_minor +@vindex $_gdb_major@r{, convenience variable} +@vindex $_gdb_minor@r{, convenience variable} +The major and minor version numbers of the running @value{GDBN}. +Development snapshots and pretest versions have their minor version +incremented by one; thus, @value{GDBN} pretest 9.11.90 will produce +the value 12 for @code{$_gdb_minor}. These variables allow you to +write scripts that work with different versions of @value{GDBN} +without errors caused by features unavailable in some of those +versions. + +@item $_shell_exitcode +@itemx $_shell_exitsignal +@vindex $_shell_exitcode@r{, convenience variable} +@vindex $_shell_exitsignal@r{, convenience variable} +@cindex shell command, exit code +@cindex shell command, exit signal +@cindex exit status of shell commands +@value{GDBN} commands such as @code{shell} and @code{|} are launching +shell commands. When a launched command terminates, @value{GDBN} +automatically maintains the variables @code{$_shell_exitcode} +and @code{$_shell_exitsignal} according to the exit status of the last +launched command. These variables are set and used similarly to +the variables @code{$_exitcode} and @code{$_exitsignal}. + +@end table + +@node Convenience Funs +@section Convenience Functions + +@cindex convenience functions +@value{GDBN} also supplies some @dfn{convenience functions}. These +have a syntax similar to convenience variables. A convenience +function can be used in an expression just like an ordinary function; +however, a convenience function is implemented internally to +@value{GDBN}. + +These functions do not require @value{GDBN} to be configured with +@code{Python} support, which means that they are always available. + +@table @code + +@findex $_isvoid@r{, convenience function} +@item $_isvoid (@var{expr}) +Return one if the expression @var{expr} is @code{void}. Otherwise it +returns zero. + +A @code{void} expression is an expression where the type of the result +is @code{void}. For example, you can examine a convenience variable +(see @ref{Convenience Vars,, Convenience Variables}) to check whether +it is @code{void}: + +@smallexample +(@value{GDBP}) print $_exitcode +$1 = void +(@value{GDBP}) print $_isvoid ($_exitcode) +$2 = 1 +(@value{GDBP}) run +Starting program: ./a.out +[Inferior 1 (process 29572) exited normally] +(@value{GDBP}) print $_exitcode +$3 = 0 +(@value{GDBP}) print $_isvoid ($_exitcode) +$4 = 0 +@end smallexample + +In the example above, we used @code{$_isvoid} to check whether +@code{$_exitcode} is @code{void} before and after the execution of the +program being debugged. Before the execution there is no exit code to +be examined, therefore @code{$_exitcode} is @code{void}. After the +execution the program being debugged returned zero, therefore +@code{$_exitcode} is zero, which means that it is not @code{void} +anymore. + +The @code{void} expression can also be a call of a function from the +program being debugged. For example, given the following function: + +@smallexample +void +foo (void) +@{ +@} +@end smallexample + +The result of calling it inside @value{GDBN} is @code{void}: + +@smallexample +(@value{GDBP}) print foo () +$1 = void +(@value{GDBP}) print $_isvoid (foo ()) +$2 = 1 +(@value{GDBP}) set $v = foo () +(@value{GDBP}) print $v +$3 = void +(@value{GDBP}) print $_isvoid ($v) +$4 = 1 +@end smallexample + +@findex $_gdb_setting_str@r{, convenience function} +@item $_gdb_setting_str (@var{setting}) +Return the value of the @value{GDBN} @var{setting} as a string. +@var{setting} is any setting that can be used in a @code{set} or +@code{show} command (@pxref{Controlling GDB}). + +@smallexample +(@value{GDBP}) show print frame-arguments +Printing of non-scalar frame arguments is "scalars". +(@value{GDBP}) p $_gdb_setting_str("print frame-arguments") +$1 = "scalars" +(@value{GDBP}) p $_gdb_setting_str("height") +$2 = "30" +(@value{GDBP}) +@end smallexample + +@findex $_gdb_setting@r{, convenience function} +@item $_gdb_setting (@var{setting}) +Return the value of the @value{GDBN} @var{setting}. +The type of the returned value depends on the setting. + +The value type for boolean and auto boolean settings is @code{int}. +The boolean values @code{off} and @code{on} are converted to +the integer values @code{0} and @code{1}. The value @code{auto} is +converted to the value @code{-1}. + +The value type for integer settings is either @code{unsigned int} +or @code{int}, depending on the setting. + +Some integer settings accept an @code{unlimited} value. +Depending on the setting, the @code{set} command also accepts +the value @code{0} or the value @code{@minus{}1} as a synonym for +@code{unlimited}. +For example, @code{set height unlimited} is equivalent to +@code{set height 0}. + +Some other settings that accept the @code{unlimited} value +use the value @code{0} to literally mean zero. +For example, @code{set history size 0} indicates to not +record any @value{GDBN} commands in the command history. +For such settings, @code{@minus{}1} is the synonym +for @code{unlimited}. + +See the documentation of the corresponding @code{set} command for +the numerical value equivalent to @code{unlimited}. + +The @code{$_gdb_setting} function converts the unlimited value +to a @code{0} or a @code{@minus{}1} value according to what the +@code{set} command uses. + +@smallexample +@group +(@value{GDBP}) p $_gdb_setting_str("height") +$1 = "30" +(@value{GDBP}) p $_gdb_setting("height") +$2 = 30 +(@value{GDBP}) set height unlimited +(@value{GDBP}) p $_gdb_setting_str("height") +$3 = "unlimited" +(@value{GDBP}) p $_gdb_setting("height") +$4 = 0 +@end group +@group +(@value{GDBP}) p $_gdb_setting_str("history size") +$5 = "unlimited" +(@value{GDBP}) p $_gdb_setting("history size") +$6 = -1 +(@value{GDBP}) p $_gdb_setting_str("disassemble-next-line") +$7 = "auto" +(@value{GDBP}) p $_gdb_setting("disassemble-next-line") +$8 = -1 +(@value{GDBP}) +@end group +@end smallexample + +Other setting types (enum, filename, optional filename, string, string noescape) +are returned as string values. + + +@findex $_gdb_maint_setting_str@r{, convenience function} +@item $_gdb_maint_setting_str (@var{setting}) +Like the @code{$_gdb_setting_str} function, but works with +@code{maintenance set} variables. + +@findex $_gdb_maint_setting@r{, convenience function} +@item $_gdb_maint_setting (@var{setting}) +Like the @code{$_gdb_setting} function, but works with +@code{maintenance set} variables. + +@anchor{$_shell convenience function} +@findex $_shell@r{, convenience function} +@item $_shell (@var{command-string}) + +Invoke a shell to execute @var{command-string}. @var{command-string} +must be a string. The shell runs on the host machine, the machine +@value{GDBN} is running on. Returns the command's exit status. On +Unix systems, a command which exits with a zero exit status has +succeeded, and non-zero exit status indicates failure. When a command +terminates on a fatal signal whose number is @var{N}, @value{GDBN} +uses the value 128+@var{N} as the exit status, as is standard in Unix +shells. Note that @var{N} is a host signal number, not a target +signal number. If you're native debugging, they will be the same, but +if cross debugging, the host vs target signal numbers may be +completely unrelated. Please consult your host operating system's +documentation for the mapping between host signal numbers and signal +names. The shell to run is determined in the same way as for the +@code{shell} command. @xref{Shell Commands, ,Shell Commands}. + +@smallexample +(@value{GDBP}) print $_shell("true") +$1 = 0 +(@value{GDBP}) print $_shell("false") +$2 = 1 +(@value{GDBP}) p $_shell("echo hello") +hello +$3 = 0 +(@value{GDBP}) p $_shell("foobar") +bash: line 1: foobar: command not found +$4 = 127 +@end smallexample + +This may also be useful in breakpoint conditions. For example: + +@smallexample +(@value{GDBP}) break function if $_shell("some command") == 0 +@end smallexample + +In this scenario, you'll want to make sure that the shell command you +run in the breakpoint condition takes the least amount of time +possible. For example, avoid running a command that may block +indefinitely, or that sleeps for a while before exiting. Prefer a +command or script which analyzes some state and exits immediately. +This is important because the debugged program stops for the +breakpoint every time, and then @value{GDBN} evaluates the breakpoint +condition. If the condition is false, the program is re-resumed +transparently, without informing you of the stop. A quick shell +command thus avoids significantly slowing down the debugged program +unnecessarily. + +Note: unlike the @code{shell} command, the @code{$_shell} convenience +function does not affect the @code{$_shell_exitcode} and +@code{$_shell_exitsignal} convenience variables. + +@end table + +The following functions require @value{GDBN} to be configured with +@code{Python} support. + +@table @code + +@findex $_memeq@r{, convenience function} +@item $_memeq(@var{buf1}, @var{buf2}, @var{length}) +Returns one if the @var{length} bytes at the addresses given by +@var{buf1} and @var{buf2} are equal. +Otherwise it returns zero. + +@findex $_regex@r{, convenience function} +@item $_regex(@var{str}, @var{regex}) +Returns one if the string @var{str} matches the regular expression +@var{regex}. Otherwise it returns zero. +The syntax of the regular expression is that specified by @code{Python}'s +regular expression support. + +@findex $_streq@r{, convenience function} +@item $_streq(@var{str1}, @var{str2}) +Returns one if the strings @var{str1} and @var{str2} are equal. +Otherwise it returns zero. + +@findex $_strlen@r{, convenience function} +@item $_strlen(@var{str}) +Returns the length of string @var{str}. + +@findex $_caller_is@r{, convenience function} +@item $_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) +Returns one if the calling function's name is equal to @var{name}. +Otherwise it returns zero. + +If the optional argument @var{number_of_frames} is provided, +it is the number of frames up in the stack to look. +The default is 1. + +Example: + +@smallexample +(@value{GDBP}) backtrace +#0 bottom_func () + at testsuite/gdb.python/py-caller-is.c:21 +#1 0x00000000004005a0 in middle_func () + at testsuite/gdb.python/py-caller-is.c:27 +#2 0x00000000004005ab in top_func () + at testsuite/gdb.python/py-caller-is.c:33 +#3 0x00000000004005b6 in main () + at testsuite/gdb.python/py-caller-is.c:39 +(@value{GDBP}) print $_caller_is ("middle_func") +$1 = 1 +(@value{GDBP}) print $_caller_is ("top_func", 2) +$1 = 1 +@end smallexample + +@findex $_caller_matches@r{, convenience function} +@item $_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) +Returns one if the calling function's name matches the regular expression +@var{regexp}. Otherwise it returns zero. + +If the optional argument @var{number_of_frames} is provided, +it is the number of frames up in the stack to look. +The default is 1. + +@findex $_any_caller_is@r{, convenience function} +@item $_any_caller_is(@var{name}@r{[}, @var{number_of_frames}@r{]}) +Returns one if any calling function's name is equal to @var{name}. +Otherwise it returns zero. + +If the optional argument @var{number_of_frames} is provided, +it is the number of frames up in the stack to look. +The default is 1. + +This function differs from @code{$_caller_is} in that this function +checks all stack frames from the immediate caller to the frame specified +by @var{number_of_frames}, whereas @code{$_caller_is} only checks the +frame specified by @var{number_of_frames}. + +@findex $_any_caller_matches@r{, convenience function} +@item $_any_caller_matches(@var{regexp}@r{[}, @var{number_of_frames}@r{]}) +Returns one if any calling function's name matches the regular expression +@var{regexp}. Otherwise it returns zero. + +If the optional argument @var{number_of_frames} is provided, +it is the number of frames up in the stack to look. +The default is 1. + +This function differs from @code{$_caller_matches} in that this function +checks all stack frames from the immediate caller to the frame specified +by @var{number_of_frames}, whereas @code{$_caller_matches} only checks the +frame specified by @var{number_of_frames}. + +@findex $_as_string@r{, convenience function} +@item $_as_string(@var{value}) +This convenience function is considered deprecated, and could be +removed from future versions of @value{GDBN}. Use the @samp{%V} format +specifier instead (@pxref{%V Format Specifier}). + +Return the string representation of @var{value}. + +This function is useful to obtain the textual label (enumerator) of an +enumeration value. For example, assuming the variable @var{node} is of +an enumerated type: + +@smallexample +(@value{GDBP}) printf "Visiting node of type %s\n", $_as_string(node) +Visiting node of type NODE_INTEGER +@end smallexample + +@findex $_cimag@r{, convenience function} +@findex $_creal@r{, convenience function} +@item $_cimag(@var{value}) +@itemx $_creal(@var{value}) +Return the imaginary (@code{$_cimag}) or real (@code{$_creal}) part of +the complex number @var{value}. + +The type of the imaginary or real part depends on the type of the +complex number, e.g., using @code{$_cimag} on a @code{float complex} +will return an imaginary part of type @code{float}. + +@end table + +@value{GDBN} provides the ability to list and get help on +convenience functions. + +@table @code +@item help function +@kindex help function +@cindex show all convenience functions +Print a list of all convenience functions. +@end table + +@node Registers +@section Registers + +@cindex registers +You can refer to machine register contents, in expressions, as variables +with names starting with @samp{$}. The names of registers are different +for each machine; use @code{info registers} to see the names used on +your machine. + +@table @code +@kindex info registers +@item info registers +Print the names and values of all registers except floating-point +and vector registers (in the selected stack frame). + +@kindex info all-registers +@cindex floating point registers +@item info all-registers +Print the names and values of all registers, including floating-point +and vector registers (in the selected stack frame). + +@anchor{info_registers_reggroup} +@item info registers @var{reggroup} @dots{} +Print the name and value of the registers in each of the specified +@var{reggroup}s. The @var{reggroup} can be any of those returned by +@code{maint print reggroups} (@pxref{Maintenance Commands}). + +@item info registers @var{regname} @dots{} +Print the @dfn{relativized} value of each specified register @var{regname}. +As discussed in detail below, register values are normally relative to +the selected stack frame. The @var{regname} may be any register name valid on +the machine you are using, with or without the initial @samp{$}. +@end table + +@anchor{standard registers} +@cindex stack pointer register +@cindex program counter register +@cindex process status register +@cindex frame pointer register +@cindex standard registers +@value{GDBN} has four ``standard'' register names that are available (in +expressions) on most machines---whenever they do not conflict with an +architecture's canonical mnemonics for registers. The register names +@code{$pc} and @code{$sp} are used for the program counter register and +the stack pointer. @code{$fp} is used for a register that contains a +pointer to the current stack frame, and @code{$ps} is used for a +register that contains the processor status. For example, +you could print the program counter in hex with + +@smallexample +p/x $pc +@end smallexample + +@noindent +or print the instruction to be executed next with + +@smallexample +x/i $pc +@end smallexample + +@noindent +or add four to the stack pointer@footnote{This is a way of removing +one word from the stack, on machines where stacks grow downward in +memory (most machines, nowadays). This assumes that the innermost +stack frame is selected; setting @code{$sp} is not allowed when other +stack frames are selected. To pop entire frames off the stack, +regardless of machine architecture, use @code{return}; +see @ref{Returning, ,Returning from a Function}.} with + +@smallexample +set $sp += 4 +@end smallexample + +Whenever possible, these four standard register names are available on +your machine even though the machine has different canonical mnemonics, +so long as there is no conflict. The @code{info registers} command +shows the canonical names. For example, on the SPARC, @code{info +registers} displays the processor status register as @code{$psr} but you +can also refer to it as @code{$ps}; and on x86-based machines @code{$ps} +is an alias for the @sc{eflags} register. + +@value{GDBN} always considers the contents of an ordinary register as an +integer when the register is examined in this way. Some machines have +special registers which can hold nothing but floating point; these +registers are considered to have floating point values. There is no way +to refer to the contents of an ordinary register as floating point value +(although you can @emph{print} it as a floating point value with +@samp{print/f $@var{regname}}). + +Some registers have distinct ``raw'' and ``virtual'' data formats. This +means that the data format in which the register contents are saved by +the operating system is not the same one that your program normally +sees. For example, the registers of the 68881 floating point +coprocessor are always saved in ``extended'' (raw) format, but all C +programs expect to work with ``double'' (virtual) format. In such +cases, @value{GDBN} normally works with the virtual format only (the format +that makes sense for your program), but the @code{info registers} command +prints the data in both formats. + +@cindex SSE registers (x86) +@cindex MMX registers (x86) +Some machines have special registers whose contents can be interpreted +in several different ways. For example, modern x86-based machines +have SSE and MMX registers that can hold several values packed +together in several different formats. @value{GDBN} refers to such +registers in @code{struct} notation: + +@smallexample +(@value{GDBP}) print $xmm1 +$1 = @{ + v4_float = @{0, 3.43859137e-038, 1.54142831e-044, 1.821688e-044@}, + v2_double = @{9.92129282474342e-303, 2.7585945287983262e-313@}, + v16_int8 = "\000\000\000\000\3706;\001\v\000\000\000\r\000\000", + v8_int16 = @{0, 0, 14072, 315, 11, 0, 13, 0@}, + v4_int32 = @{0, 20657912, 11, 13@}, + v2_int64 = @{88725056443645952, 55834574859@}, + uint128 = 0x0000000d0000000b013b36f800000000 +@} +@end smallexample + +@noindent +To set values of such registers, you need to tell @value{GDBN} which +view of the register you wish to change, as if you were assigning +value to a @code{struct} member: + +@smallexample + (@value{GDBP}) set $xmm1.uint128 = 0x000000000000000000000000FFFFFFFF +@end smallexample + +Normally, register values are relative to the selected stack frame +(@pxref{Selection, ,Selecting a Frame}). This means that you get the +value that the register would contain if all stack frames farther in +were exited and their saved registers restored. In order to see the +true contents of hardware registers, you must select the innermost +frame (with @samp{frame 0}). + +@cindex caller-saved registers +@cindex call-clobbered registers +@cindex volatile registers +@cindex values +Usually ABIs reserve some registers as not needed to be saved by the +callee (a.k.a.: ``caller-saved'', ``call-clobbered'' or ``volatile'' +registers). It may therefore not be possible for @value{GDBN} to know +the value a register had before the call (in other words, in the outer +frame), if the register value has since been changed by the callee. +@value{GDBN} tries to deduce where the inner frame saved +(``callee-saved'') registers, from the debug info, unwind info, or the +machine code generated by your compiler. If some register is not +saved, and @value{GDBN} knows the register is ``caller-saved'' (via +its own knowledge of the ABI, or because the debug/unwind info +explicitly says the register's value is undefined), @value{GDBN} +displays @w{@samp{}} as the register's value. With targets +that @value{GDBN} has no knowledge of the register saving convention, +if a register was not saved by the callee, then its value and location +in the outer frame are assumed to be the same of the inner frame. +This is usually harmless, because if the register is call-clobbered, +the caller either does not care what is in the register after the +call, or has code to restore the value that it does care about. Note, +however, that if you change such a register in the outer frame, you +may also be affecting the inner frame. Also, the more ``outer'' the +frame is you're looking at, the more likely a call-clobbered +register's value is to be wrong, in the sense that it doesn't actually +represent the value the register had just before the call. + +@node Floating Point Hardware +@section Floating Point Hardware +@cindex floating point + +Depending on the configuration, @value{GDBN} may be able to give +you more information about the status of the floating point hardware. + +@table @code +@kindex info float +@item info float +Display hardware-dependent information about the floating +point unit. The exact contents and layout vary depending on the +floating point chip. Currently, @samp{info float} is supported on +the ARM and x86 machines. +@end table + +@node Vector Unit +@section Vector Unit +@cindex vector unit + +Depending on the configuration, @value{GDBN} may be able to give you +more information about the status of the vector unit. + +@table @code +@kindex info vector +@item info vector +Display information about the vector unit. The exact contents and +layout vary depending on the hardware. +@end table + +@node OS Information +@section Operating System Auxiliary Information +@cindex OS information + +@value{GDBN} provides interfaces to useful OS facilities that can help +you debug your program. + +@cindex auxiliary vector +@cindex vector, auxiliary +Some operating systems supply an @dfn{auxiliary vector} to programs at +startup. This is akin to the arguments and environment that you +specify for a program, but contains a system-dependent variety of +binary values that tell system libraries important details about the +hardware, operating system, and process. Each value's purpose is +identified by an integer tag; the meanings are well-known but system-specific. +Depending on the configuration and operating system facilities, +@value{GDBN} may be able to show you this information. For remote +targets, this functionality may further depend on the remote stub's +support of the @samp{qXfer:auxv:read} packet, see +@ref{qXfer auxiliary vector read}. + +@table @code +@kindex info auxv +@item info auxv +Display the auxiliary vector of the inferior, which can be either a +live process or a core dump file. @value{GDBN} prints each tag value +numerically, and also shows names and text descriptions for recognized +tags. Some values in the vector are numbers, some bit masks, and some +pointers to strings or other data. @value{GDBN} displays each value in the +most appropriate form for a recognized tag, and in hexadecimal for +an unrecognized tag. +@end table + +On some targets, @value{GDBN} can access operating system-specific +information and show it to you. The types of information available +will differ depending on the type of operating system running on the +target. The mechanism used to fetch the data is described in +@ref{Operating System Information}. For remote targets, this +functionality depends on the remote stub's support of the +@samp{qXfer:osdata:read} packet, see @ref{qXfer osdata read}. + +@table @code +@kindex info os +@item info os @var{infotype} + +Display OS information of the requested type. + +On @sc{gnu}/Linux, the following values of @var{infotype} are valid: + +@anchor{linux info os infotypes} +@table @code +@kindex info os cpus +@item cpus +Display the list of all CPUs/cores. For each CPU/core, @value{GDBN} prints +the available fields from /proc/cpuinfo. For each supported architecture +different fields are available. Two common entries are processor which gives +CPU number and bogomips; a system constant that is calculated during +kernel initialization. + +@kindex info os files +@item files +Display the list of open file descriptors on the target. For each +file descriptor, @value{GDBN} prints the identifier of the process +owning the descriptor, the command of the owning process, the value +of the descriptor, and the target of the descriptor. + +@kindex info os modules +@item modules +Display the list of all loaded kernel modules on the target. For each +module, @value{GDBN} prints the module name, the size of the module in +bytes, the number of times the module is used, the dependencies of the +module, the status of the module, and the address of the loaded module +in memory. + +@kindex info os msg +@item msg +Display the list of all System V message queues on the target. For each +message queue, @value{GDBN} prints the message queue key, the message +queue identifier, the access permissions, the current number of bytes +on the queue, the current number of messages on the queue, the processes +that last sent and received a message on the queue, the user and group +of the owner and creator of the message queue, the times at which a +message was last sent and received on the queue, and the time at which +the message queue was last changed. + +@kindex info os processes +@item processes +Display the list of processes on the target. For each process, +@value{GDBN} prints the process identifier, the name of the user, the +command corresponding to the process, and the list of processor cores +that the process is currently running on. (To understand what these +properties mean, for this and the following info types, please consult +the general @sc{gnu}/Linux documentation.) + +@kindex info os procgroups +@item procgroups +Display the list of process groups on the target. For each process, +@value{GDBN} prints the identifier of the process group that it belongs +to, the command corresponding to the process group leader, the process +identifier, and the command line of the process. The list is sorted +first by the process group identifier, then by the process identifier, +so that processes belonging to the same process group are grouped together +and the process group leader is listed first. + +@kindex info os semaphores +@item semaphores +Display the list of all System V semaphore sets on the target. For each +semaphore set, @value{GDBN} prints the semaphore set key, the semaphore +set identifier, the access permissions, the number of semaphores in the +set, the user and group of the owner and creator of the semaphore set, +and the times at which the semaphore set was operated upon and changed. + +@kindex info os shm +@item shm +Display the list of all System V shared-memory regions on the target. +For each shared-memory region, @value{GDBN} prints the region key, +the shared-memory identifier, the access permissions, the size of the +region, the process that created the region, the process that last +attached to or detached from the region, the current number of live +attaches to the region, and the times at which the region was last +attached to, detach from, and changed. + +@kindex info os sockets +@item sockets +Display the list of Internet-domain sockets on the target. For each +socket, @value{GDBN} prints the address and port of the local and +remote endpoints, the current state of the connection, the creator of +the socket, the IP address family of the socket, and the type of the +connection. + +@kindex info os threads +@item threads +Display the list of threads running on the target. For each thread, +@value{GDBN} prints the identifier of the process that the thread +belongs to, the command of the process, the thread identifier, and the +processor core that it is currently running on. The main thread of a +process is not listed. +@end table + +@item info os +If @var{infotype} is omitted, then list the possible values for +@var{infotype} and the kind of OS information available for each +@var{infotype}. If the target does not return a list of possible +types, this command will report an error. +@end table + +@node Memory Region Attributes +@section Memory Region Attributes +@cindex memory region attributes + +@dfn{Memory region attributes} allow you to describe special handling +required by regions of your target's memory. @value{GDBN} uses +attributes to determine whether to allow certain types of memory +accesses; whether to use specific width accesses; and whether to cache +target memory. By default the description of memory regions is +fetched from the target (if the current target supports this), but the +user can override the fetched regions. + +Defined memory regions can be individually enabled and disabled. When a +memory region is disabled, @value{GDBN} uses the default attributes when +accessing memory in that region. Similarly, if no memory regions have +been defined, @value{GDBN} uses the default attributes when accessing +all memory. + +When a memory region is defined, it is given a number to identify it; +to enable, disable, or remove a memory region, you specify that number. + +@table @code +@kindex mem +@item mem @var{lower} @var{upper} @var{attributes}@dots{} +Define a memory region bounded by @var{lower} and @var{upper} with +attributes @var{attributes}@dots{}, and add it to the list of regions +monitored by @value{GDBN}. Note that @var{upper} == 0 is a special +case: it is treated as the target's maximum memory address. +(0xffff on 16 bit targets, 0xffffffff on 32 bit targets, etc.) + +@item mem auto +Discard any user changes to the memory regions and use target-supplied +regions, if available, or no regions if the target does not support. + +@kindex delete mem +@item delete mem @var{nums}@dots{} +Remove memory regions @var{nums}@dots{} from the list of regions +monitored by @value{GDBN}. + +@kindex disable mem +@item disable mem @var{nums}@dots{} +Disable monitoring of memory regions @var{nums}@dots{}. +A disabled memory region is not forgotten. +It may be enabled again later. + +@kindex enable mem +@item enable mem @var{nums}@dots{} +Enable monitoring of memory regions @var{nums}@dots{}. + +@kindex info mem +@item info mem +Print a table of all defined memory regions, with the following columns +for each region: + +@table @emph +@item Memory Region Number +@item Enabled or Disabled. +Enabled memory regions are marked with @samp{y}. +Disabled memory regions are marked with @samp{n}. + +@item Lo Address +The address defining the inclusive lower bound of the memory region. + +@item Hi Address +The address defining the exclusive upper bound of the memory region. + +@item Attributes +The list of attributes set for this memory region. +@end table +@end table + + +@subsection Attributes + +@subsubsection Memory Access Mode +The access mode attributes set whether @value{GDBN} may make read or +write accesses to a memory region. + +While these attributes prevent @value{GDBN} from performing invalid +memory accesses, they do nothing to prevent the target system, I/O DMA, +etc.@: from accessing memory. + +@table @code +@item ro +Memory is read only. +@item wo +Memory is write only. +@item rw +Memory is read/write. This is the default. +@end table + +@subsubsection Memory Access Size +The access size attribute tells @value{GDBN} to use specific sized +accesses in the memory region. Often memory mapped device registers +require specific sized accesses. If no access size attribute is +specified, @value{GDBN} may use accesses of any size. + +@table @code +@item 8 +Use 8 bit memory accesses. +@item 16 +Use 16 bit memory accesses. +@item 32 +Use 32 bit memory accesses. +@item 64 +Use 64 bit memory accesses. +@end table + +@c @subsubsection Hardware/Software Breakpoints +@c The hardware/software breakpoint attributes set whether @value{GDBN} +@c will use hardware or software breakpoints for the internal breakpoints +@c used by the step, next, finish, until, etc. commands. +@c +@c @table @code +@c @item hwbreak +@c Always use hardware breakpoints +@c @item swbreak (default) +@c @end table + +@subsubsection Data Cache +The data cache attributes set whether @value{GDBN} will cache target +memory. While this generally improves performance by reducing debug +protocol overhead, it can lead to incorrect results because @value{GDBN} +does not know about volatile variables or memory mapped device +registers. + +@table @code +@item cache +Enable @value{GDBN} to cache target memory. +@item nocache +Disable @value{GDBN} from caching target memory. This is the default. +@end table + +@subsection Memory Access Checking +@value{GDBN} can be instructed to refuse accesses to memory that is +not explicitly described. This can be useful if accessing such +regions has undesired effects for a specific target, or to provide +better error checking. The following commands control this behavior. + +@table @code +@kindex set mem inaccessible-by-default +@item set mem inaccessible-by-default [on|off] +If @code{on} is specified, make @value{GDBN} treat memory not +explicitly described by the memory ranges as non-existent and refuse accesses +to such memory. The checks are only performed if there's at least one +memory range defined. If @code{off} is specified, make @value{GDBN} +treat the memory not explicitly described by the memory ranges as RAM. +The default value is @code{on}. +@kindex show mem inaccessible-by-default +@item show mem inaccessible-by-default +Show the current handling of accesses to unknown memory. +@end table + + +@c @subsubsection Memory Write Verification +@c The memory write verification attributes set whether @value{GDBN} +@c will re-reads data after each write to verify the write was successful. +@c +@c @table @code +@c @item verify +@c @item noverify (default) +@c @end table + +@node Dump/Restore Files +@section Copy Between Memory and a File +@cindex dump/restore files +@cindex append data to a file +@cindex dump data to a file +@cindex restore data from a file + +You can use the commands @code{dump}, @code{append}, and +@code{restore} to copy data between target memory and a file. The +@code{dump} and @code{append} commands write data to a file, and the +@code{restore} command reads data from a file back into the inferior's +memory. Files may be in binary, Motorola S-record, Intel hex, +Tektronix Hex, or Verilog Hex format; however, @value{GDBN} can only +append to binary files, and cannot read from Verilog Hex files. + +@table @code + +@kindex dump +@item dump @r{[}@var{format}@r{]} memory @var{filename} @var{start_addr} @var{end_addr} +@itemx dump @r{[}@var{format}@r{]} value @var{filename} @var{expr} +Dump the contents of memory from @var{start_addr} to @var{end_addr}, +or the value of @var{expr}, to @var{filename} in the given format. + +The @var{format} parameter may be any one of: +@table @code +@item binary +Raw binary form. +@item ihex +Intel hex format. +@item srec +Motorola S-record format. +@item tekhex +Tektronix Hex format. +@item verilog +Verilog Hex format. +@end table + +@value{GDBN} uses the same definitions of these formats as the +@sc{gnu} binary utilities, like @samp{objdump} and @samp{objcopy}. If +@var{format} is omitted, @value{GDBN} dumps the data in raw binary +form. + +@kindex append +@item append @r{[}binary@r{]} memory @var{filename} @var{start_addr} @var{end_addr} +@itemx append @r{[}binary@r{]} value @var{filename} @var{expr} +Append the contents of memory from @var{start_addr} to @var{end_addr}, +or the value of @var{expr}, to the file @var{filename}, in raw binary form. +(@value{GDBN} can only append data to files in raw binary form.) + +@kindex restore +@item restore @var{filename} @r{[}binary@r{]} @var{bias} @var{start} @var{end} +Restore the contents of file @var{filename} into memory. The +@code{restore} command can automatically recognize any known @sc{bfd} +file format, except for raw binary. To restore a raw binary file you +must specify the optional keyword @code{binary} after the filename. + +If @var{bias} is non-zero, its value will be added to the addresses +contained in the file. Binary files always start at address zero, so +they will be restored at address @var{bias}. Other bfd files have +a built-in location; they will be restored at offset @var{bias} +from that location. + +If @var{start} and/or @var{end} are non-zero, then only data between +file offset @var{start} and file offset @var{end} will be restored. +These offsets are relative to the addresses in the file, before +the @var{bias} argument is applied. + +@end table + +@node Core File Generation +@section How to Produce a Core File from Your Program +@cindex dump core from inferior + +A @dfn{core file} or @dfn{core dump} is a file that records the memory +image of a running process and its process status (register values +etc.). Its primary use is post-mortem debugging of a program that +crashed while it ran outside a debugger. A program that crashes +automatically produces a core file, unless this feature is disabled by +the user. @xref{Files}, for information on invoking @value{GDBN} in +the post-mortem debugging mode. + +Occasionally, you may wish to produce a core file of the program you +are debugging in order to preserve a snapshot of its state. +@value{GDBN} has a special command for that. + +@table @code +@kindex gcore +@kindex generate-core-file +@item generate-core-file [@var{file}] +@itemx gcore [@var{file}] +Produce a core dump of the inferior process. The optional argument +@var{file} specifies the file name where to put the core dump. If not +specified, the file name defaults to @file{core.@var{pid}}, where +@var{pid} is the inferior process ID. + +If supported by the filesystem where the core is written to, +@value{GDBN} generates a sparse core dump file. + +Note that this command is implemented only for some systems (as of +this writing, @sc{gnu}/Linux, FreeBSD, Solaris, and S390). + +On @sc{gnu}/Linux, this command can take into account the value of the +file @file{/proc/@var{pid}/coredump_filter} when generating the core +dump (@pxref{set use-coredump-filter}), and by default honors the +@code{VM_DONTDUMP} flag for mappings where it is present in the file +@file{/proc/@var{pid}/smaps} (@pxref{set dump-excluded-mappings}). + +@kindex set use-coredump-filter +@anchor{set use-coredump-filter} +@item set use-coredump-filter on +@itemx set use-coredump-filter off +Enable or disable the use of the file +@file{/proc/@var{pid}/coredump_filter} when generating core dump +files. This file is used by the Linux kernel to decide what types of +memory mappings will be dumped or ignored when generating a core dump +file. @var{pid} is the process ID of a currently running process. + +To make use of this feature, you have to write in the +@file{/proc/@var{pid}/coredump_filter} file a value, in hexadecimal, +which is a bit mask representing the memory mapping types. If a bit +is set in the bit mask, then the memory mappings of the corresponding +types will be dumped; otherwise, they will be ignored. This +configuration is inherited by child processes. For more information +about the bits that can be set in the +@file{/proc/@var{pid}/coredump_filter} file, please refer to the +manpage of @code{core(5)}. + +By default, this option is @code{on}. If this option is turned +@code{off}, @value{GDBN} does not read the @file{coredump_filter} file +and instead uses the same default value as the Linux kernel in order +to decide which pages will be dumped in the core dump file. This +value is currently @code{0x33}, which means that bits @code{0} +(anonymous private mappings), @code{1} (anonymous shared mappings), +@code{4} (ELF headers) and @code{5} (private huge pages) are active. +This will cause these memory mappings to be dumped automatically. + +@kindex set dump-excluded-mappings +@anchor{set dump-excluded-mappings} +@item set dump-excluded-mappings on +@itemx set dump-excluded-mappings off +If @code{on} is specified, @value{GDBN} will dump memory mappings +marked with the @code{VM_DONTDUMP} flag. This flag is represented in +the file @file{/proc/@var{pid}/smaps} with the acronym @code{dd}. + +The default value is @code{off}. +@end table + +@node Character Sets +@section Character Sets +@cindex character sets +@cindex charset +@cindex translating between character sets +@cindex host character set +@cindex target character set + +If the program you are debugging uses a different character set to +represent characters and strings than the one @value{GDBN} uses itself, +@value{GDBN} can automatically translate between the character sets for +you. The character set @value{GDBN} uses we call the @dfn{host +character set}; the one the inferior program uses we call the +@dfn{target character set}. + +For example, if you are running @value{GDBN} on a @sc{gnu}/Linux system, which +uses the ISO Latin 1 character set, but you are using @value{GDBN}'s +remote protocol (@pxref{Remote Debugging}) to debug a program +running on an IBM mainframe, which uses the @sc{ebcdic} character set, +then the host character set is Latin-1, and the target character set is +@sc{ebcdic}. If you give @value{GDBN} the command @code{set +target-charset EBCDIC-US}, then @value{GDBN} translates between +@sc{ebcdic} and Latin 1 as you print character or string values, or use +character and string literals in expressions. + +@value{GDBN} has no way to automatically recognize which character set +the inferior program uses; you must tell it, using the @code{set +target-charset} command, described below. + +Here are the commands for controlling @value{GDBN}'s character set +support: + +@table @code +@item set target-charset @var{charset} +@kindex set target-charset +Set the current target character set to @var{charset}. To display the +list of supported target character sets, type +@kbd{@w{set target-charset @key{TAB}@key{TAB}}}. + +@item set host-charset @var{charset} +@kindex set host-charset +Set the current host character set to @var{charset}. + +By default, @value{GDBN} uses a host character set appropriate to the +system it is running on; you can override that default using the +@code{set host-charset} command. On some systems, @value{GDBN} cannot +automatically determine the appropriate host character set. In this +case, @value{GDBN} uses @samp{UTF-8}. + +@value{GDBN} can only use certain character sets as its host character +set. If you type @kbd{@w{set host-charset @key{TAB}@key{TAB}}}, +@value{GDBN} will list the host character sets it supports. + +@item set charset @var{charset} +@kindex set charset +Set the current host and target character sets to @var{charset}. As +above, if you type @kbd{@w{set charset @key{TAB}@key{TAB}}}, +@value{GDBN} will list the names of the character sets that can be used +for both host and target. + +@item show charset +@kindex show charset +Show the names of the current host and target character sets. + +@item show host-charset +@kindex show host-charset +Show the name of the current host character set. + +@item show target-charset +@kindex show target-charset +Show the name of the current target character set. + +@item set target-wide-charset @var{charset} +@kindex set target-wide-charset +Set the current target's wide character set to @var{charset}. This is +the character set used by the target's @code{wchar_t} type. To +display the list of supported wide character sets, type +@kbd{@w{set target-wide-charset @key{TAB}@key{TAB}}}. + +@item show target-wide-charset +@kindex show target-wide-charset +Show the name of the current target's wide character set. +@end table + +Here is an example of @value{GDBN}'s character set support in action. +Assume that the following source code has been placed in the file +@file{charset-test.c}: + +@smallexample +#include + +char ascii_hello[] + = @{72, 101, 108, 108, 111, 44, 32, 119, + 111, 114, 108, 100, 33, 10, 0@}; +char ibm1047_hello[] + = @{200, 133, 147, 147, 150, 107, 64, 166, + 150, 153, 147, 132, 90, 37, 0@}; + +main () +@{ + printf ("Hello, world!\n"); +@} +@end smallexample + +In this program, @code{ascii_hello} and @code{ibm1047_hello} are arrays +containing the string @samp{Hello, world!} followed by a newline, +encoded in the @sc{ascii} and @sc{ibm1047} character sets. + +We compile the program, and invoke the debugger on it: + +@smallexample +$ gcc -g charset-test.c -o charset-test +$ gdb -nw charset-test +GNU gdb 2001-12-19-cvs +Copyright 2001 Free Software Foundation, Inc. +@dots{} +(@value{GDBP}) +@end smallexample + +We can use the @code{show charset} command to see what character sets +@value{GDBN} is currently using to interpret and display characters and +strings: + +@smallexample +(@value{GDBP}) show charset +The current host and target character set is `ISO-8859-1'. +(@value{GDBP}) +@end smallexample + +For the sake of printing this manual, let's use @sc{ascii} as our +initial character set: +@smallexample +(@value{GDBP}) set charset ASCII +(@value{GDBP}) show charset +The current host and target character set is `ASCII'. +(@value{GDBP}) +@end smallexample + +Let's assume that @sc{ascii} is indeed the correct character set for our +host system --- in other words, let's assume that if @value{GDBN} prints +characters using the @sc{ascii} character set, our terminal will display +them properly. Since our current target character set is also +@sc{ascii}, the contents of @code{ascii_hello} print legibly: + +@smallexample +(@value{GDBP}) print ascii_hello +$1 = 0x401698 "Hello, world!\n" +(@value{GDBP}) print ascii_hello[0] +$2 = 72 'H' +(@value{GDBP}) +@end smallexample + +@value{GDBN} uses the target character set for character and string +literals you use in expressions: + +@smallexample +(@value{GDBP}) print '+' +$3 = 43 '+' +(@value{GDBP}) +@end smallexample + +The @sc{ascii} character set uses the number 43 to encode the @samp{+} +character. + +@value{GDBN} relies on the user to tell it which character set the +target program uses. If we print @code{ibm1047_hello} while our target +character set is still @sc{ascii}, we get jibberish: + +@smallexample +(@value{GDBP}) print ibm1047_hello +$4 = 0x4016a8 "\310\205\223\223\226k@@\246\226\231\223\204Z%" +(@value{GDBP}) print ibm1047_hello[0] +$5 = 200 '\310' +(@value{GDBP}) +@end smallexample + +If we invoke the @code{set target-charset} followed by @key{TAB}@key{TAB}, +@value{GDBN} tells us the character sets it supports: + +@smallexample +(@value{GDBP}) set target-charset +ASCII EBCDIC-US IBM1047 ISO-8859-1 +(@value{GDBP}) set target-charset +@end smallexample + +We can select @sc{ibm1047} as our target character set, and examine the +program's strings again. Now the @sc{ascii} string is wrong, but +@value{GDBN} translates the contents of @code{ibm1047_hello} from the +target character set, @sc{ibm1047}, to the host character set, +@sc{ascii}, and they display correctly: + +@smallexample +(@value{GDBP}) set target-charset IBM1047 +(@value{GDBP}) show charset +The current host character set is `ASCII'. +The current target character set is `IBM1047'. +(@value{GDBP}) print ascii_hello +$6 = 0x401698 "\110\145%%?\054\040\167?\162%\144\041\012" +(@value{GDBP}) print ascii_hello[0] +$7 = 72 '\110' +(@value{GDBP}) print ibm1047_hello +$8 = 0x4016a8 "Hello, world!\n" +(@value{GDBP}) print ibm1047_hello[0] +$9 = 200 'H' +(@value{GDBP}) +@end smallexample + +As above, @value{GDBN} uses the target character set for character and +string literals you use in expressions: + +@smallexample +(@value{GDBP}) print '+' +$10 = 78 '+' +(@value{GDBP}) +@end smallexample + +The @sc{ibm1047} character set uses the number 78 to encode the @samp{+} +character. + +@node Caching Target Data +@section Caching Data of Targets +@cindex caching data of targets + +@value{GDBN} caches data exchanged between the debugger and a target. +Each cache is associated with the address space of the inferior. +@xref{Inferiors Connections and Programs}, about inferior and address space. +Such caching generally improves performance in remote debugging +(@pxref{Remote Debugging}), because it reduces the overhead of the +remote protocol by bundling memory reads and writes into large chunks. +Unfortunately, simply caching everything would lead to incorrect results, +since @value{GDBN} does not necessarily know anything about volatile +values, memory-mapped I/O addresses, etc. Furthermore, in non-stop mode +(@pxref{Non-Stop Mode}) memory can be changed @emph{while} a gdb command +is executing. +Therefore, by default, @value{GDBN} only caches data +known to be on the stack@footnote{In non-stop mode, it is moderately +rare for a running thread to modify the stack of a stopped thread +in a way that would interfere with a backtrace, and caching of +stack reads provides a significant speed up of remote backtraces.} or +in the code segment. +Other regions of memory can be explicitly marked as +cacheable; @pxref{Memory Region Attributes}. + +@table @code +@kindex set remotecache +@item set remotecache on +@itemx set remotecache off +This option no longer does anything; it exists for compatibility +with old scripts. + +@kindex show remotecache +@item show remotecache +Show the current state of the obsolete remotecache flag. + +@kindex set stack-cache +@item set stack-cache on +@itemx set stack-cache off +Enable or disable caching of stack accesses. When @code{on}, use +caching. By default, this option is @code{on}. + +@kindex show stack-cache +@item show stack-cache +Show the current state of data caching for memory accesses. + +@kindex set code-cache +@item set code-cache on +@itemx set code-cache off +Enable or disable caching of code segment accesses. When @code{on}, +use caching. By default, this option is @code{on}. This improves +performance of disassembly in remote debugging. + +@kindex show code-cache +@item show code-cache +Show the current state of target memory cache for code segment +accesses. + +@kindex info dcache +@item info dcache @r{[}line@r{]} +Print the information about the performance of data cache of the +current inferior's address space. The information displayed +includes the dcache width and depth, and for each cache line, its +number, address, and how many times it was referenced. This +command is useful for debugging the data cache operation. + +If a line number is specified, the contents of that line will be +printed in hex. + +@item set dcache size @var{size} +@cindex dcache size +@kindex set dcache size +Set maximum number of entries in dcache (dcache depth above). + +@item set dcache line-size @var{line-size} +@cindex dcache line-size +@kindex set dcache line-size +Set number of bytes each dcache entry caches (dcache width above). +Must be a power of 2. + +@item show dcache size +@kindex show dcache size +Show maximum number of dcache entries. @xref{Caching Target Data, info dcache}. + +@item show dcache line-size +@kindex show dcache line-size +Show default size of dcache lines. + +@item maint flush dcache +@cindex dcache, flushing +@kindex maint flush dcache +Flush the contents (if any) of the dcache. This maintainer command is +useful when debugging the dcache implementation. + +@end table + +@node Searching Memory +@section Search Memory +@cindex searching memory + +Memory can be searched for a particular sequence of bytes with the +@code{find} command. + +@table @code +@kindex find +@item find @r{[}/@var{sn}@r{]} @var{start_addr}, +@var{len}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} +@itemx find @r{[}/@var{sn}@r{]} @var{start_addr}, @var{end_addr}, @var{val1} @r{[}, @var{val2}, @dots{}@r{]} +Search memory for the sequence of bytes specified by @var{val1}, @var{val2}, +etc. The search begins at address @var{start_addr} and continues for either +@var{len} bytes or through to @var{end_addr} inclusive. +@end table + +@var{s} and @var{n} are optional parameters. +They may be specified in either order, apart or together. + +@table @r +@item @var{s}, search query size +The size of each search query value. + +@table @code +@item b +bytes +@item h +halfwords (two bytes) +@item w +words (four bytes) +@item g +giant words (eight bytes) +@end table + +All values are interpreted in the current language. +This means, for example, that if the current source language is C/C@t{++} +then searching for the string ``hello'' includes the trailing '\0'. +The null terminator can be removed from searching by using casts, +e.g.: @samp{@{char[5]@}"hello"}. + +If the value size is not specified, it is taken from the +value's type in the current language. +This is useful when one wants to specify the search +pattern as a mixture of types. +Note that this means, for example, that in the case of C-like languages +a search for an untyped 0x42 will search for @samp{(int) 0x42} +which is typically four bytes. + +@item @var{n}, maximum number of finds +The maximum number of matches to print. The default is to print all finds. +@end table + +You can use strings as search values. Quote them with double-quotes + (@code{"}). +The string value is copied into the search pattern byte by byte, +regardless of the endianness of the target and the size specification. + +The address of each match found is printed as well as a count of the +number of matches found. + +The address of the last value found is stored in convenience variable +@samp{$_}. +A count of the number of matches is stored in @samp{$numfound}. + +For example, if stopped at the @code{printf} in this function: + +@smallexample +void +hello () +@{ + static char hello[] = "hello-hello"; + static struct @{ char c; short s; int i; @} + __attribute__ ((packed)) mixed + = @{ 'c', 0x1234, 0x87654321 @}; + printf ("%s\n", hello); +@} +@end smallexample + +@noindent +you get during debugging: + +@smallexample +(@value{GDBP}) find &hello[0], +sizeof(hello), "hello" +0x804956d +1 pattern found +(@value{GDBP}) find &hello[0], +sizeof(hello), 'h', 'e', 'l', 'l', 'o' +0x8049567 +0x804956d +2 patterns found. +(@value{GDBP}) find &hello[0], +sizeof(hello), @{char[5]@}"hello" +0x8049567 +0x804956d +2 patterns found. +(@value{GDBP}) find /b1 &hello[0], +sizeof(hello), 'h', 0x65, 'l' +0x8049567 +1 pattern found +(@value{GDBP}) find &mixed, +sizeof(mixed), (char) 'c', (short) 0x1234, (int) 0x87654321 +0x8049560 +1 pattern found +(@value{GDBP}) print $numfound +$1 = 1 +(@value{GDBP}) print $_ +$2 = (void *) 0x8049560 +@end smallexample + +@node Value Sizes +@section Value Sizes + +Whenever @value{GDBN} prints a value memory will be allocated within +@value{GDBN} to hold the contents of the value. It is possible in +some languages with dynamic typing systems, that an invalid program +may indicate a value that is incorrectly large, this in turn may cause +@value{GDBN} to try and allocate an overly large amount of memory. + +@table @code +@anchor{set max-value-size} +@kindex set max-value-size +@item set max-value-size @var{bytes} +@itemx set max-value-size unlimited +Set the maximum size of memory that @value{GDBN} will allocate for the +contents of a value to @var{bytes}, trying to display a value that +requires more memory than that will result in an error. + +Setting this variable does not effect values that have already been +allocated within @value{GDBN}, only future allocations. + +There's a minimum size that @code{max-value-size} can be set to in +order that @value{GDBN} can still operate correctly, this minimum is +currently 16 bytes. + +The limit applies to the results of some subexpressions as well as to +complete expressions. For example, an expression denoting a simple +integer component, such as @code{x.y.z}, may fail if the size of +@var{x.y} is dynamic and exceeds @var{bytes}. On the other hand, +@value{GDBN} is sometimes clever; the expression @code{A[i]}, where +@var{A} is an array variable with non-constant size, will generally +succeed regardless of the bounds on @var{A}, as long as the component +size is less than @var{bytes}. + +The default value of @code{max-value-size} is currently 64k. + +@kindex show max-value-size +@item show max-value-size +Show the maximum size of memory, in bytes, that @value{GDBN} will +allocate for the contents of a value. +@end table + +@node Optimized Code +@chapter Debugging Optimized Code +@cindex optimized code, debugging +@cindex debugging optimized code + +Almost all compilers support optimization. With optimization +disabled, the compiler generates assembly code that corresponds +directly to your source code, in a simplistic way. As the compiler +applies more powerful optimizations, the generated assembly code +diverges from your original source code. With help from debugging +information generated by the compiler, @value{GDBN} can map from +the running program back to constructs from your original source. + +@value{GDBN} is more accurate with optimization disabled. If you +can recompile without optimization, it is easier to follow the +progress of your program during debugging. But, there are many cases +where you may need to debug an optimized version. + +When you debug a program compiled with @samp{-g -O}, remember that the +optimizer has rearranged your code; the debugger shows you what is +really there. Do not be too surprised when the execution path does not +exactly match your source file! An extreme example: if you define a +variable, but never use it, @value{GDBN} never sees that +variable---because the compiler optimizes it out of existence. + +Some things do not work as well with @samp{-g -O} as with just +@samp{-g}, particularly on machines with instruction scheduling. If in +doubt, recompile with @samp{-g} alone, and if this fixes the problem, +please report it to us as a bug (including a test case!). +@xref{Variables}, for more information about debugging optimized code. + +@menu +* Inline Functions:: How @value{GDBN} presents inlining +* Tail Call Frames:: @value{GDBN} analysis of jumps to functions +@end menu + +@node Inline Functions +@section Inline Functions +@cindex inline functions, debugging + +@dfn{Inlining} is an optimization that inserts a copy of the function +body directly at each call site, instead of jumping to a shared +routine. @value{GDBN} displays inlined functions just like +non-inlined functions. They appear in backtraces. You can view their +arguments and local variables, step into them with @code{step}, skip +them with @code{next}, and escape from them with @code{finish}. +You can check whether a function was inlined by using the +@code{info frame} command. + +For @value{GDBN} to support inlined functions, the compiler must +record information about inlining in the debug information --- +@value{NGCC} using the @sc{dwarf 2} format does this, and several +other compilers do also. @value{GDBN} only supports inlined functions +when using @sc{dwarf 2}. Versions of @value{NGCC} before 4.1 +do not emit two required attributes (@samp{DW_AT_call_file} and +@samp{DW_AT_call_line}); @value{GDBN} does not display inlined +function calls with earlier versions of @value{NGCC}. It instead +displays the arguments and local variables of inlined functions as +local variables in the caller. + +The body of an inlined function is directly included at its call site; +unlike a non-inlined function, there are no instructions devoted to +the call. @value{GDBN} still pretends that the call site and the +start of the inlined function are different instructions. Stepping to +the call site shows the call site, and then stepping again shows +the first line of the inlined function, even though no additional +instructions are executed. + +This makes source-level debugging much clearer; you can see both the +context of the call and then the effect of the call. Only stepping by +a single instruction using @code{stepi} or @code{nexti} does not do +this; single instruction steps always show the inlined body. + +There are some ways that @value{GDBN} does not pretend that inlined +function calls are the same as normal calls: + +@itemize @bullet +@item +Setting breakpoints at the call site of an inlined function may not +work, because the call site does not contain any code. @value{GDBN} +may incorrectly move the breakpoint to the next line of the enclosing +function, after the call. This limitation will be removed in a future +version of @value{GDBN}; until then, set a breakpoint on an earlier line +or inside the inlined function instead. + +@item +@value{GDBN} cannot locate the return value of inlined calls after +using the @code{finish} command. This is a limitation of compiler-generated +debugging information; after @code{finish}, you can step to the next line +and print a variable where your program stored the return value. + +@end itemize + +@node Tail Call Frames +@section Tail Call Frames +@cindex tail call frames, debugging + +Function @code{B} can call function @code{C} in its very last statement. In +unoptimized compilation the call of @code{C} is immediately followed by return +instruction at the end of @code{B} code. Optimizing compiler may replace the +call and return in function @code{B} into one jump to function @code{C} +instead. Such use of a jump instruction is called @dfn{tail call}. + +During execution of function @code{C}, there will be no indication in the +function call stack frames that it was tail-called from @code{B}. If function +@code{A} regularly calls function @code{B} which tail-calls function @code{C}, +then @value{GDBN} will see @code{A} as the caller of @code{C}. However, in +some cases @value{GDBN} can determine that @code{C} was tail-called from +@code{B}, and it will then create fictitious call frame for that, with the +return address set up as if @code{B} called @code{C} normally. + +This functionality is currently supported only by DWARF 2 debugging format and +the compiler has to produce @samp{DW_TAG_call_site} tags. With +@value{NGCC}, you need to specify @option{-O -g} during compilation, to get +this information. + +@kbd{info frame} command (@pxref{Frame Info}) will indicate the tail call frame +kind by text @code{tail call frame} such as in this sample @value{GDBN} output: + +@smallexample +(@value{GDBP}) x/i $pc - 2 + 0x40066b : jmp 0x400640 +(@value{GDBP}) info frame +Stack level 1, frame at 0x7fffffffda30: + rip = 0x40066d in b (amd64-entry-value.cc:59); saved rip 0x4004c5 + tail call frame, caller of frame at 0x7fffffffda30 + source language c++. + Arglist at unknown address. + Locals at unknown address, Previous frame's sp is 0x7fffffffda30 +@end smallexample + +The detection of all the possible code path executions can find them ambiguous. +There is no execution history stored (possible @ref{Reverse Execution} is never +used for this purpose) and the last known caller could have reached the known +callee by multiple different jump sequences. In such case @value{GDBN} still +tries to show at least all the unambiguous top tail callers and all the +unambiguous bottom tail callees, if any. + +@table @code +@anchor{set debug entry-values} +@item set debug entry-values +@kindex set debug entry-values +When set to on, enables printing of analysis messages for both frame argument +values at function entry and tail calls. It will show all the possible valid +tail calls code paths it has considered. It will also print the intersection +of them with the final unambiguous (possibly partial or even empty) code path +result. + +@item show debug entry-values +@kindex show debug entry-values +Show the current state of analysis messages printing for both frame argument +values at function entry and tail calls. +@end table + +The analysis messages for tail calls can for example show why the virtual tail +call frame for function @code{c} has not been recognized (due to the indirect +reference by variable @code{x}): + +@smallexample +static void __attribute__((noinline, noclone)) c (void); +void (*x) (void) = c; +static void __attribute__((noinline, noclone)) a (void) @{ x++; @} +static void __attribute__((noinline, noclone)) c (void) @{ a (); @} +int main (void) @{ x (); return 0; @} + +Breakpoint 1, DW_OP_entry_value resolving cannot find +DW_TAG_call_site 0x40039a in main +a () at t.c:3 +3 static void __attribute__((noinline, noclone)) a (void) @{ x++; @} +(@value{GDBP}) bt +#0 a () at t.c:3 +#1 0x000000000040039a in main () at t.c:5 +@end smallexample + +Another possibility is an ambiguous virtual tail call frames resolution: + +@smallexample +int i; +static void __attribute__((noinline, noclone)) f (void) @{ i++; @} +static void __attribute__((noinline, noclone)) e (void) @{ f (); @} +static void __attribute__((noinline, noclone)) d (void) @{ f (); @} +static void __attribute__((noinline, noclone)) c (void) @{ d (); @} +static void __attribute__((noinline, noclone)) b (void) +@{ if (i) c (); else e (); @} +static void __attribute__((noinline, noclone)) a (void) @{ b (); @} +int main (void) @{ a (); return 0; @} + +tailcall: initial: 0x4004d2(a) 0x4004ce(b) 0x4004b2(c) 0x4004a2(d) +tailcall: compare: 0x4004d2(a) 0x4004cc(b) 0x400492(e) +tailcall: reduced: 0x4004d2(a) | +(@value{GDBP}) bt +#0 f () at t.c:2 +#1 0x00000000004004d2 in a () at t.c:8 +#2 0x0000000000400395 in main () at t.c:9 +@end smallexample + +@set CALLSEQ1A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}c@value{ARROW}d@value{ARROW}f} +@set CALLSEQ2A @code{main@value{ARROW}a@value{ARROW}b@value{ARROW}e@value{ARROW}f} + +@c Convert CALLSEQ#A to CALLSEQ#B depending on HAVE_MAKEINFO_CLICK. +@ifset HAVE_MAKEINFO_CLICK +@set ARROW @click{} +@set CALLSEQ1B @clicksequence{@value{CALLSEQ1A}} +@set CALLSEQ2B @clicksequence{@value{CALLSEQ2A}} +@end ifset +@ifclear HAVE_MAKEINFO_CLICK +@set ARROW -> +@set CALLSEQ1B @value{CALLSEQ1A} +@set CALLSEQ2B @value{CALLSEQ2A} +@end ifclear + +Frames #0 and #2 are real, #1 is a virtual tail call frame. +The code can have possible execution paths @value{CALLSEQ1B} or +@value{CALLSEQ2B}, @value{GDBN} cannot find which one from the inferior state. + +@code{initial:} state shows some random possible calling sequence @value{GDBN} +has found. It then finds another possible calling sequence - that one is +prefixed by @code{compare:}. The non-ambiguous intersection of these two is +printed as the @code{reduced:} calling sequence. That one could have many +further @code{compare:} and @code{reduced:} statements as long as there remain +any non-ambiguous sequence entries. + +For the frame of function @code{b} in both cases there are different possible +@code{$pc} values (@code{0x4004cc} or @code{0x4004ce}), therefore this frame is +also ambiguous. The only non-ambiguous frame is the one for function @code{a}, +therefore this one is displayed to the user while the ambiguous frames are +omitted. + +There can be also reasons why printing of frame argument values at function +entry may fail: + +@smallexample +int v; +static void __attribute__((noinline, noclone)) c (int i) @{ v++; @} +static void __attribute__((noinline, noclone)) a (int i); +static void __attribute__((noinline, noclone)) b (int i) @{ a (i); @} +static void __attribute__((noinline, noclone)) a (int i) +@{ if (i) b (i - 1); else c (0); @} +int main (void) @{ a (5); return 0; @} + +(@value{GDBP}) bt +#0 c (i=i@@entry=0) at t.c:2 +#1 0x0000000000400428 in a (DW_OP_entry_value resolving has found +function "a" at 0x400420 can call itself via tail calls +i=) at t.c:6 +#2 0x000000000040036e in main () at t.c:7 +@end smallexample + +@value{GDBN} cannot find out from the inferior state if and how many times did +function @code{a} call itself (via function @code{b}) as these calls would be +tail calls. Such tail calls would modify the @code{i} variable, therefore +@value{GDBN} cannot be sure the value it knows would be right - @value{GDBN} +prints @code{} instead. + +@node Macros +@chapter C Preprocessor Macros + +Some languages, such as C and C@t{++}, provide a way to define and invoke +``preprocessor macros'' which expand into strings of tokens. +@value{GDBN} can evaluate expressions containing macro invocations, show +the result of macro expansion, and show a macro's definition, including +where it was defined. + +You may need to compile your program specially to provide @value{GDBN} +with information about preprocessor macros. Most compilers do not +include macros in their debugging information, even when you compile +with the @option{-g} flag. @xref{Compilation}. + +A program may define a macro at one point, remove that definition later, +and then provide a different definition after that. Thus, at different +points in the program, a macro may have different definitions, or have +no definition at all. If there is a current stack frame, @value{GDBN} +uses the macros in scope at that frame's source code line. Otherwise, +@value{GDBN} uses the macros in scope at the current listing location; +see @ref{List}. + +Whenever @value{GDBN} evaluates an expression, it always expands any +macro invocations present in the expression. @value{GDBN} also provides +the following commands for working with macros explicitly. + +@table @code + +@kindex macro expand +@cindex macro expansion, showing the results of preprocessor +@cindex preprocessor macro expansion, showing the results of +@cindex expanding preprocessor macros +@item macro expand @var{expression} +@itemx macro exp @var{expression} +Show the results of expanding all preprocessor macro invocations in +@var{expression}. Since @value{GDBN} simply expands macros, but does +not parse the result, @var{expression} need not be a valid expression; +it can be any string of tokens. + +@kindex macro exp1 +@item macro expand-once @var{expression} +@itemx macro exp1 @var{expression} +@cindex expand macro once +@i{(This command is not yet implemented.)} Show the results of +expanding those preprocessor macro invocations that appear explicitly in +@var{expression}. Macro invocations appearing in that expansion are +left unchanged. This command allows you to see the effect of a +particular macro more clearly, without being confused by further +expansions. Since @value{GDBN} simply expands macros, but does not +parse the result, @var{expression} need not be a valid expression; it +can be any string of tokens. + +@kindex info macro +@cindex macro definition, showing +@cindex definition of a macro, showing +@cindex macros, from debug info +@item info macro [-a|-all] [--] @var{macro} +Show the current definition or all definitions of the named @var{macro}, +and describe the source location or compiler command-line where that +definition was established. The optional double dash is to signify the end of +argument processing and the beginning of @var{macro} for non C-like macros where +the macro may begin with a hyphen. + +@kindex info macros +@item info macros @var{locspec} +Show all macro definitions that are in effect at the source line of +the code location that results from resolving @var{locspec}, and +describe the source location or compiler command-line where those +definitions were established. + +@kindex macro define +@cindex user-defined macros +@cindex defining macros interactively +@cindex macros, user-defined +@item macro define @var{macro} @var{replacement-list} +@itemx macro define @var{macro}(@var{arglist}) @var{replacement-list} +Introduce a definition for a preprocessor macro named @var{macro}, +invocations of which are replaced by the tokens given in +@var{replacement-list}. The first form of this command defines an +``object-like'' macro, which takes no arguments; the second form +defines a ``function-like'' macro, which takes the arguments given in +@var{arglist}. + +A definition introduced by this command is in scope in every +expression evaluated in @value{GDBN}, until it is removed with the +@code{macro undef} command, described below. The definition overrides +all definitions for @var{macro} present in the program being debugged, +as well as any previous user-supplied definition. + +@kindex macro undef +@item macro undef @var{macro} +Remove any user-supplied definition for the macro named @var{macro}. +This command only affects definitions provided with the @code{macro +define} command, described above; it cannot remove definitions present +in the program being debugged. + +@kindex macro list +@item macro list +List all the macros defined using the @code{macro define} command. +@end table + +@cindex macros, example of debugging with +Here is a transcript showing the above commands in action. First, we +show our source files: + +@smallexample +$ cat sample.c +#include +#include "sample.h" + +#define M 42 +#define ADD(x) (M + x) + +main () +@{ +#define N 28 + printf ("Hello, world!\n"); +#undef N + printf ("We're so creative.\n"); +#define N 1729 + printf ("Goodbye, world!\n"); +@} +$ cat sample.h +#define Q < +$ +@end smallexample + +Now, we compile the program using the @sc{gnu} C compiler, +@value{NGCC}. We pass the @option{-gdwarf-2}@footnote{This is the +minimum. Recent versions of @value{NGCC} support @option{-gdwarf-3} +and @option{-gdwarf-4}; we recommend always choosing the most recent +version of DWARF.} @emph{and} @option{-g3} flags to ensure the compiler +includes information about preprocessor macros in the debugging +information. + +@smallexample +$ gcc -gdwarf-2 -g3 sample.c -o sample +$ +@end smallexample + +Now, we start @value{GDBN} on our sample program: + +@smallexample +$ gdb -nw sample +GNU gdb 2002-05-06-cvs +Copyright 2002 Free Software Foundation, Inc. +GDB is free software, @dots{} +(@value{GDBP}) +@end smallexample + +We can expand macros and examine their definitions, even when the +program is not running. @value{GDBN} uses the current listing position +to decide which macro definitions are in scope: + +@smallexample +(@value{GDBP}) list main +3 +4 #define M 42 +5 #define ADD(x) (M + x) +6 +7 main () +8 @{ +9 #define N 28 +10 printf ("Hello, world!\n"); +11 #undef N +12 printf ("We're so creative.\n"); +(@value{GDBP}) info macro ADD +Defined at /home/jimb/gdb/macros/play/sample.c:5 +#define ADD(x) (M + x) +(@value{GDBP}) info macro Q +Defined at /home/jimb/gdb/macros/play/sample.h:1 + included at /home/jimb/gdb/macros/play/sample.c:2 +#define Q < +(@value{GDBP}) macro expand ADD(1) +expands to: (42 + 1) +(@value{GDBP}) macro expand-once ADD(1) +expands to: once (M + 1) +(@value{GDBP}) +@end smallexample + +In the example above, note that @code{macro expand-once} expands only +the macro invocation explicit in the original text --- the invocation of +@code{ADD} --- but does not expand the invocation of the macro @code{M}, +which was introduced by @code{ADD}. + +Once the program is running, @value{GDBN} uses the macro definitions in +force at the source line of the current stack frame: + +@smallexample +(@value{GDBP}) break main +Breakpoint 1 at 0x8048370: file sample.c, line 10. +(@value{GDBP}) run +Starting program: /home/jimb/gdb/macros/play/sample + +Breakpoint 1, main () at sample.c:10 +10 printf ("Hello, world!\n"); +(@value{GDBP}) +@end smallexample + +At line 10, the definition of the macro @code{N} at line 9 is in force: + +@smallexample +(@value{GDBP}) info macro N +Defined at /home/jimb/gdb/macros/play/sample.c:9 +#define N 28 +(@value{GDBP}) macro expand N Q M +expands to: 28 < 42 +(@value{GDBP}) print N Q M +$1 = 1 +(@value{GDBP}) +@end smallexample + +As we step over directives that remove @code{N}'s definition, and then +give it a new definition, @value{GDBN} finds the definition (or lack +thereof) in force at each point: + +@smallexample +(@value{GDBP}) next +Hello, world! +12 printf ("We're so creative.\n"); +(@value{GDBP}) info macro N +The symbol `N' has no definition as a C/C++ preprocessor macro +at /home/jimb/gdb/macros/play/sample.c:12 +(@value{GDBP}) next +We're so creative. +14 printf ("Goodbye, world!\n"); +(@value{GDBP}) info macro N +Defined at /home/jimb/gdb/macros/play/sample.c:13 +#define N 1729 +(@value{GDBP}) macro expand N Q M +expands to: 1729 < 42 +(@value{GDBP}) print N Q M +$2 = 0 +(@value{GDBP}) +@end smallexample + +In addition to source files, macros can be defined on the compilation command +line using the @option{-D@var{name}=@var{value}} syntax. For macros defined in +such a way, @value{GDBN} displays the location of their definition as line zero +of the source file submitted to the compiler. + +@smallexample +(@value{GDBP}) info macro __STDC__ +Defined at /home/jimb/gdb/macros/play/sample.c:0 +-D__STDC__=1 +(@value{GDBP}) +@end smallexample + + +@node Tracepoints +@chapter Tracepoints +@c This chapter is based on the documentation written by Michael +@c Snyder, David Taylor, Jim Blandy, and Elena Zannoni. + +@cindex tracepoints +In some applications, it is not feasible for the debugger to interrupt +the program's execution long enough for the developer to learn +anything helpful about its behavior. If the program's correctness +depends on its real-time behavior, delays introduced by a debugger +might cause the program to change its behavior drastically, or perhaps +fail, even when the code itself is correct. It is useful to be able +to observe the program's behavior without interrupting it. + +Using @value{GDBN}'s @code{trace} and @code{collect} commands, you can +specify locations in the program, called @dfn{tracepoints}, and +arbitrary expressions to evaluate when those tracepoints are reached. +Later, using the @code{tfind} command, you can examine the values +those expressions had when the program hit the tracepoints. The +expressions may also denote objects in memory---structures or arrays, +for example---whose values @value{GDBN} should record; while visiting +a particular tracepoint, you may inspect those objects as if they were +in memory at that moment. However, because @value{GDBN} records these +values without interacting with you, it can do so quickly and +unobtrusively, hopefully not disturbing the program's behavior. + +The tracepoint facility is currently available only for remote +targets. @xref{Targets}. In addition, your remote target must know +how to collect trace data. This functionality is implemented in the +remote stub; however, none of the stubs distributed with @value{GDBN} +support tracepoints as of this writing. The format of the remote +packets used to implement tracepoints are described in @ref{Tracepoint +Packets}. + +It is also possible to get trace data from a file, in a manner reminiscent +of corefiles; you specify the filename, and use @code{tfind} to search +through the file. @xref{Trace Files}, for more details. + +This chapter describes the tracepoint commands and features. + +@menu +* Set Tracepoints:: +* Analyze Collected Data:: +* Tracepoint Variables:: +* Trace Files:: +@end menu + +@node Set Tracepoints +@section Commands to Set Tracepoints + +Before running such a @dfn{trace experiment}, an arbitrary number of +tracepoints can be set. A tracepoint is actually a special type of +breakpoint (@pxref{Set Breaks}), so you can manipulate it using +standard breakpoint commands. For instance, as with breakpoints, +tracepoint numbers are successive integers starting from one, and many +of the commands associated with tracepoints take the tracepoint number +as their argument, to identify which tracepoint to work on. + +For each tracepoint, you can specify, in advance, some arbitrary set +of data that you want the target to collect in the trace buffer when +it hits that tracepoint. The collected data can include registers, +local variables, or global data. Later, you can use @value{GDBN} +commands to examine the values these data had at the time the +tracepoint was hit. + +Tracepoints do not support every breakpoint feature. Ignore counts on +tracepoints have no effect, and tracepoints cannot run @value{GDBN} +commands when they are hit. Tracepoints may not be thread-specific +either. + +@cindex fast tracepoints +Some targets may support @dfn{fast tracepoints}, which are inserted in +a different way (such as with a jump instead of a trap), that is +faster but possibly restricted in where they may be installed. + +@cindex static tracepoints +@cindex markers, static tracepoints +@cindex probing markers, static tracepoints +Regular and fast tracepoints are dynamic tracing facilities, meaning +that they can be used to insert tracepoints at (almost) any location +in the target. Some targets may also support controlling @dfn{static +tracepoints} from @value{GDBN}. With static tracing, a set of +instrumentation points, also known as @dfn{markers}, are embedded in +the target program, and can be activated or deactivated by name or +address. These are usually placed at locations which facilitate +investigating what the target is actually doing. @value{GDBN}'s +support for static tracing includes being able to list instrumentation +points, and attach them with @value{GDBN} defined high level +tracepoints that expose the whole range of convenience of +@value{GDBN}'s tracepoints support. Namely, support for collecting +registers values and values of global or local (to the instrumentation +point) variables; tracepoint conditions and trace state variables. +The act of installing a @value{GDBN} static tracepoint on an +instrumentation point, or marker, is referred to as @dfn{probing} a +static tracepoint marker. + +@code{gdbserver} supports tracepoints on some target systems. +@xref{Server,,Tracepoints support in @code{gdbserver}}. + +This section describes commands to set tracepoints and associated +conditions and actions. + +@menu +* Create and Delete Tracepoints:: +* Enable and Disable Tracepoints:: +* Tracepoint Passcounts:: +* Tracepoint Conditions:: +* Trace State Variables:: +* Tracepoint Actions:: +* Listing Tracepoints:: +* Listing Static Tracepoint Markers:: +* Starting and Stopping Trace Experiments:: +* Tracepoint Restrictions:: +@end menu + +@node Create and Delete Tracepoints +@subsection Create and Delete Tracepoints + +@table @code +@cindex set tracepoint +@kindex trace +@item trace @var{locspec} +The @code{trace} command is very similar to the @code{break} command. +Its argument @var{locspec} can be any valid location specification. +@xref{Location Specifications}. The @code{trace} command defines a tracepoint, +which is a point in the target program where the debugger will briefly stop, +collect some data, and then allow the program to continue. Setting a tracepoint +or changing its actions takes effect immediately if the remote stub +supports the @samp{InstallInTrace} feature (@pxref{install tracepoint +in tracing}). +If remote stub doesn't support the @samp{InstallInTrace} feature, all +these changes don't take effect until the next @code{tstart} +command, and once a trace experiment is running, further changes will +not have any effect until the next trace experiment starts. In addition, +@value{GDBN} supports @dfn{pending tracepoints}---tracepoints whose +address is not yet resolved. (This is similar to pending breakpoints.) +Pending tracepoints are not downloaded to the target and not installed +until they are resolved. The resolution of pending tracepoints requires +@value{GDBN} support---when debugging with the remote target, and +@value{GDBN} disconnects from the remote stub (@pxref{disconnected +tracing}), pending tracepoints can not be resolved (and downloaded to +the remote stub) while @value{GDBN} is disconnected. + +Here are some examples of using the @code{trace} command: + +@smallexample +(@value{GDBP}) @b{trace foo.c:121} // a source file and line number + +(@value{GDBP}) @b{trace +2} // 2 lines forward + +(@value{GDBP}) @b{trace my_function} // first source line of function + +(@value{GDBP}) @b{trace *my_function} // EXACT start address of function + +(@value{GDBP}) @b{trace *0x2117c4} // an address +@end smallexample + +@noindent +You can abbreviate @code{trace} as @code{tr}. + +@item trace @var{locspec} if @var{cond} +Set a tracepoint with condition @var{cond}; evaluate the expression +@var{cond} each time the tracepoint is reached, and collect data only +if the value is nonzero---that is, if @var{cond} evaluates as true. +@xref{Tracepoint Conditions, ,Tracepoint Conditions}, for more +information on tracepoint conditions. + +@item ftrace @var{locspec} [ if @var{cond} ] +@cindex set fast tracepoint +@cindex fast tracepoints, setting +@kindex ftrace +The @code{ftrace} command sets a fast tracepoint. For targets that +support them, fast tracepoints will use a more efficient but possibly +less general technique to trigger data collection, such as a jump +instruction instead of a trap, or some sort of hardware support. It +may not be possible to create a fast tracepoint at the desired +location, in which case the command will exit with an explanatory +message. + +@value{GDBN} handles arguments to @code{ftrace} exactly as for +@code{trace}. + +On 32-bit x86-architecture systems, fast tracepoints normally need to +be placed at an instruction that is 5 bytes or longer, but can be +placed at 4-byte instructions if the low 64K of memory of the target +program is available to install trampolines. Some Unix-type systems, +such as @sc{gnu}/Linux, exclude low addresses from the program's +address space; but for instance with the Linux kernel it is possible +to let @value{GDBN} use this area by doing a @command{sysctl} command +to set the @code{mmap_min_addr} kernel parameter, as in + +@example +sudo sysctl -w vm.mmap_min_addr=32768 +@end example + +@noindent +which sets the low address to 32K, which leaves plenty of room for +trampolines. The minimum address should be set to a page boundary. + +@item strace [@var{locspec} | -m @var{marker}] [ if @var{cond} ] +@cindex set static tracepoint +@cindex static tracepoints, setting +@cindex probe static tracepoint marker +@kindex strace +The @code{strace} command sets a static tracepoint. For targets that +support it, setting a static tracepoint probes a static +instrumentation point, or marker, found at the code locations that +result from resolving @var{locspec}. It may not be possible to set a +static tracepoint at the desired code location, in which case the +command will exit with an explanatory message. + +@value{GDBN} handles arguments to @code{strace} exactly as for +@code{trace}, with the addition that the user can also specify +@code{-m @var{marker}} instead of a location spec. This probes the marker +identified by the @var{marker} string identifier. This identifier +depends on the static tracepoint backend library your program is +using. You can find all the marker identifiers in the @samp{ID} field +of the @code{info static-tracepoint-markers} command output. +@xref{Listing Static Tracepoint Markers,,Listing Static Tracepoint +Markers}. For example, in the following small program using the UST +tracing engine: + +@smallexample +main () +@{ + trace_mark(ust, bar33, "str %s", "FOOBAZ"); +@} +@end smallexample + +@noindent +the marker id is composed of joining the first two arguments to the +@code{trace_mark} call with a slash, which translates to: + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt Enb ID Address What +1 n ust/bar33 0x0000000000400ddc in main at stexample.c:22 + Data: "str %s" +[etc...] +@end smallexample + +@noindent +so you may probe the marker above with: + +@smallexample +(@value{GDBP}) strace -m ust/bar33 +@end smallexample + +Static tracepoints accept an extra collect action --- @code{collect +$_sdata}. This collects arbitrary user data passed in the probe point +call to the tracing library. In the UST example above, you'll see +that the third argument to @code{trace_mark} is a printf-like format +string. The user data is then the result of running that formatting +string against the following arguments. Note that @code{info +static-tracepoint-markers} command output lists that format string in +the @samp{Data:} field. + +You can inspect this data when analyzing the trace buffer, by printing +the $_sdata variable like any other variable available to +@value{GDBN}. @xref{Tracepoint Actions,,Tracepoint Action Lists}. + +@vindex $tpnum +@cindex last tracepoint number +@cindex recent tracepoint number +@cindex tracepoint number +The convenience variable @code{$tpnum} records the tracepoint number +of the most recently set tracepoint. + +@kindex delete tracepoint +@cindex tracepoint deletion +@item delete tracepoint @r{[}@var{num}@r{]} +Permanently delete one or more tracepoints. With no argument, the +default is to delete all tracepoints. Note that the regular +@code{delete} command can remove tracepoints also. + +Examples: + +@smallexample +(@value{GDBP}) @b{delete trace 1 2 3} // remove three tracepoints + +(@value{GDBP}) @b{delete trace} // remove all tracepoints +@end smallexample + +@noindent +You can abbreviate this command as @code{del tr}. +@end table + +@node Enable and Disable Tracepoints +@subsection Enable and Disable Tracepoints + +These commands are deprecated; they are equivalent to plain @code{disable} and @code{enable}. + +@table @code +@kindex disable tracepoint +@item disable tracepoint @r{[}@var{num}@r{]} +Disable tracepoint @var{num}, or all tracepoints if no argument +@var{num} is given. A disabled tracepoint will have no effect during +a trace experiment, but it is not forgotten. You can re-enable +a disabled tracepoint using the @code{enable tracepoint} command. +If the command is issued during a trace experiment and the debug target +has support for disabling tracepoints during a trace experiment, then the +change will be effective immediately. Otherwise, it will be applied to the +next trace experiment. + +@kindex enable tracepoint +@item enable tracepoint @r{[}@var{num}@r{]} +Enable tracepoint @var{num}, or all tracepoints. If this command is +issued during a trace experiment and the debug target supports enabling +tracepoints during a trace experiment, then the enabled tracepoints will +become effective immediately. Otherwise, they will become effective the +next time a trace experiment is run. +@end table + +@node Tracepoint Passcounts +@subsection Tracepoint Passcounts + +@table @code +@kindex passcount +@cindex tracepoint pass count +@item passcount @r{[}@var{n} @r{[}@var{num}@r{]]} +Set the @dfn{passcount} of a tracepoint. The passcount is a way to +automatically stop a trace experiment. If a tracepoint's passcount is +@var{n}, then the trace experiment will be automatically stopped on +the @var{n}'th time that tracepoint is hit. If the tracepoint number +@var{num} is not specified, the @code{passcount} command sets the +passcount of the most recently defined tracepoint. If no passcount is +given, the trace experiment will run until stopped explicitly by the +user. + +Examples: + +@smallexample +(@value{GDBP}) @b{passcount 5 2} // Stop on the 5th execution of +@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// tracepoint 2} + +(@value{GDBP}) @b{passcount 12} // Stop on the 12th execution of the +@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// most recently defined tracepoint.} +(@value{GDBP}) @b{trace foo} +(@value{GDBP}) @b{pass 3} +(@value{GDBP}) @b{trace bar} +(@value{GDBP}) @b{pass 2} +(@value{GDBP}) @b{trace baz} +(@value{GDBP}) @b{pass 1} // Stop tracing when foo has been +@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// executed 3 times OR when bar has} +@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// been executed 2 times} +@exdent @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @ @code{// OR when baz has been executed 1 time.} +@end smallexample +@end table + +@node Tracepoint Conditions +@subsection Tracepoint Conditions +@cindex conditional tracepoints +@cindex tracepoint conditions + +The simplest sort of tracepoint collects data every time your program +reaches a specified place. You can also specify a @dfn{condition} for +a tracepoint. A condition is just a Boolean expression in your +programming language (@pxref{Expressions, ,Expressions}). A +tracepoint with a condition evaluates the expression each time your +program reaches it, and data collection happens only if the condition +is true. + +Tracepoint conditions can be specified when a tracepoint is set, by +using @samp{if} in the arguments to the @code{trace} command. +@xref{Create and Delete Tracepoints, ,Setting Tracepoints}. They can +also be set or changed at any time with the @code{condition} command, +just as with breakpoints. + +Unlike breakpoint conditions, @value{GDBN} does not actually evaluate +the conditional expression itself. Instead, @value{GDBN} encodes the +expression into an agent expression (@pxref{Agent Expressions}) +suitable for execution on the target, independently of @value{GDBN}. +Global variables become raw memory locations, locals become stack +accesses, and so forth. + +For instance, suppose you have a function that is usually called +frequently, but should not be called after an error has occurred. You +could use the following tracepoint command to collect data about calls +of that function that happen while the error code is propagating +through the program; an unconditional tracepoint could end up +collecting thousands of useless trace frames that you would have to +search through. + +@smallexample +(@value{GDBP}) @kbd{trace normal_operation if errcode > 0} +@end smallexample + +@node Trace State Variables +@subsection Trace State Variables +@cindex trace state variables + +A @dfn{trace state variable} is a special type of variable that is +created and managed by target-side code. The syntax is the same as +that for GDB's convenience variables (a string prefixed with ``$''), +but they are stored on the target. They must be created explicitly, +using a @code{tvariable} command. They are always 64-bit signed +integers. + +Trace state variables are remembered by @value{GDBN}, and downloaded +to the target along with tracepoint information when the trace +experiment starts. There are no intrinsic limits on the number of +trace state variables, beyond memory limitations of the target. + +@cindex convenience variables, and trace state variables +Although trace state variables are managed by the target, you can use +them in print commands and expressions as if they were convenience +variables; @value{GDBN} will get the current value from the target +while the trace experiment is running. Trace state variables share +the same namespace as other ``$'' variables, which means that you +cannot have trace state variables with names like @code{$23} or +@code{$pc}, nor can you have a trace state variable and a convenience +variable with the same name. + +@table @code + +@item tvariable $@var{name} [ = @var{expression} ] +@kindex tvariable +The @code{tvariable} command creates a new trace state variable named +@code{$@var{name}}, and optionally gives it an initial value of +@var{expression}. The @var{expression} is evaluated when this command is +entered; the result will be converted to an integer if possible, +otherwise @value{GDBN} will report an error. A subsequent +@code{tvariable} command specifying the same name does not create a +variable, but instead assigns the supplied initial value to the +existing variable of that name, overwriting any previous initial +value. The default initial value is 0. + +@item info tvariables +@kindex info tvariables +List all the trace state variables along with their initial values. +Their current values may also be displayed, if the trace experiment is +currently running. + +@item delete tvariable @r{[} $@var{name} @dots{} @r{]} +@kindex delete tvariable +Delete the given trace state variables, or all of them if no arguments +are specified. + +@end table + +@node Tracepoint Actions +@subsection Tracepoint Action Lists + +@table @code +@kindex actions +@cindex tracepoint actions +@item actions @r{[}@var{num}@r{]} +This command will prompt for a list of actions to be taken when the +tracepoint is hit. If the tracepoint number @var{num} is not +specified, this command sets the actions for the one that was most +recently defined (so that you can define a tracepoint and then say +@code{actions} without bothering about its number). You specify the +actions themselves on the following lines, one action at a time, and +terminate the actions list with a line containing just @code{end}. So +far, the only defined actions are @code{collect}, @code{teval}, and +@code{while-stepping}. + +@code{actions} is actually equivalent to @code{commands} (@pxref{Break +Commands, ,Breakpoint Command Lists}), except that only the defined +actions are allowed; any other @value{GDBN} command is rejected. + +@cindex remove actions from a tracepoint +To remove all actions from a tracepoint, type @samp{actions @var{num}} +and follow it immediately with @samp{end}. + +@smallexample +(@value{GDBP}) @b{collect @var{data}} // collect some data + +(@value{GDBP}) @b{while-stepping 5} // single-step 5 times, collect data + +(@value{GDBP}) @b{end} // signals the end of actions. +@end smallexample + +In the following example, the action list begins with @code{collect} +commands indicating the things to be collected when the tracepoint is +hit. Then, in order to single-step and collect additional data +following the tracepoint, a @code{while-stepping} command is used, +followed by the list of things to be collected after each step in a +sequence of single steps. The @code{while-stepping} command is +terminated by its own separate @code{end} command. Lastly, the action +list is terminated by an @code{end} command. + +@smallexample +(@value{GDBP}) @b{trace foo} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint 1, one per line: +> collect bar,baz +> collect $regs +> while-stepping 12 + > collect $pc, arr[i] + > end +end +@end smallexample + +@kindex collect @r{(tracepoints)} +@item collect@r{[}/@var{mods}@r{]} @var{expr1}, @var{expr2}, @dots{} +Collect values of the given expressions when the tracepoint is hit. +This command accepts a comma-separated list of any valid expressions. +In addition to global, static, or local variables, the following +special arguments are supported: + +@table @code +@item $regs +Collect all registers. + +@item $args +Collect all function arguments. + +@item $locals +Collect all local variables. + +@item $_ret +Collect the return address. This is helpful if you want to see more +of a backtrace. + +@emph{Note:} The return address location can not always be reliably +determined up front, and the wrong address / registers may end up +collected instead. On some architectures the reliability is higher +for tracepoints at function entry, while on others it's the opposite. +When this happens, backtracing will stop because the return address is +found unavailable (unless another collect rule happened to match it). + +@item $_probe_argc +Collects the number of arguments from the static probe at which the +tracepoint is located. +@xref{Static Probe Points}. + +@item $_probe_arg@var{n} +@var{n} is an integer between 0 and 11. Collects the @var{n}th argument +from the static probe at which the tracepoint is located. +@xref{Static Probe Points}. + +@item $_sdata +@vindex $_sdata@r{, collect} +Collect static tracepoint marker specific data. Only available for +static tracepoints. @xref{Tracepoint Actions,,Tracepoint Action +Lists}. On the UST static tracepoints library backend, an +instrumentation point resembles a @code{printf} function call. The +tracing library is able to collect user specified data formatted to a +character string using the format provided by the programmer that +instrumented the program. Other backends have similar mechanisms. +Here's an example of a UST marker call: + +@smallexample + const char master_name[] = "$your_name"; + trace_mark(channel1, marker1, "hello %s", master_name) +@end smallexample + +In this case, collecting @code{$_sdata} collects the string +@samp{hello $yourname}. When analyzing the trace buffer, you can +inspect @samp{$_sdata} like any other variable available to +@value{GDBN}. +@end table + +You can give several consecutive @code{collect} commands, each one +with a single argument, or one @code{collect} command with several +arguments separated by commas; the effect is the same. + +The optional @var{mods} changes the usual handling of the arguments. +@code{s} requests that pointers to chars be handled as strings, in +particular collecting the contents of the memory being pointed at, up +to the first zero. The upper bound is by default the value of the +@code{print characters} variable; if @code{s} is followed by a decimal +number, that is the upper bound instead. So for instance +@samp{collect/s25 mystr} collects as many as 25 characters at +@samp{mystr}. + +The command @code{info scope} (@pxref{Symbols, info scope}) is +particularly useful for figuring out what data to collect. + +@kindex teval @r{(tracepoints)} +@item teval @var{expr1}, @var{expr2}, @dots{} +Evaluate the given expressions when the tracepoint is hit. This +command accepts a comma-separated list of expressions. The results +are discarded, so this is mainly useful for assigning values to trace +state variables (@pxref{Trace State Variables}) without adding those +values to the trace buffer, as would be the case if the @code{collect} +action were used. + +@kindex while-stepping @r{(tracepoints)} +@item while-stepping @var{n} +Perform @var{n} single-step instruction traces after the tracepoint, +collecting new data after each step. The @code{while-stepping} +command is followed by the list of what to collect while stepping +(followed by its own @code{end} command): + +@smallexample +> while-stepping 12 + > collect $regs, myglobal + > end +> +@end smallexample + +@noindent +Note that @code{$pc} is not automatically collected by +@code{while-stepping}; you need to explicitly collect that register if +you need it. You may abbreviate @code{while-stepping} as @code{ws} or +@code{stepping}. + +@item set default-collect @var{expr1}, @var{expr2}, @dots{} +@kindex set default-collect +@cindex default collection action +This variable is a list of expressions to collect at each tracepoint +hit. It is effectively an additional @code{collect} action prepended +to every tracepoint action list. The expressions are parsed +individually for each tracepoint, so for instance a variable named +@code{xyz} may be interpreted as a global for one tracepoint, and a +local for another, as appropriate to the tracepoint's location. + +@item show default-collect +@kindex show default-collect +Show the list of expressions that are collected by default at each +tracepoint hit. + +@end table + +@node Listing Tracepoints +@subsection Listing Tracepoints + +@table @code +@kindex info tracepoints @r{[}@var{n}@dots{}@r{]} +@kindex info tp @r{[}@var{n}@dots{}@r{]} +@cindex information about tracepoints +@item info tracepoints @r{[}@var{num}@dots{}@r{]} +Display information about the tracepoint @var{num}. If you don't +specify a tracepoint number, displays information about all the +tracepoints defined so far. The format is similar to that used for +@code{info breakpoints}; in fact, @code{info tracepoints} is the same +command, simply restricting itself to tracepoints. + +A tracepoint's listing may include additional information specific to +tracing: + +@itemize @bullet +@item +its passcount as given by the @code{passcount @var{n}} command + +@item +the state about installed on target of each location +@end itemize + +@smallexample +(@value{GDBP}) @b{info trace} +Num Type Disp Enb Address What +1 tracepoint keep y 0x0804ab57 in foo() at main.cxx:7 + while-stepping 20 + collect globfoo, $regs + end + collect globfoo2 + end + pass count 1200 +2 tracepoint keep y + collect $eip +2.1 y 0x0804859c in func4 at change-loc.h:35 + installed on target +2.2 y 0xb7ffc480 in func4 at change-loc.h:35 + installed on target +2.3 y set_tracepoint +3 tracepoint keep y 0x080485b1 in foo at change-loc.c:29 + not installed on target +(@value{GDBP}) +@end smallexample + +@noindent +This command can be abbreviated @code{info tp}. +@end table + +@node Listing Static Tracepoint Markers +@subsection Listing Static Tracepoint Markers + +@table @code +@kindex info static-tracepoint-markers +@cindex information about static tracepoint markers +@item info static-tracepoint-markers +Display information about all static tracepoint markers defined in the +program. + +For each marker, the following columns are printed: + +@table @emph +@item Count +An incrementing counter, output to help readability. This is not a +stable identifier. +@item ID +The marker ID, as reported by the target. +@item Enabled or Disabled +Probed markers are tagged with @samp{y}. @samp{n} identifies marks +that are not enabled. +@item Address +Where the marker is in your program, as a memory address. +@item What +Where the marker is in the source for your program, as a file and line +number. If the debug information included in the program does not +allow @value{GDBN} to locate the source of the marker, this column +will be left blank. +@end table + +@noindent +In addition, the following information may be printed for each marker: + +@table @emph +@item Data +User data passed to the tracing library by the marker call. In the +UST backend, this is the format string passed as argument to the +marker call. +@item Static tracepoints probing the marker +The list of static tracepoints attached to the marker. +@end table + +@smallexample +(@value{GDBP}) info static-tracepoint-markers +Cnt ID Enb Address What +1 ust/bar2 y 0x0000000000400e1a in main at stexample.c:25 + Data: number1 %d number2 %d + Probed by static tracepoints: #2 +2 ust/bar33 n 0x0000000000400c87 in main at stexample.c:24 + Data: str %s +(@value{GDBP}) +@end smallexample +@end table + +@node Starting and Stopping Trace Experiments +@subsection Starting and Stopping Trace Experiments + +@table @code +@kindex tstart [ @var{notes} ] +@cindex start a new trace experiment +@cindex collected data discarded +@item tstart +This command starts the trace experiment, and begins collecting data. +It has the side effect of discarding all the data collected in the +trace buffer during the previous trace experiment. If any arguments +are supplied, they are taken as a note and stored with the trace +experiment's state. The notes may be arbitrary text, and are +especially useful with disconnected tracing in a multi-user context; +the notes can explain what the trace is doing, supply user contact +information, and so forth. + +@kindex tstop [ @var{notes} ] +@cindex stop a running trace experiment +@item tstop +This command stops the trace experiment. If any arguments are +supplied, they are recorded with the experiment as a note. This is +useful if you are stopping a trace started by someone else, for +instance if the trace is interfering with the system's behavior and +needs to be stopped quickly. + +@strong{Note}: a trace experiment and data collection may stop +automatically if any tracepoint's passcount is reached +(@pxref{Tracepoint Passcounts}), or if the trace buffer becomes full. + +@kindex tstatus +@cindex status of trace data collection +@cindex trace experiment, status of +@item tstatus +This command displays the status of the current trace data +collection. +@end table + +Here is an example of the commands we described so far: + +@smallexample +(@value{GDBP}) @b{trace gdb_c_test} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint #1, one per line. +> collect $regs,$locals,$args +> while-stepping 11 + > collect $regs + > end +> end +(@value{GDBP}) @b{tstart} + [time passes @dots{}] +(@value{GDBP}) @b{tstop} +@end smallexample + +@anchor{disconnected tracing} +@cindex disconnected tracing +You can choose to continue running the trace experiment even if +@value{GDBN} disconnects from the target, voluntarily or +involuntarily. For commands such as @code{detach}, the debugger will +ask what you want to do with the trace. But for unexpected +terminations (@value{GDBN} crash, network outage), it would be +unfortunate to lose hard-won trace data, so the variable +@code{disconnected-tracing} lets you decide whether the trace should +continue running without @value{GDBN}. + +@table @code +@item set disconnected-tracing on +@itemx set disconnected-tracing off +@kindex set disconnected-tracing +Choose whether a tracing run should continue to run if @value{GDBN} +has disconnected from the target. Note that @code{detach} or +@code{quit} will ask you directly what to do about a running trace no +matter what this variable's setting, so the variable is mainly useful +for handling unexpected situations, such as loss of the network. + +@item show disconnected-tracing +@kindex show disconnected-tracing +Show the current choice for disconnected tracing. + +@end table + +When you reconnect to the target, the trace experiment may or may not +still be running; it might have filled the trace buffer in the +meantime, or stopped for one of the other reasons. If it is running, +it will continue after reconnection. + +Upon reconnection, the target will upload information about the +tracepoints in effect. @value{GDBN} will then compare that +information to the set of tracepoints currently defined, and attempt +to match them up, allowing for the possibility that the numbers may +have changed due to creation and deletion in the meantime. If one of +the target's tracepoints does not match any in @value{GDBN}, the +debugger will create a new tracepoint, so that you have a number with +which to specify that tracepoint. This matching-up process is +necessarily heuristic, and it may result in useless tracepoints being +created; you may simply delete them if they are of no use. + +@cindex circular trace buffer +If your target agent supports a @dfn{circular trace buffer}, then you +can run a trace experiment indefinitely without filling the trace +buffer; when space runs out, the agent deletes already-collected trace +frames, oldest first, until there is enough room to continue +collecting. This is especially useful if your tracepoints are being +hit too often, and your trace gets terminated prematurely because the +buffer is full. To ask for a circular trace buffer, simply set +@samp{circular-trace-buffer} to on. You can set this at any time, +including during tracing; if the agent can do it, it will change +buffer handling on the fly, otherwise it will not take effect until +the next run. + +@table @code +@item set circular-trace-buffer on +@itemx set circular-trace-buffer off +@kindex set circular-trace-buffer +Choose whether a tracing run should use a linear or circular buffer +for trace data. A linear buffer will not lose any trace data, but may +fill up prematurely, while a circular buffer will discard old trace +data, but it will have always room for the latest tracepoint hits. + +@item show circular-trace-buffer +@kindex show circular-trace-buffer +Show the current choice for the trace buffer. Note that this may not +match the agent's current buffer handling, nor is it guaranteed to +match the setting that might have been in effect during a past run, +for instance if you are looking at frames from a trace file. + +@end table + +@table @code +@item set trace-buffer-size @var{n} +@itemx set trace-buffer-size unlimited +@kindex set trace-buffer-size +Request that the target use a trace buffer of @var{n} bytes. Not all +targets will honor the request; they may have a compiled-in size for +the trace buffer, or some other limitation. Set to a value of +@code{unlimited} or @code{-1} to let the target use whatever size it +likes. This is also the default. + +@item show trace-buffer-size +@kindex show trace-buffer-size +Show the current requested size for the trace buffer. Note that this +will only match the actual size if the target supports size-setting, +and was able to handle the requested size. For instance, if the +target can only change buffer size between runs, this variable will +not reflect the change until the next run starts. Use @code{tstatus} +to get a report of the actual buffer size. +@end table + +@table @code +@item set trace-user @var{text} +@kindex set trace-user + +@item show trace-user +@kindex show trace-user + +@item set trace-notes @var{text} +@kindex set trace-notes +Set the trace run's notes. + +@item show trace-notes +@kindex show trace-notes +Show the trace run's notes. + +@item set trace-stop-notes @var{text} +@kindex set trace-stop-notes +Set the trace run's stop notes. The handling of the note is as for +@code{tstop} arguments; the set command is convenient way to fix a +stop note that is mistaken or incomplete. + +@item show trace-stop-notes +@kindex show trace-stop-notes +Show the trace run's stop notes. + +@end table + +@node Tracepoint Restrictions +@subsection Tracepoint Restrictions + +@cindex tracepoint restrictions +There are a number of restrictions on the use of tracepoints. As +described above, tracepoint data gathering occurs on the target +without interaction from @value{GDBN}. Thus the full capabilities of +the debugger are not available during data gathering, and then at data +examination time, you will be limited by only having what was +collected. The following items describe some common problems, but it +is not exhaustive, and you may run into additional difficulties not +mentioned here. + +@itemize @bullet + +@item +Tracepoint expressions are intended to gather objects (lvalues). Thus +the full flexibility of GDB's expression evaluator is not available. +You cannot call functions, cast objects to aggregate types, access +convenience variables or modify values (except by assignment to trace +state variables). Some language features may implicitly call +functions (for instance Objective-C fields with accessors), and therefore +cannot be collected either. + +@item +Collection of local variables, either individually or in bulk with +@code{$locals} or @code{$args}, during @code{while-stepping} may +behave erratically. The stepping action may enter a new scope (for +instance by stepping into a function), or the location of the variable +may change (for instance it is loaded into a register). The +tracepoint data recorded uses the location information for the +variables that is correct for the tracepoint location. When the +tracepoint is created, it is not possible, in general, to determine +where the steps of a @code{while-stepping} sequence will advance the +program---particularly if a conditional branch is stepped. + +@item +Collection of an incompletely-initialized or partially-destroyed object +may result in something that @value{GDBN} cannot display, or displays +in a misleading way. + +@item +When @value{GDBN} displays a pointer to character it automatically +dereferences the pointer to also display characters of the string +being pointed to. However, collecting the pointer during tracing does +not automatically collect the string. You need to explicitly +dereference the pointer and provide size information if you want to +collect not only the pointer, but the memory pointed to. For example, +@code{*ptr@@50} can be used to collect the 50 element array pointed to +by @code{ptr}. + +@item +It is not possible to collect a complete stack backtrace at a +tracepoint. Instead, you may collect the registers and a few hundred +bytes from the stack pointer with something like @code{*(unsigned char *)$esp@@300} +(adjust to use the name of the actual stack pointer register on your +target architecture, and the amount of stack you wish to capture). +Then the @code{backtrace} command will show a partial backtrace when +using a trace frame. The number of stack frames that can be examined +depends on the sizes of the frames in the collected stack. Note that +if you ask for a block so large that it goes past the bottom of the +stack, the target agent may report an error trying to read from an +invalid address. + +@item +If you do not collect registers at a tracepoint, @value{GDBN} can +infer that the value of @code{$pc} must be the same as the address of +the tracepoint and use that when you are looking at a trace frame +for that tracepoint. However, this cannot work if the tracepoint has +multiple locations (for instance if it was set in a function that was +inlined), or if it has a @code{while-stepping} loop. In those cases +@value{GDBN} will warn you that it can't infer @code{$pc}, and default +it to zero. + +@end itemize + +@node Analyze Collected Data +@section Using the Collected Data + +After the tracepoint experiment ends, you use @value{GDBN} commands +for examining the trace data. The basic idea is that each tracepoint +collects a trace @dfn{snapshot} every time it is hit and another +snapshot every time it single-steps. All these snapshots are +consecutively numbered from zero and go into a buffer, and you can +examine them later. The way you examine them is to @dfn{focus} on a +specific trace snapshot. When the remote stub is focused on a trace +snapshot, it will respond to all @value{GDBN} requests for memory and +registers by reading from the buffer which belongs to that snapshot, +rather than from @emph{real} memory or registers of the program being +debugged. This means that @strong{all} @value{GDBN} commands +(@code{print}, @code{info registers}, @code{backtrace}, etc.) will +behave as if we were currently debugging the program state as it was +when the tracepoint occurred. Any requests for data that are not in +the buffer will fail. + +@menu +* tfind:: How to select a trace snapshot +* tdump:: How to display all data for a snapshot +* save tracepoints:: How to save tracepoints for a future run +@end menu + +@node tfind +@subsection @code{tfind @var{n}} + +@kindex tfind +@cindex select trace snapshot +@cindex find trace snapshot +The basic command for selecting a trace snapshot from the buffer is +@code{tfind @var{n}}, which finds trace snapshot number @var{n}, +counting from zero. If no argument @var{n} is given, the next +snapshot is selected. + +Here are the various forms of using the @code{tfind} command. + +@table @code +@item tfind start +Find the first snapshot in the buffer. This is a synonym for +@code{tfind 0} (since 0 is the number of the first snapshot). + +@item tfind none +Stop debugging trace snapshots, resume @emph{live} debugging. + +@item tfind end +Same as @samp{tfind none}. + +@item tfind +No argument means find the next trace snapshot or find the first +one if no trace snapshot is selected. + +@item tfind - +Find the previous trace snapshot before the current one. This permits +retracing earlier steps. + +@item tfind tracepoint @var{num} +Find the next snapshot associated with tracepoint @var{num}. Search +proceeds forward from the last examined trace snapshot. If no +argument @var{num} is given, it means find the next snapshot collected +for the same tracepoint as the current snapshot. + +@item tfind pc @var{addr} +Find the next snapshot associated with the value @var{addr} of the +program counter. Search proceeds forward from the last examined trace +snapshot. If no argument @var{addr} is given, it means find the next +snapshot with the same value of PC as the current snapshot. + +@item tfind outside @var{addr1}, @var{addr2} +Find the next snapshot whose PC is outside the given range of +addresses (exclusive). + +@item tfind range @var{addr1}, @var{addr2} +Find the next snapshot whose PC is between @var{addr1} and +@var{addr2} (inclusive). + +@item tfind line @r{[}@var{file}:@r{]}@var{n} +Find the next snapshot associated with the source line @var{n}. If +the optional argument @var{file} is given, refer to line @var{n} in +that source file. Search proceeds forward from the last examined +trace snapshot. If no argument @var{n} is given, it means find the +next line other than the one currently being examined; thus saying +@code{tfind line} repeatedly can appear to have the same effect as +stepping from line to line in a @emph{live} debugging session. +@end table + +The default arguments for the @code{tfind} commands are specifically +designed to make it easy to scan through the trace buffer. For +instance, @code{tfind} with no argument selects the next trace +snapshot, and @code{tfind -} with no argument selects the previous +trace snapshot. So, by giving one @code{tfind} command, and then +simply hitting @key{RET} repeatedly you can examine all the trace +snapshots in order. Or, by saying @code{tfind -} and then hitting +@key{RET} repeatedly you can examine the snapshots in reverse order. +The @code{tfind line} command with no argument selects the snapshot +for the next source line executed. The @code{tfind pc} command with +no argument selects the next snapshot with the same program counter +(PC) as the current frame. The @code{tfind tracepoint} command with +no argument selects the next trace snapshot collected by the same +tracepoint as the current one. + +In addition to letting you scan through the trace buffer manually, +these commands make it easy to construct @value{GDBN} scripts that +scan through the trace buffer and print out whatever collected data +you are interested in. Thus, if we want to examine the PC, FP, and SP +registers from each trace frame in the buffer, we can say this: + +@smallexample +(@value{GDBP}) @b{tfind start} +(@value{GDBP}) @b{while ($trace_frame != -1)} +> printf "Frame %d, PC = %08X, SP = %08X, FP = %08X\n", \ + $trace_frame, $pc, $sp, $fp +> tfind +> end + +Frame 0, PC = 0020DC64, SP = 0030BF3C, FP = 0030BF44 +Frame 1, PC = 0020DC6C, SP = 0030BF38, FP = 0030BF44 +Frame 2, PC = 0020DC70, SP = 0030BF34, FP = 0030BF44 +Frame 3, PC = 0020DC74, SP = 0030BF30, FP = 0030BF44 +Frame 4, PC = 0020DC78, SP = 0030BF2C, FP = 0030BF44 +Frame 5, PC = 0020DC7C, SP = 0030BF28, FP = 0030BF44 +Frame 6, PC = 0020DC80, SP = 0030BF24, FP = 0030BF44 +Frame 7, PC = 0020DC84, SP = 0030BF20, FP = 0030BF44 +Frame 8, PC = 0020DC88, SP = 0030BF1C, FP = 0030BF44 +Frame 9, PC = 0020DC8E, SP = 0030BF18, FP = 0030BF44 +Frame 10, PC = 00203F6C, SP = 0030BE3C, FP = 0030BF14 +@end smallexample + +Or, if we want to examine the variable @code{X} at each source line in +the buffer: + +@smallexample +(@value{GDBP}) @b{tfind start} +(@value{GDBP}) @b{while ($trace_frame != -1)} +> printf "Frame %d, X == %d\n", $trace_frame, X +> tfind line +> end + +Frame 0, X = 1 +Frame 7, X = 2 +Frame 13, X = 255 +@end smallexample + +@node tdump +@subsection @code{tdump} +@kindex tdump +@cindex dump all data collected at tracepoint +@cindex tracepoint data, display + +This command takes no arguments. It prints all the data collected at +the current trace snapshot. + +@smallexample +(@value{GDBP}) @b{trace 444} +(@value{GDBP}) @b{actions} +Enter actions for tracepoint #2, one per line: +> collect $regs, $locals, $args, gdb_long_test +> end + +(@value{GDBP}) @b{tstart} + +(@value{GDBP}) @b{tfind line 444} +#0 gdb_test (p1=0x11, p2=0x22, p3=0x33, p4=0x44, p5=0x55, p6=0x66) +at gdb_test.c:444 +444 printp( "%s: arguments = 0x%X 0x%X 0x%X 0x%X 0x%X 0x%X\n", ) + +(@value{GDBP}) @b{tdump} +Data collected at tracepoint 2, trace frame 1: +d0 0xc4aa0085 -995491707 +d1 0x18 24 +d2 0x80 128 +d3 0x33 51 +d4 0x71aea3d 119204413 +d5 0x22 34 +d6 0xe0 224 +d7 0x380035 3670069 +a0 0x19e24a 1696330 +a1 0x3000668 50333288 +a2 0x100 256 +a3 0x322000 3284992 +a4 0x3000698 50333336 +a5 0x1ad3cc 1758156 +fp 0x30bf3c 0x30bf3c +sp 0x30bf34 0x30bf34 +ps 0x0 0 +pc 0x20b2c8 0x20b2c8 +fpcontrol 0x0 0 +fpstatus 0x0 0 +fpiaddr 0x0 0 +p = 0x20e5b4 "gdb-test" +p1 = (void *) 0x11 +p2 = (void *) 0x22 +p3 = (void *) 0x33 +p4 = (void *) 0x44 +p5 = (void *) 0x55 +p6 = (void *) 0x66 +gdb_long_test = 17 '\021' + +(@value{GDBP}) +@end smallexample + +@code{tdump} works by scanning the tracepoint's current collection +actions and printing the value of each expression listed. So +@code{tdump} can fail, if after a run, you change the tracepoint's +actions to mention variables that were not collected during the run. + +Also, for tracepoints with @code{while-stepping} loops, @code{tdump} +uses the collected value of @code{$pc} to distinguish between trace +frames that were collected at the tracepoint hit, and frames that were +collected while stepping. This allows it to correctly choose whether +to display the basic list of collections, or the collections from the +body of the while-stepping loop. However, if @code{$pc} was not collected, +then @code{tdump} will always attempt to dump using the basic collection +list, and may fail if a while-stepping frame does not include all the +same data that is collected at the tracepoint hit. +@c This is getting pretty arcane, example would be good. + +@node save tracepoints +@subsection @code{save tracepoints @var{filename}} +@kindex save tracepoints +@kindex save-tracepoints +@cindex save tracepoints for future sessions + +This command saves all current tracepoint definitions together with +their actions and passcounts, into a file @file{@var{filename}} +suitable for use in a later debugging session. To read the saved +tracepoint definitions, use the @code{source} command (@pxref{Command +Files}). The @w{@code{save-tracepoints}} command is a deprecated +alias for @w{@code{save tracepoints}} + +@node Tracepoint Variables +@section Convenience Variables for Tracepoints +@cindex tracepoint variables +@cindex convenience variables for tracepoints + +@table @code +@vindex $trace_frame +@item (int) $trace_frame +The current trace snapshot (a.k.a.@: @dfn{frame}) number, or -1 if no +snapshot is selected. + +@vindex $tracepoint +@item (int) $tracepoint +The tracepoint for the current trace snapshot. + +@vindex $trace_line +@item (int) $trace_line +The line number for the current trace snapshot. + +@vindex $trace_file +@item (char []) $trace_file +The source file for the current trace snapshot. + +@vindex $trace_func +@item (char []) $trace_func +The name of the function containing @code{$tracepoint}. +@end table + +Note: @code{$trace_file} is not suitable for use in @code{printf}, +use @code{output} instead. + +Here's a simple example of using these convenience variables for +stepping through all the trace snapshots and printing some of their +data. Note that these are not the same as trace state variables, +which are managed by the target. + +@smallexample +(@value{GDBP}) @b{tfind start} + +(@value{GDBP}) @b{while $trace_frame != -1} +> output $trace_file +> printf ", line %d (tracepoint #%d)\n", $trace_line, $tracepoint +> tfind +> end +@end smallexample + +@node Trace Files +@section Using Trace Files +@cindex trace files + +In some situations, the target running a trace experiment may no +longer be available; perhaps it crashed, or the hardware was needed +for a different activity. To handle these cases, you can arrange to +dump the trace data into a file, and later use that file as a source +of trace data, via the @code{target tfile} command. + +@table @code + +@kindex tsave +@item tsave [ -r ] @var{filename} +@itemx tsave [-ctf] @var{dirname} +Save the trace data to @var{filename}. By default, this command +assumes that @var{filename} refers to the host filesystem, so if +necessary @value{GDBN} will copy raw trace data up from the target and +then save it. If the target supports it, you can also supply the +optional argument @code{-r} (``remote'') to direct the target to save +the data directly into @var{filename} in its own filesystem, which may be +more efficient if the trace buffer is very large. (Note, however, that +@code{target tfile} can only read from files accessible to the host.) +By default, this command will save trace frame in tfile format. +You can supply the optional argument @code{-ctf} to save data in CTF +format. The @dfn{Common Trace Format} (CTF) is proposed as a trace format +that can be shared by multiple debugging and tracing tools. Please go to +@indicateurl{http://www.efficios.com/ctf} to get more information. + +@kindex target tfile +@kindex tfile +@kindex target ctf +@kindex ctf +@item target tfile @var{filename} +@itemx target ctf @var{dirname} +Use the file named @var{filename} or directory named @var{dirname} as +a source of trace data. Commands that examine data work as they do with +a live target, but it is not possible to run any new trace experiments. +@code{tstatus} will report the state of the trace run at the moment +the data was saved, as well as the current trace frame you are examining. +Both @var{filename} and @var{dirname} must be on a filesystem accessible to +the host. + +The @var{filename} and @var{dirname} arguments supports escaping and +quoting, see @ref{Filename Arguments,,Filenames As Command Arguments}. + +@smallexample +(@value{GDBP}) target ctf ctf.ctf +(@value{GDBP}) tfind +Found trace frame 0, tracepoint 2 +39 ++a; /* set tracepoint 1 here */ +(@value{GDBP}) tdump +Data collected at tracepoint 2, trace frame 0: +i = 0 +a = 0 +b = 1 '\001' +c = @{"123", "456", "789", "123", "456", "789"@} +d = @{@{@{a = 1, b = 2@}, @{a = 3, b = 4@}@}, @{@{a = 5, b = 6@}, @{a = 7, b = 8@}@}@} +(@value{GDBP}) p b +$1 = 1 +@end smallexample + +@end table + +@node Overlays +@chapter Debugging Programs That Use Overlays +@cindex overlays + +If your program is too large to fit completely in your target system's +memory, you can sometimes use @dfn{overlays} to work around this +problem. @value{GDBN} provides some support for debugging programs that +use overlays. + +@menu +* How Overlays Work:: A general explanation of overlays. +* Overlay Commands:: Managing overlays in @value{GDBN}. +* Automatic Overlay Debugging:: @value{GDBN} can find out which overlays are + mapped by asking the inferior. +* Overlay Sample Program:: A sample program using overlays. +@end menu + +@node How Overlays Work +@section How Overlays Work +@cindex mapped overlays +@cindex unmapped overlays +@cindex load address, overlay's +@cindex mapped address +@cindex overlay area + +Suppose you have a computer whose instruction address space is only 64 +kilobytes long, but which has much more memory which can be accessed by +other means: special instructions, segment registers, or memory +management hardware, for example. Suppose further that you want to +adapt a program which is larger than 64 kilobytes to run on this system. + +One solution is to identify modules of your program which are relatively +independent, and need not call each other directly; call these modules +@dfn{overlays}. Separate the overlays from the main program, and place +their machine code in the larger memory. Place your main program in +instruction memory, but leave at least enough space there to hold the +largest overlay as well. + +Now, to call a function located in an overlay, you must first copy that +overlay's machine code from the large memory into the space set aside +for it in the instruction memory, and then jump to its entry point +there. + +@c NB: In the below the mapped area's size is greater or equal to the +@c size of all overlays. This is intentional to remind the developer +@c that overlays don't necessarily need to be the same size. + +@smallexample +@group + Data Instruction Larger +Address Space Address Space Address Space ++-----------+ +-----------+ +-----------+ +| | | | | | ++-----------+ +-----------+ +-----------+<-- overlay 1 +| program | | main | .----| overlay 1 | load address +| variables | | program | | +-----------+ +| and heap | | | | | | ++-----------+ | | | +-----------+<-- overlay 2 +| | +-----------+ | | | load address ++-----------+ | | | .-| overlay 2 | + | | | | | | + mapped --->+-----------+ | | +-----------+ + address | | | | | | + | overlay | <-' | | | + | area | <---' +-----------+<-- overlay 3 + | | <---. | | load address + +-----------+ `--| overlay 3 | + | | | | + +-----------+ | | + +-----------+ + | | + +-----------+ + + @anchor{A code overlay}A code overlay +@end group +@end smallexample + +The diagram (@pxref{A code overlay}) shows a system with separate data +and instruction address spaces. To map an overlay, the program copies +its code from the larger address space to the instruction address space. +Since the overlays shown here all use the same mapped address, only one +may be mapped at a time. For a system with a single address space for +data and instructions, the diagram would be similar, except that the +program variables and heap would share an address space with the main +program and the overlay area. + +An overlay loaded into instruction memory and ready for use is called a +@dfn{mapped} overlay; its @dfn{mapped address} is its address in the +instruction memory. An overlay not present (or only partially present) +in instruction memory is called @dfn{unmapped}; its @dfn{load address} +is its address in the larger memory. The mapped address is also called +the @dfn{virtual memory address}, or @dfn{VMA}; the load address is also +called the @dfn{load memory address}, or @dfn{LMA}. + +Unfortunately, overlays are not a completely transparent way to adapt a +program to limited instruction memory. They introduce a new set of +global constraints you must keep in mind as you design your program: + +@itemize @bullet + +@item +Before calling or returning to a function in an overlay, your program +must make sure that overlay is actually mapped. Otherwise, the call or +return will transfer control to the right address, but in the wrong +overlay, and your program will probably crash. + +@item +If the process of mapping an overlay is expensive on your system, you +will need to choose your overlays carefully to minimize their effect on +your program's performance. + +@item +The executable file you load onto your system must contain each +overlay's instructions, appearing at the overlay's load address, not its +mapped address. However, each overlay's instructions must be relocated +and its symbols defined as if the overlay were at its mapped address. +You can use GNU linker scripts to specify different load and relocation +addresses for pieces of your program; see @ref{Overlay Description,,, +ld.info, Using ld: the GNU linker}. + +@item +The procedure for loading executable files onto your system must be able +to load their contents into the larger address space as well as the +instruction and data spaces. + +@end itemize + +The overlay system described above is rather simple, and could be +improved in many ways: + +@itemize @bullet + +@item +If your system has suitable bank switch registers or memory management +hardware, you could use those facilities to make an overlay's load area +contents simply appear at their mapped address in instruction space. +This would probably be faster than copying the overlay to its mapped +area in the usual way. + +@item +If your overlays are small enough, you could set aside more than one +overlay area, and have more than one overlay mapped at a time. + +@item +You can use overlays to manage data, as well as instructions. In +general, data overlays are even less transparent to your design than +code overlays: whereas code overlays only require care when you call or +return to functions, data overlays require care every time you access +the data. Also, if you change the contents of a data overlay, you +must copy its contents back out to its load address before you can copy a +different data overlay into the same mapped area. + +@end itemize + + +@node Overlay Commands +@section Overlay Commands + +To use @value{GDBN}'s overlay support, each overlay in your program must +correspond to a separate section of the executable file. The section's +virtual memory address and load memory address must be the overlay's +mapped and load addresses. Identifying overlays with sections allows +@value{GDBN} to determine the appropriate address of a function or +variable, depending on whether the overlay is mapped or not. + +@value{GDBN}'s overlay commands all start with the word @code{overlay}; +you can abbreviate this as @code{ov} or @code{ovly}. The commands are: + +@table @code +@item overlay off +@kindex overlay +Disable @value{GDBN}'s overlay support. When overlay support is +disabled, @value{GDBN} assumes that all functions and variables are +always present at their mapped addresses. By default, @value{GDBN}'s +overlay support is disabled. + +@item overlay manual +@cindex manual overlay debugging +Enable @dfn{manual} overlay debugging. In this mode, @value{GDBN} +relies on you to tell it which overlays are mapped, and which are not, +using the @code{overlay map-overlay} and @code{overlay unmap-overlay} +commands described below. + +@item overlay map-overlay @var{overlay} +@itemx overlay map @var{overlay} +@cindex map an overlay +Tell @value{GDBN} that @var{overlay} is now mapped; @var{overlay} must +be the name of the object file section containing the overlay. When an +overlay is mapped, @value{GDBN} assumes it can find the overlay's +functions and variables at their mapped addresses. @value{GDBN} assumes +that any other overlays whose mapped ranges overlap that of +@var{overlay} are now unmapped. + +@item overlay unmap-overlay @var{overlay} +@itemx overlay unmap @var{overlay} +@cindex unmap an overlay +Tell @value{GDBN} that @var{overlay} is no longer mapped; @var{overlay} +must be the name of the object file section containing the overlay. +When an overlay is unmapped, @value{GDBN} assumes it can find the +overlay's functions and variables at their load addresses. + +@item overlay auto +Enable @dfn{automatic} overlay debugging. In this mode, @value{GDBN} +consults a data structure the overlay manager maintains in the inferior +to see which overlays are mapped. For details, see @ref{Automatic +Overlay Debugging}. + +@item overlay load-target +@itemx overlay load +@cindex reloading the overlay table +Re-read the overlay table from the inferior. Normally, @value{GDBN} +re-reads the table @value{GDBN} automatically each time the inferior +stops, so this command should only be necessary if you have changed the +overlay mapping yourself using @value{GDBN}. This command is only +useful when using automatic overlay debugging. + +@item overlay list-overlays +@itemx overlay list +@cindex listing mapped overlays +Display a list of the overlays currently mapped, along with their mapped +addresses, load addresses, and sizes. + +@end table + +Normally, when @value{GDBN} prints a code address, it includes the name +of the function the address falls in: + +@smallexample +(@value{GDBP}) print main +$3 = @{int ()@} 0x11a0
+@end smallexample +@noindent +When overlay debugging is enabled, @value{GDBN} recognizes code in +unmapped overlays, and prints the names of unmapped functions with +asterisks around them. For example, if @code{foo} is a function in an +unmapped overlay, @value{GDBN} prints it this way: + +@smallexample +(@value{GDBP}) overlay list +No sections are mapped. +(@value{GDBP}) print foo +$5 = @{int (int)@} 0x100000 <*foo*> +@end smallexample +@noindent +When @code{foo}'s overlay is mapped, @value{GDBN} prints the function's +name normally: + +@smallexample +(@value{GDBP}) overlay list +Section .ov.foo.text, loaded at 0x100000 - 0x100034, + mapped at 0x1016 - 0x104a +(@value{GDBP}) print foo +$6 = @{int (int)@} 0x1016 +@end smallexample + +When overlay debugging is enabled, @value{GDBN} can find the correct +address for functions and variables in an overlay, whether or not the +overlay is mapped. This allows most @value{GDBN} commands, like +@code{break} and @code{disassemble}, to work normally, even on unmapped +code. However, @value{GDBN}'s breakpoint support has some limitations: + +@itemize @bullet +@item +@cindex breakpoints in overlays +@cindex overlays, setting breakpoints in +You can set breakpoints in functions in unmapped overlays, as long as +@value{GDBN} can write to the overlay at its load address. +@item +@value{GDBN} can not set hardware or simulator-based breakpoints in +unmapped overlays. However, if you set a breakpoint at the end of your +overlay manager (and tell @value{GDBN} which overlays are now mapped, if +you are using manual overlay management), @value{GDBN} will re-set its +breakpoints properly. +@end itemize + + +@node Automatic Overlay Debugging +@section Automatic Overlay Debugging +@cindex automatic overlay debugging + +@value{GDBN} can automatically track which overlays are mapped and which +are not, given some simple co-operation from the overlay manager in the +inferior. If you enable automatic overlay debugging with the +@code{overlay auto} command (@pxref{Overlay Commands}), @value{GDBN} +looks in the inferior's memory for certain variables describing the +current state of the overlays. + +Here are the variables your overlay manager must define to support +@value{GDBN}'s automatic overlay debugging: + +@table @asis + +@item @code{_ovly_table}: +This variable must be an array of the following structures: + +@smallexample +struct +@{ + /* The overlay's mapped address. */ + unsigned long vma; + + /* The size of the overlay, in bytes. */ + unsigned long size; + + /* The overlay's load address. */ + unsigned long lma; + + /* Non-zero if the overlay is currently mapped; + zero otherwise. */ + unsigned long mapped; +@} +@end smallexample + +@item @code{_novlys}: +This variable must be a four-byte signed integer, holding the total +number of elements in @code{_ovly_table}. + +@end table + +To decide whether a particular overlay is mapped or not, @value{GDBN} +looks for an entry in @w{@code{_ovly_table}} whose @code{vma} and +@code{lma} members equal the VMA and LMA of the overlay's section in the +executable file. When @value{GDBN} finds a matching entry, it consults +the entry's @code{mapped} member to determine whether the overlay is +currently mapped. + +In addition, your overlay manager may define a function called +@code{_ovly_debug_event}. If this function is defined, @value{GDBN} +will silently set a breakpoint there. If the overlay manager then +calls this function whenever it has changed the overlay table, this +will enable @value{GDBN} to accurately keep track of which overlays +are in program memory, and update any breakpoints that may be set +in overlays. This will allow breakpoints to work even if the +overlays are kept in ROM or other non-writable memory while they +are not being executed. + +@node Overlay Sample Program +@section Overlay Sample Program +@cindex overlay example program + +When linking a program which uses overlays, you must place the overlays +at their load addresses, while relocating them to run at their mapped +addresses. To do this, you must write a linker script (@pxref{Overlay +Description,,, ld.info, Using ld: the GNU linker}). Unfortunately, +since linker scripts are specific to a particular host system, target +architecture, and target memory layout, this manual cannot provide +portable sample code demonstrating @value{GDBN}'s overlay support. + +However, the @value{GDBN} source distribution does contain an overlaid +program, with linker scripts for a few systems, as part of its test +suite. The program consists of the following files from +@file{gdb/testsuite/gdb.base}: + +@table @file +@item overlays.c +The main program file. +@item ovlymgr.c +A simple overlay manager, used by @file{overlays.c}. +@item foo.c +@itemx bar.c +@itemx baz.c +@itemx grbx.c +Overlay modules, loaded and used by @file{overlays.c}. +@item d10v.ld +@itemx m32r.ld +Linker scripts for linking the test program on the @code{d10v-elf} +and @code{m32r-elf} targets. +@end table + +You can build the test program using the @code{d10v-elf} GCC +cross-compiler like this: + +@smallexample +$ d10v-elf-gcc -g -c overlays.c +$ d10v-elf-gcc -g -c ovlymgr.c +$ d10v-elf-gcc -g -c foo.c +$ d10v-elf-gcc -g -c bar.c +$ d10v-elf-gcc -g -c baz.c +$ d10v-elf-gcc -g -c grbx.c +$ d10v-elf-gcc -g overlays.o ovlymgr.o foo.o bar.o \ + baz.o grbx.o -Wl,-Td10v.ld -o overlays +@end smallexample + +The build process is identical for any other architecture, except that +you must substitute the appropriate compiler and linker script for the +target system for @code{d10v-elf-gcc} and @code{d10v.ld}. + + +@node Languages +@chapter Using @value{GDBN} with Different Languages +@cindex languages + +Although programming languages generally have common aspects, they are +rarely expressed in the same manner. For instance, in ANSI C, +dereferencing a pointer @code{p} is accomplished by @code{*p}, but in +Modula-2, it is accomplished by @code{p^}. Values can also be +represented (and displayed) differently. Hex numbers in C appear as +@samp{0x1ae}, while in Modula-2 they appear as @samp{1AEH}. + +@cindex working language +Language-specific information is built into @value{GDBN} for some languages, +allowing you to express operations like the above in your program's +native language, and allowing @value{GDBN} to output values in a manner +consistent with the syntax of your program's native language. The +language you use to build expressions is called the @dfn{working +language}. + +@menu +* Setting:: Switching between source languages +* Show:: Displaying the language +* Checks:: Type and range checks +* Supported Languages:: Supported languages +* Unsupported Languages:: Unsupported languages +@end menu + +@node Setting +@section Switching Between Source Languages + +There are two ways to control the working language---either have @value{GDBN} +set it automatically, or select it manually yourself. You can use the +@code{set language} command for either purpose. On startup, @value{GDBN} +defaults to setting the language automatically. The working language is +used to determine how expressions you type are interpreted, how values +are printed, etc. + +In addition to the working language, every source file that +@value{GDBN} knows about has its own working language. For some object +file formats, the compiler might indicate which language a particular +source file is in. However, most of the time @value{GDBN} infers the +language from the name of the file. The language of a source file +controls whether C@t{++} names are demangled---this way @code{backtrace} can +show each frame appropriately for its own language. There is no way to +set the language of a source file from within @value{GDBN}, but you can +set the language associated with a filename extension. @xref{Show, , +Displaying the Language}. + +This is most commonly a problem when you use a program, such +as @code{cfront} or @code{f2c}, that generates C but is written in +another language. In that case, make the +program use @code{#line} directives in its C output; that way +@value{GDBN} will know the correct language of the source code of the original +program, and will display that source code, not the generated C code. + +@menu +* Filenames:: Filename extensions and languages. +* Manually:: Setting the working language manually +* Automatically:: Having @value{GDBN} infer the source language +@end menu + +@node Filenames +@subsection List of Filename Extensions and Languages + +If a source file name ends in one of the following extensions, then +@value{GDBN} infers that its language is the one indicated. + +@table @file +@item .ada +@itemx .ads +@itemx .adb +@itemx .a +Ada source file. + +@item .c +C source file + +@item .C +@itemx .cc +@itemx .cp +@itemx .cpp +@itemx .cxx +@itemx .c++ +C@t{++} source file + +@item .d +D source file + +@item .m +Objective-C source file + +@item .f +@itemx .F +Fortran source file + +@item .mod +Modula-2 source file + +@item .s +@itemx .S +Assembler source file. This actually behaves almost like C, but +@value{GDBN} does not skip over function prologues when stepping. +@end table + +In addition, you may set the language associated with a filename +extension. @xref{Show, , Displaying the Language}. + +@node Manually +@subsection Setting the Working Language + +If you allow @value{GDBN} to set the language automatically, +expressions are interpreted the same way in your debugging session and +your program. + +@kindex set language +If you wish, you may set the language manually. To do this, issue the +command @samp{set language @var{lang}}, where @var{lang} is the name of +a language, such as +@code{c} or @code{modula-2}. +For a list of the supported languages, type @samp{set language}. + +Setting the language manually prevents @value{GDBN} from updating the working +language automatically. This can lead to confusion if you try +to debug a program when the working language is not the same as the +source language, when an expression is acceptable to both +languages---but means different things. For instance, if the current +source file were written in C, and @value{GDBN} was parsing Modula-2, a +command such as: + +@smallexample +print a = b + c +@end smallexample + +@noindent +might not have the effect you intended. In C, this means to add +@code{b} and @code{c} and place the result in @code{a}. The result +printed would be the value of @code{a}. In Modula-2, this means to compare +@code{a} to the result of @code{b+c}, yielding a @code{BOOLEAN} value. + +@node Automatically +@subsection Having @value{GDBN} Infer the Source Language + +To have @value{GDBN} set the working language automatically, use +@samp{set language local} or @samp{set language auto}. @value{GDBN} +then infers the working language. That is, when your program stops in a +frame (usually by encountering a breakpoint), @value{GDBN} sets the +working language to the language recorded for the function in that +frame. If the language for a frame is unknown (that is, if the function +or block corresponding to the frame was defined in a source file that +does not have a recognized extension), the current working language is +not changed, and @value{GDBN} issues a warning. + +This may not seem necessary for most programs, which are written +entirely in one source language. However, program modules and libraries +written in one source language can be used by a main program written in +a different source language. Using @samp{set language auto} in this +case frees you from having to set the working language manually. + +The warning is enabled by default, but it can be controlled via a +setting: + +@table @code +@item set warn-language-frame-mismatch [on|off] +@kindex warn-language-frame-mismatch +Enable or disable the warning that is issued when the current language +is set to a value that does not match the current frame. + +@item show warn-language-frame-mismatch +Show whether the frame-mismatch warning will be issued. +@end table + +@node Show +@section Displaying the Language + +The following commands help you find out which language is the +working language, and also what language source files were written in. + +@table @code +@item show language +@anchor{show language} +@kindex show language +Display the current working language. This is the +language you can use with commands such as @code{print} to +build and compute expressions that may involve variables in your program. + +@item info frame +@kindex info frame@r{, show the source language} +Display the source language for this frame. This language becomes the +working language if you use an identifier from this frame. +@xref{Frame Info, ,Information about a Frame}, to identify the other +information listed here. + +@item info source +@kindex info source@r{, show the source language} +Display the source language of this source file. +@xref{Symbols, ,Examining the Symbol Table}, to identify the other +information listed here. +@end table + +In unusual circumstances, you may have source files with extensions +not in the standard list. You can then set the extension associated +with a language explicitly: + +@table @code +@item set extension-language @var{ext} @var{language} +@kindex set extension-language +Tell @value{GDBN} that source files with extension @var{ext} are to be +assumed as written in the source language @var{language}. + +@item info extensions +@kindex info extensions +List all the filename extensions and the associated languages. +@end table + +@node Checks +@section Type and Range Checking + +Some languages are designed to guard you against making seemingly common +errors through a series of compile- and run-time checks. These include +checking the type of arguments to functions and operators and making +sure mathematical overflows are caught at run time. Checks such as +these help to ensure a program's correctness once it has been compiled +by eliminating type mismatches and providing active checks for range +errors when your program is running. + +By default @value{GDBN} checks for these errors according to the +rules of the current source language. Although @value{GDBN} does not check +the statements in your program, it can check expressions entered directly +into @value{GDBN} for evaluation via the @code{print} command, for example. + +@menu +* Type Checking:: An overview of type checking +* Range Checking:: An overview of range checking +@end menu + +@cindex type checking +@cindex checks, type +@node Type Checking +@subsection An Overview of Type Checking + +Some languages, such as C and C@t{++}, are strongly typed, meaning that the +arguments to operators and functions have to be of the correct type, +otherwise an error occurs. These checks prevent type mismatch +errors from ever causing any run-time problems. For example, + +@smallexample +int klass::my_method(char *b) @{ return b ? 1 : 2; @} + +(@value{GDBP}) print obj.my_method (0) +$1 = 2 +@exdent but +(@value{GDBP}) print obj.my_method (0x1234) +Cannot resolve method klass::my_method to any overloaded instance +@end smallexample + +The second example fails because in C@t{++} the integer constant +@samp{0x1234} is not type-compatible with the pointer parameter type. + +For the expressions you use in @value{GDBN} commands, you can tell +@value{GDBN} to not enforce strict type checking or +to treat any mismatches as errors and abandon the expression; +When type checking is disabled, @value{GDBN} successfully evaluates +expressions like the second example above. + +Even if type checking is off, there may be other reasons +related to type that prevent @value{GDBN} from evaluating an expression. +For instance, @value{GDBN} does not know how to add an @code{int} and +a @code{struct foo}. These particular type errors have nothing to do +with the language in use and usually arise from expressions which make +little sense to evaluate anyway. + +@value{GDBN} provides some additional commands for controlling type checking: + +@kindex set check type +@kindex show check type +@table @code +@item set check type on +@itemx set check type off +Set strict type checking on or off. If any type mismatches occur in +evaluating an expression while type checking is on, @value{GDBN} prints a +message and aborts evaluation of the expression. + +@item show check type +Show the current setting of type checking and whether @value{GDBN} +is enforcing strict type checking rules. +@end table + +@cindex range checking +@cindex checks, range +@node Range Checking +@subsection An Overview of Range Checking + +In some languages (such as Modula-2), it is an error to exceed the +bounds of a type; this is enforced with run-time checks. Such range +checking is meant to ensure program correctness by making sure +computations do not overflow, or indices on an array element access do +not exceed the bounds of the array. + +For expressions you use in @value{GDBN} commands, you can tell +@value{GDBN} to treat range errors in one of three ways: ignore them, +always treat them as errors and abandon the expression, or issue +warnings but evaluate the expression anyway. + +A range error can result from numerical overflow, from exceeding an +array index bound, or when you type a constant that is not a member +of any type. Some languages, however, do not treat overflows as an +error. In many implementations of C, mathematical overflow causes the +result to ``wrap around'' to lower values---for example, if @var{m} is +the largest integer value, and @var{s} is the smallest, then + +@smallexample +@var{m} + 1 @result{} @var{s} +@end smallexample + +This, too, is specific to individual languages, and in some cases +specific to individual compilers or machines. @xref{Supported Languages, , +Supported Languages}, for further details on specific languages. + +@value{GDBN} provides some additional commands for controlling the range checker: + +@kindex set check range +@kindex show check range +@table @code +@item set check range auto +Set range checking on or off based on the current working language. +@xref{Supported Languages, ,Supported Languages}, for the default settings for +each language. + +@item set check range on +@itemx set check range off +Set range checking on or off, overriding the default setting for the +current working language. A warning is issued if the setting does not +match the language default. If a range error occurs and range checking is on, +then a message is printed and evaluation of the expression is aborted. + +@item set check range warn +Output messages when the @value{GDBN} range checker detects a range error, +but attempt to evaluate the expression anyway. Evaluating the +expression may still be impossible for other reasons, such as accessing +memory that the process does not own (a typical example from many Unix +systems). + +@item show check range +Show the current setting of the range checker, and whether or not it is +being set automatically by @value{GDBN}. +@end table + +@node Supported Languages +@section Supported Languages + +@value{GDBN} supports C, C@t{++}, D, Go, Objective-C, Fortran, +OpenCL C, Pascal, Rust, assembly, Modula-2, and Ada. +@c This is false ... +Some @value{GDBN} features may be used in expressions regardless of the +language you use: the @value{GDBN} @code{@@} and @code{::} operators, +and the @samp{@{type@}addr} construct (@pxref{Expressions, +,Expressions}) can be used with the constructs of any supported +language. + +The following sections detail to what degree each source language is +supported by @value{GDBN}. These sections are not meant to be language +tutorials or references, but serve only as a reference guide to what the +@value{GDBN} expression parser accepts, and what input and output +formats should look like for different languages. There are many good +books written on each of these languages; please look to these for a +language reference or tutorial. + +@menu +* C:: C and C@t{++} +* D:: D +* Go:: Go +* Objective-C:: Objective-C +* OpenCL C:: OpenCL C +* Fortran:: Fortran +* Pascal:: Pascal +* Rust:: Rust +* Modula-2:: Modula-2 +* Ada:: Ada +@end menu + +@node C +@subsection C and C@t{++} + +@cindex C and C@t{++} +@cindex expressions in C or C@t{++} + +Since C and C@t{++} are so closely related, many features of @value{GDBN} apply +to both languages. Whenever this is the case, we discuss those languages +together. + +@cindex C@t{++} +@cindex @code{g++}, @sc{gnu} C@t{++} compiler +@cindex @sc{gnu} C@t{++} +The C@t{++} debugging facilities are jointly implemented by the C@t{++} +compiler and @value{GDBN}. Therefore, to debug your C@t{++} code +effectively, you must compile your C@t{++} programs with a supported +C@t{++} compiler, such as @sc{gnu} @code{g++}, or the HP ANSI C@t{++} +compiler (@code{aCC}). + +@menu +* C Operators:: C and C@t{++} operators +* C Constants:: C and C@t{++} constants +* C Plus Plus Expressions:: C@t{++} expressions +* C Defaults:: Default settings for C and C@t{++} +* C Checks:: C and C@t{++} type and range checks +* Debugging C:: @value{GDBN} and C +* Debugging C Plus Plus:: @value{GDBN} features for C@t{++} +* Decimal Floating Point:: Numbers in Decimal Floating Point format +@end menu + +@node C Operators +@subsubsection C and C@t{++} Operators + +@cindex C and C@t{++} operators + +Operators must be defined on values of specific types. For instance, +@code{+} is defined on numbers, but not on structures. Operators are +often defined on groups of types. + +For the purposes of C and C@t{++}, the following definitions hold: + +@itemize @bullet + +@item +@emph{Integral types} include @code{int} with any of its storage-class +specifiers; @code{char}; @code{enum}; and, for C@t{++}, @code{bool}. + +@item +@emph{Floating-point types} include @code{float}, @code{double}, and +@code{long double} (if supported by the target platform). + +@item +@emph{Pointer types} include all types defined as @code{(@var{type} *)}. + +@item +@emph{Scalar types} include all of the above. + +@end itemize + +@noindent +The following operators are supported. They are listed here +in order of increasing precedence: + +@table @code +@item , +The comma or sequencing operator. Expressions in a comma-separated list +are evaluated from left to right, with the result of the entire +expression being the last expression evaluated. + +@item = +Assignment. The value of an assignment expression is the value +assigned. Defined on scalar types. + +@item @var{op}= +Used in an expression of the form @w{@code{@var{a} @var{op}= @var{b}}}, +and translated to @w{@code{@var{a} = @var{a op b}}}. +@w{@code{@var{op}=}} and @code{=} have the same precedence. The operator +@var{op} is any one of the operators @code{|}, @code{^}, @code{&}, +@code{<<}, @code{>>}, @code{+}, @code{-}, @code{*}, @code{/}, @code{%}. + +@item ?: +The ternary operator. @code{@var{a} ? @var{b} : @var{c}} can be thought +of as: if @var{a} then @var{b} else @var{c}. The argument @var{a} +should be of an integral type. + +@item || +Logical @sc{or}. Defined on integral types. + +@item && +Logical @sc{and}. Defined on integral types. + +@item | +Bitwise @sc{or}. Defined on integral types. + +@item ^ +Bitwise exclusive-@sc{or}. Defined on integral types. + +@item & +Bitwise @sc{and}. Defined on integral types. + +@item ==@r{, }!= +Equality and inequality. Defined on scalar types. The value of these +expressions is 0 for false and non-zero for true. + +@item <@r{, }>@r{, }<=@r{, }>= +Less than, greater than, less than or equal, greater than or equal. +Defined on scalar types. The value of these expressions is 0 for false +and non-zero for true. + +@item <<@r{, }>> +left shift, and right shift. Defined on integral types. + +@item @@ +The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). + +@item +@r{, }- +Addition and subtraction. Defined on integral types, floating-point types and +pointer types. + +@item *@r{, }/@r{, }% +Multiplication, division, and modulus. Multiplication and division are +defined on integral and floating-point types. Modulus is defined on +integral types. + +@item ++@r{, }-- +Increment and decrement. When appearing before a variable, the +operation is performed before the variable is used in an expression; +when appearing after it, the variable's value is used before the +operation takes place. + +@item * +Pointer dereferencing. Defined on pointer types. Same precedence as +@code{++}. + +@item & +Address operator. Defined on variables. Same precedence as @code{++}. + +For debugging C@t{++}, @value{GDBN} implements a use of @samp{&} beyond what is +allowed in the C@t{++} language itself: you can use @samp{&(&@var{ref})} +to examine the address +where a C@t{++} reference variable (declared with @samp{&@var{ref}}) is +stored. + +@item - +Negative. Defined on integral and floating-point types. Same +precedence as @code{++}. + +@item ! +Logical negation. Defined on integral types. Same precedence as +@code{++}. + +@item ~ +Bitwise complement operator. Defined on integral types. Same precedence as +@code{++}. + + +@item .@r{, }-> +Structure member, and pointer-to-structure member. For convenience, +@value{GDBN} regards the two as equivalent, choosing whether to dereference a +pointer based on the stored type information. +Defined on @code{struct} and @code{union} data. + +@item .*@r{, }->* +Dereferences of pointers to members. + +@item [] +Array indexing. @code{@var{a}[@var{i}]} is defined as +@code{*(@var{a}+@var{i})}. Same precedence as @code{->}. + +@item () +Function parameter list. Same precedence as @code{->}. + +@item :: +C@t{++} scope resolution operator. Defined on @code{struct}, @code{union}, +and @code{class} types. + +@item :: +Doubled colons also represent the @value{GDBN} scope operator +(@pxref{Expressions, ,Expressions}). Same precedence as @code{::}, +above. +@end table + +If an operator is redefined in the user code, @value{GDBN} usually +attempts to invoke the redefined version instead of using the operator's +predefined meaning. + +@node C Constants +@subsubsection C and C@t{++} Constants + +@cindex C and C@t{++} constants + +@value{GDBN} allows you to express the constants of C and C@t{++} in the +following ways: + +@itemize @bullet +@item +Integer constants are a sequence of digits. Octal constants are +specified by a leading @samp{0} (i.e.@: zero), and hexadecimal constants +by a leading @samp{0x} or @samp{0X}. Constants may also end with a letter +@samp{l}, specifying that the constant should be treated as a +@code{long} value. + +@item +Floating point constants are a sequence of digits, followed by a decimal +point, followed by a sequence of digits, and optionally followed by an +exponent. An exponent is of the form: +@samp{@w{e@r{[[}+@r{]|}-@r{]}@var{nnn}}}, where @var{nnn} is another +sequence of digits. The @samp{+} is optional for positive exponents. +A floating-point constant may also end with a letter @samp{f} or +@samp{F}, specifying that the constant should be treated as being of +the @code{float} (as opposed to the default @code{double}) type; or with +a letter @samp{l} or @samp{L}, which specifies a @code{long double} +constant. + +@item +Enumerated constants consist of enumerated identifiers, or their +integral equivalents. + +@item +Character constants are a single character surrounded by single quotes +(@code{'}), or a number---the ordinal value of the corresponding character +(usually its @sc{ascii} value). Within quotes, the single character may +be represented by a letter or by @dfn{escape sequences}, which are of +the form @samp{\@var{nnn}}, where @var{nnn} is the octal representation +of the character's ordinal value; or of the form @samp{\@var{x}}, where +@samp{@var{x}} is a predefined special character---for example, +@samp{\n} for newline. + +Wide character constants can be written by prefixing a character +constant with @samp{L}, as in C. For example, @samp{L'x'} is the wide +form of @samp{x}. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + +@item +String constants are a sequence of character constants surrounded by +double quotes (@code{"}). Any valid character constant (as described +above) may appear. Double quotes within the string must be preceded by +a backslash, so for instance @samp{"a\"b'c"} is a string of five +characters. + +Wide string constants can be written by prefixing a string constant +with @samp{L}, as in C. The target wide character set is used when +computing the value of this constant (@pxref{Character Sets}). + +@item +Pointer constants are an integral value. You can also write pointers +to constants using the C operator @samp{&}. + +@item +Array constants are comma-separated lists surrounded by braces @samp{@{} +and @samp{@}}; for example, @samp{@{1,2,3@}} is a three-element array of +integers, @samp{@{@{1,2@}, @{3,4@}, @{5,6@}@}} is a three-by-two array, +and @samp{@{&"hi", &"there", &"fred"@}} is a three-element array of pointers. +@end itemize + +@node C Plus Plus Expressions +@subsubsection C@t{++} Expressions + +@cindex expressions in C@t{++} +@value{GDBN} expression handling can interpret most C@t{++} expressions. + +@cindex debugging C@t{++} programs +@cindex C@t{++} compilers +@cindex debug formats and C@t{++} +@cindex @value{NGCC} and C@t{++} +@quotation +@emph{Warning:} @value{GDBN} can only debug C@t{++} code if you use +the proper compiler and the proper debug format. Currently, +@value{GDBN} works best when debugging C@t{++} code that is compiled +with the most recent version of @value{NGCC} possible. The DWARF +debugging format is preferred; @value{NGCC} defaults to this on most +popular platforms. Other compilers and/or debug formats are likely to +work badly or not at all when using @value{GDBN} to debug C@t{++} +code. @xref{Compilation}. +@end quotation + +@enumerate + +@cindex member functions +@item +Member function calls are allowed; you can use expressions like + +@smallexample +count = aml->GetOriginal(x, y) +@end smallexample + +@vindex this@r{, inside C@t{++} member functions} +@cindex namespace in C@t{++} +@item +While a member function is active (in the selected stack frame), your +expressions have the same namespace available as the member function; +that is, @value{GDBN} allows implicit references to the class instance +pointer @code{this} following the same rules as C@t{++}. @code{using} +declarations in the current scope are also respected by @value{GDBN}. + +@cindex call overloaded functions +@cindex overloaded functions, calling +@cindex type conversions in C@t{++} +@item +You can call overloaded functions; @value{GDBN} resolves the function +call to the right definition, with some restrictions. @value{GDBN} does not +perform overload resolution involving user-defined type conversions, +calls to constructors, or instantiations of templates that do not exist +in the program. It also cannot handle ellipsis argument lists or +default arguments. + +It does perform integral conversions and promotions, floating-point +promotions, arithmetic conversions, pointer conversions, conversions of +class objects to base classes, and standard conversions such as those of +functions or arrays to pointers; it requires an exact match on the +number of function arguments. + +Overload resolution is always performed, unless you have specified +@code{set overload-resolution off}. @xref{Debugging C Plus Plus, +,@value{GDBN} Features for C@t{++}}. + +You must specify @code{set overload-resolution off} in order to use an +explicit function signature to call an overloaded function, as in +@smallexample +p 'foo(char,int)'('x', 13) +@end smallexample + +The @value{GDBN} command-completion facility can simplify this; +see @ref{Completion, ,Command Completion}. + +@cindex reference declarations +@item +@value{GDBN} understands variables declared as C@t{++} lvalue or rvalue +references; you can use them in expressions just as you do in C@t{++} +source---they are automatically dereferenced. + +In the parameter list shown when @value{GDBN} displays a frame, the values of +reference variables are not displayed (unlike other variables); this +avoids clutter, since references are often used for large structures. +The @emph{address} of a reference variable is always shown, unless +you have specified @samp{set print address off}. + +@item +@value{GDBN} supports the C@t{++} name resolution operator @code{::}---your +expressions can use it just as expressions in your program do. Since +one scope may be defined in another, you can use @code{::} repeatedly if +necessary, for example in an expression like +@samp{@var{scope1}::@var{scope2}::@var{name}}. @value{GDBN} also allows +resolving name scope by reference to source files, in both C and C@t{++} +debugging (@pxref{Variables, ,Program Variables}). + +@item +@value{GDBN} performs argument-dependent lookup, following the C@t{++} +specification. +@end enumerate + +@node C Defaults +@subsubsection C and C@t{++} Defaults + +@cindex C and C@t{++} defaults + +If you allow @value{GDBN} to set range checking automatically, it +defaults to @code{off} whenever the working language changes to +C or C@t{++}. This happens regardless of whether you or @value{GDBN} +selects the working language. + +If you allow @value{GDBN} to set the language automatically, it +recognizes source files whose names end with @file{.c}, @file{.C}, or +@file{.cc}, etc, and when @value{GDBN} enters code compiled from one of +these files, it sets the working language to C or C@t{++}. +@xref{Automatically, ,Having @value{GDBN} Infer the Source Language}, +for further details. + +@node C Checks +@subsubsection C and C@t{++} Type and Range Checks + +@cindex C and C@t{++} checks + +By default, when @value{GDBN} parses C or C@t{++} expressions, strict type +checking is used. However, if you turn type checking off, @value{GDBN} +will allow certain non-standard conversions, such as promoting integer +constants to pointers. + +Range checking, if turned on, is done on mathematical operations. Array +indices are not checked, since they are often used to index a pointer +that is not itself an array. + +@node Debugging C +@subsubsection @value{GDBN} and C + +The @code{set print union} and @code{show print union} commands apply to +the @code{union} type. When set to @samp{on}, any @code{union} that is +inside a @code{struct} or @code{class} is also printed. Otherwise, it +appears as @samp{@{...@}}. + +The @code{@@} operator aids in the debugging of dynamic arrays, formed +with pointers and a memory allocation function. @xref{Expressions, +,Expressions}. + +@node Debugging C Plus Plus +@subsubsection @value{GDBN} Features for C@t{++} + +@cindex commands for C@t{++} + +Some @value{GDBN} commands are particularly useful with C@t{++}, and some are +designed specifically for use with C@t{++}. Here is a summary: + +@table @code +@cindex break in overloaded functions +@item @r{breakpoint menus} +When you want a breakpoint in a function whose name is overloaded, +@value{GDBN} has the capability to display a menu of possible breakpoint +locations to help you specify which function definition you want. +@xref{Ambiguous Expressions,,Ambiguous Expressions}. + +@cindex overloading in C@t{++} +@item rbreak @var{regex} +Setting breakpoints using regular expressions is helpful for setting +breakpoints on overloaded functions that are not members of any special +classes. +@xref{Set Breaks, ,Setting Breakpoints}. + +@cindex C@t{++} exception handling +@item catch throw +@itemx catch rethrow +@itemx catch catch +Debug C@t{++} exception handling using these commands. @xref{Set +Catchpoints, , Setting Catchpoints}. + +@cindex inheritance +@item ptype @var{typename} +Print inheritance relationships as well as other information for type +@var{typename}. +@xref{Symbols, ,Examining the Symbol Table}. + +@item info vtbl @var{expression}. +The @code{info vtbl} command can be used to display the virtual +method tables of the object computed by @var{expression}. This shows +one entry per virtual table; there may be multiple virtual tables when +multiple inheritance is in use. + +@cindex C@t{++} demangling +@item demangle @var{name} +Demangle @var{name}. +@xref{Symbols}, for a more complete description of the @code{demangle} command. + +@cindex C@t{++} symbol display +@item set print demangle +@itemx show print demangle +@itemx set print asm-demangle +@itemx show print asm-demangle +Control whether C@t{++} symbols display in their source form, both when +displaying code as C@t{++} source and when displaying disassemblies. +@xref{Print Settings, ,Print Settings}. + +@item set print object +@itemx show print object +Choose whether to print derived (actual) or declared types of objects. +@xref{Print Settings, ,Print Settings}. + +@item set print vtbl +@itemx show print vtbl +Control the format for printing virtual function tables. +@xref{Print Settings, ,Print Settings}. +(The @code{vtbl} commands do not work on programs compiled with the HP +ANSI C@t{++} compiler (@code{aCC}).) + +@kindex set overload-resolution +@cindex overloaded functions, overload resolution +@item set overload-resolution on +Enable overload resolution for C@t{++} expression evaluation. The default +is on. For overloaded functions, @value{GDBN} evaluates the arguments +and searches for a function whose signature matches the argument types, +using the standard C@t{++} conversion rules (see @ref{C Plus Plus +Expressions, ,C@t{++} Expressions}, for details). +If it cannot find a match, it emits a message. + +@item set overload-resolution off +Disable overload resolution for C@t{++} expression evaluation. For +overloaded functions that are not class member functions, @value{GDBN} +chooses the first function of the specified name that it finds in the +symbol table, whether or not its arguments are of the correct type. For +overloaded functions that are class member functions, @value{GDBN} +searches for a function whose signature @emph{exactly} matches the +argument types. + +@kindex show overload-resolution +@item show overload-resolution +Show the current setting of overload resolution. + +@item @r{Overloaded symbol names} +You can specify a particular definition of an overloaded symbol, using +the same notation that is used to declare such symbols in C@t{++}: type +@code{@var{symbol}(@var{types})} rather than just @var{symbol}. You can +also use the @value{GDBN} command-line word completion facilities to list the +available choices, or to finish the type list for you. +@xref{Completion,, Command Completion}, for details on how to do this. + +@item @r{Breakpoints in template functions} + +Similar to how overloaded symbols are handled, @value{GDBN} will ignore +template parameter lists when it encounters a symbol which includes a +C@t{++} template. This permits setting breakpoints on families of template functions +or functions whose parameters include template types. + +The @kbd{-qualified} flag may be used to override this behavior, causing +@value{GDBN} to search for a specific function or type. + +The @value{GDBN} command-line word completion facility also understands +template parameters and may be used to list available choices or finish +template parameter lists for you. @xref{Completion,, Command Completion}, for +details on how to do this. + +@item @r{Breakpoints in functions with ABI tags} + +The GNU C@t{++} compiler introduced the notion of ABI ``tags'', which +correspond to changes in the ABI of a type, function, or variable that +would not otherwise be reflected in a mangled name. See +@url{https://developers.redhat.com/blog/2015/02/05/gcc5-and-the-c11-abi/} +for more detail. + +The ABI tags are visible in C@t{++} demangled names. For example, a +function that returns a std::string: + +@smallexample +std::string function(int); +@end smallexample + +@noindent +when compiled for the C++11 ABI is marked with the @code{cxx11} ABI +tag, and @value{GDBN} displays the symbol like this: + +@smallexample +function[abi:cxx11](int) +@end smallexample + +You can set a breakpoint on such functions simply as if they had no +tag. For example: + +@smallexample +(@value{GDBP}) b function(int) +Breakpoint 2 at 0x40060d: file main.cc, line 10. +(@value{GDBP}) info breakpoints +Num Type Disp Enb Address What +1 breakpoint keep y 0x0040060d in function[abi:cxx11](int) + at main.cc:10 +@end smallexample + +On the rare occasion you need to disambiguate between different ABI +tags, you can do so by simply including the ABI tag in the function +name, like: + +@smallexample +(@value{GDBP}) b ambiguous[abi:other_tag](int) +@end smallexample +@end table + +@node Decimal Floating Point +@subsubsection Decimal Floating Point format +@cindex decimal floating point format + +@value{GDBN} can examine, set and perform computations with numbers in +decimal floating point format, which in the C language correspond to the +@code{_Decimal32}, @code{_Decimal64} and @code{_Decimal128} types as +specified by the extension to support decimal floating-point arithmetic. + +There are two encodings in use, depending on the architecture: BID (Binary +Integer Decimal) for x86 and x86-64, and DPD (Densely Packed Decimal) for +PowerPC and S/390. @value{GDBN} will use the appropriate encoding for the +configured target. + +Because of a limitation in @file{libdecnumber}, the library used by @value{GDBN} +to manipulate decimal floating point numbers, it is not possible to convert +(using a cast, for example) integers wider than 32-bit to decimal float. + +In addition, in order to imitate @value{GDBN}'s behavior with binary floating +point computations, error checking in decimal float operations ignores +underflow, overflow and divide by zero exceptions. + +In the PowerPC architecture, @value{GDBN} provides a set of pseudo-registers +to inspect @code{_Decimal128} values stored in floating point registers. +See @ref{PowerPC,,PowerPC} for more details. + +@node D +@subsection D + +@cindex D +@value{GDBN} can be used to debug programs written in D and compiled with +GDC, LDC or DMD compilers. Currently @value{GDBN} supports only one D +specific feature --- dynamic arrays. + +@node Go +@subsection Go + +@cindex Go (programming language) +@value{GDBN} can be used to debug programs written in Go and compiled with +@file{gccgo} or @file{6g} compilers. + +Here is a summary of the Go-specific features and restrictions: + +@table @code +@cindex current Go package +@item The current Go package +The name of the current package does not need to be specified when +specifying global variables and functions. + +For example, given the program: + +@example +package main +var myglob = "Shall we?" +func main () @{ + // ... +@} +@end example + +When stopped inside @code{main} either of these work: + +@example +(@value{GDBP}) p myglob +(@value{GDBP}) p main.myglob +@end example + +@cindex builtin Go types +@item Builtin Go types +The @code{string} type is recognized by @value{GDBN} and is printed +as a string. + +@cindex builtin Go functions +@item Builtin Go functions +The @value{GDBN} expression parser recognizes the @code{unsafe.Sizeof} +function and handles it internally. + +@cindex restrictions on Go expressions +@item Restrictions on Go expressions +All Go operators are supported except @code{&^}. +The Go @code{_} ``blank identifier'' is not supported. +Automatic dereferencing of pointers is not supported. +@end table + +@node Objective-C +@subsection Objective-C + +@cindex Objective-C +This section provides information about some commands and command +options that are useful for debugging Objective-C code. See also +@ref{Symbols, info classes}, and @ref{Symbols, info selectors}, for a +few more commands specific to Objective-C support. + +@menu +* Method Names in Commands:: +* The Print Command with Objective-C:: +@end menu + +@node Method Names in Commands +@subsubsection Method Names in Commands + +The following commands have been extended to accept Objective-C method +names as line specifications: + +@kindex clear@r{, and Objective-C} +@kindex break@r{, and Objective-C} +@kindex info line@r{, and Objective-C} +@kindex jump@r{, and Objective-C} +@kindex list@r{, and Objective-C} +@itemize +@item @code{clear} +@item @code{break} +@item @code{info line} +@item @code{jump} +@item @code{list} +@end itemize + +A fully qualified Objective-C method name is specified as + +@smallexample +-[@var{Class} @var{methodName}] +@end smallexample + +where the minus sign is used to indicate an instance method and a +plus sign (not shown) is used to indicate a class method. The class +name @var{Class} and method name @var{methodName} are enclosed in +brackets, similar to the way messages are specified in Objective-C +source code. For example, to set a breakpoint at the @code{create} +instance method of class @code{Fruit} in the program currently being +debugged, enter: + +@smallexample +break -[Fruit create] +@end smallexample + +To list ten program lines around the @code{initialize} class method, +enter: + +@smallexample +list +[NSText initialize] +@end smallexample + +In the current version of @value{GDBN}, the plus or minus sign is +required. In future versions of @value{GDBN}, the plus or minus +sign will be optional, but you can use it to narrow the search. It +is also possible to specify just a method name: + +@smallexample +break create +@end smallexample + +You must specify the complete method name, including any colons. If +your program's source files contain more than one @code{create} method, +you'll be presented with a numbered list of classes that implement that +method. Indicate your choice by number, or type @samp{0} to exit if +none apply. + +As another example, to clear a breakpoint established at the +@code{makeKeyAndOrderFront:} method of the @code{NSWindow} class, enter: + +@smallexample +clear -[NSWindow makeKeyAndOrderFront:] +@end smallexample + +@node The Print Command with Objective-C +@subsubsection The Print Command With Objective-C +@cindex Objective-C, print objects +@kindex print-object +@kindex po @r{(@code{print-object})} + +The print command has also been extended to accept methods. For example: + +@smallexample +print -[@var{object} hash] +@end smallexample + +@cindex print an Objective-C object description +@cindex @code{_NSPrintForDebugger}, and printing Objective-C objects +@noindent +will tell @value{GDBN} to send the @code{hash} message to @var{object} +and print the result. Also, an additional command has been added, +@code{print-object} or @code{po} for short, which is meant to print +the description of an object. However, this command may only work +with certain Objective-C libraries that have a particular hook +function, @code{_NSPrintForDebugger}, defined. + +@node OpenCL C +@subsection OpenCL C + +@cindex OpenCL C +This section provides information about @value{GDBN}s OpenCL C support. + +@menu +* OpenCL C Datatypes:: +* OpenCL C Expressions:: +* OpenCL C Operators:: +@end menu + +@node OpenCL C Datatypes +@subsubsection OpenCL C Datatypes + +@cindex OpenCL C Datatypes +@value{GDBN} supports the builtin scalar and vector datatypes specified +by OpenCL 1.1. In addition the half- and double-precision floating point +data types of the @code{cl_khr_fp16} and @code{cl_khr_fp64} OpenCL +extensions are also known to @value{GDBN}. + +@node OpenCL C Expressions +@subsubsection OpenCL C Expressions + +@cindex OpenCL C Expressions +@value{GDBN} supports accesses to vector components including the access as +lvalue where possible. Since OpenCL C is based on C99 most C expressions +supported by @value{GDBN} can be used as well. + +@node OpenCL C Operators +@subsubsection OpenCL C Operators + +@cindex OpenCL C Operators +@value{GDBN} supports the operators specified by OpenCL 1.1 for scalar and +vector data types. + +@node Fortran +@subsection Fortran +@cindex Fortran-specific support in @value{GDBN} + +@value{GDBN} can be used to debug programs written in Fortran. Note, that not +all Fortran language features are available yet. + +@cindex trailing underscore, in Fortran symbols +Some Fortran compilers (@sc{gnu} Fortran 77 and Fortran 95 compilers +among them) append an underscore to the names of variables and +functions. When you debug programs compiled by those compilers, you +will need to refer to variables and functions with a trailing +underscore. + +@cindex Fortran Defaults +Fortran symbols are usually case-insensitive, so @value{GDBN} by +default uses case-insensitive matching for Fortran symbols. You can +change that with the @samp{set case-insensitive} command, see +@ref{Symbols}, for the details. + +@menu +* Fortran Types:: Fortran builtin types +* Fortran Operators:: Fortran operators and expressions +* Fortran Intrinsics:: Fortran intrinsic functions +* Special Fortran Commands:: Special @value{GDBN} commands for Fortran +@end menu + +@node Fortran Types +@subsubsection Fortran Types + +@cindex Fortran Types + +In Fortran the primitive data-types have an associated @code{KIND} type +parameter, written as @samp{@var{type}*@var{kindparam}}, +@samp{@var{type}*@var{kindparam}}, or in the @value{GDBN}-only dialect +@samp{@var{type}_@var{kindparam}}. A concrete example would be +@samp{@code{Real*4}}, @samp{@code{Real(kind=4)}}, and @samp{@code{Real_4}}. +The kind of a type can be retrieved by using the intrinsic function +@code{KIND}, see @ref{Fortran Intrinsics}. + +Generally, the actual implementation of the @code{KIND} type parameter is +compiler specific. In @value{GDBN} the kind parameter is implemented in +accordance with its use in the @sc{gnu} @command{gfortran} compiler. Here, the +kind parameter for a given @var{type} specifies its size in memory --- a +Fortran @code{Integer*4} or @code{Integer(kind=4)} would be an integer type +occupying 4 bytes of memory. An exception to this rule is the @code{Complex} +type for which the kind of the type does not specify its entire size, but +the size of each of the two @code{Real}'s it is composed of. A +@code{Complex*4} would thus consist of two @code{Real*4}s and occupy 8 bytes +of memory. + +For every type there is also a default kind associated with it, e.g.@ +@code{Integer} in @value{GDBN} will internally be an @code{Integer*4} (see the +table below for default types). The default types are the same as in @sc{gnu} +compilers but note, that the @sc{gnu} default types can actually be changed by +compiler flags such as @option{-fdefault-integer-8} and +@option{-fdefault-real-8}. + +Not every kind parameter is valid for every type and in @value{GDBN} the +following type kinds are available. + +@table @code +@item Integer +@code{Integer*1}, @code{Integer*2}, @code{Integer*4}, @code{Integer*8}, and +@code{Integer} = @code{Integer*4}. + +@item Logical +@code{Logical*1}, @code{Logical*2}, @code{Logical*4}, @code{Logical*8}, and +@code{Logical} = @code{Logical*4}. + +@item Real +@code{Real*4}, @code{Real*8}, @code{Real*16}, and @code{Real} = @code{Real*4}. + +@item Complex +@code{Complex*4}, @code{Complex*8}, @code{Complex*16}, and @code{Complex} = +@code{Complex*4}. + +@end table + +@node Fortran Operators +@subsubsection Fortran Operators and Expressions + +@cindex Fortran operators and expressions + +Operators must be defined on values of specific types. For instance, +@code{+} is defined on numbers, but not on characters or other non- +arithmetic types. Operators are often defined on groups of types. + +@table @code +@item ** +The exponentiation operator. It raises the first operand to the power +of the second one. + +@item : +The range operator. Normally used in the form of array(low:high) to +represent a section of array. + +@item % +The access component operator. Normally used to access elements in derived +types. Also suitable for unions. As unions aren't part of regular Fortran, +this can only happen when accessing a register that uses a gdbarch-defined +union type. +@item :: +The scope operator. Normally used to access variables in modules or +to set breakpoints on subroutines nested in modules or in other +subroutines (internal subroutines). +@end table + +@node Fortran Intrinsics +@subsubsection Fortran Intrinsics + +@cindex Fortran Intrinsics + +Fortran provides a large set of intrinsic procedures. @value{GDBN} implements +an incomplete subset of those procedures and their overloads. Some of these +procedures take an optional @code{KIND} parameter, see @ref{Fortran Types}. + +@table @code +@item ABS(@var{a}) +Computes the absolute value of its argument @var{a}. Currently not supported +for @code{Complex} arguments. + +@item ALLOCATE(@var{array}) +Returns whether @var{array} is allocated or not. + +@item ASSOCIATED(@var{pointer} [, @var{target}]) +Returns the association status of the pointer @var{pointer} or, if @var{target} +is present, whether @var{pointer} is associated with the target @var{target}. + +@item CEILING(@var{a} [, @var{kind}]) +Computes the least integer greater than or equal to @var{a}. The optional +parameter @var{kind} specifies the kind of the return type +@code{Integer(@var{kind})}. + +@item CMPLX(@var{x} [, @var{y} [, @var{kind}]]) +Returns a complex number where @var{x} is converted to the real component. If +@var{y} is present it is converted to the imaginary component. If @var{y} is +not present then the imaginary component is set to @code{0.0} except if @var{x} +itself is of @code{Complex} type. The optional parameter @var{kind} specifies +the kind of the return type @code{Complex(@var{kind})}. + +@item FLOOR(@var{a} [, @var{kind}]) +Computes the greatest integer less than or equal to @var{a}. The optional +parameter @var{kind} specifies the kind of the return type +@code{Integer(@var{kind})}. + +@item KIND(@var{a}) +Returns the kind value of the argument @var{a}, see @ref{Fortran Types}. + +@item LBOUND(@var{array} [, @var{dim} [, @var{kind}]]) +Returns the lower bounds of an @var{array}, or a single lower bound along the +@var{dim} dimension if present. The optional parameter @var{kind} specifies +the kind of the return type @code{Integer(@var{kind})}. + +@item LOC(@var{x}) +Returns the address of @var{x} as an @code{Integer}. + +@item MOD(@var{a}, @var{p}) +Computes the remainder of the division of @var{a} by @var{p}. + +@item MODULO(@var{a}, @var{p}) +Computes the @var{a} modulo @var{p}. + +@item RANK(@var{a}) +Returns the rank of a scalar or array (scalars have rank @code{0}). + +@item SHAPE(@var{a}) +Returns the shape of a scalar or array (scalars have shape @samp{()}). + +@item SIZE(@var{array}[, @var{dim} [, @var{kind}]]) +Returns the extent of @var{array} along a specified dimension @var{dim}, or the +total number of elements in @var{array} if @var{dim} is absent. The optional +parameter @var{kind} specifies the kind of the return type +@code{Integer(@var{kind})}. + +@item UBOUND(@var{array} [, @var{dim} [, @var{kind}]]) +Returns the upper bounds of an @var{array}, or a single upper bound along the +@var{dim} dimension if present. The optional parameter @var{kind} specifies +the kind of the return type @code{Integer(@var{kind})}. + +@end table + +@node Special Fortran Commands +@subsubsection Special Fortran Commands + +@cindex Special Fortran commands + +@value{GDBN} has some commands to support Fortran-specific features, +such as displaying common blocks. + +@table @code +@cindex @code{COMMON} blocks, Fortran +@kindex info common +@item info common @r{[}@var{common-name}@r{]} +This command prints the values contained in the Fortran @code{COMMON} +block whose name is @var{common-name}. With no argument, the names of +all @code{COMMON} blocks visible at the current program location are +printed. +@cindex arrays slices (Fortran) +@kindex set fortran repack-array-slices +@kindex show fortran repack-array-slices +@item set fortran repack-array-slices [on|off] +@item show fortran repack-array-slices +When taking a slice from an array, a Fortran compiler can choose to +either produce an array descriptor that describes the slice in place, +or it may repack the slice, copying the elements of the slice into a +new region of memory. + +When this setting is on, then @value{GDBN} will also repack array +slices in some situations. When this setting is off, then +@value{GDBN} will create array descriptors for slices that reference +the original data in place. + +@value{GDBN} will never repack an array slice if the data for the +slice is contiguous within the original array. + +@value{GDBN} will always repack string slices if the data for the +slice is non-contiguous within the original string as @value{GDBN} +does not support printing non-contiguous strings. + +The default for this setting is @code{off}. +@end table + +@node Pascal +@subsection Pascal + +@cindex Pascal support in @value{GDBN}, limitations +Debugging Pascal programs which use sets, subranges, file variables, or +nested functions does not currently work. @value{GDBN} does not support +entering expressions, printing values, or similar features using Pascal +syntax. + +The Pascal-specific command @code{set print pascal_static-members} +controls whether static members of Pascal objects are displayed. +@xref{Print Settings, pascal_static-members}. + +@node Rust +@subsection Rust + +@value{GDBN} supports the @url{https://www.rust-lang.org/, Rust +Programming Language}. Type- and value-printing, and expression +parsing, are reasonably complete. However, there are a few +peculiarities and holes to be aware of. + +@itemize @bullet +@item +Linespecs (@pxref{Location Specifications}) are never relative to the +current crate. Instead, they act as if there were a global namespace +of crates, somewhat similar to the way @code{extern crate} behaves. + +That is, if @value{GDBN} is stopped at a breakpoint in a function in +crate @samp{A}, module @samp{B}, then @code{break B::f} will attempt +to set a breakpoint in a function named @samp{f} in a crate named +@samp{B}. + +As a consequence of this approach, linespecs also cannot refer to +items using @samp{self::} or @samp{super::}. + +@item +Because @value{GDBN} implements Rust name-lookup semantics in +expressions, it will sometimes prepend the current crate to a name. +For example, if @value{GDBN} is stopped at a breakpoint in the crate +@samp{K}, then @code{print ::x::y} will try to find the symbol +@samp{K::x::y}. + +However, since it is useful to be able to refer to other crates when +debugging, @value{GDBN} provides the @code{extern} extension to +circumvent this. To use the extension, just put @code{extern} before +a path expression to refer to the otherwise unavailable ``global'' +scope. + +In the above example, if you wanted to refer to the symbol @samp{y} in +the crate @samp{x}, you would use @code{print extern x::y}. + +@item +The Rust expression evaluator does not support ``statement-like'' +expressions such as @code{if} or @code{match}, or lambda expressions. + +@item +Tuple expressions are not implemented. + +@item +The Rust expression evaluator does not currently implement the +@code{Drop} trait. Objects that may be created by the evaluator will +never be destroyed. + +@item +@value{GDBN} does not implement type inference for generics. In order +to call generic functions or otherwise refer to generic items, you +will have to specify the type parameters manually. + +@item +@value{GDBN} currently uses the C@t{++} demangler for Rust. In most +cases this does not cause any problems. However, in an expression +context, completing a generic function name will give syntactically +invalid results. This happens because Rust requires the @samp{::} +operator between the function name and its generic arguments. For +example, @value{GDBN} might provide a completion like +@code{crate::f}, where the parser would require +@code{crate::f::}. + +@item +As of this writing, the Rust compiler (version 1.8) has a few holes in +the debugging information it generates. These holes prevent certain +features from being implemented by @value{GDBN}: +@itemize @bullet + +@item +Method calls cannot be made via traits. + +@item +Operator overloading is not implemented. + +@item +When debugging in a monomorphized function, you cannot use the generic +type names. + +@item +The type @code{Self} is not available. + +@item +@code{use} statements are not available, so some names may not be +available in the crate. +@end itemize +@end itemize + +@node Modula-2 +@subsection Modula-2 + +@cindex Modula-2, @value{GDBN} support + +The extensions made to @value{GDBN} to support Modula-2 only support +output from the @sc{gnu} Modula-2 compiler (which is currently being +developed). Other Modula-2 compilers are not currently supported, and +attempting to debug executables produced by them is most likely +to give an error as @value{GDBN} reads in the executable's symbol +table. + +@cindex expressions in Modula-2 +@menu +* M2 Operators:: Built-in operators +* Built-In Func/Proc:: Built-in functions and procedures +* M2 Constants:: Modula-2 constants +* M2 Types:: Modula-2 types +* M2 Defaults:: Default settings for Modula-2 +* Deviations:: Deviations from standard Modula-2 +* M2 Checks:: Modula-2 type and range checks +* M2 Scope:: The scope operators @code{::} and @code{.} +* GDB/M2:: @value{GDBN} and Modula-2 +@end menu + +@node M2 Operators +@subsubsection Operators +@cindex Modula-2 operators + +Operators must be defined on values of specific types. For instance, +@code{+} is defined on numbers, but not on structures. Operators are +often defined on groups of types. For the purposes of Modula-2, the +following definitions hold: + +@itemize @bullet + +@item +@emph{Integral types} consist of @code{INTEGER}, @code{CARDINAL}, and +their subranges. + +@item +@emph{Character types} consist of @code{CHAR} and its subranges. + +@item +@emph{Floating-point types} consist of @code{REAL}. + +@item +@emph{Pointer types} consist of anything declared as @code{POINTER TO +@var{type}}. + +@item +@emph{Scalar types} consist of all of the above. + +@item +@emph{Set types} consist of @code{SET} and @code{BITSET} types. + +@item +@emph{Boolean types} consist of @code{BOOLEAN}. +@end itemize + +@noindent +The following operators are supported, and appear in order of +increasing precedence: + +@table @code +@item , +Function argument or array index separator. + +@item := +Assignment. The value of @var{var} @code{:=} @var{value} is +@var{value}. + +@item <@r{, }> +Less than, greater than on integral, floating-point, or enumerated +types. + +@item <=@r{, }>= +Less than or equal to, greater than or equal to +on integral, floating-point and enumerated types, or set inclusion on +set types. Same precedence as @code{<}. + +@item =@r{, }<>@r{, }# +Equality and two ways of expressing inequality, valid on scalar types. +Same precedence as @code{<}. In @value{GDBN} scripts, only @code{<>} is +available for inequality, since @code{#} conflicts with the script +comment character. + +@item IN +Set membership. Defined on set types and the types of their members. +Same precedence as @code{<}. + +@item OR +Boolean disjunction. Defined on boolean types. + +@item AND@r{, }& +Boolean conjunction. Defined on boolean types. + +@item @@ +The @value{GDBN} ``artificial array'' operator (@pxref{Expressions, ,Expressions}). + +@item +@r{, }- +Addition and subtraction on integral and floating-point types, or union +and difference on set types. + +@item * +Multiplication on integral and floating-point types, or set intersection +on set types. + +@item / +Division on floating-point types, or symmetric set difference on set +types. Same precedence as @code{*}. + +@item DIV@r{, }MOD +Integer division and remainder. Defined on integral types. Same +precedence as @code{*}. + +@item - +Negative. Defined on @code{INTEGER} and @code{REAL} data. + +@item ^ +Pointer dereferencing. Defined on pointer types. + +@item NOT +Boolean negation. Defined on boolean types. Same precedence as +@code{^}. + +@item . +@code{RECORD} field selector. Defined on @code{RECORD} data. Same +precedence as @code{^}. + +@item [] +Array indexing. Defined on @code{ARRAY} data. Same precedence as @code{^}. + +@item () +Procedure argument list. Defined on @code{PROCEDURE} objects. Same precedence +as @code{^}. + +@item ::@r{, }. +@value{GDBN} and Modula-2 scope operators. +@end table + +@quotation +@emph{Warning:} Set expressions and their operations are not yet supported, so @value{GDBN} +treats the use of the operator @code{IN}, or the use of operators +@code{+}, @code{-}, @code{*}, @code{/}, @code{=}, , @code{<>}, @code{#}, +@code{<=}, and @code{>=} on sets as an error. +@end quotation + + +@node Built-In Func/Proc +@subsubsection Built-in Functions and Procedures +@cindex Modula-2 built-ins + +Modula-2 also makes available several built-in procedures and functions. +In describing these, the following metavariables are used: + +@table @var + +@item a +represents an @code{ARRAY} variable. + +@item c +represents a @code{CHAR} constant or variable. + +@item i +represents a variable or constant of integral type. + +@item m +represents an identifier that belongs to a set. Generally used in the +same function with the metavariable @var{s}. The type of @var{s} should +be @code{SET OF @var{mtype}} (where @var{mtype} is the type of @var{m}). + +@item n +represents a variable or constant of integral or floating-point type. + +@item r +represents a variable or constant of floating-point type. + +@item t +represents a type. + +@item v +represents a variable. + +@item x +represents a variable or constant of one of many types. See the +explanation of the function for details. +@end table + +All Modula-2 built-in procedures also return a result, described below. + +@table @code +@item ABS(@var{n}) +Returns the absolute value of @var{n}. + +@item ADR(@var{n}) +Returns the memory address of @var{n}. + +@item CAP(@var{c}) +If @var{c} is a lower case letter, it returns its upper case +equivalent, otherwise it returns its argument. + +@item CHR(@var{i}) +Returns the character whose ordinal value is @var{i}. + +@item DEC(@var{v}) +Decrements the value in the variable @var{v} by one. Returns the new value. + +@item DEC(@var{v},@var{i}) +Decrements the value in the variable @var{v} by @var{i}. Returns the +new value. + +@item EXCL(@var{m},@var{s}) +Removes the element @var{m} from the set @var{s}. Returns the new +set. + +@item FLOAT(@var{i}) +Returns the floating point equivalent of the integer @var{i}. + +@item HIGH(@var{a}) +Returns the index of the last member of @var{a}. + +@item INC(@var{v}) +Increments the value in the variable @var{v} by one. Returns the new value. + +@item INC(@var{v},@var{i}) +Increments the value in the variable @var{v} by @var{i}. Returns the +new value. + +@item INCL(@var{m},@var{s}) +Adds the element @var{m} to the set @var{s} if it is not already +there. Returns the new set. + +@item MAX(@var{t}) +Returns the maximum value of the type @var{t}. + +@item MIN(@var{t}) +Returns the minimum value of the type @var{t}. + +@item ODD(@var{i}) +Returns boolean TRUE if @var{i} is an odd number. + +@item ORD(@var{x}) +Returns the ordinal value of its argument. For example, the ordinal +value of a character is its @sc{ascii} value (on machines supporting +the @sc{ascii} character set). The argument @var{x} must be of an +ordered type, which include integral, character and enumerated types. + +@item SIZE(@var{x}) +Returns the size of its argument. The argument @var{x} can be a +variable or a type. + +@item TRUNC(@var{r}) +Returns the integral part of @var{r}. + +@item TSIZE(@var{x}) +Returns the size of its argument. The argument @var{x} can be a +variable or a type. + +@item VAL(@var{t},@var{i}) +Returns the member of the type @var{t} whose ordinal value is @var{i}. +@end table + +@quotation +@emph{Warning:} Sets and their operations are not yet supported, so +@value{GDBN} treats the use of procedures @code{INCL} and @code{EXCL} as +an error. +@end quotation + +@cindex Modula-2 constants +@node M2 Constants +@subsubsection Constants + +@value{GDBN} allows you to express the constants of Modula-2 in the following +ways: + +@itemize @bullet + +@item +Integer constants are simply a sequence of digits. When used in an +expression, a constant is interpreted to be type-compatible with the +rest of the expression. Hexadecimal integers are specified by a +trailing @samp{H}, and octal integers by a trailing @samp{B}. + +@item +Floating point constants appear as a sequence of digits, followed by a +decimal point and another sequence of digits. An optional exponent can +then be specified, in the form @samp{E@r{[}+@r{|}-@r{]}@var{nnn}}, where +@samp{@r{[}+@r{|}-@r{]}@var{nnn}} is the desired exponent. All of the +digits of the floating point constant must be valid decimal (base 10) +digits. + +@item +Character constants consist of a single character enclosed by a pair of +like quotes, either single (@code{'}) or double (@code{"}). They may +also be expressed by their ordinal value (their @sc{ascii} value, usually) +followed by a @samp{C}. + +@item +String constants consist of a sequence of characters enclosed by a +pair of like quotes, either single (@code{'}) or double (@code{"}). +Escape sequences in the style of C are also allowed. @xref{C +Constants, ,C and C@t{++} Constants}, for a brief explanation of escape +sequences. + +@item +Enumerated constants consist of an enumerated identifier. + +@item +Boolean constants consist of the identifiers @code{TRUE} and +@code{FALSE}. + +@item +Pointer constants consist of integral values only. + +@item +Set constants are not yet supported. +@end itemize + +@node M2 Types +@subsubsection Modula-2 Types +@cindex Modula-2 types + +Currently @value{GDBN} can print the following data types in Modula-2 +syntax: array types, record types, set types, pointer types, procedure +types, enumerated types, subrange types and base types. You can also +print the contents of variables declared using these type. +This section gives a number of simple source code examples together with +sample @value{GDBN} sessions. + +The first example contains the following section of code: + +@smallexample +VAR + s: SET OF CHAR ; + r: [20..40] ; +@end smallexample + +@noindent +and you can request @value{GDBN} to interrogate the type and value of +@code{r} and @code{s}. + +@smallexample +(@value{GDBP}) print s +@{'A'..'C', 'Z'@} +(@value{GDBP}) ptype s +SET OF CHAR +(@value{GDBP}) print r +21 +(@value{GDBP}) ptype r +[20..40] +@end smallexample + +@noindent +Likewise if your source code declares @code{s} as: + +@smallexample +VAR + s: SET ['A'..'Z'] ; +@end smallexample + +@noindent +then you may query the type of @code{s} by: + +@smallexample +(@value{GDBP}) ptype s +type = SET ['A'..'Z'] +@end smallexample + +@noindent +Note that at present you cannot interactively manipulate set +expressions using the debugger. + +The following example shows how you might declare an array in Modula-2 +and how you can interact with @value{GDBN} to print its type and contents: + +@smallexample +VAR + s: ARRAY [-10..10] OF CHAR ; +@end smallexample + +@smallexample +(@value{GDBP}) ptype s +ARRAY [-10..10] OF CHAR +@end smallexample + +Note that the array handling is not yet complete and although the type +is printed correctly, expression handling still assumes that all +arrays have a lower bound of zero and not @code{-10} as in the example +above. + +Here are some more type related Modula-2 examples: + +@smallexample +TYPE + colour = (blue, red, yellow, green) ; + t = [blue..yellow] ; +VAR + s: t ; +BEGIN + s := blue ; +@end smallexample + +@noindent +The @value{GDBN} interaction shows how you can query the data type +and value of a variable. + +@smallexample +(@value{GDBP}) print s +$1 = blue +(@value{GDBP}) ptype t +type = [blue..yellow] +@end smallexample + +@noindent +In this example a Modula-2 array is declared and its contents +displayed. Observe that the contents are written in the same way as +their @code{C} counterparts. + +@smallexample +VAR + s: ARRAY [1..5] OF CARDINAL ; +BEGIN + s[1] := 1 ; +@end smallexample + +@smallexample +(@value{GDBP}) print s +$1 = @{1, 0, 0, 0, 0@} +(@value{GDBP}) ptype s +type = ARRAY [1..5] OF CARDINAL +@end smallexample + +The Modula-2 language interface to @value{GDBN} also understands +pointer types as shown in this example: + +@smallexample +VAR + s: POINTER TO ARRAY [1..5] OF CARDINAL ; +BEGIN + NEW(s) ; + s^[1] := 1 ; +@end smallexample + +@noindent +and you can request that @value{GDBN} describes the type of @code{s}. + +@smallexample +(@value{GDBP}) ptype s +type = POINTER TO ARRAY [1..5] OF CARDINAL +@end smallexample + +@value{GDBN} handles compound types as we can see in this example. +Here we combine array types, record types, pointer types and subrange +types: + +@smallexample +TYPE + foo = RECORD + f1: CARDINAL ; + f2: CHAR ; + f3: myarray ; + END ; + + myarray = ARRAY myrange OF CARDINAL ; + myrange = [-2..2] ; +VAR + s: POINTER TO ARRAY myrange OF foo ; +@end smallexample + +@noindent +and you can ask @value{GDBN} to describe the type of @code{s} as shown +below. + +@smallexample +(@value{GDBP}) ptype s +type = POINTER TO ARRAY [-2..2] OF foo = RECORD + f1 : CARDINAL; + f2 : CHAR; + f3 : ARRAY [-2..2] OF CARDINAL; +END +@end smallexample + +@node M2 Defaults +@subsubsection Modula-2 Defaults +@cindex Modula-2 defaults + +If type and range checking are set automatically by @value{GDBN}, they +both default to @code{on} whenever the working language changes to +Modula-2. This happens regardless of whether you or @value{GDBN} +selected the working language. + +If you allow @value{GDBN} to set the language automatically, then entering +code compiled from a file whose name ends with @file{.mod} sets the +working language to Modula-2. @xref{Automatically, ,Having @value{GDBN} +Infer the Source Language}, for further details. + +@node Deviations +@subsubsection Deviations from Standard Modula-2 +@cindex Modula-2, deviations from + +A few changes have been made to make Modula-2 programs easier to debug. +This is done primarily via loosening its type strictness: + +@itemize @bullet +@item +Unlike in standard Modula-2, pointer constants can be formed by +integers. This allows you to modify pointer variables during +debugging. (In standard Modula-2, the actual address contained in a +pointer variable is hidden from you; it can only be modified +through direct assignment to another pointer variable or expression that +returned a pointer.) + +@item +C escape sequences can be used in strings and characters to represent +non-printable characters. @value{GDBN} prints out strings with these +escape sequences embedded. Single non-printable characters are +printed using the @samp{CHR(@var{nnn})} format. + +@item +The assignment operator (@code{:=}) returns the value of its right-hand +argument. + +@item +All built-in procedures both modify @emph{and} return their argument. +@end itemize + +@node M2 Checks +@subsubsection Modula-2 Type and Range Checks +@cindex Modula-2 checks + +@quotation +@emph{Warning:} in this release, @value{GDBN} does not yet perform type or +range checking. +@end quotation +@c FIXME remove warning when type/range checks added + +@value{GDBN} considers two Modula-2 variables type equivalent if: + +@itemize @bullet +@item +They are of types that have been declared equivalent via a @code{TYPE +@var{t1} = @var{t2}} statement + +@item +They have been declared on the same line. (Note: This is true of the +@sc{gnu} Modula-2 compiler, but it may not be true of other compilers.) +@end itemize + +As long as type checking is enabled, any attempt to combine variables +whose types are not equivalent is an error. + +Range checking is done on all mathematical operations, assignment, array +index bounds, and all built-in functions and procedures. + +@node M2 Scope +@subsubsection The Scope Operators @code{::} and @code{.} +@cindex scope +@cindex @code{.}, Modula-2 scope operator +@cindex colon, doubled as scope operator +@ifinfo +@vindex colon-colon@r{, in Modula-2} +@c Info cannot handle :: but TeX can. +@end ifinfo +@ifnotinfo +@vindex ::@r{, in Modula-2} +@end ifnotinfo + +There are a few subtle differences between the Modula-2 scope operator +(@code{.}) and the @value{GDBN} scope operator (@code{::}). The two have +similar syntax: + +@smallexample + +@var{module} . @var{id} +@var{scope} :: @var{id} +@end smallexample + +@noindent +where @var{scope} is the name of a module or a procedure, +@var{module} the name of a module, and @var{id} is any declared +identifier within your program, except another module. + +Using the @code{::} operator makes @value{GDBN} search the scope +specified by @var{scope} for the identifier @var{id}. If it is not +found in the specified scope, then @value{GDBN} searches all scopes +enclosing the one specified by @var{scope}. + +Using the @code{.} operator makes @value{GDBN} search the current scope for +the identifier specified by @var{id} that was imported from the +definition module specified by @var{module}. With this operator, it is +an error if the identifier @var{id} was not imported from definition +module @var{module}, or if @var{id} is not an identifier in +@var{module}. + +@node GDB/M2 +@subsubsection @value{GDBN} and Modula-2 + +Some @value{GDBN} commands have little use when debugging Modula-2 programs. +Five subcommands of @code{set print} and @code{show print} apply +specifically to C and C@t{++}: @samp{vtbl}, @samp{demangle}, +@samp{asm-demangle}, @samp{object}, and @samp{union}. The first four +apply to C@t{++}, and the last to the C @code{union} type, which has no direct +analogue in Modula-2. + +The @code{@@} operator (@pxref{Expressions, ,Expressions}), while available +with any language, is not useful with Modula-2. Its +intent is to aid the debugging of @dfn{dynamic arrays}, which cannot be +created in Modula-2 as they can in C or C@t{++}. However, because an +address can be specified by an integral constant, the construct +@samp{@{@var{type}@}@var{adrexp}} is still useful. + +@cindex @code{#} in Modula-2 +In @value{GDBN} scripts, the Modula-2 inequality operator @code{#} is +interpreted as the beginning of a comment. Use @code{<>} instead. + +@node Ada +@subsection Ada +@cindex Ada + +The extensions made to @value{GDBN} for Ada only support +output from the @sc{gnu} Ada (GNAT) compiler. +Other Ada compilers are not currently supported, and +attempting to debug executables produced by them is most likely +to be difficult. + + +@cindex expressions in Ada +@menu +* Ada Mode Intro:: General remarks on the Ada syntax + and semantics supported by Ada mode + in @value{GDBN}. +* Omissions from Ada:: Restrictions on the Ada expression syntax. +* Additions to Ada:: Extensions of the Ada expression syntax. +* Overloading support for Ada:: Support for expressions involving overloaded + subprograms. +* Stopping Before Main Program:: Debugging the program during elaboration. +* Ada Exceptions:: Ada Exceptions +* Ada Tasks:: Listing and setting breakpoints in tasks. +* Ada Tasks and Core Files:: Tasking Support when Debugging Core Files +* Ravenscar Profile:: Tasking Support when using the Ravenscar + Profile +* Ada Source Character Set:: Character set of Ada source files. +* Ada Glitches:: Known peculiarities of Ada mode. +@end menu + +@node Ada Mode Intro +@subsubsection Introduction +@cindex Ada mode, general + +The Ada mode of @value{GDBN} supports a fairly large subset of Ada expression +syntax, with some extensions. +The philosophy behind the design of this subset is + +@itemize @bullet +@item +That @value{GDBN} should provide basic literals and access to operations for +arithmetic, dereferencing, field selection, indexing, and subprogram calls, +leaving more sophisticated computations to subprograms written into the +program (which therefore may be called from @value{GDBN}). + +@item +That type safety and strict adherence to Ada language restrictions +are not particularly important to the @value{GDBN} user. + +@item +That brevity is important to the @value{GDBN} user. +@end itemize + +Thus, for brevity, the debugger acts as if all names declared in +user-written packages are directly visible, even if they are not visible +according to Ada rules, thus making it unnecessary to fully qualify most +names with their packages, regardless of context. Where this causes +ambiguity, @value{GDBN} asks the user's intent. + +The debugger will start in Ada mode if it detects an Ada main program. +As for other languages, it will enter Ada mode when stopped in a program that +was translated from an Ada source file. + +While in Ada mode, you may use `@t{--}' for comments. This is useful +mostly for documenting command files. The standard @value{GDBN} comment +(@samp{#}) still works at the beginning of a line in Ada mode, but not in the +middle (to allow based literals). + +@node Omissions from Ada +@subsubsection Omissions from Ada +@cindex Ada, omissions from + +Here are the notable omissions from the subset: + +@itemize @bullet +@item +Only a subset of the attributes are supported: + +@itemize @minus +@item +@t{'First}, @t{'Last}, and @t{'Length} + on array objects (not on types and subtypes). + +@item +@t{'Min} and @t{'Max}. + +@item +@t{'Pos} and @t{'Val}. + +@item +@t{'Tag}. + +@item +@t{'Range} on array objects (not subtypes), but only as the right +operand of the membership (@code{in}) operator. + +@item +@t{'Access}, @t{'Unchecked_Access}, and +@t{'Unrestricted_Access} (a GNAT extension). + +@item +@t{'Address}. + +@item +@t{'Size} is available for objects (not types). + +@item +@t{'Object_Size} is available, but not for indefinite types. +@end itemize + +@item +The names in @code{Characters.Latin_1} are not available. + +@item +Equality tests (@samp{=} and @samp{/=}) on arrays test for bitwise +equality of representations. They will generally work correctly +for strings and arrays whose elements have integer or enumeration types. +They may not work correctly for arrays whose element +types have user-defined equality, for arrays of real values +(in particular, IEEE-conformant floating point, because of negative +zeroes and NaNs), and for arrays whose elements contain unused bits with +indeterminate values. + +@item +The other component-by-component array operations (@code{and}, @code{or}, +@code{xor}, @code{not}, and relational tests other than equality) +are not implemented. + +@item +@cindex array aggregates (Ada) +@cindex record aggregates (Ada) +@cindex aggregates (Ada) +There is limited support for array and record aggregates. They are +permitted only on the right sides of assignments, as in these examples: + +@smallexample +(@value{GDBP}) set An_Array := (1, 2, 3, 4, 5, 6) +(@value{GDBP}) set An_Array := (1, others => 0) +(@value{GDBP}) set An_Array := (0|4 => 1, 1..3 => 2, 5 => 6) +(@value{GDBP}) set A_2D_Array := ((1, 2, 3), (4, 5, 6), (7, 8, 9)) +(@value{GDBP}) set A_Record := (1, "Peter", True); +(@value{GDBP}) set A_Record := (Name => "Peter", Id => 1, Alive => True) +@end smallexample + +Changing a +discriminant's value by assigning an aggregate has an +undefined effect if that discriminant is used within the record. +However, you can first modify discriminants by directly assigning to +them (which normally would not be allowed in Ada), and then performing an +aggregate assignment. For example, given a variable @code{A_Rec} +declared to have a type such as: + +@smallexample +type Rec (Len : Small_Integer := 0) is record + Id : Integer; + Vals : IntArray (1 .. Len); +end record; +@end smallexample + +you can assign a value with a different size of @code{Vals} with two +assignments: + +@smallexample +(@value{GDBP}) set A_Rec.Len := 4 +(@value{GDBP}) set A_Rec := (Id => 42, Vals => (1, 2, 3, 4)) +@end smallexample + +As this example also illustrates, @value{GDBN} is very loose about the usual +rules concerning aggregates. You may leave out some of the +components of an array or record aggregate (such as the @code{Len} +component in the assignment to @code{A_Rec} above); they will retain their +original values upon assignment. You may freely use dynamic values as +indices in component associations. You may even use overlapping or +redundant component associations, although which component values are +assigned in such cases is not defined. + +@item +Calls to dispatching subprograms are not implemented. + +@item +The overloading algorithm is much more limited (i.e., less selective) +than that of real Ada. It makes only limited use of the context in +which a subexpression appears to resolve its meaning, and it is much +looser in its rules for allowing type matches. As a result, some +function calls will be ambiguous, and the user will be asked to choose +the proper resolution. + +@item +The @code{new} operator is not implemented. + +@item +Entry calls are not implemented. + +@item +Aside from printing, arithmetic operations on the native VAX floating-point +formats are not supported. + +@item +It is not possible to slice a packed array. + +@item +The names @code{True} and @code{False}, when not part of a qualified name, +are interpreted as if implicitly prefixed by @code{Standard}, regardless of +context. +Should your program +redefine these names in a package or procedure (at best a dubious practice), +you will have to use fully qualified names to access their new definitions. + +@item +Based real literals are not implemented. +@end itemize + +@node Additions to Ada +@subsubsection Additions to Ada +@cindex Ada, deviations from + +As it does for other languages, @value{GDBN} makes certain generic +extensions to Ada (@pxref{Expressions}): + +@itemize @bullet +@item +If the expression @var{E} is a variable residing in memory (typically +a local variable or array element) and @var{N} is a positive integer, +then @code{@var{E}@@@var{N}} displays the values of @var{E} and the +@var{N}-1 adjacent variables following it in memory as an array. In +Ada, this operator is generally not necessary, since its prime use is +in displaying parts of an array, and slicing will usually do this in +Ada. However, there are occasional uses when debugging programs in +which certain debugging information has been optimized away. + +@item +@code{@var{B}::@var{var}} means ``the variable named @var{var} that +appears in function or file @var{B}.'' When @var{B} is a file name, +you must typically surround it in single quotes. + +@item +The expression @code{@{@var{type}@} @var{addr}} means ``the variable of type +@var{type} that appears at address @var{addr}.'' + +@item +A name starting with @samp{$} is a convenience variable +(@pxref{Convenience Vars}) or a machine register (@pxref{Registers}). +@end itemize + +In addition, @value{GDBN} provides a few other shortcuts and outright +additions specific to Ada: + +@itemize @bullet +@item +The assignment statement is allowed as an expression, returning +its right-hand operand as its value. Thus, you may enter + +@smallexample +(@value{GDBP}) set x := y + 3 +(@value{GDBP}) print A(tmp := y + 1) +@end smallexample + +@item +The semicolon is allowed as an ``operator,'' returning as its value +the value of its right-hand operand. +This allows, for example, +complex conditional breaks: + +@smallexample +(@value{GDBP}) break f +(@value{GDBP}) condition 1 (report(i); k += 1; A(k) > 100) +@end smallexample + +@item +An extension to based literals can be used to specify the exact byte +contents of a floating-point literal. After the base, you can use +from zero to two @samp{l} characters, followed by an @samp{f}. The +number of @samp{l} characters controls the width of the resulting real +constant: zero means @code{Float} is used, one means +@code{Long_Float}, and two means @code{Long_Long_Float}. + +@smallexample +(@value{GDBP}) print 16f#41b80000# +$1 = 23.0 +@end smallexample + +@item +Rather than use catenation and symbolic character names to introduce special +characters into strings, one may instead use a special bracket notation, +which is also used to print strings. A sequence of characters of the form +@samp{["@var{XX}"]} within a string or character literal denotes the +(single) character whose numeric encoding is @var{XX} in hexadecimal. The +sequence of characters @samp{["""]} also denotes a single quotation mark +in strings. For example, +@smallexample + "One line.["0a"]Next line.["0a"]" +@end smallexample +@noindent +contains an ASCII newline character (@code{Ada.Characters.Latin_1.LF}) +after each period. + +@item +The subtype used as a prefix for the attributes @t{'Pos}, @t{'Min}, and +@t{'Max} is optional (and is ignored in any case). For example, it is valid +to write + +@smallexample +(@value{GDBP}) print 'max(x, y) +@end smallexample + +@item +When printing arrays, @value{GDBN} uses positional notation when the +array has a lower bound of 1, and uses a modified named notation otherwise. +For example, a one-dimensional array of three integers with a lower bound +of 3 might print as + +@smallexample +(3 => 10, 17, 1) +@end smallexample + +@noindent +That is, in contrast to valid Ada, only the first component has a @code{=>} +clause. + +@item +You may abbreviate attributes in expressions with any unique, +multi-character subsequence of +their names (an exact match gets preference). +For example, you may use @t{a'len}, @t{a'gth}, or @t{a'lh} +in place of @t{a'length}. + +@item +@cindex quoting Ada internal identifiers +Since Ada is case-insensitive, the debugger normally maps identifiers you type +to lower case. The GNAT compiler uses upper-case characters for +some of its internal identifiers, which are normally of no interest to users. +For the rare occasions when you actually have to look at them, +enclose them in angle brackets to avoid the lower-case mapping. +For example, +@smallexample +(@value{GDBP}) print [0] +@end smallexample + +@item +Printing an object of class-wide type or dereferencing an +access-to-class-wide value will display all the components of the object's +specific type (as indicated by its run-time tag). Likewise, component +selection on such a value will operate on the specific type of the +object. + +@end itemize + +@node Overloading support for Ada +@subsubsection Overloading support for Ada +@cindex overloading, Ada + +The debugger supports limited overloading. Given a subprogram call in which +the function symbol has multiple definitions, it will use the number of +actual parameters and some information about their types to attempt to narrow +the set of definitions. It also makes very limited use of context, preferring +procedures to functions in the context of the @code{call} command, and +functions to procedures elsewhere. + +If, after narrowing, the set of matching definitions still contains more than +one definition, @value{GDBN} will display a menu to query which one it should +use, for instance: + +@smallexample +(@value{GDBP}) print f(1) +Multiple matches for f +[0] cancel +[1] foo.f (integer) return boolean at foo.adb:23 +[2] foo.f (foo.new_integer) return boolean at foo.adb:28 +> +@end smallexample + +In this case, just select one menu entry either to cancel expression evaluation +(type @kbd{0} and press @key{RET}) or to continue evaluation with a specific +instance (type the corresponding number and press @key{RET}). + +Here are a couple of commands to customize @value{GDBN}'s behavior in this +case: + +@table @code + +@kindex set ada print-signatures +@item set ada print-signatures +Control whether parameter types and return types are displayed in overloads +selection menus. It is @code{on} by default. +@xref{Overloading support for Ada}. + +@kindex show ada print-signatures +@item show ada print-signatures +Show the current setting for displaying parameter types and return types in +overloads selection menu. +@xref{Overloading support for Ada}. + +@end table + +@node Stopping Before Main Program +@subsubsection Stopping at the Very Beginning + +@cindex breakpointing Ada elaboration code +It is sometimes necessary to debug the program during elaboration, and +before reaching the main procedure. +As defined in the Ada Reference +Manual, the elaboration code is invoked from a procedure called +@code{adainit}. To run your program up to the beginning of +elaboration, simply use the following two commands: +@code{tbreak adainit} and @code{run}. + +@node Ada Exceptions +@subsubsection Ada Exceptions + +A command is provided to list all Ada exceptions: + +@table @code +@kindex info exceptions +@item info exceptions +@itemx info exceptions @var{regexp} +The @code{info exceptions} command allows you to list all Ada exceptions +defined within the program being debugged, as well as their addresses. +With a regular expression, @var{regexp}, as argument, only those exceptions +whose names match @var{regexp} are listed. +@end table + +Below is a small example, showing how the command can be used, first +without argument, and next with a regular expression passed as an +argument. + +@smallexample +(@value{GDBP}) info exceptions +All defined Ada exceptions: +constraint_error: 0x613da0 +program_error: 0x613d20 +storage_error: 0x613ce0 +tasking_error: 0x613ca0 +const.aint_global_e: 0x613b00 +(@value{GDBP}) info exceptions const.aint +All Ada exceptions matching regular expression "const.aint": +constraint_error: 0x613da0 +const.aint_global_e: 0x613b00 +@end smallexample + +It is also possible to ask @value{GDBN} to stop your program's execution +when an exception is raised. For more details, see @ref{Set Catchpoints}. + +@node Ada Tasks +@subsubsection Extensions for Ada Tasks +@cindex Ada, tasking + +Support for Ada tasks is analogous to that for threads (@pxref{Threads}). +@value{GDBN} provides the following task-related commands: + +@table @code +@kindex info tasks +@item info tasks +This command shows a list of current Ada tasks, as in the following example: + + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8088000 0 15 Child Activation Wait main_task + 2 80a4000 1 15 Accept Statement b + 3 809a800 1 15 Child Activation Wait a +* 4 80ae800 3 15 Runnable c + +@end smallexample + +@noindent +In this listing, the asterisk before the last task indicates it to be the +task currently being inspected. + +@table @asis +@item ID +Represents @value{GDBN}'s internal task number. + +@item TID +The Ada task ID. + +@item P-ID +The parent's task ID (@value{GDBN}'s internal task number). + +@item Pri +The base priority of the task. + +@item State +Current state of the task. + +@table @code +@item Unactivated +The task has been created but has not been activated. It cannot be +executing. + +@item Runnable +The task is not blocked for any reason known to Ada. (It may be waiting +for a mutex, though.) It is conceptually "executing" in normal mode. + +@item Terminated +The task is terminated, in the sense of ARM 9.3 (5). Any dependents +that were waiting on terminate alternatives have been awakened and have +terminated themselves. + +@item Child Activation Wait +The task is waiting for created tasks to complete activation. + +@item Accept or Select Term +The task is waiting on an accept or selective wait statement. + +@item Waiting on entry call +The task is waiting on an entry call. + +@item Async Select Wait +The task is waiting to start the abortable part of an asynchronous +select statement. + +@item Delay Sleep +The task is waiting on a select statement with only a delay +alternative open. + +@item Child Termination Wait +The task is sleeping having completed a master within itself, and is +waiting for the tasks dependent on that master to become terminated or +waiting on a terminate Phase. + +@item Wait Child in Term Alt +The task is sleeping waiting for tasks on terminate alternatives to +finish terminating. + +@item Asynchronous Hold +The task has been held by @code{Ada.Asynchronous_Task_Control.Hold_Task}. + +@item Activating +The task has been created and is being made runnable. + +@item Selective Wait +The task is waiting in a selective wait statement. + +@item Accepting RV with @var{taskno} +The task is accepting a rendez-vous with the task @var{taskno}. + +@item Waiting on RV with @var{taskno} +The task is waiting for a rendez-vous with the task @var{taskno}. +@end table + +@item Name +Name of the task in the program. + +@end table + +@kindex info task @var{taskno} +@item info task @var{taskno} +This command shows detailed information on the specified task, as in +the following example: +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077880 0 15 Child Activation Wait main_task +* 2 807c468 1 15 Runnable task_1 +(@value{GDBP}) info task 2 +Ada Task: 0x807c468 +Name: "task_1" +Thread: 0 +LWP: 0x1fac +Parent: 1 ("main_task") +Base Priority: 15 +State: Runnable +@end smallexample + +@item task +@kindex task@r{ (Ada)} +@cindex current Ada task ID +This command prints the ID and name of the current task. + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task +* 2 807c458 1 15 Runnable some_task +(@value{GDBP}) task +[Current task is 2 "some_task"] +@end smallexample + +@item task @var{taskno} +@cindex Ada task switching +This command is like the @code{thread @var{thread-id}} +command (@pxref{Threads}). It switches the context of debugging +from the current task to the given task. + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 8077870 0 15 Child Activation Wait main_task +* 2 807c458 1 15 Runnable some_task +(@value{GDBP}) task 1 +[Switching to task 1 "main_task"] +#0 0x8067726 in pthread_cond_wait () +(@value{GDBP}) bt +#0 0x8067726 in pthread_cond_wait () +#1 0x8056714 in system.os_interface.pthread_cond_wait () +#2 0x805cb63 in system.task_primitives.operations.sleep () +#3 0x806153e in system.tasking.stages.activate_tasks () +#4 0x804aacc in un () at un.adb:5 +@end smallexample + +@item task apply [@var{task-id-list} | all] [@var{flag}]@dots{} @var{command} +The @code{task apply} command is the Ada tasking analogue of +@code{thread apply} (@pxref{Threads}). It allows you to apply the +named @var{command} to one or more tasks. Specify the tasks that you +want affected using a list of task IDs, or specify @code{all} to apply +to all tasks. + +The @var{flag} arguments control what output to produce and how to +handle errors raised when applying @var{command} to a task. +@var{flag} must start with a @code{-} directly followed by one letter +in @code{qcs}. If several flags are provided, they must be given +individually, such as @code{-c -q}. + +By default, @value{GDBN} displays some task information before the +output produced by @var{command}, and an error raised during the +execution of a @var{command} will abort @code{task apply}. The +following flags can be used to fine-tune this behavior: + +@table @code +@item -c +The flag @code{-c}, which stands for @samp{continue}, causes any +errors in @var{command} to be displayed, and the execution of +@code{task apply} then continues. +@item -s +The flag @code{-s}, which stands for @samp{silent}, causes any errors +or empty output produced by a @var{command} to be silently ignored. +That is, the execution continues, but the task information and errors +are not printed. +@item -q +The flag @code{-q} (@samp{quiet}) disables printing the task +information. +@end table + +Flags @code{-c} and @code{-s} cannot be used together. + +@item break @var{locspec} task @var{taskno} +@itemx break @var{locspec} task @var{taskno} if @dots{} +@cindex breakpoints and tasks, in Ada +@cindex task breakpoints, in Ada +@kindex break @dots{} task @var{taskno}@r{ (Ada)} +These commands are like the @code{break @dots{} thread @dots{}} +command (@pxref{Thread Stops}). @xref{Location Specifications}, for +the various forms of @var{locspec}. + +Use the qualifier @samp{task @var{taskno}} with a breakpoint command +to specify that you only want @value{GDBN} to stop the program when a +particular Ada task reaches this breakpoint. The @var{taskno} is one of the +numeric task identifiers assigned by @value{GDBN}, shown in the first +column of the @samp{info tasks} display. + +If you do not specify @samp{task @var{taskno}} when you set a +breakpoint, the breakpoint applies to @emph{all} tasks of your +program. + +You can use the @code{task} qualifier on conditional breakpoints as +well; in this case, place @samp{task @var{taskno}} before the +breakpoint condition (before the @code{if}). + +For example, + +@smallexample +@iftex +@leftskip=0.5cm +@end iftex +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task + 2 140045060 1 15 Accept/Select Wait t2 + 3 140044840 1 15 Runnable t1 +* 4 140056040 1 15 Runnable t3 +(@value{GDBP}) b 15 task 2 +Breakpoint 5 at 0x120044cb0: file test_task_debug.adb, line 15. +(@value{GDBP}) cont +Continuing. +task # 1 running +task # 2 running + +Breakpoint 5, test_task_debug () at test_task_debug.adb:15 +15 flush; +(@value{GDBP}) info tasks + ID TID P-ID Pri State Name + 1 140022020 0 15 Child Activation Wait main_task +* 2 140045060 1 15 Runnable t2 + 3 140044840 1 15 Runnable t1 + 4 140056040 1 15 Delay Sleep t3 +@end smallexample +@end table + +@node Ada Tasks and Core Files +@subsubsection Tasking Support when Debugging Core Files +@cindex Ada tasking and core file debugging + +When inspecting a core file, as opposed to debugging a live program, +tasking support may be limited or even unavailable, depending on +the platform being used. +For instance, on x86-linux, the list of tasks is available, but task +switching is not supported. + +On certain platforms, the debugger needs to perform some +memory writes in order to provide Ada tasking support. When inspecting +a core file, this means that the core file must be opened with read-write +privileges, using the command @samp{"set write on"} (@pxref{Patching}). +Under these circumstances, you should make a backup copy of the core +file before inspecting it with @value{GDBN}. + +@node Ravenscar Profile +@subsubsection Tasking Support when using the Ravenscar Profile +@cindex Ravenscar Profile + +The @dfn{Ravenscar Profile} is a subset of the Ada tasking features, +specifically designed for systems with safety-critical real-time +requirements. + +@table @code +@kindex set ravenscar task-switching on +@cindex task switching with program using Ravenscar Profile +@item set ravenscar task-switching on +Allows task switching when debugging a program that uses the Ravenscar +Profile. This is the default. + +@kindex set ravenscar task-switching off +@item set ravenscar task-switching off +Turn off task switching when debugging a program that uses the Ravenscar +Profile. This is mostly intended to disable the code that adds support +for the Ravenscar Profile, in case a bug in either @value{GDBN} or in +the Ravenscar runtime is preventing @value{GDBN} from working properly. +To be effective, this command should be run before the program is started. + +@kindex show ravenscar task-switching +@item show ravenscar task-switching +Show whether it is possible to switch from task to task in a program +using the Ravenscar Profile. + +@end table + +@cindex Ravenscar thread +When Ravenscar task-switching is enabled, Ravenscar tasks are +announced by @value{GDBN} as if they were threads: + +@smallexample +(gdb) continue +[New Ravenscar Thread 0x2b8f0] +@end smallexample + +Both Ravenscar tasks and the underlying CPU threads will show up in +the output of @code{info threads}: + +@smallexample +(gdb) info threads + Id Target Id Frame + 1 Thread 1 (CPU#0 [running]) simple () at simple.adb:10 + 2 Thread 2 (CPU#1 [running]) 0x0000000000003d34 in __gnat_initialize_cpu_devices () + 3 Thread 3 (CPU#2 [running]) 0x0000000000003d28 in __gnat_initialize_cpu_devices () + 4 Thread 4 (CPU#3 [halted ]) 0x000000000000c6ec in system.task_primitives.operations.idle () +* 5 Ravenscar Thread 0x2b8f0 simple () at simple.adb:10 + 6 Ravenscar Thread 0x2f150 0x000000000000c6ec in system.task_primitives.operations.idle () +@end smallexample + +One known limitation of the Ravenscar support in @value{GDBN} is that +it isn't currently possible to single-step through the runtime +initialization sequence. If you need to debug this code, you should +use @code{set ravenscar task-switching off}. + +@node Ada Source Character Set +@subsubsection Ada Source Character Set +@cindex Ada, source character set + +The GNAT compiler supports a number of character sets for source +files. @xref{Character Set Control, , Character Set Control, +gnat_ugn}. @value{GDBN} includes support for this as well. + +@table @code +@item set ada source-charset @var{charset} +@kindex set ada source-charset +Set the source character set for Ada. The character set must be +supported by GNAT. Because this setting affects the decoding of +symbols coming from the debug information in your program, the setting +should be set as early as possible. The default is @code{ISO-8859-1}, +because that is also GNAT's default. + +@item show ada source-charset +@kindex show ada source-charset +Show the current source character set for Ada. +@end table + +@node Ada Glitches +@subsubsection Known Peculiarities of Ada Mode +@cindex Ada, problems + +Besides the omissions listed previously (@pxref{Omissions from Ada}), +we know of several problems with and limitations of Ada mode in +@value{GDBN}, +some of which will be fixed with planned future releases of the debugger +and the GNU Ada compiler. + +@itemize @bullet +@item +Static constants that the compiler chooses not to materialize as objects in +storage are invisible to the debugger. + +@item +Named parameter associations in function argument lists are ignored (the +argument lists are treated as positional). + +@item +Many useful library packages are currently invisible to the debugger. + +@item +Fixed-point arithmetic, conversions, input, and output is carried out using +floating-point arithmetic, and may give results that only approximate those on +the host machine. + +@item +The GNAT compiler never generates the prefix @code{Standard} for any of +the standard symbols defined by the Ada language. @value{GDBN} knows about +this: it will strip the prefix from names when you use it, and will never +look for a name you have so qualified among local symbols, nor match against +symbols in other packages or subprograms. If you have +defined entities anywhere in your program other than parameters and +local variables whose simple names match names in @code{Standard}, +GNAT's lack of qualification here can cause confusion. When this happens, +you can usually resolve the confusion +by qualifying the problematic names with package +@code{Standard} explicitly. +@end itemize + +Older versions of the compiler sometimes generate erroneous debugging +information, resulting in the debugger incorrectly printing the value +of affected entities. In some cases, the debugger is able to work +around an issue automatically. In other cases, the debugger is able +to work around the issue, but the work-around has to be specifically +enabled. + +@kindex set ada trust-PAD-over-XVS +@kindex show ada trust-PAD-over-XVS +@table @code + +@item set ada trust-PAD-over-XVS on +Configure GDB to strictly follow the GNAT encoding when computing the +value of Ada entities, particularly when @code{PAD} and @code{PAD___XVS} +types are involved (see @code{ada/exp_dbug.ads} in the GCC sources for +a complete description of the encoding used by the GNAT compiler). +This is the default. + +@item set ada trust-PAD-over-XVS off +This is related to the encoding using by the GNAT compiler. If @value{GDBN} +sometimes prints the wrong value for certain entities, changing @code{ada +trust-PAD-over-XVS} to @code{off} activates a work-around which may fix +the issue. It is always safe to set @code{ada trust-PAD-over-XVS} to +@code{off}, but this incurs a slight performance penalty, so it is +recommended to leave this setting to @code{on} unless necessary. + +@end table + +@cindex GNAT descriptive types +@cindex GNAT encoding +Internally, the debugger also relies on the compiler following a number +of conventions known as the @samp{GNAT Encoding}, all documented in +@file{gcc/ada/exp_dbug.ads} in the GCC sources. This encoding describes +how the debugging information should be generated for certain types. +In particular, this convention makes use of @dfn{descriptive types}, +which are artificial types generated purely to help the debugger. + +These encodings were defined at a time when the debugging information +format used was not powerful enough to describe some of the more complex +types available in Ada. Since DWARF allows us to express nearly all +Ada features, the long-term goal is to slowly replace these descriptive +types by their pure DWARF equivalent. To facilitate that transition, +a new maintenance option is available to force the debugger to ignore +those descriptive types. It allows the user to quickly evaluate how +well @value{GDBN} works without them. + +@table @code + +@kindex maint ada set ignore-descriptive-types +@item maintenance ada set ignore-descriptive-types [on|off] +Control whether the debugger should ignore descriptive types. +The default is not to ignore descriptives types (@code{off}). + +@kindex maint ada show ignore-descriptive-types +@item maintenance ada show ignore-descriptive-types +Show if descriptive types are ignored by @value{GDBN}. + +@end table + +@node Unsupported Languages +@section Unsupported Languages + +@cindex unsupported languages +@cindex minimal language +In addition to the other fully-supported programming languages, +@value{GDBN} also provides a pseudo-language, called @code{minimal}. +It does not represent a real programming language, but provides a set +of capabilities close to what the C or assembly languages provide. +This should allow most simple operations to be performed while debugging +an application that uses a language currently not supported by @value{GDBN}. + +If the language is set to @code{auto}, @value{GDBN} will automatically +select this language if the current frame corresponds to an unsupported +language. + +@node Symbols +@chapter Examining the Symbol Table + +The commands described in this chapter allow you to inquire about the +symbols (names of variables, functions and types) defined in your +program. This information is inherent in the text of your program and +does not change as your program executes. @value{GDBN} finds it in your +program's symbol table, in the file indicated when you started @value{GDBN} +(@pxref{File Options, ,Choosing Files}), or by one of the +file-management commands (@pxref{Files, ,Commands to Specify Files}). + +@cindex symbol names +@cindex names of symbols +@cindex quoting names +@anchor{quoting names} +Occasionally, you may need to refer to symbols that contain unusual +characters, which @value{GDBN} ordinarily treats as word delimiters. The +most frequent case is in referring to static variables in other +source files (@pxref{Variables,,Program Variables}). File names +are recorded in object files as debugging symbols, but @value{GDBN} would +ordinarily parse a typical file name, like @file{foo.c}, as the three words +@samp{foo} @samp{.} @samp{c}. To allow @value{GDBN} to recognize +@samp{foo.c} as a single symbol, enclose it in single quotes; for example, + +@smallexample +p 'foo.c'::x +@end smallexample + +@noindent +looks up the value of @code{x} in the scope of the file @file{foo.c}. + +@table @code +@cindex case-insensitive symbol names +@cindex case sensitivity in symbol names +@kindex set case-sensitive +@item set case-sensitive on +@itemx set case-sensitive off +@itemx set case-sensitive auto +Normally, when @value{GDBN} looks up symbols, it matches their names +with case sensitivity determined by the current source language. +Occasionally, you may wish to control that. The command @code{set +case-sensitive} lets you do that by specifying @code{on} for +case-sensitive matches or @code{off} for case-insensitive ones. If +you specify @code{auto}, case sensitivity is reset to the default +suitable for the source language. The default is case-sensitive +matches for all languages except for Fortran, for which the default is +case-insensitive matches. + +@kindex show case-sensitive +@item show case-sensitive +This command shows the current setting of case sensitivity for symbols +lookups. + +@kindex set print type methods +@item set print type methods +@itemx set print type methods on +@itemx set print type methods off +Normally, when @value{GDBN} prints a class, it displays any methods +declared in that class. You can control this behavior either by +passing the appropriate flag to @code{ptype}, or using @command{set +print type methods}. Specifying @code{on} will cause @value{GDBN} to +display the methods; this is the default. Specifying @code{off} will +cause @value{GDBN} to omit the methods. + +@kindex show print type methods +@item show print type methods +This command shows the current setting of method display when printing +classes. + +@kindex set print type nested-type-limit +@item set print type nested-type-limit @var{limit} +@itemx set print type nested-type-limit unlimited +Set the limit of displayed nested types that the type printer will +show. A @var{limit} of @code{unlimited} or @code{-1} will show all +nested definitions. By default, the type printer will not show any nested +types defined in classes. + +@kindex show print type nested-type-limit +@item show print type nested-type-limit +This command shows the current display limit of nested types when +printing classes. + +@kindex set print type typedefs +@item set print type typedefs +@itemx set print type typedefs on +@itemx set print type typedefs off + +Normally, when @value{GDBN} prints a class, it displays any typedefs +defined in that class. You can control this behavior either by +passing the appropriate flag to @code{ptype}, or using @command{set +print type typedefs}. Specifying @code{on} will cause @value{GDBN} to +display the typedef definitions; this is the default. Specifying +@code{off} will cause @value{GDBN} to omit the typedef definitions. +Note that this controls whether the typedef definition itself is +printed, not whether typedef names are substituted when printing other +types. + +@kindex show print type typedefs +@item show print type typedefs +This command shows the current setting of typedef display when +printing classes. + +@kindex set print type hex +@item set print type hex +@itemx set print type hex on +@itemx set print type hex off + +When @value{GDBN} prints sizes and offsets of struct members, it can use +either the decimal or hexadecimal notation. You can select one or the +other either by passing the appropriate flag to @code{ptype}, or by using +the @command{set print type hex} command. + +@kindex show print type hex +@item show print type hex +This command shows whether the sizes and offsets of struct members are +printed in decimal or hexadecimal notation. + +@kindex info address +@cindex address of a symbol +@item info address @var{symbol} +Describe where the data for @var{symbol} is stored. For a register +variable, this says which register it is kept in. For a non-register +local variable, this prints the stack-frame offset at which the variable +is always stored. + +Note the contrast with @samp{print &@var{symbol}}, which does not work +at all for a register variable, and for a stack local variable prints +the exact address of the current instantiation of the variable. + +@kindex info symbol +@cindex symbol from address +@cindex closest symbol and offset for an address +@item info symbol @var{addr} +Print the name of a symbol which is stored at the address @var{addr}. +If no symbol is stored exactly at @var{addr}, @value{GDBN} prints the +nearest symbol and an offset from it: + +@smallexample +(@value{GDBP}) info symbol 0x54320 +_initialize_vx + 396 in section .text +@end smallexample + +@noindent +This is the opposite of the @code{info address} command. You can use +it to find out the name of a variable or a function given its address. + +For dynamically linked executables, the name of executable or shared +library containing the symbol is also printed: + +@smallexample +(@value{GDBP}) info symbol 0x400225 +_start + 5 in section .text of /tmp/a.out +(@value{GDBP}) info symbol 0x2aaaac2811cf +__read_nocancel + 6 in section .text of /usr/lib64/libc.so.6 +@end smallexample + +@kindex demangle +@cindex demangle +@item demangle @r{[}-l @var{language}@r{]} @r{[}@var{--}@r{]} @var{name} +Demangle @var{name}. +If @var{language} is provided it is the name of the language to demangle +@var{name} in. Otherwise @var{name} is demangled in the current language. + +The @samp{--} option specifies the end of options, +and is useful when @var{name} begins with a dash. + +The parameter @code{demangle-style} specifies how to interpret the kind +of mangling used. @xref{Print Settings}. + +@kindex whatis +@item whatis[/@var{flags}] [@var{arg}] +Print the data type of @var{arg}, which can be either an expression +or a name of a data type. With no argument, print the data type of +@code{$}, the last value in the value history. + +If @var{arg} is an expression (@pxref{Expressions, ,Expressions}), it +is not actually evaluated, and any side-effecting operations (such as +assignments or function calls) inside it do not take place. + +If @var{arg} is a variable or an expression, @code{whatis} prints its +literal type as it is used in the source code. If the type was +defined using a @code{typedef}, @code{whatis} will @emph{not} print +the data type underlying the @code{typedef}. If the type of the +variable or the expression is a compound data type, such as +@code{struct} or @code{class}, @code{whatis} never prints their +fields or methods. It just prints the @code{struct}/@code{class} +name (a.k.a.@: its @dfn{tag}). If you want to see the members of +such a compound data type, use @code{ptype}. + +If @var{arg} is a type name that was defined using @code{typedef}, +@code{whatis} @dfn{unrolls} only one level of that @code{typedef}. +Unrolling means that @code{whatis} will show the underlying type used +in the @code{typedef} declaration of @var{arg}. However, if that +underlying type is also a @code{typedef}, @code{whatis} will not +unroll it. + +For C code, the type names may also have the form @samp{class +@var{class-name}}, @samp{struct @var{struct-tag}}, @samp{union +@var{union-tag}} or @samp{enum @var{enum-tag}}. + +@var{flags} can be used to modify how the type is displayed. +Available flags are: + +@table @code +@item r +Display in ``raw'' form. Normally, @value{GDBN} substitutes template +parameters and typedefs defined in a class when printing the class' +members. The @code{/r} flag disables this. + +@item m +Do not print methods defined in the class. + +@item M +Print methods defined in the class. This is the default, but the flag +exists in case you change the default with @command{set print type methods}. + +@item t +Do not print typedefs defined in the class. Note that this controls +whether the typedef definition itself is printed, not whether typedef +names are substituted when printing other types. + +@item T +Print typedefs defined in the class. This is the default, but the flag +exists in case you change the default with @command{set print type typedefs}. + +@item o +Print the offsets and sizes of fields in a struct, similar to what the +@command{pahole} tool does. This option implies the @code{/tm} flags. + +@item x +Use hexadecimal notation when printing offsets and sizes of fields in a +struct. + +@item d +Use decimal notation when printing offsets and sizes of fields in a +struct. + +For example, given the following declarations: + +@smallexample +struct tuv +@{ + int a1; + char *a2; + int a3; +@}; + +struct xyz +@{ + int f1; + char f2; + void *f3; + struct tuv f4; +@}; + +union qwe +@{ + struct tuv fff1; + struct xyz fff2; +@}; + +struct tyu +@{ + int a1 : 1; + int a2 : 3; + int a3 : 23; + char a4 : 2; + int64_t a5; + int a6 : 5; + int64_t a7 : 3; +@}; +@end smallexample + +Issuing a @kbd{ptype /o struct tuv} command would print: + +@smallexample +(@value{GDBP}) ptype /o struct tuv +/* offset | size */ type = struct tuv @{ +/* 0 | 4 */ int a1; +/* XXX 4-byte hole */ +/* 8 | 8 */ char *a2; +/* 16 | 4 */ int a3; + + /* total size (bytes): 24 */ + @} +@end smallexample + +Notice the format of the first column of comments. There, you can +find two parts separated by the @samp{|} character: the @emph{offset}, +which indicates where the field is located inside the struct, in +bytes, and the @emph{size} of the field. Another interesting line is +the marker of a @emph{hole} in the struct, indicating that it may be +possible to pack the struct and make it use less space by reorganizing +its fields. + +It is also possible to print offsets inside an union: + +@smallexample +(@value{GDBP}) ptype /o union qwe +/* offset | size */ type = union qwe @{ +/* 24 */ struct tuv @{ +/* 0 | 4 */ int a1; +/* XXX 4-byte hole */ +/* 8 | 8 */ char *a2; +/* 16 | 4 */ int a3; + + /* total size (bytes): 24 */ + @} fff1; +/* 40 */ struct xyz @{ +/* 0 | 4 */ int f1; +/* 4 | 1 */ char f2; +/* XXX 3-byte hole */ +/* 8 | 8 */ void *f3; +/* 16 | 24 */ struct tuv @{ +/* 16 | 4 */ int a1; +/* XXX 4-byte hole */ +/* 24 | 8 */ char *a2; +/* 32 | 4 */ int a3; + + /* total size (bytes): 24 */ + @} f4; + + /* total size (bytes): 40 */ + @} fff2; + + /* total size (bytes): 40 */ + @} +@end smallexample + +In this case, since @code{struct tuv} and @code{struct xyz} occupy the +same space (because we are dealing with an union), the offset is not +printed for them. However, you can still examine the offset of each +of these structures' fields. + +Another useful scenario is printing the offsets of a struct containing +bitfields: + +@smallexample +(@value{GDBP}) ptype /o struct tyu +/* offset | size */ type = struct tyu @{ +/* 0:31 | 4 */ int a1 : 1; +/* 0:28 | 4 */ int a2 : 3; +/* 0: 5 | 4 */ int a3 : 23; +/* 3: 3 | 1 */ signed char a4 : 2; +/* XXX 3-bit hole */ +/* XXX 4-byte hole */ +/* 8 | 8 */ int64_t a5; +/* 16: 0 | 4 */ int a6 : 5; +/* 16: 5 | 8 */ int64_t a7 : 3; +/* XXX 7-byte padding */ + + /* total size (bytes): 24 */ + @} +@end smallexample + +Note how the offset information is now extended to also include the +first bit of the bitfield. +@end table + +@kindex ptype +@item ptype[/@var{flags}] [@var{arg}] +@code{ptype} accepts the same arguments as @code{whatis}, but prints a +detailed description of the type, instead of just the name of the type. +@xref{Expressions, ,Expressions}. + +Contrary to @code{whatis}, @code{ptype} always unrolls any +@code{typedef}s in its argument declaration, whether the argument is +a variable, expression, or a data type. This means that @code{ptype} +of a variable or an expression will not print literally its type as +present in the source code---use @code{whatis} for that. @code{typedef}s at +the pointer or reference targets are also unrolled. Only @code{typedef}s of +fields, methods and inner @code{class typedef}s of @code{struct}s, +@code{class}es and @code{union}s are not unrolled even with @code{ptype}. + +For example, for this variable declaration: + +@smallexample +typedef double real_t; +struct complex @{ real_t real; double imag; @}; +typedef struct complex complex_t; +complex_t var; +real_t *real_pointer_var; +@end smallexample + +@noindent +the two commands give this output: + +@smallexample +@group +(@value{GDBP}) whatis var +type = complex_t +(@value{GDBP}) ptype var +type = struct complex @{ + real_t real; + double imag; +@} +(@value{GDBP}) whatis complex_t +type = struct complex +(@value{GDBP}) whatis struct complex +type = struct complex +(@value{GDBP}) ptype struct complex +type = struct complex @{ + real_t real; + double imag; +@} +(@value{GDBP}) whatis real_pointer_var +type = real_t * +(@value{GDBP}) ptype real_pointer_var +type = double * +@end group +@end smallexample + +@noindent +As with @code{whatis}, using @code{ptype} without an argument refers to +the type of @code{$}, the last value in the value history. + +@cindex incomplete type +Sometimes, programs use opaque data types or incomplete specifications +of complex data structure. If the debug information included in the +program does not allow @value{GDBN} to display a full declaration of +the data type, it will say @samp{}. For example, +given these declarations: + +@smallexample + struct foo; + struct foo *fooptr; +@end smallexample + +@noindent +but no definition for @code{struct foo} itself, @value{GDBN} will say: + +@smallexample + (@value{GDBP}) ptype foo + $1 = +@end smallexample + +@noindent +``Incomplete type'' is C terminology for data types that are not +completely specified. + +@cindex unknown type +Othertimes, information about a variable's type is completely absent +from the debug information included in the program. This most often +happens when the program or library where the variable is defined +includes no debug information at all. @value{GDBN} knows the variable +exists from inspecting the linker/loader symbol table (e.g., the ELF +dynamic symbol table), but such symbols do not contain type +information. Inspecting the type of a (global) variable for which +@value{GDBN} has no type information shows: + +@smallexample + (@value{GDBP}) ptype var + type = +@end smallexample + +@xref{Variables, no debug info variables}, for how to print the values +of such variables. + +@kindex info types +@item info types [-q] [@var{regexp}] +Print a brief description of all types whose names match the regular +expression @var{regexp} (or all types in your program, if you supply +no argument). Each complete typename is matched as though it were a +complete line; thus, @samp{i type value} gives information on all +types in your program whose names include the string @code{value}, but +@samp{i type ^value$} gives information only on types whose complete +name is @code{value}. + +In programs using different languages, @value{GDBN} chooses the syntax +to print the type description according to the +@samp{set language} value: using @samp{set language auto} +(see @ref{Automatically, ,Set Language Automatically}) means to use the +language of the type, other values mean to use +the manually specified language (see @ref{Manually, ,Set Language Manually}). + +This command differs from @code{ptype} in two ways: first, like +@code{whatis}, it does not print a detailed description; second, it +lists all source files and line numbers where a type is defined. + +The output from @samp{into types} is proceeded with a header line +describing what types are being listed. The optional flag @samp{-q}, +which stands for @samp{quiet}, disables printing this header +information. + +@kindex info type-printers +@item info type-printers +Versions of @value{GDBN} that ship with Python scripting enabled may +have ``type printers'' available. When using @command{ptype} or +@command{whatis}, these printers are consulted when the name of a type +is needed. @xref{Type Printing API}, for more information on writing +type printers. + +@code{info type-printers} displays all the available type printers. + +@kindex enable type-printer +@kindex disable type-printer +@item enable type-printer @var{name}@dots{} +@item disable type-printer @var{name}@dots{} +These commands can be used to enable or disable type printers. + +@kindex info scope +@cindex local variables +@item info scope @var{locspec} +List all the variables local to the lexical scope of the code location +that results from resolving @var{locspec}. @xref{Location +Specifications}, for details about supported forms of @var{locspec}. +For example: + +@smallexample +(@value{GDBP}) @b{info scope command_line_handler} +Scope for command_line_handler: +Symbol rl is an argument at stack/frame offset 8, length 4. +Symbol linebuffer is in static storage at address 0x150a18, length 4. +Symbol linelength is in static storage at address 0x150a1c, length 4. +Symbol p is a local variable in register $esi, length 4. +Symbol p1 is a local variable in register $ebx, length 4. +Symbol nline is a local variable in register $edx, length 4. +Symbol repeat is a local variable at frame offset -8, length 4. +@end smallexample + +@noindent +This command is especially useful for determining what data to collect +during a @dfn{trace experiment}, see @ref{Tracepoint Actions, +collect}. + +@kindex info source +@item info source +Show information about the current source file---that is, the source file for +the function containing the current point of execution: +@itemize @bullet +@item +the name of the source file, and the directory containing it, +@item +the directory it was compiled in, +@item +its length, in lines, +@item +which programming language it is written in, +@item +if the debug information provides it, the program that compiled the file +(which may include, e.g., the compiler version and command line arguments), +@item +whether the executable includes debugging information for that file, and +if so, what format the information is in (e.g., STABS, Dwarf 2, etc.), and +@item +whether the debugging information includes information about +preprocessor macros. +@end itemize + + +@kindex info sources +@item info sources @r{[}-dirname | -basename@r{]} @r{[}--@r{]} @r{[}@var{regexp}@r{]} + + +With no options @samp{info sources} prints the names of all source +files in your program for which there is debugging information. The +source files are presented based on a list of object files +(executables and libraries) currently loaded into @value{GDBN}. For +each object file all of the associated source files are listed. + +Each source file will only be printed once for each object file, but a +single source file can be repeated in the output if it is part of +multiple object files. + +If the optional @var{regexp} is provided, then only source files that +match the regular expression will be printed. The matching is +case-sensitive, except on operating systems that have case-insensitive +filesystem (e.g., MS-Windows). @samp{--} can be used before +@var{regexp} to prevent @value{GDBN} interpreting @var{regexp} as a +command option (e.g. if @var{regexp} starts with @samp{-}). + +By default, the @var{regexp} is used to match anywhere in the +filename. If @code{-dirname}, only files having a dirname matching +@var{regexp} are shown. If @code{-basename}, only files having a +basename matching @var{regexp} are shown. + +It is possible that an object file may be printed in the list with no +associated source files. This can happen when either no source files +match @var{regexp}, or, the object file was compiled without debug +information and so @value{GDBN} is unable to find any source file +names. + +@kindex info functions +@item info functions [-q] [-n] +Print the names and data types of all defined functions. +Similarly to @samp{info types}, this command groups its output by source +files and annotates each function definition with its source line +number. + +In programs using different languages, @value{GDBN} chooses the syntax +to print the function name and type according to the +@samp{set language} value: using @samp{set language auto} +(see @ref{Automatically, ,Set Language Automatically}) means to use the +language of the function, other values mean to use +the manually specified language (see @ref{Manually, ,Set Language Manually}). + +The @samp{-n} flag excludes @dfn{non-debugging symbols} from the +results. A non-debugging symbol is a symbol that comes from the +executable's symbol table, not from the debug information (for +example, DWARF) associated with the executable. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no functions +have been printed. + +@item info functions [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] +Like @samp{info functions}, but only print the names and data types +of the functions selected with the provided regexp(s). + +If @var{regexp} is provided, print only the functions whose names +match the regular expression @var{regexp}. +Thus, @samp{info fun step} finds all functions whose +names include @code{step}; @samp{info fun ^step} finds those whose names +start with @code{step}. If a function name contains characters that +conflict with the regular expression language (e.g.@: +@samp{operator*()}), they may be quoted with a backslash. + +If @var{type_regexp} is provided, print only the functions whose +types, as printed by the @code{whatis} command, match +the regular expression @var{type_regexp}. +If @var{type_regexp} contains space(s), it should be enclosed in +quote characters. If needed, use backslash to escape the meaning +of special characters or quotes. +Thus, @samp{info fun -t '^int ('} finds the functions that return +an integer; @samp{info fun -t '(.*int.*'} finds the functions that +have an argument type containing int; @samp{info fun -t '^int (' ^step} +finds the functions whose names start with @code{step} and that return +int. + +If both @var{regexp} and @var{type_regexp} are provided, a function +is printed only if its name matches @var{regexp} and its type matches +@var{type_regexp}. + + +@kindex info variables +@item info variables [-q] [-n] +Print the names and data types of all variables that are defined +outside of functions (i.e.@: excluding local variables). +The printed variables are grouped by source files and annotated with +their respective source line numbers. + +In programs using different languages, @value{GDBN} chooses the syntax +to print the variable name and type according to the +@samp{set language} value: using @samp{set language auto} +(see @ref{Automatically, ,Set Language Automatically}) means to use the +language of the variable, other values mean to use +the manually specified language (see @ref{Manually, ,Set Language Manually}). + +The @samp{-n} flag excludes non-debugging symbols from the results. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no variables +have been printed. + +@item info variables [-q] [-n] [-t @var{type_regexp}] [@var{regexp}] +Like @kbd{info variables}, but only print the variables selected +with the provided regexp(s). + +If @var{regexp} is provided, print only the variables whose names +match the regular expression @var{regexp}. + +If @var{type_regexp} is provided, print only the variables whose +types, as printed by the @code{whatis} command, match +the regular expression @var{type_regexp}. +If @var{type_regexp} contains space(s), it should be enclosed in +quote characters. If needed, use backslash to escape the meaning +of special characters or quotes. + +If both @var{regexp} and @var{type_regexp} are provided, an argument +is printed only if its name matches @var{regexp} and its type matches +@var{type_regexp}. + +@kindex info modules +@cindex modules +@item info modules @r{[}-q@r{]} @r{[}@var{regexp}@r{]} +List all Fortran modules in the program, or all modules matching the +optional regular expression @var{regexp}. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no modules +have been printed. + +@kindex info module +@cindex Fortran modules, information about +@cindex functions and variables by Fortran module +@cindex module functions and variables +@item info module functions @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} +@itemx info module variables @r{[}-q@r{]} @r{[}-m @var{module-regexp}@r{]} @r{[}-t @var{type-regexp}@r{]} @r{[}@var{regexp}@r{]} +List all functions or variables within all Fortran modules. The set +of functions or variables listed can be limited by providing some or +all of the optional regular expressions. If @var{module-regexp} is +provided, then only Fortran modules matching @var{module-regexp} will +be searched. Only functions or variables whose type matches the +optional regular expression @var{type-regexp} will be listed. And +only functions or variables whose name matches the optional regular +expression @var{regexp} will be listed. + +The optional flag @samp{-q}, which stands for @samp{quiet}, disables +printing header information and messages explaining why no functions +or variables have been printed. + +@kindex info main +@item info main +Print the name of the starting function of the program. This serves +primarily Fortran programs, which have a user-supplied name for the +main subroutine. + +@kindex info classes +@cindex Objective-C, classes and selectors +@item info classes +@itemx info classes @var{regexp} +Display all Objective-C classes in your program, or +(with the @var{regexp} argument) all those matching a particular regular +expression. + +@kindex info selectors +@item info selectors +@itemx info selectors @var{regexp} +Display all Objective-C selectors in your program, or +(with the @var{regexp} argument) all those matching a particular regular +expression. + +@ignore +This was never implemented. +@kindex info methods +@item info methods +@itemx info methods @var{regexp} +The @code{info methods} command permits the user to examine all defined +methods within C@t{++} program, or (with the @var{regexp} argument) a +specific set of methods found in the various C@t{++} classes. Many +C@t{++} classes provide a large number of methods. Thus, the output +from the @code{ptype} command can be overwhelming and hard to use. The +@code{info-methods} command filters the methods, printing only those +which match the regular-expression @var{regexp}. +@end ignore + +@cindex opaque data types +@kindex set opaque-type-resolution +@item set opaque-type-resolution on +Tell @value{GDBN} to resolve opaque types. An opaque type is a type +declared as a pointer to a @code{struct}, @code{class}, or +@code{union}---for example, @code{struct MyType *}---that is used in one +source file although the full declaration of @code{struct MyType} is in +another source file. The default is on. + +A change in the setting of this subcommand will not take effect until +the next time symbols for a file are loaded. + +@item set opaque-type-resolution off +Tell @value{GDBN} not to resolve opaque types. In this case, the type +is printed as follows: +@smallexample +@{@} +@end smallexample + +@kindex show opaque-type-resolution +@item show opaque-type-resolution +Show whether opaque types are resolved or not. + +@kindex set print symbol-loading +@cindex print messages when symbols are loaded +@item set print symbol-loading +@itemx set print symbol-loading full +@itemx set print symbol-loading brief +@itemx set print symbol-loading off +The @code{set print symbol-loading} command allows you to control the +printing of messages when @value{GDBN} loads symbol information. +By default a message is printed for the executable and one for each +shared library, and normally this is what you want. However, when +debugging apps with large numbers of shared libraries these messages +can be annoying. +When set to @code{brief} a message is printed for each executable, +and when @value{GDBN} loads a collection of shared libraries at once +it will only print one message regardless of the number of shared +libraries. When set to @code{off} no messages are printed. + +@kindex show print symbol-loading +@item show print symbol-loading +Show whether messages will be printed when a @value{GDBN} command +entered from the keyboard causes symbol information to be loaded. + +@anchor{maint print symbols} +@kindex maint print symbols +@cindex symbol dump +@kindex maint print psymbols +@cindex partial symbol dump +@kindex maint print msymbols +@cindex minimal symbol dump +@item maint print symbols @r{[}-pc @var{address}@r{]} @r{[}@var{filename}@r{]} +@itemx maint print symbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} +@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-pc @var{address}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} +@itemx maint print psymbols @r{[}-objfile @var{objfile}@r{]} @r{[}-source @var{source}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} +@itemx maint print msymbols @r{[}-objfile @var{objfile}@r{]} @r{[}--@r{]} @r{[}@var{filename}@r{]} +Write a dump of debugging symbol data into the file @var{filename} or +the terminal if @var{filename} is unspecified. +If @code{-objfile @var{objfile}} is specified, only dump symbols for +that objfile. +If @code{-pc @var{address}} is specified, only dump symbols for the file +with code at that address. Note that @var{address} may be a symbol like +@code{main}. +If @code{-source @var{source}} is specified, only dump symbols for that +source file. + +These commands are used to debug the @value{GDBN} symbol-reading code. +These commands do not modify internal @value{GDBN} state, therefore +@samp{maint print symbols} will only print symbols for already expanded symbol +tables. +You can use the command @code{info sources} to find out which files these are. +If you use @samp{maint print psymbols} instead, the dump shows information +about symbols that @value{GDBN} only knows partially---that is, symbols +defined in files that @value{GDBN} has skimmed, but not yet read completely. +Finally, @samp{maint print msymbols} just dumps ``minimal symbols'', e.g., +``ELF symbols''. + +@xref{Files, ,Commands to Specify Files}, for a discussion of how +@value{GDBN} reads symbols (in the description of @code{symbol-file}). + +@kindex maint info symtabs +@kindex maint info psymtabs +@cindex listing @value{GDBN}'s internal symbol tables +@cindex symbol tables, listing @value{GDBN}'s internal +@cindex full symbol tables, listing @value{GDBN}'s internal +@cindex partial symbol tables, listing @value{GDBN}'s internal +@item maint info symtabs @r{[} @var{regexp} @r{]} +@itemx maint info psymtabs @r{[} @var{regexp} @r{]} + +List the @code{struct symtab} or @code{struct partial_symtab} +structures whose names match @var{regexp}. If @var{regexp} is not +given, list them all. The output includes expressions which you can +copy into a @value{GDBN} debugging this one to examine a particular +structure in more detail. For example: + +@smallexample +(@value{GDBP}) maint info psymtabs dwarf2read +@{ objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + @{ psymtab /home/gnu/src/gdb/dwarf2read.c + ((struct partial_symtab *) 0x8474b10) + readin no + fullname (null) + text addresses 0x814d3c8 -- 0x8158074 + globals (* (struct partial_symbol **) 0x8507a08 @@ 9) + statics (* (struct partial_symbol **) 0x40e95b78 @@ 2882) + dependencies (none) + @} +@} +(@value{GDBP}) maint info symtabs +(@value{GDBP}) +@end smallexample +@noindent +We see that there is one partial symbol table whose filename contains +the string @samp{dwarf2read}, belonging to the @samp{gdb} executable; +and we see that @value{GDBN} has not read in any symtabs yet at all. +If we set a breakpoint on a function, that will cause @value{GDBN} to +read the symtab for the compilation unit containing that function: + +@smallexample +(@value{GDBP}) break dwarf2_psymtab_to_symtab +Breakpoint 1 at 0x814e5da: file /home/gnu/src/gdb/dwarf2read.c, +line 1574. +(@value{GDBP}) maint info symtabs +@{ objfile /home/gnu/build/gdb/gdb + ((struct objfile *) 0x82e69d0) + @{ symtab /home/gnu/src/gdb/dwarf2read.c + ((struct symtab *) 0x86c1f38) + dirname (null) + fullname (null) + blockvector ((struct blockvector *) 0x86c1bd0) (primary) + linetable ((struct linetable *) 0x8370fa0) + debugformat DWARF 2 + @} +@} +(@value{GDBP}) +@end smallexample + +@kindex maint info line-table +@cindex listing @value{GDBN}'s internal line tables +@cindex line tables, listing @value{GDBN}'s internal +@item maint info line-table @r{[} @var{regexp} @r{]} + +List the @code{struct linetable} from all @code{struct symtab} +instances whose name matches @var{regexp}. If @var{regexp} is not +given, list the @code{struct linetable} from all @code{struct symtab}. +For example: + +@smallexample +(@value{GDBP}) maint info line-table +objfile: /home/gnu/build/a.out ((struct objfile *) 0x6120000e0d40) +compunit_symtab: simple.cpp ((struct compunit_symtab *) 0x6210000ff450) +symtab: /home/gnu/src/simple.cpp ((struct symtab *) 0x6210000ff4d0) +linetable: ((struct linetable *) 0x62100012b760): +INDEX LINE ADDRESS IS-STMT PROLOGUE-END EPILOGUE-BEGIN +0 3 0x0000000000401110 Y +1 4 0x0000000000401114 Y Y Y +2 9 0x0000000000401120 Y +3 10 0x0000000000401124 Y Y +4 10 0x0000000000401129 Y Y +5 15 0x0000000000401130 Y +6 16 0x0000000000401134 Y Y +7 16 0x0000000000401139 +8 21 0x0000000000401140 Y Y +9 22 0x000000000040114f Y Y +10 22 0x0000000000401154 Y +11 END 0x000000000040115a Y +@end smallexample +@noindent +The @samp{IS-STMT} column indicates if the address is a recommended breakpoint +location to represent a line or a statement. The @samp{PROLOGUE-END} column +indicates that a given address is an adequate place to set a breakpoint at the +first instruction following a function prologue. The @samp{EPILOGUE-BEGIN} +column indicates that a given address marks the point where a block's frame is +destroyed, making local variables hard or impossible to find. + +@kindex set always-read-ctf [on|off] +@kindex show always-read-ctf +@cindex always-read-ctf +@cindex CTF info, when to read +@item set always-read-ctf [on|off] +@itemx show always-read-ctf + +When off, CTF debug info is only read if DWARF debug info is not +present. When on, CTF debug info is read regardless of whether DWARF +debug info is present. The default value is off. + +@kindex maint set symbol-cache-size +@cindex symbol cache size +@item maint set symbol-cache-size @var{size} +Set the size of the symbol cache to @var{size}. +The default size is intended to be good enough for debugging +most applications. This option exists to allow for experimenting +with different sizes. + +@kindex maint show symbol-cache-size +@item maint show symbol-cache-size +Show the size of the symbol cache. + +@kindex maint print symbol-cache +@cindex symbol cache, printing its contents +@item maint print symbol-cache +Print the contents of the symbol cache. +This is useful when debugging symbol cache issues. + +@kindex maint print symbol-cache-statistics +@cindex symbol cache, printing usage statistics +@item maint print symbol-cache-statistics +Print symbol cache usage statistics. +This helps determine how well the cache is being utilized. + +@kindex maint flush symbol-cache +@kindex maint flush-symbol-cache +@cindex symbol cache, flushing +@item maint flush symbol-cache +@itemx maint flush-symbol-cache +Flush the contents of the symbol cache, all entries are removed. This +command is useful when debugging the symbol cache. It is also useful +when collecting performance data. The command @code{maint +flush-symbol-cache} is deprecated in favor of @code{maint flush +symbol-cache}.. + +@kindex maint set ignore-prologue-end-flag +@cindex prologue-end +@item maint set ignore-prologue-end-flag [on|off] +Enable or disable the use of the @samp{PROLOGUE-END} flag from the line-table. +When @samp{off} (the default), @value{GDBN} uses the @samp{PROLOGUE-END} flag +to place breakpoints past the end of a function prologue. When @samp{on}, +@value{GDBN} ignores the flag and relies on prologue analyzers to skip function +prologues. + +@kindex maint show ignore-prologue-end-flag +@item maint show ignore-prologue-end-flag +Show whether @value{GDBN} will ignore the @samp{PROLOGUE-END} flag. + +@end table + +@node Altering +@chapter Altering Execution + +Once you think you have found an error in your program, you might want to +find out for certain whether correcting the apparent error would lead to +correct results in the rest of the run. You can find the answer by +experiment, using the @value{GDBN} features for altering execution of the +program. + +For example, you can store new values into variables or memory +locations, give your program a signal, restart it at a different +address, or even return prematurely from a function. + +@menu +* Assignment:: Assignment to variables +* Jumping:: Continuing at a different address +* Signaling:: Giving your program a signal +* Returning:: Returning from a function +* Calling:: Calling your program's functions +* Patching:: Patching your program +* Compiling and Injecting Code:: Compiling and injecting code in @value{GDBN} +@end menu + +@node Assignment +@section Assignment to Variables + +@cindex assignment +@cindex setting variables +To alter the value of a variable, evaluate an assignment expression. +@xref{Expressions, ,Expressions}. For example, + +@smallexample +print x=4 +@end smallexample + +@noindent +stores the value 4 into the variable @code{x}, and then prints the +value of the assignment expression (which is 4). +@xref{Languages, ,Using @value{GDBN} with Different Languages}, for more +information on operators in supported languages. + +@kindex set variable +@cindex variables, setting +If you are not interested in seeing the value of the assignment, use the +@code{set} command instead of the @code{print} command. @code{set} is +really the same as @code{print} except that the expression's value is +not printed and is not put in the value history (@pxref{Value History, +,Value History}). The expression is evaluated only for its effects. + +If the beginning of the argument string of the @code{set} command +appears identical to a @code{set} subcommand, use the @code{set +variable} command instead of just @code{set}. This command is identical +to @code{set} except for its lack of subcommands. For example, if your +program has a variable @code{width}, you get an error if you try to set +a new value with just @samp{set width=13}, because @value{GDBN} has the +command @code{set width}: + +@smallexample +(@value{GDBP}) whatis width +type = double +(@value{GDBP}) p width +$4 = 13 +(@value{GDBP}) set width=47 +Invalid syntax in expression. +@end smallexample + +@noindent +The invalid expression, of course, is @samp{=47}. In +order to actually set the program's variable @code{width}, use + +@smallexample +(@value{GDBP}) set var width=47 +@end smallexample + +Because the @code{set} command has many subcommands that can conflict +with the names of program variables, it is a good idea to use the +@code{set variable} command instead of just @code{set}. For example, if +your program has a variable @code{g}, you run into problems if you try +to set a new value with just @samp{set g=4}, because @value{GDBN} has +the command @code{set gnutarget}, abbreviated @code{set g}: + +@smallexample +@group +(@value{GDBP}) whatis g +type = double +(@value{GDBP}) p g +$1 = 1 +(@value{GDBP}) set g=4 +(@value{GDBP}) p g +$2 = 1 +(@value{GDBP}) r +The program being debugged has been started already. +Start it from the beginning? (y or n) y +Starting program: /home/smith/cc_progs/a.out +"/home/smith/cc_progs/a.out": can't open to read symbols: + Invalid bfd target. +(@value{GDBP}) show g +The current BFD target is "=4". +@end group +@end smallexample + +@noindent +The program variable @code{g} did not change, and you silently set the +@code{gnutarget} to an invalid value. In order to set the variable +@code{g}, use + +@smallexample +(@value{GDBP}) set var g=4 +@end smallexample + +@value{GDBN} allows more implicit conversions in assignments than C; you can +freely store an integer value into a pointer variable or vice versa, +and you can convert any structure to any other structure that is the +same length or shorter. +@comment FIXME: how do structs align/pad in these conversions? +@comment /doc@cygnus.com 18dec1990 + +To store values into arbitrary places in memory, use the @samp{@{@dots{}@}} +construct to generate a value of specified type at a specified address +(@pxref{Expressions, ,Expressions}). For example, @code{@{int@}0x83040} refers +to memory location @code{0x83040} as an integer (which implies a certain size +and representation in memory), and + +@smallexample +set @{int@}0x83040 = 4 +@end smallexample + +@noindent +stores the value 4 into that memory location. + +@node Jumping +@section Continuing at a Different Address + +Ordinarily, when you continue your program, you do so at the place where +it stopped, with the @code{continue} command. You can instead continue at +an address of your own choosing, with the following commands: + +@table @code +@kindex jump +@kindex j @r{(@code{jump})} +@item jump @var{locspec} +@itemx j @var{locspec} +Resume execution at the address of the code location that results from +resolving @var{locspec}. +@xref{Location Specifications}, for a description of the different +forms of @var{locspec}. If @var{locspec} resolves to more than one address, +those outside the current compilation unit are ignored. If considering just +the addresses in the current compilation unit still doesn't yield a unique +address, the command aborts before jumping. +Execution stops again immediately if there is a breakpoint there. It +is common practice to use the @code{tbreak} command in conjunction +with @code{jump}. @xref{Set Breaks, ,Setting Breakpoints}. + +The @code{jump} command does not change the current stack frame, or +the stack pointer, or the contents of any memory location or any +register other than the program counter. If @var{locspec} resolves to +an address in a different function from the one currently executing, the +results may be bizarre if the two functions expect different patterns +of arguments or of local variables. For this reason, the @code{jump} +command requests confirmation if the jump address is not in the +function currently executing. However, even bizarre results are +predictable if you are well acquainted with the machine-language code +of your program. +@end table + +On many systems, you can get much the same effect as the @code{jump} +command by storing a new value into the register @code{$pc}. The +difference is that this does not start your program running; it only +changes the address of where it @emph{will} run when you continue. For +example, + +@smallexample +set $pc = 0x485 +@end smallexample + +@noindent +makes the next @code{continue} command or stepping command execute at +address @code{0x485}, rather than at the address where your program stopped. +@xref{Continuing and Stepping, ,Continuing and Stepping}. + +However, writing directly to @code{$pc} will only change the value of +the program-counter register, while using @code{jump} will ensure that +any additional auxiliary state is also updated. For example, on +SPARC, @code{jump} will update both @code{$pc} and @code{$npc} +registers prior to resuming execution. When using the approach of +writing directly to @code{$pc} it is your job to also update the +@code{$npc} register. + +The most common occasion to use the @code{jump} command is to back +up---perhaps with more breakpoints set---over a portion of a program +that has already executed, in order to examine its execution in more +detail. + +@c @group +@node Signaling +@section Giving your Program a Signal +@cindex deliver a signal to a program + +@table @code +@kindex signal +@item signal @var{signal} +Resume execution where your program is stopped, but immediately give it the +signal @var{signal}. The @var{signal} can be the name or the number of a +signal. For example, on many systems @code{signal 2} and @code{signal +SIGINT} are both ways of sending an interrupt signal. + +Alternatively, if @var{signal} is zero, continue execution without +giving a signal. This is useful when your program stopped on account of +a signal and would ordinarily see the signal when resumed with the +@code{continue} command; @samp{signal 0} causes it to resume without a +signal. + +@emph{Note:} When resuming a multi-threaded program, @var{signal} is +delivered to the currently selected thread, not the thread that last +reported a stop. This includes the situation where a thread was +stopped due to a signal. So if you want to continue execution +suppressing the signal that stopped a thread, you should select that +same thread before issuing the @samp{signal 0} command. If you issue +the @samp{signal 0} command with another thread as the selected one, +@value{GDBN} detects that and asks for confirmation. + +Invoking the @code{signal} command is not the same as invoking the +@code{kill} utility from the shell. Sending a signal with @code{kill} +causes @value{GDBN} to decide what to do with the signal depending on +the signal handling tables (@pxref{Signals}). The @code{signal} command +passes the signal directly to your program. + +@code{signal} does not repeat when you press @key{RET} a second time +after executing the command. + +@kindex queue-signal +@item queue-signal @var{signal} +Queue @var{signal} to be delivered immediately to the current thread +when execution of the thread resumes. The @var{signal} can be the name or +the number of a signal. For example, on many systems @code{signal 2} and +@code{signal SIGINT} are both ways of sending an interrupt signal. +The handling of the signal must be set to pass the signal to the program, +otherwise @value{GDBN} will report an error. +You can control the handling of signals from @value{GDBN} with the +@code{handle} command (@pxref{Signals}). + +Alternatively, if @var{signal} is zero, any currently queued signal +for the current thread is discarded and when execution resumes no signal +will be delivered. This is useful when your program stopped on account +of a signal and would ordinarily see the signal when resumed with the +@code{continue} command. + +This command differs from the @code{signal} command in that the signal +is just queued, execution is not resumed. And @code{queue-signal} cannot +be used to pass a signal whose handling state has been set to @code{nopass} +(@pxref{Signals}). +@end table +@c @end group + +@xref{stepping into signal handlers}, for information on how stepping +commands behave when the thread has a signal queued. + +@node Returning +@section Returning from a Function + +@table @code +@cindex returning from a function +@kindex return +@item return +@itemx return @var{expression} +You can cancel execution of a function call with the @code{return} +command. If you give an +@var{expression} argument, its value is used as the function's return +value. +@end table + +When you use @code{return}, @value{GDBN} discards the selected stack frame +(and all frames within it). You can think of this as making the +discarded frame return prematurely. If you wish to specify a value to +be returned, give that value as the argument to @code{return}. + +This pops the selected stack frame (@pxref{Selection, ,Selecting a +Frame}), and any other frames inside of it, leaving its caller as the +innermost remaining frame. That frame becomes selected. The +specified value is stored in the registers used for returning values +of functions. + +The @code{return} command does not resume execution; it leaves the +program stopped in the state that would exist if the function had just +returned. In contrast, the @code{finish} command (@pxref{Continuing +and Stepping, ,Continuing and Stepping}) resumes execution until the +selected stack frame returns naturally. + +@value{GDBN} needs to know how the @var{expression} argument should be set for +the inferior. The concrete registers assignment depends on the OS ABI and the +type being returned by the selected stack frame. For example it is common for +OS ABI to return floating point values in FPU registers while integer values in +CPU registers. Still some ABIs return even floating point values in CPU +registers. Larger integer widths (such as @code{long long int}) also have +specific placement rules. @value{GDBN} already knows the OS ABI from its +current target so it needs to find out also the type being returned to make the +assignment into the right register(s). + +Normally, the selected stack frame has debug info. @value{GDBN} will always +use the debug info instead of the implicit type of @var{expression} when the +debug info is available. For example, if you type @kbd{return -1}, and the +function in the current stack frame is declared to return a @code{long long +int}, @value{GDBN} transparently converts the implicit @code{int} value of -1 +into a @code{long long int}: + +@smallexample +Breakpoint 1, func () at gdb.base/return-nodebug.c:29 +29 return 31; +(@value{GDBP}) return -1 +Make func return now? (y or n) y +#0 0x004004f6 in main () at gdb.base/return-nodebug.c:43 +43 printf ("result=%lld\n", func ()); +(@value{GDBP}) +@end smallexample + +However, if the selected stack frame does not have a debug info, e.g., if the +function was compiled without debug info, @value{GDBN} has to find out the type +to return from user. Specifying a different type by mistake may set the value +in different inferior registers than the caller code expects. For example, +typing @kbd{return -1} with its implicit type @code{int} would set only a part +of a @code{long long int} result for a debug info less function (on 32-bit +architectures). Therefore the user is required to specify the return type by +an appropriate cast explicitly: + +@smallexample +Breakpoint 2, 0x0040050b in func () +(@value{GDBP}) return -1 +Return value type not available for selected stack frame. +Please use an explicit cast of the value to return. +(@value{GDBP}) return (long long int) -1 +Make selected stack frame return now? (y or n) y +#0 0x00400526 in main () +(@value{GDBP}) +@end smallexample + +@node Calling +@section Calling Program Functions + +@table @code +@cindex calling functions +@cindex inferior functions, calling +@item print @var{expr} +Evaluate the expression @var{expr} and display the resulting value. +The expression may include calls to functions in the program being +debugged. + +@kindex call +@item call @var{expr} +Evaluate the expression @var{expr} without displaying @code{void} +returned values. + +You can use this variant of the @code{print} command if you want to +execute a function from your program that does not return anything +(a.k.a.@: @dfn{a void function}), but without cluttering the output +with @code{void} returned values that @value{GDBN} will otherwise +print. If the result is not void, it is printed and saved in the +value history. +@end table + +It is possible for the function you call via the @code{print} or +@code{call} command to generate a signal (e.g., if there's a bug in +the function, or if you passed it incorrect arguments). What happens +in that case is controlled by the @code{set unwind-on-signal} command. + +Similarly, with a C@t{++} program it is possible for the function you +call via the @code{print} or @code{call} command to generate an +exception that is not handled due to the constraints of the dummy +frame. In this case, any exception that is raised in the frame, but has +an out-of-frame exception handler will not be found. GDB builds a +dummy-frame for the inferior function call, and the unwinder cannot +seek for exception handlers outside of this dummy-frame. What happens +in that case is controlled by the +@code{set unwind-on-terminating-exception} command. + +@anchor{stack unwind settings} +@table @code +@item set unwind-on-signal +@kindex set unwind-on-signal +@kindex set unwindonsignal +@cindex unwind stack in called functions +@cindex call dummy stack unwinding +Set unwinding of the stack if a signal is received while in a function +that @value{GDBN} called in the program being debugged. If set to on, +@value{GDBN} unwinds the stack it created for the call and restores +the context to what it was before the call. If set to off (the +default), @value{GDBN} stops in the frame where the signal was +received. + +The command @code{set unwindonsignal} is an alias for this command, +and is maintained for backward compatibility. + +@item show unwind-on-signal +@kindex show unwind-on-signal +@kindex show unwindonsignal +Show the current setting of stack unwinding in the functions called by +@value{GDBN}. + +The command @code{show unwindonsignal} is an alias for this command, +and is maintained for backward compatibility. + +@item set unwind-on-terminating-exception +@kindex set unwind-on-terminating-exception +@cindex unwind stack in called functions with unhandled exceptions +@cindex call dummy stack unwinding on unhandled exception. +Set unwinding of the stack if a C@t{++} exception is raised, but left +unhandled while in a function that @value{GDBN} called in the program being +debugged. If set to on (the default), @value{GDBN} unwinds the stack +it created for the call and restores the context to what it was before +the call. If set to off, @value{GDBN} the exception is delivered to +the default C@t{++} exception handler and the inferior terminated. + +@item show unwind-on-terminating-exception +@kindex show unwind-on-terminating-exception +Show the current setting of stack unwinding in the functions called by +@value{GDBN}. + +@anchor{set unwind-on-timeout} +@item set unwind-on-timeout +@kindex set unwind-on-timeout +@cindex unwind stack in called functions when timing out +@cindex call dummy stack unwinding on timeout. +Set unwinding of the stack if a function called from @value{GDBN} +times out. If set to @code{off} (the default), @value{GDBN} stops in +the frame where the timeout occurred. If set to @code{on}, +@value{GDBN} unwinds the stack it created for the call and restores +the context to what it was before the call. + +@item show unwind-on-timeout +@kindex show unwind-on-timeout +Show whether @value{GDBN} will unwind the stack if a function called +from @value{GDBN} times out. + +@item set may-call-functions +@kindex set may-call-functions +@cindex disabling calling functions in the program +@cindex calling functions in the program, disabling +Set permission to call functions in the program. +This controls whether @value{GDBN} will attempt to call functions in +the program, such as with expressions in the @code{print} command. It +defaults to @code{on}. + +To call a function in the program, @value{GDBN} has to temporarily +modify the state of the inferior. This has potentially undesired side +effects. Also, having @value{GDBN} call nested functions is likely to +be erroneous and may even crash the program being debugged. You can +avoid such hazards by forbidding @value{GDBN} from calling functions +in the program being debugged. If calling functions in the program +is forbidden, GDB will throw an error when a command (such as printing +an expression) starts a function call in the program. + +@item show may-call-functions +@kindex show may-call-functions +Show permission to call functions in the program. + +@end table + +When calling a function within a program, it is possible that the +program could enter a state from which the called function may never +return. If this happens then it is possible to interrupt the function +call by typing the interrupt character (often @kbd{Ctrl-c}). + +If a called function is interrupted for any reason, including hitting +a breakpoint, or triggering a watchpoint, and the stack is not unwound +due to @code{set unwind-on-terminating-exception on}, @code{set +unwind-on-timeout on}, or @code{set unwind-on-signal on} (@pxref{stack +unwind settings}), then the dummy-frame, created by @value{GDBN} to +facilitate the call to the program function, will be visible in the +backtrace, for example frame @code{#3} in the following backtrace: + +@smallexample +(@value{GDBP}) backtrace +#0 0x00007ffff7b3d1e7 in nanosleep () from /lib64/libc.so.6 +#1 0x00007ffff7b3d11e in sleep () from /lib64/libc.so.6 +#2 0x000000000040113f in deadlock () at test.cc:13 +#3 +#4 breakpt () at test.cc:20 +#5 0x0000000000401151 in main () at test.cc:25 +@end smallexample + +At this point it is possible to examine the state of the inferior just +like any other stop. + +Depending on why the function was interrupted then it may be possible +to resume the inferior (using commands like @code{continue}, +@code{step}, etc). In this case, when the inferior finally returns to +the dummy-frame, @value{GDBN} will once again halt the inferior. + +On targets that support asynchronous execution (@pxref{Background +Execution}) @value{GDBN} can place a timeout on any functions called +from @value{GDBN}. If the timeout expires and the function call is +still ongoing, then @value{GDBN} will interrupt the program. + +If a function called from @value{GDBN} is interrupted by a timeout, +then by default the inferior is left in the frame where the timeout +occurred, this behavior can be adjusted with @samp{set +unwind-on-timeout} (@pxref{set unwind-on-timeout}). + +For targets that don't support asynchronous execution +(@pxref{Background Execution}) then timeouts for functions called from +@value{GDBN} are not supported, the timeout settings described below +will be treated as @code{unlimited}, meaning @value{GDBN} will wait +indefinitely for function call to complete, unless interrupted by the +user using @kbd{Ctrl-C}. + +@table @code +@item set direct-call-timeout @var{seconds} +@kindex set direct-call-timeout +@cindex timeout for called functions +Set the timeout used when calling functions in the program to +@var{seconds}, which should be an integer greater than zero, or the +special value @code{unlimited}, which indicates no timeout should be +used. The default for this setting is @code{unlimited}. + +This setting is used when the user calls a function directly from the +command prompt, for example with a @code{call} or @code{print} +command. + +This setting only works for targets that support asynchronous +execution (@pxref{Background Execution}), for any other target the +setting is treated as @code{unlimited}. + +@item show direct-call-timeout +@kindex show direct-call-timeout +@cindex timeout for called functions +Show the timeout used when calling functions in the program with a +@code{call} or @code{print} command. +@end table + +It is also possible to call functions within the program from the +condition of a conditional breakpoint (@pxref{Conditions, ,Break +Conditions}). A different setting controls the timeout used for +function calls made from a breakpoint condition. + +@table @code +@item set indirect-call-timeout @var{seconds} +@kindex set indirect-call-timeout +@cindex timeout for called functions +Set the timeout used when calling functions in the program from a +breakpoint or watchpoint condition to @var{seconds}, which should be +an integer greater than zero, or the special value @code{unlimited}, +which indicates no timeout should be used. The default for this +setting is @code{30} seconds. + +This setting only works for targets that support asynchronous +execution (@pxref{Background Execution}), for any other target the +setting is treated as @code{unlimited}. + +If a function called from a breakpoint or watchpoint condition times +out, then @value{GDBN} will stop at the point where the timeout +occurred. The breakpoint condition evaluation will be abandoned. + +@item show indirect-call-timeout +@kindex show indirect-call-timeout +@cindex timeout for called functions +Show the timeout used when calling functions in the program from a +breakpoint or watchpoint condition. +@end table + +@subsection Calling functions with no debug info + +@cindex no debug info functions +Sometimes, a function you wish to call is missing debug information. +In such case, @value{GDBN} does not know the type of the function, +including the types of the function's parameters. To avoid calling +the inferior function incorrectly, which could result in the called +function functioning erroneously and even crash, @value{GDBN} refuses +to call the function unless you tell it the type of the function. + +For prototyped (i.e.@: ANSI/ISO style) functions, there are two ways +to do that. The simplest is to cast the call to the function's +declared return type. For example: + +@smallexample +(@value{GDBP}) p getenv ("PATH") +'getenv' has unknown return type; cast the call to its declared return type +(@value{GDBP}) p (char *) getenv ("PATH") +$1 = 0x7fffffffe7ba "/usr/local/bin:/"... +@end smallexample + +Casting the return type of a no-debug function is equivalent to +casting the function to a pointer to a prototyped function that has a +prototype that matches the types of the passed-in arguments, and +calling that. I.e., the call above is equivalent to: + +@smallexample +(@value{GDBP}) p ((char * (*) (const char *)) getenv) ("PATH") +@end smallexample + +@noindent +and given this prototyped C or C++ function with float parameters: + +@smallexample +float multiply (float v1, float v2) @{ return v1 * v2; @} +@end smallexample + +@noindent +these calls are equivalent: + +@smallexample +(@value{GDBP}) p (float) multiply (2.0f, 3.0f) +(@value{GDBP}) p ((float (*) (float, float)) multiply) (2.0f, 3.0f) +@end smallexample + +If the function you wish to call is declared as unprototyped (i.e.@: +old K&R style), you must use the cast-to-function-pointer syntax, so +that @value{GDBN} knows that it needs to apply default argument +promotions (promote float arguments to double). @xref{ABI, float +promotion}. For example, given this unprototyped C function with +float parameters, and no debug info: + +@smallexample +float +multiply_noproto (v1, v2) + float v1, v2; +@{ + return v1 * v2; +@} +@end smallexample + +@noindent +you call it like this: + +@smallexample + (@value{GDBP}) p ((float (*) ()) multiply_noproto) (2.0f, 3.0f) +@end smallexample + +@node Patching +@section Patching Programs + +@cindex patching binaries +@cindex writing into executables +@cindex writing into corefiles + +By default, @value{GDBN} opens the file containing your program's +executable code (or the corefile) read-only. This prevents accidental +alterations to machine code; but it also prevents you from intentionally +patching your program's binary. + +If you'd like to be able to patch the binary, you can specify that +explicitly with the @code{set write} command. For example, you might +want to turn on internal debugging flags, or even to make emergency +repairs. + +@table @code +@kindex set write +@item set write on +@itemx set write off +If you specify @samp{set write on}, @value{GDBN} opens executable and +core files for both reading and writing; if you specify @kbd{set write +off} (the default), @value{GDBN} opens them read-only. + +If you have already loaded a file, you must load it again (using the +@code{exec-file} or @code{core-file} command) after changing @code{set +write}, for your new setting to take effect. + +@item show write +@kindex show write +Display whether executable files and core files are opened for writing +as well as reading. +@end table + +@node Compiling and Injecting Code +@section Compiling and injecting code in @value{GDBN} +@cindex injecting code +@cindex writing into executables +@cindex compiling code + +@value{GDBN} supports on-demand compilation and code injection into +programs running under @value{GDBN}. GCC 5.0 or higher built with +@file{libcc1.so} must be installed for this functionality to be enabled. +This functionality is implemented with the following commands. + +@table @code +@kindex compile code +@item compile code @var{source-code} +@itemx compile code -raw @var{--} @var{source-code} +Compile @var{source-code} with the compiler language found as the current +language in @value{GDBN} (@pxref{Languages}). If compilation and +injection is not supported with the current language specified in +@value{GDBN}, or the compiler does not support this feature, an error +message will be printed. If @var{source-code} compiles and links +successfully, @value{GDBN} will load the object-code emitted, +and execute it within the context of the currently selected inferior. +It is important to note that the compiled code is executed immediately. +After execution, the compiled code is removed from @value{GDBN} and any +new types or variables you have defined will be deleted. + +The command allows you to specify @var{source-code} in two ways. +The simplest method is to provide a single line of code to the command. +E.g.: + +@smallexample +compile code printf ("hello world\n"); +@end smallexample + +If you specify options on the command line as well as source code, they +may conflict. The @samp{--} delimiter can be used to separate options +from actual source code. E.g.: + +@smallexample +compile code -r -- printf ("hello world\n"); +@end smallexample + +Alternatively you can enter source code as multiple lines of text. To +enter this mode, invoke the @samp{compile code} command without any text +following the command. This will start the multiple-line editor and +allow you to type as many lines of source code as required. When you +have completed typing, enter @samp{end} on its own line to exit the +editor. + +@smallexample +compile code +>printf ("hello\n"); +>printf ("world\n"); +>end +@end smallexample + +Specifying @samp{-raw}, prohibits @value{GDBN} from wrapping the +provided @var{source-code} in a callable scope. In this case, you must +specify the entry point of the code by defining a function named +@code{_gdb_expr_}. The @samp{-raw} code cannot access variables of the +inferior. Using @samp{-raw} option may be needed for example when +@var{source-code} requires @samp{#include} lines which may conflict with +inferior symbols otherwise. + +@kindex compile file +@item compile file @var{filename} +@itemx compile file -raw @var{filename} +Like @code{compile code}, but take the source code from @var{filename}. + +@smallexample +compile file /home/user/example.c +@end smallexample + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. +@end table + +@table @code +@item compile print [[@var{options}] --] @var{expr} +@itemx compile print [[@var{options}] --] /@var{f} @var{expr} +Compile and execute @var{expr} with the compiler language found as the +current language in @value{GDBN} (@pxref{Languages}). By default the +value of @var{expr} is printed in a format appropriate to its data type; +you can choose a different format by specifying @samp{/@var{f}}, where +@var{f} is a letter specifying the format; see @ref{Output Formats,,Output +Formats}. The @code{compile print} command accepts the same options +as the @code{print} command; see @ref{print options}. + +@item compile print [[@var{options}] --] +@itemx compile print [[@var{options}] --] /@var{f} +@cindex reprint the last value +Alternatively you can enter the expression (source code producing it) as +multiple lines of text. To enter this mode, invoke the @samp{compile print} +command without any text following the command. This will start the +multiple-line editor. +@end table + +@noindent +The process of compiling and injecting the code can be inspected using: + +@table @code +@anchor{set debug compile} +@item set debug compile +@cindex compile command debugging info +Turns on or off display of @value{GDBN} process of compiling and +injecting the code. The default is off. + +@item show debug compile +Displays the current state of displaying @value{GDBN} process of +compiling and injecting the code. + +@anchor{set debug compile-cplus-types} +@item set debug compile-cplus-types +@cindex compile C@t{++} type conversion +Turns on or off the display of C@t{++} type conversion debugging information. +The default is off. + +@item show debug compile-cplus-types +Displays the current state of displaying debugging information for +C@t{++} type conversion. +@end table + +@subsection Compilation options for the @code{compile} command + +@value{GDBN} needs to specify the right compilation options for the code +to be injected, in part to make its ABI compatible with the inferior +and in part to make the injected code compatible with @value{GDBN}'s +injecting process. + +@noindent +The options used, in increasing precedence: + +@table @asis +@item target architecture and OS options (@code{gdbarch}) +These options depend on target processor type and target operating +system, usually they specify at least 32-bit (@code{-m32}) or 64-bit +(@code{-m64}) compilation option. + +@item compilation options recorded in the target +@value{NGCC} (since version 4.7) stores the options used for compilation +into @code{DW_AT_producer} part of DWARF debugging information according +to the @value{NGCC} option @code{-grecord-gcc-switches}. One has to +explicitly specify @code{-g} during inferior compilation otherwise +@value{NGCC} produces no DWARF. This feature is only relevant for +platforms where @code{-g} produces DWARF by default, otherwise one may +try to enforce DWARF by using @code{-gdwarf-4}. + +@item compilation options set by @code{set compile-args} +@end table + +@noindent +You can override compilation options using the following command: + +@table @code +@item set compile-args +@cindex compile command options override +Set compilation options used for compiling and injecting code with the +@code{compile} commands. These options override any conflicting ones +from the target architecture and/or options stored during inferior +compilation. + +@item show compile-args +Displays the current state of compilation options override. +This does not show all the options actually used during compilation, +use @ref{set debug compile} for that. +@end table + +@subsection Caveats when using the @code{compile} command + +There are a few caveats to keep in mind when using the @code{compile} +command. As the caveats are different per language, the table below +highlights specific issues on a per language basis. + +@table @asis +@item C code examples and caveats +When the language in @value{GDBN} is set to @samp{C}, the compiler will +attempt to compile the source code with a @samp{C} compiler. The source +code provided to the @code{compile} command will have much the same +access to variables and types as it normally would if it were part of +the program currently being debugged in @value{GDBN}. + +Below is a sample program that forms the basis of the examples that +follow. This program has been compiled and loaded into @value{GDBN}, +much like any other normal debugging session. + +@smallexample +void function1 (void) +@{ + int i = 42; + printf ("function 1\n"); +@} + +void function2 (void) +@{ + int j = 12; + function1 (); +@} + +int main(void) +@{ + int k = 6; + int *p; + function2 (); + return 0; +@} +@end smallexample + +For the purposes of the examples in this section, the program above has +been compiled, loaded into @value{GDBN}, stopped at the function +@code{main}, and @value{GDBN} is awaiting input from the user. + +To access variables and types for any program in @value{GDBN}, the +program must be compiled and packaged with debug information. The +@code{compile} command is not an exception to this rule. Without debug +information, you can still use the @code{compile} command, but you will +be very limited in what variables and types you can access. + +So with that in mind, the example above has been compiled with debug +information enabled. The @code{compile} command will have access to +all variables and types (except those that may have been optimized +out). Currently, as @value{GDBN} has stopped the program in the +@code{main} function, the @code{compile} command would have access to +the variable @code{k}. You could invoke the @code{compile} command +and type some source code to set the value of @code{k}. You can also +read it, or do anything with that variable you would normally do in +@code{C}. Be aware that changes to inferior variables in the +@code{compile} command are persistent. In the following example: + +@smallexample +compile code k = 3; +@end smallexample + +@noindent +the variable @code{k} is now 3. It will retain that value until +something else in the example program changes it, or another +@code{compile} command changes it. + +Normal scope and access rules apply to source code compiled and +injected by the @code{compile} command. In the example, the variables +@code{j} and @code{k} are not accessible yet, because the program is +currently stopped in the @code{main} function, where these variables +are not in scope. Therefore, the following command + +@smallexample +compile code j = 3; +@end smallexample + +@noindent +will result in a compilation error message. + +Once the program is continued, execution will bring these variables in +scope, and they will become accessible; then the code you specify via +the @code{compile} command will be able to access them. + +You can create variables and types with the @code{compile} command as +part of your source code. Variables and types that are created as part +of the @code{compile} command are not visible to the rest of the program for +the duration of its run. This example is valid: + +@smallexample +compile code int ff = 5; printf ("ff is %d\n", ff); +@end smallexample + +However, if you were to type the following into @value{GDBN} after that +command has completed: + +@smallexample +compile code printf ("ff is %d\n'', ff); +@end smallexample + +@noindent +a compiler error would be raised as the variable @code{ff} no longer +exists. Object code generated and injected by the @code{compile} +command is removed when its execution ends. Caution is advised +when assigning to program variables values of variables created by the +code submitted to the @code{compile} command. This example is valid: + +@smallexample +compile code int ff = 5; k = ff; +@end smallexample + +The value of the variable @code{ff} is assigned to @code{k}. The variable +@code{k} does not require the existence of @code{ff} to maintain the value +it has been assigned. However, pointers require particular care in +assignment. If the source code compiled with the @code{compile} command +changed the address of a pointer in the example program, perhaps to a +variable created in the @code{compile} command, that pointer would point +to an invalid location when the command exits. The following example +would likely cause issues with your debugged program: + +@smallexample +compile code int ff = 5; p = &ff; +@end smallexample + +In this example, @code{p} would point to @code{ff} when the +@code{compile} command is executing the source code provided to it. +However, as variables in the (example) program persist with their +assigned values, the variable @code{p} would point to an invalid +location when the command exists. A general rule should be followed +in that you should either assign @code{NULL} to any assigned pointers, +or restore a valid location to the pointer before the command exits. + +Similar caution must be exercised with any structs, unions, and typedefs +defined in @code{compile} command. Types defined in the @code{compile} +command will no longer be available in the next @code{compile} command. +Therefore, if you cast a variable to a type defined in the +@code{compile} command, care must be taken to ensure that any future +need to resolve the type can be achieved. + +@smallexample +(@value{GDBP}) compile code static struct a @{ int a; @} v = @{ 42 @}; argv = &v; +(@value{GDBP}) compile code printf ("%d\n", ((struct a *) argv)->a); +gdb command line:1:36: error: dereferencing pointer to incomplete type ‘struct a’ +Compilation failed. +(@value{GDBP}) compile code struct a @{ int a; @}; printf ("%d\n", ((struct a *) argv)->a); +42 +@end smallexample + +Variables that have been optimized away by the compiler are not +accessible to the code submitted to the @code{compile} command. +Access to those variables will generate a compiler error which @value{GDBN} +will print to the console. +@end table + +@subsection Compiler search for the @code{compile} command + +@value{GDBN} needs to find @value{NGCC} for the inferior being debugged +which may not be obvious for remote targets of different architecture +than where @value{GDBN} is running. Environment variable @env{PATH} on +@value{GDBN} host is searched for @value{NGCC} binary matching the +target architecture and operating system. This search can be overridden +by @code{set compile-gcc} @value{GDBN} command below. @env{PATH} is +taken from shell that executed @value{GDBN}, it is not the value set by +@value{GDBN} command @code{set environment}). @xref{Environment}. + + +Specifically @env{PATH} is searched for binaries matching regular expression +@code{@var{arch}(-[^-]*)?-@var{os}-gcc} according to the inferior target being +debugged. @var{arch} is processor name --- multiarch is supported, so for +example both @code{i386} and @code{x86_64} targets look for pattern +@code{(x86_64|i.86)} and both @code{s390} and @code{s390x} targets look +for pattern @code{s390x?}. @var{os} is currently supported only for +pattern @code{linux(-gnu)?}. + +On Posix hosts the compiler driver @value{GDBN} needs to find also +shared library @file{libcc1.so} from the compiler. It is searched in +default shared library search path (overridable with usual environment +variable @env{LD_LIBRARY_PATH}), unrelated to @env{PATH} or @code{set +compile-gcc} settings. Contrary to it @file{libcc1plugin.so} is found +according to the installation of the found compiler --- as possibly +specified by the @code{set compile-gcc} command. + +@table @code +@item set compile-gcc +@cindex compile command driver filename override +Set compilation command used for compiling and injecting code with the +@code{compile} commands. If this option is not set (it is set to +an empty string), the search described above will occur --- that is the +default. + +@item show compile-gcc +Displays the current compile command @value{NGCC} driver filename. +If set, it is the main command @command{gcc}, found usually for example +under name @file{x86_64-linux-gnu-gcc}. +@end table + +@node GDB Files +@chapter @value{GDBN} Files + +@value{GDBN} needs to know the file name of the program to be debugged, +both in order to read its symbol table and in order to start your +program. To debug a core dump of a previous run, you must also tell +@value{GDBN} the name of the core dump file. + +@menu +* Files:: Commands to specify files +* File Caching:: Information about @value{GDBN}'s file caching +* Separate Debug Files:: Debugging information in separate files +* MiniDebugInfo:: Debugging information in a special section +* Index Files:: Index files speed up GDB +* Debug Names:: Extensions to .debug_names +* Symbol Errors:: Errors reading symbol files +* Data Files:: GDB data files +@end menu + +@node Files +@section Commands to Specify Files + +@cindex symbol table +@cindex core dump file + +You may want to specify executable and core dump file names. The usual +way to do this is at start-up time, using the arguments to +@value{GDBN}'s start-up commands (@pxref{Invocation, , Getting In and +Out of @value{GDBN}}). + +Occasionally it is necessary to change to a different file during a +@value{GDBN} session. Or you may run @value{GDBN} and forget to +specify a file you want to use. Or you are debugging a remote target +via @code{gdbserver} (@pxref{Server, file, Using the @code{gdbserver} +Program}). In these situations the @value{GDBN} commands to specify +new files are useful. + +@table @code +@cindex executable file +@kindex file +@item file @var{filename} +Use @var{filename} as the program to be debugged. It is read for its +symbols and for the contents of pure memory. It is also the program +executed when you use the @code{run} command. If you do not specify a +directory and the file is not found in the @value{GDBN} working directory, +@value{GDBN} uses the environment variable @env{PATH} as a list of +directories to search, just as the shell does when looking for a program +to run. You can change the value of this variable, for both @value{GDBN} +and your program, using the @code{path} command. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@cindex unlinked object files +@cindex patching object files +You can load unlinked object @file{.o} files into @value{GDBN} using +the @code{file} command. You will not be able to ``run'' an object +file, but you can disassemble functions and inspect variables. Also, +if the underlying BFD functionality supports it, you could use +@kbd{gdb -write} to patch object files using this technique. Note +that @value{GDBN} can neither interpret nor modify relocations in this +case, so branches and some initialized variables will appear to go to +the wrong place. But this feature is still handy from time to time. + +@item file +@code{file} with no argument makes @value{GDBN} discard any information it +has on both executable file and the symbol table. + +@kindex exec-file +@item exec-file @r{[} @var{filename} @r{]} +Specify that the program to be run (but not the symbol table) is found +in @var{filename}. @value{GDBN} searches the environment variable @env{PATH} +if necessary to locate your program. Omitting @var{filename} means to +discard information on the executable file. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@kindex symbol-file +@item symbol-file @r{[} @var{filename} @r{[} -o @var{offset} @r{]]} +Read symbol table information from file @var{filename}. @env{PATH} is +searched when necessary. Use the @code{file} command to get both symbol +table and program to run from the same file. + +If an optional @var{offset} is specified, it is added to the start +address of each section in the symbol file. This is useful if the +program is relocated at runtime, such as the Linux kernel with kASLR +enabled. + +@code{symbol-file} with no argument clears out @value{GDBN} information on your +program's symbol table. + +The @code{symbol-file} command causes @value{GDBN} to forget the contents of +some breakpoints and auto-display expressions. This is because they may +contain pointers to the internal data recording symbols and data types, +which are part of the old symbol table data being discarded inside +@value{GDBN}. + +@code{symbol-file} does not repeat if you press @key{RET} again after +executing it once. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +When @value{GDBN} is configured for a particular environment, it +understands debugging information in whatever format is the standard +generated for that environment; you may use either a @sc{gnu} compiler, or +other compilers that adhere to the local conventions. +Best results are usually obtained from @sc{gnu} compilers; for example, +using @code{@value{NGCC}} you can generate debugging information for +optimized code. + +For most kinds of object files, with the exception of old SVR3 systems +using COFF, the @code{symbol-file} command does not normally read the +symbol table in full right away. Instead, it scans the symbol table +quickly to find which source files and which symbols are present. The +details are read later, one source file at a time, as they are needed. + +The purpose of this two-stage reading strategy is to make @value{GDBN} +start up faster. For the most part, it is invisible except for +occasional pauses while the symbol table details for a particular source +file are being read. (The @code{set verbose} command can turn these +pauses into messages if desired. @xref{Messages/Warnings, ,Optional +Warnings and Messages}.) + +We have not implemented the two-stage strategy for COFF yet. When the +symbol table is stored in COFF format, @code{symbol-file} reads the +symbol table data in full right away. Note that ``stabs-in-COFF'' +still does the two-stage strategy, since the debug info is actually +in stabs format. + +@kindex readnow +@cindex reading symbols immediately +@cindex symbols, reading immediately +@item symbol-file @r{[} -readnow @r{]} @var{filename} +@itemx file @r{[} -readnow @r{]} @var{filename} +You can override the @value{GDBN} two-stage strategy for reading symbol +tables by using the @samp{-readnow} option with any of the commands that +load symbol table information, if you want to be sure @value{GDBN} has the +entire symbol table available. + +@cindex @code{-readnever}, option for symbol-file command +@cindex never read symbols +@cindex symbols, never read +@item symbol-file @r{[} -readnever @r{]} @var{filename} +@itemx file @r{[} -readnever @r{]} @var{filename} +You can instruct @value{GDBN} to never read the symbolic information +contained in @var{filename} by using the @samp{-readnever} option. +@xref{--readnever}. + +@c FIXME: for now no mention of directories, since this seems to be in +@c flux. 13mar1992 status is that in theory GDB would look either in +@c current dir or in same dir as myprog; but issues like competing +@c GDB's, or clutter in system dirs, mean that in practice right now +@c only current dir is used. FFish says maybe a special GDB hierarchy +@c (eg rooted in val of env var GDBSYMS) could exist for mappable symbol +@c files. + +@anchor{core-file command} +@kindex core-file +@item core-file @r{[}@var{filename}@r{]} +@itemx core +Specify the whereabouts of a core dump file to be used as the ``contents +of memory''. Traditionally, core files contain only some parts of the +address space of the process that generated them; @value{GDBN} can access the +executable file itself for other parts. + +@code{core-file} with no argument specifies that no core file is +to be used. + +Note that the core file is ignored when your program is actually running +under @value{GDBN}. So, if you have been running your program and you +wish to debug a core file instead, you must kill the subprocess in which +the program is running. To do this, use the @code{kill} command +(@pxref{Kill Process, ,Killing the Child Process}). + +@kindex add-symbol-file +@cindex dynamic linking +@item add-symbol-file @var{filename} @r{[} -readnow @r{|} -readnever @r{]} @r{[} -o @var{offset} @r{]} @r{[} @var{textaddress} @r{]} @r{[} -s @var{section} @var{address} @dots{} @r{]} +The @code{add-symbol-file} command reads additional symbol table +information from the file @var{filename}. You would use this command +when @var{filename} has been dynamically loaded (by some other means) +into the program that is running. The @var{textaddress} parameter gives +the memory address at which the file's text section has been loaded. +You can additionally specify the base address of other sections using +an arbitrary number of @samp{-s @var{section} @var{address}} pairs. +If a section is omitted, @value{GDBN} will use its default addresses +as found in @var{filename}. Any @var{address} or @var{textaddress} +can be given as an expression. + +If an optional @var{offset} is specified, it is added to the start +address of each section, except those for which the address was +specified explicitly. + +The symbol table of the file @var{filename} is added to the symbol table +originally read with the @code{symbol-file} command. You can use the +@code{add-symbol-file} command any number of times; the new symbol data +thus read is kept in addition to the old. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +Changes can be reverted using the command @code{remove-symbol-file}. + +@cindex relocatable object files, reading symbols from +@cindex object files, relocatable, reading symbols from +@cindex reading symbols from relocatable object files +@cindex symbols, reading from relocatable object files +@cindex @file{.o} files, reading symbols from +Although @var{filename} is typically a shared library file, an +executable file, or some other object file which has been fully +relocated for loading into a process, you can also load symbolic +information from relocatable @file{.o} files, as long as: + +@itemize @bullet +@item +the file's symbolic information refers only to linker symbols defined in +that file, not to symbols defined by other object files, +@item +every section the file's symbolic information refers to has actually +been loaded into the inferior, as it appears in the file, and +@item +you can determine the address at which every section was loaded, and +provide these to the @code{add-symbol-file} command. +@end itemize + +@noindent +Some embedded operating systems, like Sun Chorus and VxWorks, can load +relocatable files into an already running program; such systems +typically make the requirements above easy to meet. However, it's +important to recognize that many native systems use complex link +procedures (@code{.linkonce} section factoring and C@t{++} constructor table +assembly, for example) that make the requirements difficult to meet. In +general, one cannot assume that using @code{add-symbol-file} to read a +relocatable object file's symbolic information will have the same effect +as linking the relocatable object file into the program in the normal +way. + +@code{add-symbol-file} does not repeat if you press @key{RET} after using it. + +@kindex remove-symbol-file +@item remove-symbol-file @var{filename} +@item remove-symbol-file -a @var{address} +Remove a symbol file added via the @code{add-symbol-file} command. The +file to remove can be identified by its @var{filename} or by an @var{address} +that lies within the boundaries of this symbol file in memory. Example: + +@smallexample +(@value{GDBP}) add-symbol-file /home/user/gdb/mylib.so 0x7ffff7ff9480 +add symbol table from file "/home/user/gdb/mylib.so" at + .text_addr = 0x7ffff7ff9480 +(y or n) y +Reading symbols from /home/user/gdb/mylib.so... +(@value{GDBP}) remove-symbol-file -a 0x7ffff7ff9480 +Remove symbol table from file "/home/user/gdb/mylib.so"? (y or n) y +(@value{GDBP}) +@end smallexample + +The @var{address} can be any expression which evaluates to an address. + +@code{remove-symbol-file} does not repeat if you press @key{RET} after using it. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@kindex add-symbol-file-from-memory +@cindex @code{syscall DSO} +@cindex load symbols from memory +@item add-symbol-file-from-memory @var{address} +Load symbols from the given @var{address} in a dynamically loaded +object file whose image is mapped directly into the inferior's memory. +For example, the Linux kernel maps a @code{syscall DSO} into each +process's address space; this DSO provides kernel-specific code for +some system calls. The argument can be any expression whose +evaluation yields the address of the file's shared object file header. +For this command to work, you must have used @code{symbol-file} or +@code{exec-file} commands in advance. + +@kindex section +@item section @var{section} @var{addr} +The @code{section} command changes the base address of the named +@var{section} of the exec file to @var{addr}. This can be used if the +exec file does not contain section addresses, (such as in the +@code{a.out} format), or when the addresses specified in the file +itself are wrong. Each section must be changed separately. The +@code{info files} command, described below, lists all the sections and +their addresses. + +@kindex info files +@kindex info target +@item info files +@itemx info target +@code{info files} and @code{info target} are synonymous; both print the +current target (@pxref{Targets, ,Specifying a Debugging Target}), +including the names of the executable and core dump files currently in +use by @value{GDBN}, and the files from which symbols were loaded. The +command @code{help target} lists all possible targets rather than +current ones. + +@kindex maint info sections +@item maint info sections @r{[}-all-objects@r{]} @r{[}@var{filter-list}@r{]} +Another command that can give you extra information about program sections +is @code{maint info sections}. In addition to the section information +displayed by @code{info files}, this command displays the flags and file +offset of each section in the executable and core dump files. + +When @samp{-all-objects} is passed then sections from all loaded object +files, including shared libraries, are printed. + +The optional @var{filter-list} is a space separated list of filter +keywords. Sections that match any one of the filter criteria will be +printed. There are two types of filter: + +@table @code +@item @var{section-name} +Display information about any section named @var{section-name}. +@item @var{section-flag} +Display information for any section with @var{section-flag}. The +section flags that @value{GDBN} currently knows about are: +@table @code +@item ALLOC +Section will have space allocated in the process when loaded. +Set for all sections except those containing debug information. +@item LOAD +Section will be loaded from the file into the child process memory. +Set for pre-initialized code and data, clear for @code{.bss} sections. +@item RELOC +Section needs to be relocated before loading. +@item READONLY +Section cannot be modified by the child process. +@item CODE +Section contains executable code only. +@item DATA +Section contains data only (no executable code). +@item ROM +Section will reside in ROM. +@item CONSTRUCTOR +Section contains data for constructor/destructor lists. +@item HAS_CONTENTS +Section is not empty. +@item NEVER_LOAD +An instruction to the linker to not output the section. +@item COFF_SHARED_LIBRARY +A notification to the linker that the section contains +COFF shared library information. +@item IS_COMMON +Section contains common symbols. +@end table +@end table + +@kindex maint info target-sections +@item maint info target-sections +This command prints @value{GDBN}'s internal section table. For each +target @value{GDBN} maintains a table containing the allocatable +sections from all currently mapped objects, along with information +about where the section is mapped. + +@kindex set trust-readonly-sections +@cindex read-only sections +@item set trust-readonly-sections on +Tell @value{GDBN} that readonly sections in your object file +really are read-only (i.e.@: that their contents will not change). +In that case, @value{GDBN} can fetch values from these sections +out of the object file, rather than from the target program. +For some targets (notably embedded ones), this can be a significant +enhancement to debugging performance. + +The default is off. + +@item set trust-readonly-sections off +Tell @value{GDBN} not to trust readonly sections. This means that +the contents of the section might change while the program is running, +and must therefore be fetched from the target when needed. + +@item show trust-readonly-sections +Show the current setting of trusting readonly sections. +@end table + +All file-specifying commands allow both absolute and relative file names +as arguments. @value{GDBN} always converts the file name to an absolute file +name and remembers it that way. + +@cindex shared libraries +@anchor{Shared Libraries} +@value{GDBN} supports @sc{gnu}/Linux, MS-Windows, SunOS, +Darwin/Mach-O, SVr4, IBM RS/6000 AIX, FDPIC (FR-V), and +DSBT (TIC6X) shared libraries. + +On MS-Windows @value{GDBN} must be linked with the Expat library to support +shared libraries. @xref{Expat}. + +@value{GDBN} automatically loads symbol definitions from shared libraries +when you use the @code{run} command, or when you examine a core file. +(Before you issue the @code{run} command, @value{GDBN} does not understand +references to a function in a shared library, however---unless you are +debugging a core file). + +@c FIXME: some @value{GDBN} release may permit some refs to undef +@c FIXME...symbols---eg in a break cmd---assuming they are from a shared +@c FIXME...lib; check this from time to time when updating manual + +There are times, however, when you may wish to not automatically load +symbol definitions from shared libraries, such as when they are +particularly large or there are many of them. + +To control the automatic loading of shared library symbols, use the +commands: + +@table @code +@kindex set auto-solib-add +@item set auto-solib-add @var{mode} +If @var{mode} is @code{on}, symbols from all shared object libraries +will be loaded automatically when the inferior begins execution, you +attach to an independently started inferior, or when the dynamic linker +informs @value{GDBN} that a new library has been loaded. If @var{mode} +is @code{off}, symbols must be loaded manually, using the +@code{sharedlibrary} command. The default value is @code{on}. + +@cindex memory used for symbol tables +If your program uses lots of shared libraries with debug info that +takes large amounts of memory, you can decrease the @value{GDBN} +memory footprint by preventing it from automatically loading the +symbols from shared libraries. To that end, type @kbd{set +auto-solib-add off} before running the inferior, then load each +library whose debug symbols you do need with @kbd{sharedlibrary +@var{regexp}}, where @var{regexp} is a regular expression that matches +the libraries whose symbols you want to be loaded. + +@kindex show auto-solib-add +@item show auto-solib-add +Display the current autoloading mode. +@end table + +@cindex load shared library +To explicitly load shared library symbols, use the @code{sharedlibrary} +command: + +@table @code +@kindex info sharedlibrary +@kindex info share +@item info share @var{regex} +@itemx info sharedlibrary @var{regex} +Print the names of the shared libraries which are currently loaded +that match @var{regex}. If @var{regex} is omitted then print +all shared libraries that are loaded. + +@kindex info dll +@item info dll @var{regex} +This is an alias of @code{info sharedlibrary}. + +@kindex sharedlibrary +@kindex share +@item sharedlibrary @var{regex} +@itemx share @var{regex} +Load shared object library symbols for files matching a +Unix regular expression. +As with files loaded automatically, it only loads shared libraries +required by your program for a core file or after typing @code{run}. If +@var{regex} is omitted all shared libraries required by your program are +loaded. + +@item nosharedlibrary +@kindex nosharedlibrary +@cindex unload symbols from shared libraries +Unload all shared object library symbols. This discards all symbols +that have been loaded from all shared libraries. Symbols from shared +libraries that were loaded by explicit user requests are not +discarded. +@end table + +Sometimes you may wish that @value{GDBN} stops and gives you control +when any of shared library events happen. The best way to do this is +to use @code{catch load} and @code{catch unload} (@pxref{Set +Catchpoints}). + +@value{GDBN} also supports the @code{set stop-on-solib-events} +command for this. This command exists for historical reasons. It is +less useful than setting a catchpoint, because it does not allow for +conditions or commands as a catchpoint does. + +@table @code +@item set stop-on-solib-events +@kindex set stop-on-solib-events +This command controls whether @value{GDBN} should give you control +when the dynamic linker notifies it about some shared library event. +The most common event of interest is loading or unloading of a new +shared library. + +@item show stop-on-solib-events +@kindex show stop-on-solib-events +Show whether @value{GDBN} stops and gives you control when shared +library events happen. +@end table + +Shared libraries are also supported in many cross or remote debugging +configurations. @value{GDBN} needs to have access to the target's libraries; +this can be accomplished either by providing copies of the libraries +on the host system, or by asking @value{GDBN} to automatically retrieve the +libraries from the target. If copies of the target libraries are +provided, they need to be the same as the target libraries, although the +copies on the target can be stripped as long as the copies on the host are +not. + +@cindex where to look for shared libraries +For remote debugging, you need to tell @value{GDBN} where the target +libraries are, so that it can load the correct copies---otherwise, it +may try to load the host's libraries. @value{GDBN} has two variables +to specify the search directories for target libraries. + +@table @code +@cindex prefix for executable and shared library file names +@cindex system root, alternate +@kindex set solib-absolute-prefix +@kindex set sysroot +@item set sysroot @var{path} +Use @var{path} as the system root for the program being debugged. Any +absolute shared library paths will be prefixed with @var{path}; many +runtime loaders store the absolute paths to the shared library in the +target program's memory. When starting processes remotely, and when +attaching to already-running processes (local or remote), their +executable filenames will be prefixed with @var{path} if reported to +@value{GDBN} as absolute by the operating system. If you use +@code{set sysroot} to find executables and shared libraries, they need +to be laid out in the same way that they are on the target, with +e.g.@: a @file{/bin}, @file{/lib} and @file{/usr/lib} hierarchy under +@var{path}. + +If @var{path} starts with the sequence @file{target:} and the target +system is remote then @value{GDBN} will retrieve the target binaries +from the remote system. This is only supported when using a remote +target that supports the @code{remote get} command (@pxref{File +Transfer,,Sending files to a remote system}). The part of @var{path} +following the initial @file{target:} (if present) is used as system +root prefix on the remote file system. If @var{path} starts with the +sequence @file{remote:} this is converted to the sequence +@file{target:} by @code{set sysroot}@footnote{Historically the +functionality to retrieve binaries from the remote system was +provided by prefixing @var{path} with @file{remote:}}. If you want +to specify a local system root using a directory that happens to be +named @file{target:} or @file{remote:}, you need to use some +equivalent variant of the name like @file{./target:}. + +For targets with an MS-DOS based filesystem, such as MS-Windows, +@value{GDBN} tries prefixing a few variants of the target +absolute file name with @var{path}. But first, on Unix hosts, +@value{GDBN} converts all backslash directory separators into forward +slashes, because the backslash is not a directory separator on Unix: + +@smallexample + c:\foo\bar.dll @result{} c:/foo/bar.dll +@end smallexample + +Then, @value{GDBN} attempts prefixing the target file name with +@var{path}, and looks for the resulting file name in the host file +system: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/c:/foo/bar.dll +@end smallexample + +If that does not find the binary, @value{GDBN} tries removing +the @samp{:} character from the drive spec, both for convenience, and, +for the case of the host file system not supporting file names with +colons: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/c/foo/bar.dll +@end smallexample + +This makes it possible to have a system root that mirrors a target +with more than one drive. E.g., you may want to setup your local +copies of the target system shared libraries like so (note @samp{c} vs +@samp{z}): + +@smallexample + @file{/path/to/sysroot/c/sys/bin/foo.dll} + @file{/path/to/sysroot/c/sys/bin/bar.dll} + @file{/path/to/sysroot/z/sys/bin/bar.dll} +@end smallexample + +@noindent +and point the system root at @file{/path/to/sysroot}, so that +@value{GDBN} can find the correct copies of both +@file{c:\sys\bin\foo.dll}, and @file{z:\sys\bin\bar.dll}. + +If that still does not find the binary, @value{GDBN} tries +removing the whole drive spec from the target file name: + +@smallexample + c:/foo/bar.dll @result{} /path/to/sysroot/foo/bar.dll +@end smallexample + +This last lookup makes it possible to not care about the drive name, +if you don't want or need to. + +The @code{set solib-absolute-prefix} command is an alias for @code{set +sysroot}. + +@cindex default system root +@cindex @samp{--with-sysroot} +You can set the default system root by using the configure-time +@samp{--with-sysroot} option. If the system root is inside +@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or +@samp{--exec-prefix}), then the default system root will be updated +automatically if the installed @value{GDBN} is moved to a new +location. + +@kindex show sysroot +@item show sysroot +Display the current executable and shared library prefix. + +@kindex set solib-search-path +@item set solib-search-path @var{path} +If this variable is set, @var{path} is a colon-separated list of +directories to search for shared libraries. @samp{solib-search-path} +is used after @samp{sysroot} fails to locate the library, or if the +path to the library is relative instead of absolute. If you want to +use @samp{solib-search-path} instead of @samp{sysroot}, be sure to set +@samp{sysroot} to a nonexistent directory to prevent @value{GDBN} from +finding your host's libraries. @samp{sysroot} is preferred; setting +it to a nonexistent directory may interfere with automatic loading +of shared library symbols. + +@kindex show solib-search-path +@item show solib-search-path +Display the current shared library search path. + +@cindex DOS file-name semantics of file names. +@kindex set target-file-system-kind (unix|dos-based|auto) +@kindex show target-file-system-kind +@item set target-file-system-kind @var{kind} +Set assumed file system kind for target reported file names. + +Shared library file names as reported by the target system may not +make sense as is on the system @value{GDBN} is running on. For +example, when remote debugging a target that has MS-DOS based file +system semantics, from a Unix host, the target may be reporting to +@value{GDBN} a list of loaded shared libraries with file names such as +@file{c:\Windows\kernel32.dll}. On Unix hosts, there's no concept of +drive letters, so the @samp{c:\} prefix is not normally understood as +indicating an absolute file name, and neither is the backslash +normally considered a directory separator character. In that case, +the native file system would interpret this whole absolute file name +as a relative file name with no directory components. This would make +it impossible to point @value{GDBN} at a copy of the remote target's +shared libraries on the host using @code{set sysroot}, and impractical +with @code{set solib-search-path}. Setting +@code{target-file-system-kind} to @code{dos-based} tells @value{GDBN} +to interpret such file names similarly to how the target would, and to +map them to file names valid on @value{GDBN}'s native file system +semantics. The value of @var{kind} can be @code{"auto"}, in addition +to one of the supported file system kinds. In that case, @value{GDBN} +tries to determine the appropriate file system variant based on the +current target's operating system (@pxref{ABI, ,Configuring the +Current ABI}). The supported file system settings are: + +@table @code +@item unix +Instruct @value{GDBN} to assume the target file system is of Unix +kind. Only file names starting the forward slash (@samp{/}) character +are considered absolute, and the directory separator character is also +the forward slash. + +@item dos-based +Instruct @value{GDBN} to assume the target file system is DOS based. +File names starting with either a forward slash, or a drive letter +followed by a colon (e.g., @samp{c:}), are considered absolute, and +both the slash (@samp{/}) and the backslash (@samp{\\}) characters are +considered directory separators. + +@item auto +Instruct @value{GDBN} to use the file system kind associated with the +target operating system (@pxref{ABI, ,Configuring the Current ABI}). +This is the default. +@end table +@end table + +@cindex file name canonicalization +@cindex base name differences +When processing file names provided by the user, @value{GDBN} +frequently needs to compare them to the file names recorded in the +program's debug info. Normally, @value{GDBN} compares just the +@dfn{base names} of the files as strings, which is reasonably fast +even for very large programs. (The base name of a file is the last +portion of its name, after stripping all the leading directories.) +This shortcut in comparison is based upon the assumption that files +cannot have more than one base name. This is usually true, but +references to files that use symlinks or similar filesystem +facilities violate that assumption. If your program records files +using such facilities, or if you provide file names to @value{GDBN} +using symlinks etc., you can set @code{basenames-may-differ} to +@code{true} to instruct @value{GDBN} to completely canonicalize each +pair of file names it needs to compare. This will make file-name +comparisons accurate, but at a price of a significant slowdown. + +@table @code +@item set basenames-may-differ +@kindex set basenames-may-differ +Set whether a source file may have multiple base names. + +@item show basenames-may-differ +@kindex show basenames-may-differ +Show whether a source file may have multiple base names. +@end table + +@node File Caching +@section File Caching +@cindex caching of opened files +@cindex caching of bfd objects + +To speed up file loading, and reduce memory usage, @value{GDBN} will +reuse the @code{bfd} objects used to track open files. @xref{Top, , +BFD, bfd, The Binary File Descriptor Library}. The following commands +allow visibility and control of the caching behavior. + +@table @code +@kindex maint info bfds +@item maint info bfds +This prints information about each @code{bfd} object that is known to +@value{GDBN}. + +@kindex maint set bfd-sharing +@kindex maint show bfd-sharing +@kindex bfd caching +@item maint set bfd-sharing +@item maint show bfd-sharing +Control whether @code{bfd} objects can be shared. When sharing is +enabled @value{GDBN} reuses already open @code{bfd} objects rather +than reopening the same file. Turning sharing off does not cause +already shared @code{bfd} objects to be unshared, but all future files +that are opened will create a new @code{bfd} object. Similarly, +re-enabling sharing does not cause multiple existing @code{bfd} +objects to be collapsed into a single shared @code{bfd} object. + +@kindex set debug bfd-cache @var{level} +@kindex bfd caching +@item set debug bfd-cache @var{level} +Turns on debugging of the bfd cache, setting the level to @var{level}. + +@kindex show debug bfd-cache +@kindex bfd caching +@item show debug bfd-cache +Show the current debugging level of the bfd cache. +@end table + +@node Separate Debug Files +@section Debugging Information in Separate Files +@cindex separate debugging information files +@cindex debugging information in separate files +@cindex @file{.debug} subdirectories +@cindex debugging information directory, global +@cindex global debugging information directories +@cindex build ID, and separate debugging files +@cindex @file{.build-id} directory + +@value{GDBN} allows you to put a program's debugging information in a +file separate from the executable itself, in a way that allows +@value{GDBN} to find and load the debugging information automatically. +Since debugging information can be very large---sometimes larger +than the executable code itself---some systems distribute debugging +information for their executables in separate files, which users can +install only when they need to debug a problem. + +@value{GDBN} supports two ways of specifying the separate debug info +file: + +@itemize @bullet +@item +The executable contains a @dfn{debug link} that specifies the name of +the separate debug info file. The separate debug file's name is +usually @file{@var{executable}.debug}, where @var{executable} is the +name of the corresponding executable file without leading directories +(e.g., @file{ls.debug} for @file{/usr/bin/ls}). In addition, the +debug link specifies a 32-bit @dfn{Cyclic Redundancy Check} (CRC) +checksum for the debug file, which @value{GDBN} uses to validate that +the executable and the debug file came from the same build. + +@item +@anchor{build ID} +The executable contains a @dfn{build ID}, a unique bit string that is +also present in the corresponding debug info file. (This is supported +only on some operating systems, when using the ELF or PE file formats +for binary files and the @sc{gnu} Binutils.) For more details about +this feature, see the description of the @option{--build-id} +command-line option in @ref{Options, , Command Line Options, ld, +The GNU Linker}. The debug info file's name is not specified +explicitly by the build ID, but can be computed from the build ID, see +below. +@end itemize + +Depending on the way the debug info file is specified, @value{GDBN} +uses two different methods of looking for the debug file: + +@itemize @bullet +@item +For the ``debug link'' method, @value{GDBN} looks up the named file in +the directory of the executable file, then in a subdirectory of that +directory named @file{.debug}, and finally under each one of the +global debug directories, in a subdirectory whose name is identical to +the leading directories of the executable's absolute file name. (On +MS-Windows/MS-DOS, the drive letter of the executable's leading +directories is converted to a one-letter subdirectory, i.e.@: +@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows +filesystems disallow colons in file names.) + +@item +For the ``build ID'' method, @value{GDBN} looks in the +@file{.build-id} subdirectory of each one of the global debug directories for +a file named @file{@var{nn}/@var{nnnnnnnn}.debug}, where @var{nn} are the +first 2 hex characters of the build ID bit string, and @var{nnnnnnnn} +are the rest of the bit string. (Real build ID strings are 32 or more +hex characters, not 10.) @value{GDBN} can automatically query +@code{debuginfod} servers using build IDs in order to download separate debug +files that cannot be found locally. For more information see @ref{Debuginfod}. +@end itemize + +So, for example, suppose you ask @value{GDBN} to debug +@file{/usr/bin/ls}, which has a debug link that specifies the +file @file{ls.debug}, and a build ID whose value in hex is +@code{abcdef1234}. If the list of the global debug directories includes +@file{/usr/lib/debug}, then @value{GDBN} will look for the following +debug information files, in the indicated order: + +@itemize @minus +@item +@file{/usr/lib/debug/.build-id/ab/cdef1234.debug} +@item +@file{/usr/bin/ls.debug} +@item +@file{/usr/bin/.debug/ls.debug} +@item +@file{/usr/lib/debug/usr/bin/ls.debug}. +@end itemize + +If the debug file still has not been found and @code{debuginfod} +(@pxref{Debuginfod}) is enabled, @value{GDBN} will attempt to download the +file from @code{debuginfod} servers. + +@anchor{debug-file-directory} +Global debugging info directories default to what is set by @value{GDBN} +configure option @option{--with-separate-debug-dir} and augmented by the +colon-separated list of directories provided via @value{GDBN} configure +option @option{--additional-debug-dirs}. During @value{GDBN} run you can +also set the global debugging info directories, and view the list +@value{GDBN} is currently using. + +@table @code + +@kindex set debug-file-directory +@item set debug-file-directory @var{directories} +Set the directories which @value{GDBN} searches for separate debugging +information files to @var{directory}. Multiple path components can be set +concatenating them by a path separator. + +@kindex show debug-file-directory +@item show debug-file-directory +Show the directories @value{GDBN} searches for separate debugging +information files. + +@end table + +@cindex @code{.gnu_debuglink} sections +@cindex debug link sections +A debug link is a special section of the executable file named +@code{.gnu_debuglink}. The section must contain: + +@itemize +@item +A filename, with any leading directory components removed, followed by +a zero byte, +@item +zero to three bytes of padding, as needed to reach the next four-byte +boundary within the section, and +@item +a four-byte CRC checksum, stored in the same endianness used for the +executable file itself. The checksum is computed on the debugging +information file's full contents by the function given below, passing +zero as the @var{crc} argument. +@end itemize + +Any executable file format can carry a debug link, as long as it can +contain a section named @code{.gnu_debuglink} with the contents +described above. + +@cindex @code{.note.gnu.build-id} sections +@cindex build ID sections +The build ID is a special section in the executable file (and in other +ELF binary files that @value{GDBN} may consider). This section is +often named @code{.note.gnu.build-id}, but that name is not mandatory. +It contains unique identification for the built files---the ID remains +the same across multiple builds of the same build tree. The default +algorithm SHA1 produces 160 bits (40 hexadecimal characters) of the +content for the build ID string. The same section with an identical +value is present in the original built binary with symbols, in its +stripped variant, and in the separate debugging information file. + +The debugging information file itself should be an ordinary +executable, containing a full set of linker symbols, sections, and +debugging information. The sections of the debugging information file +should have the same names, addresses, and sizes as the original file, +but they need not contain any data---much like a @code{.bss} section +in an ordinary executable. + +The @sc{gnu} binary utilities (Binutils) package includes the +@samp{objcopy} utility that can produce +the separated executable / debugging information file pairs using the +following commands: + +@smallexample +@kbd{objcopy --only-keep-debug foo foo.debug} +@kbd{strip -g foo} +@end smallexample + +@noindent +These commands remove the debugging +information from the executable file @file{foo} and place it in the file +@file{foo.debug}. You can use the first, second or both methods to link the +two files: + +@itemize @bullet +@item +The debug link method needs the following additional command to also leave +behind a debug link in @file{foo}: + +@smallexample +@kbd{objcopy --add-gnu-debuglink=foo.debug foo} +@end smallexample + +Ulrich Drepper's @file{elfutils} package, starting with version 0.53, contains +a version of the @code{strip} command such that the command @kbd{strip foo -f +foo.debug} has the same functionality as the two @code{objcopy} commands and +the @code{ln -s} command above, together. + +@item +Build ID gets embedded into the main executable using @code{ld --build-id} or +the @value{NGCC} counterpart @code{gcc -Wl,--build-id}. Build ID support plus +compatibility fixes for debug files separation are present in @sc{gnu} binary +utilities (Binutils) package since version 2.18. +@end itemize + +@noindent + +@cindex CRC algorithm definition +The CRC used in @code{.gnu_debuglink} is the CRC-32 defined in +IEEE 802.3 using the polynomial: + +@c TexInfo requires naked braces for multi-digit exponents for Tex +@c output, but this causes HTML output to barf. HTML has to be set using +@c raw commands. So we end up having to specify this equation in 2 +@c different ways! +@ifhtml +@display +@html + x32 + x26 + x23 + x22 + x16 + x12 + x11 + + x10 + x8 + x7 + x5 + x4 + x2 + x + 1 +@end html +@end display +@end ifhtml +@ifnothtml +@display + @math{x^{32} + x^{26} + x^{23} + x^{22} + x^{16} + x^{12} + x^{11}} + @math{+ x^{10} + x^8 + x^7 + x^5 + x^4 + x^2 + x + 1} +@end display +@end ifnothtml + +The function is computed byte at a time, taking the least +significant bit of each byte first. The initial pattern +@code{0xffffffff} is used, to ensure leading zeros affect the CRC and +the final result is inverted to ensure trailing zeros also affect the +CRC. + +@emph{Note:} This is the same CRC polynomial as used in handling the +@dfn{Remote Serial Protocol} @code{qCRC} packet (@pxref{qCRC packet}). +However in the case of the Remote Serial Protocol, the CRC is computed +@emph{most} significant bit first, and the result is not inverted, so +trailing zeros have no effect on the CRC value. + +To complete the description, we show below the code of the function +which produces the CRC used in @code{.gnu_debuglink}. Inverting the +initially supplied @code{crc} argument means that an initial call to +this function passing in zero will start computing the CRC using +@code{0xffffffff}. + +@kindex gnu_debuglink_crc32 +@smallexample +unsigned long +gnu_debuglink_crc32 (unsigned long crc, + unsigned char *buf, size_t len) +@{ + static const unsigned long crc32_table[256] = + @{ + 0x00000000, 0x77073096, 0xee0e612c, 0x990951ba, 0x076dc419, + 0x706af48f, 0xe963a535, 0x9e6495a3, 0x0edb8832, 0x79dcb8a4, + 0xe0d5e91e, 0x97d2d988, 0x09b64c2b, 0x7eb17cbd, 0xe7b82d07, + 0x90bf1d91, 0x1db71064, 0x6ab020f2, 0xf3b97148, 0x84be41de, + 0x1adad47d, 0x6ddde4eb, 0xf4d4b551, 0x83d385c7, 0x136c9856, + 0x646ba8c0, 0xfd62f97a, 0x8a65c9ec, 0x14015c4f, 0x63066cd9, + 0xfa0f3d63, 0x8d080df5, 0x3b6e20c8, 0x4c69105e, 0xd56041e4, + 0xa2677172, 0x3c03e4d1, 0x4b04d447, 0xd20d85fd, 0xa50ab56b, + 0x35b5a8fa, 0x42b2986c, 0xdbbbc9d6, 0xacbcf940, 0x32d86ce3, + 0x45df5c75, 0xdcd60dcf, 0xabd13d59, 0x26d930ac, 0x51de003a, + 0xc8d75180, 0xbfd06116, 0x21b4f4b5, 0x56b3c423, 0xcfba9599, + 0xb8bda50f, 0x2802b89e, 0x5f058808, 0xc60cd9b2, 0xb10be924, + 0x2f6f7c87, 0x58684c11, 0xc1611dab, 0xb6662d3d, 0x76dc4190, + 0x01db7106, 0x98d220bc, 0xefd5102a, 0x71b18589, 0x06b6b51f, + 0x9fbfe4a5, 0xe8b8d433, 0x7807c9a2, 0x0f00f934, 0x9609a88e, + 0xe10e9818, 0x7f6a0dbb, 0x086d3d2d, 0x91646c97, 0xe6635c01, + 0x6b6b51f4, 0x1c6c6162, 0x856530d8, 0xf262004e, 0x6c0695ed, + 0x1b01a57b, 0x8208f4c1, 0xf50fc457, 0x65b0d9c6, 0x12b7e950, + 0x8bbeb8ea, 0xfcb9887c, 0x62dd1ddf, 0x15da2d49, 0x8cd37cf3, + 0xfbd44c65, 0x4db26158, 0x3ab551ce, 0xa3bc0074, 0xd4bb30e2, + 0x4adfa541, 0x3dd895d7, 0xa4d1c46d, 0xd3d6f4fb, 0x4369e96a, + 0x346ed9fc, 0xad678846, 0xda60b8d0, 0x44042d73, 0x33031de5, + 0xaa0a4c5f, 0xdd0d7cc9, 0x5005713c, 0x270241aa, 0xbe0b1010, + 0xc90c2086, 0x5768b525, 0x206f85b3, 0xb966d409, 0xce61e49f, + 0x5edef90e, 0x29d9c998, 0xb0d09822, 0xc7d7a8b4, 0x59b33d17, + 0x2eb40d81, 0xb7bd5c3b, 0xc0ba6cad, 0xedb88320, 0x9abfb3b6, + 0x03b6e20c, 0x74b1d29a, 0xead54739, 0x9dd277af, 0x04db2615, + 0x73dc1683, 0xe3630b12, 0x94643b84, 0x0d6d6a3e, 0x7a6a5aa8, + 0xe40ecf0b, 0x9309ff9d, 0x0a00ae27, 0x7d079eb1, 0xf00f9344, + 0x8708a3d2, 0x1e01f268, 0x6906c2fe, 0xf762575d, 0x806567cb, + 0x196c3671, 0x6e6b06e7, 0xfed41b76, 0x89d32be0, 0x10da7a5a, + 0x67dd4acc, 0xf9b9df6f, 0x8ebeeff9, 0x17b7be43, 0x60b08ed5, + 0xd6d6a3e8, 0xa1d1937e, 0x38d8c2c4, 0x4fdff252, 0xd1bb67f1, + 0xa6bc5767, 0x3fb506dd, 0x48b2364b, 0xd80d2bda, 0xaf0a1b4c, + 0x36034af6, 0x41047a60, 0xdf60efc3, 0xa867df55, 0x316e8eef, + 0x4669be79, 0xcb61b38c, 0xbc66831a, 0x256fd2a0, 0x5268e236, + 0xcc0c7795, 0xbb0b4703, 0x220216b9, 0x5505262f, 0xc5ba3bbe, + 0xb2bd0b28, 0x2bb45a92, 0x5cb36a04, 0xc2d7ffa7, 0xb5d0cf31, + 0x2cd99e8b, 0x5bdeae1d, 0x9b64c2b0, 0xec63f226, 0x756aa39c, + 0x026d930a, 0x9c0906a9, 0xeb0e363f, 0x72076785, 0x05005713, + 0x95bf4a82, 0xe2b87a14, 0x7bb12bae, 0x0cb61b38, 0x92d28e9b, + 0xe5d5be0d, 0x7cdcefb7, 0x0bdbdf21, 0x86d3d2d4, 0xf1d4e242, + 0x68ddb3f8, 0x1fda836e, 0x81be16cd, 0xf6b9265b, 0x6fb077e1, + 0x18b74777, 0x88085ae6, 0xff0f6a70, 0x66063bca, 0x11010b5c, + 0x8f659eff, 0xf862ae69, 0x616bffd3, 0x166ccf45, 0xa00ae278, + 0xd70dd2ee, 0x4e048354, 0x3903b3c2, 0xa7672661, 0xd06016f7, + 0x4969474d, 0x3e6e77db, 0xaed16a4a, 0xd9d65adc, 0x40df0b66, + 0x37d83bf0, 0xa9bcae53, 0xdebb9ec5, 0x47b2cf7f, 0x30b5ffe9, + 0xbdbdf21c, 0xcabac28a, 0x53b39330, 0x24b4a3a6, 0xbad03605, + 0xcdd70693, 0x54de5729, 0x23d967bf, 0xb3667a2e, 0xc4614ab8, + 0x5d681b02, 0x2a6f2b94, 0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, + 0x2d02ef8d + @}; + unsigned char *end; + + crc = ~crc & 0xffffffff; + for (end = buf + len; buf < end; ++buf) + crc = crc32_table[(crc ^ *buf) & 0xff] ^ (crc >> 8); + return ~crc & 0xffffffff; +@} +@end smallexample + +@noindent +This computation does not apply to the ``build ID'' method. + +@node MiniDebugInfo +@section Debugging information in a special section +@cindex separate debug sections +@cindex @samp{.gnu_debugdata} section + +Some systems ship pre-built executables and libraries that have a +special @samp{.gnu_debugdata} section. This feature is called +@dfn{MiniDebugInfo}. This section holds an LZMA-compressed object and +is used to supply extra symbols for backtraces. + +The intent of this section is to provide extra minimal debugging +information for use in simple backtraces. It is not intended to be a +replacement for full separate debugging information (@pxref{Separate +Debug Files}). The example below shows the intended use; however, +@value{GDBN} does not currently put restrictions on what sort of +debugging information might be included in the section. + +@value{GDBN} has support for this extension. If the section exists, +then it is used provided that no other source of debugging information +can be found, and that @value{GDBN} was configured with LZMA support. + +This section can be easily created using @command{objcopy} and other +standard utilities: + +@smallexample +# Extract the dynamic symbols from the main binary, there is no need +# to also have these in the normal symbol table. +nm -D @var{binary} --format=posix --defined-only \ + | awk '@{ print $1 @}' | sort > dynsyms + +# Extract all the text (i.e. function) symbols from the debuginfo. +# (Note that we actually also accept "D" symbols, for the benefit +# of platforms like PowerPC64 that use function descriptors.) +nm @var{binary} --format=posix --defined-only \ + | awk '@{ if ($2 == "T" || $2 == "t" || $2 == "D") print $1 @}' \ + | sort > funcsyms + +# Keep all the function symbols not already in the dynamic symbol +# table. +comm -13 dynsyms funcsyms > keep_symbols + +# Separate full debug info into debug binary. +objcopy --only-keep-debug @var{binary} debug + +# Copy the full debuginfo, keeping only a minimal set of symbols and +# removing some unnecessary sections. +objcopy -S --remove-section .gdb_index --remove-section .comment \ + --keep-symbols=keep_symbols debug mini_debuginfo + +# Drop the full debug info from the original binary. +strip --strip-all -R .comment @var{binary} + +# Inject the compressed data into the .gnu_debugdata section of the +# original binary. +xz mini_debuginfo +objcopy --add-section .gnu_debugdata=mini_debuginfo.xz @var{binary} +@end smallexample + +@node Index Files +@section Index Files Speed Up @value{GDBN} +@cindex index files +@cindex @samp{.gdb_index} section + +When @value{GDBN} finds a symbol file, it scans the symbols in the +file in order to construct an internal symbol table. This lets most +@value{GDBN} operations work quickly---at the cost of a delay early +on. For large programs, this delay can be quite lengthy, so +@value{GDBN} provides a way to build an index, which speeds up +startup. + +For convenience, @value{GDBN} comes with a program, +@command{gdb-add-index}, which can be used to add the index to a +symbol file. It takes the symbol file as its only argument: + +@smallexample +$ gdb-add-index symfile +@end smallexample + +@xref{gdb-add-index}. + +It is also possible to do the work manually. Here is what +@command{gdb-add-index} does behind the curtains. + +The index is stored as a section in the symbol file. @value{GDBN} can +write the index to a file, then you can put it into the symbol file +using @command{objcopy}. + +To create an index file, use the @code{save gdb-index} command: + +@table @code +@item save gdb-index [-dwarf-5] @var{directory} +@kindex save gdb-index +Create index files for all symbol files currently known by +@value{GDBN}. For each known @var{symbol-file}, this command by +default creates it produces a single file +@file{@var{symbol-file}.gdb-index}. If you invoke this command with +the @option{-dwarf-5} option, it produces 2 files: +@file{@var{symbol-file}.debug_names} and +@file{@var{symbol-file}.debug_str}. The files are created in the +given @var{directory}. + +The @var{directory} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. +@end table + +Once you have created an index file you can merge it into your symbol +file, here named @file{symfile}, using @command{objcopy}: + +@smallexample +$ objcopy --add-section .gdb_index=symfile.gdb-index \ + --set-section-flags .gdb_index=readonly symfile symfile +@end smallexample + +Or for @code{-dwarf-5}: + +@smallexample +$ objcopy --dump-section .debug_str=symfile.debug_str.new symfile +$ cat symfile.debug_str >>symfile.debug_str.new +$ objcopy --add-section .debug_names=symfile.gdb-index \ + --set-section-flags .debug_names=readonly \ + --update-section .debug_str=symfile.debug_str.new symfile symfile +@end smallexample + +@value{GDBN} will normally ignore older versions of @file{.gdb_index} +sections that have been deprecated. Usually they are deprecated because +they are missing a new feature or have performance issues. +To tell @value{GDBN} to use a deprecated index section anyway +specify @code{set use-deprecated-index-sections on}. +The default is @code{off}. +This can speed up startup, but may result in some functionality being lost. +@xref{Index Section Format}. + +@emph{Warning:} Setting @code{use-deprecated-index-sections} to @code{on} +must be done before gdb reads the file. The following will not work: + +@smallexample +$ gdb -ex "set use-deprecated-index-sections on" +@end smallexample + +Instead you must do, for example, + +@smallexample +$ gdb -iex "set use-deprecated-index-sections on" +@end smallexample + +Indices only work when using DWARF debugging information, not stabs. + +@subsection Automatic symbol index cache + +@cindex automatic symbol index cache +It is possible for @value{GDBN} to automatically save a copy of this index in a +cache on disk and retrieve it from there when loading the same binary in the +future. This feature can be turned on with @kbd{set index-cache enabled on}. +The following commands can be used to tweak the behavior of the index cache. + +@table @code + +@kindex set index-cache +@item set index-cache enabled on +@itemx set index-cache enabled off +Enable or disable the use of the symbol index cache. + +@item set index-cache directory @var{directory} +@kindex show index-cache +@itemx show index-cache directory +Set/show the directory where index files will be saved. + +The default value for this directory depends on the host platform. On +most systems, the index is cached in the @file{gdb} subdirectory of +the directory pointed to by the @env{XDG_CACHE_HOME} environment +variable, if it is defined, else in the @file{.cache/gdb} subdirectory +of your home directory. However, on some systems, the default may +differ according to local convention. + +There is no limit on the disk space used by index cache. It is perfectly safe +to delete the content of that directory to free up disk space. + +@item show index-cache stats +Print the number of cache hits and misses since the launch of @value{GDBN}. + +@end table + +@subsection Building the index with GNU @command{gold} + +The GNU @command{gold} linker can write the index at link time into +the resulting ELF file, by passing the @command{--gdb-index} flag to +@command{gold}. + +This is especially helpful if you intend to build a program and immediately +run it under @value{GDBN}. You may find that it is faster overall for +the linker to write the index while it has the relevant information in +memory anyways, rather than re-reloading the data from disk with +@command{gdb-add-index}, or debugging the program without an index at +all, especially for large programs. + +@node Debug Names +@section Extensions to @samp{.debug_names} +@cindex index files +@cindex @samp{.debug_names} section + +The DWARF specification documents an optional index section called +@samp{.debug_names}. @value{GDBN} can both read and create this +section. However, in order to work with @value{GDBN}, some extensions +were necessary. + +@value{GDBN} uses the augmentation string @samp{GDB2}. Earlier +versions used the string @samp{GDB}, but these versions of the index +are no longer supported. + +@value{GDBN} does not use the specified hash table. Therefore, +because this hash table is optional, @value{GDBN} also does not write +it. + +@value{GDBN} also generates and uses some extra index attributes: +@table @code +@item DW_IDX_GNU_internal +This has the value @samp{0x2000}. It is a flag that, when set, +indicates that the associated entry has @code{static} linkage. + +@item DW_IDX_GNU_main +This has the value @samp{0x2002}. It is a flag that, when set, +indicates that the associated entry is the program's @code{main}. + +@item DW_IDX_GNU_language +This has the value @samp{0x2003}. It is @samp{DW_LANG_} constant, +indicating the language of the associated entry. + +@item DW_IDX_GNU_linkage_name +This has the value @samp{0x2004}. It is a flag that, when set, +indicates that the associated entry is a linkage name, and not a +source name. +@end table + +@node Symbol Errors +@section Errors Reading Symbol Files + +While reading a symbol file, @value{GDBN} occasionally encounters problems, +such as symbol types it does not recognize, or known bugs in compiler +output. By default, @value{GDBN} does not notify you of such problems, since +they are relatively common and primarily of interest to people +debugging compilers. If you are interested in seeing information +about ill-constructed symbol tables, you can either ask @value{GDBN} to print +only one message about each such type of problem, no matter how many +times the problem occurs; or you can ask @value{GDBN} to print more messages, +to see how many times the problems occur, with the @code{set +complaints} command (@pxref{Messages/Warnings, ,Optional Warnings and +Messages}). + +The messages currently printed, and their meanings, include: + +@table @code +@item inner block not inside outer block in @var{symbol} + +The symbol information shows where symbol scopes begin and end +(such as at the start of a function or a block of statements). This +error indicates that an inner scope block is not fully contained +in its outer scope blocks. + +@value{GDBN} circumvents the problem by treating the inner block as if it had +the same scope as the outer block. In the error message, @var{symbol} +may be shown as ``@code{(don't know)}'' if the outer block is not a +function. + +@item block at @var{address} out of order + +The symbol information for symbol scope blocks should occur in +order of increasing addresses. This error indicates that it does not +do so. + +@value{GDBN} does not circumvent this problem, and has trouble +locating symbols in the source file whose symbols it is reading. (You +can often determine what source file is affected by specifying +@code{set verbose on}. @xref{Messages/Warnings, ,Optional Warnings and +Messages}.) + +@item bad block start address patched + +The symbol information for a symbol scope block has a start address +smaller than the address of the preceding source line. This is known +to occur in the SunOS 4.1.1 (and earlier) C compiler. + +@value{GDBN} circumvents the problem by treating the symbol scope block as +starting on the previous source line. + +@item bad string table offset in symbol @var{n} + +@cindex foo +Symbol number @var{n} contains a pointer into the string table which is +larger than the size of the string table. + +@value{GDBN} circumvents the problem by considering the symbol to have the +name @code{foo}, which may cause other problems if many symbols end up +with this name. + +@item unknown symbol type @code{0x@var{nn}} + +The symbol information contains new data types that @value{GDBN} does +not yet know how to read. @code{0x@var{nn}} is the symbol type of the +uncomprehended information, in hexadecimal. + +@value{GDBN} circumvents the error by ignoring this symbol information. +This usually allows you to debug your program, though certain symbols +are not accessible. If you encounter such a problem and feel like +debugging it, you can debug @code{@value{GDBP}} with itself, breakpoint +on @code{complain}, then go up to the function @code{read_dbx_symtab} +and examine @code{*bufp} to see the symbol. + +@item stub type has NULL name + +@value{GDBN} could not find the full definition for a struct or class. + +@item const/volatile indicator missing (ok if using g++ v1.x), got@dots{} +The symbol information for a C@t{++} member function is missing some +information that recent versions of the compiler should have output for +it. + +@item info mismatch between compiler and debugger + +@value{GDBN} could not parse a type specification output by the compiler. + +@end table + +@node Data Files +@section GDB Data Files + +@cindex prefix for data files +@value{GDBN} will sometimes read an auxiliary data file. These files +are kept in a directory known as the @dfn{data directory}. + +You can set the data directory's name, and view the name @value{GDBN} +is currently using. + +@table @code +@kindex set data-directory +@item set data-directory @var{directory} +Set the directory which @value{GDBN} searches for auxiliary data files +to @var{directory}. + +@kindex show data-directory +@item show data-directory +Show the directory @value{GDBN} searches for auxiliary data files. +@end table + +@cindex default data directory +@cindex @samp{--with-gdb-datadir} +You can set the default data directory by using the configure-time +@samp{--with-gdb-datadir} option. If the data directory is inside +@value{GDBN}'s configured binary prefix (set with @samp{--prefix} or +@samp{--exec-prefix}), then the default data directory will be updated +automatically if the installed @value{GDBN} is moved to a new +location. + +The data directory may also be specified with the +@code{--data-directory} command line option. +@xref{Mode Options}. + +@node Targets +@chapter Specifying a Debugging Target + +@cindex debugging target +A @dfn{target} is the execution environment occupied by your program. + +Often, @value{GDBN} runs in the same host environment as your program; +in that case, the debugging target is specified as a side effect when +you use the @code{file} or @code{core} commands. When you need more +flexibility---for example, running @value{GDBN} on a physically separate +host, or controlling a standalone system over a serial port or a +realtime system over a TCP/IP connection---you can use the @code{target} +command to specify one of the target types configured for @value{GDBN} +(@pxref{Target Commands, ,Commands for Managing Targets}). + +@cindex target architecture +It is possible to build @value{GDBN} for several different @dfn{target +architectures}. When @value{GDBN} is built like that, you can choose +one of the available architectures with the @kbd{set architecture} +command. + +@table @code +@kindex set architecture +@kindex show architecture +@item set architecture @var{arch} +This command sets the current target architecture to @var{arch}. The +value of @var{arch} can be @code{"auto"}, in addition to one of the +supported architectures. + +@item show architecture +Show the current target architecture. + +@item set processor +@itemx processor +@kindex set processor +@kindex show processor +These are alias commands for, respectively, @code{set architecture} +and @code{show architecture}. +@end table + +@menu +* Active Targets:: Active targets +* Target Commands:: Commands for managing targets +* Byte Order:: Choosing target byte order +@end menu + +@node Active Targets +@section Active Targets + +@cindex stacking targets +@cindex active targets +@cindex multiple targets + +There are multiple classes of targets such as: processes, executable files or +recording sessions. Core files belong to the process class, making core file +and process mutually exclusive. Otherwise, @value{GDBN} can work concurrently +on multiple active targets, one in each class. This allows you to (for +example) start a process and inspect its activity, while still having access to +the executable file after the process finishes. Or if you start process +recording (@pxref{Reverse Execution}) and @code{reverse-step} there, you are +presented a virtual layer of the recording target, while the process target +remains stopped at the chronologically last point of the process execution. + +Use the @code{core-file} and @code{exec-file} commands to select a new core +file or executable target (@pxref{Files, ,Commands to Specify Files}). To +specify as a target a process that is already running, use the @code{attach} +command (@pxref{Attach, ,Debugging an Already-running Process}). + +@node Target Commands +@section Commands for Managing Targets + +@table @code +@item target @var{type} @var{parameters} +Connects the @value{GDBN} host environment to a target machine or +process. A target is typically a protocol for talking to debugging +facilities. You use the argument @var{type} to specify the type or +protocol of the target machine. + +Further @var{parameters} are interpreted by the target protocol, but +typically include things like device names or host names to connect +with, process numbers, and baud rates. + +The @code{target} command does not repeat if you press @key{RET} again +after executing the command. + +@kindex help target +@item help target +Displays the names of all targets available. To display targets +currently selected, use either @code{info target} or @code{info files} +(@pxref{Files, ,Commands to Specify Files}). + +@item help target @var{name} +Describe a particular target, including any parameters necessary to +select it. + +@kindex set gnutarget +@item set gnutarget @var{args} +@value{GDBN} uses its own library BFD to read your files. @value{GDBN} +knows whether it is reading an @dfn{executable}, +a @dfn{core}, or a @dfn{.o} file; however, you can specify the file format +with the @code{set gnutarget} command. Unlike most @code{target} commands, +with @code{gnutarget} the @code{target} refers to a program, not a machine. + +@quotation +@emph{Warning:} To specify a file format with @code{set gnutarget}, +you must know the actual BFD name. +@end quotation + +@noindent +@xref{Files, , Commands to Specify Files}. + +@kindex show gnutarget +@item show gnutarget +Use the @code{show gnutarget} command to display what file format +@code{gnutarget} is set to read. If you have not set @code{gnutarget}, +@value{GDBN} will determine the file format for each file automatically, +and @code{show gnutarget} displays @samp{The current BFD target is "auto"}. +@end table + +@cindex common targets +Here are some common targets (available, or not, depending on the GDB +configuration): + +@table @code +@kindex target +@item target exec @var{program} +@cindex executable file target +An executable file. @samp{target exec @var{program}} is the same as +@samp{exec-file @var{program}}. + +The @var{program} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@item target core @var{filename} +@cindex core dump file target +A core dump file. @samp{target core @var{filename}} is the same as +@samp{core-file @var{filename}}. + +The @var{filename} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@item target remote @var{medium} +@cindex remote target +A remote system connected to @value{GDBN} via a serial line or network +connection. This command tells @value{GDBN} to use its own remote +protocol over @var{medium} for debugging. @xref{Remote Debugging}. + +For example, if you have a board connected to @file{/dev/ttya} on the +machine running @value{GDBN}, you could say: + +@smallexample +target remote /dev/ttya +@end smallexample + +@code{target remote} supports the @code{load} command. This is only +useful if you have some other way of getting the stub to the target +system, and you can put it somewhere in memory where it won't get +clobbered by the download. + +@item target sim @r{[}@var{simargs}@r{]} @dots{} +@cindex built-in simulator target +Builtin CPU simulator. @value{GDBN} includes simulators for most architectures. +In general, +@smallexample + target sim + load + run +@end smallexample +@noindent +works; however, you cannot assume that a specific memory map, device +drivers, or even basic I/O is available, although some simulators do +provide these. For info about any processor-specific simulator details, +see the appropriate section in @ref{Embedded Processors, ,Embedded +Processors}. + +@item target native +@cindex native target +Setup for local/native process debugging. Useful to make the +@code{run} command spawn native processes (likewise @code{attach}, +etc.@:) even when @code{set auto-connect-native-target} is @code{off} +(@pxref{set auto-connect-native-target}). + +@end table + +Different targets are available on different configurations of @value{GDBN}; +your configuration may have more or fewer targets. + +Many remote targets require you to download the executable's code once +you've successfully established a connection. You may wish to control +various aspects of this process. + +@table @code + +@item set hash +@kindex set hash@r{, for remote monitors} +@cindex hash mark while downloading +This command controls whether a hash mark @samp{#} is displayed while +downloading a file to the remote monitor. If on, a hash mark is +displayed after each S-record is successfully downloaded to the +monitor. + +@item show hash +@kindex show hash@r{, for remote monitors} +Show the current status of displaying the hash mark. + +@item set debug monitor +@kindex set debug monitor +@cindex display remote monitor communications +Enable or disable display of communications messages between +@value{GDBN} and the remote monitor. + +@item show debug monitor +@kindex show debug monitor +Show the current status of displaying communications between +@value{GDBN} and the remote monitor. +@end table + +@table @code + +@kindex load @var{filename} @var{offset} +@item load @var{filename} @var{offset} +@anchor{load} +Depending on what remote debugging facilities are configured into +@value{GDBN}, the @code{load} command may be available. Where it exists, it +is meant to make @var{filename} (an executable) available for debugging +on the remote system---by downloading, or dynamic linking, for example. +@code{load} also records the @var{filename} symbol table in @value{GDBN}, like +the @code{add-symbol-file} command. + +If your @value{GDBN} does not have a @code{load} command, attempting to +execute it gets the error message ``@code{You can't do that when your +target is @dots{}}'' + +The file is loaded at whatever address is specified in the executable. +For some object file formats, you can specify the load address when you +link the program; for other formats, like a.out, the object file format +specifies a fixed address. +@c FIXME! This would be a good place for an xref to the GNU linker doc. + +It is also possible to tell @value{GDBN} to load the executable file at a +specific offset described by the optional argument @var{offset}. When +@var{offset} is provided, @var{filename} must also be provided. + +Depending on the remote side capabilities, @value{GDBN} may be able to +load programs into flash memory. + +@code{load} does not repeat if you press @key{RET} again after using it. +@end table + +@table @code + +@kindex flash-erase +@item flash-erase +@anchor{flash-erase} + +Erases all known flash memory regions on the target. + +@end table + +@node Byte Order +@section Choosing Target Byte Order + +@cindex choosing target byte order +@cindex target byte order + +Some types of processors, such as the @acronym{MIPS}, PowerPC, and Renesas SH, +offer the ability to run either big-endian or little-endian byte +orders. Usually the executable or symbol will include a bit to +designate the endian-ness, and you will not need to worry about +which to use. However, you may still find it useful to adjust +@value{GDBN}'s idea of processor endian-ness manually. + +@table @code +@kindex set endian +@item set endian big +Instruct @value{GDBN} to assume the target is big-endian. + +@item set endian little +Instruct @value{GDBN} to assume the target is little-endian. + +@item set endian auto +Instruct @value{GDBN} to use the byte order associated with the +executable. + +@item show endian +Display @value{GDBN}'s current idea of the target byte order. + +@end table + +If the @code{set endian auto} mode is in effect and no executable has +been selected, then the endianness used is the last one chosen either +by one of the @code{set endian big} and @code{set endian little} +commands or by inferring from the last executable used. If no +endianness has been previously chosen, then the default for this mode +is inferred from the target @value{GDBN} has been built for, and is +@code{little} if the name of the target CPU has an @code{el} suffix +and @code{big} otherwise. + +Note that these commands merely adjust interpretation of symbolic +data on the host, and that they have absolutely no effect on the +target system. + + +@node Remote Debugging +@chapter Debugging Remote Programs +@cindex remote debugging + +If you are trying to debug a program running on a machine that cannot run +@value{GDBN} in the usual way, it is often useful to use remote debugging. +For example, you might use remote debugging on an operating system kernel, +or on a small system which does not have a general purpose operating system +powerful enough to run a full-featured debugger. + +Some configurations of @value{GDBN} have special serial or TCP/IP interfaces +to make this work with particular debugging targets. In addition, +@value{GDBN} comes with a generic serial protocol (specific to @value{GDBN}, +but not specific to any particular target system) which you can use if you +write the remote stubs---the code that runs on the remote system to +communicate with @value{GDBN}. + +Other remote targets may be available in your +configuration of @value{GDBN}; use @code{help target} to list them. + +@menu +* Connecting:: Connecting to a remote target +* File Transfer:: Sending files to a remote system +* Server:: Using the gdbserver program +* Remote Configuration:: Remote configuration +* Remote Stub:: Implementing a remote stub +@end menu + +@node Connecting +@section Connecting to a Remote Target +@cindex remote debugging, connecting +@cindex @code{gdbserver}, connecting +@cindex remote debugging, types of connections +@cindex @code{gdbserver}, types of connections +@cindex @code{gdbserver}, @code{target remote} mode +@cindex @code{gdbserver}, @code{target extended-remote} mode + +This section describes how to connect to a remote target, including the +types of connections and their differences, how to set up executable and +symbol files on the host and target, and the commands used for +connecting to and disconnecting from the remote target. + +@subsection Types of Remote Connections + +@value{GDBN} supports two types of remote connections, @code{target remote} +mode and @code{target extended-remote} mode. Note that many remote targets +support only @code{target remote} mode. There are several major +differences between the two types of connections, enumerated here: + +@table @asis + +@cindex remote debugging, detach and program exit +@item Result of detach or program exit +@strong{With target remote mode:} When the debugged program exits or you +detach from it, @value{GDBN} disconnects from the target. When using +@code{gdbserver}, @code{gdbserver} will exit. + +@strong{With target extended-remote mode:} When the debugged program exits or +you detach from it, @value{GDBN} remains connected to the target, even +though no program is running. You can rerun the program, attach to a +running program, or use @code{monitor} commands specific to the target. + +When using @code{gdbserver} in this case, it does not exit unless it was +invoked using the @option{--once} option. If the @option{--once} option +was not used, you can ask @code{gdbserver} to exit using the +@code{monitor exit} command (@pxref{Monitor Commands for gdbserver}). + +@item Specifying the program to debug +For both connection types you use the @code{file} command to specify the +program on the host system. If you are using @code{gdbserver} there are +some differences in how to specify the location of the program on the +target. + +@strong{With target remote mode:} You must either specify the program to debug +on the @code{gdbserver} command line or use the @option{--attach} option +(@pxref{Attaching to a program,,Attaching to a Running Program}). + +@cindex @option{--multi}, @code{gdbserver} option +@strong{With target extended-remote mode:} You may specify the program to debug +on the @code{gdbserver} command line, or you can load the program or attach +to it using @value{GDBN} commands after connecting to @code{gdbserver}. + +@anchor{--multi Option in Types of Remote Connnections} +You can start @code{gdbserver} without supplying an initial command to run +or process ID to attach. To do this, use the @option{--multi} command line +option. Then you can connect using @code{target extended-remote} and start +the program you want to debug (see below for details on using the +@code{run} command in this scenario). Note that the conditions under which +@code{gdbserver} terminates depend on how @value{GDBN} connects to it +(@code{target remote} or @code{target extended-remote}). The +@option{--multi} option to @code{gdbserver} has no influence on that. + +@item The @code{run} command +@strong{With target remote mode:} The @code{run} command is not +supported. Once a connection has been established, you can use all +the usual @value{GDBN} commands to examine and change data. The +remote program is already running, so you can use commands like +@kbd{step} and @kbd{continue}. + +@strong{With target extended-remote mode:} The @code{run} command is +supported. The @code{run} command uses the value set by +@code{set remote exec-file} (@pxref{set remote exec-file}) to select +the program to run. Command line arguments are supported, except for +wildcard expansion and I/O redirection (@pxref{Arguments}). + +If you specify the program to debug on the command line, then the +@code{run} command is not required to start execution, and you can +resume using commands like @kbd{step} and @kbd{continue} as with +@code{target remote} mode. + +@anchor{Attaching in Types of Remote Connections} +@item Attaching +@strong{With target remote mode:} The @value{GDBN} command @code{attach} is +not supported. To attach to a running program using @code{gdbserver}, you +must use the @option{--attach} option (@pxref{Running gdbserver}). + +@strong{With target extended-remote mode:} To attach to a running program, +you may use the @code{attach} command after the connection has been +established. If you are using @code{gdbserver}, you may also invoke +@code{gdbserver} using the @option{--attach} option +(@pxref{Running gdbserver}). + +Some remote targets allow @value{GDBN} to determine the executable file running +in the process the debugger is attaching to. In such a case, @value{GDBN} +uses the value of @code{exec-file-mismatch} to handle a possible mismatch +between the executable file name running in the process and the name of the +current exec-file loaded by @value{GDBN} (@pxref{set exec-file-mismatch}). + +@end table + +@anchor{Host and target files} +@subsection Host and Target Files +@cindex remote debugging, symbol files +@cindex symbol files, remote debugging + +@value{GDBN}, running on the host, needs access to symbol and debugging +information for your program running on the target. This requires +access to an unstripped copy of your program, and possibly any associated +symbol files. Note that this section applies equally to both @code{target +remote} mode and @code{target extended-remote} mode. + +Some remote targets (@pxref{qXfer executable filename read}, and +@pxref{Host I/O Packets}) allow @value{GDBN} to access program files over +the same connection used to communicate with @value{GDBN}. With such a +target, if the remote program is unstripped, the only command you need is +@code{target remote} (or @code{target extended-remote}). + +If the remote program is stripped, or the target does not support remote +program file access, start up @value{GDBN} using the name of the local +unstripped copy of your program as the first argument, or use the +@code{file} command. Use @code{set sysroot} to specify the location (on +the host) of target libraries (unless your @value{GDBN} was compiled with +the correct sysroot using @code{--with-sysroot}). Alternatively, you +may use @code{set solib-search-path} to specify how @value{GDBN} locates +target libraries. + +The symbol file and target libraries must exactly match the executable +and libraries on the target, with one exception: the files on the host +system should not be stripped, even if the files on the target system +are. Mismatched or missing files will lead to confusing results +during debugging. On @sc{gnu}/Linux targets, mismatched or missing +files may also prevent @code{gdbserver} from debugging multi-threaded +programs. + +@subsection Remote Connection Commands +@cindex remote connection commands +@value{GDBN} can communicate with the target over a serial line, a +local Unix domain socket, or +over an @acronym{IP} network using @acronym{TCP} or @acronym{UDP}. In +each case, @value{GDBN} uses the same protocol for debugging your +program; only the medium carrying the debugging packets varies. The +@code{target remote} and @code{target extended-remote} commands +establish a connection to the target. Both commands accept the same +arguments, which indicate the medium to use: + +@table @code + +@item target remote @var{serial-device} +@itemx target extended-remote @var{serial-device} +@cindex serial line, @code{target remote} +Use @var{serial-device} to communicate with the target. For example, +to use a serial line connected to the device named @file{/dev/ttyb}: + +@smallexample +target remote /dev/ttyb +@end smallexample + +If you're using a serial line, you may want to give @value{GDBN} the +@samp{--baud} option, or use the @code{set serial baud} command +(@pxref{Remote Configuration, set serial baud}) before the +@code{target} command. + +@item target remote @var{local-socket} +@itemx target extended-remote @var{local-socket} +@cindex local socket, @code{target remote} +@cindex Unix domain socket +Use @var{local-socket} to communicate with the target. For example, +to use a local Unix domain socket bound to the file system entry @file{/tmp/gdb-socket0}: + +@smallexample +target remote /tmp/gdb-socket0 +@end smallexample + +Note that this command has the same form as the command to connect +to a serial line. @value{GDBN} will automatically determine which +kind of file you have specified and will make the appropriate kind +of connection. +This feature is not available if the host system does not support +Unix domain sockets. + +@item target remote @code{@var{host}:@var{port}} +@itemx target remote @code{[@var{host}]:@var{port}} +@itemx target remote @code{tcp:@var{host}:@var{port}} +@itemx target remote @code{tcp:[@var{host}]:@var{port}} +@itemx target remote @code{tcp4:@var{host}:@var{port}} +@itemx target remote @code{tcp6:@var{host}:@var{port}} +@itemx target remote @code{tcp6:[@var{host}]:@var{port}} +@itemx target extended-remote @code{@var{host}:@var{port}} +@itemx target extended-remote @code{[@var{host}]:@var{port}} +@itemx target extended-remote @code{tcp:@var{host}:@var{port}} +@itemx target extended-remote @code{tcp:[@var{host}]:@var{port}} +@itemx target extended-remote @code{tcp4:@var{host}:@var{port}} +@itemx target extended-remote @code{tcp6:@var{host}:@var{port}} +@itemx target extended-remote @code{tcp6:[@var{host}]:@var{port}} +@cindex @acronym{TCP} port, @code{target remote} +Debug using a @acronym{TCP} connection to @var{port} on @var{host}. +The @var{host} may be either a host name, a numeric @acronym{IPv4} +address, or a numeric @acronym{IPv6} address (with or without the +square brackets to separate the address from the port); @var{port} +must be a decimal number. The @var{host} could be the target machine +itself, if it is directly connected to the net, or it might be a +terminal server which in turn has a serial line to the target. + +For example, to connect to port 2828 on a terminal server named +@code{manyfarms}: + +@smallexample +target remote manyfarms:2828 +@end smallexample + +To connect to port 2828 on a terminal server whose address is +@code{2001:0db8:85a3:0000:0000:8a2e:0370:7334}, you can either use the +square bracket syntax: + +@smallexample +target remote [2001:0db8:85a3:0000:0000:8a2e:0370:7334]:2828 +@end smallexample + +@noindent +or explicitly specify the @acronym{IPv6} protocol: + +@smallexample +target remote tcp6:2001:0db8:85a3:0000:0000:8a2e:0370:7334:2828 +@end smallexample + +This last example may be confusing to the reader, because there is no +visible separation between the hostname and the port number. +Therefore, we recommend the user to provide @acronym{IPv6} addresses +using square brackets for clarity. However, it is important to +mention that for @value{GDBN} there is no ambiguity: the number after +the last colon is considered to be the port number. + +If your remote target is actually running on the same machine as your +debugger session (e.g.@: a simulator for your target running on the +same host), you can omit the hostname. For example, to connect to +port 1234 on your local machine: + +@smallexample +target remote :1234 +@end smallexample +@noindent + +Note that the colon is still required here. + +@item target remote @code{udp:@var{host}:@var{port}} +@itemx target remote @code{udp:[@var{host}]:@var{port}} +@itemx target remote @code{udp4:@var{host}:@var{port}} +@itemx target remote @code{udp6:[@var{host}]:@var{port}} +@itemx target extended-remote @code{udp:@var{host}:@var{port}} +@itemx target extended-remote @code{udp:@var{host}:@var{port}} +@itemx target extended-remote @code{udp:[@var{host}]:@var{port}} +@itemx target extended-remote @code{udp4:@var{host}:@var{port}} +@itemx target extended-remote @code{udp6:@var{host}:@var{port}} +@itemx target extended-remote @code{udp6:[@var{host}]:@var{port}} +@cindex @acronym{UDP} port, @code{target remote} +Debug using @acronym{UDP} packets to @var{port} on @var{host}. For example, to +connect to @acronym{UDP} port 2828 on a terminal server named @code{manyfarms}: + +@smallexample +target remote udp:manyfarms:2828 +@end smallexample + +When using a @acronym{UDP} connection for remote debugging, you should +keep in mind that the `U' stands for ``Unreliable''. @acronym{UDP} +can silently drop packets on busy or unreliable networks, which will +cause havoc with your debugging session. + +@item target remote | @var{command} +@itemx target extended-remote | @var{command} +@cindex pipe, @code{target remote} to +Run @var{command} in the background and communicate with it using a +pipe. The @var{command} is a shell command, to be parsed and expanded +by the system's command shell, @code{/bin/sh}; it should expect remote +protocol packets on its standard input, and send replies on its +standard output. You could use this to run a stand-alone simulator +that speaks the remote debugging protocol, to make net connections +using programs like @code{ssh}, or for other similar tricks. + +If @var{command} closes its standard output (perhaps by exiting), +@value{GDBN} will try to send it a @code{SIGTERM} signal. (If the +program has already exited, this will have no effect.) + +@end table + +@cindex interrupting remote programs +@cindex remote programs, interrupting +Whenever @value{GDBN} is waiting for the remote program, if you type the +interrupt character (often @kbd{Ctrl-c}), @value{GDBN} attempts to stop the +program. This may or may not succeed, depending in part on the hardware +and the serial drivers the remote system uses. If you type the +interrupt character once again, @value{GDBN} displays this prompt: + +@smallexample +Interrupted while waiting for the program. +Give up (and stop debugging it)? (y or n) +@end smallexample + +In @code{target remote} mode, if you type @kbd{y}, @value{GDBN} abandons +the remote debugging session. (If you decide you want to try again later, +you can use @kbd{target remote} again to connect once more.) If you type +@kbd{n}, @value{GDBN} goes back to waiting. + +In @code{target extended-remote} mode, typing @kbd{n} will leave +@value{GDBN} connected to the target. + +@table @code +@kindex detach (remote) +@item detach +When you have finished debugging the remote program, you can use the +@code{detach} command to release it from @value{GDBN} control. +Detaching from the target normally resumes its execution, but the results +will depend on your particular remote stub. After the @code{detach} +command in @code{target remote} mode, @value{GDBN} is free to connect to +another target. In @code{target extended-remote} mode, @value{GDBN} is +still connected to the target. + +@kindex disconnect +@item disconnect +The @code{disconnect} command closes the connection to the target, and +the target is generally not resumed. It will wait for @value{GDBN} +(this instance or another one) to connect and continue debugging. After +the @code{disconnect} command, @value{GDBN} is again free to connect to +another target. + +@cindex send command to remote monitor +@cindex extend @value{GDBN} for remote targets +@cindex add new commands for external monitor +@kindex monitor +@item monitor @var{cmd} +This command allows you to send arbitrary commands directly to the +remote monitor. Since @value{GDBN} doesn't care about the commands it +sends like this, this command is the way to extend @value{GDBN}---you +can add new commands that only the external monitor will understand +and implement. +@end table + +@node File Transfer +@section Sending files to a remote system +@cindex remote target, file transfer +@cindex file transfer +@cindex sending files to remote systems + +Some remote targets offer the ability to transfer files over the same +connection used to communicate with @value{GDBN}. This is convenient +for targets accessible through other means, e.g.@: @sc{gnu}/Linux systems +running @code{gdbserver} over a network interface. For other targets, +e.g.@: embedded devices with only a single serial port, this may be +the only way to upload or download files. + +Not all remote targets support these commands. + +@table @code +@kindex remote put +@item remote put @var{hostfile} @var{targetfile} +Copy file @var{hostfile} from the host system (the machine running +@value{GDBN}) to @var{targetfile} on the target system. + +@kindex remote get +@item remote get @var{targetfile} @var{hostfile} +Copy file @var{targetfile} from the target system to @var{hostfile} +on the host system. + +@kindex remote delete +@item remote delete @var{targetfile} +Delete @var{targetfile} from the target system. + +@end table + +@node Server +@section Using the @code{gdbserver} Program + +@kindex gdbserver +@cindex remote connection without stubs +@code{gdbserver} is a control program for Unix-like systems, which +allows you to connect your program with a remote @value{GDBN} via +@code{target remote} or @code{target extended-remote}---but without +linking in the usual debugging stub. + +@code{gdbserver} is not a complete replacement for the debugging stubs, +because it requires essentially the same operating-system facilities +that @value{GDBN} itself does. In fact, a system that can run +@code{gdbserver} to connect to a remote @value{GDBN} could also run +@value{GDBN} locally! @code{gdbserver} is sometimes useful nevertheless, +because it is a much smaller program than @value{GDBN} itself. It is +also easier to port than all of @value{GDBN}, so you may be able to get +started more quickly on a new system by using @code{gdbserver}. +Finally, if you develop code for real-time systems, you may find that +the tradeoffs involved in real-time operation make it more convenient to +do as much development work as possible on another system, for example +by cross-compiling. You can use @code{gdbserver} to make a similar +choice for debugging. + +@value{GDBN} and @code{gdbserver} communicate via either a serial line +or a TCP connection, using the standard @value{GDBN} remote serial +protocol. + +@quotation +@emph{Warning:} @code{gdbserver} does not have any built-in security. +Do not run @code{gdbserver} connected to any public network; a +@value{GDBN} connection to @code{gdbserver} provides access to the +target system with the same privileges as the user running +@code{gdbserver}. +@end quotation + +@anchor{Running gdbserver} +@subsection Running @code{gdbserver} +@cindex arguments, to @code{gdbserver} +@cindex @code{gdbserver}, command-line arguments + +Run @code{gdbserver} on the target system. You need a copy of the +program you want to debug, including any libraries it requires. +@code{gdbserver} does not need your program's symbol table, so you can +strip the program if necessary to save space. @value{GDBN} on the host +system does all the symbol handling. + +To use the server, you must tell it how to communicate with @value{GDBN}; +the name of your program; and the arguments for your program. The usual +syntax is: + +@smallexample +target> gdbserver @var{comm} @var{program} [ @var{args} @dots{} ] +@end smallexample + +@var{comm} is either a device name (to use a serial line), or a TCP +hostname and portnumber, or @code{-} or @code{stdio} to use +stdin/stdout of @code{gdbserver}. +For example, to debug Emacs with the argument +@samp{foo.txt} and communicate with @value{GDBN} over the serial port +@file{/dev/com1}: + +@smallexample +target> gdbserver /dev/com1 emacs foo.txt +@end smallexample + +@code{gdbserver} waits passively for the host @value{GDBN} to communicate +with it. + +To use a TCP connection instead of a serial line: + +@smallexample +target> gdbserver host:2345 emacs foo.txt +@end smallexample + +The only difference from the previous example is the first argument, +specifying that you are communicating with the host @value{GDBN} via +TCP. The @samp{host:2345} argument means that @code{gdbserver} is to +expect a TCP connection from machine @samp{host} to local TCP port 2345. +(Currently, the @samp{host} part is ignored.) You can choose any number +you want for the port number as long as it does not conflict with any +TCP ports already in use on the target system (for example, @code{23} is +reserved for @code{telnet}).@footnote{If you choose a port number that +conflicts with another service, @code{gdbserver} prints an error message +and exits.} You must use the same port number with the host @value{GDBN} +@code{target remote} command. + +The @code{stdio} connection is useful when starting @code{gdbserver} +with ssh: + +@smallexample +(@value{GDBP}) target remote | ssh -T hostname gdbserver - hello +@end smallexample + +The @samp{-T} option to ssh is provided because we don't need a remote pty, +and we don't want escape-character handling. Ssh does this by default when +a command is provided, the flag is provided to make it explicit. +You could elide it if you want to. + +Programs started with stdio-connected gdbserver have @file{/dev/null} for +@code{stdin}, and @code{stdout},@code{stderr} are sent back to gdb for +display through a pipe connected to gdbserver. +Both @code{stdout} and @code{stderr} use the same pipe. + +@anchor{Attaching to a program} +@subsubsection Attaching to a Running Program +@cindex attach to a program, @code{gdbserver} +@cindex @option{--attach}, @code{gdbserver} option + +On some targets, @code{gdbserver} can also attach to running programs. +This is accomplished via the @code{--attach} argument. The syntax is: + +@smallexample +target> gdbserver --attach @var{comm} @var{pid} +@end smallexample + +@var{pid} is the process ID of a currently running process. It isn't +necessary to point @code{gdbserver} at a binary for the running process. + +In @code{target extended-remote} mode, you can also attach using the +@value{GDBN} attach command +(@pxref{Attaching in Types of Remote Connections}). + +@pindex pidof +You can debug processes by name instead of process ID if your target has the +@code{pidof} utility: + +@smallexample +target> gdbserver --attach @var{comm} `pidof @var{program}` +@end smallexample + +In case more than one copy of @var{program} is running, or @var{program} +has multiple threads, most versions of @code{pidof} support the +@code{-s} option to only return the first process ID. + +@subsubsection TCP port allocation lifecycle of @code{gdbserver} + +This section applies only when @code{gdbserver} is run to listen on a TCP +port. + +@code{gdbserver} normally terminates after all of its debugged processes have +terminated in @kbd{target remote} mode. On the other hand, for @kbd{target +extended-remote}, @code{gdbserver} stays running even with no processes left. +@value{GDBN} normally terminates the spawned debugged process on its exit, +which normally also terminates @code{gdbserver} in the @kbd{target remote} +mode. Therefore, when the connection drops unexpectedly, and @value{GDBN} +cannot ask @code{gdbserver} to kill its debugged processes, @code{gdbserver} +stays running even in the @kbd{target remote} mode. + +When @code{gdbserver} stays running, @value{GDBN} can connect to it again later. +Such reconnecting is useful for features like @ref{disconnected tracing}. For +completeness, at most one @value{GDBN} can be connected at a time. + +@cindex @option{--once}, @code{gdbserver} option +By default, @code{gdbserver} keeps the listening TCP port open, so that +subsequent connections are possible. However, if you start @code{gdbserver} +with the @option{--once} option, it will stop listening for any further +connection attempts after connecting to the first @value{GDBN} session. This +means no further connections to @code{gdbserver} will be possible after the +first one. It also means @code{gdbserver} will terminate after the first +connection with remote @value{GDBN} has closed, even for unexpectedly closed +connections and even in the @kbd{target extended-remote} mode. The +@option{--once} option allows reusing the same port number for connecting to +multiple instances of @code{gdbserver} running on the same host, since each +instance closes its port after the first connection. + +@anchor{Other Command-Line Arguments for gdbserver} +@subsubsection Other Command-Line Arguments for @code{gdbserver} + +You can use the @option{--multi} option to start @code{gdbserver} without +specifying a program to debug or a process to attach to. Then you can +attach in @code{target extended-remote} mode and run or attach to a +program. For more information, +@pxref{--multi Option in Types of Remote Connnections}. + +@cindex @option{--debug}, @code{gdbserver} option +The @option{--debug[=option1,option2,@dots{}]} option tells +@code{gdbserver} to display extra diagnostic information about the +debugging process. The options (@var{option1}, @var{option2}, etc) +control for which areas of @code{gdbserver} additional information +will be displayed, possible values are: + +@table @code +@item all +This enables all available diagnostic output. +@item threads +This enables diagnostic output related to threading. Currently other +general diagnostic output is included in this category, but this could +change in future releases of @code{gdbserver}. +@item event-loop +This enables event-loop specific diagnostic output. +@item remote +This enables diagnostic output related to the transfer of remote +protocol packets too and from the debugger. +@end table + +@noindent +If no options are passed to @option{--debug} then this is treated as +equivalent to @option{--debug=threads}. This could change in future +releases of @code{gdbserver}. The options passed to @option{--debug} +are processed left to right, and individual options can be prefixed +with the @kbd{-} (minus) character to disable diagnostic output from +this area, so it is possible to use: + +@smallexample + target> gdbserver --debug=all,-event-loop +@end smallexample + +@noindent +In order to enable all diagnostic output except that for the +event-loop. + +@cindex @option{--debug-file}, @code{gdbserver} option +@cindex @code{gdbserver}, send all debug output to a single file +The @option{--debug-file=@var{filename}} option tells @code{gdbserver} to +write any debug output to the given @var{filename}. These options are intended +for @code{gdbserver} development and for bug reports to the developers. + +@cindex @option{--debug-format}, @code{gdbserver} option +The @option{--debug-format=option1[,option2,...]} option tells +@code{gdbserver} to include additional information in each output. +Possible options are: + +@table @code +@item none +Turn off all extra information in debugging output. +@item all +Turn on all extra information in debugging output. +@item timestamps +Include a timestamp in each line of debugging output. +@end table + +Options are processed in order. Thus, for example, if @option{none} +appears last then no additional information is added to debugging output. + +@cindex @option{--wrapper}, @code{gdbserver} option +The @option{--wrapper} option specifies a wrapper to launch programs +for debugging. The option should be followed by the name of the +wrapper, then any command-line arguments to pass to the wrapper, then +@kbd{--} indicating the end of the wrapper arguments. + +@code{gdbserver} runs the specified wrapper program with a combined +command line including the wrapper arguments, then the name of the +program to debug, then any arguments to the program. The wrapper +runs until it executes your program, and then @value{GDBN} gains control. + +You can use any program that eventually calls @code{execve} with +its arguments as a wrapper. Several standard Unix utilities do +this, e.g.@: @code{env} and @code{nohup}. Any Unix shell script ending +with @code{exec "$@@"} will also work. + +For example, you can use @code{env} to pass an environment variable to +the debugged program, without setting the variable in @code{gdbserver}'s +environment: + +@smallexample +$ gdbserver --wrapper env LD_PRELOAD=libtest.so -- :2222 ./testprog +@end smallexample + +@cindex @option{--selftest} +The @option{--selftest} option runs the self tests in @code{gdbserver}: + +@smallexample +$ gdbserver --selftest +Ran 2 unit tests, 0 failed +@end smallexample + +These tests are disabled in release. +@subsection Connecting to @code{gdbserver} + +The basic procedure for connecting to the remote target is: +@itemize + +@item +Run @value{GDBN} on the host system. + +@item +Make sure you have the necessary symbol files +(@pxref{Host and target files}). +Load symbols for your application using the @code{file} command before you +connect. Use @code{set sysroot} to locate target libraries (unless your +@value{GDBN} was compiled with the correct sysroot using +@code{--with-sysroot}). + +@item +Connect to your target (@pxref{Connecting,,Connecting to a Remote Target}). +For TCP connections, you must start up @code{gdbserver} prior to using +the @code{target} command. Otherwise you may get an error whose +text depends on the host system, but which usually looks something like +@samp{Connection refused}. Don't use the @code{load} +command in @value{GDBN} when using @code{target remote} mode, since the +program is already on the target. + +@end itemize + +@anchor{Monitor Commands for gdbserver} +@subsection Monitor Commands for @code{gdbserver} +@cindex monitor commands, for @code{gdbserver} + +During a @value{GDBN} session using @code{gdbserver}, you can use the +@code{monitor} command to send special requests to @code{gdbserver}. +Here are the available commands. + +@table @code +@item monitor help +List the available monitor commands. + +@item monitor set debug off +Disable all internal logging from gdbserver. + +@item monitor set debug on +Enable some general logging from within gdbserver. Currently this is +equivalent to @kbd{monitor set debug threads on}, but this might +change in future releases of gdbserver. + +@item monitor set debug threads off +@itemx monitor set debug threads on +Disable or enable specific logging messages associated with thread +handling in gdbserver. Currently this category also includes +additional output not specifically related to thread handling, this +could change in future releases of gdbserver. + +@item monitor set debug remote off +@itemx monitor set debug remote on +Disable or enable specific logging messages associated with the remote +protocol (@pxref{Remote Protocol}). + +@item monitor set debug event-loop off +@itemx monitor set debug event-loop on +Disable or enable specific logging messages associated with +gdbserver's event-loop. + +@item monitor set debug-file filename +@itemx monitor set debug-file +Send any debug output to the given file, or to stderr. + +@item monitor set debug-format option1@r{[},option2,...@r{]} +Specify additional text to add to debugging messages. +Possible options are: + +@table @code +@item none +Turn off all extra information in debugging output. +@item all +Turn on all extra information in debugging output. +@item timestamps +Include a timestamp in each line of debugging output. +@end table + +Options are processed in order. Thus, for example, if @option{none} +appears last then no additional information is added to debugging output. + +@item monitor set libthread-db-search-path [PATH] +@cindex gdbserver, search path for @code{libthread_db} +When this command is issued, @var{path} is a colon-separated list of +directories to search for @code{libthread_db} (@pxref{Threads,,set +libthread-db-search-path}). If you omit @var{path}, +@samp{libthread-db-search-path} will be reset to its default value. + +The special entry @samp{$pdir} for @samp{libthread-db-search-path} is +not supported in @code{gdbserver}. + +@item monitor exit +Tell gdbserver to exit immediately. This command should be followed by +@code{disconnect} to close the debugging session. @code{gdbserver} will +detach from any attached processes and kill any processes it created. +Use @code{monitor exit} to terminate @code{gdbserver} at the end +of a multi-process mode debug session. + +@end table + +@subsection Tracepoints support in @code{gdbserver} +@cindex tracepoints support in @code{gdbserver} + +On some targets, @code{gdbserver} supports tracepoints, fast +tracepoints and static tracepoints. + +For fast or static tracepoints to work, a special library called the +@dfn{in-process agent} (IPA), must be loaded in the inferior process. +This library is built and distributed as an integral part of +@code{gdbserver}. In addition, support for static tracepoints +requires building the in-process agent library with static tracepoints +support. At present, the UST (LTTng Userspace Tracer, +@url{http://lttng.org/ust}) tracing engine is supported. This support +is automatically available if UST development headers are found in the +standard include path when @code{gdbserver} is built, or if +@code{gdbserver} was explicitly configured using @option{--with-ust} +to point at such headers. You can explicitly disable the support +using @option{--with-ust=no}. + +There are several ways to load the in-process agent in your program: + +@table @code +@item Specifying it as dependency at link time + +You can link your program dynamically with the in-process agent +library. On most systems, this is accomplished by adding +@code{-linproctrace} to the link command. + +@item Using the system's preloading mechanisms + +You can force loading the in-process agent at startup time by using +your system's support for preloading shared libraries. Many Unixes +support the concept of preloading user defined libraries. In most +cases, you do that by specifying @code{LD_PRELOAD=libinproctrace.so} +in the environment. See also the description of @code{gdbserver}'s +@option{--wrapper} command line option. + +@item Using @value{GDBN} to force loading the agent at run time + +On some systems, you can force the inferior to load a shared library, +by calling a dynamic loader function in the inferior that takes care +of dynamically looking up and loading a shared library. On most Unix +systems, the function is @code{dlopen}. You'll use the @code{call} +command for that. For example: + +@smallexample +(@value{GDBP}) call dlopen ("libinproctrace.so", ...) +@end smallexample + +Note that on most Unix systems, for the @code{dlopen} function to be +available, the program needs to be linked with @code{-ldl}. +@end table + +On systems that have a userspace dynamic loader, like most Unix +systems, when you connect to @code{gdbserver} using @code{target +remote}, you'll find that the program is stopped at the dynamic +loader's entry point, and no shared library has been loaded in the +program's address space yet, including the in-process agent. In that +case, before being able to use any of the fast or static tracepoints +features, you need to let the loader run and load the shared +libraries. The simplest way to do that is to run the program to the +main procedure. E.g., if debugging a C or C@t{++} program, start +@code{gdbserver} like so: + +@smallexample +$ gdbserver :9999 myprogram +@end smallexample + +Start GDB and connect to @code{gdbserver} like so, and run to main: + +@smallexample +$ gdb myprogram +(@value{GDBP}) target remote myhost:9999 +0x00007f215893ba60 in ?? () from /lib64/ld-linux-x86-64.so.2 +(@value{GDBP}) b main +(@value{GDBP}) continue +@end smallexample + +The in-process tracing agent library should now be loaded into the +process; you can confirm it with the @code{info sharedlibrary} +command, which will list @file{libinproctrace.so} as loaded in the +process. You are now ready to install fast tracepoints, list static +tracepoint markers, probe static tracepoints markers, and start +tracing. + +@node Remote Configuration +@section Remote Configuration + +@kindex set remote +@kindex show remote +This section documents the configuration options available when +debugging remote programs. For the options related to the File I/O +extensions of the remote protocol, see @ref{system, +system-call-allowed}. + +@table @code +@item set remoteaddresssize @var{bits} +@cindex address size for remote targets +@cindex bits in remote address +Set the maximum size of address in a memory packet to the specified +number of bits. @value{GDBN} will mask off the address bits above +that number, when it passes addresses to the remote target. The +default value is the number of bits in the target's address. + +@item show remoteaddresssize +Show the current value of remote address size in bits. + +@item set serial baud @var{n} +@cindex baud rate for remote targets +Set the baud rate for the remote serial I/O to @var{n} baud. The +value is used to set the speed of the serial port used for debugging +remote targets. + +@item show serial baud +Show the current speed of the remote connection. + +@item set serial parity @var{parity} +Set the parity for the remote serial I/O. Supported values of @var{parity} are: +@code{even}, @code{none}, and @code{odd}. The default is @code{none}. + +@item show serial parity +Show the current parity of the serial port. + +@item set remotebreak +@cindex interrupt remote programs +@cindex BREAK signal instead of Ctrl-C +@anchor{set remotebreak} +If set to on, @value{GDBN} sends a @code{BREAK} signal to the remote +when you type @kbd{Ctrl-c} to interrupt the program running +on the remote. If set to off, @value{GDBN} sends the @samp{Ctrl-C} +character instead. The default is off, since most remote systems +expect to see @samp{Ctrl-C} as the interrupt signal. + +@item show remotebreak +Show whether @value{GDBN} sends @code{BREAK} or @samp{Ctrl-C} to +interrupt the remote program. + +@item set remoteflow on +@itemx set remoteflow off +@kindex set remoteflow +Enable or disable hardware flow control (@code{RTS}/@code{CTS}) +on the serial port used to communicate to the remote target. + +@item show remoteflow +@kindex show remoteflow +Show the current setting of hardware flow control. + +@item set remotelogbase @var{base} +Set the base (a.k.a.@: radix) of logging serial protocol +communications to @var{base}. Supported values of @var{base} are: +@code{ascii}, @code{octal}, and @code{hex}. The default is +@code{ascii}. + +@item show remotelogbase +Show the current setting of the radix for logging remote serial +protocol. + +@item set remotelogfile @var{file} +@cindex record serial communications on file +Record remote serial communications on the named @var{file}. The +default is not to record at all. + +@item show remotelogfile +Show the current setting of the file name on which to record the +serial communications. + +@item set remotetimeout @var{num} +@cindex timeout for serial communications +@cindex remote timeout +Set the timeout limit to wait for the remote target to respond to +@var{num} seconds. The default is 2 seconds. + +@item show remotetimeout +Show the current number of seconds to wait for the remote target +responses. + +@cindex limit hardware breakpoints and watchpoints +@cindex remote target, limit break- and watchpoints +@anchor{set remote hardware-watchpoint-limit} +@anchor{set remote hardware-breakpoint-limit} +@item set remote hardware-watchpoint-limit @var{limit} +@itemx set remote hardware-breakpoint-limit @var{limit} +Restrict @value{GDBN} to using @var{limit} remote hardware watchpoints +or breakpoints. The @var{limit} can be set to 0 to disable hardware +watchpoints or breakpoints, and @code{unlimited} for unlimited +watchpoints or breakpoints. + +@item show remote hardware-watchpoint-limit +@itemx show remote hardware-breakpoint-limit +Show the current limit for the number of hardware watchpoints or +breakpoints that @value{GDBN} can use. + +@cindex limit hardware watchpoints length +@cindex remote target, limit watchpoints length +@anchor{set remote hardware-watchpoint-length-limit} +@item set remote hardware-watchpoint-length-limit @var{limit} +Restrict @value{GDBN} to using @var{limit} bytes for the maximum +length of a remote hardware watchpoint. A @var{limit} of 0 disables +hardware watchpoints and @code{unlimited} allows watchpoints of any +length. + +@item show remote hardware-watchpoint-length-limit +Show the current limit (in bytes) of the maximum length of +a remote hardware watchpoint. + +@item set remote exec-file @var{filename} +@itemx show remote exec-file +@anchor{set remote exec-file} +@cindex executable file, for remote target +Select the file used for @code{run} with @code{target +extended-remote}. This should be set to a filename valid on the +target system. If it is not set, the target will use a default +filename (e.g.@: the last program run). + +@item set remote interrupt-sequence +@cindex interrupt remote programs +@cindex select Ctrl-C, BREAK or BREAK-g +Allow the user to select one of @samp{Ctrl-C}, a @code{BREAK} or +@samp{BREAK-g} as the +sequence to the remote target in order to interrupt the execution. +@samp{Ctrl-C} is a default. Some system prefers @code{BREAK} which +is high level of serial line for some certain time. +Linux kernel prefers @samp{BREAK-g}, a.k.a Magic SysRq g. +It is @code{BREAK} signal followed by character @code{g}. + +@item show remote interrupt-sequence +Show which of @samp{Ctrl-C}, @code{BREAK} or @code{BREAK-g} +is sent by @value{GDBN} to interrupt the remote program. +@code{BREAK-g} is BREAK signal followed by @code{g} and +also known as Magic SysRq g. + +@item set remote interrupt-on-connect +@cindex send interrupt-sequence on start +Specify whether interrupt-sequence is sent to remote target when +@value{GDBN} connects to it. This is mostly needed when you debug +Linux kernel. Linux kernel expects @code{BREAK} followed by @code{g} +which is known as Magic SysRq g in order to connect @value{GDBN}. + +@item show remote interrupt-on-connect +Show whether interrupt-sequence is sent +to remote target when @value{GDBN} connects to it. + +@kindex set tcp +@kindex show tcp +@item set tcp auto-retry on +@cindex auto-retry, for remote TCP target +Enable auto-retry for remote TCP connections. This is useful if the remote +debugging agent is launched in parallel with @value{GDBN}; there is a race +condition because the agent may not become ready to accept the connection +before @value{GDBN} attempts to connect. When auto-retry is +enabled, if the initial attempt to connect fails, @value{GDBN} reattempts +to establish the connection using the timeout specified by +@code{set tcp connect-timeout}. + +@item set tcp auto-retry off +Do not auto-retry failed TCP connections. + +@item show tcp auto-retry +Show the current auto-retry setting. + +@item set tcp connect-timeout @var{seconds} +@itemx set tcp connect-timeout unlimited +@cindex connection timeout, for remote TCP target +@cindex timeout, for remote target connection +Set the timeout for establishing a TCP connection to the remote target to +@var{seconds}. The timeout affects both polling to retry failed connections +(enabled by @code{set tcp auto-retry on}) and waiting for connections +that are merely slow to complete, and represents an approximate cumulative +value. If @var{seconds} is @code{unlimited}, there is no timeout and +@value{GDBN} will keep attempting to establish a connection forever, +unless interrupted with @kbd{Ctrl-c}. The default is 15 seconds. + +@item show tcp connect-timeout +Show the current connection timeout setting. +@end table + +@cindex remote packets, enabling and disabling +The @value{GDBN} remote protocol autodetects the packets supported by +your debugging stub. If you need to override the autodetection, you +can use these commands to enable or disable individual packets. Each +packet can be set to @samp{on} (the remote target supports this +packet), @samp{off} (the remote target does not support this packet), +or @samp{auto} (detect remote target support for this packet). They +all default to @samp{auto}. For more information about each packet, +see @ref{Remote Protocol}. + +During normal use, you should not have to use any of these commands. +If you do, that may be a bug in your remote debugging stub, or a bug +in @value{GDBN}. You may want to report the problem to the +@value{GDBN} developers. + +For each packet @var{name}, the command to enable or disable the +packet is @code{set remote @var{name}-packet}. If you configure a packet, the +configuration will apply for all future remote targets if no target is selected. +In case there is a target selected, only the configuration of the current target +is changed. All other existing remote targets' features are not affected. +The command to print the current configuration of a packet is +@code{show remote @var{name}-packet}. It displays the current remote target's +configuration. If no remote target is selected, the default configuration for +future connections is shown. The available settings are: + +@multitable @columnfractions 0.28 0.32 0.25 +@item Command Name +@tab Remote Packet +@tab Related Features + +@item @code{fetch-register} +@tab @code{p} +@tab @code{info registers} + +@item @code{set-register} +@tab @code{P} +@tab @code{set} + +@item @code{binary-download} +@tab @code{X} +@tab @code{load}, @code{set} + +@item @code{read-aux-vector} +@tab @code{qXfer:auxv:read} +@tab @code{info auxv} + +@item @code{symbol-lookup} +@tab @code{qSymbol} +@tab Detecting multiple threads + +@item @code{attach} +@tab @code{vAttach} +@tab @code{attach} + +@item @code{verbose-resume} +@tab @code{vCont} +@tab Stepping or resuming multiple threads + +@item @code{run} +@tab @code{vRun} +@tab @code{run} + +@item @code{software-breakpoint} +@tab @code{Z0} +@tab @code{break} + +@item @code{hardware-breakpoint} +@tab @code{Z1} +@tab @code{hbreak} + +@item @code{write-watchpoint} +@tab @code{Z2} +@tab @code{watch} + +@item @code{read-watchpoint} +@tab @code{Z3} +@tab @code{rwatch} + +@item @code{access-watchpoint} +@tab @code{Z4} +@tab @code{awatch} + +@item @code{pid-to-exec-file} +@tab @code{qXfer:exec-file:read} +@tab @code{attach}, @code{run} + +@item @code{target-features} +@tab @code{qXfer:features:read} +@tab @code{set architecture} + +@item @code{library-info} +@tab @code{qXfer:libraries:read} +@tab @code{info sharedlibrary} + +@item @code{memory-map} +@tab @code{qXfer:memory-map:read} +@tab @code{info mem} + +@item @code{read-sdata-object} +@tab @code{qXfer:sdata:read} +@tab @code{print $_sdata} + +@item @code{read-siginfo-object} +@tab @code{qXfer:siginfo:read} +@tab @code{print $_siginfo} + +@item @code{write-siginfo-object} +@tab @code{qXfer:siginfo:write} +@tab @code{set $_siginfo} + +@item @code{threads} +@tab @code{qXfer:threads:read} +@tab @code{info threads} + +@item @code{get-thread-local-@*storage-address} +@tab @code{qGetTLSAddr} +@tab Displaying @code{__thread} variables + +@item @code{get-thread-information-block-address} +@tab @code{qGetTIBAddr} +@tab Display MS-Windows Thread Information Block. + +@item @code{search-memory} +@tab @code{qSearch:memory} +@tab @code{find} + +@item @code{supported-packets} +@tab @code{qSupported} +@tab Remote communications parameters + +@item @code{catch-syscalls} +@tab @code{QCatchSyscalls} +@tab @code{catch syscall} + +@item @code{pass-signals} +@tab @code{QPassSignals} +@tab @code{handle @var{signal}} + +@item @code{program-signals} +@tab @code{QProgramSignals} +@tab @code{handle @var{signal}} + +@item @code{hostio-close-packet} +@tab @code{vFile:close} +@tab @code{remote get}, @code{remote put} + +@item @code{hostio-open-packet} +@tab @code{vFile:open} +@tab @code{remote get}, @code{remote put} + +@item @code{hostio-pread-packet} +@tab @code{vFile:pread} +@tab @code{remote get}, @code{remote put} + +@item @code{hostio-pwrite-packet} +@tab @code{vFile:pwrite} +@tab @code{remote get}, @code{remote put} + +@item @code{hostio-unlink-packet} +@tab @code{vFile:unlink} +@tab @code{remote delete} + +@item @code{hostio-readlink-packet} +@tab @code{vFile:readlink} +@tab Host I/O + +@item @code{hostio-fstat-packet} +@tab @code{vFile:fstat} +@tab Host I/O + +@item @code{hostio-stat-packet} +@tab @code{vFile:stat} +@tab Host I/O + +@item @code{hostio-setfs-packet} +@tab @code{vFile:setfs} +@tab Host I/O + +@item @code{noack-packet} +@tab @code{QStartNoAckMode} +@tab Packet acknowledgment + +@item @code{osdata} +@tab @code{qXfer:osdata:read} +@tab @code{info os} + +@item @code{query-attached} +@tab @code{qAttached} +@tab Querying remote process attach state. + +@item @code{trace-buffer-size} +@tab @code{QTBuffer:size} +@tab @code{set trace-buffer-size} + +@item @code{trace-status} +@tab @code{qTStatus} +@tab @code{tstatus} + +@item @code{traceframe-info} +@tab @code{qXfer:traceframe-info:read} +@tab Traceframe info + +@item @code{install-in-trace} +@tab @code{InstallInTrace} +@tab Install tracepoint in tracing + +@item @code{disable-randomization} +@tab @code{QDisableRandomization} +@tab @code{set disable-randomization} + +@item @code{startup-with-shell} +@tab @code{QStartupWithShell} +@tab @code{set startup-with-shell} + +@item @code{environment-hex-encoded} +@tab @code{QEnvironmentHexEncoded} +@tab @code{set environment} + +@item @code{environment-unset} +@tab @code{QEnvironmentUnset} +@tab @code{unset environment} + +@item @code{environment-reset} +@tab @code{QEnvironmentReset} +@tab @code{Reset the inferior environment (i.e., unset user-set variables)} + +@item @code{set-working-dir} +@tab @code{QSetWorkingDir} +@tab @code{set cwd} + +@item @code{conditional-breakpoints-packet} +@tab @code{Z0 and Z1} +@tab @code{Support for target-side breakpoint condition evaluation} + +@item @code{multiprocess-extensions} +@tab @code{multiprocess extensions} +@tab Debug multiple processes and remote process PID awareness + +@item @code{swbreak-feature} +@tab @code{swbreak stop reason} +@tab @code{break} + +@item @code{hwbreak-feature} +@tab @code{hwbreak stop reason} +@tab @code{hbreak} + +@item @code{fork-event-feature} +@tab @code{fork stop reason} +@tab @code{fork} + +@item @code{vfork-event-feature} +@tab @code{vfork stop reason} +@tab @code{vfork} + +@item @code{exec-event-feature} +@tab @code{exec stop reason} +@tab @code{exec} + +@item @code{thread-events} +@tab @code{QThreadEvents} +@tab Tracking thread lifetime. + +@item @code{thread-options} +@tab @code{QThreadOptions} +@tab Set thread event reporting options. + +@item @code{no-resumed-stop-reply} +@tab @code{no resumed thread left stop reply} +@tab Tracking thread lifetime. + +@end multitable + +@cindex packet size, remote, configuring +The number of bytes per memory-read or memory-write packet for a remote target +can be configured using the commands +@w{@code{set remote memory-read-packet-size}} and +@w{@code{set remote memory-write-packet-size}}. If set to @samp{0} (zero) the +default packet size will be used. The actual limit is further reduced depending +on the target. Specify @samp{fixed} to disable the target-dependent restriction +and @samp{limit} to enable it. Similar to the enabling and disabling of remote +packets, the command applies to the currently selected target (if available). +If no remote target is selected, it applies to all future remote connections. +The configuration of the selected target can be displayed using the commands +@w{@code{show remote memory-read-packet-size}} and +@w{@code{show remote memory-write-packet-size}}. If no remote target is +selected, the default configuration for future connections is shown. + +@node Remote Stub +@section Implementing a Remote Stub + +@cindex debugging stub, example +@cindex remote stub, example +@cindex stub example, remote debugging +The stub files provided with @value{GDBN} implement the target side of the +communication protocol, and the @value{GDBN} side is implemented in the +@value{GDBN} source file @file{remote.c}. Normally, you can simply allow +these subroutines to communicate, and ignore the details. (If you're +implementing your own stub file, you can still ignore the details: start +with one of the existing stub files. @file{sparc-stub.c} is the best +organized, and therefore the easiest to read.) + +@cindex remote serial debugging, overview +To debug a program running on another machine (the debugging +@dfn{target} machine), you must first arrange for all the usual +prerequisites for the program to run by itself. For example, for a C +program, you need: + +@enumerate +@item +A startup routine to set up the C runtime environment; these usually +have a name like @file{crt0}. The startup routine may be supplied by +your hardware supplier, or you may have to write your own. + +@item +A C subroutine library to support your program's +subroutine calls, notably managing input and output. + +@item +A way of getting your program to the other machine---for example, a +download program. These are often supplied by the hardware +manufacturer, but you may have to write your own from hardware +documentation. +@end enumerate + +The next step is to arrange for your program to use a serial port to +communicate with the machine where @value{GDBN} is running (the @dfn{host} +machine). In general terms, the scheme looks like this: + +@table @emph +@item On the host, +@value{GDBN} already understands how to use this protocol; when everything +else is set up, you can simply use the @samp{target remote} command +(@pxref{Targets,,Specifying a Debugging Target}). + +@item On the target, +you must link with your program a few special-purpose subroutines that +implement the @value{GDBN} remote serial protocol. The file containing these +subroutines is called a @dfn{debugging stub}. + +On certain remote targets, you can use an auxiliary program +@code{gdbserver} instead of linking a stub into your program. +@xref{Server,,Using the @code{gdbserver} Program}, for details. +@end table + +The debugging stub is specific to the architecture of the remote +machine; for example, use @file{sparc-stub.c} to debug programs on +@sc{sparc} boards. + +@cindex remote serial stub list +These working remote stubs are distributed with @value{GDBN}: + +@table @code + +@item i386-stub.c +@cindex @file{i386-stub.c} +@cindex Intel +@cindex i386 +For Intel 386 and compatible architectures. + +@item m68k-stub.c +@cindex @file{m68k-stub.c} +@cindex Motorola 680x0 +@cindex m680x0 +For Motorola 680x0 architectures. + +@item sh-stub.c +@cindex @file{sh-stub.c} +@cindex Renesas +@cindex SH +For Renesas SH architectures. + +@item sparc-stub.c +@cindex @file{sparc-stub.c} +@cindex Sparc +For @sc{sparc} architectures. + +@item sparcl-stub.c +@cindex @file{sparcl-stub.c} +@cindex Fujitsu +@cindex SparcLite +For Fujitsu @sc{sparclite} architectures. + +@end table + +The @file{README} file in the @value{GDBN} distribution may list other +recently added stubs. + +@menu +* Stub Contents:: What the stub can do for you +* Bootstrapping:: What you must do for the stub +* Debug Session:: Putting it all together +@end menu + +@node Stub Contents +@subsection What the Stub Can Do for You + +@cindex remote serial stub +The debugging stub for your architecture supplies these three +subroutines: + +@table @code +@findex set_debug_traps +@item set_debug_traps +@cindex remote serial stub, initialization +This routine arranges for @code{handle_exception} to run when your +program stops. You must call this subroutine explicitly in your +program's startup code. + +@findex handle_exception +@item handle_exception +@cindex remote serial stub, main routine +This is the central workhorse, but your program never calls it +explicitly---the setup code arranges for @code{handle_exception} to +run when a trap is triggered. + +@code{handle_exception} takes control when your program stops during +execution (for example, on a breakpoint), and mediates communications +with @value{GDBN} on the host machine. This is where the communications +protocol is implemented; @code{handle_exception} acts as the @value{GDBN} +representative on the target machine. It begins by sending summary +information on the state of your program, then continues to execute, +retrieving and transmitting any information @value{GDBN} needs, until you +execute a @value{GDBN} command that makes your program resume; at that point, +@code{handle_exception} returns control to your own code on the target +machine. + +@item breakpoint +@cindex @code{breakpoint} subroutine, remote +Use this auxiliary subroutine to make your program contain a +breakpoint. Depending on the particular situation, this may be the only +way for @value{GDBN} to get control. For instance, if your target +machine has some sort of interrupt button, you won't need to call this; +pressing the interrupt button transfers control to +@code{handle_exception}---in effect, to @value{GDBN}. On some machines, +simply receiving characters on the serial port may also trigger a trap; +again, in that situation, you don't need to call @code{breakpoint} from +your own program---simply running @samp{target remote} from the host +@value{GDBN} session gets control. + +Call @code{breakpoint} if none of these is true, or if you simply want +to make certain your program stops at a predetermined point for the +start of your debugging session. +@end table + +@node Bootstrapping +@subsection What You Must Do for the Stub + +@cindex remote stub, support routines +The debugging stubs that come with @value{GDBN} are set up for a particular +chip architecture, but they have no information about the rest of your +debugging target machine. + +First of all you need to tell the stub how to communicate with the +serial port. + +@table @code +@findex getDebugChar +@item int getDebugChar() +Write this subroutine to read a single character from the serial port. +It may be identical to @code{getchar} for your target system; a +different name is used to allow you to distinguish the two if you wish. + +@findex putDebugChar +@item void putDebugChar(int) +Write this subroutine to write a single character to the serial port. +It may be identical to @code{putchar} for your target system; a +different name is used to allow you to distinguish the two if you wish. +@end table + +@cindex control C, and remote debugging +@cindex interrupting remote targets +If you want @value{GDBN} to be able to stop your program while it is +running, you need to use an interrupt-driven serial driver, and arrange +for it to stop when it receives a @code{^C} (@samp{\003}, the control-C +character). That is the character which @value{GDBN} uses to tell the +remote system to stop. + +Getting the debugging target to return the proper status to @value{GDBN} +probably requires changes to the standard stub; one quick and dirty way +is to just execute a breakpoint instruction (the ``dirty'' part is that +@value{GDBN} reports a @code{SIGTRAP} instead of a @code{SIGINT}). + +Other routines you need to supply are: + +@table @code +@findex exceptionHandler +@item void exceptionHandler (int @var{exception_number}, void *@var{exception_address}) +Write this function to install @var{exception_address} in the exception +handling tables. You need to do this because the stub does not have any +way of knowing what the exception handling tables on your target system +are like (for example, the processor's table might be in @sc{rom}, +containing entries which point to a table in @sc{ram}). +The @var{exception_number} specifies the exception which should be changed; +its meaning is architecture-dependent (for example, different numbers +might represent divide by zero, misaligned access, etc). When this +exception occurs, control should be transferred directly to +@var{exception_address}, and the processor state (stack, registers, +and so on) should be just as it is when a processor exception occurs. So if +you want to use a jump instruction to reach @var{exception_address}, it +should be a simple jump, not a jump to subroutine. + +For the 386, @var{exception_address} should be installed as an interrupt +gate so that interrupts are masked while the handler runs. The gate +should be at privilege level 0 (the most privileged level). The +@sc{sparc} and 68k stubs are able to mask interrupts themselves without +help from @code{exceptionHandler}. + +@findex flush_i_cache +@item void flush_i_cache() +On @sc{sparc} and @sc{sparclite} only, write this subroutine to flush the +instruction cache, if any, on your target machine. If there is no +instruction cache, this subroutine may be a no-op. + +On target machines that have instruction caches, @value{GDBN} requires this +function to make certain that the state of your program is stable. +@end table + +@noindent +You must also make sure this library routine is available: + +@table @code +@findex memset +@item void *memset(void *, int, int) +This is the standard library function @code{memset} that sets an area of +memory to a known value. If you have one of the free versions of +@code{libc.a}, @code{memset} can be found there; otherwise, you must +either obtain it from your hardware manufacturer, or write your own. +@end table + +If you do not use the GNU C compiler, you may need other standard +library subroutines as well; this varies from one stub to another, +but in general the stubs are likely to use any of the common library +subroutines which @code{@value{NGCC}} generates as inline code. + + +@node Debug Session +@subsection Putting it All Together + +@cindex remote serial debugging summary +In summary, when your program is ready to debug, you must follow these +steps. + +@enumerate +@item +Make sure you have defined the supporting low-level routines +(@pxref{Bootstrapping,,What You Must Do for the Stub}): +@display +@code{getDebugChar}, @code{putDebugChar}, +@code{flush_i_cache}, @code{memset}, @code{exceptionHandler}. +@end display + +@item +Insert these lines in your program's startup code, before the main +procedure is called: + +@smallexample +set_debug_traps(); +breakpoint(); +@end smallexample + +On some machines, when a breakpoint trap is raised, the hardware +automatically makes the PC point to the instruction after the +breakpoint. If your machine doesn't do that, you may need to adjust +@code{handle_exception} to arrange for it to return to the instruction +after the breakpoint on this first invocation, so that your program +doesn't keep hitting the initial breakpoint instead of making +progress. + +@item +For the 680x0 stub only, you need to provide a variable called +@code{exceptionHook}. Normally you just use: + +@smallexample +void (*exceptionHook)() = 0; +@end smallexample + +@noindent +but if before calling @code{set_debug_traps}, you set it to point to a +function in your program, that function is called when +@code{@value{GDBN}} continues after stopping on a trap (for example, bus +error). The function indicated by @code{exceptionHook} is called with +one parameter: an @code{int} which is the exception number. + +@item +Compile and link together: your program, the @value{GDBN} debugging stub for +your target architecture, and the supporting subroutines. + +@item +Make sure you have a serial connection between your target machine and +the @value{GDBN} host, and identify the serial port on the host. + +@item +@c The "remote" target now provides a `load' command, so we should +@c document that. FIXME. +Download your program to your target machine (or get it there by +whatever means the manufacturer provides), and start it. + +@item +Start @value{GDBN} on the host, and connect to the target +(@pxref{Connecting,,Connecting to a Remote Target}). + +@end enumerate + +@node Configurations +@chapter Configuration-Specific Information + +While nearly all @value{GDBN} commands are available for all native and +cross versions of the debugger, there are some exceptions. This chapter +describes things that are only available in certain configurations. + +There are three major categories of configurations: native +configurations, where the host and target are the same, embedded +operating system configurations, which are usually the same for several +different processor architectures, and bare embedded processors, which +are quite different from each other. + +@menu +* Native:: +* Embedded OS:: +* Embedded Processors:: +* Architectures:: +@end menu + +@node Native +@section Native + +This section describes details specific to particular native +configurations. + +@menu +* BSD libkvm Interface:: Debugging BSD kernel memory images +* Process Information:: Process information +* DJGPP Native:: Features specific to the DJGPP port +* Cygwin Native:: Features specific to the Cygwin port +* Hurd Native:: Features specific to @sc{gnu} Hurd +* Darwin:: Features specific to Darwin +* FreeBSD:: Features specific to FreeBSD +@end menu + +@node BSD libkvm Interface +@subsection BSD libkvm Interface + +@cindex libkvm +@cindex kernel memory image +@cindex kernel crash dump + +BSD-derived systems (FreeBSD/NetBSD/OpenBSD) have a kernel memory +interface that provides a uniform interface for accessing kernel virtual +memory images, including live systems and crash dumps. @value{GDBN} +uses this interface to allow you to debug live kernels and kernel crash +dumps on many native BSD configurations. This is implemented as a +special @code{kvm} debugging target. For debugging a live system, load +the currently running kernel into @value{GDBN} and connect to the +@code{kvm} target: + +@smallexample +(@value{GDBP}) @b{target kvm} +@end smallexample + +For debugging crash dumps, provide the file name of the crash dump as an +argument: + +@smallexample +(@value{GDBP}) @b{target kvm /var/crash/bsd.0} +@end smallexample + +Once connected to the @code{kvm} target, the following commands are +available: + +@table @code +@kindex kvm +@item kvm pcb +Set current context from the @dfn{Process Control Block} (PCB) address. + +@item kvm proc +Set current context from proc address. This command isn't available on +modern FreeBSD systems. +@end table + +@node Process Information +@subsection Process Information +@cindex /proc +@cindex examine process image +@cindex process info via @file{/proc} + +Some operating systems provide interfaces to fetch additional +information about running processes beyond memory and per-thread +register state. If @value{GDBN} is configured for an operating system +with a supported interface, the command @code{info proc} is available +to report information about the process running your program, or about +any process running on your system. + +One supported interface is a facility called @samp{/proc} that can be +used to examine the image of a running process using file-system +subroutines. This facility is supported on @sc{gnu}/Linux and Solaris +systems. + +On FreeBSD and NetBSD systems, system control nodes are used to query +process information. + +In addition, some systems may provide additional process information +in core files. Note that a core file may include a subset of the +information available from a live process. Process information is +currently available from cores created on @sc{gnu}/Linux and FreeBSD +systems. + +@table @code +@kindex info proc +@cindex process ID +@item info proc +@itemx info proc @var{process-id} +Summarize available information about a process. If a +process ID is specified by @var{process-id}, display information about +that process; otherwise display information about the program being +debugged. The summary includes the debugged process ID, the command +line used to invoke it, its current working directory, and its +executable file's absolute file name. + +On some systems, @var{process-id} can be of the form +@samp{[@var{pid}]/@var{tid}} which specifies a certain thread ID +within a process. If the optional @var{pid} part is missing, it means +a thread from the process being debugged (the leading @samp{/} still +needs to be present, or else @value{GDBN} will interpret the number as +a process ID rather than a thread ID). + +@item info proc cmdline +@cindex info proc cmdline +Show the original command line of the process. This command is +supported on @sc{gnu}/Linux, FreeBSD and NetBSD. + +@item info proc cwd +@cindex info proc cwd +Show the current working directory of the process. This command is +supported on @sc{gnu}/Linux, FreeBSD and NetBSD. + +@item info proc exe +@cindex info proc exe +Show the name of executable of the process. This command is supported +on @sc{gnu}/Linux, FreeBSD and NetBSD. + +@item info proc files +@cindex info proc files +Show the file descriptors open by the process. For each open file +descriptor, @value{GDBN} shows its number, type (file, directory, +character device, socket), file pointer offset, and the name of the +resource open on the descriptor. The resource name can be a file name +(for files, directories, and devices) or a protocol followed by socket +address (for network connections). This command is supported on +FreeBSD. + +This example shows the open file descriptors for a process using a +tty for standard input and output as well as two network sockets: + +@smallexample +(@value{GDBP}) info proc files 22136 +process 22136 +Open files: + + FD Type Offset Flags Name + text file - r-------- /usr/bin/ssh + ctty chr - rw------- /dev/pts/20 + cwd dir - r-------- /usr/home/john + root dir - r-------- / + 0 chr 0x32933a4 rw------- /dev/pts/20 + 1 chr 0x32933a4 rw------- /dev/pts/20 + 2 chr 0x32933a4 rw------- /dev/pts/20 + 3 socket 0x0 rw----n-- tcp4 10.0.1.2:53014 -> 10.0.1.10:22 + 4 socket 0x0 rw------- unix stream:/tmp/ssh-FIt89oAzOn5f/agent.2456 +@end smallexample + +@item info proc mappings +@cindex memory address space mappings +Report the memory address space ranges accessible in a process. On +Solaris, FreeBSD and NetBSD systems, each memory range includes information +on whether the process has read, write, or execute access rights to each +range. On @sc{gnu}/Linux, FreeBSD and NetBSD systems, each memory range +includes the object file which is mapped to that range. + +@item info proc stat +@itemx info proc status +@cindex process detailed status information +Show additional process-related information, including the user ID and +group ID; virtual memory usage; the signals that are pending, blocked, +and ignored; its TTY; its consumption of system and user time; its +stack size; its @samp{nice} value; etc. These commands are supported +on @sc{gnu}/Linux, FreeBSD and NetBSD. + +For @sc{gnu}/Linux systems, see the @samp{proc} man page for more +information (type @kbd{man 5 proc} from your shell prompt). + +For FreeBSD and NetBSD systems, @code{info proc stat} is an alias for +@code{info proc status}. + +@item info proc all +Show all the information about the process described under all of the +above @code{info proc} subcommands. + +@ignore +@comment These sub-options of 'info proc' were not included when +@comment procfs.c was re-written. Keep their descriptions around +@comment against the day when someone finds the time to put them back in. +@kindex info proc times +@item info proc times +Starting time, user CPU time, and system CPU time for your program and +its children. + +@kindex info proc id +@item info proc id +Report on the process IDs related to your program: its own process ID, +the ID of its parent, the process group ID, and the session ID. +@end ignore + +@item set procfs-trace +@kindex set procfs-trace +@cindex @code{procfs} API calls +This command enables and disables tracing of @code{procfs} API calls. + +@item show procfs-trace +@kindex show procfs-trace +Show the current state of @code{procfs} API call tracing. + +@item set procfs-file @var{file} +@kindex set procfs-file +Tell @value{GDBN} to write @code{procfs} API trace to the named +@var{file}. @value{GDBN} appends the trace info to the previous +contents of the file. The default is to display the trace on the +standard output. + +@item show procfs-file +@kindex show procfs-file +Show the file to which @code{procfs} API trace is written. + +@item proc-trace-entry +@itemx proc-trace-exit +@itemx proc-untrace-entry +@itemx proc-untrace-exit +@kindex proc-trace-entry +@kindex proc-trace-exit +@kindex proc-untrace-entry +@kindex proc-untrace-exit +These commands enable and disable tracing of entries into and exits +from the @code{syscall} interface. + +@end table + +@node DJGPP Native +@subsection Features for Debugging @sc{djgpp} Programs +@cindex @sc{djgpp} debugging +@cindex native @sc{djgpp} debugging +@cindex MS-DOS-specific commands + +@cindex DPMI +@sc{djgpp} is a port of the @sc{gnu} development tools to MS-DOS and +MS-Windows. @sc{djgpp} programs are 32-bit protected-mode programs +that use the @dfn{DPMI} (DOS Protected-Mode Interface) API to run on +top of real-mode DOS systems and their emulations. + +@value{GDBN} supports native debugging of @sc{djgpp} programs, and +defines a few commands specific to the @sc{djgpp} port. This +subsection describes those commands. + +@table @code +@kindex info dos +@item info dos +This is a prefix of @sc{djgpp}-specific commands which print +information about the target system and important OS structures. + +@kindex sysinfo +@cindex MS-DOS system info +@cindex free memory information (MS-DOS) +@item info dos sysinfo +This command displays assorted information about the underlying +platform: the CPU type and features, the OS version and flavor, the +DPMI version, and the available conventional and DPMI memory. + +@cindex GDT +@cindex LDT +@cindex IDT +@cindex segment descriptor tables +@cindex descriptor tables display +@item info dos gdt +@itemx info dos ldt +@itemx info dos idt +These 3 commands display entries from, respectively, Global, Local, +and Interrupt Descriptor Tables (GDT, LDT, and IDT). The descriptor +tables are data structures which store a descriptor for each segment +that is currently in use. The segment's selector is an index into a +descriptor table; the table entry for that index holds the +descriptor's base address and limit, and its attributes and access +rights. + +A typical @sc{djgpp} program uses 3 segments: a code segment, a data +segment (used for both data and the stack), and a DOS segment (which +allows access to DOS/BIOS data structures and absolute addresses in +conventional memory). However, the DPMI host will usually define +additional segments in order to support the DPMI environment. + +@cindex garbled pointers +These commands allow to display entries from the descriptor tables. +Without an argument, all entries from the specified table are +displayed. An argument, which should be an integer expression, means +display a single entry whose index is given by the argument. For +example, here's a convenient way to display information about the +debugged program's data segment: + +@smallexample +@exdent @code{(@value{GDBP}) info dos ldt $ds} +@exdent @code{0x13f: base=0x11970000 limit=0x0009ffff 32-Bit Data (Read/Write, Exp-up)} +@end smallexample + +@noindent +This comes in handy when you want to see whether a pointer is outside +the data segment's limit (i.e.@: @dfn{garbled}). + +@cindex page tables display (MS-DOS) +@item info dos pde +@itemx info dos pte +These two commands display entries from, respectively, the Page +Directory and the Page Tables. Page Directories and Page Tables are +data structures which control how virtual memory addresses are mapped +into physical addresses. A Page Table includes an entry for every +page of memory that is mapped into the program's address space; there +may be several Page Tables, each one holding up to 4096 entries. A +Page Directory has up to 4096 entries, one each for every Page Table +that is currently in use. + +Without an argument, @kbd{info dos pde} displays the entire Page +Directory, and @kbd{info dos pte} displays all the entries in all of +the Page Tables. An argument, an integer expression, given to the +@kbd{info dos pde} command means display only that entry from the Page +Directory table. An argument given to the @kbd{info dos pte} command +means display entries from a single Page Table, the one pointed to by +the specified entry in the Page Directory. + +@cindex direct memory access (DMA) on MS-DOS +These commands are useful when your program uses @dfn{DMA} (Direct +Memory Access), which needs physical addresses to program the DMA +controller. + +These commands are supported only with some DPMI servers. + +@cindex physical address from linear address +@item info dos address-pte @var{addr} +This command displays the Page Table entry for a specified linear +address. The argument @var{addr} is a linear address which should +already have the appropriate segment's base address added to it, +because this command accepts addresses which may belong to @emph{any} +segment. For example, here's how to display the Page Table entry for +the page where a variable @code{i} is stored: + +@smallexample +@exdent @code{(@value{GDBP}) info dos address-pte __djgpp_base_address + (char *)&i} +@exdent @code{Page Table entry for address 0x11a00d30:} +@exdent @code{Base=0x02698000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0xd30} +@end smallexample + +@noindent +This says that @code{i} is stored at offset @code{0xd30} from the page +whose physical base address is @code{0x02698000}, and shows all the +attributes of that page. + +Note that you must cast the addresses of variables to a @code{char *}, +since otherwise the value of @code{__djgpp_base_address}, the base +address of all variables and functions in a @sc{djgpp} program, will +be added using the rules of C pointer arithmetic: if @code{i} is +declared an @code{int}, @value{GDBN} will add 4 times the value of +@code{__djgpp_base_address} to the address of @code{i}. + +Here's another example, it displays the Page Table entry for the +transfer buffer: + +@smallexample +@exdent @code{(@value{GDBP}) info dos address-pte *((unsigned *)&_go32_info_block + 3)} +@exdent @code{Page Table entry for address 0x29110:} +@exdent @code{Base=0x00029000 Dirty Acc. Not-Cached Write-Back Usr Read-Write +0x110} +@end smallexample + +@noindent +(The @code{+ 3} offset is because the transfer buffer's address is the +3rd member of the @code{_go32_info_block} structure.) The output +clearly shows that this DPMI server maps the addresses in conventional +memory 1:1, i.e.@: the physical (@code{0x00029000} + @code{0x110}) and +linear (@code{0x29110}) addresses are identical. + +This command is supported only with some DPMI servers. +@end table + +@cindex DOS serial data link, remote debugging +In addition to native debugging, the DJGPP port supports remote +debugging via a serial data link. The following commands are specific +to remote serial debugging in the DJGPP port of @value{GDBN}. + +@table @code +@kindex set com1base +@kindex set com1irq +@kindex set com2base +@kindex set com2irq +@kindex set com3base +@kindex set com3irq +@kindex set com4base +@kindex set com4irq +@item set com1base @var{addr} +This command sets the base I/O port address of the @file{COM1} serial +port. + +@item set com1irq @var{irq} +This command sets the @dfn{Interrupt Request} (@code{IRQ}) line to use +for the @file{COM1} serial port. + +There are similar commands @samp{set com2base}, @samp{set com3irq}, +etc.@: for setting the port address and the @code{IRQ} lines for the +other 3 COM ports. + +@kindex show com1base +@kindex show com1irq +@kindex show com2base +@kindex show com2irq +@kindex show com3base +@kindex show com3irq +@kindex show com4base +@kindex show com4irq +The related commands @samp{show com1base}, @samp{show com1irq} etc.@: +display the current settings of the base address and the @code{IRQ} +lines used by the COM ports. + +@item info serial +@kindex info serial +@cindex DOS serial port status +This command prints the status of the 4 DOS serial ports. For each +port, it prints whether it's active or not, its I/O base address and +IRQ number, whether it uses a 16550-style FIFO, its baudrate, and the +counts of various errors encountered so far. +@end table + + +@node Cygwin Native +@subsection Features for Debugging MS Windows PE Executables +@cindex MS Windows debugging +@cindex native Cygwin debugging +@cindex Cygwin-specific commands + +@value{GDBN} supports native debugging of MS Windows programs, including +DLLs with and without symbolic debugging information. + +@cindex Ctrl-BREAK, MS-Windows +@cindex interrupt debuggee on MS-Windows +MS-Windows programs that call @code{SetConsoleMode} to switch off the +special meaning of the @samp{Ctrl-C} keystroke cannot be interrupted +by typing @kbd{C-c}. For this reason, @value{GDBN} on MS-Windows +supports @kbd{C-@key{BREAK}} as an alternative interrupt key +sequence, which can be used to interrupt the debuggee even if it +ignores @kbd{C-c}. + +There are various additional Cygwin-specific commands, described in +this section. Working with DLLs that have no debugging symbols is +described in @ref{Non-debug DLL Symbols}. + +@table @code +@kindex info w32 +@item info w32 +This is a prefix of MS Windows-specific commands which print +information about the target system and important OS structures. + +@item info w32 selector +This command displays information returned by +the Win32 API @code{GetThreadSelectorEntry} function. +It takes an optional argument that is evaluated to +a long value to give the information about this given selector. +Without argument, this command displays information +about the six segment registers. + +@item info w32 thread-information-block +This command displays thread specific information stored in the +Thread Information Block (readable on the X86 CPU family using @code{$fs} +selector for 32-bit programs and @code{$gs} for 64-bit programs). + +@kindex signal-event +@item signal-event @var{id} +This command signals an event with user-provided @var{id}. Used to resume +crashing process when attached to it using MS-Windows JIT debugging (AeDebug). + +To use it, create or edit the following keys in +@code{HKLM\SOFTWARE\Microsoft\Windows NT\CurrentVersion\AeDebug} and/or +@code{HKLM\SOFTWARE\Wow6432Node\Microsoft\Windows NT\CurrentVersion\AeDebug} +(for x86_64 versions): + +@itemize @minus +@item +@code{Debugger} (REG_SZ) --- a command to launch the debugger. +Suggested command is: @code{@var{fully-qualified-path-to-gdb.exe} -ex +"attach %ld" -ex "signal-event %ld" -ex "continue"}. + +The first @code{%ld} will be replaced by the process ID of the +crashing process, the second @code{%ld} will be replaced by the ID of +the event that blocks the crashing process, waiting for @value{GDBN} +to attach. + +@item +@code{Auto} (REG_SZ) --- either @code{1} or @code{0}. @code{1} will +make the system run debugger specified by the Debugger key +automatically, @code{0} will cause a dialog box with ``OK'' and +``Cancel'' buttons to appear, which allows the user to either +terminate the crashing process (OK) or debug it (Cancel). +@end itemize + +@kindex set cygwin-exceptions +@cindex debugging the Cygwin DLL +@cindex Cygwin DLL, debugging +@item set cygwin-exceptions @var{mode} +If @var{mode} is @code{on}, @value{GDBN} will break on exceptions that +happen inside the Cygwin DLL. If @var{mode} is @code{off}, +@value{GDBN} will delay recognition of exceptions, and may ignore some +exceptions which seem to be caused by internal Cygwin DLL +``bookkeeping''. This option is meant primarily for debugging the +Cygwin DLL itself; the default value is @code{off} to avoid annoying +@value{GDBN} users with false @code{SIGSEGV} signals. + +@kindex show cygwin-exceptions +@item show cygwin-exceptions +Displays whether @value{GDBN} will break on exceptions that happen +inside the Cygwin DLL itself. + +@kindex set new-console +@item set new-console @var{mode} +If @var{mode} is @code{on} the debuggee will +be started in a new console on next start. +If @var{mode} is @code{off}, the debuggee will +be started in the same console as the debugger. + +@kindex show new-console +@item show new-console +Displays whether a new console is used +when the debuggee is started. + +@kindex set new-group +@item set new-group @var{mode} +This boolean value controls whether the debuggee should +start a new group or stay in the same group as the debugger. +This affects the way the Windows OS handles +@samp{Ctrl-C}. + +@kindex show new-group +@item show new-group +Displays current value of new-group boolean. + +@kindex set debugevents +@item set debugevents +This boolean value adds debug output concerning kernel events related +to the debuggee seen by the debugger. This includes events that +signal thread and process creation and exit, DLL loading and +unloading, console interrupts, and debugging messages produced by the +Windows @code{OutputDebugString} API call. + +@kindex set debugexec +@item set debugexec +This boolean value adds debug output concerning execute events +(such as resume thread) seen by the debugger. + +@kindex set debugexceptions +@item set debugexceptions +This boolean value adds debug output concerning exceptions in the +debuggee seen by the debugger. + +@kindex set debugmemory +@item set debugmemory +This boolean value adds debug output concerning debuggee memory reads +and writes by the debugger. + +@kindex set shell +@item set shell +This boolean values specifies whether the debuggee is called +via a shell or directly (default value is on). + +@kindex show shell +@item show shell +Displays if the debuggee will be started with a shell. + +@end table + +@menu +* Non-debug DLL Symbols:: Support for DLLs without debugging symbols +@end menu + +@node Non-debug DLL Symbols +@subsubsection Support for DLLs without Debugging Symbols +@cindex DLLs with no debugging symbols +@cindex Minimal symbols and DLLs + +Very often on windows, some of the DLLs that your program relies on do +not include symbolic debugging information (for example, +@file{kernel32.dll}). When @value{GDBN} doesn't recognize any debugging +symbols in a DLL, it relies on the minimal amount of symbolic +information contained in the DLL's export table. This section +describes working with such symbols, known internally to @value{GDBN} as +``minimal symbols''. + +Note that before the debugged program has started execution, no DLLs +will have been loaded. The easiest way around this problem is simply to +start the program --- either by setting a breakpoint or letting the +program run once to completion. + +@subsubsection DLL Name Prefixes + +In keeping with the naming conventions used by the Microsoft debugging +tools, DLL export symbols are made available with a prefix based on the +DLL name, for instance @code{KERNEL32!CreateFileA}. The plain name is +also entered into the symbol table, so @code{CreateFileA} is often +sufficient. In some cases there will be name clashes within a program +(particularly if the executable itself includes full debugging symbols) +necessitating the use of the fully qualified name when referring to the +contents of the DLL. Use single-quotes around the name to avoid the +exclamation mark (``!'') being interpreted as a language operator. + +Note that the internal name of the DLL may be all upper-case, even +though the file name of the DLL is lower-case, or vice-versa. Since +symbols within @value{GDBN} are @emph{case-sensitive} this may cause +some confusion. If in doubt, try the @code{info functions} and +@code{info variables} commands or even @code{maint print msymbols} +(@pxref{Symbols}). Here's an example: + +@smallexample +(@value{GDBP}) info function CreateFileA +All functions matching regular expression "CreateFileA": + +Non-debugging symbols: +0x77e885f4 CreateFileA +0x77e885f4 KERNEL32!CreateFileA +@end smallexample + +@smallexample +(@value{GDBP}) info function ! +All functions matching regular expression "!": + +Non-debugging symbols: +0x6100114c cygwin1!__assert +0x61004034 cygwin1!_dll_crt0@@0 +0x61004240 cygwin1!dll_crt0(per_process *) +[etc...] +@end smallexample + +@subsubsection Working with Minimal Symbols + +Symbols extracted from a DLL's export table do not contain very much +type information. All that @value{GDBN} can do is guess whether a symbol +refers to a function or variable depending on the linker section that +contains the symbol. Also note that the actual contents of the memory +contained in a DLL are not available unless the program is running. This +means that you cannot examine the contents of a variable or disassemble +a function within a DLL without a running program. + +Variables are generally treated as pointers and dereferenced +automatically. For this reason, it is often necessary to prefix a +variable name with the address-of operator (``&'') and provide explicit +type information in the command. Here's an example of the type of +problem: + +@smallexample +(@value{GDBP}) print 'cygwin1!__argv' +'cygwin1!__argv' has unknown type; cast it to its declared type +@end smallexample + +@smallexample +(@value{GDBP}) x 'cygwin1!__argv' +'cygwin1!__argv' has unknown type; cast it to its declared type +@end smallexample + +And two possible solutions: + +@smallexample +(@value{GDBP}) print ((char **)'cygwin1!__argv')[0] +$2 = 0x22fd98 "/cygdrive/c/mydirectory/myprogram" +@end smallexample + +@smallexample +(@value{GDBP}) x/2x &'cygwin1!__argv' +0x610c0aa8 : 0x10021608 0x00000000 +(@value{GDBP}) x/x 0x10021608 +0x10021608: 0x0022fd98 +(@value{GDBP}) x/s 0x0022fd98 +0x22fd98: "/cygdrive/c/mydirectory/myprogram" +@end smallexample + +Setting a break point within a DLL is possible even before the program +starts execution. However, under these circumstances, @value{GDBN} can't +examine the initial instructions of the function in order to skip the +function's frame set-up code. You can work around this by using ``*&'' +to set the breakpoint at a raw memory address: + +@smallexample +(@value{GDBP}) break *&'python22!PyOS_Readline' +Breakpoint 1 at 0x1e04eff0 +@end smallexample + +The author of these extensions is not entirely convinced that setting a +break point within a shared DLL like @file{kernel32.dll} is completely +safe. + +@node Hurd Native +@subsection Commands Specific to @sc{gnu} Hurd Systems +@cindex @sc{gnu} Hurd debugging + +This subsection describes @value{GDBN} commands specific to the +@sc{gnu} Hurd native debugging. + +@table @code +@item set signals +@itemx set sigs +@kindex set signals@r{, Hurd command} +@kindex set sigs@r{, Hurd command} +This command toggles the state of inferior signal interception by +@value{GDBN}. Mach exceptions, such as breakpoint traps, are not +affected by this command. @code{sigs} is a shorthand alias for +@code{signals}. + +@item show signals +@itemx show sigs +@kindex show signals@r{, Hurd command} +@kindex show sigs@r{, Hurd command} +Show the current state of intercepting inferior's signals. + +@item set signal-thread +@itemx set sigthread +@kindex set signal-thread +@kindex set sigthread +This command tells @value{GDBN} which thread is the @code{libc} signal +thread. That thread is run when a signal is delivered to a running +process. @code{set sigthread} is the shorthand alias of @code{set +signal-thread}. + +@item show signal-thread +@itemx show sigthread +@kindex show signal-thread +@kindex show sigthread +These two commands show which thread will run when the inferior is +delivered a signal. + +@item set stopped +@kindex set stopped@r{, Hurd command} +This commands tells @value{GDBN} that the inferior process is stopped, +as with the @code{SIGSTOP} signal. The stopped process can be +continued by delivering a signal to it. + +@item show stopped +@kindex show stopped@r{, Hurd command} +This command shows whether @value{GDBN} thinks the debuggee is +stopped. + +@item set exceptions +@kindex set exceptions@r{, Hurd command} +Use this command to turn off trapping of exceptions in the inferior. +When exception trapping is off, neither breakpoints nor +single-stepping will work. To restore the default, set exception +trapping on. + +@item show exceptions +@kindex show exceptions@r{, Hurd command} +Show the current state of trapping exceptions in the inferior. + +@item set task pause +@kindex set task@r{, Hurd commands} +@cindex task attributes (@sc{gnu} Hurd) +@cindex pause current task (@sc{gnu} Hurd) +This command toggles task suspension when @value{GDBN} has control. +Setting it to on takes effect immediately, and the task is suspended +whenever @value{GDBN} gets control. Setting it to off will take +effect the next time the inferior is continued. If this option is set +to off, you can use @code{set thread default pause on} or @code{set +thread pause on} (see below) to pause individual threads. + +@item show task pause +@kindex show task@r{, Hurd commands} +Show the current state of task suspension. + +@item set task detach-suspend-count +@cindex task suspend count +@cindex detach from task, @sc{gnu} Hurd +This command sets the suspend count the task will be left with when +@value{GDBN} detaches from it. + +@item show task detach-suspend-count +Show the suspend count the task will be left with when detaching. + +@item set task exception-port +@itemx set task excp +@cindex task exception port, @sc{gnu} Hurd +This command sets the task exception port to which @value{GDBN} will +forward exceptions. The argument should be the value of the @dfn{send +rights} of the task. @code{set task excp} is a shorthand alias. + +@item set noninvasive +@cindex noninvasive task options +This command switches @value{GDBN} to a mode that is the least +invasive as far as interfering with the inferior is concerned. This +is the same as using @code{set task pause}, @code{set exceptions}, and +@code{set signals} to values opposite to the defaults. + +@item info send-rights +@itemx info receive-rights +@itemx info port-rights +@itemx info port-sets +@itemx info dead-names +@itemx info ports +@itemx info psets +@cindex send rights, @sc{gnu} Hurd +@cindex receive rights, @sc{gnu} Hurd +@cindex port rights, @sc{gnu} Hurd +@cindex port sets, @sc{gnu} Hurd +@cindex dead names, @sc{gnu} Hurd +These commands display information about, respectively, send rights, +receive rights, port rights, port sets, and dead names of a task. +There are also shorthand aliases: @code{info ports} for @code{info +port-rights} and @code{info psets} for @code{info port-sets}. + +@item set thread pause +@kindex set thread@r{, Hurd command} +@cindex thread properties, @sc{gnu} Hurd +@cindex pause current thread (@sc{gnu} Hurd) +This command toggles current thread suspension when @value{GDBN} has +control. Setting it to on takes effect immediately, and the current +thread is suspended whenever @value{GDBN} gets control. Setting it to +off will take effect the next time the inferior is continued. +Normally, this command has no effect, since when @value{GDBN} has +control, the whole task is suspended. However, if you used @code{set +task pause off} (see above), this command comes in handy to suspend +only the current thread. + +@item show thread pause +@kindex show thread@r{, Hurd command} +This command shows the state of current thread suspension. + +@item set thread run +This command sets whether the current thread is allowed to run. + +@item show thread run +Show whether the current thread is allowed to run. + +@item set thread detach-suspend-count +@cindex thread suspend count, @sc{gnu} Hurd +@cindex detach from thread, @sc{gnu} Hurd +This command sets the suspend count @value{GDBN} will leave on a +thread when detaching. This number is relative to the suspend count +found by @value{GDBN} when it notices the thread; use @code{set thread +takeover-suspend-count} to force it to an absolute value. + +@item show thread detach-suspend-count +Show the suspend count @value{GDBN} will leave on the thread when +detaching. + +@item set thread exception-port +@itemx set thread excp +Set the thread exception port to which to forward exceptions. This +overrides the port set by @code{set task exception-port} (see above). +@code{set thread excp} is the shorthand alias. + +@item set thread takeover-suspend-count +Normally, @value{GDBN}'s thread suspend counts are relative to the +value @value{GDBN} finds when it notices each thread. This command +changes the suspend counts to be absolute instead. + +@item set thread default +@itemx show thread default +@cindex thread default settings, @sc{gnu} Hurd +Each of the above @code{set thread} commands has a @code{set thread +default} counterpart (e.g., @code{set thread default pause}, @code{set +thread default exception-port}, etc.). The @code{thread default} +variety of commands sets the default thread properties for all +threads; you can then change the properties of individual threads with +the non-default commands. +@end table + +@node Darwin +@subsection Darwin +@cindex Darwin + +@value{GDBN} provides the following commands specific to the Darwin target: + +@table @code +@item set debug darwin @var{num} +@kindex set debug darwin +When set to a non zero value, enables debugging messages specific to +the Darwin support. Higher values produce more verbose output. + +@item show debug darwin +@kindex show debug darwin +Show the current state of Darwin messages. + +@item set debug mach-o @var{num} +@kindex set debug mach-o +When set to a non zero value, enables debugging messages while +@value{GDBN} is reading Darwin object files. (@dfn{Mach-O} is the +file format used on Darwin for object and executable files.) Higher +values produce more verbose output. This is a command to diagnose +problems internal to @value{GDBN} and should not be needed in normal +usage. + +@item show debug mach-o +@kindex show debug mach-o +Show the current state of Mach-O file messages. + +@item set mach-exceptions on +@itemx set mach-exceptions off +@kindex set mach-exceptions +On Darwin, faults are first reported as a Mach exception and are then +mapped to a Posix signal. Use this command to turn on trapping of +Mach exceptions in the inferior. This might be sometimes useful to +better understand the cause of a fault. The default is off. + +@item show mach-exceptions +@kindex show mach-exceptions +Show the current state of exceptions trapping. +@end table + +@node FreeBSD +@subsection FreeBSD +@cindex FreeBSD + +When the ABI of a system call is changed in the FreeBSD kernel, this +is implemented by leaving a compatibility system call using the old +ABI at the existing number and allocating a new system call number for +the version using the new ABI. As a convenience, when a system call +is caught by name (@pxref{catch syscall}), compatibility system calls +are also caught. + +For example, FreeBSD 12 introduced a new variant of the @code{kevent} +system call and catching the @code{kevent} system call by name catches +both variants: + +@smallexample +(@value{GDBP}) catch syscall kevent +Catchpoint 1 (syscalls 'freebsd11_kevent' [363] 'kevent' [560]) +(@value{GDBP}) +@end smallexample + + +@node Embedded OS +@section Embedded Operating Systems + +This section describes configurations involving the debugging of +embedded operating systems that are available for several different +architectures. + +@value{GDBN} includes the ability to debug programs running on +various real-time operating systems. + +@node Embedded Processors +@section Embedded Processors + +This section goes into details specific to particular embedded +configurations. + +@cindex send command to simulator +Whenever a specific embedded processor has a simulator, @value{GDBN} +allows to send an arbitrary command to the simulator. + +@table @code +@item sim @var{command} +@kindex sim@r{, a command} +Send an arbitrary @var{command} string to the simulator. Consult the +documentation for the specific simulator in use for information about +acceptable commands. +@end table + + +@menu +* ARC:: Synopsys ARC +* ARM:: ARM +* BPF:: eBPF +* M68K:: Motorola M68K +* MicroBlaze:: Xilinx MicroBlaze +* MIPS Embedded:: MIPS Embedded +* OpenRISC 1000:: OpenRISC 1000 (or1k) +* PowerPC Embedded:: PowerPC Embedded +* AVR:: Atmel AVR +* CRIS:: CRIS +* Super-H:: Renesas Super-H +@end menu + +@node ARC +@subsection Synopsys ARC +@cindex Synopsys ARC +@cindex ARC specific commands +@cindex ARC600 +@cindex ARC700 +@cindex ARC EM +@cindex ARC HS + +@value{GDBN} provides the following ARC-specific commands: + +@table @code +@item set debug arc +@kindex set debug arc +Control the level of ARC specific debug messages. Use 0 for no messages (the +default), 1 for debug messages, and 2 for even more debug messages. + +@item show debug arc +@kindex show debug arc +Show the level of ARC specific debugging in operation. + +@item maint print arc arc-instruction @var{address} +@kindex maint print arc arc-instruction +Print internal disassembler information about instruction at a given address. + +@end table + +@node ARM +@subsection ARM + +@value{GDBN} provides the following ARM-specific commands: + +@table @code +@item set arm disassembler +@kindex set arm +This commands selects from a list of disassembly styles. The +@code{"std"} style is the standard style. + +@item show arm disassembler +@kindex show arm +Show the current disassembly style. + +@item set arm apcs32 +@cindex ARM 32-bit mode +This command toggles ARM operation mode between 32-bit and 26-bit. + +@item show arm apcs32 +Display the current usage of the ARM 32-bit mode. + +@item set arm fpu @var{fputype} +This command sets the ARM floating-point unit (FPU) type. The +argument @var{fputype} can be one of these: + +@table @code +@item auto +Determine the FPU type by querying the OS ABI. +@item softfpa +Software FPU, with mixed-endian doubles on little-endian ARM +processors. +@item fpa +GCC-compiled FPA co-processor. +@item softvfp +Software FPU with pure-endian doubles. +@item vfp +VFP co-processor. +@end table + +@item show arm fpu +Show the current type of the FPU. + +@item set arm abi +This command forces @value{GDBN} to use the specified ABI. + +@item show arm abi +Show the currently used ABI. + +@item set arm fallback-mode (arm|thumb|auto) +@value{GDBN} uses the symbol table, when available, to determine +whether instructions are ARM or Thumb. This command controls +@value{GDBN}'s default behavior when the symbol table is not +available. The default is @samp{auto}, which causes @value{GDBN} to +use the current execution mode (from the @code{T} bit in the @code{CPSR} +register). + +@item show arm fallback-mode +Show the current fallback instruction mode. + +@item set arm force-mode (arm|thumb|auto) +This command overrides use of the symbol table to determine whether +instructions are ARM or Thumb. The default is @samp{auto}, which +causes @value{GDBN} to use the symbol table and then the setting +of @samp{set arm fallback-mode}. + +@item show arm force-mode +Show the current forced instruction mode. + +@item set arm unwind-secure-frames +This command enables unwinding from Non-secure to Secure mode on +Cortex-M with Security extension. +This can trigger security exceptions when unwinding the exception +stack. +It is enabled by default. + +@item show arm unwind-secure-frames +Show whether unwinding from Non-secure to Secure mode is enabled. + +@item set debug arm +Toggle whether to display ARM-specific debugging messages from the ARM +target support subsystem. + +@item show debug arm +Show whether ARM-specific debugging messages are enabled. +@end table + +@table @code +@item target sim @r{[}@var{simargs}@r{]} @dots{} +The @value{GDBN} ARM simulator accepts the following optional arguments. + +@table @code +@item --swi-support=@var{type} +Tell the simulator which SWI interfaces to support. The argument +@var{type} may be a comma separated list of the following values. +The default value is @code{all}. + +@table @code +@item none +@item demon +@item angel +@item redboot +@item all +@end table +@end table +@end table + +@node BPF +@subsection BPF + +@table @code +@item target sim @r{[}@var{simargs}@r{]} @dots{} +The @value{GDBN} BPF simulator accepts the following optional arguments. + +@table @code +@item --skb-data-offset=@var{offset} +Tell the simulator the offset, measured in bytes, of the +@code{skb_data} field in the kernel @code{struct sk_buff} structure. +This offset is used by some BPF specific-purpose load/store +instructions. Defaults to 0. +@end table +@end table + +@node M68K +@subsection M68k + +The Motorola m68k configuration includes ColdFire support. + +@node MicroBlaze +@subsection MicroBlaze +@cindex Xilinx MicroBlaze +@cindex XMD, Xilinx Microprocessor Debugger + +The MicroBlaze is a soft-core processor supported on various Xilinx +FPGAs, such as Spartan or Virtex series. Boards with these processors +usually have JTAG ports which connect to a host system running the Xilinx +Embedded Development Kit (EDK) or Software Development Kit (SDK). +This host system is used to download the configuration bitstream to +the target FPGA. The Xilinx Microprocessor Debugger (XMD) program +communicates with the target board using the JTAG interface and +presents a @code{gdbserver} interface to the board. By default +@code{xmd} uses port @code{1234}. (While it is possible to change +this default port, it requires the use of undocumented @code{xmd} +commands. Contact Xilinx support if you need to do this.) + +Use these GDB commands to connect to the MicroBlaze target processor. + +@table @code +@item target remote :1234 +Use this command to connect to the target if you are running @value{GDBN} +on the same system as @code{xmd}. + +@item target remote @var{xmd-host}:1234 +Use this command to connect to the target if it is connected to @code{xmd} +running on a different system named @var{xmd-host}. + +@item load +Use this command to download a program to the MicroBlaze target. + +@item set debug microblaze @var{n} +Enable MicroBlaze-specific debugging messages if non-zero. + +@item show debug microblaze @var{n} +Show MicroBlaze-specific debugging level. +@end table + +@node MIPS Embedded +@subsection @acronym{MIPS} Embedded + +@noindent +@value{GDBN} supports these special commands for @acronym{MIPS} targets: + +@table @code +@item set mipsfpu double +@itemx set mipsfpu single +@itemx set mipsfpu none +@itemx set mipsfpu auto +@itemx show mipsfpu +@kindex set mipsfpu +@kindex show mipsfpu +@cindex @acronym{MIPS} remote floating point +@cindex floating point, @acronym{MIPS} remote +If your target board does not support the @acronym{MIPS} floating point +coprocessor, you should use the command @samp{set mipsfpu none} (if you +need this, you may wish to put the command in your @value{GDBN} init +file). This tells @value{GDBN} how to find the return value of +functions which return floating point values. It also allows +@value{GDBN} to avoid saving the floating point registers when calling +functions on the board. If you are using a floating point coprocessor +with only single precision floating point support, as on the @sc{r4650} +processor, use the command @samp{set mipsfpu single}. The default +double precision floating point coprocessor may be selected using +@samp{set mipsfpu double}. + +In previous versions the only choices were double precision or no +floating point, so @samp{set mipsfpu on} will select double precision +and @samp{set mipsfpu off} will select no floating point. + +As usual, you can inquire about the @code{mipsfpu} variable with +@samp{show mipsfpu}. +@end table + +@node OpenRISC 1000 +@subsection OpenRISC 1000 +@cindex OpenRISC 1000 + +@noindent +The OpenRISC 1000 provides a free RISC instruction set architecture. It is +mainly provided as a soft-core which can run on Xilinx, Altera and other +FPGA's. + +@value{GDBN} for OpenRISC supports the below commands when connecting to +a target: + +@table @code + +@kindex target sim +@item target sim + +Runs the builtin CPU simulator which can run very basic +programs but does not support most hardware functions like MMU. +For more complex use cases the user is advised to run an external +target, and connect using @samp{target remote}. + +Example: @code{target sim} + +@item set debug or1k +Toggle whether to display OpenRISC-specific debugging messages from the +OpenRISC target support subsystem. + +@item show debug or1k +Show whether OpenRISC-specific debugging messages are enabled. +@end table + +@node PowerPC Embedded +@subsection PowerPC Embedded + +@cindex DVC register +@value{GDBN} supports using the DVC (Data Value Compare) register to +implement in hardware simple hardware watchpoint conditions of the form: + +@smallexample +(@value{GDBP}) watch @var{address|variable} \ + if @var{address|variable} == @var{constant expression} +@end smallexample + +The DVC register will be automatically used when @value{GDBN} detects +such pattern in a condition expression, and the created watchpoint uses one +debug register (either the @code{exact-watchpoints} option is on and the +variable is scalar, or the variable has a length of one byte). This feature +is available in native @value{GDBN} running on a Linux kernel version 2.6.34 +or newer. + +When running on PowerPC embedded processors, @value{GDBN} automatically uses +ranged hardware watchpoints, unless the @code{exact-watchpoints} option is on, +in which case watchpoints using only one debug register are created when +watching variables of scalar types. + +You can create an artificial array to watch an arbitrary memory +region using one of the following commands (@pxref{Expressions}): + +@smallexample +(@value{GDBP}) watch *((char *) @var{address})@@@var{length} +(@value{GDBP}) watch @{char[@var{length}]@} @var{address} +@end smallexample + +PowerPC embedded processors support masked watchpoints. See the discussion +about the @code{mask} argument in @ref{Set Watchpoints}. + +@cindex ranged breakpoint +PowerPC embedded processors support hardware accelerated +@dfn{ranged breakpoints}. A ranged breakpoint stops execution of +the inferior whenever it executes an instruction at any address within +the range it was set at. To set a ranged breakpoint in @value{GDBN}, +use the @code{break-range} command. + +@value{GDBN} provides the following PowerPC-specific commands: + +@table @code +@kindex break-range +@item break-range @var{start-locspec}, @var{end-locspec} +Set a breakpoint for an address range given by @var{start-locspec} and +@var{end-locspec}, which are location specs. @xref{Location +Specifications}, for a list of all the possible forms of location +specs. @value{GDBN} resolves both @var{start-locspec} and +@var{end-locspec}, and uses the addresses of the resolved code +locations as start and end addresses of the range to break at. The +breakpoint will stop execution of the inferior whenever it executes an +instruction at any address between the start and end addresses, +inclusive. If either @var{start-locspec} or @var{end-locspec} resolve +to multiple code locations in the program, then the command aborts +with an error without creating a breakpoint. + +@kindex set powerpc +@item set powerpc soft-float +@itemx show powerpc soft-float +Force @value{GDBN} to use (or not use) a software floating point calling +convention. By default, @value{GDBN} selects the calling convention based +on the selected architecture and the provided executable file. + +@item set powerpc vector-abi +@itemx show powerpc vector-abi +Force @value{GDBN} to use the specified calling convention for vector +arguments and return values. The valid options are @samp{auto}; +@samp{generic}, to avoid vector registers even if they are present; +@samp{altivec}, to use AltiVec registers; and @samp{spe} to use SPE +registers. By default, @value{GDBN} selects the calling convention +based on the selected architecture and the provided executable file. + +@item set powerpc exact-watchpoints +@itemx show powerpc exact-watchpoints +Allow @value{GDBN} to use only one debug register when watching a variable +of scalar type, thus assuming that the variable is accessed through the +address of its first byte. + +@end table + +@node AVR +@subsection Atmel AVR +@cindex AVR + +When configured for debugging the Atmel AVR, @value{GDBN} supports the +following AVR-specific commands: + +@table @code +@item info io_registers +@kindex info io_registers@r{, AVR} +@cindex I/O registers (Atmel AVR) +This command displays information about the AVR I/O registers. For +each register, @value{GDBN} prints its number and value. +@end table + +@node CRIS +@subsection CRIS +@cindex CRIS + +When configured for debugging CRIS, @value{GDBN} provides the +following CRIS-specific commands: + +@table @code +@item set cris-version @var{ver} +@cindex CRIS version +Set the current CRIS version to @var{ver}, either @samp{10} or @samp{32}. +The CRIS version affects register names and sizes. This command is useful in +case autodetection of the CRIS version fails. + +@item show cris-version +Show the current CRIS version. + +@item set cris-dwarf2-cfi +@cindex DWARF-2 CFI and CRIS +Set the usage of DWARF-2 CFI for CRIS debugging. The default is @samp{on}. +Change to @samp{off} when using @code{gcc-cris} whose version is below +@code{R59}. + +@item show cris-dwarf2-cfi +Show the current state of using DWARF-2 CFI. + +@item set cris-mode @var{mode} +@cindex CRIS mode +Set the current CRIS mode to @var{mode}. It should only be changed when +debugging in guru mode, in which case it should be set to +@samp{guru} (the default is @samp{normal}). + +@item show cris-mode +Show the current CRIS mode. +@end table + +@node Super-H +@subsection Renesas Super-H +@cindex Super-H + +For the Renesas Super-H processor, @value{GDBN} provides these +commands: + +@table @code +@item set sh calling-convention @var{convention} +@kindex set sh calling-convention +Set the calling-convention used when calling functions from @value{GDBN}. +Allowed values are @samp{gcc}, which is the default setting, and @samp{renesas}. +With the @samp{gcc} setting, functions are called using the @value{NGCC} calling +convention. If the DWARF-2 information of the called function specifies +that the function follows the Renesas calling convention, the function +is called using the Renesas calling convention. If the calling convention +is set to @samp{renesas}, the Renesas calling convention is always used, +regardless of the DWARF-2 information. This can be used to override the +default of @samp{gcc} if debug information is missing, or the compiler +does not emit the DWARF-2 calling convention entry for a function. + +@item show sh calling-convention +@kindex show sh calling-convention +Show the current calling convention setting. + +@end table + + +@node Architectures +@section Architectures + +This section describes characteristics of architectures that affect +all uses of @value{GDBN} with the architecture, both native and cross. + +@menu +* AArch64:: +* x86:: +* Alpha:: +* MIPS:: +* HPPA:: HP PA architecture +* PowerPC:: +* Sparc64:: +* S12Z:: +* AMD GPU:: @acronym{AMD GPU} architectures +@end menu + +@node AArch64 +@subsection AArch64 +@cindex AArch64 support + +When @value{GDBN} is debugging the AArch64 architecture, it provides the +following special commands: + +@table @code +@item set debug aarch64 +@kindex set debug aarch64 +This command determines whether AArch64 architecture-specific debugging +messages are to be displayed. + +@item show debug aarch64 +Show whether AArch64 debugging messages are displayed. + +@end table + +@subsubsection AArch64 SVE. +@cindex AArch64 SVE. + +When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Vector +Extension (SVE) is present, then @value{GDBN} will provide the vector registers +@code{$z0} through @code{$z31}, vector predicate registers @code{$p0} through +@code{$p15}, and the @code{$ffr} register. In addition, the pseudo register +@code{$vg} will be provided. This is the vector granule for the current thread +and represents the number of 64-bit chunks in an SVE @code{z} register. + +If the vector length changes, then the @code{$vg} register will be updated, +but the lengths of the @code{z} and @code{p} registers will not change. This +is a known limitation of @value{GDBN} and does not affect the execution of the +target process. + +For SVE, the following definitions are used throughout @value{GDBN}'s source +code and in this document: + +@itemize + +@item +@var{vl}: The vector length, in bytes. It defines the size of each @code{Z} +register. +@anchor{vl} +@cindex vl + +@item +@var{vq}: The number of 128 bit units in @var{vl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{vq} +@cindex vq + +@item +@var{vg}: The number of 64 bit units in @var{vl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{vg} +@cindex vg + +@end itemize + +@subsubsection AArch64 SME. +@anchor{AArch64 SME} +@cindex SME +@cindex AArch64 SME +@cindex Scalable Matrix Extension + +The Scalable Matrix Extension (@url{https://community.arm.com/arm-community-blogs/b/architectures-and-processors-blog/posts/scalable-matrix-extension-armv9-a-architecture, @acronym{SME}}) +is an AArch64 architecture extension that expands on the concept of the +Scalable Vector Extension (@url{https://developer.arm.com/documentation/101726/4-0/Learn-about-the-Scalable-Vector-Extension--SVE-/What-is-the-Scalable-Vector-Extension-, @acronym{SVE}}) +by providing a 2-dimensional register @code{ZA}, which is a square +matrix of variable size, just like SVE provides a group of vector registers of +variable size. + +Similarly to SVE, where the size of each @code{Z} register is directly related +to the vector length (@var{vl} for short), the @acronym{SME} @code{ZA} matrix +register's size is directly related to the streaming vector length +(@var{svl} for short). @xref{vl}. @xref{svl}. + +The @code{ZA} register state can be either active or inactive, if it is not in +use. + +@acronym{SME} also introduces a new execution mode called streaming +@acronym{SVE} mode (streaming mode for short). When streaming mode is +enabled, the program supports execution of @acronym{SVE2} instructions and the +@acronym{SVE} registers will have vector length @var{svl}. When streaming +mode is disabled, the SVE registers have vector length @var{vl}. + +For more information about @acronym{SME} and @acronym{SVE}, please refer to +official @url{https://developer.arm.com/documentation/ddi0487/latest, +architecture documentation}. + +The following definitions are used throughout @value{GDBN}'s source code and +in this document: + +@itemize + +@item +@var{svl}: The streaming vector length, in bytes. It defines the size of each +dimension of the 2-dimensional square @code{ZA} matrix. The total size of +@code{ZA} is therefore @var{svl} by @var{svl}. + +When streaming mode is enabled, it defines the size of the @acronym{SVE} +registers as well. +@anchor{svl} +@cindex svl + +@item +@var{svq}: The number of 128 bit units in @var{svl}, also known as streaming +vector granule. This is mostly used internally by @value{GDBN} and the Linux +Kernel. +@anchor{svq} +@cindex svq + +@item +@var{svg}: The number of 64 bit units in @var{svl}. This is mostly used +internally by @value{GDBN} and the Linux Kernel. +@anchor{svg} +@cindex svg + +@end itemize + +When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix +Extension (@acronym{SME}) is present, then @value{GDBN} will make the @code{ZA} +register available. @value{GDBN} will also make the @code{SVG} register and +@code{SVCR} pseudo-register available. + +The @code{ZA} register is a 2-dimensional square @var{svl} by @var{svl} +matrix of bytes. To simplify the representation and access to the @code{ZA} +register in @value{GDBN}, it is defined as a vector of +@var{svl}x@var{svl} bytes. + +If the user wants to index the @code{ZA} register as a matrix, it is possible +to reference @code{ZA} as @code{ZA[@var{i}][@var{j}]}, where @var{i} is the +row number and @var{j} is the column number. + +The @code{SVG} register always contains the streaming vector granule +(@var{svg}) for the current thread. From the value of register @code{SVG} we +can easily derive the @var{svl} value. + +@anchor{aarch64 sme svcr} +The @code{SVCR} pseudo-register (streaming vector control register) is a status +register that holds two state bits: @sc{sm} in bit 0 and @sc{za} in bit 1. + +If the @sc{sm} bit is 1, it means the current thread is in streaming +mode, and the @acronym{SVE} registers will use @var{svl} for their sizes. If +the @sc{sm} bit is 0, the current thread is not in streaming mode, and the +@acronym{SVE} registers will use @var{vl} for their sizes. @xref{vl}. + +If the @sc{za} bit is 1, it means the @code{ZA} register is being used and +has meaningful contents. If the @sc{za} bit is 0, the @code{ZA} register is +unavailable and its contents are undefined. + +For convenience and simplicity, if the @sc{za} bit is 0, the @code{ZA} +register and all of its pseudo-registers will read as zero. + +If @var{svl} changes during the execution of a program, then the @code{ZA} +register size and the bits in the @code{SVCR} pseudo-register will be updated +to reflect it. + +It is possible for users to change @var{svl} during the execution of a +program by modifying the @code{SVG} register value. + +Whenever the @code{SVG} register is modified with a new value, the +following will be observed: + +@itemize + +@item The @sc{za} and @sc{sm} bits will be cleared in the @code{SVCR} +pseudo-register. + +@item The @code{ZA} register will have a new size and its state will be +cleared, forcing its contents and the contents of all of its pseudo-registers +back to zero. + +@item If the @sc{sm} bit was 1, the @acronym{SVE} registers will be reset to +having their sizes based on @var{vl} as opposed to @var{svl}. If the +@sc{sm} bit was 0 prior to modifying the @code{SVG} register, there will be no +observable effect on the @acronym{SVE} registers. + +@end itemize + +The possible values for the @code{SVG} register are 2, 4, 8, 16, 32. These +numbers correspond to streaming vector length (@var{svl}) values of 16 +bytes, 32 bytes, 64 bytes, 128 bytes and 256 bytes respectively. + +The minimum size of the @code{ZA} register is 16 x 16 (256) bytes, and the +maximum size is 256 x 256 (65536) bytes. In streaming mode, with bit @sc{sm} +set, the size of the @code{ZA} register is the size of all the SVE @code{Z} +registers combined. + +The @code{ZA} register can also be accessed using tiles and tile slices. + +Tile pseudo-registers are square, 2-dimensional sub-arrays of elements within +the @code{ZA} register. + +The tile pseudo-registers have the following naming pattern: +@code{ZA<@var{tile number}><@var{qualifier}>}. + +There is a total of 31 @code{ZA} tile pseudo-registers. They are +@code{ZA0B}, @code{ZA0H} through @code{ZA1H}, @code{ZA0S} through @code{ZA3S}, +@code{ZA0D} through @code{ZA7D} and @code{ZA0Q} through @code{ZA15Q}. + +Tile slice pseudo-registers are vectors of horizontally or vertically +contiguous elements within the @code{ZA} register. + +The tile slice pseudo-registers have the following naming pattern: +@code{ZA<@var{tile number}><@var{direction}><@var{qualifier}> +<@var{slice number}>}. + +There are up to 16 tiles (0 ~ 15), the direction can be either @code{v} +(vertical) or @code{h} (horizontal), the qualifiers can be @code{b} (byte), +@code{h} (halfword), @code{s} (word), @code{d} (doubleword) and @code{q} +(quadword) and there are up to 256 slices (0 ~ 255) depending on the value +of @var{svl}. The number of slices is the same as the value of @var{svl}. + +The number of available tile slice pseudo-registers can be large. For a +minimum @var{svl} of 16 bytes, there are 5 (number of qualifiers) x +2 (number of directions) x 16 (@var{svl}) pseudo-registers. For the +maximum @var{svl} of 256 bytes, there are 5 x 2 x 256 pseudo-registers. + +When listing all the available registers, users will see the +currently-available @code{ZA} pseudo-registers. Pseudo-registers that don't +exist for a given @var{svl} value will not be displayed. + +For more information on @acronym{SME} and its terminology, please refer to the +@url{https://developer.arm.com/documentation/ddi0616/aa/, +Arm Architecture Reference Manual Supplement}, The Scalable Matrix Extension +(@acronym{SME}), for Armv9-A. + +Some features are still under development and rely on +@url{https://github.com/ARM-software/acle/releases/latest, ACLE} and +@url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst, ABI} +definitions, so there are known limitations to the current @acronym{SME} +support in @value{GDBN}. + +One such example is calling functions in the program being debugged by +@value{GDBN}. Such calls are not @acronym{SME}-aware and thus don't take into +account the @code{SVCR} pseudo-register bits nor the @code{ZA} register +contents. @xref{Calling}. + +The @url{https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst#the-za-lazy-saving-scheme, +lazy saving scheme} involving the @code{TPIDR2} register is not yet supported +by @value{GDBN}, though the @code{TPIDR2} register is known and supported +by @value{GDBN}. + +Lastly, an important limitation for @command{gdbserver} is its inability to +communicate @var{svl} changes to @value{GDBN}. This means @command{gdbserver}, +even though it is capable of adjusting its internal caches to reflect a change +in the value of @var{svl} mid-execution, will operate with a potentially +different @var{svl} value compared to @value{GDBN}. This can lead to +@value{GDBN} showing incorrect values for the @code{ZA} register and +incorrect values for SVE registers (when in streaming mode). + +This is the same limitation we have for the @acronym{SVE} registers, and there +are plans to address this limitation going forward. + +@subsubsection AArch64 SME2. +@anchor{AArch64 SME2} +@cindex SME2 +@cindex AArch64 SME2 +@cindex Scalable Matrix Extension 2 + +The Scalable Matrix Extension 2 is an AArch64 architecture extension that +further expands the @acronym{SME} extension with the following: + +@itemize + +@item The ability to address the @code{ZA} array through groups of +one-dimensional @code{ZA} array vectors, as opposed to @code{ZA} tiles +with 2 dimensions. + +@item Instructions to operate on groups of @acronym{SVE} @code{Z} registers and +@code{ZA} array vectors. + +@item A new 512 bit @code{ZT0} lookup table register, for data decompression. + +@end itemize + +When @value{GDBN} is debugging the AArch64 architecture, if the Scalable Matrix +Extension 2 (@acronym{SME2}) is present, then @value{GDBN} will make the +@code{ZT0} register available. + +The @code{ZT0} register is only considered active when the @code{ZA} register +state is active, therefore when the @sc{za} bit of the @code{SVCR} is 1. + +When the @sc{za} bit of @code{SVCR} is 0, that means the @code{ZA} register +state is not active, which means the @code{ZT0} register state is also not +active. + +When @code{ZT0} is not active, it is comprised of zeroes, just like @code{ZA}. + +Similarly to the @code{ZA} register, if the @code{ZT0} state is not active and +the user attempts to modify its value such that any of its bytes is non-zero, +then @value{GDBN} will initialize the @code{ZA} register state as well, which +means the @code{SVCR} @sc{za} bit gets set to 1. + +For more information about @acronym{SME2}, please refer to the +official @url{https://developer.arm.com/documentation/ddi0487/latest, +architecture documentation}. + +@subsubsection AArch64 Pointer Authentication. +@cindex AArch64 Pointer Authentication. +@anchor{AArch64 PAC} + +When @value{GDBN} is debugging the AArch64 architecture, and the program is +using the v8.3-A feature Pointer Authentication (PAC), then whenever the link +register @code{$lr} is pointing to an PAC function its value will be masked. +When GDB prints a backtrace, any addresses that required unmasking will be +postfixed with the marker [PAC]. When using the MI, this is printed as part +of the @code{addr_flags} field. + +@subsubsection AArch64 Memory Tagging Extension. +@cindex AArch64 Memory Tagging Extension. + +When @value{GDBN} is debugging the AArch64 architecture, the program is +using the v8.5-A feature Memory Tagging Extension (MTE) and there is support +in the kernel for MTE, @value{GDBN} will make memory tagging functionality +available for inspection and editing of logical and allocation tags. +@xref{Memory Tagging}. + +To aid debugging, @value{GDBN} will output additional information when SIGSEGV +signals are generated as a result of memory tag failures. + +If the tag violation is synchronous, the following will be shown: + +@smallexample +Program received signal SIGSEGV, Segmentation fault +Memory tag violation while accessing address 0x0500fffff7ff8000 +Allocation tag 0x1 +Logical tag 0x5. +@end smallexample + +If the tag violation is asynchronous, the fault address is not available. +In this case @value{GDBN} will show the following: + +@smallexample +Program received signal SIGSEGV, Segmentation fault +Memory tag violation +Fault address unavailable. +@end smallexample + +A special register, @code{tag_ctl}, is made available through the +@code{org.gnu.gdb.aarch64.mte} feature. This register exposes some +options that can be controlled at runtime and emulates the @code{prctl} +option @code{PR_SET_TAGGED_ADDR_CTRL}. For further information, see the +documentation in the Linux kernel. + +@value{GDBN} supports dumping memory tag data to core files through the +@command{gcore} command and reading memory tag data from core files generated +by the @command{gcore} command or the Linux kernel. + +When a process uses memory-mapped pages protected by memory tags (for +example, AArch64 MTE), this additional information will be recorded in +the core file in the event of a crash or if @value{GDBN} generates a core file +from the current process state. + +The memory tag data will be used so developers can display the memory +tags from a particular memory region (using the @samp{m} modifier to the +@command{x} command, using the @command{print} command or using the various +@command{memory-tag} subcommands. + +In the case of a crash, @value{GDBN} will attempt to retrieve the memory tag +information automatically from the core file, and will show one of the above +messages depending on whether the synchronous or asynchronous mode is selected. +@xref{Memory Tagging}. @xref{Memory}. + +@node x86 +@subsection x86 + +@table @code +@item set struct-convention @var{mode} +@kindex set struct-convention +@cindex struct return convention +@cindex struct/union returned in registers +Set the convention used by the inferior to return @code{struct}s and +@code{union}s from functions to @var{mode}. Possible values of +@var{mode} are @code{"pcc"}, @code{"reg"}, and @code{"default"} (the +default). @code{"default"} or @code{"pcc"} means that @code{struct}s +are returned on the stack, while @code{"reg"} means that a +@code{struct} or a @code{union} whose size is 1, 2, 4, or 8 bytes will +be returned in a register. + +@item show struct-convention +@kindex show struct-convention +Show the current setting of the convention to return @code{struct}s +from functions. +@end table + +@subsubsection x87 registers + +@value{GDBN} provides access to the x87 state through the following registers: + +@itemize + +@item @code{$st0} to @code{st7}: @code{ST(0)} to @code{ST(7)} floating-point +registers +@item @code{$fctrl}: control word register (@code{FCW}) +@item @code{$fstat}: status word register (@code{FSW}) +@item @code{$ftag}: tag word (@code{FTW}) +@item @code{$fiseg}: last instruction pointer segment +@item @code{$fioff}: last instruction pointer +@item @code{$foseg}: last data pointer segment +@item @code{$fooff}: last data pointer +@item @code{$fop}: last opcode + +@end itemize + +@node Alpha +@subsection Alpha + +See the following section. + +@node MIPS +@subsection @acronym{MIPS} + +@cindex stack on Alpha +@cindex stack on @acronym{MIPS} +@cindex Alpha stack +@cindex @acronym{MIPS} stack +Alpha- and @acronym{MIPS}-based computers use an unusual stack frame, which +sometimes requires @value{GDBN} to search backward in the object code to +find the beginning of a function. + +@cindex response time, @acronym{MIPS} debugging +To improve response time (especially for embedded applications, where +@value{GDBN} may be restricted to a slow serial line for this search) +you may want to limit the size of this search, using one of these +commands: + +@table @code +@cindex @code{heuristic-fence-post} (Alpha, @acronym{MIPS}) +@item set heuristic-fence-post @var{limit} +Restrict @value{GDBN} to examining at most @var{limit} bytes in its +search for the beginning of a function. A value of @var{0} (the +default) means there is no limit. However, except for @var{0}, the +larger the limit the more bytes @code{heuristic-fence-post} must search +and therefore the longer it takes to run. You should only need to use +this command when debugging a stripped executable. + +@item show heuristic-fence-post +Display the current limit. +@end table + +@noindent +These commands are available @emph{only} when @value{GDBN} is configured +for debugging programs on Alpha or @acronym{MIPS} processors. + +Several @acronym{MIPS}-specific commands are available when debugging @acronym{MIPS} +programs: + +@table @code +@item set mips abi @var{arg} +@kindex set mips abi +@cindex set ABI for @acronym{MIPS} +Tell @value{GDBN} which @acronym{MIPS} ABI is used by the inferior. Possible +values of @var{arg} are: + +@table @samp +@item auto +The default ABI associated with the current binary (this is the +default). +@item o32 +@item o64 +@item n32 +@item n64 +@item eabi32 +@item eabi64 +@end table + +@item show mips abi +@kindex show mips abi +Show the @acronym{MIPS} ABI used by @value{GDBN} to debug the inferior. + +@item set mips compression @var{arg} +@kindex set mips compression +@cindex code compression, @acronym{MIPS} +Tell @value{GDBN} which @acronym{MIPS} compressed +@acronym{ISA, Instruction Set Architecture} encoding is used by the +inferior. @value{GDBN} uses this for code disassembly and other +internal interpretation purposes. This setting is only referred to +when no executable has been associated with the debugging session or +the executable does not provide information about the encoding it uses. +Otherwise this setting is automatically updated from information +provided by the executable. + +Possible values of @var{arg} are @samp{mips16} and @samp{micromips}. +The default compressed @acronym{ISA} encoding is @samp{mips16}, as +executables containing @acronym{MIPS16} code frequently are not +identified as such. + +This setting is ``sticky''; that is, it retains its value across +debugging sessions until reset either explicitly with this command or +implicitly from an executable. + +The compiler and/or assembler typically add symbol table annotations to +identify functions compiled for the @acronym{MIPS16} or +@acronym{microMIPS} @acronym{ISA}s. If these function-scope annotations +are present, @value{GDBN} uses them in preference to the global +compressed @acronym{ISA} encoding setting. + +@item show mips compression +@kindex show mips compression +Show the @acronym{MIPS} compressed @acronym{ISA} encoding used by +@value{GDBN} to debug the inferior. + +@item set mipsfpu +@itemx show mipsfpu +@xref{MIPS Embedded, set mipsfpu}. + +@item set mips mask-address @var{arg} +@kindex set mips mask-address +@cindex @acronym{MIPS} addresses, masking +This command determines whether the most-significant 32 bits of 64-bit +@acronym{MIPS} addresses are masked off. The argument @var{arg} can be +@samp{on}, @samp{off}, or @samp{auto}. The latter is the default +setting, which lets @value{GDBN} determine the correct value. + +@item show mips mask-address +@kindex show mips mask-address +Show whether the upper 32 bits of @acronym{MIPS} addresses are masked off or +not. + +@item set remote-mips64-transfers-32bit-regs +@kindex set remote-mips64-transfers-32bit-regs +This command controls compatibility with 64-bit @acronym{MIPS} targets that +transfer data in 32-bit quantities. If you have an old @acronym{MIPS} 64 target +that transfers 32 bits for some registers, like @sc{sr} and @sc{fsr}, +and 64 bits for other registers, set this option to @samp{on}. + +@item show remote-mips64-transfers-32bit-regs +@kindex show remote-mips64-transfers-32bit-regs +Show the current setting of compatibility with older @acronym{MIPS} 64 targets. + +@item set debug mips +@kindex set debug mips +This command turns on and off debugging messages for the @acronym{MIPS}-specific +target code in @value{GDBN}. + +@item show debug mips +@kindex show debug mips +Show the current setting of @acronym{MIPS} debugging messages. +@end table + + +@node HPPA +@subsection HPPA +@cindex HPPA support + +When @value{GDBN} is debugging the HP PA architecture, it provides the +following special commands: + +@table @code +@item set debug hppa +@kindex set debug hppa +This command determines whether HPPA architecture-specific debugging +messages are to be displayed. + +@item show debug hppa +Show whether HPPA debugging messages are displayed. + +@item maint print unwind @var{address} +@kindex maint print unwind@r{, HPPA} +This command displays the contents of the unwind table entry at the +given @var{address}. + +@end table + + +@node PowerPC +@subsection PowerPC +@cindex PowerPC architecture + +When @value{GDBN} is debugging the PowerPC architecture, it provides a set of +pseudo-registers to enable inspection of 128-bit wide Decimal Floating Point +numbers stored in the floating point registers. These values must be stored +in two consecutive registers, always starting at an even register like +@code{f0} or @code{f2}. + +The pseudo-registers go from @code{$dl0} through @code{$dl15}, and are formed +by joining the even/odd register pairs @code{f0} and @code{f1} for @code{$dl0}, +@code{f2} and @code{f3} for @code{$dl1} and so on. + +For POWER7 processors, @value{GDBN} provides a set of pseudo-registers, the 64-bit +wide Extended Floating Point Registers (@samp{f32} through @samp{f63}). + +@node Sparc64 +@subsection Sparc64 +@cindex Sparc64 support +@cindex Application Data Integrity +@subsubsection ADI Support + +The M7 processor supports an Application Data Integrity (ADI) feature that +detects invalid data accesses. When software allocates memory and enables +ADI on the allocated memory, it chooses a 4-bit version number, sets the +version in the upper 4 bits of the 64-bit pointer to that data, and stores +the 4-bit version in every cacheline of that data. Hardware saves the latter +in spare bits in the cache and memory hierarchy. On each load and store, +the processor compares the upper 4 VA (virtual address) bits to the +cacheline's version. If there is a mismatch, the processor generates a +version mismatch trap which can be either precise or disrupting. The trap +is an error condition which the kernel delivers to the process as a SIGSEGV +signal. + +Note that only 64-bit applications can use ADI and need to be built with +ADI-enabled. + +Values of the ADI version tags, which are in granularity of a +cacheline (64 bytes), can be viewed or modified. + + +@table @code +@kindex adi examine +@item adi (examine | x) [ / @var{n} ] @var{addr} + +The @code{adi examine} command displays the value of one ADI version tag per +cacheline. + +@var{n} is a decimal integer specifying the number in bytes; the default +is 1. It specifies how much ADI version information, at the ratio of 1:ADI +block size, to display. + +@var{addr} is the address in user address space where you want @value{GDBN} +to begin displaying the ADI version tags. + +Below is an example of displaying ADI versions of variable "shmaddr". + +@smallexample +(@value{GDBP}) adi x/100 shmaddr + 0xfff800010002c000: 0 0 +@end smallexample + +@kindex adi assign +@item adi (assign | a) [ / @var{n} ] @var{addr} = @var{tag} + +The @code{adi assign} command is used to assign new ADI version tag +to an address. + +@var{n} is a decimal integer specifying the number in bytes; +the default is 1. It specifies how much ADI version information, at the +ratio of 1:ADI block size, to modify. + +@var{addr} is the address in user address space where you want @value{GDBN} +to begin modifying the ADI version tags. + +@var{tag} is the new ADI version tag. + +For example, do the following to modify then verify ADI versions of +variable "shmaddr": + +@smallexample +(@value{GDBP}) adi a/100 shmaddr = 7 +(@value{GDBP}) adi x/100 shmaddr + 0xfff800010002c000: 7 7 +@end smallexample + +@end table + +@node S12Z +@subsection S12Z +@cindex S12Z support + +When @value{GDBN} is debugging the S12Z architecture, +it provides the following special command: + +@table @code +@item maint info bdccsr +@kindex maint info bdccsr@r{, S12Z} +This command displays the current value of the microprocessor's +BDCCSR register. +@end table + +@node AMD GPU +@subsection @acronym{AMD GPU} +@cindex @acronym{AMD GPU} support + +@value{GDBN} supports debugging programs offloaded to @acronym{AMD GPU} devices +using the @url{https://docs.amd.com/, @acronym{AMD ROCm}} platform. +@value{GDBN} presents host threads alongside GPU wavefronts, allowing debugging +both the host and device parts of the program simultaneously. + +@subsubsection @acronym{AMD GPU} Architectures + +The list of @acronym{AMD GPU} architectures supported by @value{GDBN} depends +on the version of the AMD Debugger API library used. See its +@uref{https://docs.amd.com/bundle/ROCDebugger_User_and_API, documentation} for +more details. + +@subsubsection @acronym{AMD GPU} Device Driver and @acronym{AMD ROCm} Runtime + +@value{GDBN} requires a compatible @acronym{AMD GPU} device driver to +be installed. A warning message is displayed if either the device +driver version or the version of the debug support it implements is +unsupported. @value{GDBN} will continue to function except no +@acronym{AMD GPU} debugging will be possible. + +@value{GDBN} requires each agent to have compatible firmware installed +by the device driver. A warning message is displayed if unsupported +firmware is detected. @value{GDBN} will continue to function except +no @acronym{AMD GPU} debugging will be possible on the agent. + +@value{GDBN} requires a compatible @acronym{AMD ROCm} runtime to be +loaded in order to detect @acronym{AMD GPU} code objects and +wavefronts. A warning message is displayed if an unsupported +@acronym{AMD ROCm} runtime is detected, or there is an error or +restriction that prevents debugging. @value{GDBN} will continue to +function except no @acronym{AMD GPU} debugging will be possible. + +@subsubsection @acronym{AMD GPU} Wavefronts +@cindex wavefronts + +An @acronym{AMD GPU} wavefront is represented in @value{GDBN} as a +thread. + +Note that some @acronym{AMD GPU} architectures may have restrictions +on providing information about @acronym{AMD GPU} wavefronts created +when @value{GDBN} is not attached (@pxref{AMD GPU Attaching +Restrictions, , @acronym{AMD GPU} Attaching Restrictions}). + +When scheduler-locking is in effect (@pxref{set scheduler-locking}), +new wavefronts created by the resumed thread (either CPU thread or GPU +wavefront) are held in the halt state. + +@subsubsection @acronym{AMD GPU} Code Objects + +The @samp{info sharedlibrary} command will show the @acronym{AMD GPU} +code objects as file or memory URIs, together with the host's shared +libraries. For example: + +@smallexample +(@value{GDBP}) info sharedlibrary +From To Syms Read Shared Object Library +0x1111 0x2222 Yes (*) /lib64/ld-linux-x86-64.so.2 +... +0x3333 0x4444 Yes (*) /opt/rocm-4.5.0/.../libamd_comgr.so +0x5555 0x6666 Yes (*) /lib/x86_64-linux-gnu/libtinfo.so.5 +0x7777 0x8888 Yes file:///tmp/a.out#offset=6477&size=10832 +0x9999 0xaaaa Yes (*) memory://95557/mem#offset=0x1234&size=100 +(*): Shared library is missing debugging information. +(@value{GDBP}) +@end smallexample + +For a @samp{file} URI, the path portion is the file on disk containing +the code object. The @var{offset} parameter is a 0-based offset in +this file, to the start of the code object. If omitted, it defaults to +0. The @var{size} parameter is the size of the code object in bytes. +If omitted, it defaults to the size of the file. + +For a @samp{memory} URI, the path portion is the process id of the +process owning the memory containing the code object. The @var{offset} +parameter is the memory address where the code object is found, and +the @var{size} parameter is its size in bytes. + +@acronym{AMD GPU} code objects are loaded into each @acronym{AMD GPU} +device separately. The @samp{info sharedlibrary} command may +therefore show the same code object loaded multiple times. As a +consequence, setting a breakpoint in @acronym{AMD GPU} code will +result in multiple breakpoint locations if there are multiple +@acronym{AMD GPU} devices. + +@subsubsection @acronym{AMD GPU} Entity Target Identifiers and Convenience Variables + +The @acronym{AMD GPU} entities have the following target identifier formats: + +@table @asis + +@item Thread Target ID +The @acronym{AMD GPU} thread target identifier (@var{systag}) string has the +following format: + +@smallexample +AMDGPU Wave @var{agent-id}:@var{queue-id}:@var{dispatch-id}:@var{wave-id} (@var{work-group-x},@var{work-group-y},@var{work-group-z})/@var{work-group-thread-index} +@end smallexample + +@end table + +@anchor{AMD GPU Signals} +@subsubsection @acronym{AMD GPU} Signals + +For @acronym{AMD GPU} wavefronts, @value{GDBN} maps target conditions to stop +signals in the following way: + +@table @code + +@item SIGILL +Execution of an illegal instruction. + +@item SIGTRAP +Execution of a @code{S_TRAP} instruction other than: + +@itemize @bullet{} + +@item +@code{S_TRAP 1} which is used by @value{GDBN} to insert breakpoints. + +@item +@code{S_TRAP 2} which raises @code{SIGABRT}. + +@end itemize + +@item SIGABRT +Execution of a @code{S_TRAP 2} instruction. + +@item SIGFPE +Execution of a floating point or integer instruction detects a +condition that is enabled to raise a signal. The conditions include: + +@itemize @bullet{} + +@item +Floating point operation is invalid. + +@item +Floating point operation had subnormal input that was rounded to zero. + +@item +Floating point operation performed a division by zero. + +@item +Floating point operation produced an overflow result. The result was +rounded to infinity. + +@item +Floating point operation produced an underflow result. A subnormal +result was rounded to zero. + +@item +Floating point operation produced an inexact result. + +@item +Integer operation performed a division by zero. + +@end itemize + +By default, these conditions are not enabled to raise signals. The +@samp{set $mode} command can be used to change the @acronym{AMD GPU} +wavefront's register that has bits controlling which conditions are +enabled to raise signals. The @samp{print $trapsts} command can be +used to inspect which conditions have been detected even if they are +not enabled to raise a signal. + +@item SIGBUS +Execution of an instruction that accessed global memory using an +address that is outside the virtual address range. + +@item SIGSEGV +Execution of an instruction that accessed a global memory page that is +either not mapped or accessed with incompatible permissions. + +@end table + +If a single instruction raises more than one signal, they will be +reported one at a time each time the wavefront is continued. + +@subsubsection @acronym{AMD GPU} Memory Violation Reporting + +A wavefront can report memory violation events. However, the program +location at which they are reported may be after the machine instruction +that caused them. This can result in the reported source statement +being incorrect. The following commands can be used to control this +behavior: + +@table @code + +@kindex set amdgpu precise-memory +@cindex AMD GPU precise memory event reporting +@item set amdgpu precise-memory @var{mode} +Controls how @acronym{AMD GPU} devices detect memory violations, where +@var{mode} can be: + +@table @code + +@item off +The program location may not be immediately after the instruction that +caused the memory violation. This is the default. + +@item on +Requests that the program location will be immediately after the +instruction that caused a memory violation. Enabling this mode may make +the @acronym{AMD GPU} device execution significantly slower as it has to +wait for each memory operation to complete before executing the next +instruction. + +@end table + +The @code{amdgpu precise-memory} parameter is per-inferior. When an +inferior forks or execs, or the user uses the @code{clone-inferior} command, +and an inferior is created as a result, the newly created inferior inherits +the parameter value of the original inferior. + +@kindex show amdgpu precise-memory +@cindex AMD GPU precise memory event reporting +@item show amdgpu precise-memory +Displays the currently requested AMD GPU precise memory setting. + +@end table + +@subsubsection @acronym{AMD GPU} Logging + +The @samp{set debug amd-dbgapi} command can be used +to enable diagnostic messages in the @samp{amd-dbgapi} target. The +@samp{show debug amd-dbgapi} command displays the current setting. +@xref{set debug amd-dbgapi}. + +The @samp{set debug amd-dbgapi-lib log-level @var{level}} command can be used +to enable diagnostic messages from the @samp{amd-dbgapi} library (which +@value{GDBN} uses under the hood). The @samp{show debug amd-dbgapi-lib +log-level} command displays the current @samp{amd-dbgapi} library log level. +@xref{set debug amd-dbgapi-lib}. + +@subsubsection @acronym{AMD GPU} Restrictions + +@enumerate + +@item +When in non-stop mode, wavefronts may not hit breakpoints inserted +while not stopped, nor see memory updates made while not stopped, +until the wavefront is next stopped. Memory updated by non-stopped +wavefronts may not be visible until the wavefront is next stopped. + +@item The HIP runtime performs deferred code object loading by default. +@acronym{AMD GPU} code objects are not loaded until the first kernel is +launched. Before then, all breakpoints have to be set as pending breakpoints. + +If source line positions are used that only correspond to source lines in +unloaded code objects, then @value{GDBN} may not set pending breakpoints, and +instead set breakpoints on the next following source line that maps to host +code. This can result in unexpected breakpoint hits being reported. When the +code object containing the source lines is loaded, the incorrect breakpoints +will be removed and replaced by the correct ones. This problem can be avoided +by only setting breakpoints in unloaded code objects using symbol or function +names. + +Setting the @code{HIP_ENABLE_DEFERRED_LOADING} environment variable to @code{0} +can be used to disable deferred code object loading by the HIP runtime. This +ensures all code objects will be loaded when the inferior reaches the beginning +of the @code{main} function. + +@item +If no CPU thread is running, then @samp{Ctrl-C} is not able to stop +@acronym{AMD GPU} threads. This can happen for example if you enable +@code{scheduler-locking} after the whole program stopped, and then resume an +@acronym{AMD GPU} thread. The only way to unblock the situation is to kill the +@value{GDBN} process. + +@anchor{AMD GPU Attaching Restrictions} +@item + +By default, for some architectures, the @acronym{AMD GPU} device driver causes +all @acronym{AMD GPU} wavefronts created when @value{GDBN} is not attached to +be unable to report the dispatch associated with the wavefront, or the +wavefront's work-group position. The @samp{info threads} command will display +this missing information with a @samp{?}. + +This does not affect wavefronts created while @value{GDBN} is attached which +are always capable of reporting this information. + +If the @env{HSA_ENABLE_DEBUG} environment variable is set to @samp{1} when the +@acronym{AMD ROCm} runtime is initialized, then this information will be +available for all architectures even for wavefronts created when @value{GDBN} +was not attached. + +@end enumerate + +@node Controlling GDB +@chapter Controlling @value{GDBN} + +You can alter the way @value{GDBN} interacts with you by using the +@code{set} command. For commands controlling how @value{GDBN} displays +data, see @ref{Print Settings, ,Print Settings}. Other settings are +described here. + +@menu +* Prompt:: Prompt +* Editing:: Command editing +* Command History:: Command history +* Screen Size:: Screen size +* Output Styling:: Output styling +* Numbers:: Numbers +* ABI:: Configuring the current ABI +* Auto-loading:: Automatically loading associated files +* Messages/Warnings:: Optional warnings and messages +* Debugging Output:: Optional messages about internal happenings +* Other Misc Settings:: Other Miscellaneous Settings +@end menu + +@node Prompt +@section Prompt + +@cindex prompt + +@value{GDBN} indicates its readiness to read a command by printing a string +called the @dfn{prompt}. This string is normally @samp{(@value{GDBP})}. You +can change the prompt string with the @code{set prompt} command. For +instance, when debugging @value{GDBN} with @value{GDBN}, it is useful to change +the prompt in one of the @value{GDBN} sessions so that you can always tell +which one you are talking to. + +@emph{Note:} @code{set prompt} does not add a space for you after the +prompt you set. This allows you to set a prompt which ends in a space +or a prompt that does not. + +@table @code +@kindex set prompt +@item set prompt @var{newprompt} +Directs @value{GDBN} to use @var{newprompt} as its prompt string henceforth. + +@kindex show prompt +@item show prompt +Prints a line of the form: @samp{Gdb's prompt is: @var{your-prompt}} +@end table + +Versions of @value{GDBN} that ship with Python scripting enabled have +prompt extensions. The commands for interacting with these extensions +are: + +@table @code +@kindex set extended-prompt +@item set extended-prompt @var{prompt} +Set an extended prompt that allows for substitutions. +@xref{gdb.prompt}, for a list of escape sequences that can be used for +substitution. Any escape sequences specified as part of the prompt +string are replaced with the corresponding strings each time the prompt +is displayed. + +For example: + +@smallexample +set extended-prompt Current working directory: \w (@value{GDBP}) +@end smallexample + +Note that when an extended-prompt is set, it takes control of the +@var{prompt_hook} hook. @xref{prompt_hook}, for further information. + +@kindex show extended-prompt +@item show extended-prompt +Prints the extended prompt. Any escape sequences specified as part of +the prompt string with @code{set extended-prompt}, are replaced with the +corresponding strings each time the prompt is displayed. +@end table + +@node Editing +@section Command Editing +@cindex readline +@cindex command line editing + +@value{GDBN} reads its input commands via the @dfn{Readline} interface. This +@sc{gnu} library provides consistent behavior for programs which provide a +command line interface to the user. Advantages are @sc{gnu} Emacs-style +or @dfn{vi}-style inline editing of commands, @code{csh}-like history +substitution, and a storage and recall of command history across +debugging sessions. + +You may control the behavior of command line editing in @value{GDBN} with the +command @code{set}. + +@table @code +@kindex set editing +@cindex editing +@item set editing +@itemx set editing on +Enable command line editing (enabled by default). + +@item set editing off +Disable command line editing. + +@kindex show editing +@item show editing +Show whether command line editing is enabled. +@end table + +@ifset SYSTEM_READLINE +@xref{Command Line Editing, , , rluserman, GNU Readline Library}, +@end ifset +@ifclear SYSTEM_READLINE +@xref{Command Line Editing}, +@end ifclear +for more details about the Readline +interface. Users unfamiliar with @sc{gnu} Emacs or @code{vi} are +encouraged to read that chapter. + +@cindex Readline application name +@value{GDBN} sets the Readline application name to @samp{gdb}. This +is useful for conditions in @file{.inputrc}. + +@cindex operate-and-get-next +@value{GDBN} defines a bindable Readline command, +@code{operate-and-get-next}. This is bound to @kbd{C-o} by default. +This command accepts the current line for execution and fetches the +next line relative to the current line from the history for editing. +Any argument is ignored. + +It is possible to discover which version of Readline @value{GDBN} is +using with the @kbd{show configuration} command (@pxref{show +configuration}). + +@node Command History +@section Command History +@cindex command history + +@value{GDBN} can keep track of the commands you type during your +debugging sessions, so that you can be certain of precisely what +happened. Use these commands to manage the @value{GDBN} command +history facility. + +@value{GDBN} uses the @sc{gnu} History library, a part of the Readline +package, to provide the history facility. +@ifset SYSTEM_READLINE +@xref{Using History Interactively, , , history, GNU History Library}, +@end ifset +@ifclear SYSTEM_READLINE +@xref{Using History Interactively}, +@end ifclear +for the detailed description of the History library. + +To issue a command to @value{GDBN} without affecting certain aspects of +the state which is seen by users, prefix it with @samp{server } +(@pxref{Server Prefix}). This +means that this command will not affect the command history, nor will it +affect @value{GDBN}'s notion of which command to repeat if @key{RET} is +pressed on a line by itself. + +@cindex @code{server}, command prefix +The server prefix does not affect the recording of values into the value +history; to print a value without recording it into the value history, +use the @code{output} command instead of the @code{print} command. + +Here is the description of @value{GDBN} commands related to command +history. + +@table @code +@cindex history substitution +@cindex history file +@kindex set history filename +@cindex @env{GDBHISTFILE}, environment variable +@item set history filename @r{[}@var{fname}@r{]} +Set the name of the @value{GDBN} command history file to @var{fname}. +This is the file where @value{GDBN} reads an initial command history +list, and where it writes the command history from this session when it +exits. You can access this list through history expansion or through +the history command editing characters listed below. This file defaults +to the value of the environment variable @env{GDBHISTFILE}, or to +@file{./.gdb_history} (@file{./_gdb_history} on MS-DOS) if this variable +is not set. + +The @env{GDBHISTFILE} environment variable is read after processing +any @value{GDBN} initialization files (@pxref{Startup}) and after +processing any commands passed using command line options (for +example, @code{-ex}). + +If the @var{fname} argument is not given, or if the @env{GDBHISTFILE} +is the empty string then @value{GDBN} will neither try to load an +existing history file, nor will it try to save the history on exit. + +@cindex save command history +@kindex set history save +@item set history save +@itemx set history save on +Record command history in a file, whose name may be specified with the +@code{set history filename} command. By default, this option is +disabled. The command history will be recorded when @value{GDBN} +exits. If @code{set history filename} is set to the empty string then +history saving is disabled, even when @code{set history save} is +@code{on}. + +@item set history save off +Don't record the command history into the file specified by @code{set +history filename} when @value{GDBN} exits. + +@cindex history size +@kindex set history size +@cindex @env{GDBHISTSIZE}, environment variable +@item set history size @var{size} +@itemx set history size unlimited +Set the number of commands which @value{GDBN} keeps in its history list. +This defaults to the value of the environment variable @env{GDBHISTSIZE}, or +to 256 if this variable is not set. Non-numeric values of @env{GDBHISTSIZE} +are ignored. If @var{size} is @code{unlimited} or if @env{GDBHISTSIZE} is +either a negative number or the empty string, then the number of commands +@value{GDBN} keeps in the history list is unlimited. + +The @env{GDBHISTSIZE} environment variable is read after processing +any @value{GDBN} initialization files (@pxref{Startup}) and after +processing any commands passed using command line options (for +example, @code{-ex}). + +@cindex remove duplicate history +@kindex set history remove-duplicates +@item set history remove-duplicates @var{count} +@itemx set history remove-duplicates unlimited +Control the removal of duplicate history entries in the command history list. +If @var{count} is non-zero, @value{GDBN} will look back at the last @var{count} +history entries and remove the first entry that is a duplicate of the current +entry being added to the command history list. If @var{count} is +@code{unlimited} then this lookbehind is unbounded. If @var{count} is 0, then +removal of duplicate history entries is disabled. + +Only history entries added during the current session are considered for +removal. This option is set to 0 by default. + +@end table + +History expansion assigns special meaning to the character @kbd{!}. +@ifset SYSTEM_READLINE +@xref{Event Designators, , , history, GNU History Library}, +@end ifset +@ifclear SYSTEM_READLINE +@xref{Event Designators}, +@end ifclear +for more details. + +@cindex history expansion, turn on/off +Since @kbd{!} is also the logical not operator in C, history expansion +is off by default. If you decide to enable history expansion with the +@code{set history expansion on} command, you may sometimes need to +follow @kbd{!} (when it is used as logical not, in an expression) with +a space or a tab to prevent it from being expanded. The readline +history facilities do not attempt substitution on the strings +@kbd{!=} and @kbd{!(}, even when history expansion is enabled. + +The commands to control history expansion are: + +@table @code +@item set history expansion on +@itemx set history expansion +@kindex set history expansion +Enable history expansion. History expansion is off by default. + +@item set history expansion off +Disable history expansion. + +@c @group +@kindex show history +@item show history +@itemx show history filename +@itemx show history save +@itemx show history size +@itemx show history expansion +These commands display the state of the @value{GDBN} history parameters. +@code{show history} by itself displays all four states. +@c @end group +@end table + +@table @code +@kindex show commands +@cindex show last commands +@cindex display command history +@item show commands +Display the last ten commands in the command history. + +@item show commands @var{n} +Print ten commands centered on command number @var{n}. + +@item show commands + +Print ten commands just after the commands last printed. +@end table + +@node Screen Size +@section Screen Size +@cindex size of screen +@cindex screen size +@cindex pagination +@cindex page size +@cindex pauses in output + +Certain commands to @value{GDBN} may produce large amounts of +information output to the screen. To help you read all of it, +@value{GDBN} pauses and asks you for input at the end of each page of +output. Type @key{RET} when you want to see one more page of output, +@kbd{q} to discard the remaining output, or @kbd{c} to continue +without paging for the rest of the current command. Also, the screen +width setting determines when to wrap lines of output. Depending on +what is being printed, @value{GDBN} tries to break the line at a +readable place, rather than simply letting it overflow onto the +following line. + +Normally @value{GDBN} knows the size of the screen from the terminal +driver software. For example, on Unix @value{GDBN} uses the termcap data base +together with the value of the @env{TERM} environment variable and the +@code{stty rows} and @code{stty cols} settings. If this is not correct, +you can override it with the @code{set height} and @code{set +width} commands: + +@table @code +@kindex set height +@kindex set width +@kindex show width +@kindex show height +@item set height @var{lpp} +@itemx set height unlimited +@itemx show height +@itemx set width @var{cpl} +@itemx set width unlimited +@itemx show width +These @code{set} commands specify a screen height of @var{lpp} lines and +a screen width of @var{cpl} characters. The associated @code{show} +commands display the current settings. + +If you specify a height of either @code{unlimited} or zero lines, +@value{GDBN} does not pause during output no matter how long the +output is. This is useful if output is to a file or to an editor +buffer. + +Likewise, you can specify @samp{set width unlimited} or @samp{set +width 0} to prevent @value{GDBN} from wrapping its output. + +@item set pagination on +@itemx set pagination off +@kindex set pagination +Turn the output pagination on or off; the default is on. Turning +pagination off is the alternative to @code{set height unlimited}. Note that +running @value{GDBN} with the @option{--batch} option (@pxref{Mode +Options, -batch}) also automatically disables pagination. + +@item show pagination +@kindex show pagination +Show the current pagination mode. +@end table + +@node Output Styling +@section Output Styling +@cindex styling +@cindex colors + +@kindex set style +@kindex show style +@value{GDBN} can style its output on a capable terminal. This is +enabled by default on most systems, but disabled by default when in +batch mode (@pxref{Mode Options}). Various style settings are available; +and styles can also be disabled entirely. + +@table @code +@item set style enabled @samp{on|off} +Enable or disable all styling. The default is host-dependent, with +most hosts defaulting to @samp{on}. + +If the @env{NO_COLOR} environment variable is set to a non-empty +value, then @value{GDBN} will change this to @samp{off} at startup. + +@item show style enabled +Show the current state of styling. + +@item set style sources @samp{on|off} +Enable or disable source code styling. This affects whether source +code, such as the output of the @code{list} command, is styled. The +default is @samp{on}. Note that source styling only works if styling +in general is enabled, and if a source highlighting library is +available to @value{GDBN}. + +There are two ways that highlighting can be done. First, if +@value{GDBN} was linked with the GNU Source Highlight library, then it +is used. Otherwise, if @value{GDBN} was configured with Python +scripting support, and if the Python Pygments package is available, +then it will be used. + +@item show style sources +Show the current state of source code styling. + +@item set style tui-current-position @samp{on|off} +Enable or disable styling of the source and assembly code highlighted +by the TUI's current position indicator. The default is @samp{off}. +@xref{TUI, ,@value{GDBN} Text User Interface}. + +@item show style tui-current-position +Show whether the source and assembly code highlighted by the TUI's +current position indicator is styled. + +@anchor{style_disassembler_enabled} +@item set style disassembler enabled @samp{on|off} +Enable or disable disassembler styling. This affects whether +disassembler output, such as the output of the @code{disassemble} +command, is styled. Disassembler styling only works if styling in +general is enabled (with @code{set style enabled on}), and if a source +highlighting library is available to @value{GDBN}. + +The two source highlighting libraries that @value{GDBN} could use to +style disassembler output are; @value{GDBN}'s builtin disassembler, or +the Python Pygments package. + +@value{GDBN}'s first choice will be to use the builtin disassembler +for styling, this usually provides better results, being able to style +different types of instruction operands differently. However, the +builtin disassembler is not able to style all architectures. + +For architectures that the builtin disassembler is unable to style, +@value{GDBN} will fall back to use the Python Pygments package where +possible. In order to use the Python Pygments package, @value{GDBN} +must be built with Python support, and the Pygments package must be +installed. + +If neither of these options are available then @value{GDBN} will +produce unstyled disassembler output, even when this setting is +@samp{on}. + +To discover if the current architecture supports styling using the +builtin disassembler library see @ref{maint_libopcodes_styling,,@kbd{maint +show libopcodes-styling enabled}}. + +@item show style disassembler enabled +Show the current state of disassembler styling. + +@end table + +Subcommands of @code{set style} control specific forms of styling. +These subcommands all follow the same pattern: each style-able object +can be styled with a foreground color, a background color, and an +intensity. + +For example, the style of file names can be controlled using the +@code{set style filename} group of commands: + +@table @code +@item set style filename background @var{color} +Set the background to @var{color}. Valid colors are @samp{none} +(meaning the terminal's default color), @samp{black}, @samp{red}, +@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, +and@samp{white}. + +@item set style filename foreground @var{color} +Set the foreground to @var{color}. Valid colors are @samp{none} +(meaning the terminal's default color), @samp{black}, @samp{red}, +@samp{green}, @samp{yellow}, @samp{blue}, @samp{magenta}, @samp{cyan}, +and@samp{white}. + +@item set style filename intensity @var{value} +Set the intensity to @var{value}. Valid intensities are @samp{normal} +(the default), @samp{bold}, and @samp{dim}. +@end table + +The @code{show style} command and its subcommands are styling +a style name in their output using its own style. +So, use @command{show style} to see the complete list of styles, +their characteristics and the visual aspect of each style. + +The style-able objects are: +@table @code +@item command +Control the styling of any @value{GDBN} commands that are displayed by +@value{GDBN}. By default, this style's intensity is bold. + +@item filename +Control the styling of file names and URLs. By default, this style's +foreground color is green. + +@item function +Control the styling of function names. These are managed with the +@code{set style function} family of commands. By default, this +style's foreground color is yellow. + +This style is also used for symbol names in styled disassembler output +if @value{GDBN} is using its builtin disassembler library for styling +(@pxref{style_disassembler_enabled,,@kbd{set style disassembler +enabled}}). + +@item line-number +Control the styling of line numbers. By default, this style's +intensity is dim. + +@item variable +Control the styling of variable names. These are managed with the +@code{set style variable} family of commands. By default, this style's +foreground color is cyan. + +@item address +Control the styling of addresses. These are managed with the +@code{set style address} family of commands. By default, this style's +foreground color is blue. + +This style is also used for addresses in styled disassembler output +if @value{GDBN} is using its builtin disassembler library for styling +(@pxref{style_disassembler_enabled,,@kbd{set style disassembler +enabled}}). + +@item version +Control the styling of @value{GDBN}'s version number text. By +default, this style's foreground color is magenta and it has bold +intensity. The version number is displayed in two places, the output +of @command{show version}, and when @value{GDBN} starts up. + +In order to control how @value{GDBN} styles the version number at +startup, add the @code{set style version} family of commands to the +early initialization command file (@pxref{Initialization +Files}). + +@item title +Control the styling of titles. These are managed with the +@code{set style title} family of commands. By default, this style's +intensity is bold. The title style is used when displaying the header +line of a list, for example the first line of the output of +@code{info breakpoints} (@pxref{Set Breaks}). + +@item highlight +Control the styling of highlightings. These are managed with the +@code{set style highlight} family of commands. By default, this style's +foreground color is red. Commands are using the highlight style to draw +the user attention to some specific parts of their output. For example, +the command @command{apropos -v REGEXP} uses the highlight style to +mark the documentation parts matching @var{regexp}. + +@item metadata +Control the styling of data annotations added by @value{GDBN} to data +it displays. By default, this style's intensity is dim. Metadata +annotations include the @samp{repeats @var{n} times} annotation for +suppressed display of repeated array elements (@pxref{Print Settings}), +@samp{} and @w{@samp{}} annotations +for errors and @samp{} annotations for optimized-out +values in displaying stack frame information in backtraces +(@pxref{Backtrace}), etc. + +@item tui-border +Control the styling of the TUI border. Note that, unlike other +styling options, only the color of the border can be controlled via +@code{set style}. This was done for compatibility reasons, as TUI +controls to set the border's intensity predated the addition of +general styling to @value{GDBN}. @xref{TUI Configuration}. + +@item tui-active-border +Control the styling of the active TUI border; that is, the TUI window +that has the focus. + +@item disassembler comment +Control the styling of comments in the disassembler output. These are +managed with the @code{set style disassembler comment} family of +commands. This style is only used when @value{GDBN} is styling using +its builtin disassembler library +(@pxref{style_disassembler_enabled,,@kbd{set style disassembler +enabled}}). By default, this style's intensity is dim, and its +foreground color is white. + +@item disassembler immediate +Control the styling of numeric operands in the disassembler output. +These are managed with the @code{set style disassembler immediate} +family of commands. This style is not used for instruction operands +that represent addresses, in that case the @samp{disassembler address} +style is used. This style is only used when @value{GDBN} is styling +using its builtin disassembler library. By default, this style's +foreground color is blue. + +@item disassembler address +Control the styling of address operands in the disassembler output. +This is an alias for the @samp{address} style. + +@item disassembler symbol +Control the styling of symbol names in the disassembler output. This +is an alias for the @samp{function} style. + +@item disassembler mnemonic +Control the styling of instruction mnemonics in the disassembler +output. These are managed with the @code{set style disassembler +mnemonic} family of commands. This style is also used for assembler +directives, e.g.@: @code{.byte}, @code{.word}, etc. This style is +only used when @value{GDBN} is styling using its builtin disassembler +library. By default, this style's foreground color is green. + +@item disassembler register +Control the styling of register operands in the disassembler output. +These are managed with the @code{set style disassembler register} +family of commands. This style is only used when @value{GDBN} is +styling using its builtin disassembler library. By default, this style's +foreground color is red. + +@end table + +@node Numbers +@section Numbers +@cindex number representation +@cindex entering numbers + +You can always enter numbers in octal, decimal, or hexadecimal in +@value{GDBN} by the usual conventions: octal numbers begin with +@samp{0}, decimal numbers end with @samp{.}, and hexadecimal numbers +begin with @samp{0x}. Numbers that neither begin with @samp{0} or +@samp{0x}, nor end with a @samp{.} are, by default, entered in base +10; likewise, the default display for numbers---when no particular +format is specified---is base 10. You can change the default base for +both input and output with the commands described below. + +@table @code +@kindex set input-radix +@item set input-radix @var{base} +Set the default base for numeric input. Supported choices +for @var{base} are decimal 8, 10, or 16. The base must itself be +specified either unambiguously or using the current input radix; for +example, any of + +@smallexample +set input-radix 012 +set input-radix 10. +set input-radix 0xa +@end smallexample + +@noindent +sets the input base to decimal. On the other hand, @samp{set input-radix 10} +leaves the input radix unchanged, no matter what it was, since +@samp{10}, being without any leading or trailing signs of its base, is +interpreted in the current radix. Thus, if the current radix is 16, +@samp{10} is interpreted in hex, i.e.@: as 16 decimal, which doesn't +change the radix. + +@kindex set output-radix +@item set output-radix @var{base} +Set the default base for numeric display. Supported choices +for @var{base} are decimal 8, 10, or 16. The base must itself be +specified either unambiguously or using the current input radix. + +@kindex show input-radix +@item show input-radix +Display the current default base for numeric input. + +@kindex show output-radix +@item show output-radix +Display the current default base for numeric display. + +@item set radix @r{[}@var{base}@r{]} +@itemx show radix +@kindex set radix +@kindex show radix +These commands set and show the default base for both input and output +of numbers. @code{set radix} sets the radix of input and output to +the same base; without an argument, it resets the radix back to its +default value of 10. + +@end table + +@node ABI +@section Configuring the Current ABI + +@value{GDBN} can determine the @dfn{ABI} (Application Binary Interface) of your +application automatically. However, sometimes you need to override its +conclusions. Use these commands to manage @value{GDBN}'s view of the +current ABI. + +@cindex OS ABI +@kindex set osabi +@kindex show osabi +@cindex Newlib OS ABI and its influence on the longjmp handling + +One @value{GDBN} configuration can debug binaries for multiple operating +system targets, either via remote debugging or native emulation. +@value{GDBN} will autodetect the @dfn{OS ABI} (Operating System ABI) in use, +but you can override its conclusion using the @code{set osabi} command. +One example where this is useful is in debugging of binaries which use +an alternate C library (e.g.@: @sc{uClibc} for @sc{gnu}/Linux) which does +not have the same identifying marks that the standard C library for your +platform provides. + +When @value{GDBN} is debugging the AArch64 architecture, it provides a +``Newlib'' OS ABI. This is useful for handling @code{setjmp} and +@code{longjmp} when debugging binaries that use the @sc{newlib} C library. +The ``Newlib'' OS ABI can be selected by @code{set osabi Newlib}. + +@table @code +@item show osabi +Show the OS ABI currently in use. + +@item set osabi +With no argument, show the list of registered available OS ABI's. + +@item set osabi @var{abi} +Set the current OS ABI to @var{abi}. +@end table + +@cindex float promotion + +Generally, the way that an argument of type @code{float} is passed to a +function depends on whether the function is prototyped. For a prototyped +(i.e.@: ANSI/ISO style) function, @code{float} arguments are passed unchanged, +according to the architecture's convention for @code{float}. For unprototyped +(i.e.@: K&R style) functions, @code{float} arguments are first promoted to type +@code{double} and then passed. + +Unfortunately, some forms of debug information do not reliably indicate whether +a function is prototyped. If @value{GDBN} calls a function that is not marked +as prototyped, it consults @kbd{set coerce-float-to-double}. + +@table @code +@kindex set coerce-float-to-double +@item set coerce-float-to-double +@itemx set coerce-float-to-double on +Arguments of type @code{float} will be promoted to @code{double} when passed +to an unprototyped function. This is the default setting. + +@item set coerce-float-to-double off +Arguments of type @code{float} will be passed directly to unprototyped +functions. + +@kindex show coerce-float-to-double +@item show coerce-float-to-double +Show the current setting of promoting @code{float} to @code{double}. +@end table + +@kindex set cp-abi +@kindex show cp-abi +@value{GDBN} needs to know the ABI used for your program's C@t{++} +objects. The correct C@t{++} ABI depends on which C@t{++} compiler was +used to build your application. @value{GDBN} only fully supports +programs with a single C@t{++} ABI; if your program contains code using +multiple C@t{++} ABI's or if @value{GDBN} can not identify your +program's ABI correctly, you can tell @value{GDBN} which ABI to use. +Currently supported ABI's include ``gnu-v2'', for @code{g++} versions +before 3.0, ``gnu-v3'', for @code{g++} versions 3.0 and later, and +``hpaCC'' for the HP ANSI C@t{++} compiler. Other C@t{++} compilers may +use the ``gnu-v2'' or ``gnu-v3'' ABI's as well. The default setting is +``auto''. + +@table @code +@item show cp-abi +Show the C@t{++} ABI currently in use. + +@item set cp-abi +With no argument, show the list of supported C@t{++} ABI's. + +@item set cp-abi @var{abi} +@itemx set cp-abi auto +Set the current C@t{++} ABI to @var{abi}, or return to automatic detection. +@end table + +@node Auto-loading +@section Automatically loading associated files +@cindex auto-loading + +@value{GDBN} sometimes reads files with commands and settings automatically, +without being explicitly told so by the user. We call this feature +@dfn{auto-loading}. While auto-loading is useful for automatically adapting +@value{GDBN} to the needs of your project, it can sometimes produce unexpected +results or introduce security risks (e.g., if the file comes from untrusted +sources). + +There are various kinds of files @value{GDBN} can automatically load. +In addition to these files, @value{GDBN} supports auto-loading code written +in various extension languages. @xref{Auto-loading extensions}. + +Note that loading of these associated files (including the local @file{.gdbinit} +file) requires accordingly configured @code{auto-load safe-path} +(@pxref{Auto-loading safe path}). + +For these reasons, @value{GDBN} includes commands and options to let you +control when to auto-load files and which files should be auto-loaded. + +@table @code +@anchor{set auto-load off} +@kindex set auto-load off +@item set auto-load off +Globally disable loading of all auto-loaded files. +You may want to use this command with the @samp{-iex} option +(@pxref{Option -init-eval-command}) such as: +@smallexample +$ @kbd{gdb -iex "set auto-load off" untrusted-executable corefile} +@end smallexample + +Be aware that system init file (@pxref{System-wide configuration}) +and init files from your home directory (@pxref{Home Directory Init File}) +still get read (as they come from generally trusted directories). +To prevent @value{GDBN} from auto-loading even those init files, use the +@option{-nx} option (@pxref{Mode Options}), in addition to +@code{set auto-load no}. + +@anchor{show auto-load} +@kindex show auto-load +@item show auto-load +Show whether auto-loading of each specific @samp{auto-load} file(s) is enabled +or disabled. + +@smallexample +(@value{GDBP}) show auto-load +gdb-scripts: Auto-loading of canned sequences of commands scripts is on. +libthread-db: Auto-loading of inferior specific libthread_db is on. +local-gdbinit: Auto-loading of .gdbinit script from current directory + is on. +python-scripts: Auto-loading of Python scripts is on. +safe-path: List of directories from which it is safe to auto-load files + is $debugdir:$datadir/auto-load. +scripts-directory: List of directories from which to load auto-loaded scripts + is $debugdir:$datadir/auto-load. +@end smallexample + +@anchor{info auto-load} +@kindex info auto-load +@item info auto-load +Print whether each specific @samp{auto-load} file(s) have been auto-loaded or +not. + +@smallexample +(@value{GDBP}) info auto-load +gdb-scripts: +Loaded Script +Yes /home/user/gdb/gdb-gdb.gdb +libthread-db: No auto-loaded libthread-db. +local-gdbinit: Local .gdbinit file "/home/user/gdb/.gdbinit" has been + loaded. +python-scripts: +Loaded Script +Yes /home/user/gdb/gdb-gdb.py +@end smallexample +@end table + +These are @value{GDBN} control commands for the auto-loading: + +@multitable @columnfractions .5 .5 +@item @xref{set auto-load off}. +@tab Disable auto-loading globally. +@item @xref{show auto-load}. +@tab Show setting of all kinds of files. +@item @xref{info auto-load}. +@tab Show state of all kinds of files. +@item @xref{set auto-load gdb-scripts}. +@tab Control for @value{GDBN} command scripts. +@item @xref{show auto-load gdb-scripts}. +@tab Show setting of @value{GDBN} command scripts. +@item @xref{info auto-load gdb-scripts}. +@tab Show state of @value{GDBN} command scripts. +@item @xref{set auto-load python-scripts}. +@tab Control for @value{GDBN} Python scripts. +@item @xref{show auto-load python-scripts}. +@tab Show setting of @value{GDBN} Python scripts. +@item @xref{info auto-load python-scripts}. +@tab Show state of @value{GDBN} Python scripts. +@item @xref{set auto-load guile-scripts}. +@tab Control for @value{GDBN} Guile scripts. +@item @xref{show auto-load guile-scripts}. +@tab Show setting of @value{GDBN} Guile scripts. +@item @xref{info auto-load guile-scripts}. +@tab Show state of @value{GDBN} Guile scripts. +@item @xref{set auto-load scripts-directory}. +@tab Control for @value{GDBN} auto-loaded scripts location. +@item @xref{show auto-load scripts-directory}. +@tab Show @value{GDBN} auto-loaded scripts location. +@item @xref{add-auto-load-scripts-directory}. +@tab Add directory for auto-loaded scripts location list. +@item @xref{set auto-load local-gdbinit}. +@tab Control for init file in the current directory. +@item @xref{show auto-load local-gdbinit}. +@tab Show setting of init file in the current directory. +@item @xref{info auto-load local-gdbinit}. +@tab Show state of init file in the current directory. +@item @xref{set auto-load libthread-db}. +@tab Control for thread debugging library. +@item @xref{show auto-load libthread-db}. +@tab Show setting of thread debugging library. +@item @xref{info auto-load libthread-db}. +@tab Show state of thread debugging library. +@item @xref{set auto-load safe-path}. +@tab Control directories trusted for automatic loading. +@item @xref{show auto-load safe-path}. +@tab Show directories trusted for automatic loading. +@item @xref{add-auto-load-safe-path}. +@tab Add directory trusted for automatic loading. +@end multitable + +@menu +* Init File in the Current Directory:: @samp{set/show/info auto-load local-gdbinit} +* libthread_db.so.1 file:: @samp{set/show/info auto-load libthread-db} + +* Auto-loading safe path:: @samp{set/show/info auto-load safe-path} +* Auto-loading verbose mode:: @samp{set/show debug auto-load} +@end menu + +@node Init File in the Current Directory +@subsection Automatically loading init file in the current directory +@cindex auto-loading init file in the current directory + +By default, @value{GDBN} reads and executes the canned sequences of commands +from init file (if any) in the current working directory, +see @ref{Init File in the Current Directory during Startup}. + +Note that loading of this local @file{.gdbinit} file also requires accordingly +configured @code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +@table @code +@anchor{set auto-load local-gdbinit} +@kindex set auto-load local-gdbinit +@item set auto-load local-gdbinit [on|off] +Enable or disable the auto-loading of canned sequences of commands +(@pxref{Sequences}) found in init file in the current directory. + +@anchor{show auto-load local-gdbinit} +@kindex show auto-load local-gdbinit +@item show auto-load local-gdbinit +Show whether auto-loading of canned sequences of commands from init file in the +current directory is enabled or disabled. + +@anchor{info auto-load local-gdbinit} +@kindex info auto-load local-gdbinit +@item info auto-load local-gdbinit +Print whether canned sequences of commands from init file in the +current directory have been auto-loaded. +@end table + +@node libthread_db.so.1 file +@subsection Automatically loading thread debugging library +@cindex auto-loading libthread_db.so.1 + +This feature is currently present only on @sc{gnu}/Linux native hosts. + +@value{GDBN} reads in some cases thread debugging library from places specific +to the inferior (@pxref{set libthread-db-search-path}). + +The special @samp{libthread-db-search-path} entry @samp{$sdir} is processed +without checking this @samp{set auto-load libthread-db} switch as system +libraries have to be trusted in general. In all other cases of +@samp{libthread-db-search-path} entries @value{GDBN} checks first if @samp{set +auto-load libthread-db} is enabled before trying to open such thread debugging +library. + +Note that loading of this debugging library also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +@table @code +@anchor{set auto-load libthread-db} +@kindex set auto-load libthread-db +@item set auto-load libthread-db [on|off] +Enable or disable the auto-loading of inferior specific thread debugging library. + +@anchor{show auto-load libthread-db} +@kindex show auto-load libthread-db +@item show auto-load libthread-db +Show whether auto-loading of inferior specific thread debugging library is +enabled or disabled. + +@anchor{info auto-load libthread-db} +@kindex info auto-load libthread-db +@item info auto-load libthread-db +Print the list of all loaded inferior specific thread debugging libraries and +for each such library print list of inferior @var{pid}s using it. +@end table + +@node Auto-loading safe path +@subsection Security restriction for auto-loading +@cindex auto-loading safe-path + +As the files of inferior can come from untrusted source (such as submitted by +an application user) @value{GDBN} does not always load any files automatically. +@value{GDBN} provides the @samp{set auto-load safe-path} setting to list +directories trusted for loading files not explicitly requested by user. +Each directory can also be a shell wildcard pattern. + +If the path is not set properly you will see a warning and the file will not +get loaded: + +@smallexample +$ ./gdb -q ./gdb +Reading symbols from /home/user/gdb/gdb... +warning: File "/home/user/gdb/gdb-gdb.gdb" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". +warning: File "/home/user/gdb/gdb-gdb.py" auto-loading has been + declined by your `auto-load safe-path' set + to "$debugdir:$datadir/auto-load". +@end smallexample + +@noindent +To instruct @value{GDBN} to go ahead and use the init files anyway, +invoke @value{GDBN} like this: + +@smallexample +$ gdb -q -iex "set auto-load safe-path /home/user/gdb" ./gdb +@end smallexample + +The list of trusted directories is controlled by the following commands: + +@table @code +@anchor{set auto-load safe-path} +@kindex set auto-load safe-path +@item set auto-load safe-path @r{[}@var{directories}@r{]} +Set the list of directories (and their subdirectories) trusted for automatic +loading and execution of scripts. You can also enter a specific trusted file. +Each directory can also be a shell wildcard pattern; wildcards do not match +directory separator - see @code{FNM_PATHNAME} for system function @code{fnmatch} +(@pxref{Wildcard Matching, fnmatch, , libc, GNU C Library Reference Manual}). +If you omit @var{directories}, @samp{auto-load safe-path} will be reset to +its default value as specified during @value{GDBN} compilation. + +The list of directories uses path separator (@samp{:} on GNU and Unix +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly +to the @env{PATH} environment variable. + +@anchor{show auto-load safe-path} +@kindex show auto-load safe-path +@item show auto-load safe-path +Show the list of directories trusted for automatic loading and execution of +scripts. + +@anchor{add-auto-load-safe-path} +@kindex add-auto-load-safe-path +@item add-auto-load-safe-path +Add an entry (or list of entries) to the list of directories trusted for +automatic loading and execution of scripts. Multiple entries may be delimited +by the host platform path separator in use. +@end table + +This variable defaults to what @code{--with-auto-load-dir} has been configured +to (@pxref{with-auto-load-dir}). @file{$debugdir} and @file{$datadir} +substitution applies the same as for @ref{set auto-load scripts-directory}. +The default @code{set auto-load safe-path} value can be also overridden by +@value{GDBN} configuration option @option{--with-auto-load-safe-path}. + +Setting this variable to @file{/} disables this security protection, +corresponding @value{GDBN} configuration option is +@option{--without-auto-load-safe-path}. +This variable is supposed to be set to the system directories writable by the +system superuser only. Users can add their source directories in init files in +their home directories (@pxref{Home Directory Init File}). See also deprecated +init file in the current directory +(@pxref{Init File in the Current Directory during Startup}). + +To force @value{GDBN} to load the files it declined to load in the previous +example, you could use one of the following ways: + +@table @asis +@item @file{~/.gdbinit}: @samp{add-auto-load-safe-path ~/src/gdb} +Specify this trusted directory (or a file) as additional component of the list. +You have to specify also any existing directories displayed by +by @samp{show auto-load safe-path} (such as @samp{/usr:/bin} in this example). + +@item @kbd{gdb -iex "set auto-load safe-path /usr:/bin:~/src/gdb" @dots{}} +Specify this directory as in the previous case but just for a single +@value{GDBN} session. + +@item @kbd{gdb -iex "set auto-load safe-path /" @dots{}} +Disable auto-loading safety for a single @value{GDBN} session. +This assumes all the files you debug during this @value{GDBN} session will come +from trusted sources. + +@item @kbd{./configure --without-auto-load-safe-path} +During compilation of @value{GDBN} you may disable any auto-loading safety. +This assumes all the files you will ever debug with this @value{GDBN} come from +trusted sources. +@end table + +On the other hand you can also explicitly forbid automatic files loading which +also suppresses any such warning messages: + +@table @asis +@item @kbd{gdb -iex "set auto-load no" @dots{}} +You can use @value{GDBN} command-line option for a single @value{GDBN} session. + +@item @file{~/.gdbinit}: @samp{set auto-load no} +Disable auto-loading globally for the user +(@pxref{Home Directory Init File}). While it is improbable, you could also +use system init file instead (@pxref{System-wide configuration}). +@end table + +This setting applies to the file names as entered by user. If no entry matches +@value{GDBN} tries as a last resort to also resolve all the file names into +their canonical form (typically resolving symbolic links) and compare the +entries again. @value{GDBN} already canonicalizes most of the filenames on its +own before starting the comparison so a canonical form of directories is +recommended to be entered. + +@node Auto-loading verbose mode +@subsection Displaying files tried for auto-load +@cindex auto-loading verbose mode + +For better visibility of all the file locations where you can place scripts to +be auto-loaded with inferior --- or to protect yourself against accidental +execution of untrusted scripts --- @value{GDBN} provides a feature for printing +all the files attempted to be loaded. Both existing and non-existing files may +be printed. + +For example the list of directories from which it is safe to auto-load files +(@pxref{Auto-loading safe path}) applies also to canonicalized filenames which +may not be too obvious while setting it up. + +@smallexample +(@value{GDBP}) set debug auto-load on +(@value{GDBP}) file ~/src/t/true +auto-load: Loading canned sequences of commands script "/tmp/true-gdb.gdb" + for objfile "/tmp/true". +auto-load: Updating directories of "/usr:/opt". +auto-load: Using directory "/usr". +auto-load: Using directory "/opt". +warning: File "/tmp/true-gdb.gdb" auto-loading has been declined + by your `auto-load safe-path' set to "/usr:/opt". +@end smallexample + +@table @code +@anchor{set debug auto-load} +@kindex set debug auto-load +@item set debug auto-load [on|off] +Set whether to print the filenames attempted to be auto-loaded. + +@anchor{show debug auto-load} +@kindex show debug auto-load +@item show debug auto-load +Show whether printing of the filenames attempted to be auto-loaded is turned +on or off. +@end table + +@node Messages/Warnings +@section Optional Warnings and Messages + +@cindex verbose operation +@cindex optional warnings +By default, @value{GDBN} is silent about its inner workings. If you are +running on a slow machine, you may want to use the @code{set verbose} +command. This makes @value{GDBN} tell you when it does a lengthy +internal operation, so you will not think it has crashed. + +Currently, the messages controlled by @code{set verbose} are those +which announce that the symbol table for a source file is being read; +see @code{symbol-file} in @ref{Files, ,Commands to Specify Files}. + +@table @code +@kindex set verbose +@item set verbose on +Enables @value{GDBN} output of certain informational messages. + +@item set verbose off +Disables @value{GDBN} output of certain informational messages. + +@kindex show verbose +@item show verbose +Displays whether @code{set verbose} is on or off. +@end table + +By default, if @value{GDBN} encounters bugs in the symbol table of an +object file, it is silent; but if you are debugging a compiler, you may +find this information useful (@pxref{Symbol Errors, ,Errors Reading +Symbol Files}). + +@table @code + +@kindex set complaints +@item set complaints @var{limit} +Permits @value{GDBN} to output @var{limit} complaints about each type of +unusual symbols before becoming silent about the problem. Set +@var{limit} to zero to suppress all complaints; set it to a large number +to prevent complaints from being suppressed. + +@kindex show complaints +@item show complaints +Displays how many symbol complaints @value{GDBN} is permitted to produce. + +@end table + +@anchor{confirmation requests} +By default, @value{GDBN} is cautious, and asks what sometimes seems to be a +lot of stupid questions to confirm certain commands. For example, if +you try to run a program which is already running: + +@smallexample +(@value{GDBP}) run +The program being debugged has been started already. +Start it from the beginning? (y or n) +@end smallexample + +If you are willing to unflinchingly face the consequences of your own +commands, you can disable this ``feature'': + +@table @code + +@kindex set confirm +@cindex flinching +@cindex confirmation +@cindex stupid questions +@item set confirm off +Disables confirmation requests. Note that running @value{GDBN} with +the @option{--batch} option (@pxref{Mode Options, -batch}) also +automatically disables confirmation requests. + +@item set confirm on +Enables confirmation requests (the default). + +@kindex show confirm +@item show confirm +Displays state of confirmation requests. + +@end table + +@cindex command tracing +If you need to debug user-defined commands or sourced files you may find it +useful to enable @dfn{command tracing}. In this mode each command will be +printed as it is executed, prefixed with one or more @samp{+} symbols, the +quantity denoting the call depth of each command. + +@table @code +@kindex set trace-commands +@cindex command scripts, debugging +@item set trace-commands on +Enable command tracing. +@item set trace-commands off +Disable command tracing. +@item show trace-commands +Display the current state of command tracing. +@end table + +@node Debugging Output +@section Optional Messages about Internal Happenings +@cindex optional debugging messages + +@value{GDBN} has commands that enable optional debugging messages from +various @value{GDBN} subsystems; normally these commands are of +interest to @value{GDBN} maintainers, or when reporting a bug. This +section documents those commands. + +@table @code +@kindex set exec-done-display +@item set exec-done-display +Turns on or off the notification of asynchronous commands' +completion. When on, @value{GDBN} will print a message when an +asynchronous command finishes its execution. The default is off. +@kindex show exec-done-display +@item show exec-done-display +Displays the current setting of asynchronous command completion +notification. + +@kindex set debug +@cindex ARM AArch64 +@item set debug aarch64 +Turns on or off display of debugging messages related to ARM AArch64. +The default is off. +@kindex show debug +@item show debug aarch64 +Displays the current state of displaying debugging messages related to +ARM AArch64. + +@cindex gdbarch debugging info +@cindex architecture debugging info +@item set debug arch +Turns on or off display of gdbarch debugging info. The default is off +@item show debug arch +Displays the current state of displaying gdbarch debugging info. + +@item set debug aix-thread +@cindex AIX threads +Display debugging messages about inner workings of the AIX thread +module. +@item show debug aix-thread +Show the current state of AIX thread debugging info display. + +@cindex AMD GPU debugging info +@anchor{set debug amd-dbgapi-lib} +@item set debug amd-dbgapi-lib +@itemx show debug amd-dbgapi-lib + +The @code{set debug amd-dbgapi-lib log-level @var{level}} command can be used +to enable diagnostic messages from the @samp{amd-dbgapi} library, where +@var{level} can be: + +@table @code + +@item off +no logging is enabled + +@item error +fatal errors are reported + +@item warning +fatal errors and warnings are reported + +@item info +fatal errors, warnings, and info messages are reported + +@item verbose +all messages are reported + +@end table + +The @code{show debug amd-dbgapi-lib log-level} command displays the current +@acronym{amd-dbgapi} library log level. + +@anchor{set debug amd-dbgapi} +@item set debug amd-dbgapi +@itemx show debug amd-dbgapi + +The @samp{set debug amd-dbgapi} command can be used +to enable diagnostic messages in the @samp{amd-dbgapi} target. The +@samp{show debug amd-dbgapi} command displays the current setting. +@xref{set debug amd-dbgapi}. + +@item set debug check-physname +@cindex physname +Check the results of the ``physname'' computation. When reading DWARF +debugging information for C@t{++}, @value{GDBN} attempts to compute +each entity's name. @value{GDBN} can do this computation in two +different ways, depending on exactly what information is present. +When enabled, this setting causes @value{GDBN} to compute the names +both ways and display any discrepancies. +@item show debug check-physname +Show the current state of ``physname'' checking. + +@item set debug coff-pe-read +@cindex COFF/PE exported symbols +Control display of debugging messages related to reading of COFF/PE +exported symbols. The default is off. +@item show debug coff-pe-read +Displays the current state of displaying debugging messages related to +reading of COFF/PE exported symbols. + +@item set debug dwarf-die +@cindex DWARF DIEs +Dump DWARF DIEs after they are read in. +The value is the number of nesting levels to print. +A value of zero turns off the display. +@item show debug dwarf-die +Show the current state of DWARF DIE debugging. + +@item set debug dwarf-line +@cindex DWARF Line Tables +Turns on or off display of debugging messages related to reading +DWARF line tables. The default is 0 (off). +A value of 1 provides basic information. +A value greater than 1 provides more verbose information. +@item show debug dwarf-line +Show the current state of DWARF line table debugging. + +@item set debug dwarf-read +@cindex DWARF Reading +Turns on or off display of debugging messages related to reading +DWARF debug info. The default is 0 (off). +A value of 1 provides basic information. +A value greater than 1 provides more verbose information. +@item show debug dwarf-read +Show the current state of DWARF reader debugging. + +@item set debug displaced +@cindex displaced stepping debugging info +Turns on or off display of @value{GDBN} debugging info for the +displaced stepping support. The default is off. +@item show debug displaced +Displays the current state of displaying @value{GDBN} debugging info +related to displaced stepping. + +@item set debug event +@cindex event debugging info +Turns on or off display of @value{GDBN} event debugging info. The +default is off. +@item show debug event +Displays the current state of displaying @value{GDBN} event debugging +info. + +@item set debug event-loop +@cindex event-loop debugging +Controls output of debugging info about the event loop. The possible +values are @samp{off}, @samp{all} (shows all debugging info) and +@samp{all-except-ui} (shows all debugging info except those about +UI-related events). +@item show debug event-loop +Shows the current state of displaying debugging info about the event +loop. + +@item set debug expression +@cindex expression debugging info +Turns on or off display of debugging info about @value{GDBN} +expression parsing. The default is off. +@item show debug expression +Displays the current state of displaying debugging info about +@value{GDBN} expression parsing. + +@item set debug fbsd-lwp +@cindex FreeBSD LWP debug messages +Turns on or off debugging messages from the FreeBSD LWP debug support. +@item show debug fbsd-lwp +Show the current state of FreeBSD LWP debugging messages. + +@item set debug fbsd-nat +@cindex FreeBSD native target debug messages +Turns on or off debugging messages from the FreeBSD native target. +@item show debug fbsd-nat +Show the current state of FreeBSD native target debugging messages. + +@item set debug fortran-array-slicing +@cindex fortran array slicing debugging info +Turns on or off display of @value{GDBN} Fortran array slicing +debugging info. The default is off. + +@item show debug fortran-array-slicing +Displays the current state of displaying @value{GDBN} Fortran array +slicing debugging info. + +@item set debug frame +@cindex frame debugging info +Turns on or off display of @value{GDBN} frame debugging info. The +default is off. +@item show debug frame +Displays the current state of displaying @value{GDBN} frame debugging +info. + +@item set debug gnu-nat +@cindex @sc{gnu}/Hurd debug messages +Turn on or off debugging messages from the @sc{gnu}/Hurd debug support. +@item show debug gnu-nat +Show the current state of @sc{gnu}/Hurd debugging messages. + +@item set debug infrun +@cindex inferior debugging info +Turns on or off display of @value{GDBN} debugging info for running the inferior. +The default is off. @file{infrun.c} contains GDB's runtime state machine used +for implementing operations such as single-stepping the inferior. +@item show debug infrun +Displays the current state of @value{GDBN} inferior debugging. + +@item set debug infcall +@cindex inferior function call debugging info +Turns on or off display of debugging info related to inferior function +calls made by @value{GDBN}. +@item show debug infcall +Displays the current state of @value{GDBN} inferior function call debugging. + +@item set debug jit +@cindex just-in-time compilation, debugging messages +Turn on or off debugging messages from JIT debug support. +@item show debug jit +Displays the current state of @value{GDBN} JIT debugging. + +@item set debug linux-nat @r{[}on@r{|}off@r{]} +@cindex @sc{gnu}/Linux native target debug messages +@cindex Linux native targets +Turn on or off debugging messages from the Linux native target debug support. +@item show debug linux-nat +Show the current state of Linux native target debugging messages. + +@item set debug linux-namespaces +@cindex @sc{gnu}/Linux namespaces debug messages +Turn on or off debugging messages from the Linux namespaces debug support. +@item show debug linux-namespaces +Show the current state of Linux namespaces debugging messages. + +@item set debug mach-o +@cindex Mach-O symbols processing +Control display of debugging messages related to Mach-O symbols +processing. The default is off. +@item show debug mach-o +Displays the current state of displaying debugging messages related to +reading of COFF/PE exported symbols. + +@item set debug notification +@cindex remote async notification debugging info +Turn on or off debugging messages about remote async notification. +The default is off. +@item show debug notification +Displays the current state of remote async notification debugging messages. + +@item set debug observer +@cindex observer debugging info +Turns on or off display of @value{GDBN} observer debugging. This +includes info such as the notification of observable events. +@item show debug observer +Displays the current state of observer debugging. + +@item set debug overload +@cindex C@t{++} overload debugging info +Turns on or off display of @value{GDBN} C@t{++} overload debugging +info. This includes info such as ranking of functions, etc. The default +is off. +@item show debug overload +Displays the current state of displaying @value{GDBN} C@t{++} overload +debugging info. + +@cindex expression parser, debugging info +@cindex debug expression parser +@item set debug parser +Turns on or off the display of expression parser debugging output. +Internally, this sets the @code{yydebug} variable in the expression +parser. @xref{Tracing, , Tracing Your Parser, bison, Bison}, for +details. The default is off. +@item show debug parser +Show the current state of expression parser debugging. + +@cindex packets, reporting on stdout +@cindex serial connections, debugging +@cindex debug remote protocol +@cindex remote protocol debugging +@cindex display remote packets +@item set debug remote +Turns on or off display of reports on all packets sent back and forth across +the serial line to the remote machine. The info is printed on the +@value{GDBN} standard output stream. The default is off. +@item show debug remote +Displays the state of display of remote packets. + +@item set debug remote-packet-max-chars +Sets the maximum number of characters to display for each remote packet when +@code{set debug remote} is on. This is useful to prevent @value{GDBN} from +displaying lengthy remote packets and polluting the console. + +The default value is @code{512}, which means @value{GDBN} will truncate each +remote packet after 512 bytes. + +Setting this option to @code{unlimited} will disable truncation and will output +the full length of the remote packets. +@item show debug remote-packet-max-chars +Displays the number of bytes to output for remote packet debugging. + +@item set debug separate-debug-file +Turns on or off display of debug output about separate debug file search. +@item show debug separate-debug-file +Displays the state of separate debug file search debug output. + +@item set debug serial +Turns on or off display of @value{GDBN} serial debugging info. The +default is off. +@item show debug serial +Displays the current state of displaying @value{GDBN} serial debugging +info. + +@item set debug solib +Turns on or off display of debugging messages related to shared libraries. +The default is off. +@item show debug solib +Show the current state of solib debugging messages. + +@item set debug symbol-lookup +@cindex symbol lookup +Turns on or off display of debugging messages related to symbol lookup. +The default is 0 (off). +A value of 1 provides basic information. +A value greater than 1 provides more verbose information. +@item show debug symbol-lookup +Show the current state of symbol lookup debugging messages. + +@item set debug symfile +@cindex symbol file functions +Turns on or off display of debugging messages related to symbol file functions. +The default is off. @xref{Files}. +@item show debug symfile +Show the current state of symbol file debugging messages. + +@item set debug symtab-create +@cindex symbol table creation +Turns on or off display of debugging messages related to symbol table creation. +The default is 0 (off). +A value of 1 provides basic information. +A value greater than 1 provides more verbose information. +@item show debug symtab-create +Show the current state of symbol table creation debugging. + +@item set debug target +@cindex target debugging info +Turns on or off display of @value{GDBN} target debugging info. This info +includes what is going on at the target level of GDB, as it happens. The +default is 0. Set it to 1 to track events, and to 2 to also track the +value of large memory transfers. +@item show debug target +Displays the current state of displaying @value{GDBN} target debugging +info. + +@item set debug timestamp +@cindex timestamping debugging info +Turns on or off display of timestamps with @value{GDBN} debugging info. +When enabled, seconds and microseconds are displayed before each debugging +message. +@item show debug timestamp +Displays the current state of displaying timestamps with @value{GDBN} +debugging info. + +@item set debug varobj +@cindex variable object debugging info +Turns on or off display of @value{GDBN} variable object debugging +info. The default is off. +@item show debug varobj +Displays the current state of displaying @value{GDBN} variable object +debugging info. + +@item set debug xml +@cindex XML parser debugging +Turn on or off debugging messages for built-in XML parsers. +@item show debug xml +Displays the current state of XML debugging messages. + +@item set debug breakpoints +@cindex breakpoint debugging info +Turns on or off display of @value{GDBN} debugging info for breakpoint insertion +and removal. The default is off. +@item show debug breakpoints +Displays the current state of displaying @value{GDBN} debugging info for +breakpoint insertion and removal. +@end table + +@node Other Misc Settings +@section Other Miscellaneous Settings +@cindex miscellaneous settings + +@table @code +@kindex set interactive-mode +@item set interactive-mode +If @code{on}, forces @value{GDBN} to assume that GDB was started +in a terminal. In practice, this means that @value{GDBN} should wait +for the user to answer queries generated by commands entered at +the command prompt. If @code{off}, forces @value{GDBN} to operate +in the opposite mode, and it uses the default answers to all queries. +If @code{auto} (the default), @value{GDBN} tries to determine whether +its standard input is a terminal, and works in interactive-mode if it +is, non-interactively otherwise. + +In the vast majority of cases, the debugger should be able to guess +correctly which mode should be used. But this setting can be useful +in certain specific cases, such as running a MinGW @value{GDBN} +inside a cygwin window. + +@kindex show interactive-mode +@item show interactive-mode +Displays whether the debugger is operating in interactive mode or not. +@end table + +@table @code +@kindex set suppress-cli-notifications +@item set suppress-cli-notifications +If @code{on}, command-line-interface (CLI) notifications that are +printed by @value{GDBN} are suppressed. If @code{off}, the +notifications are printed as usual. The default value is @code{off}. +CLI notifications occur when you change the selected context or when +the program being debugged stops, as detailed below. + +@table @emph +@item User-selected context changes: +When you change the selected context (i.e.@: the current inferior, +thread and/or the frame), @value{GDBN} prints information about the +new context. For example, the default behavior is below: + +@smallexample +(gdb) inferior 1 +[Switching to inferior 1 [process 634] (/tmp/test)] +[Switching to thread 1 (process 634)] +#0 main () at test.c:3 +3 return 0; +(gdb) +@end smallexample + +When the notifications are suppressed, the new context is not printed: + +@smallexample +(gdb) set suppress-cli-notifications on +(gdb) inferior 1 +(gdb) +@end smallexample + +@item The program being debugged stops: +When the program you are debugging stops (e.g.@: because of hitting a +breakpoint, completing source-stepping, an interrupt, etc.), +@value{GDBN} prints information about the stop event. For example, +below is a breakpoint hit: + +@smallexample +(gdb) break test.c:3 +Breakpoint 2 at 0x555555555155: file test.c, line 3. +(gdb) continue +Continuing. + +Breakpoint 2, main () at test.c:3 +3 return 0; +(gdb) +@end smallexample + +When the notifications are suppressed, the output becomes: + +@smallexample +(gdb) break test.c:3 +Breakpoint 2 at 0x555555555155: file test.c, line 3. +(gdb) set suppress-cli-notifications on +(gdb) continue +Continuing. +(gdb) +@end smallexample + +Suppressing CLI notifications may be useful in scripts to obtain a +reduced output from a list of commands. +@end table + +@kindex show suppress-cli-notifications +@item show suppress-cli-notifications +Displays whether printing CLI notifications is suppressed or not. +@end table + +@node Extending GDB +@chapter Extending @value{GDBN} +@cindex extending GDB + +@value{GDBN} provides several mechanisms for extension. +@value{GDBN} also provides the ability to automatically load +extensions when it reads a file for debugging. This allows the +user to automatically customize @value{GDBN} for the program +being debugged. + +To facilitate the use of extension languages, @value{GDBN} is capable +of evaluating the contents of a file. When doing so, @value{GDBN} +can recognize which extension language is being used by looking at +the filename extension. Files with an unrecognized filename extension +are always treated as a @value{GDBN} Command Files. +@xref{Command Files,, Command files}. + +You can control how @value{GDBN} evaluates these files with the following +setting: + +@table @code +@kindex set script-extension +@kindex show script-extension +@item set script-extension off +All scripts are always evaluated as @value{GDBN} Command Files. + +@item set script-extension soft +The debugger determines the scripting language based on filename +extension. If this scripting language is supported, @value{GDBN} +evaluates the script using that language. Otherwise, it evaluates +the file as a @value{GDBN} Command File. + +@item set script-extension strict +The debugger determines the scripting language based on filename +extension, and evaluates the script using that language. If the +language is not supported, then the evaluation fails. + +@item show script-extension +Display the current value of the @code{script-extension} option. + +@end table + +@ifset SYSTEM_GDBINIT_DIR +This setting is not used for files in the system-wide gdbinit directory. +Files in that directory must have an extension matching their language, +or have a @file{.gdb} extension to be interpreted as regular @value{GDBN} +commands. @xref{Startup}. +@end ifset + +@menu +* Sequences:: Canned Sequences of @value{GDBN} Commands +* Aliases:: Command Aliases +* Python:: Extending @value{GDBN} using Python +* Guile:: Extending @value{GDBN} using Guile +* Auto-loading extensions:: Automatically loading extensions +* Multiple Extension Languages:: Working with multiple extension languages +@end menu + +@node Sequences +@section Canned Sequences of Commands + +Aside from breakpoint commands (@pxref{Break Commands, ,Breakpoint +Command Lists}), @value{GDBN} provides two ways to store sequences of +commands for execution as a unit: user-defined commands and command +files. + +@menu +* Define:: How to define your own commands +* Hooks:: Hooks for user-defined commands +* Command Files:: How to write scripts of commands to be stored in a file +* Output:: Commands for controlled output +* Auto-loading sequences:: Controlling auto-loaded command files +@end menu + +@node Define +@subsection User-defined Commands + +@cindex user-defined command +@cindex arguments, to user-defined commands +A @dfn{user-defined command} is a sequence of @value{GDBN} commands to +which you assign a new name as a command. This is done with the +@code{define} command. + +User commands may accept an unlimited number of arguments separated by +whitespace. Arguments are accessed within the user command via +@code{$arg0@dots{}$argN}. The arguments are text substitutions, so +they may reference variables, use complex expressions, or even perform +inferior functions calls. Note, however, that this textual +substitution means that working with certain arguments is difficult. +For example, there is no way for the user to pass an argument +containing a space; and while stringifying an argument can be done +using an expression like @code{"$arg1"}, this will fail if the +argument contains a quote. For more complicated and robust commands, +we recommend writing them in Python; see @ref{CLI Commands In Python}. + +A trivial example: + +@smallexample +define adder + print $arg0 + $arg1 + $arg2 +end +@end smallexample + +@noindent +To execute the command use: + +@smallexample +adder 1 2 3 +@end smallexample + +@noindent +This defines the command @code{adder}, which prints the sum of +its three arguments. + +@cindex argument count in user-defined commands +@cindex how many arguments (user-defined commands) +In addition, @code{$argc} may be used to find out how many arguments have +been passed. + +@smallexample +define adder + if $argc == 2 + print $arg0 + $arg1 + end + if $argc == 3 + print $arg0 + $arg1 + $arg2 + end +end +@end smallexample + +Combining with the @code{eval} command (@pxref{eval}) makes it easier +to process a variable number of arguments: + +@smallexample +define adder + set $i = 0 + set $sum = 0 + while $i < $argc + eval "set $sum = $sum + $arg%d", $i + set $i = $i + 1 + end + print $sum +end +@end smallexample + +@table @code + +@kindex define +@item define @var{commandname} +Define a command named @var{commandname}. If there is already a command +by that name, you are asked to confirm that you want to redefine it. +The argument @var{commandname} may be a bare command name consisting of letters, +numbers, dashes, dots, and underscores. It may also start with any +predefined or user-defined prefix command. +For example, @samp{define target my-target} creates +a user-defined @samp{target my-target} command. + +The definition of the command is made up of other @value{GDBN} command lines, +which are given following the @code{define} command. The end of these +commands is marked by a line containing @code{end}. + +@kindex document +@kindex end@r{ (user-defined commands)} +@item document @var{commandname} +Document the user-defined command @var{commandname}, so that it can be +accessed by @code{help}. The command @var{commandname} must already be +defined. This command reads lines of documentation just as @code{define} +reads the lines of the command definition, ending with @code{end}. +After the @code{document} command is finished, @code{help} on command +@var{commandname} displays the documentation you have written. + +You may use the @code{document} command again to change the +documentation of a command. Redefining the command with @code{define} +does not change the documentation. + +It is also possible to document user-defined aliases. The alias documentation +will then be used by the @code{help} and @code{apropos} commands +instead of the documentation of the aliased command. +Documenting a user-defined alias is particularly useful when defining +an alias as a set of nested @code{with} commands +(@pxref{Command aliases default args}). + +@kindex define-prefix +@item define-prefix @var{commandname} +Define or mark the command @var{commandname} as a user-defined prefix +command. Once marked, @var{commandname} can be used as prefix command +by the @code{define} command. +Note that @code{define-prefix} can be used with a not yet defined +@var{commandname}. In such a case, @var{commandname} is defined as +an empty user-defined command. +In case you redefine a command that was marked as a user-defined +prefix command, the subcommands of the redefined command are kept +(and @value{GDBN} indicates so to the user). + +Example: +@example +(@value{GDBP}) define-prefix abc +(@value{GDBP}) define-prefix abc def +(@value{GDBP}) define abc def +Type commands for definition of "abc def". +End with a line saying just "end". +>echo command initial def\n +>end +(@value{GDBP}) define abc def ghi +Type commands for definition of "abc def ghi". +End with a line saying just "end". +>echo command ghi\n +>end +(@value{GDBP}) define abc def +Keeping subcommands of prefix command "def". +Redefine command "def"? (y or n) y +Type commands for definition of "abc def". +End with a line saying just "end". +>echo command def\n +>end +(@value{GDBP}) abc def ghi +command ghi +(@value{GDBP}) abc def +command def +(@value{GDBP}) +@end example + +@kindex dont-repeat +@cindex don't repeat command +@item dont-repeat +Used inside a user-defined command, this tells @value{GDBN} that this +command should not be repeated when the user hits @key{RET} +(@pxref{Command Syntax, repeat last command}). + +@kindex help user-defined +@item help user-defined +List all user-defined commands and all python commands defined in class +COMMAND_USER. The first line of the documentation or docstring is +included (if any). + +@kindex show user +@item show user +@itemx show user @var{commandname} +Display the @value{GDBN} commands used to define @var{commandname} (but +not its documentation). If no @var{commandname} is given, display the +definitions for all user-defined commands. +This does not work for user-defined python commands. + +@cindex infinite recursion in user-defined commands +@kindex show max-user-call-depth +@kindex set max-user-call-depth +@item show max-user-call-depth +@itemx set max-user-call-depth +The value of @code{max-user-call-depth} controls how many recursion +levels are allowed in user-defined commands before @value{GDBN} suspects an +infinite recursion and aborts the command. +This does not apply to user-defined python commands. +@end table + +In addition to the above commands, user-defined commands frequently +use control flow commands, described in @ref{Command Files}. + +When user-defined commands are executed, the +commands of the definition are not printed. An error in any command +stops execution of the user-defined command. + +If used interactively, commands that would ask for confirmation proceed +without asking when used inside a user-defined command. Many @value{GDBN} +commands that normally print messages to say what they are doing omit the +messages when used in a user-defined command. + +@node Hooks +@subsection User-defined Command Hooks +@cindex command hooks +@cindex hooks, for commands +@cindex hooks, pre-command + +@kindex hook +You may define @dfn{hooks}, which are a special kind of user-defined +command. Whenever you run the command @samp{foo}, if the user-defined +command @samp{hook-foo} exists, it is executed (with no arguments) +before that command. + +@cindex hooks, post-command +@kindex hookpost +A hook may also be defined which is run after the command you executed. +Whenever you run the command @samp{foo}, if the user-defined command +@samp{hookpost-foo} exists, it is executed (with no arguments) after +that command. Post-execution hooks may exist simultaneously with +pre-execution hooks, for the same command. + +It is valid for a hook to call the command which it hooks. If this +occurs, the hook is not re-executed, thereby avoiding infinite recursion. + +@c It would be nice if hookpost could be passed a parameter indicating +@c if the command it hooks executed properly or not. FIXME! + +@kindex stop@r{, a pseudo-command} +In addition, a pseudo-command, @samp{stop} exists. Defining +(@samp{hook-stop}) makes the associated commands execute every time +execution stops in your program: before breakpoint commands are run, +displays are printed, or the stack frame is printed. + +For example, to ignore @code{SIGALRM} signals while +single-stepping, but treat them normally during normal execution, +you could define: + +@smallexample +define hook-stop +handle SIGALRM nopass +end + +define hook-run +handle SIGALRM pass +end + +define hook-continue +handle SIGALRM pass +end +@end smallexample + +As a further example, to hook at the beginning and end of the @code{echo} +command, and to add extra text to the beginning and end of the message, +you could define: + +@smallexample +define hook-echo +echo <<<--- +end + +define hookpost-echo +echo --->>>\n +end + +(@value{GDBP}) echo Hello World +<<<---Hello World--->>> +(@value{GDBP}) + +@end smallexample + +You can define a hook for any single-word command in @value{GDBN}, but +not for command aliases; you should define a hook for the basic command +name, e.g.@: @code{backtrace} rather than @code{bt}. +@c FIXME! So how does Joe User discover whether a command is an alias +@c or not? +You can hook a multi-word command by adding @code{hook-} or +@code{hookpost-} to the last word of the command, e.g.@: +@samp{define target hook-remote} to add a hook to @samp{target remote}. + +If an error occurs during the execution of your hook, execution of +@value{GDBN} commands stops and @value{GDBN} issues a prompt +(before the command that you actually typed had a chance to run). + +If you try to define a hook which does not match any known command, you +get a warning from the @code{define} command. + +@node Command Files +@subsection Command Files + +@cindex command files +@cindex scripting commands +A command file for @value{GDBN} is a text file made of lines that are +@value{GDBN} commands. Comments (lines starting with @kbd{#}) may +also be included. An empty line in a command file does nothing; it +does not mean to repeat the last command, as it would from the +terminal. + +You can request the execution of a command file with the @code{source} +command. Note that the @code{source} command is also used to evaluate +scripts that are not Command Files. The exact behavior can be configured +using the @code{script-extension} setting. +@xref{Extending GDB,, Extending GDB}. + +@table @code +@kindex source +@cindex execute commands from a file +@item source [-s] [-v] @var{filename} +Execute the command file @var{filename}. +@end table + +The lines in a command file are generally executed sequentially, +unless the order of execution is changed by one of the +@emph{flow-control commands} described below. The commands are not +printed as they are executed. An error in any command terminates +execution of the command file and control is returned to the console. + +@value{GDBN} first searches for @var{filename} in the current directory. +If the file is not found there, and @var{filename} does not specify a +directory, then @value{GDBN} also looks for the file on the source search path +(specified with the @samp{directory} command); +except that @file{$cdir} is not searched because the compilation directory +is not relevant to scripts. + +If @code{-s} is specified, then @value{GDBN} searches for @var{filename} +on the search path even if @var{filename} specifies a directory. +The search is done by appending @var{filename} to each element of the +search path. So, for example, if @var{filename} is @file{mylib/myscript} +and the search path contains @file{/home/user} then @value{GDBN} will +look for the script @file{/home/user/mylib/myscript}. +The search is also done if @var{filename} is an absolute path. +For example, if @var{filename} is @file{/tmp/myscript} and +the search path contains @file{/home/user} then @value{GDBN} will +look for the script @file{/home/user/tmp/myscript}. +For DOS-like systems, if @var{filename} contains a drive specification, +it is stripped before concatenation. For example, if @var{filename} is +@file{d:myscript} and the search path contains @file{c:/tmp} then @value{GDBN} +will look for the script @file{c:/tmp/myscript}. + +If @code{-v}, for verbose mode, is given then @value{GDBN} displays +each command as it is executed. The option must be given before +@var{filename}, and is interpreted as part of the filename anywhere else. + +Commands that would ask for confirmation if used interactively proceed +without asking when used in a command file. Many @value{GDBN} commands that +normally print messages to say what they are doing omit the messages +when called from command files. + +@value{GDBN} also accepts command input from standard input. In this +mode, normal output goes to standard output and error output goes to +standard error. Errors in a command file supplied on standard input do +not terminate execution of the command file---execution continues with +the next command. + +@smallexample +gdb < cmds > log 2>&1 +@end smallexample + +(The syntax above will vary depending on the shell used.) This example +will execute commands from the file @file{cmds}. All output and errors +would be directed to @file{log}. + +Since commands stored on command files tend to be more general than +commands typed interactively, they frequently need to deal with +complicated situations, such as different or unexpected values of +variables and symbols, changes in how the program being debugged is +built, etc. @value{GDBN} provides a set of flow-control commands to +deal with these complexities. Using these commands, you can write +complex scripts that loop over data structures, execute commands +conditionally, etc. + +@table @code +@kindex if +@kindex else +@item if +@itemx else +This command allows to include in your script conditionally executed +commands. The @code{if} command takes a single argument, which is an +expression to evaluate. It is followed by a series of commands that +are executed only if the expression is true (its value is nonzero). +There can then optionally be an @code{else} line, followed by a series +of commands that are only executed if the expression was false. The +end of the list is marked by a line containing @code{end}. + +@kindex while +@item while +This command allows to write loops. Its syntax is similar to +@code{if}: the command takes a single argument, which is an expression +to evaluate, and must be followed by the commands to execute, one per +line, terminated by an @code{end}. These commands are called the +@dfn{body} of the loop. The commands in the body of @code{while} are +executed repeatedly as long as the expression evaluates to true. + +@kindex loop_break +@item loop_break +This command exits the @code{while} loop in whose body it is included. +Execution of the script continues after that @code{while}s @code{end} +line. + +@kindex loop_continue +@item loop_continue +This command skips the execution of the rest of the body of commands +in the @code{while} loop in whose body it is included. Execution +branches to the beginning of the @code{while} loop, where it evaluates +the controlling expression. + +@kindex end@r{ (if/else/while commands)} +@item end +Terminate the block of commands that are the body of @code{if}, +@code{else}, or @code{while} flow-control commands. +@end table + + +@node Output +@subsection Commands for Controlled Output + +During the execution of a command file or a user-defined command, normal +@value{GDBN} output is suppressed; the only output that appears is what is +explicitly printed by the commands in the definition. This section +describes three commands useful for generating exactly the output you +want. + +@table @code +@kindex echo +@item echo @var{text} +@c I do not consider backslash-space a standard C escape sequence +@c because it is not in ANSI. +Print @var{text}. Nonprinting characters can be included in +@var{text} using C escape sequences, such as @samp{\n} to print a +newline. @strong{No newline is printed unless you specify one.} +In addition to the standard C escape sequences, a backslash followed +by a space stands for a space. This is useful for displaying a +string with spaces at the beginning or the end, since leading and +trailing spaces are otherwise trimmed from all arguments. +To print @samp{@w{ }and foo =@w{ }}, use the command +@samp{echo \@w{ }and foo = \@w{ }}. + +A backslash at the end of @var{text} can be used, as in C, to continue +the command onto subsequent lines. For example, + +@smallexample +echo This is some text\n\ +which is continued\n\ +onto several lines.\n +@end smallexample + +produces the same output as + +@smallexample +echo This is some text\n +echo which is continued\n +echo onto several lines.\n +@end smallexample + +@kindex output +@item output @var{expression} +Print the value of @var{expression} and nothing but that value: no +newlines, no @samp{$@var{nn} = }. The value is not entered in the +value history either. @xref{Expressions, ,Expressions}, for more information +on expressions. + +@item output/@var{fmt} @var{expression} +Print the value of @var{expression} in format @var{fmt}. You can use +the same formats as for @code{print}. @xref{Output Formats,,Output +Formats}, for more information. + +@kindex printf +@item printf @var{template}, @var{expressions}@dots{} +Print the values of one or more @var{expressions} under the control of +the string @var{template}. To print several values, make +@var{expressions} be a comma-separated list of individual expressions, +which may be either numbers or pointers. Their values are printed as +specified by @var{template}, exactly as a C program would do by +executing the code below: + +@smallexample +printf (@var{template}, @var{expressions}@dots{}); +@end smallexample + +As in @code{C} @code{printf}, ordinary characters in @var{template} +are printed verbatim, while @dfn{conversion specification} introduced +by the @samp{%} character cause subsequent @var{expressions} to be +evaluated, their values converted and formatted according to type and +style information encoded in the conversion specifications, and then +printed. + +For example, you can print two values in hex like this: + +@smallexample +printf "foo, bar-foo = 0x%x, 0x%x\n", foo, bar-foo +@end smallexample + +@code{printf} supports all the standard @code{C} conversion +specifications, including the flags and modifiers between the @samp{%} +character and the conversion letter, with the following exceptions: + +@itemize @bullet +@item +The argument-ordering modifiers, such as @samp{2$}, are not supported. + +@item +The modifier @samp{*} is not supported for specifying precision or +width. + +@item +The @samp{'} flag (for separation of digits into groups according to +@code{LC_NUMERIC'}) is not supported. + +@item +The type modifiers @samp{hh}, @samp{j}, @samp{t}, and @samp{z} are not +supported. + +@item +The conversion letter @samp{n} (as in @samp{%n}) is not supported. + +@item +The conversion letters @samp{a} and @samp{A} are not supported. +@end itemize + +@noindent +Note that the @samp{ll} type modifier is supported only if the +underlying @code{C} implementation used to build @value{GDBN} supports +the @code{long long int} type, and the @samp{L} type modifier is +supported only if @code{long double} type is available. + +As in @code{C}, @code{printf} supports simple backslash-escape +sequences, such as @code{\n}, @samp{\t}, @samp{\\}, @samp{\"}, +@samp{\a}, and @samp{\f}, that consist of backslash followed by a +single character. Octal and hexadecimal escape sequences are not +supported. + +Additionally, @code{printf} supports conversion specifications for DFP +(@dfn{Decimal Floating Point}) types using the following length modifiers +together with a floating point specifier. +letters: + +@itemize @bullet +@item +@samp{H} for printing @code{Decimal32} types. + +@item +@samp{D} for printing @code{Decimal64} types. + +@item +@samp{DD} for printing @code{Decimal128} types. +@end itemize + +If the underlying @code{C} implementation used to build @value{GDBN} has +support for the three length modifiers for DFP types, other modifiers +such as width and precision will also be available for @value{GDBN} to use. + +In case there is no such @code{C} support, no additional modifiers will be +available and the value will be printed in the standard way. + +Here's an example of printing DFP types using the above conversion letters: +@smallexample +printf "D32: %Hf - D64: %Df - D128: %DDf\n",1.2345df,1.2E10dd,1.2E1dl +@end smallexample + +@anchor{%V Format Specifier} +Additionally, @code{printf} supports a special @samp{%V} output format. +This format prints the string representation of an expression just as +@value{GDBN} would produce with the standard @kbd{print} command +(@pxref{Data, ,Examining Data}): + +@smallexample +(@value{GDBP}) print array +$1 = @{0, 1, 2, 3, 4, 5@} +(@value{GDBP}) printf "Array is: %V\n", array +Array is: @{0, 1, 2, 3, 4, 5@} +@end smallexample + +It is possible to include print options with the @samp{%V} format by +placing them in @samp{[...]} immediately after the @samp{%V}, like +this: + +@smallexample +(@value{GDBP}) printf "Array is: %V[-array-indexes on]\n", array +Array is: @{[0] = 0, [1] = 1, [2] = 2, [3] = 3, [4] = 4, [5] = 5@} +@end smallexample + +If you need to print a literal @samp{[} directly after a @samp{%V}, then +just include an empty print options list: + +@smallexample +(@value{GDBP}) printf "Array is: %V[][Hello]\n", array +Array is: @{0, 1, 2, 3, 4, 5@}[Hello] +@end smallexample + +@anchor{eval} +@kindex eval +@item eval @var{template}, @var{expressions}@dots{} +Convert the values of one or more @var{expressions} under the control of +the string @var{template} to a command line, and call it. + +@end table + +@node Auto-loading sequences +@subsection Controlling auto-loading native @value{GDBN} scripts +@cindex native script auto-loading + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for the command file @file{@var{objfile}-gdb.gdb}. +@xref{Auto-loading extensions}. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. + +@table @code +@anchor{set auto-load gdb-scripts} +@kindex set auto-load gdb-scripts +@item set auto-load gdb-scripts [on|off] +Enable or disable the auto-loading of canned sequences of commands scripts. + +@anchor{show auto-load gdb-scripts} +@kindex show auto-load gdb-scripts +@item show auto-load gdb-scripts +Show whether auto-loading of canned sequences of commands scripts is enabled or +disabled. + +@anchor{info auto-load gdb-scripts} +@kindex info auto-load gdb-scripts +@cindex print list of auto-loaded canned sequences of commands scripts +@item info auto-load gdb-scripts [@var{regexp}] +Print the list of all canned sequences of commands scripts that @value{GDBN} +auto-loaded. +@end table + +If @var{regexp} is supplied only canned sequences of commands scripts with +matching names are printed. + +@node Aliases +@section Command Aliases +@cindex aliases for commands + +Aliases allow you to define alternate spellings for existing commands. +For example, if a new @value{GDBN} command defined in Python +(@pxref{Python}) has a long name, it is handy to have an abbreviated +version of it that involves less typing. + +@value{GDBN} itself uses aliases. For example @samp{s} is an alias +of the @samp{step} command even though it is otherwise an ambiguous +abbreviation of other commands like @samp{set} and @samp{show}. + +Aliases are also used to provide shortened or more common versions +of multi-word commands. For example, @value{GDBN} provides the +@samp{tty} alias of the @samp{set inferior-tty} command. + +You can define a new alias with the @samp{alias} command. + +@table @code + +@kindex alias +@item alias [-a] [--] @var{alias} = @var{command} [@var{default-args}] + +@end table + +@var{alias} specifies the name of the new alias. Each word of +@var{alias} must consist of letters, numbers, dashes and underscores. + +@var{command} specifies the name of an existing command +that is being aliased. + +@var{command} can also be the name of an existing alias. In this +case, @var{command} cannot be an alias that has default arguments. + +The @samp{-a} option specifies that the new alias is an abbreviation +of the command. Abbreviations are not used in command completion. + +The @samp{--} option specifies the end of options, +and is useful when @var{alias} begins with a dash. + +You can specify @var{default-args} for your alias. These +@var{default-args} will be automatically added before the alias +arguments typed explicitly on the command line. + +For example, the below defines an alias @code{btfullall} that shows all local +variables and all frame arguments: +@smallexample +(@value{GDBP}) alias btfullall = backtrace -full -frame-arguments all +@end smallexample + +For more information about @var{default-args}, see @ref{Command +aliases default args, ,Default Arguments}. + +Here is a simple example showing how to make an abbreviation of a +command so that there is less to type. Suppose you were tired of +typing @samp{disas}, the current shortest unambiguous abbreviation of +the @samp{disassemble} command and you wanted an even shorter version +named @samp{di}. The following will accomplish this. + +@smallexample +(@value{GDBP}) alias -a di = disas +@end smallexample + +Note that aliases are different from user-defined commands. With a +user-defined command, you also need to write documentation for it with +the @samp{document} command. An alias automatically picks up the +documentation of the existing command. + +Here is an example where we make @samp{elms} an abbreviation of +@samp{elements} in the @samp{set print elements} command. +This is to show that you can make an abbreviation of any part +of a command. + +@smallexample +(@value{GDBP}) alias -a set print elms = set print elements +(@value{GDBP}) alias -a show print elms = show print elements +(@value{GDBP}) set p elms 200 +(@value{GDBP}) show p elms +Limit on string chars or array elements to print is 200. +@end smallexample + +Note that if you are defining an alias of a @samp{set} command, +and you want to have an alias for the corresponding @samp{show} +command, then you need to define the latter separately. + +Unambiguously abbreviated commands are allowed in @var{command} and +@var{alias}, just as they are normally. + +@smallexample +(@value{GDBP}) alias -a set pr elms = set p ele +@end smallexample + +Finally, here is an example showing the creation of a one word +alias for a more complex command. +This creates alias @samp{spe} of the command @samp{set print elements}. + +@smallexample +(@value{GDBP}) alias spe = set print elements +(@value{GDBP}) spe 20 +@end smallexample + +@menu +* Command aliases default args:: Default arguments for aliases +@end menu + +@node Command aliases default args +@subsection Default Arguments +@cindex aliases for commands, default arguments + +You can tell @value{GDBN} to always prepend some default arguments to +the list of arguments provided explicitly by the user when using a +user-defined alias. + +If you repeatedly use the same arguments or options for a command, you +can define an alias for this command and tell @value{GDBN} to +automatically prepend these arguments or options to the list of +arguments you type explicitly when using the alias@footnote{@value{GDBN} +could easily accept default arguments for pre-defined commands and aliases, +but it was deemed this would be confusing, and so is not allowed.}. + +For example, if you often use the command @code{thread apply all} +specifying to work on the threads in ascending order and to continue in case it +encounters an error, you can tell @value{GDBN} to automatically preprend +the @code{-ascending} and @code{-c} options by using: + +@smallexample +(@value{GDBP}) alias thread apply asc-all = thread apply all -ascending -c +@end smallexample + +Once you have defined this alias with its default args, any time you type +the @code{thread apply asc-all} followed by @code{some arguments}, +@value{GDBN} will execute @code{thread apply all -ascending -c some arguments}. + +To have even less to type, you can also define a one word alias: +@smallexample +(@value{GDBP}) alias t_a_c = thread apply all -ascending -c +@end smallexample + +As usual, unambiguous abbreviations can be used for @var{alias} +and @var{default-args}. + +The different aliases of a command do not share their default args. +For example, you define a new alias @code{bt_ALL} showing all possible +information and another alias @code{bt_SMALL} showing very limited information +using: +@smallexample +(@value{GDBP}) alias bt_ALL = backtrace -entry-values both -frame-arg all \ + -past-main -past-entry -full +(@value{GDBP}) alias bt_SMALL = backtrace -entry-values no -frame-arg none \ + -past-main off -past-entry off +@end smallexample + +(For more on using the @code{alias} command, see @ref{Aliases}.) + +Default args are not limited to the arguments and options of @var{command}, +but can specify nested commands if @var{command} accepts such a nested command +as argument. +For example, the below defines @code{faalocalsoftype} that lists the +frames having locals of a certain type, together with the matching +local vars: +@smallexample +(@value{GDBP}) alias faalocalsoftype = frame apply all info locals -q -t +(@value{GDBP}) faalocalsoftype int +#1 0x55554f5e in sleeper_or_burner (v=0xdf50) at sleepers.c:86 +i = 0 +ret = 21845 +@end smallexample + +This is also very useful to define an alias for a set of nested @code{with} +commands to have a particular combination of temporary settings. For example, +the below defines the alias @code{pp10} that pretty prints an expression +argument, with a maximum of 10 elements if the expression is a string or +an array: +@smallexample +(@value{GDBP}) alias pp10 = with print pretty -- with print elements 10 -- print +@end smallexample +This defines the alias @code{pp10} as being a sequence of 3 commands. +The first part @code{with print pretty --} temporarily activates the setting +@code{set print pretty}, then launches the command that follows the separator +@code{--}. +The command following the first part is also a @code{with} command that +temporarily changes the setting @code{set print elements} to 10, then +launches the command that follows the second separator @code{--}. +The third part @code{print} is the command the @code{pp10} alias will launch, +using the temporary values of the settings and the arguments explicitly given +by the user. +For more information about the @code{with} command usage, +see @ref{Command Settings}. + +By default, asking the help for an alias shows the documentation of +the aliased command. When the alias is a set of nested commands, @code{help} +of an alias shows the documentation of the first command. This help +is not particularly useful for an alias such as @code{pp10}. +For such an alias, it is useful to give a specific documentation +using the @code{document} command (@pxref{Define, document}). + + +@c Python docs live in a separate file. +@include python.texi + +@c Guile docs live in a separate file. +@include guile.texi + +@node Auto-loading extensions +@section Auto-loading extensions +@cindex auto-loading extensions + +@value{GDBN} provides two mechanisms for automatically loading +extensions when a new object file is read (for example, due to the +@code{file} command, or because the inferior has loaded a shared +library): @file{@var{objfile}-gdb.@var{ext}} (@pxref{objfile-gdbdotext +file,,The @file{@var{objfile}-gdb.@var{ext}} file}) and the +@code{.debug_gdb_scripts} section of modern file formats like ELF +(@pxref{dotdebug_gdb_scripts section,,The @code{.debug_gdb_scripts} +section}). For a discussion of the differences between these two +approaches see @ref{Which flavor to choose?}. + +The auto-loading feature is useful for supplying application-specific +debugging commands and features. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. +See the @samp{auto-loading} section of each extension language +for more information. +For @value{GDBN} command files see @ref{Auto-loading sequences}. +For Python files see @ref{Python Auto-loading}. + +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +@menu +* objfile-gdbdotext file:: The @file{@var{objfile}-gdb.@var{ext}} file +* dotdebug_gdb_scripts section:: The @code{.debug_gdb_scripts} section +* Which flavor to choose?:: Choosing between these approaches +@end menu + +@node objfile-gdbdotext file +@subsection The @file{@var{objfile}-gdb.@var{ext}} file +@cindex @file{@var{objfile}-gdb.gdb} +@cindex @file{@var{objfile}-gdb.py} +@cindex @file{@var{objfile}-gdb.scm} + +When a new object file is read, @value{GDBN} looks for a file named +@file{@var{objfile}-gdb.@var{ext}} (we call it @var{script-name} below), +where @var{objfile} is the object file's name and +where @var{ext} is the file extension for the extension language: + +@table @code +@item @file{@var{objfile}-gdb.gdb} +GDB's own command language +@item @file{@var{objfile}-gdb.py} +Python +@item @file{@var{objfile}-gdb.scm} +Guile +@end table + +@var{script-name} is formed by ensuring that the file name of @var{objfile} +is absolute, following all symlinks, and resolving @code{.} and @code{..} +components, and appending the @file{-gdb.@var{ext}} suffix. +If this file exists and is readable, @value{GDBN} will evaluate it as a +script in the specified extension language. + +If this file does not exist, then @value{GDBN} will look for +@var{script-name} file in all of the directories as specified below. +(On MS-Windows/MS-DOS, the drive letter of the executable's leading +directories is converted to a one-letter subdirectory, i.e.@: +@file{d:/usr/bin/} is converted to @file{/d/usr/bin/}, because Windows +filesystems disallow colons in file names.) + +Note that loading of these files requires an accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +For object files using @file{.exe} suffix @value{GDBN} tries to load first the +scripts normally according to its @file{.exe} filename. But if no scripts are +found @value{GDBN} also tries script filenames matching the object file without +its @file{.exe} suffix. This @file{.exe} stripping is case insensitive and it +is attempted on any platform. This makes the script filenames compatible +between Unix and MS-Windows hosts. + +@table @code +@anchor{set auto-load scripts-directory} +@kindex set auto-load scripts-directory +@item set auto-load scripts-directory @r{[}@var{directories}@r{]} +Control @value{GDBN} auto-loaded scripts location. Multiple directory entries +may be delimited by the host platform path separator in use +(@samp{:} on Unix, @samp{;} on MS-Windows and MS-DOS). + +Each entry here needs to be covered also by the security setting +@code{set auto-load safe-path} (@pxref{set auto-load safe-path}). + +@anchor{with-auto-load-dir} +This variable defaults to @file{$debugdir:$datadir/auto-load}. The default +@code{set auto-load safe-path} value can be also overridden by @value{GDBN} +configuration option @option{--with-auto-load-dir}. + +Any reference to @file{$debugdir} will get replaced by +@var{debug-file-directory} value (@pxref{Separate Debug Files}) and any +reference to @file{$datadir} will get replaced by @var{data-directory} which is +determined at @value{GDBN} startup (@pxref{Data Files}). @file{$debugdir} and +@file{$datadir} must be placed as a directory component --- either alone or +delimited by @file{/} or @file{\} directory separators, depending on the host +platform. + +The list of directories uses path separator (@samp{:} on GNU and Unix +systems, @samp{;} on MS-Windows and MS-DOS) to separate directories, similarly +to the @env{PATH} environment variable. + +@anchor{show auto-load scripts-directory} +@kindex show auto-load scripts-directory +@item show auto-load scripts-directory +Show @value{GDBN} auto-loaded scripts location. + +@anchor{add-auto-load-scripts-directory} +@kindex add-auto-load-scripts-directory +@item add-auto-load-scripts-directory @r{[}@var{directories}@dots{}@r{]} +Add an entry (or list of entries) to the list of auto-loaded scripts locations. +Multiple entries may be delimited by the host platform path separator in use. +@end table + +@value{GDBN} does not track which files it has already auto-loaded this way. +@value{GDBN} will load the associated script every time the corresponding +@var{objfile} is opened. +So your @file{-gdb.@var{ext}} file should be careful to avoid errors if it +is evaluated more than once. + +@node dotdebug_gdb_scripts section +@subsection The @code{.debug_gdb_scripts} section +@cindex @code{.debug_gdb_scripts} section + +For systems using file formats like ELF and COFF, +when @value{GDBN} loads a new object file +it will look for a special section named @code{.debug_gdb_scripts}. +If this section exists, its contents is a list of null-terminated entries +specifying scripts to load. Each entry begins with a non-null prefix byte that +specifies the kind of entry, typically the extension language and whether the +script is in a file or inlined in @code{.debug_gdb_scripts}. + +The following entries are supported: + +@table @code +@item SECTION_SCRIPT_ID_PYTHON_FILE = 1 +@item SECTION_SCRIPT_ID_SCHEME_FILE = 3 +@item SECTION_SCRIPT_ID_PYTHON_TEXT = 4 +@item SECTION_SCRIPT_ID_SCHEME_TEXT = 6 +@end table + +@subsubsection Script File Entries + +If the entry specifies a file, @value{GDBN} will look for the file first +in the current directory and then along the source search path +(@pxref{Source Path, ,Specifying Source Directories}), +except that @file{$cdir} is not searched, since the compilation +directory is not relevant to scripts. + +File entries can be placed in section @code{.debug_gdb_scripts} with, +for example, this GCC macro for Python scripts. + +@example +/* Note: The "MS" section flags are to remove duplicates. */ +#define DEFINE_GDB_PY_SCRIPT(script_name) \ + asm("\ +.pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n\ +.byte 1 /* Python */\n\ +.asciz \"" script_name "\"\n\ +.popsection \n\ +"); +@end example + +@noindent +For Guile scripts, replace @code{.byte 1} with @code{.byte 3}. +Then one can reference the macro in a header or source file like this: + +@example +DEFINE_GDB_PY_SCRIPT ("my-app-scripts.py") +@end example + +The script name may include directories if desired. + +Note that loading of this script file also requires accordingly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). + +If the macro invocation is put in a header, any application or library +using this header will get a reference to the specified script, +and with the use of @code{"MS"} attributes on the section, the linker +will remove duplicates. + +@subsubsection Script Text Entries + +Script text entries allow to put the executable script in the entry +itself instead of loading it from a file. +The first line of the entry, everything after the prefix byte and up to +the first newline (@code{0xa}) character, is the script name, and must not +contain any kind of space character, e.g., spaces or tabs. +The rest of the entry, up to the trailing null byte, is the script to +execute in the specified language. The name needs to be unique among +all script names, as @value{GDBN} executes each script only once based +on its name. + +Here is an example from file @file{py-section-script.c} in the @value{GDBN} +testsuite. + +@example +#include "symcat.h" +#include "gdb/section-scripts.h" +asm( +".pushsection \".debug_gdb_scripts\", \"MS\",@@progbits,1\n" +".byte " XSTRING (SECTION_SCRIPT_ID_PYTHON_TEXT) "\n" +".ascii \"gdb.inlined-script\\n\"\n" +".ascii \"class test_cmd (gdb.Command):\\n\"\n" +".ascii \" def __init__ (self):\\n\"\n" +".ascii \" super (test_cmd, self).__init__ (" + "\\\"test-cmd\\\", gdb.COMMAND_OBSCURE)\\n\"\n" +".ascii \" def invoke (self, arg, from_tty):\\n\"\n" +".ascii \" print (\\\"test-cmd output, arg = %s\\\" % arg)\\n\"\n" +".ascii \"test_cmd ()\\n\"\n" +".byte 0\n" +".popsection\n" +); +@end example + +Loading of inlined scripts requires a properly configured +@code{auto-load safe-path} (@pxref{Auto-loading safe path}). +The path to specify in @code{auto-load safe-path} is the path of the file +containing the @code{.debug_gdb_scripts} section. + +@node Which flavor to choose? +@subsection Which flavor to choose? + +Given the multiple ways of auto-loading extensions, it might not always +be clear which one to choose. This section provides some guidance. + +@noindent +Benefits of the @file{-gdb.@var{ext}} way: + +@itemize @bullet +@item +Can be used with file formats that don't support multiple sections. + +@item +Ease of finding scripts for public libraries. + +Scripts specified in the @code{.debug_gdb_scripts} section are searched for +in the source search path. +For publicly installed libraries, e.g., @file{libstdc++}, there typically +isn't a source directory in which to find the script. + +@item +Doesn't require source code additions. +@end itemize + +@noindent +Benefits of the @code{.debug_gdb_scripts} way: + +@itemize @bullet +@item +Works with static linking. + +Scripts for libraries done the @file{-gdb.@var{ext}} way require an objfile to +trigger their loading. When an application is statically linked the only +objfile available is the executable, and it is cumbersome to attach all the +scripts from all the input libraries to the executable's +@file{-gdb.@var{ext}} script. + +@item +Works with classes that are entirely inlined. + +Some classes can be entirely inlined, and thus there may not be an associated +shared library to attach a @file{-gdb.@var{ext}} script to. + +@item +Scripts needn't be copied out of the source tree. + +In some circumstances, apps can be built out of large collections of internal +libraries, and the build infrastructure necessary to install the +@file{-gdb.@var{ext}} scripts in a place where @value{GDBN} can find them is +cumbersome. It may be easier to specify the scripts in the +@code{.debug_gdb_scripts} section as relative paths, and add a path to the +top of the source tree to the source search path. +@end itemize + +@node Multiple Extension Languages +@section Multiple Extension Languages + +The Guile and Python extension languages do not share any state, +and generally do not interfere with each other. +There are some things to be aware of, however. + +@subsection Python comes first + +Python was @value{GDBN}'s first extension language, and to avoid breaking +existing behavior Python comes first. This is generally solved by the +``first one wins'' principle. @value{GDBN} maintains a list of enabled +extension languages, and when it makes a call to an extension language, +(say to pretty-print a value), it tries each in turn until an extension +language indicates it has performed the request (e.g., has returned the +pretty-printed form of a value). +This extends to errors while performing such requests: If an error happens +while, for example, trying to pretty-print an object then the error is +reported and any following extension languages are not tried. + +@node Interpreters +@chapter Command Interpreters +@cindex command interpreters + +@value{GDBN} supports multiple command interpreters, and some command +infrastructure to allow users or user interface writers to switch +between interpreters or run commands in other interpreters. + +@value{GDBN} currently supports two command interpreters, the console +interpreter (sometimes called the command-line interpreter or @sc{cli}) +and the machine interface interpreter (or @sc{gdb/mi}). This manual +describes both of these interfaces in great detail. + +By default, @value{GDBN} will start with the console interpreter. +However, the user may choose to start @value{GDBN} with another +interpreter by specifying the @option{-i} or @option{--interpreter} +startup options. Defined interpreters include: + +@table @code +@item console +@cindex console interpreter +The traditional console or command-line interpreter. This is the most often +used interpreter with @value{GDBN}. With no interpreter specified at runtime, +@value{GDBN} will use this interpreter. + +@item dap +@cindex DAP +@cindex Debugger Adapter Protocol +When @value{GDBN} has been built with Python support, it also supports +the Debugger Adapter Protocol. This protocol can be used by a +debugger GUI or an IDE to communicate with @value{GDBN}. This +protocol is documented at +@url{https://microsoft.github.io/debug-adapter-protocol/}. +@xref{Debugger Adapter Protocol}, for information about @value{GDBN} +extensions to the protocol. + +@item mi +@cindex mi interpreter +The newest @sc{gdb/mi} interface (currently @code{mi3}). Used primarily +by programs wishing to use @value{GDBN} as a backend for a debugger GUI +or an IDE. For more information, see @ref{GDB/MI, ,The @sc{gdb/mi} +Interface}. + +@item mi3 +@cindex mi3 interpreter +The @sc{gdb/mi} interface introduced in @value{GDBN} 9.1. + +@item mi2 +@cindex mi2 interpreter +The @sc{gdb/mi} interface introduced in @value{GDBN} 6.0. + +@end table + +@cindex invoke another interpreter + +@kindex interpreter-exec +You may execute commands in any interpreter from the current +interpreter using the appropriate command. If you are running the +console interpreter, simply use the @code{interpreter-exec} command: + +@smallexample +interpreter-exec mi "-data-list-register-names" +@end smallexample + +@sc{gdb/mi} has a similar command, although it is only available in versions of +@value{GDBN} which support @sc{gdb/mi} version 2 (or greater). + +Note that @code{interpreter-exec} only changes the interpreter for the +duration of the specified command. It does not change the interpreter +permanently. + +@cindex start a new independent interpreter + +Although you may only choose a single interpreter at startup, it is +possible to run an independent interpreter on a specified input/output +device (usually a tty). + +For example, consider a debugger GUI or IDE that wants to provide a +@value{GDBN} console view. It may do so by embedding a terminal +emulator widget in its GUI, starting @value{GDBN} in the traditional +command-line mode with stdin/stdout/stderr redirected to that +terminal, and then creating an MI interpreter running on a specified +input/output device. The console interpreter created by @value{GDBN} +at startup handles commands the user types in the terminal widget, +while the GUI controls and synchronizes state with @value{GDBN} using +the separate MI interpreter. + +To start a new secondary @dfn{user interface} running MI, use the +@code{new-ui} command: + +@kindex new-ui +@cindex new user interface +@smallexample +new-ui @var{interpreter} @var{tty} +@end smallexample + +The @var{interpreter} parameter specifies the interpreter to run. +This accepts the same values as the @code{interpreter-exec} command. +For example, @samp{console}, @samp{mi}, @samp{mi2}, etc. The +@var{tty} parameter specifies the name of the bidirectional file the +interpreter uses for input/output, usually the name of a +pseudoterminal slave on Unix systems. For example: + +@smallexample +(@value{GDBP}) new-ui mi /dev/pts/9 +@end smallexample + +@noindent +runs an MI interpreter on @file{/dev/pts/9}. + +@node TUI +@chapter @value{GDBN} Text User Interface +@cindex TUI +@cindex Text User Interface + +The @value{GDBN} Text User Interface (TUI) is a terminal +interface which uses the @code{curses} library to show the source +file, the assembly output, the program registers and @value{GDBN} +commands in separate text windows. The TUI mode is supported only +on platforms where a suitable version of the @code{curses} library +is available. + +The TUI mode is enabled by default when you invoke @value{GDBN} as +@samp{@value{GDBP} -tui}. +You can also switch in and out of TUI mode while @value{GDBN} runs by +using various TUI commands and key bindings, such as @command{tui +enable} or @kbd{C-x C-a}. @xref{TUI Commands, ,TUI Commands}, and +@ref{TUI Keys, ,TUI Key Bindings}. + +@menu +* TUI Overview:: TUI overview +* TUI Keys:: TUI key bindings +* TUI Single Key Mode:: TUI single key mode +* TUI Mouse Support:: TUI mouse support +* TUI Commands:: TUI-specific commands +* TUI Configuration:: TUI configuration variables +@end menu + +@node TUI Overview +@section TUI Overview + +In TUI mode, @value{GDBN} can display several text windows: + +@table @emph +@item command +This window is the @value{GDBN} command window with the @value{GDBN} +prompt and the @value{GDBN} output. The @value{GDBN} input is still +managed using readline. + +@item source +The source window shows the source file of the program. The current +line and active breakpoints are displayed in this window. + +@item assembly +The assembly window shows the disassembly output of the program. + +@item register +This window shows the processor registers. Registers are highlighted +when their values change. +@end table + +The source and assembly windows show the current program position by +highlighting the current line and marking it with a @samp{>} marker. +By default, source and assembly code styling is disabled for the +highlighted text, but you can enable it with the @code{set style +tui-current-position on} command. @xref{Output Styling}. + +Breakpoints are indicated with two markers. The first marker +indicates the breakpoint type: + +@table @code +@item B +Breakpoint which was hit at least once. + +@item b +Breakpoint which was never hit. + +@item H +Hardware breakpoint which was hit at least once. + +@item h +Hardware breakpoint which was never hit. +@end table + +The second marker indicates whether the breakpoint is enabled or not: + +@table @code +@item + +Breakpoint is enabled. + +@item - +Breakpoint is disabled. +@end table + +The source, assembly and register windows are updated when the current +thread changes, when the frame changes, or when the program counter +changes. + +These windows are not all visible at the same time. The command +window is always visible. The others can be arranged in several +layouts: + +@itemize @bullet +@item +source only, + +@item +assembly only, + +@item +source and assembly, + +@item +source and registers, or + +@item +assembly and registers. +@end itemize + +These are the standard layouts, but other layouts can be defined. + +A status line above the command window shows the following information: + +@table @emph +@item target +Indicates the current @value{GDBN} target. +(@pxref{Targets, ,Specifying a Debugging Target}). + +@item process +Gives the current process or thread number. +When no process is being debugged, this field is set to @code{No process}. + +@item focus +Shows the name of the TUI window that has the focus. + +@item function +Gives the current function name for the selected frame. +The name is demangled if demangling is turned on (@pxref{Print Settings}). +When there is no symbol corresponding to the current program counter, +the string @code{??} is displayed. + +@item line +Indicates the current line number for the selected frame. +When the current line number is not known, the string @code{??} is displayed. + +@item pc +Indicates the current program counter address. +@end table + +@node TUI Keys +@section TUI Key Bindings +@cindex TUI key bindings + +The TUI installs several key bindings in the readline keymaps +@ifset SYSTEM_READLINE +(@pxref{Command Line Editing, , , rluserman, GNU Readline Library}). +@end ifset +@ifclear SYSTEM_READLINE +(@pxref{Command Line Editing}). +@end ifclear +The following key bindings are installed for both TUI mode and the +@value{GDBN} standard mode. + +@table @kbd +@kindex C-x C-a +@item C-x C-a +@kindex C-x a +@itemx C-x a +@kindex C-x A +@itemx C-x A +Enter or leave the TUI mode. When leaving the TUI mode, +the curses window management stops and @value{GDBN} operates using +its standard mode, writing on the terminal directly. When reentering +the TUI mode, control is given back to the curses windows. +The screen is then refreshed. + +This key binding uses the bindable Readline function +@code{tui-switch-mode}. + +@kindex C-x 1 +@item C-x 1 +Use a TUI layout with only one window. The layout will +either be @samp{source} or @samp{assembly}. When the TUI mode +is not active, it will switch to the TUI mode. + +Think of this key binding as the Emacs @kbd{C-x 1} binding. + +This key binding uses the bindable Readline function +@code{tui-delete-other-windows}. + +@kindex C-x 2 +@item C-x 2 +Use a TUI layout with at least two windows. When the current +layout already has two windows, the next layout with two windows is used. +When a new layout is chosen, one window will always be common to the +previous layout and the new one. + +Think of it as the Emacs @kbd{C-x 2} binding. + +This key binding uses the bindable Readline function +@code{tui-change-windows}. + +@kindex C-x o +@item C-x o +Change the active window. The TUI associates several key bindings +(like scrolling and arrow keys) with the active window. This command +gives the focus to the next TUI window. + +Think of it as the Emacs @kbd{C-x o} binding. + +This key binding uses the bindable Readline function +@code{tui-other-window}. + +@kindex C-x s +@item C-x s +Switch in and out of the TUI SingleKey mode that binds single +keys to @value{GDBN} commands (@pxref{TUI Single Key Mode}). + +This key binding uses the bindable Readline function +@code{next-keymap}. +@end table + +The following key bindings only work in the TUI mode: + +@table @asis +@kindex PgUp +@item @key{PgUp} +Scroll the active window one page up. + +@kindex PgDn +@item @key{PgDn} +Scroll the active window one page down. + +@kindex Up +@item @key{Up} +Scroll the active window one line up. + +@kindex Down +@item @key{Down} +Scroll the active window one line down. + +@kindex Left +@item @key{Left} +Scroll the active window one column left. + +@kindex Right +@item @key{Right} +Scroll the active window one column right. + +@kindex C-L +@item @kbd{C-L} +Refresh the screen. +@end table + +Because the arrow keys scroll the active window in the TUI mode, they +are not available for their normal use by readline unless the command +window has the focus. When another window is active, you must use +other readline key bindings such as @kbd{C-p}, @kbd{C-n}, @kbd{C-b} +and @kbd{C-f} to control the command window. + +@node TUI Single Key Mode +@section TUI Single Key Mode +@cindex TUI single key mode + +The TUI also provides a @dfn{SingleKey} mode, which binds several +frequently used @value{GDBN} commands to single keys. Type @kbd{C-x s} to +switch into this mode, where the following key bindings are used: + +@table @kbd +@kindex c @r{(SingleKey TUI key)} +@item c +continue + +@kindex C @r{(SingleKey TUI key)} +@item C +reverse-continue + +@kindex d @r{(SingleKey TUI key)} +@item d +down + +@kindex f @r{(SingleKey TUI key)} +@item f +finish + +@kindex F @r{(SingleKey TUI key)} +@item F +reverse-finish + +@kindex n @r{(SingleKey TUI key)} +@item n +next + +@kindex N @r{(SingleKey TUI key)} +@item N +reverse-next + +@kindex o @r{(SingleKey TUI key)} +@item o +nexti. The shortcut letter @samp{o} stands for ``step Over''. + +@kindex O @r{(SingleKey TUI key)} +@item O +reverse-nexti + +@kindex q @r{(SingleKey TUI key)} +@item q +exit the SingleKey mode. + +@kindex r @r{(SingleKey TUI key)} +@item r +run + +@kindex s @r{(SingleKey TUI key)} +@item s +step + +@kindex S @r{(SingleKey TUI key)} +@item S +reverse-step + +@kindex i @r{(SingleKey TUI key)} +@item i +stepi. The shortcut letter @samp{i} stands for ``step Into''. + +@kindex I @r{(SingleKey TUI key)} +@item I +reverse-stepi + +@kindex u @r{(SingleKey TUI key)} +@item u +up + +@kindex v @r{(SingleKey TUI key)} +@item v +info locals + +@kindex w @r{(SingleKey TUI key)} +@item w +where +@end table + +Other keys temporarily switch to the @value{GDBN} command prompt. +The key that was pressed is inserted in the editing buffer so that +it is possible to type most @value{GDBN} commands without interaction +with the TUI SingleKey mode. Once the command is entered the TUI +SingleKey mode is restored. The only way to permanently leave +this mode is by typing @kbd{q} or @kbd{C-x s}. + +@cindex SingleKey keymap name +If @value{GDBN} was built with Readline 8.0 or later, the TUI +SingleKey keymap will be named @samp{SingleKey}. This can be used in +@file{.inputrc} to add additional bindings to this keymap. + +@node TUI Mouse Support +@section TUI Mouse Support +@cindex TUI mouse support + +If the curses library supports the mouse, the TUI supports mouse +actions. + +The mouse wheel scrolls the appropriate window under the mouse cursor. + +The TUI itself does not directly support copying/pasting with the +mouse. However, on Unix terminals, you can typically press and hold +the @key{SHIFT} key on your keyboard to temporarily bypass +@value{GDBN}'s TUI and access the terminal's native mouse copy/paste +functionality (commonly, click-drag-release or double-click to select +text, middle-click to paste). This copy/paste works with the +terminal's selection buffer, as opposed to the TUI's buffer. Alternatively, to +disable mouse support in the TUI entirely and give the terminal control over +mouse clicks, turn off the @code{tui mouse-events} setting +(@pxref{tui-mouse-events,,set tui mouse-events}). + +Python extensions can react to mouse clicks +(@pxref{python-window-click,,Window.click}). + +@node TUI Commands +@section TUI-specific Commands +@cindex TUI commands + +The TUI has specific commands to control the text windows. +These commands are always available, even when @value{GDBN} is not in +the TUI mode. When @value{GDBN} is in the standard mode, most +of these commands will automatically switch to the TUI mode. + +Note that if @value{GDBN}'s @code{stdout} is not connected to a +terminal, or @value{GDBN} has been started with the machine interface +interpreter (@pxref{GDB/MI, ,The @sc{gdb/mi} Interface}), most of +these commands will fail with an error, because it would not be +possible or desirable to enable curses window management. + +@table @code +@item tui enable +@kindex tui enable +Activate TUI mode. The last active TUI window layout will be used if +TUI mode has previously been used in the current debugging session, +otherwise a default layout is used. + +@item tui disable +@kindex tui disable +Disable TUI mode, returning to the console interpreter. + +@anchor{info_win_command} +@item info win +@kindex info win +List the names and sizes of all currently displayed windows. + +@item tui new-layout @var{name} @var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]} +@kindex tui new-layout +Create a new TUI layout. The new layout will be named @var{name}, and +can be accessed using the @code{layout} command (see below). + +Each @var{window} parameter is either the name of a window to display, +or a window description. The windows will be displayed from top to +bottom in the order listed. + +The names of the windows are the same as the ones given to the +@code{focus} command (see below); additionally, the @code{status} +window can be specified. Note that, because it is of fixed height, +the weight assigned to the status window is of no importance. It is +conventional to use @samp{0} here. + +A window description looks a bit like an invocation of @code{tui +new-layout}, and is of the form +@{@r{[}@code{-horizontal}@r{]}@var{window} @var{weight} @r{[}@var{window} @var{weight}@dots{}@r{]}@}. + +This specifies a sub-layout. If @code{-horizontal} is given, the +windows in this description will be arranged side-by-side, rather than +top-to-bottom. + +Each @var{weight} is an integer. It is the weight of this window +relative to all the other windows in the layout. These numbers are +used to calculate how much of the screen is given to each window. + +For example: + +@example +(gdb) tui new-layout example src 1 regs 1 status 0 cmd 1 +@end example + +Here, the new layout is called @samp{example}. It shows the source +and register windows, followed by the status window, and then finally +the command window. The non-status windows all have the same weight, +so the terminal will be split into three roughly equal sections. + +Here is a more complex example, showing a horizontal layout: + +@example +(gdb) tui new-layout example @{-horizontal src 1 asm 1@} 2 status 0 cmd 1 +@end example + +This will result in side-by-side source and assembly windows; with the +status and command window being beneath these, filling the entire +width of the terminal. Because they have weight 2, the source and +assembly windows will be twice the height of the command window. + +@kindex tui layout +@kindex layout +@item tui layout @var{name} +@itemx layout @var{name} +Changes which TUI windows are displayed. The @var{name} parameter +controls which layout is shown. It can be either one of the built-in +layout names, or the name of a layout defined by the user using +@code{tui new-layout}. + +The built-in layouts are as follows: + +@table @code +@item next +Display the next layout. + +@item prev +Display the previous layout. + +@item src +Display the source and command windows. + +@item asm +Display the assembly and command windows. + +@item split +Display the source, assembly, and command windows. + +@item regs +When in @code{src} layout display the register, source, and command +windows. When in @code{asm} or @code{split} layout display the +register, assembler, and command windows. +@end table + +@kindex focus +@item tui focus @var{name} +@itemx focus @var{name} +Changes which TUI window is currently active for scrolling. The +@var{name} parameter can be any of the following: + +@table @code +@item next +Make the next window active for scrolling. + +@item prev +Make the previous window active for scrolling. + +@item src +Make the source window active for scrolling. + +@item asm +Make the assembly window active for scrolling. + +@item regs +Make the register window active for scrolling. + +@item cmd +Make the command window active for scrolling. +@end table + +@kindex tui refresh +@kindex refresh +@item tui refresh +@itemx refresh +Refresh the screen. This is similar to typing @kbd{C-L}. + +@item tui reg @var{group} +@kindex tui reg +Changes the register group displayed in the tui register window to +@var{group}. If the register window is not currently displayed this +command will cause the register window to be displayed. The list of +register groups, as well as their order is target specific. The +following groups are available on most targets: +@table @code +@item next +Repeatedly selecting this group will cause the display to cycle +through all of the available register groups. + +@item prev +Repeatedly selecting this group will cause the display to cycle +through all of the available register groups in the reverse order to +@var{next}. + +@item general +Display the general registers. +@item float +Display the floating point registers. +@item system +Display the system registers. +@item vector +Display the vector registers. +@item all +Display all registers. +@end table + +@item update +@kindex update +Update the source window and the current execution point. + +@kindex tui window height +@kindex winheight +@item tui window height @var{name} +@var{count} +@itemx tui window height @var{name} -@var{count} +@itemx winheight @var{name} +@var{count} +@itemx winheight @var{name} -@var{count} +Change the height of the window @var{name} by @var{count} lines. +Positive counts increase the height, while negative counts decrease +it. The @var{name} parameter can be the name of any currently visible +window. The names of the currently visible windows can be discovered +using @kbd{info win} (@pxref{info_win_command,,info win}). + +The set of currently visible windows must always fill the terminal, +and so, it is only possible to resize on window if there are other +visible windows that can either give or receive the extra terminal +space. + +@kindex tui window width +@kindex winwidth +@item tui window width @var{name} +@var{count} +@itemx tui window width @var{name} -@var{count} +@itemx winwidth @var{name} +@var{count} +@itemx winwidth @var{name} -@var{count} +Change the width of the window @var{name} by @var{count} columns. +Positive counts increase the width, while negative counts decrease it. +The @var{name} parameter can be the name of any currently visible +window. The names of the currently visible windows can be discovered +using @code{info win} (@pxref{info_win_command,,info win}). + +The set of currently visible windows must always fill the terminal, +and so, it is only possible to resize on window if there are other +visible windows that can either give or receive the extra terminal +space. +@end table + +@node TUI Configuration +@section TUI Configuration Variables +@cindex TUI configuration variables + +Several configuration variables control the appearance of TUI windows. + +@table @code +@item set tui border-kind @var{kind} +@kindex set tui border-kind +Select the border appearance for the source, assembly and register windows. +The possible values are the following: +@table @code +@item space +Use a space character to draw the border. + +@item ascii +Use @sc{ascii} characters @samp{+}, @samp{-} and @samp{|} to draw the border. + +@item acs +Use the Alternate Character Set to draw the border. The border is +drawn using character line graphics if the terminal supports them. +@end table + +@item set tui border-mode @var{mode} +@kindex set tui border-mode +@itemx set tui active-border-mode @var{mode} +@kindex set tui active-border-mode +Select the display attributes for the borders of the inactive windows +or the active window. The @var{mode} can be one of the following: +@table @code +@item normal +Use normal attributes to display the border. + +@item standout +Use standout mode. + +@item reverse +Use reverse video mode. + +@item half +Use half bright mode. + +@item half-standout +Use half bright and standout mode. + +@item bold +Use extra bright or bold mode. + +@item bold-standout +Use extra bright or bold and standout mode. +@end table + +@item set tui tab-width @var{nchars} +@kindex set tui tab-width +@kindex tabset +Set the width of tab stops to be @var{nchars} characters. This +setting affects the display of TAB characters in the source and +assembly windows. + +@item set tui compact-source @r{[}on@r{|}off@r{]} +@kindex set tui compact-source +Set whether the TUI source window is displayed in ``compact'' form. +The default display uses more space for line numbers; the compact +display uses only as much space as is needed for the line numbers in +the current file. + +@anchor{tui-mouse-events} +@item set tui mouse-events @r{[}on@r{|}off@r{]} +@kindex set tui mouse-events +When on (default), mouse clicks control the TUI (@pxref{TUI Mouse Support}). +When off, mouse clicks are handled by the terminal, enabling terminal-native +text selection. + +@kindex set debug tui +@item set debug tui @r{[}on|off@r{]} +Turn on or off display of @value{GDBN} internal debug messages relating +to the TUI. + +@kindex show debug tui +@item show debug tui +Show the current status of displaying @value{GDBN} internal debug +messages relating to the TUI. + +@end table + +Note that the colors of the TUI borders can be controlled using the +appropriate @code{set style} commands. @xref{Output Styling}. + +@node Emacs +@chapter Using @value{GDBN} under @sc{gnu} Emacs + +@cindex Emacs +@cindex @sc{gnu} Emacs +A special interface allows you to use @sc{gnu} Emacs to view (and +edit) the source files for the program you are debugging with +@value{GDBN}. + +To use this interface, use the command @kbd{M-x gdb} in Emacs. Give the +executable file you want to debug as an argument. This command starts +@value{GDBN} as a subprocess of Emacs, with input and output through a newly +created Emacs buffer. +@c (Do not use the @code{-tui} option to run @value{GDBN} from Emacs.) + +Running @value{GDBN} under Emacs can be just like running @value{GDBN} normally except for two +things: + +@itemize @bullet +@item +All ``terminal'' input and output goes through an Emacs buffer, called +the GUD buffer. + +This applies both to @value{GDBN} commands and their output, and to the input +and output done by the program you are debugging. + +This is useful because it means that you can copy the text of previous +commands and input them again; you can even use parts of the output +in this way. + +All the facilities of Emacs' Shell mode are available for interacting +with your program. In particular, you can send signals the usual +way---for example, @kbd{C-c C-c} for an interrupt, @kbd{C-c C-z} for a +stop. + +@item +@value{GDBN} displays source code through Emacs. + +Each time @value{GDBN} displays a stack frame, Emacs automatically finds the +source file for that frame and puts an arrow (@samp{=>}) at the +left margin of the current line. Emacs uses a separate buffer for +source display, and splits the screen to show both your @value{GDBN} session +and the source. + +Explicit @value{GDBN} @code{list} or search commands still produce output as +usual, but you probably have no reason to use them from Emacs. +@end itemize + +We call this @dfn{text command mode}. Emacs 22.1, and later, also uses +a graphical mode, enabled by default, which provides further buffers +that can control the execution and describe the state of your program. +@xref{GDB Graphical Interface,,, Emacs, The @sc{gnu} Emacs Manual}. + +If you specify an absolute file name when prompted for the @kbd{M-x +gdb} argument, then Emacs sets your current working directory to where +your program resides. If you only specify the file name, then Emacs +sets your current working directory to the directory associated +with the previous buffer. In this case, @value{GDBN} may find your +program by searching your environment's @env{PATH} variable, but on +some operating systems it might not find the source. So, although the +@value{GDBN} input and output session proceeds normally, the auxiliary +buffer does not display the current source and line of execution. + +The initial working directory of @value{GDBN} is printed on the top +line of the GUD buffer and this serves as a default for the commands +that specify files for @value{GDBN} to operate on. @xref{Files, +,Commands to Specify Files}. + +By default, @kbd{M-x gdb} calls the program called @file{gdb}. If you +need to call @value{GDBN} by a different name (for example, if you +keep several configurations around, with different names) you can +customize the Emacs variable @code{gud-gdb-command-name} to run the +one you want. + +In the GUD buffer, you can use these special Emacs commands in +addition to the standard Shell mode commands: + +@table @kbd +@item C-h m +Describe the features of Emacs' GUD Mode. + +@item C-c C-s +Execute to another source line, like the @value{GDBN} @code{step} command; also +update the display window to show the current file and location. + +@item C-c C-n +Execute to next source line in this function, skipping all function +calls, like the @value{GDBN} @code{next} command. Then update the display window +to show the current file and location. + +@item C-c C-i +Execute one instruction, like the @value{GDBN} @code{stepi} command; update +display window accordingly. + +@item C-c C-f +Execute until exit from the selected stack frame, like the @value{GDBN} +@code{finish} command. + +@item C-c C-r +Continue execution of your program, like the @value{GDBN} @code{continue} +command. + +@item C-c < +Go up the number of frames indicated by the numeric argument +(@pxref{Arguments, , Numeric Arguments, Emacs, The @sc{gnu} Emacs Manual}), +like the @value{GDBN} @code{up} command. + +@item C-c > +Go down the number of frames indicated by the numeric argument, like the +@value{GDBN} @code{down} command. +@end table + +In any source file, the Emacs command @kbd{C-x @key{SPC}} (@code{gud-break}) +tells @value{GDBN} to set a breakpoint on the source line point is on. + +In text command mode, if you type @kbd{M-x speedbar}, Emacs displays a +separate frame which shows a backtrace when the GUD buffer is current. +Move point to any frame in the stack and type @key{RET} to make it +become the current frame and display the associated source in the +source buffer. Alternatively, click @kbd{Mouse-2} to make the +selected frame become the current one. In graphical mode, the +speedbar displays watch expressions. + +If you accidentally delete the source-display buffer, an easy way to get +it back is to type the command @code{f} in the @value{GDBN} buffer, to +request a frame display; when you run under Emacs, this recreates +the source buffer if necessary to show you the context of the current +frame. + +The source files displayed in Emacs are in ordinary Emacs buffers +which are visiting the source files in the usual way. You can edit +the files with these buffers if you wish; but keep in mind that @value{GDBN} +communicates with Emacs in terms of line numbers. If you add or +delete lines from the text, the line numbers that @value{GDBN} knows cease +to correspond properly with the code. + +A more detailed description of Emacs' interaction with @value{GDBN} is +given in the Emacs manual (@pxref{Debuggers,,, Emacs, The @sc{gnu} +Emacs Manual}). + +@node GDB/MI +@chapter The @sc{gdb/mi} Interface + +@unnumberedsec Function and Purpose + +@cindex @sc{gdb/mi}, its purpose +@sc{gdb/mi} is a line based machine oriented text interface to +@value{GDBN} and is activated by specifying using the +@option{--interpreter} command line option (@pxref{Mode Options}). It +is specifically intended to support the development of systems which +use the debugger as just one small component of a larger system. + +This chapter is a specification of the @sc{gdb/mi} interface. It is written +in the form of a reference manual. + +Note that @sc{gdb/mi} is still under construction, so some of the +features described below are incomplete and subject to change +(@pxref{GDB/MI Development and Front Ends, , @sc{gdb/mi} Development and Front Ends}). + +@unnumberedsec Notation and Terminology + +@cindex notational conventions, for @sc{gdb/mi} +This chapter uses the following notation: + +@itemize @bullet +@item +@code{|} separates two alternatives. + +@item +@code{[ @var{something} ]} indicates that @var{something} is optional: +it may or may not be given. + +@item +@code{( @var{group} )*} means that @var{group} inside the parentheses +may repeat zero or more times. + +@item +@code{( @var{group} )+} means that @var{group} inside the parentheses +may repeat one or more times. + +@item +@code{( @var{group} )} means that @var{group} inside the parentheses +occurs exactly once. + +@item +@code{"@var{string}"} means a literal @var{string}. +@end itemize + +@ignore +@heading Dependencies +@end ignore + +@menu +* GDB/MI General Design:: +* GDB/MI Command Syntax:: +* GDB/MI Compatibility with CLI:: +* GDB/MI Development and Front Ends:: +* GDB/MI Output Records:: +* GDB/MI Simple Examples:: +* GDB/MI Command Description Format:: +* GDB/MI Breakpoint Commands:: +* GDB/MI Catchpoint Commands:: +* GDB/MI Program Context:: +* GDB/MI Thread Commands:: +* GDB/MI Ada Tasking Commands:: +* GDB/MI Program Execution:: +* GDB/MI Stack Manipulation:: +* GDB/MI Variable Objects:: +* GDB/MI Data Manipulation:: +* GDB/MI Tracepoint Commands:: +* GDB/MI Symbol Query:: +* GDB/MI File Commands:: +@ignore +* GDB/MI Kod Commands:: +* GDB/MI Memory Overlay Commands:: +* GDB/MI Signal Handling Commands:: +@end ignore +* GDB/MI Target Manipulation:: +* GDB/MI File Transfer Commands:: +* GDB/MI Ada Exceptions Commands:: +* GDB/MI Support Commands:: +* GDB/MI Miscellaneous Commands:: +@end menu + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI General Design +@section @sc{gdb/mi} General Design +@cindex GDB/MI General Design + +Interaction of a @sc{gdb/mi} frontend with @value{GDBN} involves three +parts---commands sent to @value{GDBN}, responses to those commands +and notifications. Each command results in exactly one response, +indicating either successful completion of the command, or an error. +For the commands that do not resume the target, the response contains the +requested information. For the commands that resume the target, the +response only indicates whether the target was successfully resumed. +Notifications is the mechanism for reporting changes in the state of the +target, or in @value{GDBN} state, that cannot conveniently be associated with +a command and reported as part of that command response. + +The important examples of notifications are: +@itemize @bullet + +@item +Exec notifications. These are used to report changes in +target state---when a target is resumed, or stopped. It would not +be feasible to include this information in response of resuming +commands, because one resume commands can result in multiple events in +different threads. Also, quite some time may pass before any event +happens in the target, while a frontend needs to know whether the resuming +command itself was successfully executed. + +@item +Console output, and status notifications. Console output +notifications are used to report output of CLI commands, as well as +diagnostics for other commands. Status notifications are used to +report the progress of a long-running operation. Naturally, including +this information in command response would mean no output is produced +until the command is finished, which is undesirable. + +@item +General notifications. Commands may have various side effects on +the @value{GDBN} or target state beyond their official purpose. For example, +a command may change the selected thread. Although such changes can +be included in command response, using notification allows for more +orthogonal frontend design. + +@end itemize + +There's no guarantee that whenever an MI command reports an error, +@value{GDBN} or the target are in any specific state, and especially, +the state is not reverted to the state before the MI command was +processed. Therefore, whenever an MI command results in an error, +we recommend that the frontend refreshes all the information shown in +the user interface. + + +@menu +* Context management:: +* Asynchronous and non-stop modes:: +* Thread groups:: +@end menu + +@node Context management +@subsection Context management + +@subsubsection Threads and Frames + +In most cases when @value{GDBN} accesses the target, this access is +done in context of a specific thread and frame (@pxref{Frames}). +Often, even when accessing global data, the target requires that a thread +be specified. The CLI interface maintains the selected thread and frame, +and supplies them to target on each command. This is convenient, +because a command line user would not want to specify that information +explicitly on each command, and because user interacts with +@value{GDBN} via a single terminal, so no confusion is possible as +to what thread and frame are the current ones. + +In the case of MI, the concept of selected thread and frame is less +useful. First, a frontend can easily remember this information +itself. Second, a graphical frontend can have more than one window, +each one used for debugging a different thread, and the frontend might +want to access additional threads for internal purposes. This +increases the risk that by relying on implicitly selected thread, the +frontend may be operating on a wrong one. Therefore, each MI command +should explicitly specify which thread and frame to operate on. To +make it possible, each MI command accepts the @samp{--thread} and +@samp{--frame} options, the value to each is @value{GDBN} global +identifier for thread and frame to operate on. + +Usually, each top-level window in a frontend allows the user to select +a thread and a frame, and remembers the user selection for further +operations. However, in some cases @value{GDBN} may suggest that the +current thread or frame be changed. For example, when stopping on a +breakpoint it is reasonable to switch to the thread where breakpoint is +hit. For another example, if the user issues the CLI @samp{thread} or +@samp{frame} commands via the frontend, it is desirable to change the +frontend's selection to the one specified by user. @value{GDBN} +communicates the suggestion to change current thread and frame using the +@samp{=thread-selected} notification. + +Note that historically, MI shares the selected thread with CLI, so +frontends used the @code{-thread-select} to execute commands in the +right context. However, getting this to work right is cumbersome. The +simplest way is for frontend to emit @code{-thread-select} command +before every command. This doubles the number of commands that need +to be sent. The alternative approach is to suppress @code{-thread-select} +if the selected thread in @value{GDBN} is supposed to be identical to the +thread the frontend wants to operate on. However, getting this +optimization right can be tricky. In particular, if the frontend +sends several commands to @value{GDBN}, and one of the commands changes the +selected thread, then the behavior of subsequent commands will +change. So, a frontend should either wait for response from such +problematic commands, or explicitly add @code{-thread-select} for +all subsequent commands. No frontend is known to do this exactly +right, so it is suggested to just always pass the @samp{--thread} and +@samp{--frame} options. + +@subsubsection Language + +The execution of several commands depends on which language is selected. +By default, the current language (@pxref{show language}) is used. +But for commands known to be language-sensitive, it is recommended +to use the @samp{--language} option. This option takes one argument, +which is the name of the language to use while executing the command. +For instance: + +@smallexample +-data-evaluate-expression --language c "sizeof (void*)" +^done,value="4" +(gdb) +@end smallexample + +The valid language names are the same names accepted by the +@samp{set language} command (@pxref{Manually}), excluding @samp{auto}, +@samp{local} or @samp{unknown}. + +@node Asynchronous and non-stop modes +@subsection Asynchronous command execution and non-stop mode + +On some targets, @value{GDBN} is capable of processing MI commands +even while the target is running. This is called @dfn{asynchronous +command execution} (@pxref{Background Execution}). The frontend may +specify a preference for asynchronous execution using the +@code{-gdb-set mi-async 1} command, which should be emitted before +either running the executable or attaching to the target. After the +frontend has started the executable or attached to the target, it can +find if asynchronous execution is enabled using the +@code{-list-target-features} command. + +@table @code +@cindex foreground execution +@cindex background execution +@cindex asynchronous execution +@cindex execution, foreground, background and asynchronous +@kindex set mi-async +@item -gdb-set mi-async @r{[}on@r{|}off@r{]} +Set whether MI is in asynchronous mode. + +When @code{off}, which is the default, MI execution commands (e.g., +@code{-exec-continue}) are foreground commands, and @value{GDBN} waits +for the program to stop before processing further commands. + +When @code{on}, MI execution commands are background execution +commands (e.g., @code{-exec-continue} becomes the equivalent of the +@code{c&} CLI command), and so @value{GDBN} is capable of processing +MI commands even while the target is running. + +@kindex show mi-async +@item -gdb-show mi-async +Show whether MI asynchronous mode is enabled. +@end table + +Note: In @value{GDBN} version 7.7 and earlier, this option was called +@code{target-async} instead of @code{mi-async}, and it had the effect +of both putting MI in asynchronous mode and making CLI background +commands possible. CLI background commands are now always possible +``out of the box'' if the target supports them. The old spelling is +kept as a deprecated alias for backwards compatibility. + +Even if @value{GDBN} can accept a command while target is running, +many commands that access the target do not work when the target is +running. Therefore, asynchronous command execution is most useful +when combined with non-stop mode (@pxref{Non-Stop Mode}). Then, +it is possible to examine the state of one thread, while other threads +are running. + +When a given thread is running, MI commands that try to access the +target in the context of that thread may not work, or may work only on +some targets. In particular, commands that try to operate on thread's +stack will not work, on any target. Commands that read memory, or +modify breakpoints, may work or not work, depending on the target. Note +that even commands that operate on global state, such as @code{print}, +@code{set}, and breakpoint commands, still access the target in the +context of a specific thread, so frontend should try to find a +stopped thread and perform the operation on that thread (using the +@samp{--thread} option). + +Which commands will work in the context of a running thread is +highly target dependent. However, the two commands +@code{-exec-interrupt}, to stop a thread, and @code{-thread-info}, +to find the state of a thread, will always work. + +@node Thread groups +@subsection Thread groups +@value{GDBN} may be used to debug several processes at the same time. +On some platforms, @value{GDBN} may support debugging of several +hardware systems, each one having several cores with several different +processes running on each core. This section describes the MI +mechanism to support such debugging scenarios. + +The key observation is that regardless of the structure of the +target, MI can have a global list of threads, because most commands that +accept the @samp{--thread} option do not need to know what process that +thread belongs to. Therefore, it is not necessary to introduce +neither additional @samp{--process} option, nor an notion of the +current process in the MI interface. The only strictly new feature +that is required is the ability to find how the threads are grouped +into processes. + +To allow the user to discover such grouping, and to support arbitrary +hierarchy of machines/cores/processes, MI introduces the concept of a +@dfn{thread group}. Thread group is a collection of threads and other +thread groups. A thread group always has a string identifier, a type, +and may have additional attributes specific to the type. A new +command, @code{-list-thread-groups}, returns the list of top-level +thread groups, which correspond to processes that @value{GDBN} is +debugging at the moment. By passing an identifier of a thread group +to the @code{-list-thread-groups} command, it is possible to obtain +the members of specific thread group. + +To allow the user to easily discover processes, and other objects, he +wishes to debug, a concept of @dfn{available thread group} is +introduced. Available thread group is an thread group that +@value{GDBN} is not debugging, but that can be attached to, using the +@code{-target-attach} command. The list of available top-level thread +groups can be obtained using @samp{-list-thread-groups --available}. +In general, the content of a thread group may be only retrieved only +after attaching to that thread group. + +Thread groups are related to inferiors (@pxref{Inferiors Connections and +Programs}). Each inferior corresponds to a thread group of a special +type @samp{process}, and some additional operations are permitted on +such thread groups. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Syntax +@section @sc{gdb/mi} Command Syntax + +@menu +* GDB/MI Input Syntax:: +* GDB/MI Output Syntax:: +@end menu + +@node GDB/MI Input Syntax +@subsection @sc{gdb/mi} Input Syntax + +@cindex input syntax for @sc{gdb/mi} +@cindex @sc{gdb/mi}, input syntax +@table @code +@item @var{command} @expansion{} +@code{@var{cli-command} | @var{mi-command}} + +@item @var{cli-command} @expansion{} +@code{[ @var{token} ] @var{cli-command} @var{nl}}, where +@var{cli-command} is any existing @value{GDBN} CLI command. + +@item @var{mi-command} @expansion{} +@code{[ @var{token} ] "-" @var{operation} ( " " @var{option} )* +@code{[} " --" @code{]} ( " " @var{parameter} )* @var{nl}} + +@item @var{token} @expansion{} +"any sequence of digits" + +@item @var{option} @expansion{} +@code{"-" @var{parameter} [ " " @var{parameter} ]} + +@item @var{parameter} @expansion{} +@code{@var{non-blank-sequence} | @var{c-string}} + +@item @var{operation} @expansion{} +@emph{any of the operations described in this chapter} + +@item @var{non-blank-sequence} @expansion{} +@emph{anything, provided it doesn't contain special characters such as +"-", @var{nl}, """ and of course " "} + +@item @var{c-string} @expansion{} +@code{""" @var{seven-bit-iso-c-string-content} """} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} +@end table + +@noindent +Notes: + +@itemize @bullet +@item +The CLI commands are still handled by the @sc{mi} interpreter; their +output is described below. + +@item +The @code{@var{token}}, when present, is passed back when the command +finishes. + +@item +Some @sc{mi} commands accept optional arguments as part of the parameter +list. Each option is identified by a leading @samp{-} (dash) and may be +followed by an optional argument parameter. Options occur first in the +parameter list and can be delimited from normal parameters using +@samp{--} (this is useful when some parameters begin with a dash). +@end itemize + +Pragmatics: + +@itemize @bullet +@item +We want easy access to the existing CLI syntax (for debugging). + +@item +We want it to be easy to spot a @sc{mi} operation. +@end itemize + +@node GDB/MI Output Syntax +@subsection @sc{gdb/mi} Output Syntax + +@cindex output syntax of @sc{gdb/mi} +@cindex @sc{gdb/mi}, output syntax +The output from @sc{gdb/mi} consists of zero or more out-of-band records +followed, optionally, by a single result record. This result record +is for the most recent command. The sequence of output records is +terminated by @samp{(gdb)}. + +If an input command was prefixed with a @code{@var{token}} then the +corresponding output for that command will also be prefixed by that same +@var{token}. + +@table @code +@item @var{output} @expansion{} +@code{( @var{out-of-band-record} )* [ @var{result-record} ] "(gdb)" @var{nl}} + +@item @var{result-record} @expansion{} +@code{ [ @var{token} ] "^" @var{result-class} ( "," @var{result} )* @var{nl}} + +@item @var{out-of-band-record} @expansion{} +@code{@var{async-record} | @var{stream-record}} + +@item @var{async-record} @expansion{} +@code{@var{exec-async-output} | @var{status-async-output} | @var{notify-async-output}} + +@item @var{exec-async-output} @expansion{} +@code{[ @var{token} ] "*" @var{async-output nl}} + +@item @var{status-async-output} @expansion{} +@code{[ @var{token} ] "+" @var{async-output nl}} + +@item @var{notify-async-output} @expansion{} +@code{[ @var{token} ] "=" @var{async-output nl}} + +@item @var{async-output} @expansion{} +@code{@var{async-class} ( "," @var{result} )*} + +@item @var{result-class} @expansion{} +@code{"done" | "running" | "connected" | "error" | "exit"} + +@item @var{async-class} @expansion{} +@code{"stopped" | @var{others}} (where @var{others} will be added +depending on the needs---this is still in development). + +@item @var{result} @expansion{} +@code{ @var{variable} "=" @var{value}} + +@item @var{variable} @expansion{} +@code{ @var{string} } + +@item @var{value} @expansion{} +@code{ @var{const} | @var{tuple} | @var{list} } + +@item @var{const} @expansion{} +@code{@var{c-string}} + +@item @var{tuple} @expansion{} +@code{ "@{@}" | "@{" @var{result} ( "," @var{result} )* "@}" } + +@item @var{list} @expansion{} +@code{ "[]" | "[" @var{value} ( "," @var{value} )* "]" | "[" +@var{result} ( "," @var{result} )* "]" } + +@item @var{stream-record} @expansion{} +@code{@var{console-stream-output} | @var{target-stream-output} | @var{log-stream-output}} + +@item @var{console-stream-output} @expansion{} +@code{"~" @var{c-string nl}} + +@item @var{target-stream-output} @expansion{} +@code{"@@" @var{c-string nl}} + +@item @var{log-stream-output} @expansion{} +@code{"&" @var{c-string nl}} + +@item @var{nl} @expansion{} +@code{CR | CR-LF} + +@item @var{token} @expansion{} +@emph{any sequence of digits}. +@end table + +@noindent +Notes: + +@itemize @bullet +@item +All output sequences end in a single line containing a period. + +@item +The @code{@var{token}} is from the corresponding request. Note that +for all async output, while the token is allowed by the grammar and +may be output by future versions of @value{GDBN} for select async +output messages, it is generally omitted. Frontends should treat +all async output as reporting general changes in the state of the +target and there should be no need to associate async output to any +prior command. + +@item +@cindex status output in @sc{gdb/mi} +@var{status-async-output} contains on-going status information about the +progress of a slow operation. It can be discarded. All status output is +prefixed by @samp{+}. + +@item +@cindex async output in @sc{gdb/mi} +@var{exec-async-output} contains asynchronous state change on the target +(stopped, started, disappeared). All async output is prefixed by +@samp{*}. + +@item +@cindex notify output in @sc{gdb/mi} +@var{notify-async-output} contains supplementary information that the +client should handle (e.g., a new breakpoint information). All notify +output is prefixed by @samp{=}. + +@item +@cindex console output in @sc{gdb/mi} +@var{console-stream-output} is output that should be displayed as is in the +console. It is the textual response to a CLI command. All the console +output is prefixed by @samp{~}. + +@item +@cindex target output in @sc{gdb/mi} +@var{target-stream-output} is the output produced by the target program. +All the target output is prefixed by @samp{@@}. + +@item +@cindex log output in @sc{gdb/mi} +@var{log-stream-output} is output text coming from @value{GDBN}'s internals, for +instance messages that should be displayed as part of an error log. All +the log output is prefixed by @samp{&}. + +@item +@cindex list output in @sc{gdb/mi} +New @sc{gdb/mi} commands should only output @var{lists} containing +@var{values}. + + +@end itemize + +@xref{GDB/MI Stream Records, , @sc{gdb/mi} Stream Records}, for more +details about the various output records. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Compatibility with CLI +@section @sc{gdb/mi} Compatibility with CLI + +@cindex compatibility, @sc{gdb/mi} and CLI +@cindex @sc{gdb/mi}, compatibility with CLI + +For the developers convenience CLI commands can be entered directly, +but there may be some unexpected behavior. For example, commands +that query the user will behave as if the user replied yes, breakpoint +command lists are not executed and some CLI commands, such as +@code{if}, @code{when} and @code{define}, prompt for further input with +@samp{>}, which is not valid MI output. + +This feature may be removed at some stage in the future and it is +recommended that front ends use the @code{-interpreter-exec} command +(@pxref{-interpreter-exec}). + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Development and Front Ends +@section @sc{gdb/mi} Development and Front Ends +@cindex @sc{gdb/mi} development + +The application which takes the MI output and presents the state of the +program being debugged to the user is called a @dfn{front end}. + +Since @sc{gdb/mi} is used by a variety of front ends to @value{GDBN}, changes +to the MI interface may break existing usage. This section describes how the +protocol changes and how to request previous version of the protocol when it +does. + +Some changes in MI need not break a carefully designed front end, and +for these the MI version will remain unchanged. The following is a +list of changes that may occur within one level, so front ends should +parse MI output in a way that can handle them: + +@itemize @bullet +@item +New MI commands may be added. + +@item +New fields may be added to the output of any MI command. + +@item +The range of values for fields with specified values, e.g., +@code{in_scope} (@pxref{-var-update}) may be extended. + +@c The format of field's content e.g type prefix, may change so parse it +@c at your own risk. Yes, in general? + +@c The order of fields may change? Shouldn't really matter but it might +@c resolve inconsistencies. +@end itemize + +If the changes are likely to break front ends, the MI version level +will be increased by one. The new versions of the MI protocol are not compatible +with the old versions. Old versions of MI remain available, allowing front ends +to keep using them until they are modified to use the latest MI version. + +Since @code{--interpreter=mi} always points to the latest MI version, it is +recommended that front ends request a specific version of MI when launching +@value{GDBN} (e.g.@: @code{--interpreter=mi2}) to make sure they get an +interpreter with the MI version they expect. + +The following table gives a summary of the released versions of the MI +interface: the version number, the version of GDB in which it first appeared +and the breaking changes compared to the previous version. + +@multitable @columnfractions .1 .1 .8 +@headitem MI version @tab GDB version @tab Breaking changes + +@item +@center 1 +@tab +@center 5.1 +@tab +None + +@item +@center 2 +@tab +@center 6.0 +@tab + +@itemize +@item +The @code{-environment-pwd}, @code{-environment-directory} and +@code{-environment-path} commands now returns values using the MI output +syntax, rather than CLI output syntax. + +@item +@code{-var-list-children}'s @code{children} result field is now a list, rather +than a tuple. + +@item +@code{-var-update}'s @code{changelist} result field is now a list, rather than +a tuple. +@end itemize + +@item +@center 3 +@tab +@center 9.1 +@tab + +@itemize +@item +The output of information about multi-location breakpoints has changed in the +responses to the @code{-break-insert} and @code{-break-info} commands, as well +as in the @code{=breakpoint-created} and @code{=breakpoint-modified} events. +The multiple locations are now placed in a @code{locations} field, whose value +is a list. +@end itemize + +@item +@center 4 +@tab +@center 13.1 +@tab + +@itemize +@item +The syntax of the "script" field in breakpoint output has changed in the +responses to the @code{-break-insert} and @code{-break-info} commands, as +well as the @code{=breakpoint-created} and @code{=breakpoint-modified} +events. The previous output was syntactically invalid. The new output is +a list. +@end itemize + +@end multitable + +If your front end cannot yet migrate to a more recent version of the +MI protocol, you can nevertheless selectively enable specific features +available in those recent MI versions, using the following commands: + +@table @code + +@item -fix-multi-location-breakpoint-output +Use the output for multi-location breakpoints which was introduced by +MI 3, even when using MI versions below 3. This command has no +effect when using MI version 3 or later. + +@item -fix-breakpoint-script-output +Use the output for the breakpoint "script" field which was introduced by +MI 4, even when using MI versions below 4. This command has no effect when +using MI version 4 or later. + +@end table + +The best way to avoid unexpected changes in MI that might break your front +end is to make your project known to @value{GDBN} developers and +follow development on @email{gdb@@sourceware.org} and +@email{gdb-patches@@sourceware.org}. +@cindex mailing lists + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Output Records +@section @sc{gdb/mi} Output Records + +@menu +* GDB/MI Result Records:: +* GDB/MI Stream Records:: +* GDB/MI Async Records:: +* GDB/MI Breakpoint Information:: +* GDB/MI Frame Information:: +* GDB/MI Thread Information:: +* GDB/MI Ada Exception Information:: +@end menu + +@node GDB/MI Result Records +@subsection @sc{gdb/mi} Result Records + +@cindex result records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, result records +In addition to a number of out-of-band notifications, the response to a +@sc{gdb/mi} command includes one of the following result indications: + +@table @code +@findex ^done +@item "^done" [ "," @var{results} ] +The synchronous operation was successful, @code{@var{results}} are the return +values. + +@findex ^running +@item "^running" +This result record is equivalent to @samp{^done}. Historically, it +was output instead of @samp{^done} if the command has resumed the +target. This behavior is maintained for backward compatibility, but +all frontends should treat @samp{^done} and @samp{^running} +identically and rely on the @samp{*running} output record to determine +which threads are resumed. + +@findex ^connected +@item "^connected" +@value{GDBN} has connected to a remote target. + +@findex ^error +@item "^error" "," "msg=" @var{c-string} [ "," "code=" @var{c-string} ] +The operation failed. The @code{msg=@var{c-string}} variable contains +the corresponding error message. + +If present, the @code{code=@var{c-string}} variable provides an error +code on which consumers can rely on to detect the corresponding +error condition. At present, only one error code is defined: + +@table @samp +@item "undefined-command" +Indicates that the command causing the error does not exist. +@end table + +@findex ^exit +@item "^exit" +@value{GDBN} has terminated. + +@end table + +@node GDB/MI Stream Records +@subsection @sc{gdb/mi} Stream Records + +@cindex @sc{gdb/mi}, stream records +@cindex stream records in @sc{gdb/mi} +@value{GDBN} internally maintains a number of output streams: the console, the +target, and the log. The output intended for each of these streams is +funneled through the @sc{gdb/mi} interface using @dfn{stream records}. + +Each stream record begins with a unique @dfn{prefix character} which +identifies its stream (@pxref{GDB/MI Output Syntax, , @sc{gdb/mi} Output +Syntax}). In addition to the prefix, each stream record contains a +@code{@var{string-output}}. This is either raw text (with an implicit new +line) or a quoted C string (which does not contain an implicit newline). + +@table @code +@item "~" @var{string-output} +The console output stream contains text that should be displayed in the +CLI console window. It contains the textual responses to CLI commands. + +@item "@@" @var{string-output} +The target output stream contains any textual output from the running +target. This is only present when GDB's event loop is truly +asynchronous, which is currently only the case for remote targets. + +@item "&" @var{string-output} +The log stream contains debugging messages being produced by @value{GDBN}'s +internals. +@end table + +@node GDB/MI Async Records +@subsection @sc{gdb/mi} Async Records + +@cindex async records in @sc{gdb/mi} +@cindex @sc{gdb/mi}, async records +@dfn{Async} records are used to notify the @sc{gdb/mi} client of +additional changes that have occurred. Those changes can either be a +consequence of @sc{gdb/mi} commands (e.g., a breakpoint modified) or a result of +target activity (e.g., target stopped). + +The following is the list of possible async records: + +@table @code + +@item *running,thread-id="@var{thread}" +The target is now running. The @var{thread} field can be the global +thread ID of the thread that is now running, and it can be +@samp{all} if all threads are running. The frontend should assume +that no interaction with a running thread is possible after this +notification is produced. The frontend should not assume that this +notification is output only once for any command. @value{GDBN} may +emit this notification several times, either for different threads, +because it cannot resume all threads together, or even for a single +thread, if the thread must be stepped though some code before letting +it run freely. + +@item *stopped,reason="@var{reason}",thread-id="@var{id}",stopped-threads="@var{stopped}",core="@var{core}" +The target has stopped. The @var{reason} field can have one of the +following values: + +@table @code +@item breakpoint-hit +A breakpoint was reached. +@item watchpoint-trigger +A watchpoint was triggered. +@item read-watchpoint-trigger +A read watchpoint was triggered. +@item access-watchpoint-trigger +An access watchpoint was triggered. +@item function-finished +An -exec-finish or similar CLI command was accomplished. +@item location-reached +An -exec-until or similar CLI command was accomplished. +@item watchpoint-scope +A watchpoint has gone out of scope. +@item end-stepping-range +An -exec-next, -exec-next-instruction, -exec-step, -exec-step-instruction or +similar CLI command was accomplished. +@item exited-signalled +The inferior exited because of a signal. +@item exited +The inferior exited. +@item exited-normally +The inferior exited normally. +@item signal-received +A signal was received by the inferior. +@item solib-event +The inferior has stopped due to a library being loaded or unloaded. +This can happen when @code{stop-on-solib-events} (@pxref{Files}) is +set or when a @code{catch load} or @code{catch unload} catchpoint is +in use (@pxref{Set Catchpoints}). +@item fork +The inferior has forked. This is reported when @code{catch fork} +(@pxref{Set Catchpoints}) has been used. +@item vfork +The inferior has vforked. This is reported in when @code{catch vfork} +(@pxref{Set Catchpoints}) has been used. +@item syscall-entry +The inferior entered a system call. This is reported when @code{catch +syscall} (@pxref{Set Catchpoints}) has been used. +@item syscall-return +The inferior returned from a system call. This is reported when +@code{catch syscall} (@pxref{Set Catchpoints}) has been used. +@item exec +The inferior called @code{exec}. This is reported when @code{catch exec} +(@pxref{Set Catchpoints}) has been used. +@item no-history +There isn't enough history recorded to continue reverse execution. +@end table + +The @var{id} field identifies the global thread ID of the thread +that directly caused the stop -- for example by hitting a breakpoint. +Depending on whether all-stop +mode is in effect (@pxref{All-Stop Mode}), @value{GDBN} may either +stop all threads, or only the thread that directly triggered the stop. +If all threads are stopped, the @var{stopped} field will have the +value of @code{"all"}. Otherwise, the value of the @var{stopped} +field will be a list of thread identifiers. Presently, this list will +always include a single thread, but frontend should be prepared to see +several threads in the list. The @var{core} field reports the +processor core on which the stop event has happened. This field may be absent +if such information is not available. + +@item =thread-group-added,id="@var{id}" +@itemx =thread-group-removed,id="@var{id}" +A thread group was either added or removed. The @var{id} field +contains the @value{GDBN} identifier of the thread group. When a thread +group is added, it generally might not be associated with a running +process. When a thread group is removed, its id becomes invalid and +cannot be used in any way. + +@item =thread-group-started,id="@var{id}",pid="@var{pid}" +A thread group became associated with a running program, +either because the program was just started or the thread group +was attached to a program. The @var{id} field contains the +@value{GDBN} identifier of the thread group. The @var{pid} field +contains process identifier, specific to the operating system. + +@item =thread-group-exited,id="@var{id}"[,exit-code="@var{code}"] +A thread group is no longer associated with a running program, +either because the program has exited, or because it was detached +from. The @var{id} field contains the @value{GDBN} identifier of the +thread group. The @var{code} field is the exit code of the inferior; it exists +only when the inferior exited with some code. + +@item =thread-created,id="@var{id}",group-id="@var{gid}" +@itemx =thread-exited,id="@var{id}",group-id="@var{gid}" +A thread either was created, or has exited. The @var{id} field +contains the global @value{GDBN} identifier of the thread. The @var{gid} +field identifies the thread group this thread belongs to. + +@item =thread-selected,id="@var{id}"[,frame="@var{frame}"] +Informs that the selected thread or frame were changed. This notification +is not emitted as result of the @code{-thread-select} or +@code{-stack-select-frame} commands, but is emitted whenever an MI command +that is not documented to change the selected thread and frame actually +changes them. In particular, invoking, directly or indirectly +(via user-defined command), the CLI @code{thread} or @code{frame} commands, +will generate this notification. Changing the thread or frame from another +user interface (see @ref{Interpreters}) will also generate this notification. + +The @var{frame} field is only present if the newly selected thread is +stopped. See @ref{GDB/MI Frame Information} for the format of its value. + +We suggest that in response to this notification, front ends +highlight the selected thread and cause subsequent commands to apply to +that thread. + +@item =library-loaded,... +Reports that a new library file was loaded by the program. This +notification has 5 fields---@var{id}, @var{target-name}, +@var{host-name}, @var{symbols-loaded} and @var{ranges}. The @var{id} field is an +opaque identifier of the library. For remote debugging case, +@var{target-name} and @var{host-name} fields give the name of the +library file on the target, and on the host respectively. For native +debugging, both those fields have the same value. The +@var{symbols-loaded} field is emitted only for backward compatibility +and should not be relied on to convey any useful information. The +@var{thread-group} field, if present, specifies the id of the thread +group in whose context the library was loaded. If the field is +absent, it means the library was loaded in the context of all present +thread groups. The @var{ranges} field specifies the ranges of addresses belonging +to this library. + +@item =library-unloaded,... +Reports that a library was unloaded by the program. This notification +has 3 fields---@var{id}, @var{target-name} and @var{host-name} with +the same meaning as for the @code{=library-loaded} notification. +The @var{thread-group} field, if present, specifies the id of the +thread group in whose context the library was unloaded. If the field is +absent, it means the library was unloaded in the context of all present +thread groups. + +@item =traceframe-changed,num=@var{tfnum},tracepoint=@var{tpnum} +@itemx =traceframe-changed,end +Reports that the trace frame was changed and its new number is +@var{tfnum}. The number of the tracepoint associated with this trace +frame is @var{tpnum}. + +@item =tsv-created,name=@var{name},initial=@var{initial} +Reports that the new trace state variable @var{name} is created with +initial value @var{initial}. + +@item =tsv-deleted,name=@var{name} +@itemx =tsv-deleted +Reports that the trace state variable @var{name} is deleted or all +trace state variables are deleted. + +@item =tsv-modified,name=@var{name},initial=@var{initial}[,current=@var{current}] +Reports that the trace state variable @var{name} is modified with +the initial value @var{initial}. The current value @var{current} of +trace state variable is optional and is reported if the current +value of trace state variable is known. + +@item =breakpoint-created,bkpt=@{...@} +@itemx =breakpoint-modified,bkpt=@{...@} +@itemx =breakpoint-deleted,id=@var{number} +Reports that a breakpoint was created, modified, or deleted, +respectively. Only user-visible breakpoints are reported to the MI +user. + +The @var{bkpt} argument is of the same form as returned by the various +breakpoint commands; @xref{GDB/MI Breakpoint Commands}. The +@var{number} is the ordinal number of the breakpoint. + +Note that if a breakpoint is emitted in the result record of a +command, then it will not also be emitted in an async record. + +@item =record-started,thread-group="@var{id}",method="@var{method}"[,format="@var{format}"] +@itemx =record-stopped,thread-group="@var{id}" +Execution log recording was either started or stopped on an +inferior. The @var{id} is the @value{GDBN} identifier of the thread +group corresponding to the affected inferior. + +The @var{method} field indicates the method used to record execution. If the +method in use supports multiple recording formats, @var{format} will be present +and contain the currently used format. @xref{Process Record and Replay}, +for existing method and format values. + +@item =cmd-param-changed,param=@var{param},value=@var{value} +Reports that a parameter of the command @code{set @var{param}} is +changed to @var{value}. In the multi-word @code{set} command, +the @var{param} is the whole parameter list to @code{set} command. +For example, In command @code{set check type on}, @var{param} +is @code{check type} and @var{value} is @code{on}. + +@item =memory-changed,thread-group=@var{id},addr=@var{addr},len=@var{len}[,type="code"] +Reports that bytes from @var{addr} to @var{data} + @var{len} were +written in an inferior. The @var{id} is the identifier of the +thread group corresponding to the affected inferior. The optional +@code{type="code"} part is reported if the memory written to holds +executable code. +@end table + +@node GDB/MI Breakpoint Information +@subsection @sc{gdb/mi} Breakpoint Information + +When @value{GDBN} reports information about a breakpoint, a +tracepoint, a watchpoint, or a catchpoint, it uses a tuple with the +following fields: + +@table @code +@item number +The breakpoint number. + +@item type +The type of the breakpoint. For ordinary breakpoints this will be +@samp{breakpoint}, but many values are possible. + +@item catch-type +If the type of the breakpoint is @samp{catchpoint}, then this +indicates the exact type of catchpoint. + +@item disp +This is the breakpoint disposition---either @samp{del}, meaning that +the breakpoint will be deleted at the next stop, or @samp{keep}, +meaning that the breakpoint will not be deleted. + +@item enabled +This indicates whether the breakpoint is enabled, in which case the +value is @samp{y}, or disabled, in which case the value is @samp{n}. +Note that this is not the same as the field @code{enable}. + +@item addr +The address of the breakpoint. This may be a hexadecimal number, +giving the address; or the string @samp{}, for a pending +breakpoint; or the string @samp{}, for a breakpoint with +multiple locations. This field will not be present if no address can +be determined. For example, a watchpoint does not have an address. + +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + +@item func +If known, the function in which the breakpoint appears. +If not known, this field is not present. + +@item filename +The name of the source file which contains this function, if known. +If not known, this field is not present. + +@item fullname +The full file name of the source file which contains this function, if +known. If not known, this field is not present. + +@item line +The line number at which this breakpoint appears, if known. +If not known, this field is not present. + +@item at +If the source file is not known, this field may be provided. If +provided, this holds the address of the breakpoint, possibly followed +by a symbol name. + +@item pending +If this breakpoint is pending, this field is present and holds the +text used to set the breakpoint, as entered by the user. + +@item evaluated-by +Where this breakpoint's condition is evaluated, either @samp{host} or +@samp{target}. + +@item thread +If this is a thread-specific breakpoint, then this identifies the +thread in which the breakpoint can trigger. + +@item inferior +If this is an inferior-specific breakpoint, this this identifies the +inferior in which the breakpoint can trigger. + +@item task +If this breakpoint is restricted to a particular Ada task, then this +field will hold the task identifier. + +@item cond +If the breakpoint is conditional, this is the condition expression. + +@item ignore +The ignore count of the breakpoint. + +@item enable +The enable count of the breakpoint. + +@item traceframe-usage +FIXME. + +@item static-tracepoint-marker-string-id +For a static tracepoint, the name of the static tracepoint marker. + +@item mask +For a masked watchpoint, this is the mask. + +@item pass +A tracepoint's pass count. + +@item original-location +The location of the breakpoint as originally specified by the user. +This field is optional. + +@item times +The number of times the breakpoint has been hit. + +@item installed +This field is only given for tracepoints. This is either @samp{y}, +meaning that the tracepoint is installed, or @samp{n}, meaning that it +is not. + +@item what +Some extra data, the exact contents of which are type-dependent. + +@item locations +This field is present if the breakpoint has multiple locations. It is also +exceptionally present if the breakpoint is enabled and has a single, disabled +location. + +The value is a list of locations. The format of a location is described below. + +@end table + +A location in a multi-location breakpoint is represented as a tuple with the +following fields: + +@table @code + +@item number +The location number as a dotted pair, like @samp{1.2}. The first digit is the +number of the parent breakpoint. The second digit is the number of the +location within that breakpoint. + +@item enabled +There are three possible values, with the following meanings: +@table @code +@item y +The location is enabled. +@item n +The location is disabled by the user. +@item N +The location is disabled because the breakpoint condition is invalid +at this location. +@end table + +@item addr +The address of this location as an hexadecimal number. + +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + +@item func +If known, the function in which the location appears. +If not known, this field is not present. + +@item file +The name of the source file which contains this location, if known. +If not known, this field is not present. + +@item fullname +The full file name of the source file which contains this location, if +known. If not known, this field is not present. + +@item line +The line number at which this location appears, if known. +If not known, this field is not present. + +@item thread-groups +The thread groups this location is in. + +@end table + +For example, here is what the output of @code{-break-insert} +(@pxref{GDB/MI Breakpoint Commands}) might be: + +@smallexample +-> -break-insert main +<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"@} +<- (gdb) +@end smallexample + +@node GDB/MI Frame Information +@subsection @sc{gdb/mi} Frame Information + +Response from many MI commands includes an information about stack +frame. This information is a tuple that may have the following +fields: + +@table @code +@item level +The level of the stack frame. The innermost frame has the level of +zero. This field is always present. + +@item func +The name of the function corresponding to the frame. This field may +be absent if @value{GDBN} is unable to determine the function name. + +@item addr +The code address for the frame. This field is always present. + +@item addr_flags +Optional field containing any flags related to the address. These flags are +architecture-dependent; see @ref{Architectures} for their meaning for a +particular CPU. + +@item file +The name of the source files that correspond to the frame's code +address. This field may be absent. + +@item line +The source line corresponding to the frames' code address. This field +may be absent. + +@item from +The name of the binary file (either executable or shared library) the +corresponds to the frame's code address. This field may be absent. + +@end table + +@node GDB/MI Thread Information +@subsection @sc{gdb/mi} Thread Information + +Whenever @value{GDBN} has to report an information about a thread, it +uses a tuple with the following fields. The fields are always present unless +stated otherwise. + +@table @code +@item id +The global numeric id assigned to the thread by @value{GDBN}. + +@item target-id +The target-specific string identifying the thread. + +@item details +Additional information about the thread provided by the target. +It is supposed to be human-readable and not interpreted by the +frontend. This field is optional. + +@item name +The name of the thread. If the user specified a name using the +@code{thread name} command, then this name is given. Otherwise, if +@value{GDBN} can extract the thread name from the target, then that +name is given. If @value{GDBN} cannot find the thread name, then this +field is omitted. + +@item state +The execution state of the thread, either @samp{stopped} or @samp{running}, +depending on whether the thread is presently running. + +@item frame +The stack frame currently executing in the thread. This field is only present +if the thread is stopped. Its format is documented in +@ref{GDB/MI Frame Information}. + +@item core +The value of this field is an integer number of the processor core the +thread was last seen on. This field is optional. +@end table + +@node GDB/MI Ada Exception Information +@subsection @sc{gdb/mi} Ada Exception Information + +Whenever a @code{*stopped} record is emitted because the program +stopped after hitting an exception catchpoint (@pxref{Set Catchpoints}), +@value{GDBN} provides the name of the exception that was raised via +the @code{exception-name} field. Also, for exceptions that were raised +with an exception message, @value{GDBN} provides that message via +the @code{exception-message} field. + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Simple Examples +@section Simple Examples of @sc{gdb/mi} Interaction +@cindex @sc{gdb/mi}, simple examples + +This subsection presents several simple examples of interaction using +the @sc{gdb/mi} interface. In these examples, @samp{->} means that the +following line is passed to @sc{gdb/mi} as input, while @samp{<-} means +the output received from @sc{gdb/mi}. + +Note the line breaks shown in the examples are here only for +readability, they don't appear in the real output. + +@subheading Setting a Breakpoint + +Setting a breakpoint generates synchronous output which contains detailed +information of the breakpoint. + +@smallexample +-> -break-insert main +<- ^done,bkpt=@{number="1",type="breakpoint",disp="keep", + enabled="y",addr="0x08048564",func="main",file="myprog.c", + fullname="/home/nickrob/myprog.c",line="68",thread-groups=["i1"], + times="0"@} +<- (gdb) +@end smallexample + +@subheading Program Execution + +Program execution generates asynchronous records and MI gives the +reason that execution stopped. + +@smallexample +-> -exec-run +<- ^running +<- (gdb) +<- *stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", + frame=@{addr="0x08048564",func="main", + args=[@{name="argc",value="1"@},@{name="argv",value="0xbfc4d4d4"@}], + file="myprog.c",fullname="/home/nickrob/myprog.c",line="68", + arch="i386:x86_64"@} +<- (gdb) +-> -exec-continue +<- ^running +<- (gdb) +<- *stopped,reason="exited-normally" +<- (gdb) +@end smallexample + +@subheading Quitting @value{GDBN} + +Quitting @value{GDBN} just prints the result class @samp{^exit}. + +@smallexample +-> (gdb) +<- -gdb-exit +<- ^exit +@end smallexample + +Please note that @samp{^exit} is printed immediately, but it might +take some time for @value{GDBN} to actually exit. During that time, @value{GDBN} +performs necessary cleanups, including killing programs being debugged +or disconnecting from debug hardware, so the frontend should wait till +@value{GDBN} exits and should only forcibly kill @value{GDBN} if it +fails to exit in reasonable time. + +@subheading A Bad Command + +Here's what happens if you pass a non-existent command: + +@smallexample +-> -rubbish +<- ^error,msg="Undefined MI command: rubbish" +<- (gdb) +@end smallexample + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Command Description Format +@section @sc{gdb/mi} Command Description Format + +The remaining sections describe blocks of commands. Each block of +commands is laid out in a fashion similar to this section. + +@subheading Motivation + +The motivation for this collection of commands. + +@subheading Introduction + +A brief introduction to this collection of commands as a whole. + +@subheading Commands + +For each command in the block, the following is described: + +@subsubheading Synopsis + +@smallexample + -command @var{args}@dots{} +@end smallexample + +@subsubheading Result + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} CLI command(s), if any. + +@subsubheading Example + +Example(s) formatted for readability. Some of the described commands have +not been implemented yet and these are labeled N.A.@: (not available). + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Breakpoint Commands +@section @sc{gdb/mi} Breakpoint Commands + +@cindex breakpoint commands for @sc{gdb/mi} +@cindex @sc{gdb/mi}, breakpoint commands +This section documents @sc{gdb/mi} commands for manipulating +breakpoints. + +@findex -break-after +@subheading The @code{-break-after} Command + +@subsubheading Synopsis + +@smallexample + -break-after @var{number} @var{count} +@end smallexample + +The breakpoint number @var{number} is not in effect until it has been +hit @var{count} times. To see how this is reflected in the output of +the @samp{-break-list} command, see the description of the +@samp{-break-list} command below. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{ignore}. + +@subsubheading Example + +@smallexample +(gdb) +-break-insert main +^done,bkpt=@{number="1",type="breakpoint",disp="keep", +enabled="y",addr="0x000100d0",func="main",file="hello.c", +fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], +times="0"@} +(gdb) +-break-after 1 3 +~ +^done +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", +line="5",thread-groups=["i1"],times="0",ignore="3"@}]@} +(gdb) +@end smallexample + +@ignore +@findex -break-catch +@subheading The @code{-break-catch} Command +@end ignore + +@findex -break-commands +@subheading The @code{-break-commands} Command + +@subsubheading Synopsis + +@smallexample + -break-commands @var{number} [ @var{command1} ... @var{commandN} ] +@end smallexample + +Specifies the CLI commands that should be executed when breakpoint +@var{number} is hit. The parameters @var{command1} to @var{commandN} +are the commands. If no command is specified, any previously-set +commands are cleared. @xref{Break Commands}. Typical use of this +functionality is tracing a program, that is, printing of values of +some variables whenever breakpoint is hit and then continuing. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{commands}. + +@subsubheading Example + +@smallexample +(gdb) +-break-insert main +^done,bkpt=@{number="1",type="breakpoint",disp="keep", +enabled="y",addr="0x000100d0",func="main",file="hello.c", +fullname="/home/foo/hello.c",line="5",thread-groups=["i1"], +times="0"@} +(gdb) +-break-commands 1 "print v" "continue" +^done +(gdb) +@end smallexample + +@findex -break-condition +@subheading The @code{-break-condition} Command + +@subsubheading Synopsis + +@smallexample + -break-condition [ --force ] @var{number} [ @var{expr} ] +@end smallexample + +Breakpoint @var{number} will stop the program only if the condition in +@var{expr} is true. The condition becomes part of the +@samp{-break-list} output (see the description of the @samp{-break-list} +command below). If the @samp{--force} flag is passed, the condition +is forcibly defined even when it is invalid for all locations of +breakpoint @var{number}. If the @var{expr} argument is omitted, +breakpoint @var{number} becomes unconditional. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{condition}. + +@subsubheading Example + +@smallexample +(gdb) +-break-condition 1 1 +^done +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", +line="5",cond="1",thread-groups=["i1"],times="0",ignore="3"@}]@} +(gdb) +@end smallexample + +@findex -break-delete +@subheading The @code{-break-delete} Command + +@subsubheading Synopsis + +@smallexample + -break-delete ( @var{breakpoint} )+ +@end smallexample + +Delete the breakpoint(s) whose number(s) are specified in the argument +list. This is obviously reflected in the breakpoint list. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{delete}. + +@subsubheading Example + +@smallexample +(gdb) +-break-delete 1 +^done +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(gdb) +@end smallexample + +@findex -break-disable +@subheading The @code{-break-disable} Command + +@subsubheading Synopsis + +@smallexample + -break-disable ( @var{breakpoint} )+ +@end smallexample + +Disable the named @var{breakpoint}(s). The field @samp{enabled} in the +break list is now set to @samp{n} for the named @var{breakpoint}(s). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disable}. + +@subsubheading Example + +@smallexample +(gdb) +-break-disable 2 +^done +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="n", +addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", +line="5",thread-groups=["i1"],times="0"@}]@} +(gdb) +@end smallexample + +@findex -break-enable +@subheading The @code{-break-enable} Command + +@subsubheading Synopsis + +@smallexample + -break-enable ( @var{breakpoint} )+ +@end smallexample + +Enable (previously disabled) @var{breakpoint}(s). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{enable}. + +@subsubheading Example + +@smallexample +(gdb) +-break-enable 2 +^done +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",fullname="/home/foo/hello.c", +line="5",thread-groups=["i1"],times="0"@}]@} +(gdb) +@end smallexample + +@findex -break-info +@subheading The @code{-break-info} Command + +@subsubheading Synopsis + +@smallexample + -break-info @var{breakpoint} +@end smallexample + +@c REDUNDANT??? +Get information about a single breakpoint. + +The result is a table of breakpoints. @xref{GDB/MI Breakpoint +Information}, for details on the format of each breakpoint in the +table. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info break @var{breakpoint}}. + +@subsubheading Example +N.A. + +@findex -break-insert +@anchor{-break-insert} +@subheading The @code{-break-insert} Command + +@subsubheading Synopsis + +@smallexample + -break-insert [ -t ] [ -h ] [ -f ] [ -d ] [ -a ] [ --qualified ] + [ -c @var{condition} ] [ --force-condition ] [ -i @var{ignore-count} ] + [ -p @var{thread-id} ] [ -g @var{thread-group-id} ] [ @var{locspec} ] +@end smallexample + +@noindent +If specified, @var{locspec}, can be one of: + +@table @var +@item linespec location +A linespec location. @xref{Linespec Locations}. + +@item explicit location +An explicit location. @sc{gdb/mi} explicit locations are +analogous to the CLI's explicit locations using the option names +listed below. @xref{Explicit Locations}. + +@table @samp +@item --source @var{filename} +The source file name of the location. This option requires the use +of either @samp{--function} or @samp{--line}. + +@item --function @var{function} +The name of a function or method. + +@item --label @var{label} +The name of a label. + +@item --line @var{lineoffset} +An absolute or relative line offset from the start of the location. +@end table + +@item address location +An address location, *@var{address}. @xref{Address Locations}. +@end table + +@noindent +The possible optional parameters of this command are: + +@table @samp +@item -t +Insert a temporary breakpoint. +@item -h +Insert a hardware breakpoint. +@item -f +If @var{locspec} cannot be resolved (for example if it +refers to unknown files or functions), create a pending +breakpoint. Without this flag, @value{GDBN} will report +an error, and won't create a breakpoint, if @var{locspec} +cannot be parsed. +@item -d +Create a disabled breakpoint. +@item -a +Create a tracepoint. @xref{Tracepoints}. When this parameter +is used together with @samp{-h}, a fast tracepoint is created. +@item -c @var{condition} +Make the breakpoint conditional on @var{condition}. +@item --force-condition +Forcibly define the breakpoint even if the condition is invalid at +all of the breakpoint locations. +@item -i @var{ignore-count} +Initialize the @var{ignore-count}. +@item -p @var{thread-id} +Restrict the breakpoint to the thread with the specified global +@var{thread-id}. @var{thread-id} must be a valid thread-id at the +time the breakpoint is requested. Breakpoints created with a +@var{thread-id} will automatically be deleted when the corresponding +thread exits. +@item -g @var{thread-group-id} +Restrict the breakpoint to the thread group with the specified +@var{thread-group-id}. +@item --qualified +This option makes @value{GDBN} interpret a function name specified as +a complete fully-qualified name. +@end table + +@subsubheading Result + +@xref{GDB/MI Breakpoint Information}, for details on the format of the +resulting breakpoint. + +Note: this format is open to change. +@c An out-of-band breakpoint instead of part of the result? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{break}, @samp{tbreak}, +@samp{hbreak}, and @samp{thbreak}. @c and @samp{rbreak}. + +@subsubheading Example + +@smallexample +(gdb) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c", +fullname="/home/foo/recursive2.c,line="4",thread-groups=["i1"], +times="0"@} +(gdb) +-break-insert -t foo +^done,bkpt=@{number="2",addr="0x00010774",file="recursive2.c", +fullname="/home/foo/recursive2.c,line="11",thread-groups=["i1"], +times="0"@} +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x0001072c", func="main",file="recursive2.c", +fullname="/home/foo/recursive2.c,"line="4",thread-groups=["i1"], +times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="del",enabled="y", +addr="0x00010774",func="foo",file="recursive2.c", +fullname="/home/foo/recursive2.c",line="11",thread-groups=["i1"], +times="0"@}]@} +(gdb) +@end smallexample + +@findex -dprintf-insert +@subheading The @code{-dprintf-insert} Command + +@subsubheading Synopsis + +@smallexample + -dprintf-insert [ -t ] [ -f ] [ -d ] [ --qualified ] + [ -c @var{condition} ] [--force-condition] [ -i @var{ignore-count} ] + [ -p @var{thread-id} ] [ @var{locspec} ] @var{format} + [ @var{argument}@dots{} ] +@end smallexample + +@noindent +Insert a new dynamic print breakpoint at the given location. +@xref{Dynamic Printf}. @var{format} is the format to use, and any +remaining arguments are passed as expressions to substitute. + +@noindent +If supplied, @var{locspec} and @code{--qualified} may be specified +the same way as for the @code{-break-insert} command. +@xref{-break-insert}. + +The possible optional parameters of this command are: + +@table @samp +@item -t +Insert a temporary breakpoint. +@item -f +If @var{locspec} cannot be parsed (for example, if it +refers to unknown files or functions), create a pending +breakpoint. Without this flag, @value{GDBN} will report +an error, and won't create a breakpoint, if @var{locspec} +cannot be parsed. +@item -d +Create a disabled breakpoint. +@item -c @var{condition} +Make the breakpoint conditional on @var{condition}. +@item --force-condition +Forcibly define the breakpoint even if the condition is invalid at +all of the breakpoint locations. +@item -i @var{ignore-count} +Set the ignore count of the breakpoint (@pxref{Conditions, ignore count}) +to @var{ignore-count}. +@item -p @var{thread-id} +Restrict the breakpoint to the thread with the specified global +@var{thread-id}. +@end table + +@subsubheading Result + +@xref{GDB/MI Breakpoint Information}, for details on the format of the +resulting breakpoint. + +@c An out-of-band breakpoint instead of part of the result? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{dprintf}. + +@subsubheading Example + +@smallexample +(gdb) +4-dprintf-insert foo "At foo entry\n" +4^done,bkpt=@{number="1",type="dprintf",disp="keep",enabled="y", +addr="0x000000000040061b",func="foo",file="mi-dprintf.c", +fullname="mi-dprintf.c",line="25",thread-groups=["i1"], +times="0",script=["printf \"At foo entry\\n\"","continue"], +original-location="foo"@} +(gdb) +5-dprintf-insert 26 "arg=%d, g=%d\n" arg g +5^done,bkpt=@{number="2",type="dprintf",disp="keep",enabled="y", +addr="0x000000000040062a",func="foo",file="mi-dprintf.c", +fullname="mi-dprintf.c",line="26",thread-groups=["i1"], +times="0",script=["printf \"arg=%d, g=%d\\n\", arg, g","continue"], +original-location="mi-dprintf.c:26"@} +(gdb) +@end smallexample + +@findex -break-list +@subheading The @code{-break-list} Command + +@subsubheading Synopsis + +@smallexample + -break-list +@end smallexample + +Displays the list of inserted breakpoints, showing the following fields: + +@table @samp +@item Number +number of the breakpoint +@item Type +type of the breakpoint: @samp{breakpoint} or @samp{watchpoint} +@item Disposition +should the breakpoint be deleted or disabled when it is hit: @samp{keep} +or @samp{nokeep} +@item Enabled +is the breakpoint enabled or no: @samp{y} or @samp{n} +@item Address +memory location at which the breakpoint is set +@item What +logical location of the breakpoint, expressed by function name, file +name, line number +@item Thread-groups +list of thread groups to which this breakpoint applies +@item Times +number of times the breakpoint has been hit +@end table + +If there are no breakpoints, watchpoints, tracepoints, or catchpoints, +the @code{BreakpointTable} @code{body} field is an empty list. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info break}. + +@subsubheading Example + +@smallexample +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x000100d0",func="main",file="hello.c",line="5",thread-groups=["i1"], +times="0"@}, +bkpt=@{number="2",type="breakpoint",disp="keep",enabled="y", +addr="0x00010114",func="foo",file="hello.c",fullname="/home/foo/hello.c", +line="13",thread-groups=["i1"],times="0"@}]@} +(gdb) +@end smallexample + +Here's an example of the result when there are no breakpoints: + +@smallexample +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="0",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[]@} +(gdb) +@end smallexample + +@findex -break-passcount +@subheading The @code{-break-passcount} Command + +@subsubheading Synopsis + +@smallexample + -break-passcount @var{tracepoint-number} @var{passcount} +@end smallexample + +Set the passcount for tracepoint @var{tracepoint-number} to +@var{passcount}. If the breakpoint referred to by @var{tracepoint-number} +is not a tracepoint, error is emitted. This corresponds to CLI +command @samp{passcount}. + +@findex -break-watch +@subheading The @code{-break-watch} Command + +@subsubheading Synopsis + +@smallexample + -break-watch [ -a | -r ] +@end smallexample + +Create a watchpoint. With the @samp{-a} option it will create an +@dfn{access} watchpoint, i.e., a watchpoint that triggers either on a +read from or on a write to the memory location. With the @samp{-r} +option, the watchpoint created is a @dfn{read} watchpoint, i.e., it will +trigger only when the memory location is accessed for reading. Without +either of the options, the watchpoint created is a regular watchpoint, +i.e., it will trigger when the memory location is accessed for writing. +@xref{Set Watchpoints, , Setting Watchpoints}. + +Note that @samp{-break-list} will report a single list of watchpoints and +breakpoints inserted. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{watch}, @samp{awatch}, and +@samp{rwatch}. + +@subsubheading Example + +Setting a watchpoint on a variable in the @code{main} function: + +@smallexample +(gdb) +-break-watch x +^done,wpt=@{number="2",exp="x"@} +(gdb) +-exec-continue +^running +(gdb) +*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="x"@}, +value=@{old="-268439212",new="55"@}, +frame=@{func="main",args=[],file="recursive2.c", +fullname="/home/foo/bar/recursive2.c",line="5",arch="i386:x86_64"@} +(gdb) +@end smallexample + +Setting a watchpoint on a variable local to a function. @value{GDBN} will stop +the program execution twice: first for the variable changing value, then +for the watchpoint going out of scope. + +@smallexample +(gdb) +-break-watch C +^done,wpt=@{number="5",exp="C"@} +(gdb) +-exec-continue +^running +(gdb) +*stopped,reason="watchpoint-trigger", +wpt=@{number="5",exp="C"@},value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", +arch="i386:x86_64"@} +(gdb) +-exec-continue +^running +(gdb) +*stopped,reason="watchpoint-scope",wpnum="5", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", +arch="i386:x86_64"@} +(gdb) +@end smallexample + +Listing breakpoints and watchpoints, at different points in the program +execution. Note that once the watchpoint goes out of scope, it is +deleted. + +@smallexample +(gdb) +-break-watch C +^done,wpt=@{number="2",exp="C"@} +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c"line="8",thread-groups=["i1"], +times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",thread-groups=["i1"],times="0"@}]@} +(gdb) +-exec-continue +^running +(gdb) +*stopped,reason="watchpoint-trigger",wpt=@{number="2",exp="C"@}, +value=@{old="-276895068",new="3"@}, +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="13", +arch="i386:x86_64"@} +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="2",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8",thread-groups=["i1"], +times="1"@}, +bkpt=@{number="2",type="watchpoint",disp="keep", +enabled="y",addr="",what="C",thread-groups=["i1"],times="-5"@}]@} +(gdb) +-exec-continue +^running +^done,reason="watchpoint-scope",wpnum="2", +frame=@{func="callee3",args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", +arch="i386:x86_64"@} +(gdb) +-break-list +^done,BreakpointTable=@{nr_rows="1",nr_cols="6", +hdr=[@{width="3",alignment="-1",col_name="number",colhdr="Num"@}, +@{width="14",alignment="-1",col_name="type",colhdr="Type"@}, +@{width="4",alignment="-1",col_name="disp",colhdr="Disp"@}, +@{width="3",alignment="-1",col_name="enabled",colhdr="Enb"@}, +@{width="10",alignment="-1",col_name="addr",colhdr="Address"@}, +@{width="40",alignment="2",col_name="what",colhdr="What"@}], +body=[bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/devo/gdb/testsuite/gdb.mi/basics.c",line="8", +thread-groups=["i1"],times="1"@}]@} +(gdb) +@end smallexample + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Catchpoint Commands +@section @sc{gdb/mi} Catchpoint Commands + +This section documents @sc{gdb/mi} commands for manipulating +catchpoints. + +@menu +* Shared Library GDB/MI Catchpoint Commands:: +* Ada Exception GDB/MI Catchpoint Commands:: +* C++ Exception GDB/MI Catchpoint Commands:: +@end menu + +@node Shared Library GDB/MI Catchpoint Commands +@subsection Shared Library @sc{gdb/mi} Catchpoints + +@findex -catch-load +@subheading The @code{-catch-load} Command + +@subsubheading Synopsis + +@smallexample + -catch-load [ -t ] [ -d ] @var{regexp} +@end smallexample + +Add a catchpoint for library load events. If the @samp{-t} option is used, +the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting +Breakpoints}). If the @samp{-d} option is used, the catchpoint is created +in a disabled state. The @samp{regexp} argument is a regular +expression used to match the name of the loaded library. + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{catch load}. + +@subsubheading Example + +@smallexample +-catch-load -t foo.so +^done,bkpt=@{number="1",type="catchpoint",disp="del",enabled="y", +what="load of library matching foo.so",catch-type="load",times="0"@} +(gdb) +@end smallexample + + +@findex -catch-unload +@subheading The @code{-catch-unload} Command + +@subsubheading Synopsis + +@smallexample + -catch-unload [ -t ] [ -d ] @var{regexp} +@end smallexample + +Add a catchpoint for library unload events. If the @samp{-t} option is +used, the catchpoint is a temporary one (@pxref{Set Breaks, ,Setting +Breakpoints}). If the @samp{-d} option is used, the catchpoint is +created in a disabled state. The @samp{regexp} argument is a regular +expression used to match the name of the unloaded library. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{catch unload}. + +@subsubheading Example + +@smallexample +-catch-unload -d bar.so +^done,bkpt=@{number="2",type="catchpoint",disp="keep",enabled="n", +what="load of library matching bar.so",catch-type="unload",times="0"@} +(gdb) +@end smallexample + +@node Ada Exception GDB/MI Catchpoint Commands +@subsection Ada Exception @sc{gdb/mi} Catchpoints + +The following @sc{gdb/mi} commands can be used to create catchpoints +that stop the execution when Ada exceptions are being raised. + +@findex -catch-assert +@subheading The @code{-catch-assert} Command + +@subsubheading Synopsis + +@smallexample + -catch-assert [ -c @var{condition}] [ -d ] [ -t ] +@end smallexample + +Add a catchpoint for failed Ada assertions. + +The possible optional parameters for this command are: + +@table @samp +@item -c @var{condition} +Make the catchpoint conditional on @var{condition}. +@item -d +Create a disabled catchpoint. +@item -t +Create a temporary catchpoint. +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{catch assert}. + +@subsubheading Example + +@smallexample +-catch-assert +^done,bkptno="5",bkpt=@{number="5",type="breakpoint",disp="keep", +enabled="y",addr="0x0000000000404888",what="failed Ada assertions", +thread-groups=["i1"],times="0", +original-location="__gnat_debug_raise_assert_failure"@} +(gdb) +@end smallexample + +@findex -catch-exception +@subheading The @code{-catch-exception} Command + +@subsubheading Synopsis + +@smallexample + -catch-exception [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] + [ -t ] [ -u ] +@end smallexample + +Add a catchpoint stopping when Ada exceptions are raised. +By default, the command stops the program when any Ada exception +gets raised. But it is also possible, by using some of the +optional parameters described below, to create more selective +catchpoints. + +The possible optional parameters for this command are: + +@table @samp +@item -c @var{condition} +Make the catchpoint conditional on @var{condition}. +@item -d +Create a disabled catchpoint. +@item -e @var{exception-name} +Only stop when @var{exception-name} is raised. This option cannot +be used combined with @samp{-u}. +@item -t +Create a temporary catchpoint. +@item -u +Stop only when an unhandled exception gets raised. This option +cannot be used combined with @samp{-e}. +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{catch exception} +and @samp{catch exception unhandled}. + +@subsubheading Example + +@smallexample +-catch-exception -e Program_Error +^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", +enabled="y",addr="0x0000000000404874", +what="`Program_Error' Ada exception", thread-groups=["i1"], +times="0",original-location="__gnat_debug_raise_exception"@} +(gdb) +@end smallexample + +@findex -catch-handlers +@subheading The @code{-catch-handlers} Command + +@subsubheading Synopsis + +@smallexample + -catch-handlers [ -c @var{condition}] [ -d ] [ -e @var{exception-name} ] + [ -t ] +@end smallexample + +Add a catchpoint stopping when Ada exceptions are handled. +By default, the command stops the program when any Ada exception +gets handled. But it is also possible, by using some of the +optional parameters described below, to create more selective +catchpoints. + +The possible optional parameters for this command are: + +@table @samp +@item -c @var{condition} +Make the catchpoint conditional on @var{condition}. +@item -d +Create a disabled catchpoint. +@item -e @var{exception-name} +Only stop when @var{exception-name} is handled. +@item -t +Create a temporary catchpoint. +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{catch handlers}. + +@subsubheading Example + +@smallexample +-catch-handlers -e Constraint_Error +^done,bkptno="4",bkpt=@{number="4",type="breakpoint",disp="keep", +enabled="y",addr="0x0000000000402f68", +what="`Constraint_Error' Ada exception handlers",thread-groups=["i1"], +times="0",original-location="__gnat_begin_handler"@} +(gdb) +@end smallexample + +@node C++ Exception GDB/MI Catchpoint Commands +@subsection C@t{++} Exception @sc{gdb/mi} Catchpoints + +The following @sc{gdb/mi} commands can be used to create catchpoints +that stop the execution when C@t{++} exceptions are being throw, rethrown, +or caught. + +@findex -catch-throw +@subheading The @code{-catch-throw} Command + +@subsubheading Synopsis + +@smallexample + -catch-throw [ -t ] [ -r @var{regexp}] +@end smallexample + +Stop when the debuggee throws a C@t{++} exception. If @var{regexp} is +given, then only exceptions whose type matches the regular expression +will be caught. + +If @samp{-t} is given, then the catchpoint is enabled only for one +stop, the catchpoint is automatically deleted after stopping once for +the event. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{catch throw} +and @samp{tcatch throw} (@pxref{Set Catchpoints}). + +@subsubheading Example + +@smallexample +-catch-throw -r exception_type +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception throw",catch-type="throw", + thread-groups=["i1"], + regexp="exception_type",times="0"@} +(gdb) +-exec-run +^running +(gdb) +~"\n" +~"Catchpoint 1 (exception thrown), 0x00007ffff7ae00ed + in __cxa_throw () from /lib64/libstdc++.so.6\n" +*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame=@{addr="0x00007ffff7ae00ed",func="__cxa_throw", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, + thread-id="1",stopped-threads="all",core="6" +(gdb) +@end smallexample + +@findex -catch-rethrow +@subheading The @code{-catch-rethrow} Command + +@subsubheading Synopsis + +@smallexample + -catch-rethrow [ -t ] [ -r @var{regexp}] +@end smallexample + +Stop when a C@t{++} exception is re-thrown. If @var{regexp} is given, +then only exceptions whose type matches the regular expression will be +caught. + +If @samp{-t} is given, then the catchpoint is enabled only for one +stop, the catchpoint is automatically deleted after the first event is +caught. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{catch rethrow} +and @samp{tcatch rethrow} (@pxref{Set Catchpoints}). + +@subsubheading Example + +@smallexample +-catch-rethrow -r exception_type +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception rethrow",catch-type="rethrow", + thread-groups=["i1"], + regexp="exception_type",times="0"@} +(gdb) +-exec-run +^running +(gdb) +~"\n" +~"Catchpoint 1 (exception rethrown), 0x00007ffff7ae00ed + in __cxa_rethrow () from /lib64/libstdc++.so.6\n" +*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame=@{addr="0x00007ffff7ae00ed",func="__cxa_rethrow", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, + thread-id="1",stopped-threads="all",core="6" +(gdb) +@end smallexample + +@findex -catch-catch +@subheading The @code{-catch-catch} Command + +@subsubheading Synopsis + +@smallexample + -catch-catch [ -t ] [ -r @var{regexp}] +@end smallexample + +Stop when the debuggee catches a C@t{++} exception. If @var{regexp} +is given, then only exceptions whose type matches the regular +expression will be caught. + +If @samp{-t} is given, then the catchpoint is enabled only for one +stop, the catchpoint is automatically deleted after the first event is +caught. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{catch catch} +and @samp{tcatch catch} (@pxref{Set Catchpoints}). + +@subsubheading Example + +@smallexample +-catch-catch -r exception_type +^done,bkpt=@{number="1",type="catchpoint",disp="keep",enabled="y", + what="exception catch",catch-type="catch", + thread-groups=["i1"], + regexp="exception_type",times="0"@} +(gdb) +-exec-run +^running +(gdb) +~"\n" +~"Catchpoint 1 (exception caught), 0x00007ffff7ae00ed + in __cxa_begin_catch () from /lib64/libstdc++.so.6\n" +*stopped,bkptno="1",reason="breakpoint-hit",disp="keep", + frame=@{addr="0x00007ffff7ae00ed",func="__cxa_begin_catch", + args=[],from="/lib64/libstdc++.so.6",arch="i386:x86-64"@}, + thread-id="1",stopped-threads="all",core="6" +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Program Context +@section @sc{gdb/mi} Program Context + +@findex -exec-arguments +@subheading The @code{-exec-arguments} Command + + +@subsubheading Synopsis + +@smallexample + -exec-arguments @var{args} +@end smallexample + +Set the inferior program arguments, to be used in the next +@samp{-exec-run}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set args}. + +@subsubheading Example + +@smallexample +(gdb) +-exec-arguments -v word +^done +(gdb) +@end smallexample + + +@ignore +@findex -exec-show-arguments +@subheading The @code{-exec-show-arguments} Command + +@subsubheading Synopsis + +@smallexample + -exec-show-arguments +@end smallexample + +Print the arguments of the program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{show args}. + +@subsubheading Example +N.A. +@end ignore + + +@findex -environment-cd +@subheading The @code{-environment-cd} Command + +@subsubheading Synopsis + +@smallexample + -environment-cd @var{pathdir} +@end smallexample + +Set @value{GDBN}'s working directory. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{cd}. + +@subsubheading Example + +@smallexample +(gdb) +-environment-cd /kwikemart/marge/ezannoni/flathead-dev/devo/gdb +^done +(gdb) +@end smallexample + + +@findex -environment-directory +@subheading The @code{-environment-directory} Command + +@subsubheading Synopsis + +@smallexample + -environment-directory [ -r ] [ @var{pathdir} ]+ +@end smallexample + +Add directories @var{pathdir} to beginning of search path for source files. +If the @samp{-r} option is used, the search path is reset to the default +search path. If directories @var{pathdir} are supplied in addition to the +@samp{-r} option, the search path is first reset and then addition +occurs as normal. +Multiple directories may be specified, separated by blanks. Specifying +multiple directories in a single command +results in the directories added to the beginning of the +search path in the same order they were presented in the command. +If blanks are needed as +part of a directory name, double-quotes should be used around +the name. In the command output, the path will show up separated +by the system directory-separator character. The directory-separator +character must not be used +in any directory name. +If no directories are specified, the current search path is displayed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{dir}. + +@subsubheading Example + +@smallexample +(gdb) +-environment-directory /kwikemart/marge/ezannoni/flathead-dev/devo/gdb +^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" +(gdb) +-environment-directory "" +^done,source-path="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb:$cdir:$cwd" +(gdb) +-environment-directory -r /home/jjohnstn/src/gdb /usr/src +^done,source-path="/home/jjohnstn/src/gdb:/usr/src:$cdir:$cwd" +(gdb) +-environment-directory -r +^done,source-path="$cdir:$cwd" +(gdb) +@end smallexample + + +@findex -environment-path +@subheading The @code{-environment-path} Command + +@subsubheading Synopsis + +@smallexample + -environment-path [ -r ] [ @var{pathdir} ]+ +@end smallexample + +Add directories @var{pathdir} to beginning of search path for object files. +If the @samp{-r} option is used, the search path is reset to the original +search path that existed at gdb start-up. If directories @var{pathdir} are +supplied in addition to the +@samp{-r} option, the search path is first reset and then addition +occurs as normal. +Multiple directories may be specified, separated by blanks. Specifying +multiple directories in a single command +results in the directories added to the beginning of the +search path in the same order they were presented in the command. +If blanks are needed as +part of a directory name, double-quotes should be used around +the name. In the command output, the path will show up separated +by the system directory-separator character. The directory-separator +character must not be used +in any directory name. +If no directories are specified, the current path is displayed. + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{path}. + +@subsubheading Example + +@smallexample +(gdb) +-environment-path +^done,path="/usr/bin" +(gdb) +-environment-path /kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb /bin +^done,path="/kwikemart/marge/ezannoni/flathead-dev/ppc-eabi/gdb:/bin:/usr/bin" +(gdb) +-environment-path -r /usr/local/bin +^done,path="/usr/local/bin:/usr/bin" +(gdb) +@end smallexample + + +@findex -environment-pwd +@subheading The @code{-environment-pwd} Command + +@subsubheading Synopsis + +@smallexample + -environment-pwd +@end smallexample + +Show the current working directory. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{pwd}. + +@subsubheading Example + +@smallexample +(gdb) +-environment-pwd +^done,cwd="/kwikemart/marge/ezannoni/flathead-dev/devo/gdb" +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Thread Commands +@section @sc{gdb/mi} Thread Commands + + +@findex -thread-info +@subheading The @code{-thread-info} Command + +@subsubheading Synopsis + +@smallexample + -thread-info [ @var{thread-id} ] +@end smallexample + +Reports information about either a specific thread, if the +@var{thread-id} parameter is present, or about all threads. +@var{thread-id} is the thread's global thread ID. When printing +information about all threads, also reports the global ID of the +current thread. + +@subsubheading @value{GDBN} Command + +The @samp{info thread} command prints the same information +about all threads. + +@subsubheading Result + +The result contains the following attributes: + +@table @samp +@item threads +A list of threads. The format of the elements of the list is described in +@ref{GDB/MI Thread Information}. + +@item current-thread-id +The global id of the currently selected thread. This field is omitted if there +is no selected thread (for example, when the selected inferior is not running, +and therefore has no threads) or if a @var{thread-id} argument was passed to +the command. + +@end table + +@subsubheading Example + +@smallexample +-thread-info +^done,threads=[ +@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall", + args=[]@},state="running"@}, +@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame=@{level="0",addr="0x0804891f",func="foo", + args=[@{name="i",value="10"@}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@}, + state="running"@}], +current-thread-id="1" +(gdb) +@end smallexample + +@findex -thread-list-ids +@subheading The @code{-thread-list-ids} Command + +@subsubheading Synopsis + +@smallexample + -thread-list-ids +@end smallexample + +Produces a list of the currently known global @value{GDBN} thread ids. +At the end of the list it also prints the total number of such +threads. + +This command is retained for historical reasons, the +@code{-thread-info} command should be used instead. + +@subsubheading @value{GDBN} Command + +Part of @samp{info threads} supplies the same information. + +@subsubheading Example + +@smallexample +(gdb) +-thread-list-ids +^done,thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, +current-thread-id="1",number-of-threads="3" +(gdb) +@end smallexample + + +@findex -thread-select +@subheading The @code{-thread-select} Command + +@subsubheading Synopsis + +@smallexample + -thread-select @var{thread-id} +@end smallexample + +Make thread with global thread number @var{thread-id} the current +thread. It prints the number of the new current thread, and the +topmost frame for that thread. + +This command is deprecated in favor of explicitly using the +@samp{--thread} option to each command. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{thread}. + +@subsubheading Example + +@smallexample +(gdb) +-exec-next +^running +(gdb) +*stopped,reason="end-stepping-range",thread-id="2",line="187", +file="../../../devo/gdb/testsuite/gdb.threads/linux-dp.c" +(gdb) +-thread-list-ids +^done, +thread-ids=@{thread-id="3",thread-id="2",thread-id="1"@}, +number-of-threads="3" +(gdb) +-thread-select 3 +^done,new-thread-id="3", +frame=@{level="0",func="vprintf", +args=[@{name="format",value="0x8048e9c \"%*s%c %d %c\\n\""@}, +@{name="arg",value="0x2"@}],file="vprintf.c",line="31",arch="i386:x86_64"@} +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Ada Tasking Commands +@section @sc{gdb/mi} Ada Tasking Commands + +@findex -ada-task-info +@subheading The @code{-ada-task-info} Command + +@subsubheading Synopsis + +@smallexample + -ada-task-info [ @var{task-id} ] +@end smallexample + +Reports information about either a specific Ada task, if the +@var{task-id} parameter is present, or about all Ada tasks. + +@subsubheading @value{GDBN} Command + +The @samp{info tasks} command prints the same information +about all Ada tasks (@pxref{Ada Tasks}). + +@subsubheading Result + +The result is a table of Ada tasks. The following columns are +defined for each Ada task: + +@table @samp +@item current +This field exists only for the current thread. It has the value @samp{*}. + +@item id +The identifier that @value{GDBN} uses to refer to the Ada task. + +@item task-id +The identifier that the target uses to refer to the Ada task. + +@item thread-id +The global thread identifier of the thread corresponding to the Ada +task. + +This field should always exist, as Ada tasks are always implemented +on top of a thread. But if @value{GDBN} cannot find this corresponding +thread for any reason, the field is omitted. + +@item parent-id +This field exists only when the task was created by another task. +In this case, it provides the ID of the parent task. + +@item priority +The base priority of the task. + +@item state +The current state of the task. For a detailed description of the +possible states, see @ref{Ada Tasks}. + +@item name +The name of the task. + +@end table + +@subsubheading Example + +@smallexample +-ada-task-info +^done,tasks=@{nr_rows="3",nr_cols="8", +hdr=[@{width="1",alignment="-1",col_name="current",colhdr=""@}, +@{width="3",alignment="1",col_name="id",colhdr="ID"@}, +@{width="9",alignment="1",col_name="task-id",colhdr="TID"@}, +@{width="4",alignment="1",col_name="thread-id",colhdr=""@}, +@{width="4",alignment="1",col_name="parent-id",colhdr="P-ID"@}, +@{width="3",alignment="1",col_name="priority",colhdr="Pri"@}, +@{width="22",alignment="-1",col_name="state",colhdr="State"@}, +@{width="1",alignment="2",col_name="name",colhdr="Name"@}], +body=[@{current="*",id="1",task-id=" 644010",thread-id="1",priority="48", +state="Child Termination Wait",name="main_task"@}]@} +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Program Execution +@section @sc{gdb/mi} Program Execution + +These are the asynchronous commands which generate the out-of-band +record @samp{*stopped}. Currently @value{GDBN} only really executes +asynchronously with remote targets and this interaction is mimicked in +other cases. + +@findex -exec-continue +@subheading The @code{-exec-continue} Command + +@subsubheading Synopsis + +@smallexample + -exec-continue [--reverse] [--all|--thread-group N] +@end smallexample + +Resumes the execution of the inferior program, which will continue +to execute until it reaches a debugger stop event. If the +@samp{--reverse} option is specified, execution resumes in reverse until +it reaches a stop event. Stop events may include +@itemize @bullet +@item +breakpoints, watchpoints, tracepoints, or catchpoints +@item +signals or exceptions +@item +the end of the process (or its beginning under @samp{--reverse}) +@item +the end or beginning of a replay log if one is being used. +@end itemize +In all-stop mode (@pxref{All-Stop +Mode}), may resume only one thread, or all threads, depending on the +value of the @samp{scheduler-locking} variable. If @samp{--all} is +specified, all threads (in all inferiors) will be resumed. The @samp{--all} option is +ignored in all-stop mode. If the @samp{--thread-group} options is +specified, then all threads in that thread group are resumed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} corresponding is @samp{continue}. + +@subsubheading Example + +@smallexample +-exec-continue +^running +(gdb) +@@Hello world +*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",frame=@{ +func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", +line="13",arch="i386:x86_64"@} +(gdb) +@end smallexample + +For a @samp{breakpoint-hit} stopped reason, when the breakpoint +encountered has multiple locations, the field @samp{bkptno} is +followed by the field @samp{locno}. + +@smallexample +-exec-continue +^running +(gdb) +@@Hello world +*stopped,reason="breakpoint-hit",disp="keep",bkptno="2",locno="3",frame=@{ +func="foo",args=[],file="hello.c",fullname="/home/foo/bar/hello.c", +line="13",arch="i386:x86_64"@} +(gdb) +@end smallexample + +@findex -exec-finish +@subheading The @code{-exec-finish} Command + +@subsubheading Synopsis + +@smallexample + -exec-finish [--reverse] +@end smallexample + +Resumes the execution of the inferior program until the current +function is exited. Displays the results returned by the function. +If the @samp{--reverse} option is specified, resumes the reverse +execution of the inferior program until the point where current +function was called. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{finish}. + +@subsubheading Example + +Function returning @code{void}. + +@smallexample +-exec-finish +^running +(gdb) +@@hello from foo +*stopped,reason="function-finished",frame=@{func="main",args=[], +file="hello.c",fullname="/home/foo/bar/hello.c",line="7",arch="i386:x86_64"@} +(gdb) +@end smallexample + +Function returning other than @code{void}. The name of the internal +@value{GDBN} variable storing the result is printed, together with the +value itself. + +@smallexample +-exec-finish +^running +(gdb) +*stopped,reason="function-finished",frame=@{addr="0x000107b0",func="foo", +args=[@{name="a",value="1"],@{name="b",value="9"@}@}, +file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", +arch="i386:x86_64"@}, +gdb-result-var="$1",return-value="0" +(gdb) +@end smallexample + + +@findex -exec-interrupt +@subheading The @code{-exec-interrupt} Command + +@subsubheading Synopsis + +@smallexample + -exec-interrupt [--all|--thread-group N] +@end smallexample + +Interrupts the background execution of the target. Note how the token +associated with the stop message is the one for the execution command +that has been interrupted. The token for the interrupt itself only +appears in the @samp{^done} output. If the user is trying to +interrupt a non-running program, an error message will be printed. + +Note that when asynchronous execution is enabled, this command is +asynchronous just like other execution commands. That is, first the +@samp{^done} response will be printed, and the target stop will be +reported after that using the @samp{*stopped} notification. + +In non-stop mode, only the context thread is interrupted by default. +All threads (in all inferiors) will be interrupted if the +@samp{--all} option is specified. If the @samp{--thread-group} +option is specified, all threads in that group will be interrupted. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interrupt}. + +@subsubheading Example + +@smallexample +(gdb) +111-exec-continue +111^running + +(gdb) +222-exec-interrupt +222^done +(gdb) +111*stopped,signal-name="SIGINT",signal-meaning="Interrupt", +frame=@{addr="0x00010140",func="foo",args=[],file="try.c", +fullname="/home/foo/bar/try.c",line="13",arch="i386:x86_64"@} +(gdb) + +(gdb) +-exec-interrupt +^error,msg="mi_cmd_exec_interrupt: Inferior not executing." +(gdb) +@end smallexample + +@findex -exec-jump +@subheading The @code{-exec-jump} Command + +@subsubheading Synopsis + +@smallexample + -exec-jump @var{locspec} +@end smallexample + +Resumes execution of the inferior program at the address to +which @var{locspec} resolves. @xref{Location Specifications}, +for a description of the different forms of @var{locspec}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{jump}. + +@subsubheading Example + +@smallexample +-exec-jump foo.c:10 +*running,thread-id="all" +^running +@end smallexample + + +@findex -exec-next +@subheading The @code{-exec-next} Command + +@subsubheading Synopsis + +@smallexample + -exec-next [--reverse] +@end smallexample + +Resumes execution of the inferior program, stopping when the beginning +of the next source line is reached. + +If the @samp{--reverse} option is specified, resumes reverse execution +of the inferior program, stopping at the beginning of the previous +source line. If you issue this command on the first line of a +function, it will take you back to the caller of that function, to the +source line where the function was called. + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{next}. + +@subsubheading Example + +@smallexample +-exec-next +^running +(gdb) +*stopped,reason="end-stepping-range",line="8",file="hello.c" +(gdb) +@end smallexample + + +@findex -exec-next-instruction +@subheading The @code{-exec-next-instruction} Command + +@subsubheading Synopsis + +@smallexample + -exec-next-instruction [--reverse] +@end smallexample + +Executes one machine instruction. If the instruction is a function +call, continues until the function returns. If the program stops at an +instruction in the middle of a source line, the address will be +printed as well. + +If the @samp{--reverse} option is specified, resumes reverse execution +of the inferior program, stopping at the previous instruction. If the +previously executed instruction was a return from another function, +it will continue to execute in reverse until the call to that function +(from the current stack frame) is reached. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{nexti}. + +@subsubheading Example + +@smallexample +(gdb) +-exec-next-instruction +^running + +(gdb) +*stopped,reason="end-stepping-range", +addr="0x000100d4",line="5",file="hello.c" +(gdb) +@end smallexample + + +@findex -exec-return +@subheading The @code{-exec-return} Command + +@subsubheading Synopsis + +@smallexample + -exec-return +@end smallexample + +Makes current function return immediately. Doesn't execute the inferior. +Displays the new current frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{return}. + +@subsubheading Example + +@smallexample +(gdb) +200-break-insert callee4 +200^done,bkpt=@{number="1",addr="0x00010734", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c",line="8"@} +(gdb) +000-exec-run +000^running +(gdb) +000*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", +frame=@{func="callee4",args=[], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", +arch="i386:x86_64"@} +(gdb) +205-break-delete +205^done +(gdb) +111-exec-return +111^done,frame=@{level="0",func="callee3", +args=[@{name="strarg", +value="0x11940 \"A string argument.\""@}], +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="18", +arch="i386:x86_64"@} +(gdb) +@end smallexample + + +@findex -exec-run +@subheading The @code{-exec-run} Command + +@subsubheading Synopsis + +@smallexample + -exec-run [ --all | --thread-group N ] [ --start ] +@end smallexample + +Starts execution of the inferior from the beginning. The inferior +executes until either a breakpoint is encountered or the program +exits. In the latter case the output will include an exit code, if +the program has exited exceptionally. + +When neither the @samp{--all} nor the @samp{--thread-group} option +is specified, the current inferior is started. If the +@samp{--thread-group} option is specified, it should refer to a thread +group of type @samp{process}, and that thread group will be started. +If the @samp{--all} option is specified, then all inferiors will be started. + +Using the @samp{--start} option instructs the debugger to stop +the execution at the start of the inferior's main subprogram, +following the same behavior as the @code{start} command +(@pxref{Starting}). + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{run}. + +@subsubheading Examples + +@smallexample +(gdb) +-break-insert main +^done,bkpt=@{number="1",addr="0x0001072c",file="recursive2.c",line="4"@} +(gdb) +-exec-run +^running +(gdb) +*stopped,reason="breakpoint-hit",disp="keep",bkptno="1", +frame=@{func="main",args=[],file="recursive2.c", +fullname="/home/foo/bar/recursive2.c",line="4",arch="i386:x86_64"@} +(gdb) +@end smallexample + +@noindent +Program exited normally: + +@smallexample +(gdb) +-exec-run +^running +(gdb) +x = 55 +*stopped,reason="exited-normally" +(gdb) +@end smallexample + +@noindent +Program exited exceptionally: + +@smallexample +(gdb) +-exec-run +^running +(gdb) +x = 55 +*stopped,reason="exited",exit-code="01" +(gdb) +@end smallexample + +Another way the program can terminate is if it receives a signal such as +@code{SIGINT}. In this case, @sc{gdb/mi} displays this: + +@smallexample +(gdb) +*stopped,reason="exited-signalled",signal-name="SIGINT", +signal-meaning="Interrupt" +@end smallexample + + +@c @subheading -exec-signal + + +@findex -exec-step +@subheading The @code{-exec-step} Command + +@subsubheading Synopsis + +@smallexample + -exec-step [--reverse] +@end smallexample + +Resumes execution of the inferior program, stopping when the beginning +of the next source line is reached, if the next source line is not a +function call. If it is, stop at the first instruction of the called +function. If the @samp{--reverse} option is specified, resumes reverse +execution of the inferior program, stopping at the beginning of the +previously executed source line. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{step}. + +@subsubheading Example + +Stepping into a function: + +@smallexample +-exec-step +^running +(gdb) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[@{name="a",value="10"@}, +@{name="b",value="0"@}],file="recursive2.c", +fullname="/home/foo/bar/recursive2.c",line="11",arch="i386:x86_64"@} +(gdb) +@end smallexample + +Regular stepping: + +@smallexample +-exec-step +^running +(gdb) +*stopped,reason="end-stepping-range",line="14",file="recursive2.c" +(gdb) +@end smallexample + + +@findex -exec-step-instruction +@subheading The @code{-exec-step-instruction} Command + +@subsubheading Synopsis + +@smallexample + -exec-step-instruction [--reverse] +@end smallexample + +Resumes the inferior which executes one machine instruction. If the +@samp{--reverse} option is specified, resumes reverse execution of the +inferior program, stopping at the previously executed instruction. +The output, once @value{GDBN} has stopped, will vary depending on +whether we have stopped in the middle of a source line or not. In the +former case, the address at which the program stopped will be printed +as well. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{stepi}. + +@subsubheading Example + +@smallexample +(gdb) +-exec-step-instruction +^running + +(gdb) +*stopped,reason="end-stepping-range", +frame=@{func="foo",args=[],file="try.c", +fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} +(gdb) +-exec-step-instruction +^running + +(gdb) +*stopped,reason="end-stepping-range", +frame=@{addr="0x000100f4",func="foo",args=[],file="try.c", +fullname="/home/foo/bar/try.c",line="10",arch="i386:x86_64"@} +(gdb) +@end smallexample + + +@findex -exec-until +@subheading The @code{-exec-until} Command + +@subsubheading Synopsis + +@smallexample + -exec-until [ @var{locspec} ] +@end smallexample + +Executes the inferior until it reaches the address to which +@var{locspec} resolves. If there is no argument, the inferior +executes until it reaches a source line greater than the current one. +The reason for stopping in this case will be @samp{location-reached}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{until}. + +@subsubheading Example + +@smallexample +(gdb) +-exec-until recursive2.c:6 +^running +(gdb) +x = 55 +*stopped,reason="location-reached",frame=@{func="main",args=[], +file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="6", +arch="i386:x86_64"@} +(gdb) +@end smallexample + +@ignore +@subheading -file-clear +Is this going away???? +@end ignore + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Stack Manipulation +@section @sc{gdb/mi} Stack Manipulation Commands + +@findex -enable-frame-filters +@subheading The @code{-enable-frame-filters} Command + +@smallexample +-enable-frame-filters +@end smallexample + +@value{GDBN} allows Python-based frame filters to affect the output of +the MI commands relating to stack traces. As there is no way to +implement this in a fully backward-compatible way, a front end must +request that this functionality be enabled. + +Once enabled, this feature cannot be disabled. + +Note that if Python support has not been compiled into @value{GDBN}, +this command will still succeed (and do nothing). + +@findex -stack-info-frame +@subheading The @code{-stack-info-frame} Command + +@subsubheading Synopsis + +@smallexample + -stack-info-frame +@end smallexample + +Get info on the selected frame. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info frame} or @samp{frame} +(without arguments). + +@subsubheading Example + +@smallexample +(gdb) +-stack-info-frame +^done,frame=@{level="1",addr="0x0001076c",func="callee3", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", +arch="i386:x86_64"@} +(gdb) +@end smallexample + +@findex -stack-info-depth +@subheading The @code{-stack-info-depth} Command + +@subsubheading Synopsis + +@smallexample + -stack-info-depth [ @var{max-depth} ] +@end smallexample + +Return the depth of the stack. If the integer argument @var{max-depth} +is specified, do not count beyond @var{max-depth} frames. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example + +For a stack with frame levels 0 through 11: + +@smallexample +(gdb) +-stack-info-depth +^done,depth="12" +(gdb) +-stack-info-depth 4 +^done,depth="4" +(gdb) +-stack-info-depth 12 +^done,depth="12" +(gdb) +-stack-info-depth 11 +^done,depth="11" +(gdb) +-stack-info-depth 13 +^done,depth="12" +(gdb) +@end smallexample + +@anchor{-stack-list-arguments} +@findex -stack-list-arguments +@subheading The @code{-stack-list-arguments} Command + +@subsubheading Synopsis + +@smallexample + -stack-list-arguments [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} + [ @var{low-frame} @var{high-frame} ] +@end smallexample + +Display a list of the arguments for the frames between @var{low-frame} +and @var{high-frame} (inclusive). If @var{low-frame} and +@var{high-frame} are not provided, list the arguments for the whole +call stack. If the two arguments are equal, show the single frame +at the corresponding level. It is an error if @var{low-frame} is +larger than the actual number of frames. On the other hand, +@var{high-frame} may be larger than the actual number of frames, in +which case only existing frames will be returned. + +If @var{print-values} is 0 or @code{--no-values}, print only the names of +the variables; if it is 1 or @code{--all-values}, print also their +values; and if it is 2 or @code{--simple-values}, print the name, +type and value for simple data types, and the name and type for arrays, +structures and unions. If the option @code{--no-frame-filters} is +supplied, then Python frame filters will not be executed. + +If the @code{--skip-unavailable} option is specified, arguments that +are not available are not listed. Partially available arguments +are still displayed, however. + +Use of this command to obtain arguments in a single frame is +deprecated in favor of the @samp{-stack-list-variables} command. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have an equivalent command. @code{gdbtk} has a +@samp{gdb_get_args} command which partially overlaps with the +functionality of @samp{-stack-list-arguments}. + +@subsubheading Example + +@smallexample +(gdb) +-stack-list-frames +^done, +stack=[ +frame=@{level="0",addr="0x00010734",func="callee4", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="8", +arch="i386:x86_64"@}, +frame=@{level="1",addr="0x0001076c",func="callee3", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="17", +arch="i386:x86_64"@}, +frame=@{level="2",addr="0x0001078c",func="callee2", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="22", +arch="i386:x86_64"@}, +frame=@{level="3",addr="0x000107b4",func="callee1", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="27", +arch="i386:x86_64"@}, +frame=@{level="4",addr="0x000107e0",func="main", +file="../../../devo/gdb/testsuite/gdb.mi/basics.c", +fullname="/home/foo/bar/devo/gdb/testsuite/gdb.mi/basics.c",line="32", +arch="i386:x86_64"@}] +(gdb) +-stack-list-arguments 0 +^done, +stack-args=[ +frame=@{level="0",args=[]@}, +frame=@{level="1",args=[name="strarg"]@}, +frame=@{level="2",args=[name="intarg",name="strarg"]@}, +frame=@{level="3",args=[name="intarg",name="strarg",name="fltarg"]@}, +frame=@{level="4",args=[]@}] +(gdb) +-stack-list-arguments 1 +^done, +stack-args=[ +frame=@{level="0",args=[]@}, +frame=@{level="1", + args=[@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +frame=@{level="2",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}, +@{frame=@{level="3",args=[ +@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}, +@{name="fltarg",value="3.5"@}]@}, +frame=@{level="4",args=[]@}] +(gdb) +-stack-list-arguments 0 2 2 +^done,stack-args=[frame=@{level="2",args=[name="intarg",name="strarg"]@}] +(gdb) +-stack-list-arguments 1 2 2 +^done,stack-args=[frame=@{level="2", +args=[@{name="intarg",value="2"@}, +@{name="strarg",value="0x11940 \"A string argument.\""@}]@}] +(gdb) +@end smallexample + +@c @subheading -stack-list-exception-handlers + + +@anchor{-stack-list-frames} +@findex -stack-list-frames +@subheading The @code{-stack-list-frames} Command + +@subsubheading Synopsis + +@smallexample + -stack-list-frames [ --no-frame-filters @var{low-frame} @var{high-frame} ] +@end smallexample + +List the frames currently on the stack. For each frame it displays the +following info: + +@table @samp +@item @var{level} +The frame number, 0 being the topmost frame, i.e., the innermost function. +@item @var{addr} +The @code{$pc} value for that frame. +@item @var{func} +Function name. +@item @var{file} +File name of the source file where the function lives. +@item @var{fullname} +The full file name of the source file where the function lives. +@item @var{line} +Line number corresponding to the @code{$pc}. +@item @var{from} +The shared library where this function is defined. This is only given +if the frame's function is not known. +@item @var{arch} +Frame's architecture. +@end table + +If invoked without arguments, this command prints a backtrace for the +whole stack. If given two integer arguments, it shows the frames whose +levels are between the two arguments (inclusive). If the two arguments +are equal, it shows the single frame at the corresponding level. It is +an error if @var{low-frame} is larger than the actual number of +frames. On the other hand, @var{high-frame} may be larger than the +actual number of frames, in which case only existing frames will be +returned. If the option @code{--no-frame-filters} is supplied, then +Python frame filters will not be executed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{backtrace} and @samp{where}. + +@subsubheading Example + +Full stack backtrace: + +@smallexample +(gdb) +-stack-list-frames +^done,stack= +[frame=@{level="0",addr="0x0001076c",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="11", + arch="i386:x86_64"@}, +frame=@{level="1",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="2",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="6",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="7",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="8",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="9",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="10",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="11",addr="0x00010738",func="main", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="4", + arch="i386:x86_64"@}] +(gdb) +@end smallexample + +Show frames between @var{low_frame} and @var{high_frame}: + +@smallexample +(gdb) +-stack-list-frames 3 5 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="4",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}, +frame=@{level="5",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}] +(gdb) +@end smallexample + +Show a single frame: + +@smallexample +(gdb) +-stack-list-frames 3 3 +^done,stack= +[frame=@{level="3",addr="0x000107a4",func="foo", + file="recursive2.c",fullname="/home/foo/bar/recursive2.c",line="14", + arch="i386:x86_64"@}] +(gdb) +@end smallexample + + +@findex -stack-list-locals +@anchor{-stack-list-locals} +@subheading The @code{-stack-list-locals} Command + +@subsubheading Synopsis + +@smallexample + -stack-list-locals [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} +@end smallexample + +Display the local variable names for the selected frame. If +@var{print-values} is 0 or @code{--no-values}, print only the names of +the variables; if it is 1 or @code{--all-values}, print also their +values; and if it is 2 or @code{--simple-values}, print the name, +type and value for simple data types, and the name and type for arrays, +structures and unions. In this last case, a frontend can immediately +display the value of simple data types and create variable objects for +other data types when the user wishes to explore their values in +more detail. If the option @code{--no-frame-filters} is supplied, then +Python frame filters will not be executed. + +If the @code{--skip-unavailable} option is specified, local variables +that are not available are not listed. Partially available local +variables are still displayed, however. + +This command is deprecated in favor of the +@samp{-stack-list-variables} command. + +@subsubheading @value{GDBN} Command + +@samp{info locals} in @value{GDBN}, @samp{gdb_get_locals} in @code{gdbtk}. + +@subsubheading Example + +@smallexample +(gdb) +-stack-list-locals 0 +^done,locals=[name="A",name="B",name="C"] +(gdb) +-stack-list-locals --all-values +^done,locals=[@{name="A",value="1"@},@{name="B",value="2"@}, + @{name="C",value="@{1, 2, 3@}"@}] +-stack-list-locals --simple-values +^done,locals=[@{name="A",type="int",value="1"@}, + @{name="B",type="int",value="2"@},@{name="C",type="int [3]"@}] +(gdb) +@end smallexample + +@anchor{-stack-list-variables} +@findex -stack-list-variables +@subheading The @code{-stack-list-variables} Command + +@subsubheading Synopsis + +@smallexample + -stack-list-variables [ --no-frame-filters ] [ --skip-unavailable ] @var{print-values} +@end smallexample + +Display the names of local variables and function arguments for the selected frame. If +@var{print-values} is 0 or @code{--no-values}, print only the names of +the variables; if it is 1 or @code{--all-values}, print also their +values; and if it is 2 or @code{--simple-values}, print the name, +type and value for simple data types, and the name and type for arrays, +structures and unions. If the option @code{--no-frame-filters} is +supplied, then Python frame filters will not be executed. + +If the @code{--skip-unavailable} option is specified, local variables +and arguments that are not available are not listed. Partially +available arguments and local variables are still displayed, however. + +@subsubheading Example + +@smallexample +(gdb) +-stack-list-variables --thread 1 --frame 0 --all-values +^done,variables=[@{name="x",value="11"@},@{name="s",value="@{a = 1, b = 2@}"@}] +(gdb) +@end smallexample + + +@findex -stack-select-frame +@subheading The @code{-stack-select-frame} Command + +@subsubheading Synopsis + +@smallexample + -stack-select-frame @var{framenum} +@end smallexample + +Change the selected frame. Select a different frame @var{framenum} on +the stack. + +This command in deprecated in favor of passing the @samp{--frame} +option to every command. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{frame}, @samp{up}, +@samp{down}, @samp{select-frame}, @samp{up-silent}, and @samp{down-silent}. + +@subsubheading Example + +@smallexample +(gdb) +-stack-select-frame 2 +^done +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Variable Objects +@section @sc{gdb/mi} Variable Objects + +@ignore + +@subheading Motivation for Variable Objects in @sc{gdb/mi} + +For the implementation of a variable debugger window (locals, watched +expressions, etc.), we are proposing the adaptation of the existing code +used by @code{Insight}. + +The two main reasons for that are: + +@enumerate 1 +@item +It has been proven in practice (it is already on its second generation). + +@item +It will shorten development time (needless to say how important it is +now). +@end enumerate + +The original interface was designed to be used by Tcl code, so it was +slightly changed so it could be used through @sc{gdb/mi}. This section +describes the @sc{gdb/mi} operations that will be available and gives some +hints about their use. + +@emph{Note}: In addition to the set of operations described here, we +expect the @sc{gui} implementation of a variable window to require, at +least, the following operations: + +@itemize @bullet +@item @code{-gdb-show} @code{output-radix} +@item @code{-stack-list-arguments} +@item @code{-stack-list-locals} +@item @code{-stack-select-frame} +@end itemize + +@end ignore + +@subheading Introduction to Variable Objects + +@cindex variable objects in @sc{gdb/mi} + +Variable objects are "object-oriented" MI interface for examining and +changing values of expressions. Unlike some other MI interfaces that +work with expressions, variable objects are specifically designed for +simple and efficient presentation in the frontend. A variable object +is identified by string name. When a variable object is created, the +frontend specifies the expression for that variable object. The +expression can be a simple variable, or it can be an arbitrary complex +expression, and can even involve CPU registers. After creating a +variable object, the frontend can invoke other variable object +operations---for example to obtain or change the value of a variable +object, or to change display format. + +Variable objects have hierarchical tree structure. Any variable object +that corresponds to a composite type, such as structure in C, has +a number of child variable objects, for example corresponding to each +element of a structure. A child variable object can itself have +children, recursively. Recursion ends when we reach +leaf variable objects, which always have built-in types. Child variable +objects are created only by explicit request, so if a frontend +is not interested in the children of a particular variable object, no +child will be created. + +For a leaf variable object it is possible to obtain its value as a +string, or set the value from a string. String value can be also +obtained for a non-leaf variable object, but it's generally a string +that only indicates the type of the object, and does not list its +contents. Assignment to a non-leaf variable object is not allowed. + +A frontend does not need to read the values of all variable objects each time +the program stops. Instead, MI provides an update command that lists all +variable objects whose values has changed since the last update +operation. This considerably reduces the amount of data that must +be transferred to the frontend. As noted above, children variable +objects are created on demand, and only leaf variable objects have a +real value. As result, gdb will read target memory only for leaf +variables that frontend has created. + +The automatic update is not always desirable. For example, a frontend +might want to keep a value of some expression for future reference, +and never update it. For another example, fetching memory is +relatively slow for embedded targets, so a frontend might want +to disable automatic update for the variables that are either not +visible on the screen, or ``closed''. This is possible using so +called ``frozen variable objects''. Such variable objects are never +implicitly updated. + +Variable objects can be either @dfn{fixed} or @dfn{floating}. For the +fixed variable object, the expression is parsed when the variable +object is created, including associating identifiers to specific +variables. The meaning of expression never changes. For a floating +variable object the values of variables whose names appear in the +expressions are re-evaluated every time in the context of the current +frame. Consider this example: + +@smallexample +void do_work(...) +@{ + struct work_state state; + + if (...) + do_work(...); +@} +@end smallexample + +If a fixed variable object for the @code{state} variable is created in +this function, and we enter the recursive call, the variable +object will report the value of @code{state} in the top-level +@code{do_work} invocation. On the other hand, a floating variable +object will report the value of @code{state} in the current frame. + +If an expression specified when creating a fixed variable object +refers to a local variable, the variable object becomes bound to the +thread and frame in which the variable object is created. When such +variable object is updated, @value{GDBN} makes sure that the +thread/frame combination the variable object is bound to still exists, +and re-evaluates the variable object in context of that thread/frame. + +The following is the complete set of @sc{gdb/mi} operations defined to +access this functionality: + +@multitable @columnfractions .4 .6 +@item @strong{Operation} +@tab @strong{Description} + +@item @code{-enable-pretty-printing} +@tab enable Python-based pretty-printing +@item @code{-var-create} +@tab create a variable object +@item @code{-var-delete} +@tab delete the variable object and/or its children +@item @code{-var-set-format} +@tab set the display format of this variable +@item @code{-var-show-format} +@tab show the display format of this variable +@item @code{-var-info-num-children} +@tab tells how many children this object has +@item @code{-var-list-children} +@tab return a list of the object's children +@item @code{-var-info-type} +@tab show the type of this variable object +@item @code{-var-info-expression} +@tab print parent-relative expression that this variable object represents +@item @code{-var-info-path-expression} +@tab print full expression that this variable object represents +@item @code{-var-show-attributes} +@tab is this variable editable? does it exist here? +@item @code{-var-evaluate-expression} +@tab get the value of this variable +@item @code{-var-assign} +@tab set the value of this variable +@item @code{-var-update} +@tab update the variable and its children +@item @code{-var-set-frozen} +@tab set frozenness attribute +@item @code{-var-set-update-range} +@tab set range of children to display on update +@end multitable + +In the next subsection we describe each operation in detail and suggest +how it can be used. + +@subheading Description And Use of Operations on Variable Objects + +@findex -enable-pretty-printing +@subheading The @code{-enable-pretty-printing} Command + +@smallexample +-enable-pretty-printing +@end smallexample + +@value{GDBN} allows Python-based visualizers to affect the output of the +MI variable object commands. However, because there was no way to +implement this in a fully backward-compatible way, a front end must +request that this functionality be enabled. + +Once enabled, this feature cannot be disabled. + +Note that if Python support has not been compiled into @value{GDBN}, +this command will still succeed (and do nothing). + +@findex -var-create +@subheading The @code{-var-create} Command + +@subsubheading Synopsis + +@smallexample + -var-create @{@var{name} | "-"@} + @{@var{frame-addr} | "*" | "@@"@} @var{expression} +@end smallexample + +This operation creates a variable object, which allows the monitoring of +a variable, the result of an expression, a memory cell or a CPU +register. + +The @var{name} parameter is the string by which the object can be +referenced. It must be unique. If @samp{-} is specified, the varobj +system will generate a string ``varNNNNNN'' automatically. It will be +unique provided that one does not specify @var{name} of that format. +The command fails if a duplicate name is found. + +The frame under which the expression should be evaluated can be +specified by @var{frame-addr}. A @samp{*} indicates that the current +frame should be used. A @samp{@@} indicates that a floating variable +object must be created. + +@var{expression} is any expression valid on the current language set (must not +begin with a @samp{*}), or one of the following: + +@itemize @bullet +@item +@samp{*@var{addr}}, where @var{addr} is the address of a memory cell + +@item +@samp{*@var{addr}-@var{addr}} --- a memory address range (TBD) + +@item +@samp{$@var{regname}} --- a CPU register name +@end itemize + +@cindex dynamic varobj +A varobj's contents may be provided by a Python-based pretty-printer. In this +case the varobj is known as a @dfn{dynamic varobj}. Dynamic varobjs +have slightly different semantics in some cases. If the +@code{-enable-pretty-printing} command is not sent, then @value{GDBN} +will never create a dynamic varobj. This ensures backward +compatibility for existing clients. + +@subsubheading Result + +This operation returns attributes of the newly-created varobj. These +are: + +@table @samp +@item name +The name of the varobj. + +@item numchild +The number of children of the varobj. This number is not necessarily +reliable for a dynamic varobj. Instead, you must examine the +@samp{has_more} attribute. + +@item value +The varobj's scalar value. For a varobj whose type is some sort of +aggregate (e.g., a @code{struct}), this value will not be interesting. +For a dynamic varobj, this value comes directly from the Python +pretty-printer object's @code{to_string} method. + +@item type +The varobj's type. This is a string representation of the type, as +would be printed by the @value{GDBN} CLI. If @samp{print object} +(@pxref{Print Settings, set print object}) is set to @code{on}, the +@emph{actual} (derived) type of the object is shown rather than the +@emph{declared} one. + +@item thread-id +If a variable object is bound to a specific thread, then this is the +thread's global identifier. + +@item has_more +For a dynamic varobj, this indicates whether there appear to be any +children available. For a non-dynamic varobj, this will be 0. + +@item dynamic +This attribute will be present and have the value @samp{1} if the +varobj is a dynamic varobj. If the varobj is not a dynamic varobj, +then this attribute will not be present. + +@item displayhint +A dynamic varobj can supply a display hint to the front end. The +value comes directly from the Python pretty-printer object's +@code{display_hint} method. @xref{Pretty Printing API}. +@end table + +Typical output will look like this: + +@smallexample + name="@var{name}",numchild="@var{N}",type="@var{type}",thread-id="@var{M}", + has_more="@var{has_more}" +@end smallexample + + +@findex -var-delete +@subheading The @code{-var-delete} Command + +@subsubheading Synopsis + +@smallexample + -var-delete [ -c ] @var{name} +@end smallexample + +Deletes a previously created variable object and all of its children. +With the @samp{-c} option, just deletes the children. + +Returns an error if the object @var{name} is not found. + + +@findex -var-set-format +@subheading The @code{-var-set-format} Command + +@subsubheading Synopsis + +@smallexample + -var-set-format @var{name} @var{format-spec} +@end smallexample + +Sets the output format for the value of the object @var{name} to be +@var{format-spec}. + +@anchor{-var-set-format} +The syntax for the @var{format-spec} is as follows: + +@smallexample + @var{format-spec} @expansion{} + @{binary | decimal | hexadecimal | octal | natural | zero-hexadecimal@} +@end smallexample + +The natural format is the default format chosen automatically +based on the variable type (like decimal for an @code{int}, hex +for pointers, etc.). + +The zero-hexadecimal format has a representation similar to hexadecimal +but with padding zeroes to the left of the value. For example, a 32-bit +hexadecimal value of 0x1234 would be represented as 0x00001234 in the +zero-hexadecimal format. + +For a variable with children, the format is set only on the +variable itself, and the children are not affected. + +@findex -var-show-format +@subheading The @code{-var-show-format} Command + +@subsubheading Synopsis + +@smallexample + -var-show-format @var{name} +@end smallexample + +Returns the format used to display the value of the object @var{name}. + +@smallexample + @var{format} @expansion{} + @var{format-spec} +@end smallexample + + +@findex -var-info-num-children +@subheading The @code{-var-info-num-children} Command + +@subsubheading Synopsis + +@smallexample + -var-info-num-children @var{name} +@end smallexample + +Returns the number of children of a variable object @var{name}: + +@smallexample + numchild=@var{n} +@end smallexample + +Note that this number is not completely reliable for a dynamic varobj. +It will return the current number of children, but more children may +be available. + + +@findex -var-list-children +@subheading The @code{-var-list-children} Command + +@subsubheading Synopsis + +@smallexample + -var-list-children [@var{print-values}] @var{name} [@var{from} @var{to}] +@end smallexample +@anchor{-var-list-children} + +Return a list of the children of the specified variable object and +create variable objects for them, if they do not already exist. With +a single argument or if @var{print-values} has a value of 0 or +@code{--no-values}, print only the names of the variables; if +@var{print-values} is 1 or @code{--all-values}, also print their +values; and if it is 2 or @code{--simple-values} print the name and +value for simple data types and just the name for arrays, structures +and unions. + +@var{from} and @var{to}, if specified, indicate the range of children +to report. If @var{from} or @var{to} is less than zero, the range is +reset and all children will be reported. Otherwise, children starting +at @var{from} (zero-based) and up to and excluding @var{to} will be +reported. + +If a child range is requested, it will only affect the current call to +@code{-var-list-children}, but not future calls to @code{-var-update}. +For this, you must instead use @code{-var-set-update-range}. The +intent of this approach is to enable a front end to implement any +update approach it likes; for example, scrolling a view may cause the +front end to request more children with @code{-var-list-children}, and +then the front end could call @code{-var-set-update-range} with a +different range to ensure that future updates are restricted to just +the visible items. + +For each child the following results are returned: + +@table @var + +@item name +Name of the variable object created for this child. + +@item exp +The expression to be shown to the user by the front end to designate this child. +For example this may be the name of a structure member. + +For a dynamic varobj, this value cannot be used to form an +expression. There is no way to do this at all with a dynamic varobj. + +For C/C@t{++} structures there are several pseudo children returned to +designate access qualifiers. For these pseudo children @var{exp} is +@samp{public}, @samp{private}, or @samp{protected}. In this case the +type and value are not present. + +A dynamic varobj will not report the access qualifying +pseudo-children, regardless of the language. This information is not +available at all with a dynamic varobj. + +@item numchild +Number of children this child has. For a dynamic varobj, this will be +0. + +@item type +The type of the child. If @samp{print object} +(@pxref{Print Settings, set print object}) is set to @code{on}, the +@emph{actual} (derived) type of the object is shown rather than the +@emph{declared} one. + +@item value +If values were requested, this is the value. + +@item thread-id +If this variable object is associated with a thread, this is the +thread's global thread id. Otherwise this result is not present. + +@item frozen +If the variable object is frozen, this variable will be present with a value of 1. + +@item displayhint +A dynamic varobj can supply a display hint to the front end. The +value comes directly from the Python pretty-printer object's +@code{display_hint} method. @xref{Pretty Printing API}. + +@item dynamic +This attribute will be present and have the value @samp{1} if the +varobj is a dynamic varobj. If the varobj is not a dynamic varobj, +then this attribute will not be present. + +@end table + +The result may have its own attributes: + +@table @samp +@item displayhint +A dynamic varobj can supply a display hint to the front end. The +value comes directly from the Python pretty-printer object's +@code{display_hint} method. @xref{Pretty Printing API}. + +@item has_more +This is an integer attribute which is nonzero if there are children +remaining after the end of the selected range. +@end table + +@subsubheading Example + +@smallexample +(gdb) + -var-list-children n + ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, + numchild=@var{n},type=@var{type}@},@r{(repeats N times)}] +(gdb) + -var-list-children --all-values n + ^done,numchild=@var{n},children=[child=@{name=@var{name},exp=@var{exp}, + numchild=@var{n},value=@var{value},type=@var{type}@},@r{(repeats N times)}] +@end smallexample + + +@findex -var-info-type +@subheading The @code{-var-info-type} Command + +@subsubheading Synopsis + +@smallexample + -var-info-type @var{name} +@end smallexample + +Returns the type of the specified variable @var{name}. The type is +returned as a string in the same format as it is output by the +@value{GDBN} CLI: + +@smallexample + type=@var{typename} +@end smallexample + + +@findex -var-info-expression +@subheading The @code{-var-info-expression} Command + +@subsubheading Synopsis + +@smallexample + -var-info-expression @var{name} +@end smallexample + +Returns a string that is suitable for presenting this +variable object in user interface. The string is generally +not valid expression in the current language, and cannot be evaluated. + +For example, if @code{a} is an array, and variable object +@code{A} was created for @code{a}, then we'll get this output: + +@smallexample +(gdb) -var-info-expression A.1 +^done,lang="C",exp="1" +@end smallexample + +@noindent +Here, the value of @code{lang} is the language name, which can be +found in @ref{Supported Languages}. + +Note that the output of the @code{-var-list-children} command also +includes those expressions, so the @code{-var-info-expression} command +is of limited use. + +@findex -var-info-path-expression +@subheading The @code{-var-info-path-expression} Command + +@subsubheading Synopsis + +@smallexample + -var-info-path-expression @var{name} +@end smallexample + +Returns an expression that can be evaluated in the current +context and will yield the same value that a variable object has. +Compare this with the @code{-var-info-expression} command, which +result can be used only for UI presentation. Typical use of +the @code{-var-info-path-expression} command is creating a +watchpoint from a variable object. + +This command is currently not valid for children of a dynamic varobj, +and will give an error when invoked on one. + +For example, suppose @code{C} is a C@t{++} class, derived from class +@code{Base}, and that the @code{Base} class has a member called +@code{m_size}. Assume a variable @code{c} is has the type of +@code{C} and a variable object @code{C} was created for variable +@code{c}. Then, we'll get this output: +@smallexample +(gdb) -var-info-path-expression C.Base.public.m_size +^done,path_expr=((Base)c).m_size) +@end smallexample + +@findex -var-show-attributes +@subheading The @code{-var-show-attributes} Command + +@subsubheading Synopsis + +@smallexample + -var-show-attributes @var{name} +@end smallexample + +List attributes of the specified variable object @var{name}: + +@smallexample + status=@var{attr} [ ( ,@var{attr} )* ] +@end smallexample + +@noindent +where @var{attr} is @code{@{ @{ editable | noneditable @} | TBD @}}. + +@findex -var-evaluate-expression +@subheading The @code{-var-evaluate-expression} Command + +@subsubheading Synopsis + +@smallexample + -var-evaluate-expression [-f @var{format-spec}] @var{name} +@end smallexample + +Evaluates the expression that is represented by the specified variable +object and returns its value as a string. The format of the string +can be specified with the @samp{-f} option. The possible values of +this option are the same as for @code{-var-set-format} +(@pxref{-var-set-format}). If the @samp{-f} option is not specified, +the current display format will be used. The current display format +can be changed using the @code{-var-set-format} command. + +@smallexample + value=@var{value} +@end smallexample + +Note that one must invoke @code{-var-list-children} for a variable +before the value of a child variable can be evaluated. + +@findex -var-assign +@subheading The @code{-var-assign} Command + +@subsubheading Synopsis + +@smallexample + -var-assign @var{name} @var{expression} +@end smallexample + +Assigns the value of @var{expression} to the variable object specified +by @var{name}. The object must be @samp{editable}. If the variable's +value is altered by the assign, the variable will show up in any +subsequent @code{-var-update} list. + +@subsubheading Example + +@smallexample +(gdb) +-var-assign var1 3 +^done,value="3" +(gdb) +-var-update * +^done,changelist=[@{name="var1",in_scope="true",type_changed="false"@}] +(gdb) +@end smallexample + +@findex -var-update +@subheading The @code{-var-update} Command + +@subsubheading Synopsis + +@smallexample + -var-update [@var{print-values}] @{@var{name} | "*"@} +@end smallexample + +Reevaluate the expressions corresponding to the variable object +@var{name} and all its direct and indirect children, and return the +list of variable objects whose values have changed; @var{name} must +be a root variable object. Here, ``changed'' means that the result of +@code{-var-evaluate-expression} before and after the +@code{-var-update} is different. If @samp{*} is used as the variable +object names, all existing variable objects are updated, except +for frozen ones (@pxref{-var-set-frozen}). The option +@var{print-values} determines whether both names and values, or just +names are printed. The possible values of this option are the same +as for @code{-var-list-children} (@pxref{-var-list-children}). It is +recommended to use the @samp{--all-values} option, to reduce the +number of MI commands needed on each program stop. + +With the @samp{*} parameter, if a variable object is bound to a +currently running thread, it will not be updated, without any +diagnostic. + +If @code{-var-set-update-range} was previously used on a varobj, then +only the selected range of children will be reported. + +@code{-var-update} reports all the changed varobjs in a tuple named +@samp{changelist}. + +Each item in the change list is itself a tuple holding: + +@table @samp +@item name +The name of the varobj. + +@item value +If values were requested for this update, then this field will be +present and will hold the value of the varobj. + +@item in_scope +@anchor{-var-update} +This field is a string which may take one of three values: + +@table @code +@item "true" +The variable object's current value is valid. + +@item "false" +The variable object does not currently hold a valid value but it may +hold one in the future if its associated expression comes back into +scope. + +@item "invalid" +The variable object no longer holds a valid value. +This can occur when the executable file being debugged has changed, +either through recompilation or by using the @value{GDBN} @code{file} +command. The front end should normally choose to delete these variable +objects. +@end table + +In the future new values may be added to this list so the front should +be prepared for this possibility. @xref{GDB/MI Development and Front Ends, ,@sc{gdb/mi} Development and Front Ends}. + +@item type_changed +This is only present if the varobj is still valid. If the type +changed, then this will be the string @samp{true}; otherwise it will +be @samp{false}. + +When a varobj's type changes, its children are also likely to have +become incorrect. Therefore, the varobj's children are automatically +deleted when this attribute is @samp{true}. Also, the varobj's update +range, when set using the @code{-var-set-update-range} command, is +unset. + +@item new_type +If the varobj's type changed, then this field will be present and will +hold the new type. + +@item new_num_children +For a dynamic varobj, if the number of children changed, or if the +type changed, this will be the new number of children. + +The @samp{numchild} field in other varobj responses is generally not +valid for a dynamic varobj -- it will show the number of children that +@value{GDBN} knows about, but because dynamic varobjs lazily +instantiate their children, this will not reflect the number of +children which may be available. + +The @samp{new_num_children} attribute only reports changes to the +number of children known by @value{GDBN}. This is the only way to +detect whether an update has removed children (which necessarily can +only happen at the end of the update range). + +@item displayhint +The display hint, if any. + +@item has_more +This is an integer value, which will be 1 if there are more children +available outside the varobj's update range. + +@item dynamic +This attribute will be present and have the value @samp{1} if the +varobj is a dynamic varobj. If the varobj is not a dynamic varobj, +then this attribute will not be present. + +@item new_children +If new children were added to a dynamic varobj within the selected +update range (as set by @code{-var-set-update-range}), then they will +be listed in this attribute. +@end table + +@subsubheading Example + +@smallexample +(gdb) +-var-assign var1 3 +^done,value="3" +(gdb) +-var-update --all-values var1 +^done,changelist=[@{name="var1",value="3",in_scope="true", +type_changed="false"@}] +(gdb) +@end smallexample + +@findex -var-set-frozen +@anchor{-var-set-frozen} +@subheading The @code{-var-set-frozen} Command + +@subsubheading Synopsis + +@smallexample + -var-set-frozen @var{name} @var{flag} +@end smallexample + +Set the frozenness flag on the variable object @var{name}. The +@var{flag} parameter should be either @samp{1} to make the variable +frozen or @samp{0} to make it unfrozen. If a variable object is +frozen, then neither itself, nor any of its children, are +implicitly updated by @code{-var-update} of +a parent variable or by @code{-var-update *}. Only +@code{-var-update} of the variable itself will update its value and +values of its children. After a variable object is unfrozen, it is +implicitly updated by all subsequent @code{-var-update} operations. +Unfreezing a variable does not update it, only subsequent +@code{-var-update} does. + +@subsubheading Example + +@smallexample +(gdb) +-var-set-frozen V 1 +^done +(gdb) +@end smallexample + +@findex -var-set-update-range +@anchor{-var-set-update-range} +@subheading The @code{-var-set-update-range} command + +@subsubheading Synopsis + +@smallexample + -var-set-update-range @var{name} @var{from} @var{to} +@end smallexample + +Set the range of children to be returned by future invocations of +@code{-var-update}. + +@var{from} and @var{to} indicate the range of children to report. If +@var{from} or @var{to} is less than zero, the range is reset and all +children will be reported. Otherwise, children starting at @var{from} +(zero-based) and up to and excluding @var{to} will be reported. + +@subsubheading Example + +@smallexample +(gdb) +-var-set-update-range V 1 2 +^done +@end smallexample + +@findex -var-set-visualizer +@anchor{-var-set-visualizer} +@subheading The @code{-var-set-visualizer} command + +@subsubheading Synopsis + +@smallexample + -var-set-visualizer @var{name} @var{visualizer} +@end smallexample + +Set a visualizer for the variable object @var{name}. + +@var{visualizer} is the visualizer to use. The special value +@samp{None} means to disable any visualizer in use. + +If not @samp{None}, @var{visualizer} must be a Python expression. +This expression must evaluate to a callable object which accepts a +single argument. @value{GDBN} will call this object with the value of +the varobj @var{name} as an argument (this is done so that the same +Python pretty-printing code can be used for both the CLI and MI). +When called, this object must return an object which conforms to the +pretty-printing interface (@pxref{Pretty Printing API}). + +The pre-defined function @code{gdb.default_visualizer} may be used to +select a visualizer by following the built-in process +(@pxref{Selecting Pretty-Printers}). This is done automatically when +a varobj is created, and so ordinarily is not needed. + +This feature is only available if Python support is enabled. The MI +command @code{-list-features} (@pxref{GDB/MI Support Commands}) +can be used to check this. + +@subsubheading Example + +Resetting the visualizer: + +@smallexample +(gdb) +-var-set-visualizer V None +^done +@end smallexample + +Reselecting the default (type-based) visualizer: + +@smallexample +(gdb) +-var-set-visualizer V gdb.default_visualizer +^done +@end smallexample + +Suppose @code{SomeClass} is a visualizer class. A lambda expression +can be used to instantiate this class for a varobj: + +@smallexample +(gdb) +-var-set-visualizer V "lambda val: SomeClass()" +^done +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Data Manipulation +@section @sc{gdb/mi} Data Manipulation + +@cindex data manipulation, in @sc{gdb/mi} +@cindex @sc{gdb/mi}, data manipulation +This section describes the @sc{gdb/mi} commands that manipulate data: +examine memory and registers, evaluate expressions, etc. + +For details about what an addressable memory unit is, +@pxref{addressable memory unit}. + +@c REMOVED FROM THE INTERFACE. +@c @subheading -data-assign +@c Change the value of a program variable. Plenty of side effects. +@c @subsubheading GDB Command +@c set variable +@c @subsubheading Example +@c N.A. + +@findex -data-disassemble +@subheading The @code{-data-disassemble} Command + +@subsubheading Synopsis + +@smallexample + -data-disassemble + ( -s @var{start-addr} -e @var{end-addr} + | -a @var{addr} + | -f @var{filename} -l @var{linenum} [ -n @var{lines} ] ) + [ --opcodes @var{opcodes-mode} ] + [ --source ] + [ -- @var{mode} ] +@end smallexample + +@noindent +Where: + +@table @samp +@item @var{start-addr} +is the beginning address (or @code{$pc}) +@item @var{end-addr} +is the end address +@item @var{addr} +is an address anywhere within (or the name of) the function to +disassemble. If an address is specified, the whole function +surrounding that address will be disassembled. If a name is +specified, the whole function with that name will be disassembled. +@item @var{filename} +is the name of the file to disassemble +@item @var{linenum} +is the line number to disassemble around +@item @var{lines} +is the number of disassembly lines to be produced. If it is -1, +the whole function will be disassembled, in case no @var{end-addr} is +specified. If @var{end-addr} is specified as a non-zero value, and +@var{lines} is lower than the number of disassembly lines between +@var{start-addr} and @var{end-addr}, only @var{lines} lines are +displayed; if @var{lines} is higher than the number of lines between +@var{start-addr} and @var{end-addr}, only the lines up to @var{end-addr} +are displayed. +@item @var{opcodes-mode} +can only be used with @var{mode} 0, and should be one of the following: +@table @samp +@item none +no opcode information will be included in the result. + +@item bytes +opcodes will be included in the result, the opcodes will be formatted +as for @kbd{disassemble /b}. + +@item display +opcodes will be included in the result, the opcodes will be formatted +as for @kbd{disassemble /r}. +@end table +@item @var{mode} +the use of @var{mode} is deprecated in favour of using the +@code{--opcodes} and @code{--source} options. When no @var{mode} is +given, @var{mode} 0 will be assumed. However, the @var{mode} is still +available for backward compatibility. The @var{mode} should be one of: +@table @samp +@item 0 +@emph{disassembly only}, this is the default mode if no mode is +specified. + +@item 1 +@emph{mixed source and disassembly (deprecated)}, it is not possible +to recreate this mode using @code{--opcodes} and @code{--source} +options. + +@item 2 +@emph{disassembly with raw opcodes}, this mode is equivalent to using +@var{mode} 0 and passing @code{--opcodes bytes} to the command. + +@item 3 +@emph{mixed source and disassembly with raw opcodes (deprecated)}, it +is not possible to recreate this mode using @code{--opcodes} and +@code{--source} options. + +@item 4 +@emph{mixed source and disassembly}, this mode is equivalent to using +@var{mode} 0 and passing @code{--source} to the command. + +@item 5 +@emph{mixed source and disassembly with raw opcodes}, this mode is +equivalent to using @var{mode} 0 and passing @code{--opcodes bytes} +and @code{--source} to the command. +@end table +Modes 1 and 3 are deprecated. The output is ``source centric'' +which hasn't proved useful in practice. +@xref{Machine Code}, for a discussion of the difference between +@code{/m} and @code{/s} output of the @code{disassemble} command. +@end table + +The @code{--source} can only be used with @var{mode} 0. Passing this +option will include the source code in the disassembly result as if +@var{mode} 4 or 5 had been used. + +@subsubheading Result + +The result of the @code{-data-disassemble} command will be a list named +@samp{asm_insns}, the contents of this list depend on the options used +with the @code{-data-disassemble} command. + +For modes 0 and 2, and when the @code{--source} option is not used, the +@samp{asm_insns} list contains tuples with the following fields: + +@table @code +@item address +The address at which this instruction was disassembled. + +@item func-name +The name of the function this instruction is within. + +@item offset +The decimal offset in bytes from the start of @samp{func-name}. + +@item inst +The text disassembly for this @samp{address}. + +@item opcodes +This field is only present for modes 2, 3 and 5, or when the +@code{--opcodes} option @samp{bytes} or @samp{display} is used. This +contains the raw opcode bytes for the @samp{inst} field. + +When the @samp{--opcodes} option is not passed to +@code{-data-disassemble}, or the @samp{bytes} value is passed to +@samp{--opcodes}, then the bytes are formatted as a series of single +bytes, in hex, in ascending address order, with a single space between +each byte. This format is equivalent to the @samp{/b} option being +used with the @kbd{disassemble} command +(@pxref{disassemble,,@kbd{disassemble}}). + +When @samp{--opcodes} is passed the value @samp{display} then the bytes +are formatted in the natural instruction display order. This means +multiple bytes can be grouped together, and the bytes might be +byte-swapped. This format is equivalent to the @samp{/r} option being +used with the @kbd{disassemble} command. +@end table + +For modes 1, 3, 4 and 5, or when the @code{--source} option is used, the +@samp{asm_insns} list contains tuples named @samp{src_and_asm_line}, +each of which has the following fields: + +@table @code +@item line +The line number within @samp{file}. + +@item file +The file name from the compilation unit. This might be an absolute +file name or a relative file name depending on the compile command +used. + +@item fullname +Absolute file name of @samp{file}. It is converted to a canonical form +using the source file search path +(@pxref{Source Path, ,Specifying Source Directories}) +and after resolving all the symbolic links. + +If the source file is not found this field will contain the path as +present in the debug information. + +@item line_asm_insn +This is a list of tuples containing the disassembly for @samp{line} in +@samp{file}. The fields of each tuple are the same as for +@code{-data-disassemble} in @var{mode} 0 and 2, so @samp{address}, +@samp{func-name}, @samp{offset}, @samp{inst}, and optionally +@samp{opcodes}. + +@end table + +Note that whatever included in the @samp{inst} field, is not +manipulated directly by @sc{gdb/mi}, i.e., it is not possible to +adjust its format. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disassemble}. + +@subsubheading Example + +Disassemble from the current value of @code{$pc} to @code{$pc + 20}: + +@smallexample +(gdb) +-data-disassemble -s $pc -e "$pc + 20" -- 0 +^done, +asm_insns=[ +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107c8",func-name="main",offset="12", +inst="or %o2, 0x140, %o1\t! 0x11940 <_lib_version+8>"@}, +@{address="0x000107cc",func-name="main",offset="16", +inst="sethi %hi(0x11800), %o2"@}, +@{address="0x000107d0",func-name="main",offset="20", +inst="or %o2, 0x168, %o4\t! 0x11968 <_lib_version+48>"@}] +(gdb) +@end smallexample + +Disassemble the whole @code{main} function. Line 32 is part of +@code{main}. + +@smallexample +-data-disassemble -f basics.c -l 32 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}, +[@dots{}] +@{address="0x0001081c",func-name="main",offset="96",inst="ret "@}, +@{address="0x00010820",func-name="main",offset="100",inst="restore "@}] +(gdb) +@end smallexample + +Disassemble 3 instructions from the start of @code{main}: + +@smallexample +(gdb) +-data-disassemble -f basics.c -l 32 -n 3 -- 0 +^done,asm_insns=[ +@{address="0x000107bc",func-name="main",offset="0", +inst="save %sp, -112, %sp"@}, +@{address="0x000107c0",func-name="main",offset="4", +inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}] +(gdb) +@end smallexample + +Disassemble 3 instructions from the start of @code{main} in mixed mode: + +@smallexample +(gdb) +-data-disassemble -f basics.c -l 32 -n 3 -- 1 +^done,asm_insns=[ +src_and_asm_line=@{line="31", +file="../../../src/gdb/testsuite/gdb.mi/basics.c", +fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", +line_asm_insn=[@{address="0x000107bc", +func-name="main",offset="0",inst="save %sp, -112, %sp"@}]@}, +src_and_asm_line=@{line="32", +file="../../../src/gdb/testsuite/gdb.mi/basics.c", +fullname="/absolute/path/to/src/gdb/testsuite/gdb.mi/basics.c", +line_asm_insn=[@{address="0x000107c0", +func-name="main",offset="4",inst="mov 2, %o0"@}, +@{address="0x000107c4",func-name="main",offset="8", +inst="sethi %hi(0x11800), %o2"@}]@}] +(gdb) +@end smallexample + + +@findex -data-evaluate-expression +@subheading The @code{-data-evaluate-expression} Command + +@subsubheading Synopsis + +@smallexample + -data-evaluate-expression @var{expr} +@end smallexample + +Evaluate @var{expr} as an expression. The expression could contain an +inferior function call. The function call will execute synchronously. +If the expression contains spaces, it must be enclosed in double quotes. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{print}, @samp{output}, and +@samp{call}. In @code{gdbtk} only, there's a corresponding +@samp{gdb_eval} command. + +@subsubheading Example + +In the following example, the numbers that precede the commands are the +@dfn{tokens} described in @ref{GDB/MI Command Syntax, ,@sc{gdb/mi} +Command Syntax}. Notice how @sc{gdb/mi} returns the same tokens in its +output. + +@smallexample +211-data-evaluate-expression A +211^done,value="1" +(gdb) +311-data-evaluate-expression &A +311^done,value="0xefffeb7c" +(gdb) +411-data-evaluate-expression A+3 +411^done,value="4" +(gdb) +511-data-evaluate-expression "A + 3" +511^done,value="4" +(gdb) +@end smallexample + + +@findex -data-list-changed-registers +@subheading The @code{-data-list-changed-registers} Command + +@subsubheading Synopsis + +@smallexample + -data-list-changed-registers +@end smallexample + +Display a list of the registers that have changed. + +@subsubheading @value{GDBN} Command + +@value{GDBN} doesn't have a direct analog for this command; @code{gdbtk} +has the corresponding command @samp{gdb_changed_register_list}. + +@subsubheading Example + +On a PPC MBX board: + +@smallexample +(gdb) +-exec-continue +^running + +(gdb) +*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",frame=@{ +func="main",args=[],file="try.c",fullname="/home/foo/bar/try.c", +line="5",arch="powerpc"@} +(gdb) +-data-list-changed-registers +^done,changed-registers=["0","1","2","4","5","6","7","8","9", +"10","11","13","14","15","16","17","18","19","20","21","22","23", +"24","25","26","27","28","30","31","64","65","66","67","69"] +(gdb) +@end smallexample + + +@findex -data-list-register-names +@subheading The @code{-data-list-register-names} Command + +@subsubheading Synopsis + +@smallexample + -data-list-register-names [ ( @var{regno} )+ ] +@end smallexample + +Show a list of register names for the current target. If no arguments +are given, it shows a list of the names of all the registers. If +integer numbers are given as arguments, it will print a list of the +names of the registers corresponding to the arguments. To ensure +consistency between a register name and its number, the output list may +include empty register names. + +@subsubheading @value{GDBN} Command + +@value{GDBN} does not have a command which corresponds to +@samp{-data-list-register-names}. In @code{gdbtk} there is a +corresponding command @samp{gdb_regnames}. + +@subsubheading Example + +For the PPC MBX board: +@smallexample +(gdb) +-data-list-register-names +^done,register-names=["r0","r1","r2","r3","r4","r5","r6","r7", +"r8","r9","r10","r11","r12","r13","r14","r15","r16","r17","r18", +"r19","r20","r21","r22","r23","r24","r25","r26","r27","r28","r29", +"r30","r31","f0","f1","f2","f3","f4","f5","f6","f7","f8","f9", +"f10","f11","f12","f13","f14","f15","f16","f17","f18","f19","f20", +"f21","f22","f23","f24","f25","f26","f27","f28","f29","f30","f31", +"", "pc","ps","cr","lr","ctr","xer"] +(gdb) +-data-list-register-names 1 2 3 +^done,register-names=["r1","r2","r3"] +(gdb) +@end smallexample + +@findex -data-list-register-values +@subheading The @code{-data-list-register-values} Command + +@subsubheading Synopsis + +@smallexample + -data-list-register-values + [ @code{--skip-unavailable} ] @var{fmt} [ ( @var{regno} )*] +@end smallexample + +Display the registers' contents. The format according to which the +registers' contents are to be returned is given by @var{fmt}, followed +by an optional list of numbers specifying the registers to display. A +missing list of numbers indicates that the contents of all the +registers must be returned. The @code{--skip-unavailable} option +indicates that only the available registers are to be returned. + +Allowed formats for @var{fmt} are: + +@table @code +@item x +Hexadecimal +@item o +Octal +@item t +Binary +@item d +Decimal +@item r +Raw +@item N +Natural +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} commands are @samp{info reg}, @samp{info +all-reg}, and (in @code{gdbtk}) @samp{gdb_fetch_registers}. + +@subsubheading Example + +For a PPC MBX board (note: line breaks are for readability only, they +don't appear in the actual output): + +@smallexample +(gdb) +-data-list-register-values r 64 65 +^done,register-values=[@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x00029002"@}] +(gdb) +-data-list-register-values x +^done,register-values=[@{number="0",value="0xfe0043c8"@}, +@{number="1",value="0x3fff88"@},@{number="2",value="0xfffffffe"@}, +@{number="3",value="0x0"@},@{number="4",value="0xa"@}, +@{number="5",value="0x3fff68"@},@{number="6",value="0x3fff58"@}, +@{number="7",value="0xfe011e98"@},@{number="8",value="0x2"@}, +@{number="9",value="0xfa202820"@},@{number="10",value="0xfa202808"@}, +@{number="11",value="0x1"@},@{number="12",value="0x0"@}, +@{number="13",value="0x4544"@},@{number="14",value="0xffdfffff"@}, +@{number="15",value="0xffffffff"@},@{number="16",value="0xfffffeff"@}, +@{number="17",value="0xefffffed"@},@{number="18",value="0xfffffffe"@}, +@{number="19",value="0xffffffff"@},@{number="20",value="0xffffffff"@}, +@{number="21",value="0xffffffff"@},@{number="22",value="0xfffffff7"@}, +@{number="23",value="0xffffffff"@},@{number="24",value="0xffffffff"@}, +@{number="25",value="0xffffffff"@},@{number="26",value="0xfffffffb"@}, +@{number="27",value="0xffffffff"@},@{number="28",value="0xf7bfffff"@}, +@{number="29",value="0x0"@},@{number="30",value="0xfe010000"@}, +@{number="31",value="0x0"@},@{number="32",value="0x0"@}, +@{number="33",value="0x0"@},@{number="34",value="0x0"@}, +@{number="35",value="0x0"@},@{number="36",value="0x0"@}, +@{number="37",value="0x0"@},@{number="38",value="0x0"@}, +@{number="39",value="0x0"@},@{number="40",value="0x0"@}, +@{number="41",value="0x0"@},@{number="42",value="0x0"@}, +@{number="43",value="0x0"@},@{number="44",value="0x0"@}, +@{number="45",value="0x0"@},@{number="46",value="0x0"@}, +@{number="47",value="0x0"@},@{number="48",value="0x0"@}, +@{number="49",value="0x0"@},@{number="50",value="0x0"@}, +@{number="51",value="0x0"@},@{number="52",value="0x0"@}, +@{number="53",value="0x0"@},@{number="54",value="0x0"@}, +@{number="55",value="0x0"@},@{number="56",value="0x0"@}, +@{number="57",value="0x0"@},@{number="58",value="0x0"@}, +@{number="59",value="0x0"@},@{number="60",value="0x0"@}, +@{number="61",value="0x0"@},@{number="62",value="0x0"@}, +@{number="63",value="0x0"@},@{number="64",value="0xfe00a300"@}, +@{number="65",value="0x29002"@},@{number="66",value="0x202f04b5"@}, +@{number="67",value="0xfe0043b0"@},@{number="68",value="0xfe00b3e4"@}, +@{number="69",value="0x20002b03"@}] +(gdb) +@end smallexample + + +@findex -data-read-memory +@subheading The @code{-data-read-memory} Command + +This command is deprecated, use @code{-data-read-memory-bytes} instead. + +@subsubheading Synopsis + +@smallexample + -data-read-memory [ -o @var{byte-offset} ] + @var{address} @var{word-format} @var{word-size} + @var{nr-rows} @var{nr-cols} [ @var{aschar} ] +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first memory word to be +read. Complex expressions containing embedded white space should be +quoted using the C convention. + +@item @var{word-format} +The format to be used to print the memory words. The notation is the +same as for @value{GDBN}'s @code{print} command (@pxref{Output Formats, +,Output Formats}). + +@item @var{word-size} +The size of each memory word in bytes. + +@item @var{nr-rows} +The number of rows in the output table. + +@item @var{nr-cols} +The number of columns in the output table. + +@item @var{aschar} +If present, indicates that each row should include an @sc{ascii} dump. The +value of @var{aschar} is used as a padding character when a byte is not a +member of the printable @sc{ascii} character set (printable @sc{ascii} +characters are those whose code is between 32 and 126, inclusively). + +@item @var{byte-offset} +An offset to add to the @var{address} before fetching memory. +@end table + +This command displays memory contents as a table of @var{nr-rows} by +@var{nr-cols} words, each word being @var{word-size} bytes. In total, +@code{@var{nr-rows} * @var{nr-cols} * @var{word-size}} bytes are read +(returned as @samp{total-bytes}). Should less than the requested number +of bytes be returned by the target, the missing words are identified +using @samp{N/A}. The number of bytes read from the target is returned +in @samp{nr-bytes} and the starting address used to read memory in +@samp{addr}. + +The address of the next/previous row or page is available in +@samp{next-row} and @samp{prev-row}, @samp{next-page} and +@samp{prev-page}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{x}. @code{gdbtk} has +@samp{gdb_get_mem} memory read command. + +@subsubheading Example + +Read six bytes of memory starting at @code{bytes+6} but then offset by +@code{-6} bytes. Format as three rows of two columns. One byte per +word. Display each word in hex. + +@smallexample +(gdb) +9-data-read-memory -o -6 -- bytes+6 x 1 3 2 +9^done,addr="0x00001390",nr-bytes="6",total-bytes="6", +next-row="0x00001396",prev-row="0x0000138e",next-page="0x00001396", +prev-page="0x0000138a",memory=[ +@{addr="0x00001390",data=["0x00","0x01"]@}, +@{addr="0x00001392",data=["0x02","0x03"]@}, +@{addr="0x00001394",data=["0x04","0x05"]@}] +(gdb) +@end smallexample + +Read two bytes of memory starting at address @code{shorts + 64} and +display as a single word formatted in decimal. + +@smallexample +(gdb) +5-data-read-memory shorts+64 d 2 1 1 +5^done,addr="0x00001510",nr-bytes="2",total-bytes="2", +next-row="0x00001512",prev-row="0x0000150e", +next-page="0x00001512",prev-page="0x0000150e",memory=[ +@{addr="0x00001510",data=["128"]@}] +(gdb) +@end smallexample + +Read thirty two bytes of memory starting at @code{bytes+16} and format +as eight rows of four columns. Include a string encoding with @samp{x} +used as the non-printable character. + +@smallexample +(gdb) +4-data-read-memory bytes+16 x 1 8 4 x +4^done,addr="0x000013a0",nr-bytes="32",total-bytes="32", +next-row="0x000013c0",prev-row="0x0000139c", +next-page="0x000013c0",prev-page="0x00001380",memory=[ +@{addr="0x000013a0",data=["0x10","0x11","0x12","0x13"],ascii="xxxx"@}, +@{addr="0x000013a4",data=["0x14","0x15","0x16","0x17"],ascii="xxxx"@}, +@{addr="0x000013a8",data=["0x18","0x19","0x1a","0x1b"],ascii="xxxx"@}, +@{addr="0x000013ac",data=["0x1c","0x1d","0x1e","0x1f"],ascii="xxxx"@}, +@{addr="0x000013b0",data=["0x20","0x21","0x22","0x23"],ascii=" !\"#"@}, +@{addr="0x000013b4",data=["0x24","0x25","0x26","0x27"],ascii="$%&'"@}, +@{addr="0x000013b8",data=["0x28","0x29","0x2a","0x2b"],ascii="()*+"@}, +@{addr="0x000013bc",data=["0x2c","0x2d","0x2e","0x2f"],ascii=",-./"@}] +(gdb) +@end smallexample + +@findex -data-read-memory-bytes +@subheading The @code{-data-read-memory-bytes} Command + +@subsubheading Synopsis + +@smallexample + -data-read-memory-bytes [ -o @var{offset} ] + @var{address} @var{count} +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first addressable memory unit +to be read. Complex expressions containing embedded white space should be +quoted using the C convention. + +@item @var{count} +The number of addressable memory units to read. This should be an integer +literal. + +@item @var{offset} +The offset relative to @var{address} at which to start reading. This +should be an integer literal. This option is provided so that a frontend +is not required to first evaluate address and then perform address +arithmetic itself. + +@end table + +This command attempts to read all accessible memory regions in the +specified range. First, all regions marked as unreadable in the memory +map (if one is defined) will be skipped. @xref{Memory Region +Attributes}. Second, @value{GDBN} will attempt to read the remaining +regions. For each one, if reading full region results in an errors, +@value{GDBN} will try to read a subset of the region. + +In general, every single memory unit in the region may be readable or not, +and the only way to read every readable unit is to try a read at +every address, which is not practical. Therefore, @value{GDBN} will +attempt to read all accessible memory units at either beginning or the end +of the region, using a binary division scheme. This heuristic works +well for reading across a memory map boundary. Note that if a region +has a readable range that is neither at the beginning or the end, +@value{GDBN} will not read it. + +The result record (@pxref{GDB/MI Result Records}) that is output of +the command includes a field named @samp{memory} whose content is a +list of tuples. Each tuple represent a successfully read memory block +and has the following fields: + +@table @code +@item begin +The start address of the memory block, as hexadecimal literal. + +@item end +The end address of the memory block, as hexadecimal literal. + +@item offset +The offset of the memory block, as hexadecimal literal, relative to +the start address passed to @code{-data-read-memory-bytes}. + +@item contents +The contents of the memory block, in hex. + +@end table + + + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{x}. + +@subsubheading Example + +@smallexample +(gdb) +-data-read-memory-bytes &a 10 +^done,memory=[@{begin="0xbffff154",offset="0x00000000", + end="0xbffff15e", + contents="01000000020000000300"@}] +(gdb) +@end smallexample + + +@findex -data-write-memory-bytes +@subheading The @code{-data-write-memory-bytes} Command + +@subsubheading Synopsis + +@smallexample + -data-write-memory-bytes @var{address} @var{contents} + -data-write-memory-bytes @var{address} @var{contents} @r{[}@var{count}@r{]} +@end smallexample + +@noindent +where: + +@table @samp +@item @var{address} +An expression specifying the address of the first addressable memory unit +to be written. Complex expressions containing embedded white space should +be quoted using the C convention. + +@item @var{contents} +The hex-encoded data to write. It is an error if @var{contents} does +not represent an integral number of addressable memory units. + +@item @var{count} +Optional argument indicating the number of addressable memory units to be +written. If @var{count} is greater than @var{contents}' length, +@value{GDBN} will repeatedly write @var{contents} until it fills +@var{count} memory units. + +@end table + +@subsubheading @value{GDBN} Command + +There's no corresponding @value{GDBN} command. + +@subsubheading Example + +@smallexample +(gdb) +-data-write-memory-bytes &a "aabbccdd" +^done +(gdb) +@end smallexample + +@smallexample +(gdb) +-data-write-memory-bytes &a "aabbccdd" 16e +^done +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Tracepoint Commands +@section @sc{gdb/mi} Tracepoint Commands + +The commands defined in this section implement MI support for +tracepoints. For detailed introduction, see @ref{Tracepoints}. + +@findex -trace-find +@subheading The @code{-trace-find} Command + +@subsubheading Synopsis + +@smallexample + -trace-find @var{mode} [@var{parameters}@dots{}] +@end smallexample + +Find a trace frame using criteria defined by @var{mode} and +@var{parameters}. The following table lists permissible +modes and their parameters. For details of operation, see @ref{tfind}. + +@table @samp + +@item none +No parameters are required. Stops examining trace frames. + +@item frame-number +An integer is required as parameter. Selects tracepoint frame with +that index. + +@item tracepoint-number +An integer is required as parameter. Finds next +trace frame that corresponds to tracepoint with the specified number. + +@item pc +An address is required as parameter. Finds +next trace frame that corresponds to any tracepoint at the specified +address. + +@item pc-inside-range +Two addresses are required as parameters. Finds next trace +frame that corresponds to a tracepoint at an address inside the +specified range. Both bounds are considered to be inside the range. + +@item pc-outside-range +Two addresses are required as parameters. Finds +next trace frame that corresponds to a tracepoint at an address outside +the specified range. Both bounds are considered to be inside the range. + +@item line +Location specification is required as parameter. @xref{Location Specifications}. +Finds next trace frame that corresponds to a tracepoint at +the specified location. + +@end table + +If @samp{none} was passed as @var{mode}, the response does not +have fields. Otherwise, the response may have the following fields: + +@table @samp +@item found +This field has either @samp{0} or @samp{1} as the value, depending +on whether a matching tracepoint was found. + +@item traceframe +The index of the found traceframe. This field is present iff +the @samp{found} field has value of @samp{1}. + +@item tracepoint +The index of the found tracepoint. This field is present iff +the @samp{found} field has value of @samp{1}. + +@item frame +The information about the frame corresponding to the found trace +frame. This field is present only if a trace frame was found. +@xref{GDB/MI Frame Information}, for description of this field. + +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tfind}. + +@findex -trace-define-variable +@subheading The @code{-trace-define-variable} Command + +@subsubheading Synopsis + +@smallexample + -trace-define-variable @var{name} [ @var{value} ] +@end smallexample + +Create trace variable @var{name} if it does not exist. If +@var{value} is specified, sets the initial value of the specified +trace variable to that value. Note that the @var{name} should start +with the @samp{$} character. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tvariable}. + +@findex -trace-frame-collected +@subheading The @code{-trace-frame-collected} Command + +@subsubheading Synopsis + +@smallexample + -trace-frame-collected + [--var-print-values @var{var_pval}] + [--comp-print-values @var{comp_pval}] + [--registers-format @var{regformat}] + [--memory-contents] +@end smallexample + +This command returns the set of collected objects, register names, +trace state variable names, memory ranges and computed expressions +that have been collected at a particular trace frame. The optional +parameters to the command affect the output format in different ways. +See the output description table below for more details. + +The reported names can be used in the normal manner to create +varobjs and inspect the objects themselves. The items returned by +this command are categorized so that it is clear which is a variable, +which is a register, which is a trace state variable, which is a +memory range and which is a computed expression. + +For instance, if the actions were +@smallexample +collect myVar, myArray[myIndex], myObj.field, myPtr->field, myCount + 2 +collect *(int*)0xaf02bef0@@40 +@end smallexample + +@noindent +the object collected in its entirety would be @code{myVar}. The +object @code{myArray} would be partially collected, because only the +element at index @code{myIndex} would be collected. The remaining +objects would be computed expressions. + +An example output would be: + +@smallexample +(gdb) +-trace-frame-collected +^done, + explicit-variables=[@{name="myVar",value="1"@}], + computed-expressions=[@{name="myArray[myIndex]",value="0"@}, + @{name="myObj.field",value="0"@}, + @{name="myPtr->field",value="1"@}, + @{name="myCount + 2",value="3"@}, + @{name="$tvar1 + 1",value="43970027"@}], + registers=[@{number="0",value="0x7fe2c6e79ec8"@}, + @{number="1",value="0x0"@}, + @{number="2",value="0x4"@}, + ... + @{number="125",value="0x0"@}], + tvars=[@{name="$tvar1",current="43970026"@}], + memory=[@{address="0x0000000000602264",length="4"@}, + @{address="0x0000000000615bc0",length="4"@}] +(gdb) +@end smallexample + +Where: + +@table @code +@item explicit-variables +The set of objects that have been collected in their entirety (as +opposed to collecting just a few elements of an array or a few struct +members). For each object, its name and value are printed. +The @code{--var-print-values} option affects how or whether the value +field is output. If @var{var_pval} is 0, then print only the names; +if it is 1, print also their values; and if it is 2, print the name, +type and value for simple data types, and the name and type for +arrays, structures and unions. + +@item computed-expressions +The set of computed expressions that have been collected at the +current trace frame. The @code{--comp-print-values} option affects +this set like the @code{--var-print-values} option affects the +@code{explicit-variables} set. See above. + +@item registers +The registers that have been collected at the current trace frame. +For each register collected, the name and current value are returned. +The value is formatted according to the @code{--registers-format} +option. See the @command{-data-list-register-values} command for a +list of the allowed formats. The default is @samp{x}. + +@item tvars +The trace state variables that have been collected at the current +trace frame. For each trace state variable collected, the name and +current value are returned. + +@item memory +The set of memory ranges that have been collected at the current trace +frame. Its content is a list of tuples. Each tuple represents a +collected memory range and has the following fields: + +@table @code +@item address +The start address of the memory range, as hexadecimal literal. + +@item length +The length of the memory range, as decimal literal. + +@item contents +The contents of the memory block, in hex. This field is only present +if the @code{--memory-contents} option is specified. + +@end table + +@end table + +@subsubheading @value{GDBN} Command + +There is no corresponding @value{GDBN} command. + +@subsubheading Example + +@findex -trace-list-variables +@subheading The @code{-trace-list-variables} Command + +@subsubheading Synopsis + +@smallexample + -trace-list-variables +@end smallexample + +Return a table of all defined trace variables. Each element of the +table has the following fields: + +@table @samp +@item name +The name of the trace variable. This field is always present. + +@item initial +The initial value. This is a 64-bit signed integer. This +field is always present. + +@item current +The value the trace variable has at the moment. This is a 64-bit +signed integer. This field is absent iff current value is +not defined, for example if the trace was never run, or is +presently running. + +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tvariables}. + +@subsubheading Example + +@smallexample +(gdb) +-trace-list-variables +^done,trace-variables=@{nr_rows="1",nr_cols="3", +hdr=[@{width="15",alignment="-1",col_name="name",colhdr="Name"@}, + @{width="11",alignment="-1",col_name="initial",colhdr="Initial"@}, + @{width="11",alignment="-1",col_name="current",colhdr="Current"@}], +body=[variable=@{name="$trace_timestamp",initial="0"@} + variable=@{name="$foo",initial="10",current="15"@}]@} +(gdb) +@end smallexample + +@findex -trace-save +@subheading The @code{-trace-save} Command + +@subsubheading Synopsis + +@smallexample + -trace-save [ -r ] [ -ctf ] @var{filename} +@end smallexample + +Saves the collected trace data to @var{filename}. Without the +@samp{-r} option, the data is downloaded from the target and saved +in a local file. With the @samp{-r} option the target is asked +to perform the save. + +By default, this command will save the trace in the tfile format. You can +supply the optional @samp{-ctf} argument to save it the CTF format. See +@ref{Trace Files} for more information about CTF. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tsave}. + + +@findex -trace-start +@subheading The @code{-trace-start} Command + +@subsubheading Synopsis + +@smallexample + -trace-start +@end smallexample + +Starts a tracing experiment. The result of this command does not +have any fields. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tstart}. + +@findex -trace-status +@subheading The @code{-trace-status} Command + +@subsubheading Synopsis + +@smallexample + -trace-status +@end smallexample + +Obtains the status of a tracing experiment. The result may include +the following fields: + +@table @samp + +@item supported +May have a value of either @samp{0}, when no tracing operations are +supported, @samp{1}, when all tracing operations are supported, or +@samp{file} when examining trace file. In the latter case, examining +of trace frame is possible but new tracing experiment cannot be +started. This field is always present. + +@item running +May have a value of either @samp{0} or @samp{1} depending on whether +tracing experiment is in progress on target. This field is present +if @samp{supported} field is not @samp{0}. + +@item stop-reason +Report the reason why the tracing was stopped last time. This field +may be absent iff tracing was never stopped on target yet. The +value of @samp{request} means the tracing was stopped as result of +the @code{-trace-stop} command. The value of @samp{overflow} means +the tracing buffer is full. The value of @samp{disconnection} means +tracing was automatically stopped when @value{GDBN} has disconnected. +The value of @samp{passcount} means tracing was stopped when a +tracepoint was passed a maximal number of times for that tracepoint. +This field is present if @samp{supported} field is not @samp{0}. + +@item stopping-tracepoint +The number of tracepoint whose passcount as exceeded. This field is +present iff the @samp{stop-reason} field has the value of +@samp{passcount}. + +@item frames +@itemx frames-created +The @samp{frames} field is a count of the total number of trace frames +in the trace buffer, while @samp{frames-created} is the total created +during the run, including ones that were discarded, such as when a +circular trace buffer filled up. Both fields are optional. + +@item buffer-size +@itemx buffer-free +These fields tell the current size of the tracing buffer and the +remaining space. These fields are optional. + +@item circular +The value of the circular trace buffer flag. @code{1} means that the +trace buffer is circular and old trace frames will be discarded if +necessary to make room, @code{0} means that the trace buffer is linear +and may fill up. + +@item disconnected +The value of the disconnected tracing flag. @code{1} means that +tracing will continue after @value{GDBN} disconnects, @code{0} means +that the trace run will stop. + +@item trace-file +The filename of the trace file being examined. This field is +optional, and only present when examining a trace file. + +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tstatus}. + +@findex -trace-stop +@subheading The @code{-trace-stop} Command + +@subsubheading Synopsis + +@smallexample + -trace-stop +@end smallexample + +Stops a tracing experiment. The result of this command has the same +fields as @code{-trace-status}, except that the @samp{supported} and +@samp{running} fields are not output. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{tstop}. + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Symbol Query +@section @sc{gdb/mi} Symbol Query Commands + + +@ignore +@findex -symbol-info-address +@subheading The @code{-symbol-info-address} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-address @var{symbol} +@end smallexample + +Describe where @var{symbol} is stored. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info address}. + +@subsubheading Example +N.A. + + +@findex -symbol-info-file +@subheading The @code{-symbol-info-file} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-file +@end smallexample + +Show the file for the symbol. + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. @code{gdbtk} has +@samp{gdb_find_file}. + +@subsubheading Example +N.A. +@end ignore + +@findex -symbol-info-functions +@anchor{-symbol-info-functions} +@subheading The @code{-symbol-info-functions} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-functions [--include-nondebug] + [--type @var{type_regexp}] + [--name @var{name_regexp}] + [--max-results @var{limit}] +@end smallexample + +@noindent +Return a list containing the names and types for all global functions +taken from the debug information. The functions are grouped by source +file, and shown with the line number on which each function is +defined. + +The @code{--include-nondebug} option causes the output to include +code symbols from the symbol table. + +The options @code{--type} and @code{--name} allow the symbols returned +to be filtered based on either the name of the function, or the type +signature of the function. + +The option @code{--max-results} restricts the command to return no +more than @var{limit} results. If exactly @var{limit} results are +returned then there might be additional results available if a higher +limit is used. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info functions}. + +@subsubheading Example +@smallexample +@group +(gdb) +-symbol-info-functions +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="36", name="f4", type="void (int *)", + description="void f4(int *);"@}, + @{line="42", name="main", type="int ()", + description="int main();"@}, + @{line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="33", name="f2", type="float (another_float_t)", + description="float f2(another_float_t);"@}, + @{line="39", name="f3", type="int (another_int_t)", + description="int f3(another_int_t);"@}, + @{line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-functions --name f1 +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-functions --type void +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="36", name="f4", type="void (int *)", + description="void f4(int *);"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-functions --include-nondebug +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="36", name="f4", type="void (int *)", + description="void f4(int *);"@}, + @{line="42", name="main", type="int ()", + description="int main();"@}, + @{line="30", name="f1", type="my_int_t (int, int)", + description="static my_int_t f1(int, int);"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="33", name="f2", type="float (another_float_t)", + description="float f2(another_float_t);"@}, + @{line="39", name="f3", type="int (another_int_t)", + description="int f3(another_int_t);"@}, + @{line="27", name="f1", type="another_float_t (int)", + description="static another_float_t f1(int);"@}]@}], + nondebug= + [@{address="0x0000000000400398",name="_init"@}, + @{address="0x00000000004003b0",name="_start"@}, + ... + ]@} +@end group +@end smallexample + +@findex -symbol-info-module-functions +@anchor{-symbol-info-module-functions} +@subheading The @code{-symbol-info-module-functions} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-module-functions [--module @var{module_regexp}] + [--name @var{name_regexp}] + [--type @var{type_regexp}] +@end smallexample + +@noindent +Return a list containing the names of all known functions within all +know Fortran modules. The functions are grouped by source file and +containing module, and shown with the line number on which each +function is defined. + +The option @code{--module} only returns results for modules matching +@var{module_regexp}. The option @code{--name} only returns functions +whose name matches @var{name_regexp}, and @code{--type} only returns +functions whose type matches @var{type_regexp}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info module functions}. + +@subsubheading Example + +@smallexample +@group +(gdb) +-symbol-info-module-functions +^done,symbols= + [@{module="mod1", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="21",name="mod1::check_all",type="void (void)", + description="void mod1::check_all(void);"@}]@}]@}, + @{module="mod2", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="30",name="mod2::check_var_i",type="void (void)", + description="void mod2::check_var_i(void);"@}]@}]@}, + @{module="mod3", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="21",name="mod3::check_all",type="void (void)", + description="void mod3::check_all(void);"@}, + @{line="27",name="mod3::check_mod2",type="void (void)", + description="void mod3::check_mod2(void);"@}]@}]@}, + @{module="modmany", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="35",name="modmany::check_some",type="void (void)", + description="void modmany::check_some(void);"@}]@}]@}, + @{module="moduse", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="44",name="moduse::check_all",type="void (void)", + description="void moduse::check_all(void);"@}, + @{line="49",name="moduse::check_var_x",type="void (void)", + description="void moduse::check_var_x(void);"@}]@}]@}] +@end group +@end smallexample + +@findex -symbol-info-module-variables +@anchor{-symbol-info-module-variables} +@subheading The @code{-symbol-info-module-variables} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-module-variables [--module @var{module_regexp}] + [--name @var{name_regexp}] + [--type @var{type_regexp}] +@end smallexample + +@noindent +Return a list containing the names of all known variables within all +know Fortran modules. The variables are grouped by source file and +containing module, and shown with the line number on which each +variable is defined. + +The option @code{--module} only returns results for modules matching +@var{module_regexp}. The option @code{--name} only returns variables +whose name matches @var{name_regexp}, and @code{--type} only returns +variables whose type matches @var{type_regexp}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info module variables}. + +@subsubheading Example + +@smallexample +@group +(gdb) +-symbol-info-module-variables +^done,symbols= + [@{module="mod1", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="18",name="mod1::var_const",type="integer(kind=4)", + description="integer(kind=4) mod1::var_const;"@}, + @{line="17",name="mod1::var_i",type="integer(kind=4)", + description="integer(kind=4) mod1::var_i;"@}]@}]@}, + @{module="mod2", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="28",name="mod2::var_i",type="integer(kind=4)", + description="integer(kind=4) mod2::var_i;"@}]@}]@}, + @{module="mod3", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="18",name="mod3::mod1",type="integer(kind=4)", + description="integer(kind=4) mod3::mod1;"@}, + @{line="17",name="mod3::mod2",type="integer(kind=4)", + description="integer(kind=4) mod3::mod2;"@}, + @{line="19",name="mod3::var_i",type="integer(kind=4)", + description="integer(kind=4) mod3::var_i;"@}]@}]@}, + @{module="modmany", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="33",name="modmany::var_a",type="integer(kind=4)", + description="integer(kind=4) modmany::var_a;"@}, + @{line="33",name="modmany::var_b",type="integer(kind=4)", + description="integer(kind=4) modmany::var_b;"@}, + @{line="33",name="modmany::var_c",type="integer(kind=4)", + description="integer(kind=4) modmany::var_c;"@}, + @{line="33",name="modmany::var_i",type="integer(kind=4)", + description="integer(kind=4) modmany::var_i;"@}]@}]@}, + @{module="moduse", + files=[@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="42",name="moduse::var_x",type="integer(kind=4)", + description="integer(kind=4) moduse::var_x;"@}, + @{line="42",name="moduse::var_y",type="integer(kind=4)", + description="integer(kind=4) moduse::var_y;"@}]@}]@}] +@end group +@end smallexample + +@findex -symbol-info-modules +@anchor{-symbol-info-modules} +@subheading The @code{-symbol-info-modules} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-modules [--name @var{name_regexp}] + [--max-results @var{limit}] + +@end smallexample + +@noindent +Return a list containing the names of all known Fortran modules. The +modules are grouped by source file, and shown with the line number on +which each modules is defined. + +The option @code{--name} allows the modules returned to be filtered +based the name of the module. + +The option @code{--max-results} restricts the command to return no +more than @var{limit} results. If exactly @var{limit} results are +returned then there might be additional results available if a higher +limit is used. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info modules}. + +@subsubheading Example +@smallexample +@group +(gdb) +-symbol-info-modules +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="16",name="mod1"@}, + @{line="22",name="mod2"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="16",name="mod3"@}, + @{line="22",name="modmany"@}, + @{line="26",name="moduse"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-modules --name mod[123] +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules-2.f90", + symbols=[@{line="16",name="mod1"@}, + @{line="22",name="mod2"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + fullname="/project/gdb/testsuite/gdb.mi/mi-fortran-modules.f90", + symbols=[@{line="16",name="mod3"@}]@}]@} +@end group +@end smallexample + +@findex -symbol-info-types +@anchor{-symbol-info-types} +@subheading The @code{-symbol-info-types} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-types [--name @var{name_regexp}] + [--max-results @var{limit}] + +@end smallexample + +@noindent +Return a list of all defined types. The types are grouped by source +file, and shown with the line number on which each user defined type +is defined. Some base types are not defined in the source code but +are added to the debug information by the compiler, for example +@code{int}, @code{float}, etc.; these types do not have an associated +line number. + +The option @code{--name} allows the list of types returned to be +filtered by name. + +The option @code{--max-results} restricts the command to return no +more than @var{limit} results. If exactly @var{limit} results are +returned then there might be additional results available if a higher +limit is used. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info types}. + +@subsubheading Example +@smallexample +@group +(gdb) +-symbol-info-types +^done,symbols= + @{debug= + [@{filename="gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{name="float"@}, + @{name="int"@}, + @{line="27",name="typedef int my_int_t;"@}]@}, + @{filename="gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="24",name="typedef float another_float_t;"@}, + @{line="23",name="typedef int another_int_t;"@}, + @{name="float"@}, + @{name="int"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-types --name _int_ +^done,symbols= + @{debug= + [@{filename="gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="27",name="typedef int my_int_t;"@}]@}, + @{filename="gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="23",name="typedef int another_int_t;"@}]@}]@} +@end group +@end smallexample + +@findex -symbol-info-variables +@anchor{-symbol-info-variables} +@subheading The @code{-symbol-info-variables} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-variables [--include-nondebug] + [--type @var{type_regexp}] + [--name @var{name_regexp}] + [--max-results @var{limit}] + +@end smallexample + +@noindent +Return a list containing the names and types for all global variables +taken from the debug information. The variables are grouped by source +file, and shown with the line number on which each variable is +defined. + +The @code{--include-nondebug} option causes the output to include +data symbols from the symbol table. + +The options @code{--type} and @code{--name} allow the symbols returned +to be filtered based on either the name of the variable, or the type +of the variable. + +The option @code{--max-results} restricts the command to return no +more than @var{limit} results. If exactly @var{limit} results are +returned then there might be additional results available if a higher +limit is used. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info variables}. + +@subsubheading Example +@smallexample +@group +(gdb) +-symbol-info-variables +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="25",name="global_f1",type="float", + description="static float global_f1;"@}, + @{line="24",name="global_i1",type="int", + description="static int global_i1;"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="21",name="global_f2",type="int", + description="int global_f2;"@}, + @{line="20",name="global_i2",type="int", + description="int global_i2;"@}, + @{line="19",name="global_f1",type="float", + description="static float global_f1;"@}, + @{line="18",name="global_i1",type="int", + description="static int global_i1;"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-variables --name f1 +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="25",name="global_f1",type="float", + description="static float global_f1;"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="19",name="global_f1",type="float", + description="static float global_f1;"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-variables --type float +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="25",name="global_f1",type="float", + description="static float global_f1;"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="19",name="global_f1",type="float", + description="static float global_f1;"@}]@}]@} +@end group +@group +(gdb) +-symbol-info-variables --include-nondebug +^done,symbols= + @{debug= + [@{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-1.c", + symbols=[@{line="25",name="global_f1",type="float", + description="static float global_f1;"@}, + @{line="24",name="global_i1",type="int", + description="static int global_i1;"@}]@}, + @{filename="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + fullname="/project/gdb/testsuite/gdb.mi/mi-sym-info-2.c", + symbols=[@{line="21",name="global_f2",type="int", + description="int global_f2;"@}, + @{line="20",name="global_i2",type="int", + description="int global_i2;"@}, + @{line="19",name="global_f1",type="float", + description="static float global_f1;"@}, + @{line="18",name="global_i1",type="int", + description="static int global_i1;"@}]@}], + nondebug= + [@{address="0x00000000004005d0",name="_IO_stdin_used"@}, + @{address="0x00000000004005d8",name="__dso_handle"@} + ... + ]@} +@end group +@end smallexample + +@ignore +@findex -symbol-info-line +@subheading The @code{-symbol-info-line} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-line +@end smallexample + +Show the core addresses of the code for a source line. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info line}. +@code{gdbtk} has the @samp{gdb_get_line} and @samp{gdb_get_file} commands. + +@subsubheading Example +N.A. + + +@findex -symbol-info-symbol +@subheading The @code{-symbol-info-symbol} Command + +@subsubheading Synopsis + +@smallexample + -symbol-info-symbol @var{addr} +@end smallexample + +Describe what symbol is at location @var{addr}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info symbol}. + +@subsubheading Example +N.A. + + +@findex -symbol-list-functions +@subheading The @code{-symbol-list-functions} Command + +@subsubheading Synopsis + +@smallexample + -symbol-list-functions +@end smallexample + +List the functions in the executable. + +@subsubheading @value{GDBN} Command + +@samp{info functions} in @value{GDBN}, @samp{gdb_listfunc} and +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. +@end ignore + + +@findex -symbol-list-lines +@subheading The @code{-symbol-list-lines} Command + +@subsubheading Synopsis + +@smallexample + -symbol-list-lines @var{filename} +@end smallexample + +Print the list of lines that contain code and their associated program +addresses for the given source filename. The entries are sorted in +ascending PC order. + +@subsubheading @value{GDBN} Command + +There is no corresponding @value{GDBN} command. + +@subsubheading Example +@smallexample +(gdb) +-symbol-list-lines basics.c +^done,lines=[@{pc="0x08048554",line="7"@},@{pc="0x0804855a",line="8"@}] +(gdb) +@end smallexample + + +@ignore +@findex -symbol-list-types +@subheading The @code{-symbol-list-types} Command + +@subsubheading Synopsis + +@smallexample + -symbol-list-types +@end smallexample + +List all the type names. + +@subsubheading @value{GDBN} Command + +The corresponding commands are @samp{info types} in @value{GDBN}, +@samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@findex -symbol-list-variables +@subheading The @code{-symbol-list-variables} Command + +@subsubheading Synopsis + +@smallexample + -symbol-list-variables +@end smallexample + +List all the global and static variable names. + +@subsubheading @value{GDBN} Command + +@samp{info variables} in @value{GDBN}, @samp{gdb_search} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@findex -symbol-locate +@subheading The @code{-symbol-locate} Command + +@subsubheading Synopsis + +@smallexample + -symbol-locate +@end smallexample + +@subsubheading @value{GDBN} Command + +@samp{gdb_loc} in @code{gdbtk}. + +@subsubheading Example +N.A. + + +@findex -symbol-type +@subheading The @code{-symbol-type} Command + +@subsubheading Synopsis + +@smallexample + -symbol-type @var{variable} +@end smallexample + +Show type of @var{variable}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{ptype}, @code{gdbtk} has +@samp{gdb_obj_variable}. + +@subsubheading Example +N.A. +@end ignore + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI File Commands +@section @sc{gdb/mi} File Commands + +This section describes the GDB/MI commands to specify executable file names +and to read in and obtain symbol table information. + +@findex -file-exec-and-symbols +@subheading The @code{-file-exec-and-symbols} Command + +@subsubheading Synopsis + +@smallexample + -file-exec-and-symbols @var{file} +@end smallexample + +Specify the executable file to be debugged. This file is the one from +which the symbol table is also read. If no file is specified, the +command clears the executable and symbol information. If breakpoints +are set when using this command with no arguments, @value{GDBN} will produce +error messages. Otherwise, no output is produced, except a completion +notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{file}. + +@subsubheading Example + +@smallexample +(gdb) +-file-exec-and-symbols /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(gdb) +@end smallexample + + +@findex -file-exec-file +@subheading The @code{-file-exec-file} Command + +@subsubheading Synopsis + +@smallexample + -file-exec-file @var{file} +@end smallexample + +Specify the executable file to be debugged. Unlike +@samp{-file-exec-and-symbols}, the symbol table is @emph{not} read +from this file. If used without argument, @value{GDBN} clears the information +about the executable file. No output is produced, except a completion +notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{exec-file}. + +@subsubheading Example + +@smallexample +(gdb) +-file-exec-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(gdb) +@end smallexample + + +@ignore +@findex -file-list-exec-sections +@subheading The @code{-file-list-exec-sections} Command + +@subsubheading Synopsis + +@smallexample + -file-list-exec-sections +@end smallexample + +List the sections of the current executable file. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} command @samp{info file} shows, among the rest, the same +information as this command. @code{gdbtk} has a corresponding command +@samp{gdb_load_info}. + +@subsubheading Example +N.A. +@end ignore + + +@findex -file-list-exec-source-file +@subheading The @code{-file-list-exec-source-file} Command + +@subsubheading Synopsis + +@smallexample + -file-list-exec-source-file +@end smallexample + +List the line number, the current source file, and the absolute path +to the current source file for the current executable. The macro +information field has a value of @samp{1} or @samp{0} depending on +whether or not the file includes preprocessor macro information. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{info source} + +@subsubheading Example + +@smallexample +(gdb) +123-file-list-exec-source-file +123^done,line="1",file="foo.c",fullname="/home/bar/foo.c,macro-info="1" +(gdb) +@end smallexample + + +@findex -file-list-exec-source-files +@subheading The @code{-file-list-exec-source-files} Command +@kindex info sources + +@subsubheading Synopsis + +@smallexample + -file-list-exec-source-files @r{[} @var{--group-by-objfile} @r{]} + @r{[} @var{--dirname} @r{|} @var{--basename} @r{]} + @r{[} -- @r{]} + @r{[} @var{regexp} @r{]} +@end smallexample + +This command returns information about the source files @value{GDBN} +knows about, it will output both the filename and fullname (absolute +file name) of a source file, though the fullname can be elided if this +information is not known to @value{GDBN}. + +With no arguments this command returns a list of source files. Each +source file is represented by a tuple with the fields; @var{file}, +@var{fullname}, and @var{debug-fully-read}. The @var{file} is the +display name for the file, while @var{fullname} is the absolute name +of the file. The @var{fullname} field can be elided if the absolute +name of the source file can't be computed. The field +@var{debug-fully-read} will be a string, either @code{true} or +@code{false}. When @code{true}, this indicates the full debug +information for the compilation unit describing this file has been +read in. When @code{false}, the full debug information has not yet +been read in. While reading in the full debug information it is +possible that @value{GDBN} could become aware of additional source +files. + +The optional @var{regexp} can be used to filter the list of source +files returned. The @var{regexp} will be matched against the full +source file name. The matching is case-sensitive, except on operating +systems that have case-insensitive filesystem (e.g., +MS-Windows). @samp{--} can be used before @var{regexp} to prevent +@value{GDBN} interpreting @var{regexp} as a command option (e.g.@: if +@var{regexp} starts with @samp{-}). + +If @code{--dirname} is provided, then @var{regexp} is matched only +against the directory name of each source file. If @code{--basename} +is provided, then @var{regexp} is matched against the basename of each +source file. Only one of @code{--dirname} or @code{--basename} may be +given, and if either is given then @var{regexp} is required. + +If @code{--group-by-objfile} is used then the format of the results is +changed. The results will now be a list of tuples, with each tuple +representing an object file (executable or shared library) loaded into +@value{GDBN}. The fields of these tuples are; @var{filename}, +@var{debug-info}, and @var{sources}. The @var{filename} is the +absolute name of the object file, @var{debug-info} is a string with +one of the following values: + +@table @code +@item none +This object file has no debug information. +@item partially-read +This object file has debug information, but it is not fully read in +yet. When it is read in later, GDB might become aware of additional +source files. +@item fully-read +This object file has debug information, and this information is fully +read into GDB. The list of source files is complete. +@end table + +The @var{sources} is a list or tuples, with each tuple describing a +single source file with the same fields as described previously. The +@var{sources} list can be empty for object files that have no debug +information. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{info sources}. +@code{gdbtk} has an analogous command @samp{gdb_listfiles}. + +@subsubheading Example +@smallexample +(@value{GDBP}) +-file-list-exec-source-files +^done,files=[@{file="foo.c",fullname="/home/foo.c",debug-fully-read="true"@}, + @{file="/home/bar.c",fullname="/home/bar.c",debug-fully-read="true"@}, + @{file="gdb_could_not_find_fullpath.c",debug-fully-read="true"@}] +(@value{GDBP}) +-file-list-exec-source-files +^done,files=[@{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"@}, + @{file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"@}, + @{file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"@}, + @{file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"@}] +(@value{GDBP}) +-file-list-exec-source-files -- \\.c +^done,files=[@{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"@}, + @{file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"@}] +(@value{GDBP}) +-file-list-exec-source-files --group-by-objfile +^done,files=[@{filename="/tmp/info-sources/test.x", + debug-info="fully-read", + sources=[@{file="test.c", + fullname="/tmp/info-sources/test.c", + debug-fully-read="true"@}, + @{file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"@}, + @{file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"@}]@}, + @{filename="/lib64/ld-linux-x86-64.so.2", + debug-info="none", + sources=[]@}, + @{filename="system-supplied DSO at 0x7ffff7fcf000", + debug-info="none", + sources=[]@}, + @{filename="/tmp/info-sources/libhelper.so", + debug-info="fully-read", + sources=[@{file="helper.c", + fullname="/tmp/info-sources/helper.c", + debug-fully-read="true"@}, + @{file="/usr/include/stdc-predef.h", + fullname="/usr/include/stdc-predef.h", + debug-fully-read="true"@}, + @{file="header.h", + fullname="/tmp/info-sources/header.h", + debug-fully-read="true"@}]@}, + @{filename="/lib64/libc.so.6", + debug-info="none", + sources=[]@}] +@end smallexample + +@findex -file-list-shared-libraries +@subheading The @code{-file-list-shared-libraries} Command + +@subsubheading Synopsis + +@smallexample + -file-list-shared-libraries [ @var{regexp} ] +@end smallexample + +List the shared libraries in the program. +With a regular expression @var{regexp}, only those libraries whose +names match @var{regexp} are listed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info shared}. The fields +have a similar meaning to the @code{=library-loaded} notification. +The @code{ranges} field specifies the multiple segments belonging to this +library. Each range has the following fields: + +@table @samp +@item from +The address defining the inclusive lower bound of the segment. +@item to +The address defining the exclusive upper bound of the segment. +@end table + +@subsubheading Example +@smallexample +(gdb) +-file-list-exec-source-files +^done,shared-libraries=[ +@{id="/lib/libfoo.so",target-name="/lib/libfoo.so",host-name="/lib/libfoo.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x72815989",to="0x728162c0"@}]@}, +@{id="/lib/libbar.so",target-name="/lib/libbar.so",host-name="/lib/libbar.so",symbols-loaded="1",thread-group="i1",ranges=[@{from="0x76ee48c0",to="0x76ee9160"@}]@}] +(gdb) +@end smallexample + + +@ignore +@findex -file-list-symbol-files +@subheading The @code{-file-list-symbol-files} Command + +@subsubheading Synopsis + +@smallexample + -file-list-symbol-files +@end smallexample + +List symbol files. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info file} (part of it). + +@subsubheading Example +N.A. +@end ignore + + +@findex -file-symbol-file +@subheading The @code{-file-symbol-file} Command + +@subsubheading Synopsis + +@smallexample + -file-symbol-file @var{file} +@end smallexample + +Read symbol table info from the specified @var{file} argument. When +used without arguments, clears @value{GDBN}'s symbol table info. No output is +produced, except for a completion notification. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{symbol-file}. + +@subsubheading Example + +@smallexample +(gdb) +-file-symbol-file /kwikemart/marge/ezannoni/TRUNK/mbx/hello.mbx +^done +(gdb) +@end smallexample + +@ignore +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Memory Overlay Commands +@section @sc{gdb/mi} Memory Overlay Commands + +The memory overlay commands are not implemented. + +@c @subheading -overlay-auto + +@c @subheading -overlay-list-mapping-state + +@c @subheading -overlay-list-overlays + +@c @subheading -overlay-map + +@c @subheading -overlay-off + +@c @subheading -overlay-on + +@c @subheading -overlay-unmap + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Signal Handling Commands +@section @sc{gdb/mi} Signal Handling Commands + +Signal handling commands are not implemented. + +@c @subheading -signal-handle + +@c @subheading -signal-list-handle-actions + +@c @subheading -signal-list-signal-types +@end ignore + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Target Manipulation +@section @sc{gdb/mi} Target Manipulation Commands + + +@findex -target-attach +@subheading The @code{-target-attach} Command + +@subsubheading Synopsis + +@smallexample + -target-attach @var{pid} | @var{gid} | @var{file} +@end smallexample + +Attach to a process @var{pid} or a file @var{file} outside of +@value{GDBN}, or a thread group @var{gid}. If attaching to a thread +group, the id previously returned by +@samp{-list-thread-groups --available} must be used. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{attach}. + +@subsubheading Example +@smallexample +(gdb) +-target-attach 34 +=thread-created,id="1" +*stopped,thread-id="1",frame=@{addr="0xb7f7e410",func="bar",args=[]@} +^done +(gdb) +@end smallexample + +@ignore +@findex -target-compare-sections +@subheading The @code{-target-compare-sections} Command + +@subsubheading Synopsis + +@smallexample + -target-compare-sections [ @var{section} ] +@end smallexample + +Compare data of section @var{section} on target to the exec file. +Without the argument, all sections are compared. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{compare-sections}. + +@subsubheading Example +N.A. +@end ignore + + +@findex -target-detach +@subheading The @code{-target-detach} Command + +@subsubheading Synopsis + +@smallexample + -target-detach [ @var{pid} | @var{gid} ] +@end smallexample + +Detach from the remote target which normally resumes its execution. +If either @var{pid} or @var{gid} is specified, detaches from either +the specified process, or specified thread group. There's no output. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{detach}. + +@subsubheading Example + +@smallexample +(gdb) +-target-detach +^done +(gdb) +@end smallexample + + +@findex -target-disconnect +@subheading The @code{-target-disconnect} Command + +@subsubheading Synopsis + +@smallexample + -target-disconnect +@end smallexample + +Disconnect from the remote target. There's no output and the target is +generally not resumed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{disconnect}. + +@subsubheading Example + +@smallexample +(gdb) +-target-disconnect +^done +(gdb) +@end smallexample + + +@findex -target-download +@subheading The @code{-target-download} Command + +@subsubheading Synopsis + +@smallexample + -target-download +@end smallexample + +Loads the executable onto the remote target. +It prints out an update message every half second, which includes the fields: + +@table @samp +@item section +The name of the section. +@item section-sent +The size of what has been sent so far for that section. +@item section-size +The size of the section. +@item total-sent +The total size of what was sent so far (the current and the previous sections). +@item total-size +The size of the overall executable to download. +@end table + +@noindent +Each message is sent as status record (@pxref{GDB/MI Output Syntax, , +@sc{gdb/mi} Output Syntax}). + +In addition, it prints the name and size of the sections, as they are +downloaded. These messages include the following fields: + +@table @samp +@item section +The name of the section. +@item section-size +The size of the section. +@item total-size +The size of the overall executable to download. +@end table + +@noindent +At the end, a summary is printed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{load}. + +@subsubheading Example + +Note: each status message appears on a single line. Here the messages +have been broken down so that they can fit onto a page. + +@smallexample +(gdb) +-target-download ++download,@{section=".text",section-size="6668",total-size="9880"@} ++download,@{section=".text",section-sent="512",section-size="6668", +total-sent="512",total-size="9880"@} ++download,@{section=".text",section-sent="1024",section-size="6668", +total-sent="1024",total-size="9880"@} ++download,@{section=".text",section-sent="1536",section-size="6668", +total-sent="1536",total-size="9880"@} ++download,@{section=".text",section-sent="2048",section-size="6668", +total-sent="2048",total-size="9880"@} ++download,@{section=".text",section-sent="2560",section-size="6668", +total-sent="2560",total-size="9880"@} ++download,@{section=".text",section-sent="3072",section-size="6668", +total-sent="3072",total-size="9880"@} ++download,@{section=".text",section-sent="3584",section-size="6668", +total-sent="3584",total-size="9880"@} ++download,@{section=".text",section-sent="4096",section-size="6668", +total-sent="4096",total-size="9880"@} ++download,@{section=".text",section-sent="4608",section-size="6668", +total-sent="4608",total-size="9880"@} ++download,@{section=".text",section-sent="5120",section-size="6668", +total-sent="5120",total-size="9880"@} ++download,@{section=".text",section-sent="5632",section-size="6668", +total-sent="5632",total-size="9880"@} ++download,@{section=".text",section-sent="6144",section-size="6668", +total-sent="6144",total-size="9880"@} ++download,@{section=".text",section-sent="6656",section-size="6668", +total-sent="6656",total-size="9880"@} ++download,@{section=".init",section-size="28",total-size="9880"@} ++download,@{section=".fini",section-size="28",total-size="9880"@} ++download,@{section=".data",section-size="3156",total-size="9880"@} ++download,@{section=".data",section-sent="512",section-size="3156", +total-sent="7236",total-size="9880"@} ++download,@{section=".data",section-sent="1024",section-size="3156", +total-sent="7748",total-size="9880"@} ++download,@{section=".data",section-sent="1536",section-size="3156", +total-sent="8260",total-size="9880"@} ++download,@{section=".data",section-sent="2048",section-size="3156", +total-sent="8772",total-size="9880"@} ++download,@{section=".data",section-sent="2560",section-size="3156", +total-sent="9284",total-size="9880"@} ++download,@{section=".data",section-sent="3072",section-size="3156", +total-sent="9796",total-size="9880"@} +^done,address="0x10004",load-size="9880",transfer-rate="6586", +write-rate="429" +(gdb) +@end smallexample + + +@ignore +@findex -target-exec-status +@subheading The @code{-target-exec-status} Command + +@subsubheading Synopsis + +@smallexample + -target-exec-status +@end smallexample + +Provide information on the state of the target (whether it is running or +not, for instance). + +@subsubheading @value{GDBN} Command + +There's no equivalent @value{GDBN} command. + +@subsubheading Example +N.A. + + +@findex -target-list-available-targets +@subheading The @code{-target-list-available-targets} Command + +@subsubheading Synopsis + +@smallexample + -target-list-available-targets +@end smallexample + +List the possible targets to connect to. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{help target}. + +@subsubheading Example +N.A. + + +@findex -target-list-current-targets +@subheading The @code{-target-list-current-targets} Command + +@subsubheading Synopsis + +@smallexample + -target-list-current-targets +@end smallexample + +Describe the current target. + +@subsubheading @value{GDBN} Command + +The corresponding information is printed by @samp{info file} (among +other things). + +@subsubheading Example +N.A. + + +@findex -target-list-parameters +@subheading The @code{-target-list-parameters} Command + +@subsubheading Synopsis + +@smallexample + -target-list-parameters +@end smallexample + +@c ???? +@end ignore + +@subsubheading @value{GDBN} Command + +No equivalent. + +@subsubheading Example +N.A. + +@findex -target-flash-erase +@subheading The @code{-target-flash-erase} Command + +@subsubheading Synopsis + +@smallexample + -target-flash-erase +@end smallexample + +Erases all known flash memory regions on the target. + +The corresponding @value{GDBN} command is @samp{flash-erase}. + +The output is a list of flash regions that have been erased, with starting +addresses and memory region sizes. + +@smallexample +(gdb) +-target-flash-erase +^done,erased-regions=@{address="0x0",size="0x40000"@} +(gdb) +@end smallexample + +@findex -target-select +@subheading The @code{-target-select} Command + +@subsubheading Synopsis + +@smallexample + -target-select @var{type} @var{parameters @dots{}} +@end smallexample + +Connect @value{GDBN} to the remote target. This command takes two args: + +@table @samp +@item @var{type} +The type of target, for instance @samp{remote}, etc. +@item @var{parameters} +Device names, host names and the like. @xref{Target Commands, , +Commands for Managing Targets}, for more details. +@end table + +The output is a connection notification, followed by the address at +which the target program is, in the following form: + +@smallexample +^connected,addr="@var{address}",func="@var{function name}", + args=[@var{arg list}] +@end smallexample + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{target}. + +@subsubheading Example + +@smallexample +(gdb) +-target-select remote /dev/ttya +^connected,addr="0xfe00a300",func="??",args=[] +(gdb) +@end smallexample + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI File Transfer Commands +@section @sc{gdb/mi} File Transfer Commands + + +@findex -target-file-put +@subheading The @code{-target-file-put} Command + +@subsubheading Synopsis + +@smallexample + -target-file-put @var{hostfile} @var{targetfile} +@end smallexample + +Copy file @var{hostfile} from the host system (the machine running +@value{GDBN}) to @var{targetfile} on the target system. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{remote put}. + +@subsubheading Example + +@smallexample +(gdb) +-target-file-put localfile remotefile +^done +(gdb) +@end smallexample + + +@findex -target-file-get +@subheading The @code{-target-file-get} Command + +@subsubheading Synopsis + +@smallexample + -target-file-get @var{targetfile} @var{hostfile} +@end smallexample + +Copy file @var{targetfile} from the target system to @var{hostfile} +on the host system. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{remote get}. + +@subsubheading Example + +@smallexample +(gdb) +-target-file-get remotefile localfile +^done +(gdb) +@end smallexample + + +@findex -target-file-delete +@subheading The @code{-target-file-delete} Command + +@subsubheading Synopsis + +@smallexample + -target-file-delete @var{targetfile} +@end smallexample + +Delete @var{targetfile} from the target system. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{remote delete}. + +@subsubheading Example + +@smallexample +(gdb) +-target-file-delete remotefile +^done +(gdb) +@end smallexample + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Ada Exceptions Commands +@section Ada Exceptions @sc{gdb/mi} Commands + +@findex -info-ada-exceptions +@subheading The @code{-info-ada-exceptions} Command + +@subsubheading Synopsis + +@smallexample + -info-ada-exceptions [ @var{regexp}] +@end smallexample + +List all Ada exceptions defined within the program being debugged. +With a regular expression @var{regexp}, only those exceptions whose +names match @var{regexp} are listed. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info exceptions}. + +@subsubheading Result + +The result is a table of Ada exceptions. The following columns are +defined for each exception: + +@table @samp +@item name +The name of the exception. + +@item address +The address of the exception. + +@end table + +@subsubheading Example + +@smallexample +-info-ada-exceptions aint +^done,ada-exceptions=@{nr_rows="2",nr_cols="2", +hdr=[@{width="1",alignment="-1",col_name="name",colhdr="Name"@}, +@{width="1",alignment="-1",col_name="address",colhdr="Address"@}], +body=[@{name="constraint_error",address="0x0000000000613da0"@}, +@{name="const.aint_global_e",address="0x0000000000613b00"@}]@} +@end smallexample + +@subheading Catching Ada Exceptions + +The commands describing how to ask @value{GDBN} to stop when a program +raises an exception are described at @ref{Ada Exception GDB/MI +Catchpoint Commands}. + + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Support Commands +@section @sc{gdb/mi} Support Commands + +Since new commands and features get regularly added to @sc{gdb/mi}, +some commands are available to help front-ends query the debugger +about support for these capabilities. Similarly, it is also possible +to query @value{GDBN} about target support of certain features. + +@cindex @code{-info-gdb-mi-command} +@findex -info-gdb-mi-command +@subheading The @code{-info-gdb-mi-command} Command + +@subsubheading Synopsis + +@smallexample + -info-gdb-mi-command @var{cmd_name} +@end smallexample + +Query support for the @sc{gdb/mi} command named @var{cmd_name}. + +Note that the dash (@code{-}) starting all @sc{gdb/mi} commands +is technically not part of the command name (@pxref{GDB/MI Input +Syntax}), and thus should be omitted in @var{cmd_name}. However, +for ease of use, this command also accepts the form with the leading +dash. + +@subsubheading @value{GDBN} Command + +There is no corresponding @value{GDBN} command. + +@subsubheading Result + +The result is a tuple. There is currently only one field: + +@table @samp +@item exists +This field is equal to @code{"true"} if the @sc{gdb/mi} command exists, +@code{"false"} otherwise. + +@end table + +@subsubheading Example + +Here is an example where the @sc{gdb/mi} command does not exist: + +@smallexample +-info-gdb-mi-command unsupported-command +^done,command=@{exists="false"@} +@end smallexample + +@noindent +And here is an example where the @sc{gdb/mi} command is known +to the debugger: + +@smallexample +-info-gdb-mi-command symbol-list-lines +^done,command=@{exists="true"@} +@end smallexample + +@findex -list-features +@cindex supported @sc{gdb/mi} features, list +@subheading The @code{-list-features} Command + +Returns a list of particular features of the MI protocol that +this version of gdb implements. A feature can be a command, +or a new field in an output of some command, or even an +important bugfix. While a frontend can sometimes detect presence +of a feature at runtime, it is easier to perform detection at debugger +startup. + +The command returns a list of strings, with each string naming an +available feature. Each returned string is just a name, it does not +have any internal structure. The list of possible feature names +is given below. + +Example output: + +@smallexample +(gdb) -list-features +^done,result=["feature1","feature2"] +@end smallexample + +The current list of features is: + +@ftable @samp +@item frozen-varobjs +Indicates support for the @code{-var-set-frozen} command, as well +as possible presence of the @code{frozen} field in the output +of @code{-varobj-create}. +@item pending-breakpoints +Indicates support for the @option{-f} option to the @code{-break-insert} +command. +@item python +Indicates Python scripting support, Python-based +pretty-printing commands, and possible presence of the +@samp{display_hint} field in the output of @code{-var-list-children} +@item thread-info +Indicates support for the @code{-thread-info} command. +@item data-read-memory-bytes +Indicates support for the @code{-data-read-memory-bytes} and the +@code{-data-write-memory-bytes} commands. +@item breakpoint-notifications +Indicates that changes to breakpoints and breakpoints created via the +CLI will be announced via async records. +@item ada-task-info +Indicates support for the @code{-ada-task-info} command. +@item language-option +Indicates that all @sc{gdb/mi} commands accept the @option{--language} +option (@pxref{Context management}). +@item info-gdb-mi-command +Indicates support for the @code{-info-gdb-mi-command} command. +@item undefined-command-error-code +Indicates support for the "undefined-command" error code in error result +records, produced when trying to execute an undefined @sc{gdb/mi} command +(@pxref{GDB/MI Result Records}). +@item exec-run-start-option +Indicates that the @code{-exec-run} command supports the @option{--start} +option (@pxref{GDB/MI Program Execution}). +@item data-disassemble-a-option +Indicates that the @code{-data-disassemble} command supports the @option{-a} +option (@pxref{GDB/MI Data Manipulation}). +@item simple-values-ref-types +Indicates that the @code{--simple-values} argument to the +@code{-stack-list-arguments}, @code{-stack-list-locals}, +@code{-stack-list-variables}, and @code{-var-list-children} commands +takes reference types into account: that is, a value is considered +simple if it is neither an array, structure, or union, nor a reference +to an array, structure, or union. +@end ftable + +@findex -list-target-features +@subheading The @code{-list-target-features} Command + +Returns a list of particular features that are supported by the +target. Those features affect the permitted MI commands, but +unlike the features reported by the @code{-list-features} command, the +features depend on which target GDB is using at the moment. Whenever +a target can change, due to commands such as @code{-target-select}, +@code{-target-attach} or @code{-exec-run}, the list of target features +may change, and the frontend should obtain it again. +Example output: + +@smallexample +(gdb) -list-target-features +^done,result=["async"] +@end smallexample + +The current list of features is: + +@table @samp +@item async +Indicates that the target is capable of asynchronous command +execution, which means that @value{GDBN} will accept further commands +while the target is running. + +@item reverse +Indicates that the target is capable of reverse execution. +@xref{Reverse Execution}, for more information. + +@end table + +@c %%%%%%%%%%%%%%%%%%%%%%%%%%%% SECTION %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +@node GDB/MI Miscellaneous Commands +@section Miscellaneous @sc{gdb/mi} Commands + +@c @subheading -gdb-complete + +@findex -gdb-exit +@subheading The @code{-gdb-exit} Command + +@subsubheading Synopsis + +@smallexample + -gdb-exit +@end smallexample + +Exit @value{GDBN} immediately. + +@subsubheading @value{GDBN} Command + +Approximately corresponds to @samp{quit}. + +@subsubheading Example + +@smallexample +(gdb) +-gdb-exit +^exit +@end smallexample + + +@ignore +@findex -exec-abort +@subheading The @code{-exec-abort} Command + +@subsubheading Synopsis + +@smallexample + -exec-abort +@end smallexample + +Kill the inferior running program. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{kill}. + +@subsubheading Example +N.A. +@end ignore + + +@findex -gdb-set +@subheading The @code{-gdb-set} Command + +@subsubheading Synopsis + +@smallexample + -gdb-set +@end smallexample + +Set an internal @value{GDBN} variable. +@c IS THIS A DOLLAR VARIABLE? OR SOMETHING LIKE ANNOTATE ????? + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set}. + +@subsubheading Example + +@smallexample +(gdb) +-gdb-set $foo=3 +^done +(gdb) +@end smallexample + + +@findex -gdb-show +@subheading The @code{-gdb-show} Command + +@subsubheading Synopsis + +@smallexample + -gdb-show +@end smallexample + +Show the current value of a @value{GDBN} variable. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{show}. + +@subsubheading Example + +@smallexample +(gdb) +-gdb-show annotate +^done,value="0" +(gdb) +@end smallexample + +@c @subheading -gdb-source + + +@findex -gdb-version +@subheading The @code{-gdb-version} Command + +@subsubheading Synopsis + +@smallexample + -gdb-version +@end smallexample + +Show version information for @value{GDBN}. Used mostly in testing. + +@subsubheading @value{GDBN} Command + +The @value{GDBN} equivalent is @samp{show version}. @value{GDBN} by +default shows this information when you start an interactive session. + +@subsubheading Example + +@c This example modifies the actual output from GDB to avoid overfull +@c box in TeX. +@smallexample +(gdb) +-gdb-version +~GNU gdb 5.2.1 +~Copyright 2000 Free Software Foundation, Inc. +~GDB is free software, covered by the GNU General Public License, and +~you are welcome to change it and/or distribute copies of it under +~ certain conditions. +~Type "show copying" to see the conditions. +~There is absolutely no warranty for GDB. Type "show warranty" for +~ details. +~This GDB was configured as + "--host=sparc-sun-solaris2.5.1 --target=ppc-eabi". +^done +(gdb) +@end smallexample + +@findex -list-thread-groups +@subheading The @code{-list-thread-groups} Command + +@subsubheading Synopsis + +@smallexample +-list-thread-groups [ --available ] [ --recurse 1 ] [ @var{group} ... ] +@end smallexample + +Lists thread groups (@pxref{Thread groups}). When a single thread +group is passed as the argument, lists the children of that group. +When several thread group are passed, lists information about those +thread groups. Without any parameters, lists information about all +top-level thread groups. + +Normally, thread groups that are being debugged are reported. +With the @samp{--available} option, @value{GDBN} reports thread groups +available on the target. + +The output of this command may have either a @samp{threads} result or +a @samp{groups} result. The @samp{thread} result has a list of tuples +as value, with each tuple describing a thread (@pxref{GDB/MI Thread +Information}). The @samp{groups} result has a list of tuples as value, +each tuple describing a thread group. If top-level groups are +requested (that is, no parameter is passed), or when several groups +are passed, the output always has a @samp{groups} result. The format +of the @samp{group} result is described below. + +To reduce the number of roundtrips it's possible to list thread groups +together with their children, by passing the @samp{--recurse} option +and the recursion depth. Presently, only recursion depth of 1 is +permitted. If this option is present, then every reported thread group +will also include its children, either as @samp{group} or +@samp{threads} field. + +In general, any combination of option and parameters is permitted, with +the following caveats: + +@itemize @bullet +@item +When a single thread group is passed, the output will typically +be the @samp{threads} result. Because threads may not contain +anything, the @samp{recurse} option will be ignored. + +@item +When the @samp{--available} option is passed, limited information may +be available. In particular, the list of threads of a process might +be inaccessible. Further, specifying specific thread groups might +not give any performance advantage over listing all thread groups. +The frontend should assume that @samp{-list-thread-groups --available} +is always an expensive operation and cache the results. + +@end itemize + +The @samp{groups} result is a list of tuples, where each tuple may +have the following fields: + +@table @code +@item id +Identifier of the thread group. This field is always present. +The identifier is an opaque string; frontends should not try to +convert it to an integer, even though it might look like one. + +@item type +The type of the thread group. At present, only @samp{process} is a +valid type. + +@item pid +The target-specific process identifier. This field is only present +for thread groups of type @samp{process} and only if the process exists. + +@item exit-code +The exit code of this group's last exited thread, formatted in octal. +This field is only present for thread groups of type @samp{process} and +only if the process is not running. + +@item num_children +The number of children this thread group has. This field may be +absent for an available thread group. + +@item threads +This field has a list of tuples as value, each tuple describing a +thread. It may be present if the @samp{--recurse} option is +specified, and it's actually possible to obtain the threads. + +@item cores +This field is a list of integers, each identifying a core that one +thread of the group is running on. This field may be absent if +such information is not available. + +@item executable +The name of the executable file that corresponds to this thread group. +The field is only present for thread groups of type @samp{process}, +and only if there is a corresponding executable file. + +@end table + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-list-thread-groups +^done,groups=[@{id="17",type="process",pid="yyy",num_children="2"@}] +-list-thread-groups 17 +^done,threads=[@{id="2",target-id="Thread 0xb7e14b90 (LWP 21257)", + frame=@{level="0",addr="0xffffe410",func="__kernel_vsyscall",args=[]@},state="running"@}, +@{id="1",target-id="Thread 0xb7e156b0 (LWP 21254)", + frame=@{level="0",addr="0x0804891f",func="foo",args=[@{name="i",value="10"@}], + file="/tmp/a.c",fullname="/tmp/a.c",line="158",arch="i386:x86_64"@},state="running"@}]] +-list-thread-groups --available +^done,groups=[@{id="17",type="process",pid="yyy",num_children="2",cores=[1,2]@}] +-list-thread-groups --available --recurse 1 + ^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, + @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},..] +-list-thread-groups --available --recurse 1 17 18 +^done,groups=[@{id="17", types="process",pid="yyy",num_children="2",cores=[1,2], + threads=[@{id="1",target-id="Thread 0xb7e14b90",cores=[1]@}, + @{id="2",target-id="Thread 0xb7e14b90",cores=[2]@}]@},...] +@end smallexample + +@findex -info-os +@subheading The @code{-info-os} Command + +@subsubheading Synopsis + +@smallexample +-info-os [ @var{type} ] +@end smallexample + +If no argument is supplied, the command returns a table of available +operating-system-specific information types. If one of these types is +supplied as an argument @var{type}, then the command returns a table +of data of that type. + +The types of information available depend on the target operating +system. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{info os}. + +@subsubheading Example + +When run on a @sc{gnu}/Linux system, the output will look something +like this: + +@smallexample +(@value{GDBP}) +-info-os +^done,OSDataTable=@{nr_rows="10",nr_cols="3", +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="Type"@}, + @{width="10",alignment="-1",col_name="col1",colhdr="Description"@}, + @{width="10",alignment="-1",col_name="col2",colhdr="Title"@}], +body=[item=@{col0="cpus",col1="Listing of all cpus/cores on the system", + col2="CPUs"@}, + item=@{col0="files",col1="Listing of all file descriptors", + col2="File descriptors"@}, + item=@{col0="modules",col1="Listing of all loaded kernel modules", + col2="Kernel modules"@}, + item=@{col0="msg",col1="Listing of all message queues", + col2="Message queues"@}, + item=@{col0="processes",col1="Listing of all processes", + col2="Processes"@}, + item=@{col0="procgroups",col1="Listing of all process groups", + col2="Process groups"@}, + item=@{col0="semaphores",col1="Listing of all semaphores", + col2="Semaphores"@}, + item=@{col0="shm",col1="Listing of all shared-memory regions", + col2="Shared-memory regions"@}, + item=@{col0="sockets",col1="Listing of all internet-domain sockets", + col2="Sockets"@}, + item=@{col0="threads",col1="Listing of all threads", + col2="Threads"@}] +(@value{GDBP}) +-info-os processes +^done,OSDataTable=@{nr_rows="190",nr_cols="4", +hdr=[@{width="10",alignment="-1",col_name="col0",colhdr="pid"@}, + @{width="10",alignment="-1",col_name="col1",colhdr="user"@}, + @{width="10",alignment="-1",col_name="col2",colhdr="command"@}, + @{width="10",alignment="-1",col_name="col3",colhdr="cores"@}], +body=[item=@{col0="1",col1="root",col2="/sbin/init",col3="0"@}, + item=@{col0="2",col1="root",col2="[kthreadd]",col3="1"@}, + item=@{col0="3",col1="root",col2="[ksoftirqd/0]",col3="0"@}, + ... + item=@{col0="26446",col1="stan",col2="bash",col3="0"@}, + item=@{col0="28152",col1="stan",col2="bash",col3="1"@}]@} +(@value{GDBP}) +@end smallexample + +(Note that the MI output here includes a @code{"Title"} column that +does not appear in command-line @code{info os}; this column is useful +for MI clients that want to enumerate the types of data, such as in a +popup menu, but is needless clutter on the command line, and +@code{info os} omits it.) + +@findex -add-inferior +@subheading The @code{-add-inferior} Command + +@subsubheading Synopsis + +@smallexample +-add-inferior [ --no-connection ] +@end smallexample + +Creates a new inferior (@pxref{Inferiors Connections and Programs}). The created +inferior is not associated with any executable. Such association may +be established with the @samp{-file-exec-and-symbols} command +(@pxref{GDB/MI File Commands}). + +By default, the new inferior begins connected to the same target +connection as the current inferior. For example, if the current +inferior was connected to @code{gdbserver} with @code{target remote}, +then the new inferior will be connected to the same @code{gdbserver} +instance. The @samp{--no-connection} option starts the new inferior +with no connection yet. You can then for example use the +@code{-target-select remote} command to connect to some other +@code{gdbserver} instance, use @code{-exec-run} to spawn a local +program, etc. + +The command response always has a field, @var{inferior}, whose value +is the identifier of the thread group corresponding to the new +inferior. + +An additional section field, @var{connection}, is optional. This +field will only exist if the new inferior has a target connection. If +this field exists, then its value will be a tuple containing the +following fields: + +@table @samp +@item number +The number of the connection used for the new inferior. + +@item name +The name of the connection type used for the new inferior. +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{add-inferior} +(@pxref{add_inferior_cli,,@samp{add-inferior}}). + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-add-inferior +^done,inferior="i3" +@end smallexample + +@findex -remove-inferior +@subheading The @code{-remove-inferior} Command + +@subsubheading Synopsis + +@smallexample +-remove-inferior @var{inferior-id} +@end smallexample + +Removes an inferior (@pxref{Inferiors Connections and Programs}). +Only inferiors that have exited can be removed. The @var{inferior-id} +is the inferior to be removed, and should be the same id string as +returned by the @samp{-add-inferior} command. + +When an inferior is successfully removed a +@code{=thread-group-removed} notification (@pxref{GDB/MI Async +Records}) is emitted, the @var{id} field of which contains the +@var{inferior-id} for the removed inferior. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{remove-inferiors} +(@pxref{remove_inferiors_cli,,@samp{remove-inferiors}}). + +@subsubheading Example + +@smallexample +(@value{GDBP}) +-remove-inferior i3 +=thread-group-removed,id="i3" +^done +@end smallexample + +@findex -interpreter-exec +@subheading The @code{-interpreter-exec} Command + +@subsubheading Synopsis + +@smallexample +-interpreter-exec @var{interpreter} @var{command} +@end smallexample +@anchor{-interpreter-exec} + +Execute the specified @var{command} in the given @var{interpreter}. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{interpreter-exec}. + +@subsubheading Example + +@smallexample +(gdb) +-interpreter-exec console "break main" +&"During symbol reading, couldn't parse type; debugger out of date?.\n" +&"During symbol reading, bad structure-type format.\n" +~"Breakpoint 1 at 0x8074fc6: file ../../src/gdb/main.c, line 743.\n" +^done +(gdb) +@end smallexample + +@findex -inferior-tty-set +@subheading The @code{-inferior-tty-set} Command + +@subsubheading Synopsis + +@smallexample +-inferior-tty-set /dev/pts/1 +@end smallexample + +Set terminal for future runs of the program being debugged. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{set inferior-tty} /dev/pts/1. + +@subsubheading Example + +@smallexample +(gdb) +-inferior-tty-set /dev/pts/1 +^done +(gdb) +@end smallexample + +@findex -inferior-tty-show +@subheading The @code{-inferior-tty-show} Command + +@subsubheading Synopsis + +@smallexample +-inferior-tty-show +@end smallexample + +Show terminal for future runs of program being debugged. + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{show inferior-tty}. + +@subsubheading Example + +@smallexample +(gdb) +-inferior-tty-set /dev/pts/1 +^done +(gdb) +-inferior-tty-show +^done,inferior_tty_terminal="/dev/pts/1" +(gdb) +@end smallexample + +@findex -enable-timings +@subheading The @code{-enable-timings} Command + +@subsubheading Synopsis + +@smallexample +-enable-timings [yes | no] +@end smallexample + +Toggle the printing of the wallclock, user and system times for an MI +command as a field in its output. This command is to help frontend +developers optimize the performance of their code. No argument is +equivalent to @samp{yes}. + +@subsubheading @value{GDBN} Command + +No equivalent. + +@subsubheading Example + +@smallexample +(gdb) +-enable-timings +^done +(gdb) +-break-insert main +^done,bkpt=@{number="1",type="breakpoint",disp="keep",enabled="y", +addr="0x080484ed",func="main",file="myprog.c", +fullname="/home/nickrob/myprog.c",line="73",thread-groups=["i1"], +times="0"@}, +time=@{wallclock="0.05185",user="0.00800",system="0.00000"@} +(gdb) +-enable-timings no +^done +(gdb) +-exec-run +^running +(gdb) +*stopped,reason="breakpoint-hit",disp="keep",bkptno="1",thread-id="0", +frame=@{addr="0x080484ed",func="main",args=[@{name="argc",value="1"@}, +@{name="argv",value="0xbfb60364"@}],file="myprog.c", +fullname="/home/nickrob/myprog.c",line="73",arch="i386:x86_64"@} +(gdb) +@end smallexample + +@findex -complete +@subheading The @code{-complete} Command + +@subsubheading Synopsis + +@smallexample +-complete @var{command} +@end smallexample + +Show a list of completions for partially typed CLI @var{command}. + +This command is intended for @sc{gdb/mi} frontends that cannot use two separate +CLI and MI channels --- for example: because of lack of PTYs like on Windows or +because @value{GDBN} is used remotely via a SSH connection. + +@subsubheading Result + +The result consists of two or three fields: + +@table @samp +@item completion +This field contains the completed @var{command}. If @var{command} +has no known completions, this field is omitted. + +@item matches +This field contains a (possibly empty) array of matches. It is always present. + +@item max_completions_reached +This field contains @code{1} if number of known completions is above +@code{max-completions} limit (@pxref{Completion}), otherwise it contains +@code{0}. It is always present. + +@end table + +@subsubheading @value{GDBN} Command + +The corresponding @value{GDBN} command is @samp{complete}. + +@subsubheading Example + +@smallexample +(gdb) +-complete br +^done,completion="break", + matches=["break","break-range"], + max_completions_reached="0" +(gdb) +-complete "b ma" +^done,completion="b ma", + matches=["b madvise","b main"],max_completions_reached="0" +(gdb) +-complete "b push_b" +^done,completion="b push_back(", + matches=[ + "b A::push_back(void*)", + "b std::string::push_back(char)", + "b std::vector >::push_back(int&&)"], + max_completions_reached="0" +(gdb) +-complete "nonexist" +^done,matches=[],max_completions_reached="0" +(gdb) + +@end smallexample + +@node Annotations +@chapter @value{GDBN} Annotations + +This chapter describes annotations in @value{GDBN}. Annotations were +designed to interface @value{GDBN} to graphical user interfaces or other +similar programs which want to interact with @value{GDBN} at a +relatively high level. + +The annotation mechanism has largely been superseded by @sc{gdb/mi} +(@pxref{GDB/MI}). + +@ignore +This is Edition @value{EDITION}, @value{DATE}. +@end ignore + +@menu +* Annotations Overview:: What annotations are; the general syntax. +* Server Prefix:: Issuing a command without affecting user state. +* Prompting:: Annotations marking @value{GDBN}'s need for input. +* Errors:: Annotations for error messages. +* Invalidation:: Some annotations describe things now invalid. +* Annotations for Running:: + Whether the program is running, how it stopped, etc. +* Source Annotations:: Annotations describing source code. +@end menu + +@node Annotations Overview +@section What is an Annotation? +@cindex annotations + +Annotations start with a newline character, two @samp{control-z} +characters, and the name of the annotation. If there is no additional +information associated with this annotation, the name of the annotation +is followed immediately by a newline. If there is additional +information, the name of the annotation is followed by a space, the +additional information, and a newline. The additional information +cannot contain newline characters. + +Any output not beginning with a newline and two @samp{control-z} +characters denotes literal output from @value{GDBN}. Currently there is +no need for @value{GDBN} to output a newline followed by two +@samp{control-z} characters, but if there was such a need, the +annotations could be extended with an @samp{escape} annotation which +means those three characters as output. + +The annotation @var{level}, which is specified using the +@option{--annotate} command line option (@pxref{Mode Options}), controls +how much information @value{GDBN} prints together with its prompt, +values of expressions, source lines, and other types of output. Level 0 +is for no annotations, level 1 is for use when @value{GDBN} is run as a +subprocess of @sc{gnu} Emacs, level 3 is the maximum annotation suitable +for programs that control @value{GDBN}, and level 2 annotations have +been made obsolete (@pxref{Limitations, , Limitations of the Annotation +Interface, annotate, GDB's Obsolete Annotations}). + +@table @code +@kindex set annotate +@item set annotate @var{level} +The @value{GDBN} command @code{set annotate} sets the level of +annotations to the specified @var{level}. + +@item show annotate +@kindex show annotate +Show the current annotation level. +@end table + +This chapter describes level 3 annotations. + +A simple example of starting up @value{GDBN} with annotations is: + +@smallexample +$ @kbd{gdb --annotate=3} +GNU gdb 6.0 +Copyright 2003 Free Software Foundation, Inc. +GDB is free software, covered by the GNU General Public License, +and you are welcome to change it and/or distribute copies of it +under certain conditions. +Type "show copying" to see the conditions. +There is absolutely no warranty for GDB. Type "show warranty" +for details. +This GDB was configured as "i386-pc-linux-gnu" + +^Z^Zpre-prompt +(@value{GDBP}) +^Z^Zprompt +@kbd{quit} + +^Z^Zpost-prompt +$ +@end smallexample + +Here @samp{quit} is input to @value{GDBN}; the rest is output from +@value{GDBN}. The three lines beginning @samp{^Z^Z} (where @samp{^Z} +denotes a @samp{control-z} character) are annotations; the rest is +output from @value{GDBN}. + +@node Server Prefix +@section The Server Prefix +@cindex server prefix + +If you prefix a command with @samp{server } then it will not affect +the command history, nor will it affect @value{GDBN}'s notion of which +command to repeat if @key{RET} is pressed on a line by itself. This +means that commands can be run behind a user's back by a front-end in +a transparent manner. + +The @code{server } prefix does not affect the recording of values into +the value history; to print a value without recording it into the +value history, use the @code{output} command instead of the +@code{print} command. + +Using this prefix also disables confirmation requests +(@pxref{confirmation requests}). + +@node Prompting +@section Annotation for @value{GDBN} Input + +@cindex annotations for prompts +When @value{GDBN} prompts for input, it annotates this fact so it is possible +to know when to send output, when the output from a given command is +over, etc. + +Different kinds of input each have a different @dfn{input type}. Each +input type has three annotations: a @code{pre-} annotation, which +denotes the beginning of any prompt which is being output, a plain +annotation, which denotes the end of the prompt, and then a @code{post-} +annotation which denotes the end of any echo which may (or may not) be +associated with the input. For example, the @code{prompt} input type +features the following annotations: + +@smallexample +^Z^Zpre-prompt +^Z^Zprompt +^Z^Zpost-prompt +@end smallexample + +The input types are + +@table @code +@findex pre-prompt annotation +@findex prompt annotation +@findex post-prompt annotation +@item prompt +When @value{GDBN} is prompting for a command (the main @value{GDBN} prompt). + +@findex pre-commands annotation +@findex commands annotation +@findex post-commands annotation +@item commands +When @value{GDBN} prompts for a set of commands, like in the @code{commands} +command. The annotations are repeated for each command which is input. + +@findex pre-overload-choice annotation +@findex overload-choice annotation +@findex post-overload-choice annotation +@item overload-choice +When @value{GDBN} wants the user to select between various overloaded functions. + +@findex pre-query annotation +@findex query annotation +@findex post-query annotation +@item query +When @value{GDBN} wants the user to confirm a potentially dangerous operation. + +@findex pre-prompt-for-continue annotation +@findex prompt-for-continue annotation +@findex post-prompt-for-continue annotation +@item prompt-for-continue +When @value{GDBN} is asking the user to press return to continue. Note: Don't +expect this to work well; instead use @code{set height 0} to disable +prompting. This is because the counting of lines is buggy in the +presence of annotations. +@end table + +@node Errors +@section Errors +@cindex annotations for errors, warnings and interrupts + +@findex quit annotation +@smallexample +^Z^Zquit +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an interrupt. + +@findex error annotation +@smallexample +^Z^Zerror +@end smallexample + +This annotation occurs right before @value{GDBN} responds to an error. + +Quit and error annotations indicate that any annotations which @value{GDBN} was +in the middle of may end abruptly. For example, if a +@code{value-history-begin} annotation is followed by a @code{error}, one +cannot expect to receive the matching @code{value-history-end}. One +cannot expect not to receive it either, however; an error annotation +does not necessarily mean that @value{GDBN} is immediately returning all the way +to the top level. + +@findex error-begin annotation +A quit or error annotation may be preceded by + +@smallexample +^Z^Zerror-begin +@end smallexample + +Any output between that and the quit or error annotation is the error +message. + +Warning messages are not yet annotated. +@c If we want to change that, need to fix warning(), type_error(), +@c range_error(), and possibly other places. + +@node Invalidation +@section Invalidation Notices + +@cindex annotations for invalidation messages +The following annotations say that certain pieces of state may have +changed. + +@table @code +@findex frames-invalid annotation +@item ^Z^Zframes-invalid + +The frames (for example, output from the @code{backtrace} command) may +have changed. + +@findex breakpoints-invalid annotation +@item ^Z^Zbreakpoints-invalid + +The breakpoints may have changed. For example, the user just added or +deleted a breakpoint. +@end table + +@node Annotations for Running +@section Running the Program +@cindex annotations for running programs + +@findex starting annotation +@findex stopping annotation +When the program starts executing due to a @value{GDBN} command such as +@code{step} or @code{continue}, + +@smallexample +^Z^Zstarting +@end smallexample + +is output. When the program stops, + +@smallexample +^Z^Zstopped +@end smallexample + +is output. Before the @code{stopped} annotation, a variety of +annotations describe how the program stopped. + +@table @code +@findex exited annotation +@item ^Z^Zexited @var{exit-status} +The program exited, and @var{exit-status} is the exit status (zero for +successful exit, otherwise nonzero). + +@findex signalled annotation +@findex signal-name annotation +@findex signal-name-end annotation +@findex signal-string annotation +@findex signal-string-end annotation +@item ^Z^Zsignalled +The program exited with a signal. After the @code{^Z^Zsignalled}, the +annotation continues: + +@smallexample +@var{intro-text} +^Z^Zsignal-name +@var{name} +^Z^Zsignal-name-end +@var{middle-text} +^Z^Zsignal-string +@var{string} +^Z^Zsignal-string-end +@var{end-text} +@end smallexample + +@noindent +where @var{name} is the name of the signal, such as @code{SIGILL} or +@code{SIGSEGV}, and @var{string} is the explanation of the signal, such +as @code{Illegal Instruction} or @code{Segmentation fault}. The arguments +@var{intro-text}, @var{middle-text}, and @var{end-text} are for the +user's benefit and have no particular format. + +@findex signal annotation +@item ^Z^Zsignal +The syntax of this annotation is just like @code{signalled}, but @value{GDBN} is +just saying that the program received the signal, not that it was +terminated with it. + +@findex breakpoint annotation +@item ^Z^Zbreakpoint @var{number} +The program hit breakpoint number @var{number}. + +@findex watchpoint annotation +@item ^Z^Zwatchpoint @var{number} +The program hit watchpoint number @var{number}. +@end table + +@node Source Annotations +@section Displaying Source +@cindex annotations for source display + +@findex source annotation +The following annotation is used instead of displaying source code: + +@smallexample +^Z^Zsource @var{filename}:@var{line}:@var{character}:@var{middle}:@var{addr} +@end smallexample + +where @var{filename} is an absolute file name indicating which source +file, @var{line} is the line number within that file (where 1 is the +first line in the file), @var{character} is the character position +within the file (where 0 is the first character in the file) (for most +debug formats this will necessarily point to the beginning of a line), +@var{middle} is @samp{middle} if @var{addr} is in the middle of the +line, or @samp{beg} if @var{addr} is at the beginning of the line, and +@var{addr} is the address in the target program associated with the +source which is being displayed. The @var{addr} is in the form @samp{0x} +followed by one or more lowercase hex digits (note that this does not +depend on the language). + +@node Debugger Adapter Protocol +@chapter Debugger Adapter Protocol + +The Debugger Adapter Protocol is a generic API that is used by some +IDEs to communicate with debuggers. It is documented at +@url{https://microsoft.github.io/debug-adapter-protocol/}. + +Generally, @value{GDBN} implements the Debugger Adapter Protocol as +written. However, in some cases, extensions are either needed or even +expected. + +@value{GDBN} defines some parameters that can be passed to the +@code{launch} request: + +@table @code +@item args +If provided, this should be an array of strings. These strings are +provided as command-line arguments to the inferior, as if by +@code{set args}. @xref{Arguments}. + +@item cwd +If provided, this should be a string. @value{GDBN} will change its +working directory to this directory, as if by the @code{cd} command +(@pxref{Working Directory}). The launched program will inherit this +as its working directory. Note that change of directory happens +before the @code{program} parameter is processed. This will affect +the result if @code{program} is a relative filename. + +@item env +If provided, this should be an object. Each key of the object will be +used as the name of an environment variable; each value must be a +string and will be the value of that variable. The environment of the +inferior will be set to exactly as passed in. @xref{Environment}. + +@item program +If provided, this is a string that specifies the program to use. This +corresponds to the @code{file} command. @xref{Files}. + +@item stopAtBeginningOfMainSubprogram +If provided, this must be a boolean. When @samp{True}, @value{GDBN} +will set a temporary breakpoint at the program's main procedure, using +the same approach as the @code{start} command. @xref{Starting}. + +@item stopOnEntry +If provided, this must be a boolean. When @samp{True}, @value{GDBN} +will set a temporary breakpoint at the program's first instruction, using +the same approach as the @code{starti} command. @xref{Starting}. +@end table + +@value{GDBN} defines some parameters that can be passed to the +@code{attach} request. Either @code{pid} or @code{target} must be +specified, but if both are specified then @code{target} will be +ignored. + +@table @code +@item pid +The process ID to which @value{GDBN} should attach. @xref{Attach}. + +@item program +If provided, this is a string that specifies the program to use. This +corresponds to the @code{file} command. @xref{Files}. In some cases, +@value{GDBN} can automatically determine which program is running. +However, for many remote targets, this is not the case, and so this +should be supplied. + +@item target +The target to which @value{GDBN} should connect. This is a string and +is passed to the @code{target remote} command. @xref{Connecting}. +@end table + +In response to the @code{disassemble} request, DAP allows the client +to return the bytes of each instruction in an implementation-defined +format. @value{GDBN} implements this by sending a string with the +bytes encoded in hex, like @code{"55a2b900"}. + +When the @code{repl} context is used for the @code{evaluate} request, +@value{GDBN} evaluates the provided expression as a CLI command. + +Evaluation in general can cause the inferior to continue execution. +For example, evaluating the @code{continue} command could do this, as +could evaluating an expression that involves an inferior function +call. + +@code{repl} evaluation can also cause @value{GDBN} to appear to stop +responding to requests, for example if a CLI script does a lengthy +computation. + +Evaluations like this can be interrupted using the DAP @code{cancel} +request. (In fact, @code{cancel} should work for any request, but it +is unlikely to be useful for most of them.) + +@value{GDBN} provides a couple of logging settings that can be used in +DAP mode. These can be set on the command line using the @code{-iex} +option (@pxref{File Options}). + +@table @code +@item set debug dap-log-file @r{[}@var{filename}@r{]} +Enable DAP logging. Logs are written to @var{filename}. If no +@var{filename} is given, logging is stopped. + +@item set debug dap-log-level @var{level} +Set the DAP logging level. The default is @samp{1}, which logs the +DAP protocol, whatever debug messages the developers thought were +useful, and unexpected exceptions. Level @samp{2} can be used to log +all exceptions, including ones that are considered to be expected. +For example, a failure to parse an expression would be considered a +normal exception and not normally be logged. +@end table + +@node JIT Interface +@chapter JIT Compilation Interface +@cindex just-in-time compilation +@cindex JIT compilation interface + +This chapter documents @value{GDBN}'s @dfn{just-in-time} (JIT) compilation +interface. A JIT compiler is a program or library that generates native +executable code at runtime and executes it, usually in order to achieve good +performance while maintaining platform independence. + +Programs that use JIT compilation are normally difficult to debug because +portions of their code are generated at runtime, instead of being loaded from +object files, which is where @value{GDBN} normally finds the program's symbols +and debug information. In order to debug programs that use JIT compilation, +@value{GDBN} has an interface that allows the program to register in-memory +symbol files with @value{GDBN} at runtime. + +If you are using @value{GDBN} to debug a program that uses this interface, then +it should work transparently so long as you have not stripped the binary. If +you are developing a JIT compiler, then the interface is documented in the rest +of this chapter. At this time, the only known client of this interface is the +LLVM JIT. + +Broadly speaking, the JIT interface mirrors the dynamic loader interface. The +JIT compiler communicates with @value{GDBN} by writing data into a global +variable and calling a function at a well-known symbol. When @value{GDBN} +attaches, it reads a linked list of symbol files from the global variable to +find existing code, and puts a breakpoint in the function so that it can find +out about additional code. + +@menu +* Declarations:: Relevant C struct declarations +* Registering Code:: Steps to register code +* Unregistering Code:: Steps to unregister code +* Custom Debug Info:: Emit debug information in a custom format +@end menu + +@node Declarations +@section JIT Declarations + +These are the relevant struct declarations that a C program should include to +implement the interface: + +@smallexample +typedef enum +@{ + JIT_NOACTION = 0, + JIT_REGISTER_FN, + JIT_UNREGISTER_FN +@} jit_actions_t; + +struct jit_code_entry +@{ + struct jit_code_entry *next_entry; + struct jit_code_entry *prev_entry; + const char *symfile_addr; + uint64_t symfile_size; +@}; + +struct jit_descriptor +@{ + uint32_t version; + /* This type should be jit_actions_t, but we use uint32_t + to be explicit about the bitwidth. */ + uint32_t action_flag; + struct jit_code_entry *relevant_entry; + struct jit_code_entry *first_entry; +@}; + +/* GDB puts a breakpoint in this function. */ +void __attribute__((noinline)) __jit_debug_register_code() @{ @}; + +/* Make sure to specify the version statically, because the + debugger may check the version before we can set it. */ +struct jit_descriptor __jit_debug_descriptor = @{ 1, 0, 0, 0 @}; +@end smallexample + +If the JIT is multi-threaded, then it is important that the JIT synchronize any +modifications to this global data properly, which can easily be done by putting +a global mutex around modifications to these structures. + +@node Registering Code +@section Registering Code + +To register code with @value{GDBN}, the JIT should follow this protocol: + +@itemize @bullet +@item +Generate an object file in memory with symbols and other desired debug +information. The file must include the virtual addresses of the sections. + +@item +Create a code entry for the file, which gives the start and size of the symbol +file. + +@item +Add it to the linked list in the JIT descriptor. + +@item +Point the relevant_entry field of the descriptor at the entry. + +@item +Set @code{action_flag} to @code{JIT_REGISTER} and call +@code{__jit_debug_register_code}. +@end itemize + +When @value{GDBN} is attached and the breakpoint fires, @value{GDBN} uses the +@code{relevant_entry} pointer so it doesn't have to walk the list looking for +new code. However, the linked list must still be maintained in order to allow +@value{GDBN} to attach to a running process and still find the symbol files. + +@node Unregistering Code +@section Unregistering Code + +If code is freed, then the JIT should use the following protocol: + +@itemize @bullet +@item +Remove the code entry corresponding to the code from the linked list. + +@item +Point the @code{relevant_entry} field of the descriptor at the code entry. + +@item +Set @code{action_flag} to @code{JIT_UNREGISTER} and call +@code{__jit_debug_register_code}. +@end itemize + +If the JIT frees or recompiles code without unregistering it, then @value{GDBN} +and the JIT will leak the memory used for the associated symbol files. + +@node Custom Debug Info +@section Custom Debug Info +@cindex custom JIT debug info +@cindex JIT debug info reader + +Generating debug information in platform-native file formats (like ELF +or COFF) may be an overkill for JIT compilers; especially if all the +debug info is used for is displaying a meaningful backtrace. The +issue can be resolved by having the JIT writers decide on a debug info +format and also provide a reader that parses the debug info generated +by the JIT compiler. This section gives a brief overview on writing +such a parser. More specific details can be found in the source file +@file{gdb/jit-reader.in}, which is also installed as a header at +@file{@var{includedir}/gdb/jit-reader.h} for easy inclusion. + +The reader is implemented as a shared object (so this functionality is +not available on platforms which don't allow loading shared objects at +runtime). Two @value{GDBN} commands, @code{jit-reader-load} and +@code{jit-reader-unload} are provided, to be used to load and unload +the readers from a preconfigured directory. Once loaded, the shared +object is used the parse the debug information emitted by the JIT +compiler. + +@menu +* Using JIT Debug Info Readers:: How to use supplied readers correctly +* Writing JIT Debug Info Readers:: Creating a debug-info reader +@end menu + +@node Using JIT Debug Info Readers +@subsection Using JIT Debug Info Readers +@kindex jit-reader-load +@kindex jit-reader-unload + +Readers can be loaded and unloaded using the @code{jit-reader-load} +and @code{jit-reader-unload} commands. + +@table @code +@item jit-reader-load @var{reader} +Load the JIT reader named @var{reader}, which is a shared +object specified as either an absolute or a relative file name. In +the latter case, @value{GDBN} will try to load the reader from a +pre-configured directory, usually @file{@var{libdir}/gdb/} on a UNIX +system (here @var{libdir} is the system library directory, often +@file{/usr/local/lib}). + +Only one reader can be active at a time; trying to load a second +reader when one is already loaded will result in @value{GDBN} +reporting an error. A new JIT reader can be loaded by first unloading +the current one using @code{jit-reader-unload} and then invoking +@code{jit-reader-load}. + +@item show jit-reader-directory +This command will show the directory that is used by +@code{jit-reader-load} when a relative file name is specified. + +@item jit-reader-unload +Unload the currently loaded JIT reader. + +@end table + +@node Writing JIT Debug Info Readers +@subsection Writing JIT Debug Info Readers +@cindex writing JIT debug info readers + +As mentioned, a reader is essentially a shared object conforming to a +certain ABI. This ABI is described in @file{jit-reader.h}. + +@file{jit-reader.h} defines the structures, macros and functions +required to write a reader. It is installed (along with +@value{GDBN}), in @file{@var{includedir}/gdb} where @var{includedir} is +the system include directory. + +Readers need to be released under a GPL compatible license. A reader +can be declared as released under such a license by placing the macro +@code{GDB_DECLARE_GPL_COMPATIBLE_READER} in a source file. + +The entry point for readers is the symbol @code{gdb_init_reader}, +which is expected to be a function with the prototype + +@findex gdb_init_reader +@smallexample +extern struct gdb_reader_funcs *gdb_init_reader (void); +@end smallexample + +@cindex @code{struct gdb_reader_funcs} + +@code{struct gdb_reader_funcs} contains a set of pointers to callback +functions. These functions are executed to read the debug info +generated by the JIT compiler (@code{read}), to unwind stack frames +(@code{unwind}) and to create canonical frame IDs +(@code{get_frame_id}). It also has a callback that is called when the +reader is being unloaded (@code{destroy}). The struct looks like this + +@smallexample +struct gdb_reader_funcs +@{ + /* Must be set to GDB_READER_INTERFACE_VERSION. */ + int reader_version; + + /* For use by the reader. */ + void *priv_data; + + gdb_read_debug_info *read; + gdb_unwind_frame *unwind; + gdb_get_frame_id *get_frame_id; + gdb_destroy_reader *destroy; +@}; +@end smallexample + +@cindex @code{struct gdb_symbol_callbacks} +@cindex @code{struct gdb_unwind_callbacks} + +The callbacks are provided with another set of callbacks by +@value{GDBN} to do their job. For @code{read}, these callbacks are +passed in a @code{struct gdb_symbol_callbacks} and for @code{unwind} +and @code{get_frame_id}, in a @code{struct gdb_unwind_callbacks}. +@code{struct gdb_symbol_callbacks} has callbacks to create new object +files and new symbol tables inside those object files. @code{struct +gdb_unwind_callbacks} has callbacks to read registers off the current +frame and to write out the values of the registers in the previous +frame. Both have a callback (@code{target_read}) to read bytes off the +target's address space. + +@node In-Process Agent +@chapter In-Process Agent +@cindex debugging agent +The traditional debugging model is conceptually low-speed, but works fine, +because most bugs can be reproduced in debugging-mode execution. However, +as multi-core or many-core processors are becoming mainstream, and +multi-threaded programs become more and more popular, there should be more +and more bugs that only manifest themselves at normal-mode execution, for +example, thread races, because debugger's interference with the program's +timing may conceal the bugs. On the other hand, in some applications, +it is not feasible for the debugger to interrupt the program's execution +long enough for the developer to learn anything helpful about its behavior. +If the program's correctness depends on its real-time behavior, delays +introduced by a debugger might cause the program to fail, even when the +code itself is correct. It is useful to be able to observe the program's +behavior without interrupting it. + +Therefore, traditional debugging model is too intrusive to reproduce +some bugs. In order to reduce the interference with the program, we can +reduce the number of operations performed by debugger. The +@dfn{In-Process Agent}, a shared library, is running within the same +process with inferior, and is able to perform some debugging operations +itself. As a result, debugger is only involved when necessary, and +performance of debugging can be improved accordingly. Note that +interference with program can be reduced but can't be removed completely, +because the in-process agent will still stop or slow down the program. + +The in-process agent can interpret and execute Agent Expressions +(@pxref{Agent Expressions}) during performing debugging operations. The +agent expressions can be used for different purposes, such as collecting +data in tracepoints, and condition evaluation in breakpoints. + +@anchor{Control Agent} +You can control whether the in-process agent is used as an aid for +debugging with the following commands: + +@table @code +@kindex set agent on +@item set agent on +Causes the in-process agent to perform some operations on behalf of the +debugger. Just which operations requested by the user will be done +by the in-process agent depends on the its capabilities. For example, +if you request to evaluate breakpoint conditions in the in-process agent, +and the in-process agent has such capability as well, then breakpoint +conditions will be evaluated in the in-process agent. + +@kindex set agent off +@item set agent off +Disables execution of debugging operations by the in-process agent. All +of the operations will be performed by @value{GDBN}. + +@kindex show agent +@item show agent +Display the current setting of execution of debugging operations by +the in-process agent. +@end table + +@menu +* In-Process Agent Protocol:: +@end menu + +@node In-Process Agent Protocol +@section In-Process Agent Protocol +@cindex in-process agent protocol + +The in-process agent is able to communicate with both @value{GDBN} and +GDBserver (@pxref{In-Process Agent}). This section documents the protocol +used for communications between @value{GDBN} or GDBserver and the IPA. +In general, @value{GDBN} or GDBserver sends commands +(@pxref{IPA Protocol Commands}) and data to in-process agent, and then +in-process agent replies back with the return result of the command, or +some other information. The data sent to in-process agent is composed +of primitive data types, such as 4-byte or 8-byte type, and composite +types, which are called objects (@pxref{IPA Protocol Objects}). + +@menu +* IPA Protocol Objects:: +* IPA Protocol Commands:: +@end menu + +@node IPA Protocol Objects +@subsection IPA Protocol Objects +@cindex ipa protocol objects + +The commands sent to and results received from agent may contain some +complex data types called @dfn{objects}. + +The in-process agent is running on the same machine with @value{GDBN} +or GDBserver, so it doesn't have to handle as much differences between +two ends as remote protocol (@pxref{Remote Protocol}) tries to handle. +However, there are still some differences of two ends in two processes: + +@enumerate +@item +word size. On some 64-bit machines, @value{GDBN} or GDBserver can be +compiled as a 64-bit executable, while in-process agent is a 32-bit one. +@item +ABI. Some machines may have multiple types of ABI, @value{GDBN} or +GDBserver is compiled with one, and in-process agent is compiled with +the other one. +@end enumerate + +Here are the IPA Protocol Objects: + +@enumerate +@item +agent expression object. It represents an agent expression +(@pxref{Agent Expressions}). +@anchor{agent expression object} +@item +tracepoint action object. It represents a tracepoint action +(@pxref{Tracepoint Actions,,Tracepoint Action Lists}) to collect registers, +memory, static trace data and to evaluate expression. +@anchor{tracepoint action object} +@item +tracepoint object. It represents a tracepoint (@pxref{Tracepoints}). +@anchor{tracepoint object} + +@end enumerate + +The following table describes important attributes of each IPA protocol +object: + +@multitable @columnfractions .30 .20 .50 +@headitem Name @tab Size @tab Description +@item @emph{agent expression object} @tab @tab +@item length @tab 4 @tab length of bytes code +@item byte code @tab @var{length} @tab contents of byte code +@item @emph{tracepoint action for collecting memory} @tab @tab +@item 'M' @tab 1 @tab type of tracepoint action +@item addr @tab 8 @tab if @var{basereg} is @samp{-1}, @var{addr} is the +address of the lowest byte to collect, otherwise @var{addr} is the offset +of @var{basereg} for memory collecting. +@item len @tab 8 @tab length of memory for collecting +@item basereg @tab 4 @tab the register number containing the starting +memory address for collecting. +@item @emph{tracepoint action for collecting registers} @tab @tab +@item 'R' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for collecting static trace data} @tab @tab +@item 'L' @tab 1 @tab type of tracepoint action +@item @emph{tracepoint action for expression evaluation} @tab @tab +@item 'X' @tab 1 @tab type of tracepoint action +@item agent expression @tab length of @tab @ref{agent expression object} +@item @emph{tracepoint object} @tab @tab +@item number @tab 4 @tab number of tracepoint +@item address @tab 8 @tab address of tracepoint inserted on +@item type @tab 4 @tab type of tracepoint +@item enabled @tab 1 @tab enable or disable of tracepoint +@item step_count @tab 8 @tab step +@item pass_count @tab 8 @tab pass +@item numactions @tab 4 @tab number of tracepoint actions +@item hit count @tab 8 @tab hit count +@item trace frame usage @tab 8 @tab trace frame usage +@item compiled_cond @tab 8 @tab compiled condition +@item orig_size @tab 8 @tab orig size +@item condition @tab 4 if condition is NULL otherwise length of +@ref{agent expression object} +@tab zero if condition is NULL, otherwise is +@ref{agent expression object} +@item actions @tab variable +@tab numactions number of @ref{tracepoint action object} +@end multitable + +@node IPA Protocol Commands +@subsection IPA Protocol Commands +@cindex ipa protocol commands + +The spaces in each command are delimiters to ease reading this commands +specification. They don't exist in real commands. + +@table @samp + +@item FastTrace:@var{tracepoint_object} @var{gdb_jump_pad_head} +Installs a new fast tracepoint described by @var{tracepoint_object} +(@pxref{tracepoint object}). The @var{gdb_jump_pad_head}, 8-byte long, is the +head of @dfn{jumppad}, which is used to jump to data collection routine +in IPA finally. + +Replies: +@table @samp +@item OK @var{target_address} @var{gdb_jump_pad_head} @var{fjump_size} @var{fjump} +@var{target_address} is address of tracepoint in the inferior. +The @var{gdb_jump_pad_head} is updated head of jumppad. Both of +@var{target_address} and @var{gdb_jump_pad_head} are 8-byte long. +The @var{fjump} contains a sequence of instructions jump to jumppad entry. +The @var{fjump_size}, 4-byte long, is the size of @var{fjump}. + +@end table + +@item close +Closes the in-process agent. This command is sent when @value{GDBN} or GDBserver +is about to kill inferiors. + +@item qTfSTM +@xref{qTfSTM}. +@item qTsSTM +@xref{qTsSTM}. +@item qTSTMat +@xref{qTSTMat}. +@item probe_marker_at:@var{address} +Asks in-process agent to probe the marker at @var{address}. + +Replies: +@table @samp +@end table +@item unprobe_marker_at:@var{address} +Asks in-process agent to unprobe the marker at @var{address}. +@end table + +@node GDB Bugs +@chapter Reporting Bugs in @value{GDBN} +@cindex bugs in @value{GDBN} +@cindex reporting bugs in @value{GDBN} + +Your bug reports play an essential role in making @value{GDBN} reliable. + +Reporting a bug may help you by bringing a solution to your problem, or it +may not. But in any case the principal function of a bug report is to help +the entire community by making the next version of @value{GDBN} work better. Bug +reports are your contribution to the maintenance of @value{GDBN}. + +In order for a bug report to serve its purpose, you must include the +information that enables us to fix the bug. + +@menu +* Bug Criteria:: Have you found a bug? +* Bug Reporting:: How to report bugs +@end menu + +@node Bug Criteria +@section Have You Found a Bug? +@cindex bug criteria + +If you are not sure whether you have found a bug, here are some guidelines: + +@itemize @bullet +@cindex fatal signal +@cindex debugger crash +@cindex crash of debugger +@item +If the debugger gets a fatal signal, for any input whatever, that is a +@value{GDBN} bug. Reliable debuggers never crash. + +@cindex error on valid input +@item +If @value{GDBN} produces an error message for valid input, that is a +bug. (Note that if you're cross debugging, the problem may also be +somewhere in the connection to the target.) + +@cindex invalid input +@item +If @value{GDBN} does not produce an error message for invalid input, +that is a bug. However, you should note that your idea of +``invalid input'' might be our idea of ``an extension'' or ``support +for traditional practice''. + +@item +If you are an experienced user of debugging tools, your suggestions +for improvement of @value{GDBN} are welcome in any case. +@end itemize + +@node Bug Reporting +@section How to Report Bugs +@cindex bug reports +@cindex @value{GDBN} bugs, reporting + +A number of companies and individuals offer support for @sc{gnu} products. +If you obtained @value{GDBN} from a support organization, we recommend you +contact that organization first. + +You can find contact information for many support companies and +individuals in the file @file{etc/SERVICE} in the @sc{gnu} Emacs +distribution. +@c should add a web page ref... + +@ifset BUGURL +@ifset BUGURL_DEFAULT +In any event, we also recommend that you submit bug reports for +@value{GDBN}. The preferred method is to submit them directly using +@uref{http://www.gnu.org/software/gdb/bugs/, @value{GDBN}'s Bugs web +page}. Alternatively, the @email{bug-gdb@@gnu.org, e-mail gateway} can +be used. + +@strong{Do not send bug reports to @samp{info-gdb}, or to +@samp{help-gdb}, or to any newsgroups.} Most users of @value{GDBN} do +not want to receive bug reports. Those that do have arranged to receive +@samp{bug-gdb}. + +The mailing list @samp{bug-gdb} has a newsgroup @samp{gnu.gdb.bug} which +serves as a repeater. The mailing list and the newsgroup carry exactly +the same messages. Often people think of posting bug reports to the +newsgroup instead of mailing them. This appears to work, but it has one +problem which can be crucial: a newsgroup posting often lacks a mail +path back to the sender. Thus, if we need to ask for more information, +we may be unable to reach you. For this reason, it is better to send +bug reports to the mailing list. +@end ifset +@ifclear BUGURL_DEFAULT +In any event, we also recommend that you submit bug reports for +@value{GDBN} to @value{BUGURL}. +@end ifclear +@end ifset + +The fundamental principle of reporting bugs usefully is this: +@strong{report all the facts}. If you are not sure whether to state a +fact or leave it out, state it! + +Often people omit facts because they think they know what causes the +problem and assume that some details do not matter. Thus, you might +assume that the name of the variable you use in an example does not matter. +Well, probably it does not, but one cannot be sure. Perhaps the bug is a +stray memory reference which happens to fetch from the location where that +name is stored in memory; perhaps, if the name were different, the contents +of that location would fool the debugger into doing the right thing despite +the bug. Play it safe and give a specific, complete example. That is the +easiest thing for you to do, and the most helpful. + +Keep in mind that the purpose of a bug report is to enable us to fix the +bug. It may be that the bug has been reported previously, but neither +you nor we can know that unless your bug report is complete and +self-contained. + +Sometimes people give a few sketchy facts and ask, ``Does this ring a +bell?'' Those bug reports are useless, and we urge everyone to +@emph{refuse to respond to them} except to chide the sender to report +bugs properly. + +To enable us to fix the bug, you should include all these things: + +@itemize @bullet +@item +The version of @value{GDBN}. @value{GDBN} announces it if you start +with no arguments; you can also print it at any time using @code{show +version}. + +Without this, we will not know whether there is any point in looking for +the bug in the current version of @value{GDBN}. + +@item +The type of machine you are using, and the operating system name and +version number. + +@item +The details of the @value{GDBN} build-time configuration. +@value{GDBN} shows these details if you invoke it with the +@option{--configuration} command-line option, or if you type +@code{show configuration} at @value{GDBN}'s prompt. + +@item +What compiler (and its version) was used to compile @value{GDBN}---e.g.@: +``@value{GCC}--2.8.1''. + +@item +What compiler (and its version) was used to compile the program you are +debugging---e.g.@: ``@value{GCC}--2.8.1'', or ``HP92453-01 A.10.32.03 HP +C Compiler''. For @value{NGCC}, you can say @kbd{@value{GCC} --version} +to get this information; for other compilers, see the documentation for +those compilers. + +@item +The command arguments you gave the compiler to compile your example and +observe the bug. For example, did you use @samp{-O}? To guarantee +you will not omit something important, list them all. A copy of the +Makefile (or the output from make) is sufficient. + +If we were to try to guess the arguments, we would probably guess wrong +and then we might not encounter the bug. + +@item +A complete input script, and all necessary source files, that will +reproduce the bug. + +@item +A description of what behavior you observe that you believe is +incorrect. For example, ``It gets a fatal signal.'' + +Of course, if the bug is that @value{GDBN} gets a fatal signal, then we +will certainly notice it. But if the bug is incorrect output, we might +not notice unless it is glaringly wrong. You might as well not give us +a chance to make a mistake. + +Even if the problem you experience is a fatal signal, you should still +say so explicitly. Suppose something strange is going on, such as, your +copy of @value{GDBN} is out of synch, or you have encountered a bug in +the C library on your system. (This has happened!) Your copy might +crash and ours would not. If you told us to expect a crash, then when +ours fails to crash, we would know that the bug was not happening for +us. If you had not told us to expect a crash, then we would not be able +to draw any conclusion from our observations. + +@pindex script +@cindex recording a session script +To collect all this information, you can use a session recording program +such as @command{script}, which is available on many Unix systems. +Just run your @value{GDBN} session inside @command{script} and then +include the @file{typescript} file with your bug report. + +Another way to record a @value{GDBN} session is to run @value{GDBN} +inside Emacs and then save the entire buffer to a file. + +@item +If you wish to suggest changes to the @value{GDBN} source, send us context +diffs. If you even discuss something in the @value{GDBN} source, refer to +it by context, not by line number. + +The line numbers in our development sources will not match those in your +sources. Your line numbers would convey no useful information to us. + +@end itemize + +Here are some things that are not necessary: + +@itemize @bullet +@item +A description of the envelope of the bug. + +Often people who encounter a bug spend a lot of time investigating +which changes to the input file will make the bug go away and which +changes will not affect it. + +This is often time consuming and not very useful, because the way we +will find the bug is by running a single example under the debugger +with breakpoints, not by pure deduction from a series of examples. +We recommend that you save your time for something else. + +Of course, if you can find a simpler example to report @emph{instead} +of the original one, that is a convenience for us. Errors in the +output will be easier to spot, running under the debugger will take +less time, and so on. + +However, simplification is not vital; if you do not want to do this, +report the bug anyway and send us the entire test case you used. + +@item +A patch for the bug. + +A patch for the bug does help us if it is a good one. But do not omit +the necessary information, such as the test case, on the assumption that +a patch is all we need. We might see problems with your patch and decide +to fix the problem another way, or we might not understand it at all. + +Sometimes with a program as complicated as @value{GDBN} it is very hard to +construct an example that will make the program follow a certain path +through the code. If you do not send us the example, we will not be able +to construct one, so we will not be able to verify that the bug is fixed. + +And if we cannot understand what bug you are trying to fix, or why your +patch should be an improvement, we will not install it. A test case will +help us to understand. + +@item +A guess about what the bug is or what it depends on. + +Such guesses are usually wrong. Even we cannot guess right about such +things without first using the debugger to find the facts. +@end itemize + +@c The readline documentation is distributed with the readline code +@c and consists of the two following files: +@c rluser.texi +@c hsuser.texi +@c Use -I with makeinfo to point to the appropriate directory, +@c environment var TEXINPUTS with TeX. +@ifclear SYSTEM_READLINE +@include rluser.texi +@include hsuser.texi +@end ifclear + +@node In Memoriam +@appendix In Memoriam + +The @value{GDBN} project mourns the loss of the following long-time +contributors: + +@table @code +@item Fred Fish +Fred was a long-standing contributor to @value{GDBN} (1991-2006), and +to Free Software in general. Outside of @value{GDBN}, he was known in +the Amiga world for his series of Fish Disks, and the GeekGadget project. + +@item Michael Snyder +Michael was one of the Global Maintainers of the @value{GDBN} project, +with contributions recorded as early as 1996, until 2011. In addition +to his day to day participation, he was a large driving force behind +adding Reverse Debugging to @value{GDBN}. +@end table + +Beyond their technical contributions to the project, they were also +enjoyable members of the Free Software Community. We will miss them. + +@node Formatting Documentation +@appendix Formatting Documentation + +@cindex @value{GDBN} reference card +@cindex reference card +The @value{GDBN} 4 release includes an already-formatted reference card, ready +for printing with PostScript or Ghostscript, in the @file{gdb} +subdirectory of the main source directory@footnote{In +@file{gdb-@value{GDBVN}/gdb/refcard.ps} of the version @value{GDBVN} +release.}. If you can use PostScript or Ghostscript with your printer, +you can print the reference card immediately with @file{refcard.ps}. + +The release also includes the source for the reference card. You +can format it, using @TeX{}, by typing: + +@smallexample +make refcard.dvi +@end smallexample + +The @value{GDBN} reference card is designed to print in @dfn{landscape} +mode on US ``letter'' size paper; +that is, on a sheet 11 inches wide by 8.5 inches +high. You will need to specify this form of printing as an option to +your @sc{dvi} output program. + +@cindex documentation + +All the documentation for @value{GDBN} comes as part of the machine-readable +distribution. The documentation is written in Texinfo format, which is +a documentation system that uses a single source file to produce both +on-line information and a printed manual. You can use one of the Info +formatting commands to create the on-line version of the documentation +and @TeX{} (or @code{texi2roff}) to typeset the printed version. + +@value{GDBN} includes an already formatted copy of the on-line Info +version of this manual in the @file{gdb} subdirectory. The main Info +file is @file{gdb-@value{GDBVN}/gdb/gdb.info}, and it refers to +subordinate files matching @samp{gdb.info*} in the same directory. If +necessary, you can print out these files, or read them with any editor; +but they are easier to read using the @code{info} subsystem in @sc{gnu} +Emacs or the standalone @code{info} program, available as part of the +@sc{gnu} Texinfo distribution. + +If you want to format these Info files yourself, you need one of the +Info formatting programs, such as @code{texinfo-format-buffer} or +@code{makeinfo}. + +If you have @code{makeinfo} installed, and are in the top level +@value{GDBN} source directory (@file{gdb-@value{GDBVN}}, in the case of +version @value{GDBVN}), you can make the Info file by typing: + +@smallexample +cd gdb +make gdb.info +@end smallexample + +If you want to typeset and print copies of this manual, you need @TeX{}, +a program to print its @sc{dvi} output files, and @file{texinfo.tex}, the +Texinfo definitions file. + +@TeX{} is a typesetting program; it does not print files directly, but +produces output files called @sc{dvi} files. To print a typeset +document, you need a program to print @sc{dvi} files. If your system +has @TeX{} installed, chances are it has such a program. The precise +command to use depends on your system; @kbd{lpr -d} is common; another +(for PostScript devices) is @kbd{dvips}. The @sc{dvi} print command may +require a file name without any extension or a @samp{.dvi} extension. + +@TeX{} also requires a macro definitions file called +@file{texinfo.tex}. This file tells @TeX{} how to typeset a document +written in Texinfo format. On its own, @TeX{} cannot either read or +typeset a Texinfo file. @file{texinfo.tex} is distributed with GDB +and is located in the @file{gdb-@var{version-number}/texinfo} +directory. + +If you have @TeX{} and a @sc{dvi} printer program installed, you can +typeset and print this manual. First switch to the @file{gdb} +subdirectory of the main source directory (for example, to +@file{gdb-@value{GDBVN}/gdb}) and type: + +@smallexample +make gdb.dvi +@end smallexample + +Then give @file{gdb.dvi} to your @sc{dvi} printing program. + +@node Installing GDB +@appendix Installing @value{GDBN} +@cindex installation + +@menu +* Requirements:: Requirements for building @value{GDBN} +* Running Configure:: Invoking the @value{GDBN} @file{configure} script +* Separate Objdir:: Compiling @value{GDBN} in another directory +* Config Names:: Specifying names for hosts and targets +* Configure Options:: Summary of options for configure +* System-wide configuration:: Having a system-wide init file +@end menu + +@node Requirements +@section Requirements for Building @value{GDBN} +@cindex building @value{GDBN}, requirements for + +Building @value{GDBN} requires various tools and packages to be available. +Other packages will be used only if they are found. + +@heading Tools/Packages Necessary for Building @value{GDBN} +@table @asis +@item C@t{++}17 compiler +@value{GDBN} is written in C@t{++}17. It should be buildable with any +recent C@t{++}17 compiler, e.g.@: GCC. + +@item GNU make +@value{GDBN}'s build system relies on features only found in the GNU +make program. Other variants of @code{make} will not work. + +@item Libraries +The following libraries are mandatory for building @value{GDBN}. The +@file{configure} script searches for each of these libraries in +several standard locations; if some library is installed in an unusual +place, you can use either the @option{--with-@var{lib}} +@file{configure} option to specify its installation directory, or +the two separate options @option{---with-@var{library}-include} (to +specify the location of its header files) and +@option{--with-@var{library}-lib} (to specify the location of its +libraries). For example, for the GMP library, the 3 options are +@option{--with-gmp}, @option{--with-gmp-include}, and +@option{--with-gmp-lib}. @xref{Configure Options}. We mention below +the home site of each library, so that you could download and install +them if your system doesn't already include them. + +@table @asis +@item GMP (The GNU Multiple Precision arithmetic library) +@value{GDBN} uses GMP to perform some of its extended-precision +arithmetic. The latest version of GMP is available from +@url{https://gmplib.org/}. + +@anchor{MPFR} +@item MPFR (The GNU Multiple-precision floating-point library) +@value{GDBN} uses MPFR to emulate the target floating-point +arithmetic during expression evaluation, if the target uses different +floating-point formats than the host. The latest version of MPFR is +available from @url{http://www.mpfr.org}. +@end table + +@end table + +@heading Tools/Packages Optional for Building @value{GDBN} +The tools/packages and libraries listed below are optional; +@value{GDBN} can be build without them, at the expense of some run-time +functionality that will be missing. As above, we list the home sites +for each package/library, and the command-line options supported by +the @file{configure} script to specify their installation directories +if they are non-standard. In addition, for each package you can use +the option @option{--with-@var{package}} to force @value{GDBN} to be +compiled with the named @var{package}, and +@option{--without-@var{package}} to disable building with it even if +it is available. @xref{Configure Options}, for detailed description +of the options to @file{configure}. + +@table @asis +@item Python +@value{GDBN} can be scripted using Python language. @xref{Python}. +The latest version is available from +@url{https://www.python.org/downloads/}. Use the +@option{--with-python=@var{dir}} to specify the non-standard directory +where Python is installed. + +@item Guile +@value{GDBN} can also be scripted using GNU Guile. @xref{Guile}. The +latest version can be found on +@url{https://www.gnu.org/software/guile/download/}. If you have more +than one version of Guile installed, use the +@option{--with-guile=@var{guile-version}} to specify the Guile version +to include in the build. + +@anchor{Expat} +@item Expat +If available, @value{GDBN} uses the Expat library for parsing XML +files. @value{GDBN} uses XML files for the following functionalities: + +@itemize @bullet +@item +Remote protocol memory maps (@pxref{Memory Map Format}) +@item +Target descriptions (@pxref{Target Descriptions}) +@item +Remote shared library lists (@xref{Library List Format}, +or alternatively @pxref{Library List Format for SVR4 Targets}) +@item +MS-Windows shared libraries (@pxref{Shared Libraries}) +@item +Traceframe info (@pxref{Traceframe Info Format}) +@item +Branch trace (@pxref{Branch Trace Format}, +@pxref{Branch Trace Configuration Format}) +@end itemize + +The latest version of Expat is available from +@url{http://expat.sourceforge.net}. Use the +@option{--with-libexpat-prefix} to specify non-standard installation +places for Expat. + +@item iconv +@value{GDBN}'s features related to character sets (@pxref{Character +Sets}) require a functioning @code{iconv} implementation. If you are +on a GNU system, then this is provided by the GNU C Library. Some +other systems also provide a working @code{iconv}. Use the option +@option{--with-iconv-bin} to specify where to find the @command{iconv} +program. + +On systems without @code{iconv}, you can install the GNU Libiconv +library; its latest version can be found on +@url{https://ftp.gnu.org/pub/gnu/libiconv/} if your system doesn't +provide it. Use the @option{--with-libiconv-prefix} option to +@file{configure} to specify non-standard installation place for it. + +Alternatively, @value{GDBN}'s top-level @file{configure} and +@file{Makefile} will arrange to build Libiconv if a directory named +@file{libiconv} appears in the top-most source directory. If Libiconv +is built this way, and if the operating system does not provide a +suitable @code{iconv} implementation, then the just-built library will +automatically be used by @value{GDBN}. One easy way to set this up is +to download GNU Libiconv, unpack it inside the top-level directory of +the @value{GDBN} source tree, and then rename the directory holding +the Libiconv source code to @samp{libiconv}. + +@cindex compressed debug sections +@item lzma +@value{GDBN} can support debugging sections that are compressed with +the LZMA library. @xref{MiniDebugInfo}. If this library is not +included with your operating system, you can find it in the xz package +at @url{http://tukaani.org/xz/}. Use the +@option{--with-liblzma-prefix} option to specify its non-standard +location. + +@item zlib +@value{GDBN} will use the @samp{zlib} library, if available, to read +compressed debug sections. Some linkers, such as GNU @command{gold}, +are capable of producing binaries with compressed debug sections. If +@value{GDBN} is compiled with @samp{zlib}, it will be able to read the +debug information in such binaries. + +The @samp{zlib} library is likely included with your operating system +distribution; if it is not, you can get the latest version from +@url{http://zlib.net}. + +@c FIXME: what about other optional libraries: debuginfod, zstd, +@c libipt, babeltrace, xxhash, source-highlight? +@end table + +@node Running Configure +@section Invoking the @value{GDBN} @file{configure} Script +@cindex configuring @value{GDBN} +@value{GDBN} comes with a @file{configure} script that automates the process +of preparing @value{GDBN} for installation; you can then use @code{make} to +build the @code{gdb} program. +@iftex +@c irrelevant in info file; it's as current as the code it lives with. +@footnote{If you have a more recent version of @value{GDBN} than @value{GDBVN}, +look at the @file{README} file in the sources; we may have improved the +installation procedures since publishing this manual.} +@end iftex + +The @value{GDBN} distribution includes all the source code you need for +@value{GDBN} in a single directory, whose name is usually composed by +appending the version number to @samp{gdb}. + +For example, the @value{GDBN} version @value{GDBVN} distribution is in the +@file{gdb-@value{GDBVN}} directory. That directory contains: + +@table @code +@item gdb-@value{GDBVN}/configure @r{(and supporting files)} +script for configuring @value{GDBN} and all its supporting libraries + +@item gdb-@value{GDBVN}/gdb +the source specific to @value{GDBN} itself + +@item gdb-@value{GDBVN}/bfd +source for the Binary File Descriptor library + +@item gdb-@value{GDBVN}/include +@sc{gnu} include files + +@item gdb-@value{GDBVN}/libiberty +source for the @samp{-liberty} free software library + +@item gdb-@value{GDBVN}/opcodes +source for the library of opcode tables and disassemblers + +@item gdb-@value{GDBVN}/readline +source for the @sc{gnu} command-line interface +@end table + +There may be other subdirectories as well. + +The simplest way to configure and build @value{GDBN} is to run @file{configure} +from the @file{gdb-@var{version-number}} source directory, which in +this example is the @file{gdb-@value{GDBVN}} directory. + +First switch to the @file{gdb-@var{version-number}} source directory +if you are not already in it; then run @file{configure}. Pass the +identifier for the platform on which @value{GDBN} will run as an +argument. + +For example: + +@smallexample +cd gdb-@value{GDBVN} +./configure +make +@end smallexample + +Running @samp{configure} and then running @code{make} builds the +included supporting libraries, then @code{gdb} itself. The configured +source files, and the binaries, are left in the corresponding source +directories. + +@need 750 +@file{configure} is a Bourne-shell (@code{/bin/sh}) script; if your +system does not recognize this automatically when you run a different +shell, you may need to run @code{sh} on it explicitly: + +@smallexample +sh configure +@end smallexample + +You should run the @file{configure} script from the top directory in the +source tree, the @file{gdb-@var{version-number}} directory. If you run +@file{configure} from one of the subdirectories, you will configure only +that subdirectory. That is usually not what you want. In particular, +if you run the first @file{configure} from the @file{gdb} subdirectory +of the @file{gdb-@var{version-number}} directory, you will omit the +configuration of @file{bfd}, @file{readline}, and other sibling +directories of the @file{gdb} subdirectory. This leads to build errors +about missing include files such as @file{bfd/bfd.h}. + +You can install @code{@value{GDBN}} anywhere. The best way to do this +is to pass the @code{--prefix} option to @code{configure}, and then +install it with @code{make install}. + +@node Separate Objdir +@section Compiling @value{GDBN} in Another Directory + +If you want to run @value{GDBN} versions for several host or target machines, +you need a different @code{gdb} compiled for each combination of +host and target. @file{configure} is designed to make this easy by +allowing you to generate each configuration in a separate subdirectory, +rather than in the source directory. If your @code{make} program +handles the @samp{VPATH} feature (@sc{gnu} @code{make} does), running +@code{make} in each of these directories builds the @code{gdb} +program specified there. + +To build @code{gdb} in a separate directory, run @file{configure} +with the @samp{--srcdir} option to specify where to find the source. +(You also need to specify a path to find @file{configure} +itself from your working directory. If the path to @file{configure} +would be the same as the argument to @samp{--srcdir}, you can leave out +the @samp{--srcdir} option; it is assumed.) + +For example, with version @value{GDBVN}, you can build @value{GDBN} in a +separate directory for a Sun 4 like this: + +@smallexample +@group +cd gdb-@value{GDBVN} +mkdir ../gdb-sun4 +cd ../gdb-sun4 +../gdb-@value{GDBVN}/configure +make +@end group +@end smallexample + +When @file{configure} builds a configuration using a remote source +directory, it creates a tree for the binaries with the same structure +(and using the same names) as the tree under the source directory. In +the example, you'd find the Sun 4 library @file{libiberty.a} in the +directory @file{gdb-sun4/libiberty}, and @value{GDBN} itself in +@file{gdb-sun4/gdb}. + +Make sure that your path to the @file{configure} script has just one +instance of @file{gdb} in it. If your path to @file{configure} looks +like @file{../gdb-@value{GDBVN}/gdb/configure}, you are configuring only +one subdirectory of @value{GDBN}, not the whole package. This leads to +build errors about missing include files such as @file{bfd/bfd.h}. + +One popular reason to build several @value{GDBN} configurations in separate +directories is to configure @value{GDBN} for cross-compiling (where +@value{GDBN} runs on one machine---the @dfn{host}---while debugging +programs that run on another machine---the @dfn{target}). +You specify a cross-debugging target by +giving the @samp{--target=@var{target}} option to @file{configure}. + +When you run @code{make} to build a program or library, you must run +it in a configured directory---whatever directory you were in when you +called @file{configure} (or one of its subdirectories). + +The @code{Makefile} that @file{configure} generates in each source +directory also runs recursively. If you type @code{make} in a source +directory such as @file{gdb-@value{GDBVN}} (or in a separate configured +directory configured with @samp{--srcdir=@var{dirname}/gdb-@value{GDBVN}}), you +will build all the required libraries, and then build GDB. + +When you have multiple hosts or targets configured in separate +directories, you can run @code{make} on them in parallel (for example, +if they are NFS-mounted on each of the hosts); they will not interfere +with each other. + +@node Config Names +@section Specifying Names for Hosts and Targets + +The specifications used for hosts and targets in the @file{configure} +script are based on a three-part naming scheme, but some short predefined +aliases are also supported. The full naming scheme encodes three pieces +of information in the following pattern: + +@smallexample +@var{architecture}-@var{vendor}-@var{os} +@end smallexample + +For example, you can use the alias @code{sun4} as a @var{host} argument, +or as the value for @var{target} in a @code{--target=@var{target}} +option. The equivalent full name is @samp{sparc-sun-sunos4}. + +The @file{configure} script accompanying @value{GDBN} does not provide +any query facility to list all supported host and target names or +aliases. @file{configure} calls the Bourne shell script +@code{config.sub} to map abbreviations to full names; you can read the +script, if you wish, or you can use it to test your guesses on +abbreviations---for example: + +@smallexample +% sh config.sub i386-linux +i386-pc-linux-gnu +% sh config.sub alpha-linux +alpha-unknown-linux-gnu +% sh config.sub hp9k700 +hppa1.1-hp-hpux +% sh config.sub sun4 +sparc-sun-sunos4.1.1 +% sh config.sub sun3 +m68k-sun-sunos4.1.1 +% sh config.sub i986v +Invalid configuration `i986v': machine `i986v' not recognized +@end smallexample + +@noindent +@code{config.sub} is also distributed in the @value{GDBN} source +directory (@file{gdb-@value{GDBVN}}, for version @value{GDBVN}). + +@node Configure Options +@section @file{configure} Options + +@c FIXME: This largely repeats what was already described in +@c ``Requirements'', and OTOH doesn't describe the more fgine-granular +@c options like --with-libexpat-prefix and --with-python-libdir. +@c Should it? +Here is a summary of the @file{configure} options and arguments that +are most often useful for building @value{GDBN}. @file{configure} +also has several other options not listed here. @xref{Running +configure Scripts,,,autoconf}, for a full +explanation of @file{configure}. + +@smallexample +configure @r{[}--help@r{]} + @r{[}--prefix=@var{dir}@r{]} + @r{[}--exec-prefix=@var{dir}@r{]} + @r{[}--srcdir=@var{dirname}@r{]} + @r{[}--target=@var{target}@r{]} +@end smallexample + +@noindent +You may introduce options with a single @samp{-} rather than +@samp{--} if you prefer; but you may abbreviate option names if you use +@samp{--}. + +@table @code +@item --help +Display a quick summary of how to invoke @file{configure}. + +@item --prefix=@var{dir} +Configure the source to install programs and files under directory +@file{@var{dir}}. + +@item --exec-prefix=@var{dir} +Configure the source to install programs under directory +@file{@var{dir}}. + +@c avoid splitting the warning from the explanation: +@need 2000 +@item --srcdir=@var{dirname} +Use this option to make configurations in directories separate from the +@value{GDBN} source directories. Among other things, you can use this to +build (or maintain) several configurations simultaneously, in separate +directories. @file{configure} writes configuration-specific files in +the current directory, but arranges for them to use the source in the +directory @var{dirname}. @file{configure} creates directories under +the working directory in parallel to the source directories below +@var{dirname}. + +@item --target=@var{target} +Configure @value{GDBN} for cross-debugging programs running on the specified +@var{target}. Without this option, @value{GDBN} is configured to debug +programs that run on the same machine (@var{host}) as @value{GDBN} itself. + +There is no convenient way to generate a list of all available +targets. Also see the @code{--enable-targets} option, below. +@end table + +There are many other options that are specific to @value{GDBN}. This +lists just the most common ones; there are some very specialized +options not described here. + +@table @code +@item --enable-targets=@r{[}@var{target}@r{]}@dots{} +@itemx --enable-targets=all +Configure @value{GDBN} for cross-debugging programs running on the +specified list of targets. The special value @samp{all} configures +@value{GDBN} for debugging programs running on any target it supports. + +@item --with-gdb-datadir=@var{path} +Set the @value{GDBN}-specific data directory. @value{GDBN} will look +here for certain supporting files or scripts. This defaults to the +@file{gdb} subdirectory of @samp{datadir} (which can be set using +@code{--datadir}). + +@item --with-relocated-sources=@var{dir} +Sets up the default source path substitution rule so that directory +names recorded in debug information will be automatically adjusted for +any directory under @var{dir}. @var{dir} should be a subdirectory of +@value{GDBN}'s configured prefix, the one mentioned in the +@code{--prefix} or @code{--exec-prefix} options to configure. This +option is useful if GDB is supposed to be moved to a different place +after it is built. + +@item --enable-64-bit-bfd +Enable 64-bit support in BFD on 32-bit hosts. + +@item --disable-gdbmi +Build @value{GDBN} without the GDB/MI machine interface +(@pxref{GDB/MI}). + +@item --enable-tui +Build @value{GDBN} with the text-mode full-screen user interface +(TUI). Requires a curses library (ncurses and cursesX are also +supported). + +@item --with-curses +Use the curses library instead of the termcap library, for text-mode +terminal operations. + +@item --with-debuginfod +Build @value{GDBN} with @file{libdebuginfod}, the @code{debuginfod} client +library. Used to automatically fetch ELF, DWARF and source files from +@code{debuginfod} servers using build IDs associated with any missing +files. Enabled by default if @file{libdebuginfod} is installed and found +at configure time. For more information regarding @code{debuginfod} see +@ref{Debuginfod}. + +@item --with-libunwind-ia64 +Use the libunwind library for unwinding function call stack on ia64 +target platforms. See @url{http://www.nongnu.org/libunwind/index.html} for +details. + +@item --with-system-readline +Use the readline library installed on the host, rather than the +library supplied as part of @value{GDBN}. Readline 7 or newer is +required; this is enforced by the build system. + +@item --with-system-zlib +Use the zlib library installed on the host, rather than the library +supplied as part of @value{GDBN}. + +@item --with-expat +Build @value{GDBN} with Expat, a library for XML parsing. (Done by +default if libexpat is installed and found at configure time.) This +library is used to read XML files supplied with @value{GDBN}. If it +is unavailable, some features, such as remote protocol memory maps, +target descriptions, and shared library lists, that are based on XML +files, will not be available in @value{GDBN}. If your host does not +have libexpat installed, you can get the latest version from +@url{http://expat.sourceforge.net}. + +@item --with-libiconv-prefix@r{[}=@var{dir}@r{]} +Build @value{GDBN} with GNU libiconv, a character set encoding +conversion library. This is not done by default, as on GNU systems +the @code{iconv} that is built in to the C library is sufficient. If +your host does not have a working @code{iconv}, you can get the latest +version of GNU iconv from @url{https://www.gnu.org/software/libiconv/}. + +@value{GDBN}'s build system also supports building GNU libiconv as +part of the overall build. @xref{Requirements}. + +@item --with-lzma +Build @value{GDBN} with LZMA, a compression library. (Done by default +if liblzma is installed and found at configure time.) LZMA is used by +@value{GDBN}'s "mini debuginfo" feature, which is only useful on +platforms using the ELF object file format. If your host does not +have liblzma installed, you can get the latest version from +@url{https://tukaani.org/xz/}. + +@item --with-python@r{[}=@var{python}@r{]} +Build @value{GDBN} with Python scripting support. (Done by default if +libpython is present and found at configure time.) Python makes +@value{GDBN} scripting much more powerful than the restricted CLI +scripting language. If your host does not have Python installed, you +can find it on @url{http://www.python.org/download/}. The oldest version +of Python supported by GDB is 3.0.1. The optional argument @var{python} +is used to find the Python headers and libraries. It can be either +the name of a Python executable, or the name of the directory in which +Python is installed. + +@item --with-guile[=@var{guile}] +Build @value{GDBN} with GNU Guile scripting support. (Done by default +if libguile is present and found at configure time.) If your host +does not have Guile installed, you can find it at +@url{https://www.gnu.org/software/guile/}. The optional argument @var{guile} +can be a version number, which will cause @code{configure} to try to +use that version of Guile; or the file name of a @code{pkg-config} +executable, which will be queried to find the information needed to +compile and link against Guile. + +@item --without-included-regex +Don't use the regex library included with @value{GDBN} (as part of the +libiberty library). This is the default on hosts with version 2 of +the GNU C library. + +@item --with-sysroot=@var{dir} +Use @var{dir} as the default system root directory for libraries whose +file names begin with @file{/lib}' or @file{/usr/lib'}. (The value of +@var{dir} can be modified at run time by using the @command{set +sysroot} command.) If @var{dir} is under the @value{GDBN} configured +prefix (set with @code{--prefix} or @code{--exec-prefix options}, the +default system root will be automatically adjusted if and when +@value{GDBN} is moved to a different location. + +@item --with-system-gdbinit=@var{file} +Configure @value{GDBN} to automatically load a system-wide init file. +@var{file} should be an absolute file name. If @var{file} is in a +directory under the configured prefix, and @value{GDBN} is moved to +another location after being built, the location of the system-wide +init file will be adjusted accordingly. + +@item --with-system-gdbinit-dir=@var{directory} +Configure @value{GDBN} to automatically load init files from a +system-wide directory. @var{directory} should be an absolute directory +name. If @var{directory} is in a directory under the configured +prefix, and @value{GDBN} is moved to another location after being +built, the location of the system-wide init directory will be +adjusted accordingly. + +@item --enable-build-warnings +When building the @value{GDBN} sources, ask the compiler to warn about +any code which looks even vaguely suspicious. It passes many +different warning flags, depending on the exact version of the +compiler you are using. + +@item --enable-werror +Treat compiler warnings as errors. It adds the @code{-Werror} flag +to the compiler, which will fail the compilation if the compiler +outputs any warning messages. + +@item --enable-ubsan +Enable the GCC undefined behavior sanitizer. This is disabled by +default, but passing @code{--enable-ubsan=yes} or +@code{--enable-ubsan=auto} to @code{configure} will enable it. The +undefined behavior sanitizer checks for C@t{++} undefined behavior. +It has a performance cost, so if you are looking at @value{GDBN}'s +performance, you should disable it. The undefined behavior sanitizer +was first introduced in GCC 4.9. +@end table + +@node System-wide configuration +@section System-wide configuration and settings +@cindex system-wide init file + +@value{GDBN} can be configured to have a system-wide init file and a +system-wide init file directory; this file and files in that directory +(if they have a recognized file extension) will be read and executed at +startup (@pxref{Startup, , What @value{GDBN} does during startup}). + +Here are the corresponding configure options: + +@table @code +@item --with-system-gdbinit=@var{file} +Specify that the default location of the system-wide init file is +@var{file}. +@item --with-system-gdbinit-dir=@var{directory} +Specify that the default location of the system-wide init file directory +is @var{directory}. +@end table + +If @value{GDBN} has been configured with the option @option{--prefix=$prefix}, +they may be subject to relocation. Two possible cases: + +@itemize @bullet +@item +If the default location of this init file/directory contains @file{$prefix}, +it will be subject to relocation. Suppose that the configure options +are @option{--prefix=$prefix --with-system-gdbinit=$prefix/etc/gdbinit}; +if @value{GDBN} is moved from @file{$prefix} to @file{$install}, the system +init file is looked for as @file{$install/etc/gdbinit} instead of +@file{$prefix/etc/gdbinit}. + +@item +By contrast, if the default location does not contain the prefix, +it will not be relocated. E.g.@: if @value{GDBN} has been configured with +@option{--prefix=/usr/local --with-system-gdbinit=/usr/share/gdb/gdbinit}, +then @value{GDBN} will always look for @file{/usr/share/gdb/gdbinit}, +wherever @value{GDBN} is installed. +@end itemize + +If the configured location of the system-wide init file (as given by the +@option{--with-system-gdbinit} option at configure time) is in the +data-directory (as specified by @option{--with-gdb-datadir} at configure +time) or in one of its subdirectories, then @value{GDBN} will look for the +system-wide init file in the directory specified by the +@option{--data-directory} command-line option. +Note that the system-wide init file is only read once, during @value{GDBN} +initialization. If the data-directory is changed after @value{GDBN} has +started with the @code{set data-directory} command, the file will not be +reread. + +This applies similarly to the system-wide directory specified in +@option{--with-system-gdbinit-dir}. + +Any supported scripting language can be used for these init files, as long +as the file extension matches the scripting language. To be interpreted +as regular @value{GDBN} commands, the files needs to have a @file{.gdb} +extension. + +@menu +* System-wide Configuration Scripts:: Installed System-wide Configuration Scripts +@end menu + +@node System-wide Configuration Scripts +@subsection Installed System-wide Configuration Scripts +@cindex system-wide configuration scripts + +The @file{system-gdbinit} directory, located inside the data-directory +(as specified by @option{--with-gdb-datadir} at configure time) contains +a number of scripts which can be used as system-wide init files. To +automatically source those scripts at startup, @value{GDBN} should be +configured with @option{--with-system-gdbinit}. Otherwise, any user +should be able to source them by hand as needed. + +The following scripts are currently available: +@itemize @bullet + +@item @file{elinos.py} +@pindex elinos.py +@cindex ELinOS system-wide configuration script +This script is useful when debugging a program on an ELinOS target. +It takes advantage of the environment variables defined in a standard +ELinOS environment in order to determine the location of the system +shared libraries, and then sets the @samp{solib-absolute-prefix} +and @samp{solib-search-path} variables appropriately. + +@item @file{wrs-linux.py} +@pindex wrs-linux.py +@cindex Wind River Linux system-wide configuration script +This script is useful when debugging a program on a target running +Wind River Linux. It expects the @env{ENV_PREFIX} to be set to +the host-side sysroot used by the target system. + +@end itemize + +@node Maintenance Commands +@appendix Maintenance Commands +@cindex maintenance commands +@cindex internal commands + +In addition to commands intended for @value{GDBN} users, @value{GDBN} +includes a number of commands intended for @value{GDBN} developers, +that are not documented elsewhere in this manual. These commands are +provided here for reference. (For commands that turn on debugging +messages, see @ref{Debugging Output}.) + +@table @code +@kindex maint agent +@kindex maint agent-eval +@item maint agent @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} +@itemx maint agent-eval @r{[}-at @var{linespec}@r{,}@r{]} @var{expression} +Translate the given @var{expression} into remote agent bytecodes. +This command is useful for debugging the Agent Expression mechanism +(@pxref{Agent Expressions}). The @samp{agent} version produces an +expression useful for data collection, such as by tracepoints, while +@samp{maint agent-eval} produces an expression that evaluates directly +to a result. For instance, a collection expression for @code{globa + +globb} will include bytecodes to record four bytes of memory at each +of the addresses of @code{globa} and @code{globb}, while discarding +the result of the addition, while an evaluation expression will do the +addition and return the sum. +If @code{-at} is given, generate remote agent bytecode for all the +addresses to which @var{linespec} resolves (@pxref{Linespec +Locations}). +If not, generate remote agent bytecode for current frame PC address. + +@kindex maint agent-printf +@item maint agent-printf @var{format},@var{expr},... +Translate the given format string and list of argument expressions +into remote agent bytecodes and display them as a disassembled list. +This command is useful for debugging the agent version of dynamic +printf (@pxref{Dynamic Printf}). + +@kindex maint info breakpoints +@anchor{maint info breakpoints} +@item maint info breakpoints +Using the same format as @samp{info breakpoints}, display both the +breakpoints you've set explicitly, and those @value{GDBN} is using for +internal purposes. Internal breakpoints are shown with negative +breakpoint numbers. The type column identifies what kind of breakpoint +is shown: + +@table @code +@item breakpoint +Normal, explicitly set breakpoint. + +@item watchpoint +Normal, explicitly set watchpoint. + +@item longjmp +Internal breakpoint, used to handle correctly stepping through +@code{longjmp} calls. + +@item longjmp resume +Internal breakpoint at the target of a @code{longjmp}. + +@item until +Temporary internal breakpoint used by the @value{GDBN} @code{until} command. + +@item finish +Temporary internal breakpoint used by the @value{GDBN} @code{finish} command. + +@item shlib events +Shared library events. + +@end table + +@kindex maint info btrace +@item maint info btrace +Pint information about raw branch tracing data. + +@kindex maint btrace packet-history +@item maint btrace packet-history +Print the raw branch trace packets that are used to compute the +execution history for the @samp{record btrace} command. Both the +information and the format in which it is printed depend on the btrace +recording format. + +@table @code +@item bts +For the BTS recording format, print a list of blocks of sequential +code. For each block, the following information is printed: + +@table @asis +@item Block number +Newer blocks have higher numbers. The oldest block has number zero. +@item Lowest @samp{PC} +@item Highest @samp{PC} +@end table + +@item pt +For the Intel Processor Trace recording format, print a list of +Intel Processor Trace packets. For each packet, the following +information is printed: + +@table @asis +@item Packet number +Newer packets have higher numbers. The oldest packet has number zero. +@item Trace offset +The packet's offset in the trace stream. +@item Packet opcode and payload +@end table +@end table + +@kindex maint btrace clear-packet-history +@item maint btrace clear-packet-history +Discards the cached packet history printed by the @samp{maint btrace +packet-history} command. The history will be computed again when +needed. + +@kindex maint btrace clear +@item maint btrace clear +Discard the branch trace data. The data will be fetched anew and the +branch trace will be recomputed when needed. + +This implicitly truncates the branch trace to a single branch trace +buffer. When updating branch trace incrementally, the branch trace +available to @value{GDBN} may be bigger than a single branch trace +buffer. + +@kindex maint set btrace pt skip-pad +@item maint set btrace pt skip-pad +@kindex maint show btrace pt skip-pad +@item maint show btrace pt skip-pad +Control whether @value{GDBN} will skip PAD packets when computing the +packet history. + +@kindex maint info jit +@item maint info jit +Print information about JIT code objects loaded in the current inferior. + +@anchor{maint info python-disassemblers} +@kindex maint info python-disassemblers +@item maint info python-disassemblers +This command is defined within the @code{gdb.disassembler} Python +module (@pxref{Disassembly In Python}), and will only be present after +that module has been imported. To force the module to be imported do +the following: + +@kindex maint info linux-lwps +@item maint info linux-lwps +Print information about LWPs under control of the Linux native target. + +@smallexample +(@value{GDBP}) python import gdb.disassembler +@end smallexample + +This command lists all the architectures for which a disassembler is +currently registered, and the name of the disassembler. If a +disassembler is registered for all architectures, then this is listed +last against the @samp{GLOBAL} architecture. + +If one of the disassemblers would be selected for the architecture of +the current inferior, then this disassembler will be marked. + +The following example shows a situation in which two disassemblers are +registered, initially the @samp{i386} disassembler matches the current +architecture, then the architecture is changed, now the @samp{GLOBAL} +disassembler matches. + +@smallexample +@group +(@value{GDBP}) show architecture +The target architecture is set to "auto" (currently "i386"). +(@value{GDBP}) maint info python-disassemblers +Architecture Disassember Name +i386 Disassembler_1 (Matches current architecture) +GLOBAL Disassembler_2 +@end group +@group +(@value{GDBP}) set architecture arm +The target architecture is set to "arm". +(@value{GDBP}) maint info python-disassemblers +quit +Architecture Disassember Name +i386 Disassembler_1 +GLOBAL Disassembler_2 (Matches current architecture) +@end group +@end smallexample + +@kindex set displaced-stepping +@kindex show displaced-stepping +@cindex displaced stepping support +@cindex out-of-line single-stepping +@item set displaced-stepping +@itemx show displaced-stepping +Control whether or not @value{GDBN} will do @dfn{displaced stepping} +if the target supports it. Displaced stepping is a way to single-step +over breakpoints without removing them from the inferior, by executing +an out-of-line copy of the instruction that was originally at the +breakpoint location. It is also known as out-of-line single-stepping. + +@table @code +@item set displaced-stepping on +If the target architecture supports it, @value{GDBN} will use +displaced stepping to step over breakpoints. + +@item set displaced-stepping off +@value{GDBN} will not use displaced stepping to step over breakpoints, +even if such is supported by the target architecture. + +@cindex non-stop mode, and @samp{set displaced-stepping} +@item set displaced-stepping auto +This is the default mode. @value{GDBN} will use displaced stepping +only if non-stop mode is active (@pxref{Non-Stop Mode}) and the target +architecture supports displaced stepping. +@end table + +@kindex maint check-psymtabs +@item maint check-psymtabs +Check the consistency of currently expanded psymtabs versus symtabs. +Use this to check, for example, whether a symbol is in one but not the other. + +@kindex maint check-symtabs +@item maint check-symtabs +Check the consistency of currently expanded symtabs. + +@kindex maint expand-symtabs +@item maint expand-symtabs [@var{regexp}] +Expand symbol tables. +If @var{regexp} is specified, only expand symbol tables for file +names matching @var{regexp}. + +@kindex maint set catch-demangler-crashes +@kindex maint show catch-demangler-crashes +@cindex demangler crashes +@item maint set catch-demangler-crashes [on|off] +@itemx maint show catch-demangler-crashes +Control whether @value{GDBN} should attempt to catch crashes in the +symbol name demangler. The default is to attempt to catch crashes. +If enabled, the first time a crash is caught, a core file is created, +the offending symbol is displayed and the user is presented with the +option to terminate the current session. + +@kindex maint cplus first_component +@item maint cplus first_component @var{name} +Print the first C@t{++} class/namespace component of @var{name}. + +@kindex maint cplus namespace +@item maint cplus namespace +Print the list of possible C@t{++} namespaces. + +@kindex maint deprecate +@kindex maint undeprecate +@cindex deprecated commands +@item maint deprecate @var{command} @r{[}@var{replacement}@r{]} +@itemx maint undeprecate @var{command} +Deprecate or undeprecate the named @var{command}. Deprecated commands +cause @value{GDBN} to issue a warning when you use them. The optional +argument @var{replacement} says which newer command should be used in +favor of the deprecated one; if it is given, @value{GDBN} will mention +the replacement as part of the warning. + +@kindex maint dump-me +@item maint dump-me +@cindex @code{SIGQUIT} signal, dump core of @value{GDBN} +Cause a fatal signal in the debugger and force it to dump its core. +This is supported only on systems which support aborting a program +with the @code{SIGQUIT} signal. + +@kindex maint internal-error +@kindex maint internal-warning +@kindex maint demangler-warning +@cindex demangler crashes +@item maint internal-error @r{[}@var{message-text}@r{]} +@itemx maint internal-warning @r{[}@var{message-text}@r{]} +@itemx maint demangler-warning @r{[}@var{message-text}@r{]} + +Cause @value{GDBN} to call the internal function @code{internal_error}, +@code{internal_warning} or @code{demangler_warning} and hence behave +as though an internal problem has been detected. In addition to +reporting the internal problem, these functions give the user the +opportunity to either quit @value{GDBN} or (for @code{internal_error} +and @code{internal_warning}) create a core file of the current +@value{GDBN} session. + +These commands take an optional parameter @var{message-text} that is +used as the text of the error or warning message. + +Here's an example of using @code{internal-error}: + +@smallexample +(@value{GDBP}) @kbd{maint internal-error testing, 1, 2} +@dots{}/maint.c:121: internal-error: testing, 1, 2 +A problem internal to GDB has been detected. Further +debugging may prove unreliable. +Quit this debugging session? (y or n) @kbd{n} +Create a core file? (y or n) @kbd{n} +(@value{GDBP}) +@end smallexample + +@kindex maint set debuginfod download-sections +@kindex maint show debuginfod download-sections +@cindex debuginfod, maintenance commands +@item maint set debuginfod download-sections +@itemx maint set debuginfod download-sections @r{[}on|off@r{]} +@itemx maint show debuginfod download-sections +Controls whether @value{GDBN} will attempt to download individual +ELF/DWARF sections from @code{debuginfod}. If disabled, only +whole debug info files will be downloaded; this could result +in @value{GDBN} downloading larger amounts of data. + +@cindex @value{GDBN} internal error +@cindex internal errors, control of @value{GDBN} behavior +@cindex demangler crashes + +@kindex maint set internal-error +@kindex maint show internal-error +@kindex maint set internal-warning +@kindex maint show internal-warning +@kindex maint set demangler-warning +@kindex maint show demangler-warning +@item maint set internal-error @var{action} [ask|yes|no] +@itemx maint show internal-error @var{action} +@itemx maint set internal-warning @var{action} [ask|yes|no] +@itemx maint show internal-warning @var{action} +@itemx maint set demangler-warning @var{action} [ask|yes|no] +@itemx maint show demangler-warning @var{action} +When @value{GDBN} reports an internal problem (error or warning) it +gives the user the opportunity to both quit @value{GDBN} and create a +core file of the current @value{GDBN} session. These commands let you +override the default behavior for each particular @var{action}, +described in the table below. + +@table @samp +@item quit +You can specify that @value{GDBN} should always (yes) or never (no) +quit. The default is to ask the user what to do. + +@item corefile +You can specify that @value{GDBN} should always (yes) or never (no) +create a core file. The default is to ask the user what to do. Note +that there is no @code{corefile} option for @code{demangler-warning}: +demangler warnings always create a core file and this cannot be +disabled. +@end table + +@kindex maint set internal-error +@kindex maint show internal-error +@kindex maint set internal-warning +@kindex maint show internal-warning +@item maint set internal-error backtrace @r{[}on|off@r{]} +@itemx maint show internal-error backtrace +@itemx maint set internal-warning backtrace @r{[}on|off@r{]} +@itemx maint show internal-warning backtrace +When @value{GDBN} reports an internal problem (error or warning) it is +possible to have a backtrace of @value{GDBN} printed to the standard +error stream. This is @samp{on} by default for @code{internal-error} +and @samp{off} by default for @code{internal-warning}. + +@anchor{maint packet} +@kindex maint packet +@item maint packet @var{text} +If @value{GDBN} is talking to an inferior via the serial protocol, +then this command sends the string @var{text} to the inferior, and +displays the response packet. @value{GDBN} supplies the initial +@samp{$} character, the terminating @samp{#} character, and the +checksum. + +Any non-printable characters in the reply are printed as escaped hex, +e.g. @samp{\x00}, @samp{\x01}, etc. + +@kindex maint print architecture +@item maint print architecture @r{[}@var{file}@r{]} +Print the entire architecture configuration. The optional argument +@var{file} names the file where the output goes. + +@kindex maint print c-tdesc +@item maint print c-tdesc @r{[}-single-feature@r{]} @r{[}@var{file}@r{]} +Print the target description (@pxref{Target Descriptions}) as +a C source file. By default, the target description is for the current +target, but if the optional argument @var{file} is provided, that file +is used to produce the description. The @var{file} should be an XML +document, of the form described in @ref{Target Description Format}. +The created source file is built into @value{GDBN} when @value{GDBN} is +built again. This command is used by developers after they add or +modify XML target descriptions. + +When the optional flag @samp{-single-feature} is provided then the +target description being processed (either the default, or from +@var{file}) must only contain a single feature. The source file +produced is different in this case. + +The @var{file} argument supports escaping and quoting, see +@ref{Filename Arguments,,Filenames As Command Arguments}. + +@kindex maint print xml-tdesc +@item maint print xml-tdesc @r{[}@var{file}@r{]} +Print the target description (@pxref{Target Descriptions}) as an XML +file. By default print the target description for the current target, +but if the optional argument @var{file} is provided, then that file is +read in by GDB and then used to produce the description. The +@var{file} should be an XML document, of the form described in +@ref{Target Description Format}. + +@kindex maint check xml-descriptions +@item maint check xml-descriptions @var{dir} +Check that the target descriptions dynamically created by @value{GDBN} +equal the descriptions created from XML files found in @var{dir}. + +@anchor{maint check libthread-db} +@kindex maint check libthread-db +@item maint check libthread-db +Run integrity checks on the current inferior's thread debugging +library. This exercises all @code{libthread_db} functionality used by +@value{GDBN} on GNU/Linux systems, and by extension also exercises the +@code{proc_service} functions provided by @value{GDBN} that +@code{libthread_db} uses. Note that parts of the test may be skipped +on some platforms when debugging core files. + +@kindex maint print core-file-backed-mappings +@cindex memory address space mappings +@item maint print core-file-backed-mappings +Print the file-backed mappings which were loaded from a core file note. +This output represents state internal to @value{GDBN} and should be +similar to the mappings displayed by the @code{info proc mappings} +command. + +@kindex maint print dummy-frames +@item maint print dummy-frames +Prints the contents of @value{GDBN}'s internal dummy-frame stack. + +@smallexample +(@value{GDBP}) @kbd{b add} +@dots{} +(@value{GDBP}) @kbd{print add(2,3)} +Breakpoint 2, add (a=2, b=3) at @dots{} +58 return (a + b); +The program being debugged stopped while in a function called from GDB. +@dots{} +(@value{GDBP}) @kbd{maint print dummy-frames} +0xa8206d8: id=@{stack=0xbfffe734,code=0xbfffe73f,!special@}, ptid=process 9353 +(@value{GDBP}) +@end smallexample + +Takes an optional file parameter. + +@kindex maint print frame-id +@item maint print frame-id +@itemx maint print frame-id @var{level} +Print @value{GDBN}'s internal frame-id for the frame at relative +@var{level}, or for the currently selected frame when @var{level} is +not given. + +If used, @var{level} should be an integer, as displayed in the +@command{backtrace} output. + +@smallexample +(@value{GDBP}) maint print frame-id +frame-id for frame #0: @{stack=0x7fffffffac70,code=0x0000000000401106,!special@} +(@value{GDBP}) maint print frame-id 2 +frame-id for frame #2: @{stack=0x7fffffffac90,code=0x000000000040111c,!special@} +@end smallexample + +@item maint info inline-frames +@itemx maint info inline-frames @var{address} +@cindex frames of inlined functions +@kindex maint info inline-frames +Print information about inlined frames which start at the current +address, or @var{address} if specified. + +In order to allow the user to correctly step into inlined functions, +@value{GDBN} needs to identify which inlined functions start at a +particular address, and @value{GDBN} also needs to track which of +these functions was last displayed to the user as the current frame. + +Imagine a situation where function @code{main} calls @code{foo}, which +then calls @code{bar}, something like this: + +@smallexample +@group +int +main () +@{ + /* Some interesting code here... */ + + foo (); + + /* More interesting code here... */ +@} + +void +foo () +@{ + bar (); +@} + +void +bar () +@{ + /* Some interesting code here... */ +@} +@end group +@end smallexample + +As both @code{foo} and @code{bar} are inlined within @code{main} then +there could be one address within @code{main} which is also the start +of @code{foo} and also the start of @code{bar}. When the user stops +at this address they will initially be told the inferior is in +@code{main}, if the user does a @kbd{step} then @value{GDBN} doesn't +actually step the inferior, instead the user is told the inferior +entered @code{foo}. After the next @kbd{step} the user is told the +inferior entered @code{bar}. The @kbd{maint info inline-frames} +command can be used to view this internal @value{GDBN} state, like +this: + +@smallexample +@group +(@value{GDBP}) step +24 foo (); +(@value{GDBP}) maintenance info inline-frames +Cached inline state information for thread 1. +program counter = 0x401137 +skipped frames = 2 + bar + foo +> main +@end group +@end smallexample + +Here the user is stopped in @code{main} at the call to @code{foo}. The +inline-frames information shows that at this address @value{GDBN} has +found the start of inlined functions @code{bar} and @code{foo}, but +currently @value{GDBN} has skipped 2 frames and considers @code{main} +to be the current frame, this is indicated with the @samp{>}. + +If the user performs a @kbd{step} to enter @code{foo} then the +situation is updated: + +@smallexample +@group +(@value{GDBP}) step +foo () at inline.c:14 +14 bar (); +(@value{GDBP}) maintenance info inline-frames +Cached inline state information for thread 1. +program counter = 0x401137 +skipped frames = 1 + bar +> foo + main +@end group +@end smallexample + +Notice that the program counter value @code{0x401137} hasn't change, +but now @value{GDBN} considers @code{foo} to be the current frame, and +it is marked as such with the @samp{>}. + +Finally, the user performs another @kbd{step} to enter @code{bar}: + +@smallexample +@group +(@value{GDBP}) step +bar () at inline.c:6 +6 ++global_counter; +(@value{GDBP}) maintenance info inline-frames +Cached inline state information for thread 1. +program counter = 0x401137 +skipped frames = 0 +> bar + foo + main +@end group +@end smallexample + +@kindex maint info blocks +@item maint info blocks +@itemx maint info blocks @var{address} +Print information about all blocks at @var{address}, or at the current +@code{$pc} if @var{address} is not given. + +For information about what blocks are in @value{GDBN} see @ref{Blocks +In Python}. + +Blocks are listed starting from the global block, then the static +block, and then proceeding through progressively narrower scopes. + +Here is an example of the command's output: +@smallexample +@group +(@value{GDBP}) maintenance info blocks +Blocks at 0x401137: + from objfile: [(objfile *) 0x50507d0] /tmp/inline_func_demo + +[(block *) 0x504da90] 0x401106..0x40119a + entry pc: 0x401106 + is global block + symbol count: 2 + is contiguous +@end group +@group +[(block *) 0x504d9f0] 0x401106..0x40119a + entry pc: 0x401106 + is static block + symbol count: 1 + is contiguous +@end group +@group +[(block *) 0x504d9a0] 0x401106..0x40119a + entry pc: 0x401106 + function: main + is contiguous +@end group +@group +[(block *) 0x504d900] 0x401137..0x401166 + entry pc: 0x401137 + inline function: foo + symbol count: 1 + is contiguous +@end group +@group +[(block *) 0x504d860] 0x401137..0x401165 + entry pc: 0x401137 + inline function: bar + symbol count: 1 + is contiguous +@end group +@end smallexample + +The command @kbd{maint info blocks} lists the symbol count for each +block but doesn't print the symbols themselves. The symbol names can +be found using @kbd{maint print symbols} (@pxref{maint print +symbols}). + +@kindex maint print registers +@kindex maint print raw-registers +@kindex maint print cooked-registers +@kindex maint print register-groups +@kindex maint print remote-registers +@item maint print registers @r{[}@var{file}@r{]} +@itemx maint print raw-registers @r{[}@var{file}@r{]} +@itemx maint print cooked-registers @r{[}@var{file}@r{]} +@itemx maint print register-groups @r{[}@var{file}@r{]} +@itemx maint print remote-registers @r{[}@var{file}@r{]} +Print @value{GDBN}'s internal register data structures. + +The command @code{maint print raw-registers} includes the contents of +the raw register cache; the command @code{maint print +cooked-registers} includes the (cooked) value of all registers, +including registers which aren't available on the target nor visible +to user; the command @code{maint print register-groups} includes the +groups that each register is a member of; and the command @code{maint +print remote-registers} includes the remote target's register numbers +and offsets in the `G' packets, as well as an indication of which +registers were included in the last stop reply packet received by +@value{GDBN} (@pxref{Stop Reply Packets}). Please note that the list +of registers included in a stop reply can change from one stop to the +next. + +These commands take an optional parameter, a file name to which to +write the information. + +@kindex maint print reggroups +@item maint print reggroups @r{[}@var{file}@r{]} +Print @value{GDBN}'s internal register group data structures. The +optional argument @var{file} tells to what file to write the +information. + +The register groups info looks like this: + +@smallexample +(@value{GDBP}) @kbd{maint print reggroups} + Group Type + general user + float user + all user + vector user + system user + save internal + restore internal +@end smallexample + +@kindex maint flush register-cache +@kindex flushregs +@cindex register cache, flushing +@item maint flush register-cache +@itemx flushregs +Flush the contents of the register cache and as a consequence the +frame cache. This command is useful when debugging issues related to +register fetching, or frame unwinding. The command @code{flushregs} +is deprecated in favor of @code{maint flush register-cache}. + +@kindex maint flush source-cache +@cindex source code, caching +@item maint flush source-cache +Flush @value{GDBN}'s cache of source code file contents. After +@value{GDBN} reads a source file, and optionally applies styling +(@pxref{Output Styling}), the file contents are cached. This command +clears that cache. The next time @value{GDBN} wants to show lines +from a source file, the content will be re-read. + +This command is useful when debugging issues related to source code +styling. After flushing the cache any source code displayed by +@value{GDBN} will be re-read and re-styled. + +@kindex maint print objfiles +@cindex info for known object files +@item maint print objfiles @r{[}@var{regexp}@r{]} +Print a dump of all known object files. +If @var{regexp} is specified, only print object files whose names +match @var{regexp}. For each object file, this command prints its name, +address in memory, and all of its psymtabs and symtabs. + +@kindex maint print user-registers +@cindex user registers +@item maint print user-registers +List all currently available @dfn{user registers}. User registers +typically provide alternate names for actual hardware registers. They +include the four ``standard'' registers @code{$fp}, @code{$pc}, +@code{$sp}, and @code{$ps}. @xref{standard registers}. User +registers can be used in expressions in the same way as the canonical +register names, but only the latter are listed by the @code{info +registers} and @code{maint print registers} commands. + +@kindex maint print section-scripts +@cindex info for known .debug_gdb_scripts-loaded scripts +@item maint print section-scripts [@var{regexp}] +Print a dump of scripts specified in the @code{.debug_gdb_section} section. +If @var{regexp} is specified, only print scripts loaded by object files +matching @var{regexp}. +For each script, this command prints its name as specified in the objfile, +and the full path if known. +@xref{dotdebug_gdb_scripts section}. + +@kindex maint print statistics +@cindex bcache statistics +@item maint print statistics +This command prints, for each object file in the program, various data +about that object file followed by the byte cache (@dfn{bcache}) +statistics for the object file. The objfile data includes the number +of minimal, partial, full, and stabs symbols, the number of types +defined by the objfile, the number of as yet unexpanded psym tables, +the number of line tables and string tables, and the amount of memory +used by the various tables. The bcache statistics include the counts, +sizes, and counts of duplicates of all and unique objects, max, +average, and median entry size, total memory used and its overhead and +savings, and various measures of the hash table size and chain +lengths. + +@kindex maint print target-stack +@cindex target stack description +@item maint print target-stack +A @dfn{target} is an interface between the debugger and a particular +kind of file or process. Targets can be stacked in @dfn{strata}, +so that more than one target can potentially respond to a request. +In particular, memory accesses will walk down the stack of targets +until they find a target that is interested in handling that particular +address. + +This command prints a short description of each layer that was pushed on +the @dfn{target stack}, starting from the top layer down to the bottom one. + +@kindex maint print type +@cindex type chain of a data type +@item maint print type @var{expr} +Print the type chain for a type specified by @var{expr}. The argument +can be either a type name or a symbol. If it is a symbol, the type of +that symbol is described. The type chain produced by this command is +a recursive definition of the data type as stored in @value{GDBN}'s +data structures, including its flags and contained types. + +@kindex maint print record-instruction +@item maint print record-instruction +@itemx maint print record-instruction @var{N} +print how GDB recorded a given instruction. If @var{n} is not positive +number, it prints the values stored by the inferior before the @var{n}-th previous +instruction was executed. If @var{n} is positive, print the values after the @var{n}-th +following instruction is executed. If @var{n} is not given, 0 is assumed. + +@kindex maint selftest +@cindex self tests +@item maint selftest @r{[}-verbose@r{]} @r{[}@var{filter}@r{]} +Run any self tests that were compiled in to @value{GDBN}. This will +print a message showing how many tests were run, and how many failed. +If a @var{filter} is passed, only the tests with @var{filter} in their +name will be ran. If @code{-verbose} is passed, the self tests can be +more verbose. + +@kindex maint set selftest verbose +@kindex maint show selftest verbose +@cindex self tests +@item maint set selftest verbose +@item maint show selftest verbose +Control whether self tests are run verbosely or not. + +@kindex maint info selftests +@cindex self tests +@item maint info selftests +List the selftests compiled in to @value{GDBN}. + +@kindex maint set dwarf always-disassemble +@kindex maint show dwarf always-disassemble +@item maint set dwarf always-disassemble +@item maint show dwarf always-disassemble +Control the behavior of @code{info address} when using DWARF debugging +information. + +The default is @code{off}, which means that @value{GDBN} should try to +describe a variable's location in an easily readable format. When +@code{on}, @value{GDBN} will instead display the DWARF location +expression in an assembly-like format. Note that some locations are +too complex for @value{GDBN} to describe simply; in this case you will +always see the disassembly form. + +Here is an example of the resulting disassembly: + +@smallexample +(@value{GDBP}) info addr argc +Symbol "argc" is a complex DWARF expression: + 1: DW_OP_fbreg 0 +@end smallexample + +For more information on these expressions, see +@uref{http://www.dwarfstd.org/, the DWARF standard}. + +@kindex maint set dwarf max-cache-age +@kindex maint show dwarf max-cache-age +@item maint set dwarf max-cache-age +@itemx maint show dwarf max-cache-age +Control the DWARF compilation unit cache. + +@cindex DWARF compilation units cache +In object files with inter-compilation-unit references, such as those +produced by the GCC option @samp{-feliminate-dwarf2-dups}, the DWARF +reader needs to frequently refer to previously read compilation units. +This setting controls how long a compilation unit will remain in the +cache if it is not referenced. A higher limit means that cached +compilation units will be stored in memory longer, and more total +memory will be used. Setting it to zero disables caching, which will +slow down @value{GDBN} startup, but reduce memory consumption. + +@kindex maint set dwarf synchronous +@kindex maint show dwarf synchronous +@item maint set dwarf synchronous +@itemx maint show dwarf synchronous +Control whether DWARF is read asynchronously. + +On hosts where threading is available, the DWARF reader is mostly +asynchronous with respect to the rest of @value{GDBN}. That is, the +bulk of the reading is done in the background, and @value{GDBN} will +only pause for completion of this task when absolutely necessary. + +When this setting is enabled, @value{GDBN} will instead wait for DWARF +processing to complete before continuing. + +On hosts without threading, or where worker threads have been disabled +at runtime, this setting has no effect, as DWARF reading is always +done on the main thread, and is therefore always synchronous. + +@kindex maint set dwarf unwinders +@kindex maint show dwarf unwinders +@item maint set dwarf unwinders +@itemx maint show dwarf unwinders +Control use of the DWARF frame unwinders. + +@cindex DWARF frame unwinders +Many targets that support DWARF debugging use @value{GDBN}'s DWARF +frame unwinders to build the backtrace. Many of these targets will +also have a second mechanism for building the backtrace for use in +cases where DWARF information is not available, this second mechanism +is often an analysis of a function's prologue. + +In order to extend testing coverage of the second level stack +unwinding mechanisms it is helpful to be able to disable the DWARF +stack unwinders, this can be done with this switch. + +In normal use of @value{GDBN} disabling the DWARF unwinders is not +advisable, there are cases that are better handled through DWARF than +prologue analysis, and the debug experience is likely to be better +with the DWARF frame unwinders enabled. + +If DWARF frame unwinders are not supported for a particular target +architecture, then enabling this flag does not cause them to be used. + +@kindex maint info frame-unwinders +@item maint info frame-unwinders +List the frame unwinders currently in effect, starting with the highest priority. + +@kindex maint set worker-threads +@kindex maint show worker-threads +@item maint set worker-threads +@item maint show worker-threads +Control the number of worker threads that may be used by @value{GDBN}. +On capable hosts, @value{GDBN} may use multiple threads to speed up +certain CPU-intensive operations, such as demangling symbol names. +While the number of threads used by @value{GDBN} may vary, this +command can be used to set an upper bound on this number. The default +is @code{unlimited}, which lets @value{GDBN} choose a reasonable +number. Note that this only controls worker threads started by +@value{GDBN} itself; libraries used by @value{GDBN} may start threads +of their own. + +@kindex maint set profile +@kindex maint show profile +@cindex profiling GDB +@item maint set profile +@itemx maint show profile +Control profiling of @value{GDBN}. + +Profiling will be disabled until you use the @samp{maint set profile} +command to enable it. When you enable profiling, the system will begin +collecting timing and execution count data; when you disable profiling or +exit @value{GDBN}, the results will be written to a log file. Remember that +if you use profiling, @value{GDBN} will overwrite the profiling log file +(often called @file{gmon.out}). If you have a record of important profiling +data in a @file{gmon.out} file, be sure to move it to a safe location. + +Configuring with @samp{--enable-profiling} arranges for @value{GDBN} to be +compiled with the @samp{-pg} compiler option. + +@kindex maint set show-debug-regs +@kindex maint show show-debug-regs +@cindex hardware debug registers +@item maint set show-debug-regs +@itemx maint show show-debug-regs +Control whether to show variables that mirror the hardware debug +registers. Use @code{on} to enable, @code{off} to disable. If +enabled, the debug registers values are shown when @value{GDBN} inserts or +removes a hardware breakpoint or watchpoint, and when the inferior +triggers a hardware-assisted breakpoint or watchpoint. + +@kindex maint set show-all-tib +@kindex maint show show-all-tib +@item maint set show-all-tib +@itemx maint show show-all-tib +Control whether to show all non zero areas within a 1k block starting +at thread local base, when using the @samp{info w32 thread-information-block} +command. + +@kindex maint set target-async +@kindex maint show target-async +@item maint set target-async +@itemx maint show target-async +This controls whether @value{GDBN} targets operate in synchronous or +asynchronous mode (@pxref{Background Execution}). Normally the +default is asynchronous, if it is available; but this can be changed +to more easily debug problems occurring only in synchronous mode. + +@kindex maint set target-non-stop @var{mode} [on|off|auto] +@kindex maint show target-non-stop +@item maint set target-non-stop +@itemx maint show target-non-stop + +This controls whether @value{GDBN} targets always operate in non-stop +mode even if @code{set non-stop} is @code{off} (@pxref{Non-Stop +Mode}). The default is @code{auto}, meaning non-stop mode is enabled +if supported by the target. + +@table @code +@item maint set target-non-stop auto +This is the default mode. @value{GDBN} controls the target in +non-stop mode if the target supports it. + +@item maint set target-non-stop on +@value{GDBN} controls the target in non-stop mode even if the target +does not indicate support. + +@item maint set target-non-stop off +@value{GDBN} does not control the target in non-stop mode even if the +target supports it. +@end table + +@kindex maint set tui-resize-message +@kindex maint show tui-resize-message +@item maint set tui-resize-message +@item maint show tui-resize-message +Control whether @value{GDBN} displays a message each time the terminal +is resized when in TUI mode. The default is @code{off}, which means +that @value{GDBN} is silent during resizes. When @code{on}, +@value{GDBN} will display a message after a resize is completed; the +message will include a number indicating how many times the terminal +has been resized. This setting is intended for use by the test suite, +where it would otherwise be difficult to determine when a resize and +refresh has been completed. + +@kindex maint set tui-left-margin-verbose +@kindex maint show tui-left-margin-verbose +@item maint set tui-left-margin-verbose +@item maint show tui-left-margin-verbose +Control whether the left margin of the TUI source and disassembly windows +uses @samp{_} and @samp{0} at locations where otherwise there would be a +space. The default is @code{off}, which means spaces are used. The +setting is intended to make it clear where the left margin begins and +ends, to avoid incorrectly interpreting a space as being part of the +the left margin. + +@kindex maint set per-command +@kindex maint show per-command +@item maint set per-command +@itemx maint show per-command +@cindex resources used by commands + +@value{GDBN} can display the resources used by each command. +This is useful in debugging performance problems. + +@table @code +@item maint set per-command space [on|off] +@itemx maint show per-command space +Enable or disable the printing of the memory used by GDB for each command. +If enabled, @value{GDBN} will display how much memory each command +took, following the command's own output. +This can also be requested by invoking @value{GDBN} with the +@option{--statistics} command-line switch (@pxref{Mode Options}). + +@item maint set per-command time [on|off] +@itemx maint show per-command time +Enable or disable the printing of the execution time of @value{GDBN} +for each command. +If enabled, @value{GDBN} will display how much time it +took to execute each command, following the command's own output. +Both CPU time and wallclock time are printed. +Printing both is useful when trying to determine whether the cost is +CPU or, e.g., disk/network latency. +Note that the CPU time printed is for @value{GDBN} only, it does not include +the execution time of the inferior because there's no mechanism currently +to compute how much time was spent by @value{GDBN} and how much time was +spent by the program been debugged. +This can also be requested by invoking @value{GDBN} with the +@option{--statistics} command-line switch (@pxref{Mode Options}). + +@item maint set per-command symtab [on|off] +@itemx maint show per-command symtab +Enable or disable the printing of basic symbol table statistics +for each command. +If enabled, @value{GDBN} will display the following information: + +@enumerate a +@item +number of symbol tables +@item +number of primary symbol tables +@item +number of blocks in the blockvector +@end enumerate +@end table + +@kindex maint set check-libthread-db +@kindex maint show check-libthread-db +@item maint set check-libthread-db [on|off] +@itemx maint show check-libthread-db +Control whether @value{GDBN} should run integrity checks on inferior +specific thread debugging libraries as they are loaded. The default +is not to perform such checks. If any check fails @value{GDBN} will +unload the library and continue searching for a suitable candidate as +described in @ref{set libthread-db-search-path}. For more information +about the tests, see @ref{maint check libthread-db}. + +@kindex maint set gnu-source-highlight enabled +@kindex maint show gnu-source-highlight enabled +@item maint set gnu-source-highlight enabled @r{[}on|off@r{]} +@itemx maint show gnu-source-highlight enabled +Control whether @value{GDBN} should use the GNU Source Highlight +library for applying styling to source code (@pxref{Output Styling}). +This will be @samp{on} by default if the GNU Source Highlight library +is available. If the GNU Source Highlight library is not available, +then this will be @samp{off} by default, and attempting to change this +value to @samp{on} will give an error. + +If the GNU Source Highlight library is not being used, then +@value{GDBN} will use the Python Pygments package for source code +styling, if it is available. + +This option is useful for debugging @value{GDBN}'s use of the Pygments +library when @value{GDBN} is linked against the GNU Source Highlight +library. + +@anchor{maint_libopcodes_styling} +@kindex maint set libopcodes-styling enabled +@kindex maint show libopcodes-styling enabled +@item maint set libopcodes-styling enabled @r{[}on|off@r{]} +@itemx maint show libopcodes-styling enabled +Control whether @value{GDBN} should use its builtin disassembler +(@file{libopcodes}) to style disassembler output (@pxref{Output +Styling}). The builtin disassembler does not support styling for all +architectures. + +When this option is @samp{off} the builtin disassembler will not be +used for styling, @value{GDBN} will fall back to using the Python +Pygments package if possible. + +Trying to set this option @samp{on} for an architecture that the +builtin disassembler is unable to style will give an error, otherwise, +the builtin disassembler will be used to style disassembler output. + +This option is @samp{on} by default for supported architectures. + +This option is useful for debugging @value{GDBN}'s use of the Pygments +library when @value{GDBN} is built for an architecture that supports +styling with the builtin disassembler + +@kindex maint info screen +@cindex show screen characteristics +@item maint info screen +Print various characteristics of the screen, such as various notions +of width and height. + +@kindex maint space +@cindex memory used by commands +@item maint space @var{value} +An alias for @code{maint set per-command space}. +A non-zero value enables it, zero disables it. + +@kindex maint time +@cindex time of command execution +@item maint time @var{value} +An alias for @code{maint set per-command time}. +A non-zero value enables it, zero disables it. + +@kindex maint translate-address +@item maint translate-address @r{[}@var{section}@r{]} @var{addr} +Find the symbol stored at the location specified by the address +@var{addr} and an optional section name @var{section}. If found, +@value{GDBN} prints the name of the closest symbol and an offset from +the symbol's location to the specified address. This is similar to +the @code{info address} command (@pxref{Symbols}), except that this +command also allows to find symbols in other sections. + +If section was not specified, the section in which the symbol was found +is also printed. For dynamically linked executables, the name of +executable or shared library containing the symbol is printed as well. + +@kindex maint test-options +@item maint test-options require-delimiter +@itemx maint test-options unknown-is-error +@itemx maint test-options unknown-is-operand +These commands are used by the testsuite to validate the command +options framework. The @code{require-delimiter} variant requires a +double-dash delimiter to indicate end of options. The +@code{unknown-is-error} and @code{unknown-is-operand} do not. The +@code{unknown-is-error} variant throws an error on unknown option, +while @code{unknown-is-operand} treats unknown options as the start of +the command's operands. When run, the commands output the result of +the processed options. When completed, the commands store the +internal result of completion in a variable exposed by the @code{maint +show test-options-completion-result} command. + +@kindex maint show test-options-completion-result +@item maint show test-options-completion-result +Shows the result of completing the @code{maint test-options} +subcommands. This is used by the testsuite to validate completion +support in the command options framework. + +@kindex maint set test-settings +@kindex maint show test-settings +@item maint set test-settings @var{kind} +@itemx maint show test-settings @var{kind} +These are representative commands for each @var{kind} of setting type +@value{GDBN} supports. They are used by the testsuite for exercising +the settings infrastructure. + +@kindex maint set backtrace-on-fatal-signal +@kindex maint show backtrace-on-fatal-signal +@item maint set backtrace-on-fatal-signal [on|off] +@itemx maint show backtrace-on-fatal-signal +When this setting is @code{on}, if @value{GDBN} itself terminates with +a fatal signal (e.g.@: SIGSEGV), then a limited backtrace will be +printed to the standard error stream. This backtrace can be used to +help diagnose crashes within @value{GDBN} in situations where a user +is unable to share a corefile with the @value{GDBN} developers. + +If the functionality to provide this backtrace is not available for +the platform on which GDB is running then this feature will be +@code{off} by default, and attempting to turn this feature on will +give an error. + +For platforms that do support creating the backtrace this feature is +@code{on} by default. + +@kindex maint wait-for-index-cache +@item maint wait-for-index-cache +Wait until all pending writes to the index cache have completed. This +is used by the test suite to avoid races when the index cache is being +updated by a worker thread. + +@kindex maint with +@item maint with @var{setting} [@var{value}] [-- @var{command}] +Like the @code{with} command, but works with @code{maintenance set} +variables. This is used by the testsuite to exercise the @code{with} +command's infrastructure. + +@kindex maint ignore-probes +@item maint ignore-probes [@var{-v}|@var{-verbose}] [@var{provider} [@var{name} [@var{objfile}]]] +@itemx maint ignore-probes @var{-reset} +Set or reset the ignore-probes filter. The @var{provider}, @var{name} +and @var{objfile} arguments are as in @code{enable probes} and +@code{disable probes} (@pxref{enable probes}). Only supported for +SystemTap probes. + +Here's an example of using @code{maint ignore-probes}: +@smallexample +(gdb) maint ignore-probes -verbose libc ^longjmp$ +ignore-probes filter has been set to: +PROVIDER: 'libc' +PROBE_NAME: '^longjmp$' +OBJNAME: '' +(gdb) start +<... more output ...> +Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M +Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M +Ignoring SystemTap probe libc longjmp in /lib64/libc.so.6.^M +@end smallexample +@end table + +The following command is useful for non-interactive invocations of +@value{GDBN}, such as in the test suite. + +@table @code +@item set watchdog @var{nsec} +@kindex set watchdog +@cindex watchdog timer +@cindex timeout for commands +Set the maximum number of seconds @value{GDBN} will wait for the +target operation to finish. If this time expires, @value{GDBN} +reports and error and the command is aborted. + +@item show watchdog +Show the current setting of the target wait timeout. +@end table + +@node Remote Protocol +@appendix @value{GDBN} Remote Serial Protocol + +@menu +* Overview:: +* Standard Replies:: +* Packets:: +* Stop Reply Packets:: +* General Query Packets:: +* Architecture-Specific Protocol Details:: +* Tracepoint Packets:: +* Host I/O Packets:: +* Interrupts:: +* Notification Packets:: +* Remote Non-Stop:: +* Packet Acknowledgment:: +* Examples:: +* File-I/O Remote Protocol Extension:: +* Library List Format:: +* Library List Format for SVR4 Targets:: +* Memory Map Format:: +* Thread List Format:: +* Traceframe Info Format:: +* Branch Trace Format:: +* Branch Trace Configuration Format:: +@end menu + +@node Overview +@section Overview + +There may be occasions when you need to know something about the +protocol---for example, if there is only one serial port to your target +machine, you might want your program to do something special if it +recognizes a packet meant for @value{GDBN}. + +In the examples below, @samp{->} and @samp{<-} are used to indicate +transmitted and received data, respectively. + +@cindex protocol, @value{GDBN} remote serial +@cindex serial protocol, @value{GDBN} remote +@cindex remote serial protocol +All @value{GDBN} commands and responses (other than acknowledgments +and notifications, see @ref{Notification Packets}) are sent as a +@var{packet}. A @var{packet} is introduced with the character +@samp{$}, the actual @var{packet-data}, and the terminating character +@samp{#} followed by a two-digit @var{checksum}: + +@smallexample +@code{$}@var{packet-data}@code{#}@var{checksum} +@end smallexample +@noindent + +@cindex checksum, for @value{GDBN} remote +@noindent +The two-digit @var{checksum} is computed as the modulo 256 sum of all +characters between the leading @samp{$} and the trailing @samp{#} (an +eight bit unsigned checksum). + +Implementors should note that prior to @value{GDBN} 5.0 the protocol +specification also included an optional two-digit @var{sequence-id}: + +@smallexample +@code{$}@var{sequence-id}@code{:}@var{packet-data}@code{#}@var{checksum} +@end smallexample + +@cindex sequence-id, for @value{GDBN} remote +@noindent +That @var{sequence-id} was appended to the acknowledgment. @value{GDBN} +has never output @var{sequence-id}s. Stubs that handle packets added +since @value{GDBN} 5.0 must not accept @var{sequence-id}. + +When either the host or the target machine receives a packet, the first +response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request +retransmission): + +@smallexample +-> @code{$}@var{packet-data}@code{#}@var{checksum} +<- @code{+} +@end smallexample +@noindent + +The @samp{+}/@samp{-} acknowledgments can be disabled +once a connection is established. +@xref{Packet Acknowledgment}, for details. + +The host (@value{GDBN}) sends @var{command}s, and the target (the +debugging stub incorporated in your program) sends a @var{response}. In +the case of step and continue @var{command}s, the response is only sent +when the operation has completed, and the target has again stopped all +threads in all attached processes. This is the default all-stop mode +behavior, but the remote protocol also supports @value{GDBN}'s non-stop +execution mode; see @ref{Remote Non-Stop}, for details. + +@var{packet-data} consists of a sequence of characters with the +exception of @samp{#} and @samp{$} (see @samp{X} packet for additional +exceptions). + +@cindex remote protocol, field separator +Fields within the packet should be separated using @samp{,} @samp{;} or +@samp{:}. Except where otherwise noted all numbers are represented in +@sc{hex} with leading zeros suppressed. + +Implementors should note that prior to @value{GDBN} 5.0, the character +@samp{:} could not appear as the third character in a packet (as it +would potentially conflict with the @var{sequence-id}). + +@cindex remote protocol, binary data +@anchor{Binary Data} +Binary data in most packets is encoded as two hexadecimal +digits per byte of binary data. This allowed the traditional remote +protocol to work over connections which were only seven-bit clean. +Some packets designed more recently assume an eight-bit clean +connection, and use a more efficient encoding to send and receive +binary data. + +The binary data representation uses @code{7d} (@sc{ascii} @samp{@}}) +as an escape character. Any escaped byte is transmitted as the escape +character followed by the original character XORed with @code{0x20}. +For example, the byte @code{0x7d} would be transmitted as the two +bytes @code{0x7d 0x5d}. The bytes @code{0x23} (@sc{ascii} @samp{#}), +@code{0x24} (@sc{ascii} @samp{$}), and @code{0x7d} (@sc{ascii} +@samp{@}}) must always be escaped. Responses sent by the stub +must also escape @code{0x2a} (@sc{ascii} @samp{*}), so that it +is not interpreted as the start of a run-length encoded sequence +(described next). + +Response @var{data} can be run-length encoded to save space. +Run-length encoding replaces runs of identical characters with one +instance of the repeated character, followed by a @samp{*} and a +repeat count. The repeat count is itself sent encoded, to avoid +binary characters in @var{data}: a value of @var{n} is sent as +@code{@var{n}+29}. For a repeat count greater or equal to 3, this +produces a printable @sc{ascii} character, e.g.@: a space (@sc{ascii} +code 32) for a repeat count of 3. (This is because run-length +encoding starts to win for counts 3 or more.) Thus, for example, +@samp{0* } is a run-length encoding of ``0000'': the space character +after @samp{*} means repeat the leading @code{0} @w{@code{32 - 29 = +3}} more times. + +The printable characters @samp{#} and @samp{$} or with a numeric value +greater than 126 must not be used. Runs of six repeats (@samp{#}) or +seven repeats (@samp{$}) can be expanded using a repeat count of only +five (@samp{"}). For example, @samp{00000000} can be encoded as +@samp{0*"00}. + +@xref{Standard Replies} for standard error responses, and how to +respond indicating a command is not supported. + +In describing packets (commands and responses), each description has a +template showing the overall syntax, followed by an explanation of the +packet's meaning. We include spaces in some of the templates for +clarity; these are not part of the packet's syntax. No @value{GDBN} +packet uses spaces to separate its components. For example, a +template like @samp{foo @var{bar} @var{baz}} describes a packet +beginning with the three ASCII bytes @samp{foo}, followed by a +@var{bar}, followed directly by a @var{baz}. @value{GDBN} does not +transmit a space character between the @samp{foo} and the @var{bar}, +or between the @var{bar} and the @var{baz}. + +We place optional portions of a packet in [square brackets]; +for example, a template like @samp{c @r{[}@var{addr}@r{]}} describes a +packet beginning with the single ASCII character @samp{c}, possibly +followed by an @var{addr}. + +At a minimum, a stub is required to support the @samp{?} command to +tell @value{GDBN} the reason for halting, @samp{g} and @samp{G} +commands for register access, and the @samp{m} and @samp{M} commands +for memory access. Stubs that only control single-threaded targets +can implement run control with the @samp{c} (continue) command, and if +the target architecture supports hardware-assisted single-stepping, +the @samp{s} (step) command. Stubs that support multi-threading +targets should support the @samp{vCont} command. All other commands +are optional. + +@node Standard Replies +@section Standard Replies +@cindex standard responses for remote packets +@cindex remote packets, standard replies + +The remote protocol specifies a few standard replies. All commands +support these, except as noted in the individual command descriptions. + +@table @asis + +@item empty response + +@cindex empty response, for unsupported packets +@cindex unsupported packets, empty response for +An empty response (raw character sequence @samp{$#00}) means the +@var{command} is not supported by the stub. This way it is possible +to extend the protocol. A newer @value{GDBN} can tell if a command is +supported based on that response (but see also @ref{qSupported}). + +@item @samp{E @var{xx}} +An error has occurred; @var{xx} is a two-digit hexadecimal error +number. In almost all cases, the protocol does not specify the +meaning of the error numbers; @value{GDBN} usually ignores the +numbers, or displays them to the user without further interpretation. + +@anchor{textual error reply} +@item @samp{E.@var{errtext}} +An error has occurred; @var{errtext} is the textual error message, +encoded in @sc{ascii}. + +@end table + +@node Packets +@section Packets + +The following table provides a complete list of all currently defined +@var{command}s and their corresponding response @var{data}. +@xref{File-I/O Remote Protocol Extension}, for details about the File +I/O extension of the remote protocol. + +Each packet's description has a template showing the packet's overall +syntax, followed by an explanation of the packet's meaning. We +include spaces in some of the templates for clarity; these are not +part of the packet's syntax. No @value{GDBN} packet uses spaces to +separate its components. For example, a template like @samp{foo +@var{bar} @var{baz}} describes a packet beginning with the three ASCII +bytes @samp{foo}, followed by a @var{bar}, followed directly by a +@var{baz}. @value{GDBN} does not transmit a space character between the +@samp{foo} and the @var{bar}, or between the @var{bar} and the +@var{baz}. + +@cindex @var{thread-id}, in remote protocol +@anchor{thread-id syntax} +Several packets and replies include a @var{thread-id} field to identify +a thread. Normally these are positive numbers with a target-specific +interpretation, formatted as big-endian hex strings. A @var{thread-id} +can also be a literal @samp{-1} to indicate all threads, or @samp{0} to +pick any thread. + +In addition, the remote protocol supports a multiprocess feature in +which the @var{thread-id} syntax is extended to optionally include both +process and thread ID fields, as @samp{p@var{pid}.@var{tid}}. +The @var{pid} (process) and @var{tid} (thread) components each have the +format described above: a positive number with target-specific +interpretation formatted as a big-endian hex string, literal @samp{-1} +to indicate all processes or threads (respectively), or @samp{0} to +indicate an arbitrary process or thread. Specifying just a process, as +@samp{p@var{pid}}, is equivalent to @samp{p@var{pid}.-1}. It is an +error to specify all processes but a specific thread, such as +@samp{p-1.@var{tid}}. Note that the @samp{p} prefix is @emph{not} used +for those packets and replies explicitly documented to include a process +ID, rather than a @var{thread-id}. + +The multiprocess @var{thread-id} syntax extensions are only used if both +@value{GDBN} and the stub report support for the @samp{multiprocess} +feature using @samp{qSupported}. @xref{multiprocess extensions}, for +more information. + +Note that all packet forms beginning with an upper- or lower-case +letter, other than those described here, are reserved for future use. + +Here are the packet descriptions. + +@table @samp + +@item ! +@cindex @samp{!} packet +@anchor{extended mode} +Enable extended mode. In extended mode, the remote server is made +persistent. The @samp{R} packet is used to restart the program being +debugged. + +Reply: +@table @samp +@item OK +The remote target both supports and has enabled extended mode. +@end table + +@item ? +@cindex @samp{?} packet +@anchor{? packet} +This is sent when connection is first established to query the reason +the target halted. The reply is the same as for step and continue. +This packet has a special interpretation when the target is in +non-stop mode; see @ref{Remote Non-Stop}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item A @var{arglen},@var{argnum},@var{arg},@dots{} +@cindex @samp{A} packet +Initialized @code{argv[]} array passed into program. @var{arglen} +specifies the number of bytes in the hex encoded byte stream +@var{arg}. See @code{gdbserver} for more details. + +Reply: +@table @samp +@item OK +The arguments were set. +@end table + +@item b @var{baud} +@cindex @samp{b} packet +(Don't use this packet; its behavior is not well-defined.) +Change the serial line speed to @var{baud}. + +JTC: @emph{When does the transport layer state change? When it's +received, or after the ACK is transmitted. In either case, there are +problems if the command or the acknowledgment packet is dropped.} + +Stan: @emph{If people really wanted to add something like this, and get +it working for the first time, they ought to modify ser-unix.c to send +some kind of out-of-band message to a specially-setup stub and have the +switch happen "in between" packets, so that from remote protocol's point +of view, nothing actually happened.} + +@item B @var{addr},@var{mode} +@cindex @samp{B} packet +Set (@var{mode} is @samp{S}) or clear (@var{mode} is @samp{C}) a +breakpoint at @var{addr}. + +Don't use this packet. Use the @samp{Z} and @samp{z} packets instead +(@pxref{insert breakpoint or watchpoint packet}). + +@cindex @samp{bc} packet +@anchor{bc} +@item bc +Backward continue. Execute the target system in reverse. No parameter. +@xref{Reverse Execution}, for more information. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@cindex @samp{bs} packet +@anchor{bs} +@item bs +Backward single step. Execute one instruction in reverse. No parameter. +@xref{Reverse Execution}, for more information. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item c @r{[}@var{addr}@r{]} +@cindex @samp{c} packet +Continue at @var{addr}, which is the address to resume. If @var{addr} +is omitted, resume at current address. + +This packet is deprecated for multi-threading support. @xref{vCont +packet}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item C @var{sig}@r{[};@var{addr}@r{]} +@cindex @samp{C} packet +Continue with signal @var{sig} (hex signal number). If +@samp{;@var{addr}} is omitted, resume at same address. + +This packet is deprecated for multi-threading support. @xref{vCont +packet}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item d +@cindex @samp{d} packet +Toggle debug flag. + +Don't use this packet; instead, define a general set packet +(@pxref{General Query Packets}). + +@item D +@itemx D;@var{pid} +@cindex @samp{D} packet +The first form of the packet is used to detach @value{GDBN} from the +remote system. It is sent to the remote target +before @value{GDBN} disconnects via the @code{detach} command. + +The second form, including a process ID, is used when multiprocess +protocol extensions are enabled (@pxref{multiprocess extensions}), to +detach only a specific process. The @var{pid} is specified as a +big-endian hex string. + +Reply: +@table @samp +@item OK +for success +@end table + +@item F @var{RC},@var{EE},@var{CF};@var{XX} +@cindex @samp{F} packet +A reply from @value{GDBN} to an @samp{F} packet sent by the target. +This is part of the File-I/O protocol extension. @xref{File-I/O +Remote Protocol Extension}, for the specification. + +@item g +@anchor{read registers packet} +@cindex @samp{g} packet +Read general registers. + +Reply: +@table @samp +@item @var{XX@dots{}} +Each byte of register data is described by two hex digits. The bytes +with the register are transmitted in target byte order. The size of +each register and their position within the @samp{g} packet are +determined by the target description (@pxref{Target Descriptions}); in +the absence of a target description, this is done using code internal +to @value{GDBN}; typically this is some customary register layout for +the architecture in question. + +When reading registers, the stub may also return a string of literal +@samp{x}'s in place of the register data digits, to indicate that the +corresponding register's value is unavailable. For example, when +reading registers from a trace frame (@pxref{Analyze Collected +Data,,Using the Collected Data}), this means that the register has not +been collected in the trace frame. When reading registers from a live +program, this indicates that the stub has no means to access the +register contents, even though the corresponding register is known to +exist. Note that if a register truly does not exist on the target, +then it is better to not include it in the target description in the +first place. + +For example, for an architecture with 4 registers of +4 bytes each, the following reply indicates to @value{GDBN} that +registers 0 and 2 are unavailable, while registers 1 and 3 +are available, and both have zero value: + +@smallexample +-> @code{g} +<- @code{xxxxxxxx00000000xxxxxxxx00000000} +@end smallexample + +@end table + +@item G @var{XX@dots{}} +@cindex @samp{G} packet +Write general registers. @xref{read registers packet}, for a +description of the @var{XX@dots{}} data. + +Reply: +@table @samp +@item OK +for success +@end table + +@item H @var{op} @var{thread-id} +@cindex @samp{H} packet +Set thread for subsequent operations (@samp{m}, @samp{M}, @samp{g}, +@samp{G}, et.al.). Depending on the operation to be performed, @var{op} +should be @samp{c} for step and continue operations (note that this +is deprecated, supporting the @samp{vCont} command is a better +option), and @samp{g} for other operations. The thread designator +@var{thread-id} has the format and interpretation described in +@ref{thread-id syntax}. + +Reply: +@table @samp +@item OK +for success +@end table + +@c FIXME: JTC: +@c 'H': How restrictive (or permissive) is the thread model. If a +@c thread is selected and stopped, are other threads allowed +@c to continue to execute? As I mentioned above, I think the +@c semantics of each command when a thread is selected must be +@c described. For example: +@c +@c 'g': If the stub supports threads and a specific thread is +@c selected, returns the register block from that thread; +@c otherwise returns current registers. +@c +@c 'G' If the stub supports threads and a specific thread is +@c selected, sets the registers of the register block of +@c that thread; otherwise sets current registers. + +@item i @r{[}@var{addr}@r{[},@var{nnn}@r{]]} +@anchor{cycle step packet} +@cindex @samp{i} packet +Step the remote target by a single clock cycle. If @samp{,@var{nnn}} is +present, cycle step @var{nnn} cycles. If @var{addr} is present, cycle +step starting at that address. + +@item I +@cindex @samp{I} packet +Signal, then cycle step. @xref{step with signal packet}. @xref{cycle +step packet}. + +@item k +@cindex @samp{k} packet +Kill request. + +The exact effect of this packet is not specified. + +For a bare-metal target, it may power cycle or reset the target +system. For that reason, the @samp{k} packet has no reply. + +For a single-process target, it may kill that process if possible. + +A multiple-process target may choose to kill just one process, or all +that are under @value{GDBN}'s control. For more precise control, use +the vKill packet (@pxref{vKill packet}). + +If the target system immediately closes the connection in response to +@samp{k}, @value{GDBN} does not consider the lack of packet +acknowledgment to be an error, and assumes the kill was successful. + +If connected using @kbd{target extended-remote}, and the target does +not close the connection in response to a kill request, @value{GDBN} +probes the target state as if a new connection was opened +(@pxref{? packet}). + +@item m @var{addr},@var{length} +@cindex @samp{m} packet +Read @var{length} addressable memory units starting at address @var{addr} +(@pxref{addressable memory unit}). Note that @var{addr} does not have to +be aligned to any particular boundary. + +@cindex alignment of remote memory accesses +@cindex size of remote memory accesses +@cindex memory, alignment and size of remote accesses +The stub need not use any particular size or alignment when gathering +data from memory for the response; even if @var{addr} is word-aligned +and @var{length} is a multiple of the word size, the stub is free to +use byte accesses, or not. For this reason, this packet may not be +suitable for accessing memory-mapped I/O devices. + +Reply: +@table @samp +@item @var{XX@dots{}} +Memory contents; each byte is transmitted as a two-digit hexadecimal number. +The reply may contain fewer addressable memory units than requested if the +server was reading from a trace frame memory and was able to read only part +of the region of memory. +@end table + +Unlike most packets, this packet does not support +@samp{E.@var{errtext}}-style textual error replies (@pxref{textual +error reply}) by default. Stubs should be careful to only send such a +reply if @value{GDBN} reported support for it with the +@code{error-message} feature (@pxref{error-message}). + +@item M @var{addr},@var{length}:@var{XX@dots{}} +@cindex @samp{M} packet +Write @var{length} addressable memory units starting at address @var{addr} +(@pxref{addressable memory unit}). The data is given by @var{XX@dots{}}; each +byte is transmitted as a two-digit hexadecimal number. + +Reply: +@table @samp +@item OK +All the data was written successfully. (If only part of the data was +written, this command returns an error.) +@end table + +@item p @var{n} +@cindex @samp{p} packet +Read the value of register @var{n}; @var{n} is in hex. +@xref{read registers packet}, for a description of how the returned +register value is encoded. + +Reply: +@table @samp +@item @var{XX@dots{}} +the register's value +@end table + +@item P @var{n@dots{}}=@var{r@dots{}} +@anchor{write register packet} +@cindex @samp{P} packet +Write register @var{n@dots{}} with value @var{r@dots{}}. The register +number @var{n} is in hexadecimal, and @var{r@dots{}} contains two hex +digits for each byte in the register (target byte order). + +Reply: +@table @samp +@item OK +for success +@end table + +@item q @var{name} @var{params}@dots{} +@itemx Q @var{name} @var{params}@dots{} +@cindex @samp{q} packet +@cindex @samp{Q} packet +General query (@samp{q}) and set (@samp{Q}). These packets are +described fully in @ref{General Query Packets}. + +@item r +@cindex @samp{r} packet +Reset the entire system. + +Don't use this packet; use the @samp{R} packet instead. + +@item R @var{XX} +@cindex @samp{R} packet +Restart the program being debugged. The @var{XX}, while needed, is ignored. +This packet is only available in extended mode (@pxref{extended mode}). + +The @samp{R} packet has no reply. + +@item s @r{[}@var{addr}@r{]} +@cindex @samp{s} packet +Single step, resuming at @var{addr}. If +@var{addr} is omitted, resume at same address. + +This packet is deprecated for multi-threading support. @xref{vCont +packet}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item S @var{sig}@r{[};@var{addr}@r{]} +@anchor{step with signal packet} +@cindex @samp{S} packet +Step with signal. This is analogous to the @samp{C} packet, but +requests a single-step, rather than a normal resumption of execution. + +This packet is deprecated for multi-threading support. @xref{vCont +packet}. + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item t @var{addr}:@var{PP},@var{MM} +@cindex @samp{t} packet +Search backwards starting at address @var{addr} for a match with pattern +@var{PP} and mask @var{MM}, both of which are are 4 byte long. +There must be at least 3 digits in @var{addr}. + +@item T @var{thread-id} +@cindex @samp{T} packet +Find out if the thread @var{thread-id} is alive. @xref{thread-id syntax}. + +Reply: +@table @samp +@item OK +thread is still alive +@end table + +@item v +Packets starting with @samp{v} are identified by a multi-letter name, +up to the first @samp{;} or @samp{?} (or the end of the packet). + +@item vAttach;@var{pid} +@cindex @samp{vAttach} packet +Attach to a new process with the specified process ID @var{pid}. +The process ID is a +hexadecimal integer identifying the process. In all-stop mode, all +threads in the attached process are stopped; in non-stop mode, it may be +attached without being stopped if that is supported by the target. + +@c In non-stop mode, on a successful vAttach, the stub should set the +@c current thread to a thread of the newly-attached process. After +@c attaching, GDB queries for the attached process's thread ID with qC. +@c Also note that, from a user perspective, whether or not the +@c target is stopped on attach in non-stop mode depends on whether you +@c use the foreground or background version of the attach command, not +@c on what vAttach does; GDB does the right thing with respect to either +@c stopping or restarting threads. + +This packet is only available in extended mode (@pxref{extended mode}). + +Reply: +@table @samp +@item @r{Any stop packet} +for success in all-stop mode (@pxref{Stop Reply Packets}) +@item OK +for success in non-stop mode (@pxref{Remote Non-Stop}) +@end table + +@item vCont@r{[};@var{action}@r{[}:@var{thread-id}@r{]]}@dots{} +@cindex @samp{vCont} packet +@anchor{vCont packet} +Resume the inferior, specifying different actions for each thread. + +For each inferior thread, the leftmost action with a matching +@var{thread-id} is applied. Threads that don't match any action +remain in their current state. Thread IDs are specified using the +syntax described in @ref{thread-id syntax}. If multiprocess +extensions (@pxref{multiprocess extensions}) are supported, actions +can be specified to match all threads in a process by using the +@samp{p@var{pid}.-1} form of the @var{thread-id}. An action with no +@var{thread-id} matches all threads. Specifying no actions is an +error. + +Currently supported actions are: + +@table @samp +@item c +Continue. +@item C @var{sig} +Continue with signal @var{sig}. The signal @var{sig} should be two hex digits. +@item s +Step. +@item S @var{sig} +Step with signal @var{sig}. The signal @var{sig} should be two hex digits. +@item t +Stop. +@item r @var{start},@var{end} +Step once, and then keep stepping as long as the thread stops at +addresses between @var{start} (inclusive) and @var{end} (exclusive). +The remote stub reports a stop reply when either the thread goes out +of the range or is stopped due to an unrelated reason, such as hitting +a breakpoint. @xref{range stepping}. + +If the range is empty (@var{start} == @var{end}), then the action +becomes equivalent to the @samp{s} action. In other words, +single-step once, and report the stop (even if the stepped instruction +jumps to @var{start}). + +(A stop reply may be sent at any point even if the PC is still within +the stepping range; for example, it is valid to implement this packet +in a degenerate way as a single instruction step operation.) + +@end table + +The optional argument @var{addr} normally associated with the +@samp{c}, @samp{C}, @samp{s}, and @samp{S} packets is +not supported in @samp{vCont}. + +The @samp{t} action is only relevant in non-stop mode +(@pxref{Remote Non-Stop}) and may be ignored by the stub otherwise. +A stop reply should be generated for any affected thread not already stopped. +When a thread is stopped by means of a @samp{t} action, +the corresponding stop reply should indicate that the thread has stopped with +signal @samp{0}, regardless of whether the target uses some other signal +as an implementation detail. + +The server must ignore @samp{c}, @samp{C}, @samp{s}, @samp{S}, and +@samp{r} actions for threads that are already running. Conversely, +the server must ignore @samp{t} actions for threads that are already +stopped. + +@emph{Note:} In non-stop mode, a thread is considered running until +@value{GDBN} acknowledges an asynchronous stop notification for it with +the @samp{vStopped} packet (@pxref{Remote Non-Stop}). + +The stub must support @samp{vCont} if it reports support for +multiprocess extensions (@pxref{multiprocess extensions}). + +Reply: +@xref{Stop Reply Packets}, for the reply specifications. + +@item vCont? +@cindex @samp{vCont?} packet +Request a list of actions supported by the @samp{vCont} packet. + +Reply: +@table @samp +@item vCont@r{[};@var{action}@dots{}@r{]} +The @samp{vCont} packet is supported. Each @var{action} is a supported +command in the @samp{vCont} packet. +@end table + +@anchor{vCtrlC packet} +@item vCtrlC +@cindex @samp{vCtrlC} packet +Interrupt remote target as if a control-C was pressed on the remote +terminal. This is the equivalent to reacting to the @code{^C} +(@samp{\003}, the control-C character) character in all-stop mode +while the target is running, except this works in non-stop mode. +@xref{interrupting remote targets}, for more info on the all-stop +variant. + +Reply: +@table @samp +@item OK +for success +@end table + +@item vFile:@var{operation}:@var{parameter}@dots{} +@cindex @samp{vFile} packet +Perform a file operation on the target system. For details, +see @ref{Host I/O Packets}. + +@item vFlashErase:@var{addr},@var{length} +@cindex @samp{vFlashErase} packet +Direct the stub to erase @var{length} bytes of flash starting at +@var{addr}. The region may enclose any number of flash blocks, but +its start and end must fall on block boundaries, as indicated by the +flash block size appearing in the memory map (@pxref{Memory Map +Format}). @value{GDBN} groups flash memory programming operations +together, and sends a @samp{vFlashDone} request after each group; the +stub is allowed to delay erase operation until the @samp{vFlashDone} +packet is received. + +Reply: +@table @samp +@item OK +for success +@end table + +@item vFlashWrite:@var{addr}:@var{XX@dots{}} +@cindex @samp{vFlashWrite} packet +Direct the stub to write data to flash address @var{addr}. The data +is passed in binary form using the same encoding as for the @samp{X} +packet (@pxref{Binary Data}). The memory ranges specified by +@samp{vFlashWrite} packets preceding a @samp{vFlashDone} packet must +not overlap, and must appear in order of increasing addresses +(although @samp{vFlashErase} packets for higher addresses may already +have been received; the ordering is guaranteed only between +@samp{vFlashWrite} packets). If a packet writes to an address that was +neither erased by a preceding @samp{vFlashErase} packet nor by some other +target-specific method, the results are unpredictable. + + +Reply: +@table @samp +@item OK +for success +@item E.memtype +for vFlashWrite addressing non-flash memory +@end table + +@item vFlashDone +@cindex @samp{vFlashDone} packet +Indicate to the stub that flash programming operation is finished. +The stub is permitted to delay or batch the effects of a group of +@samp{vFlashErase} and @samp{vFlashWrite} packets until a +@samp{vFlashDone} packet is received. The contents of the affected +regions of flash memory are unpredictable until the @samp{vFlashDone} +request is completed. + +@item vKill;@var{pid} +@cindex @samp{vKill} packet +@anchor{vKill packet} +Kill the process with the specified process ID @var{pid}, which is a +hexadecimal integer identifying the process. This packet is used in +preference to @samp{k} when multiprocess protocol extensions are +supported; see @ref{multiprocess extensions}. + +Reply: +@table @samp +@item OK +for success +@end table + +@item vMustReplyEmpty +@cindex @samp{vMustReplyEmpty} packet +The correct reply to an unknown @samp{v} packet is to return the empty +string, however, some older versions of @command{gdbserver} would +incorrectly return @samp{OK} for unknown @samp{v} packets. + +The @samp{vMustReplyEmpty} is used as a feature test to check how +@command{gdbserver} handles unknown packets, it is important that this +packet be handled in the same way as other unknown @samp{v} packets. +If this packet is handled differently to other unknown @samp{v} +packets then it is possible that @value{GDBN} may run into problems in +other areas, specifically around use of @samp{vFile:setfs:}. + +@item vRun;@var{filename}@r{[};@var{argument}@r{]}@dots{} +@cindex @samp{vRun} packet +Run the program @var{filename}, passing it each @var{argument} on its +command line. The file and arguments are hex-encoded strings. If +@var{filename} is an empty string, the stub may use a default program +(e.g.@: the last program run). The program is created in the stopped +state. + +@c FIXME: What about non-stop mode? + +This packet is only available in extended mode (@pxref{extended mode}). + +Reply: +@table @samp +@item @r{Any stop packet} +for success (@pxref{Stop Reply Packets}) +@end table + +@item vStopped +@cindex @samp{vStopped} packet +@xref{Notification Packets}. + +@item x @var{addr},@var{length} +@anchor{x packet} +@cindex @samp{x} packet +Read @var{length} addressable memory units starting at address @var{addr} +(@pxref{addressable memory unit}). Note that @var{addr} does not have to +be aligned to any particular boundary. + +@cindex alignment of remote memory accesses +@cindex size of remote memory accesses +@cindex memory, alignment and size of remote accesses +The stub need not use any particular size or alignment when gathering +data from memory for the response; even if @var{addr} is word-aligned +and @var{length} is a multiple of the word size, the stub is free to +use byte accesses, or not. For this reason, this packet may not be +suitable for accessing memory-mapped I/O devices. + +@value{GDBN} will only use this packet if the stub reports the +@samp{binary-upload} feature is supported in its @samp{qSupported} +reply (@pxref{qSupported}). + +Reply: +@table @samp +@item b @var{XX@dots{}} +Memory contents as binary data (@pxref{Binary Data}). +The reply may contain fewer addressable memory units than requested if the +server was reading from a trace frame memory and was able to read only part +of the region of memory. +@item E @var{NN} +for an error +@end table + +@item X @var{addr},@var{length}:@var{XX@dots{}} +@anchor{X packet} +@cindex @samp{X} packet +Write data to memory, where the data is transmitted in binary. +Memory is specified by its address @var{addr} and number of addressable memory +units @var{length} (@pxref{addressable memory unit}); +@samp{@var{XX}@dots{}} is binary data (@pxref{Binary Data}). + +Reply: +@table @samp +@item OK +for success +@end table + +@item z @var{type},@var{addr},@var{kind} +@itemx Z @var{type},@var{addr},@var{kind} +@anchor{insert breakpoint or watchpoint packet} +@cindex @samp{z} packet +@cindex @samp{Z} packets +Insert (@samp{Z}) or remove (@samp{z}) a @var{type} breakpoint or +watchpoint starting at address @var{address} of kind @var{kind}. + +Each breakpoint and watchpoint packet @var{type} is documented +separately. + +@emph{Implementation notes: A remote target shall return an empty string +for an unrecognized breakpoint or watchpoint packet @var{type}. A +remote target shall support either both or neither of a given +@samp{Z@var{type}@dots{}} and @samp{z@var{type}@dots{}} packet pair. To +avoid potential problems with duplicate packets, the operations should +be implemented in an idempotent way.} + +@item z0,@var{addr},@var{kind} +@itemx Z0,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} +@cindex @samp{z0} packet +@cindex @samp{Z0} packet +Insert (@samp{Z0}) or remove (@samp{z0}) a software breakpoint at address +@var{addr} of type @var{kind}. + +A software breakpoint is implemented by replacing the instruction at +@var{addr} with a software breakpoint or trap instruction. The +@var{kind} is target-specific and typically indicates the size of the +breakpoint in bytes that should be inserted. E.g., the @sc{arm} and +@sc{mips} can insert either a 2 or 4 byte breakpoint. Some +architectures have additional meanings for @var{kind} +(@pxref{Architecture-Specific Protocol Details}); if no +architecture-specific value is being used, it should be @samp{0}. +@var{kind} is hex-encoded. @var{cond_list} is an optional list of +conditional expressions in bytecode form that should be evaluated on +the target's side. These are the conditions that should be taken into +consideration when deciding if the breakpoint trigger should be +reported back to @value{GDBN}. + +See also the @samp{swbreak} stop reason (@pxref{swbreak stop reason}) +for how to best report a software breakpoint event to @value{GDBN}. + +The @var{cond_list} parameter is comprised of a series of expressions, +concatenated without separators. Each expression has the following form: + +@table @samp + +@item X @var{len},@var{expr} +@var{len} is the length of the bytecode expression and @var{expr} is the +actual conditional expression in bytecode form. + +@end table + +The optional @var{cmd_list} parameter introduces commands that may be +run on the target, rather than being reported back to @value{GDBN}. +The parameter starts with a numeric flag @var{persist}; if the flag is +nonzero, then the breakpoint may remain active and the commands +continue to be run even when @value{GDBN} disconnects from the target. +Following this flag is a series of expressions concatenated with no +separators. Each expression has the following form: + +@table @samp + +@item X @var{len},@var{expr} +@var{len} is the length of the bytecode expression and @var{expr} is the +actual commands expression in bytecode form. + +@end table + +@emph{Implementation note: It is possible for a target to copy or move +code that contains software breakpoints (e.g., when implementing +overlays). The behavior of this packet, in the presence of such a +target, is not defined.} + +Reply: +@table @samp +@item OK +success +@end table + +@item z1,@var{addr},@var{kind} +@itemx Z1,@var{addr},@var{kind}@r{[};@var{cond_list}@dots{}@r{]}@r{[};cmds:@var{persist},@var{cmd_list}@dots{}@r{]} +@cindex @samp{z1} packet +@cindex @samp{Z1} packet +Insert (@samp{Z1}) or remove (@samp{z1}) a hardware breakpoint at +address @var{addr}. + +A hardware breakpoint is implemented using a mechanism that is not +dependent on being able to modify the target's memory. The +@var{kind}, @var{cond_list}, and @var{cmd_list} arguments have the +same meaning as in @samp{Z0} packets. + +@emph{Implementation note: A hardware breakpoint is not affected by code +movement.} + +Reply: +@table @samp +@item OK +success +@end table + +@item z2,@var{addr},@var{kind} +@itemx Z2,@var{addr},@var{kind} +@cindex @samp{z2} packet +@cindex @samp{Z2} packet +Insert (@samp{Z2}) or remove (@samp{z2}) a write watchpoint at @var{addr}. +The number of bytes to watch is specified by @var{kind}. + +Reply: +@table @samp +@item OK +success +@end table + +@item z3,@var{addr},@var{kind} +@itemx Z3,@var{addr},@var{kind} +@cindex @samp{z3} packet +@cindex @samp{Z3} packet +Insert (@samp{Z3}) or remove (@samp{z3}) a read watchpoint at @var{addr}. +The number of bytes to watch is specified by @var{kind}. + +Reply: +@table @samp +@item OK +success +@end table + +@item z4,@var{addr},@var{kind} +@itemx Z4,@var{addr},@var{kind} +@cindex @samp{z4} packet +@cindex @samp{Z4} packet +Insert (@samp{Z4}) or remove (@samp{z4}) an access watchpoint at @var{addr}. +The number of bytes to watch is specified by @var{kind}. + +Reply: +@table @samp +@item OK +success +@end table + +@end table + +@node Stop Reply Packets +@section Stop Reply Packets +@cindex stop reply packets + +The @samp{C}, @samp{c}, @samp{S}, @samp{s}, @samp{vCont}, +@samp{vAttach}, @samp{vRun}, @samp{vStopped}, and @samp{?} packets can +receive any of the below as a reply. Except for @samp{?} +and @samp{vStopped}, that reply is only returned +when the target halts. In the below the exact meaning of @dfn{signal +number} is defined by the header @file{include/gdb/signals.h} in the +@value{GDBN} source code. + +In non-stop mode, the server will simply reply @samp{OK} to commands +such as @samp{vCont}; any stop will be the subject of a future +notification. @xref{Remote Non-Stop}. + +As in the description of request packets, we include spaces in the +reply templates for clarity; these are not part of the reply packet's +syntax. No @value{GDBN} stop reply packet uses spaces to separate its +components. + +@table @samp + +@item S @var{AA} +The program received signal number @var{AA} (a two-digit hexadecimal +number). This is equivalent to a @samp{T} response with no +@var{n}:@var{r} pairs. + +@item T @var{AA} @var{n1}:@var{r1};@var{n2}:@var{r2};@dots{} +@cindex @samp{T} packet reply +The program received signal number @var{AA} (a two-digit hexadecimal +number). This is equivalent to an @samp{S} response, except that the +@samp{@var{n}:@var{r}} pairs can carry values of important registers +and other information directly in the stop reply packet, reducing +round-trip latency. Single-step and breakpoint traps are reported +this way. Each @samp{@var{n}:@var{r}} pair is interpreted as follows: + +@itemize @bullet +@item +If @var{n} is a hexadecimal number, it is a register number, and the +corresponding @var{r} gives that register's value. The data @var{r} is a +series of bytes in target byte order, with each byte given by a +two-digit hex number. + +@item +If @var{n} is @samp{thread}, then @var{r} is the thread ID of +the stopped thread, as specified in @ref{thread-id syntax}. + +@item +If @var{n} is @samp{core}, then @var{r} is the hexadecimal number of +the core on which the stop event was detected. + +@item +If @var{n} is a recognized @dfn{stop reason}, it describes a more +specific event that stopped the target. The currently defined stop +reasons are listed below. The @var{aa} should be @samp{05}, the trap +signal. At most one stop reason should be present. + +@item +Otherwise, @value{GDBN} should ignore this @samp{@var{n}:@var{r}} pair +and go on to the next; this allows us to extend the protocol in the +future. +@end itemize + +The currently defined stop reasons are: + +@table @samp +@item watch +@itemx rwatch +@itemx awatch +The packet indicates a watchpoint hit, and @var{r} is the data address, in +hex. + +@item syscall_entry +@itemx syscall_return +The packet indicates a syscall entry or return, and @var{r} is the +syscall number, in hex. + +@cindex shared library events, remote reply +@item library +The packet indicates that the loaded libraries have changed. +@value{GDBN} should use @samp{qXfer:libraries:read} to fetch a new +list of loaded libraries. The @var{r} part is ignored. + +@cindex replay log events, remote reply +@item replaylog +The packet indicates that the target cannot continue replaying +logged execution events, because it has reached the end (or the +beginning when executing backward) of the log. The value of @var{r} +will be either @samp{begin} or @samp{end}. @xref{Reverse Execution}, +for more information. + +@item swbreak +@anchor{swbreak stop reason} +The packet indicates a software breakpoint instruction was executed, +irrespective of whether it was @value{GDBN} that planted the +breakpoint or the breakpoint is hardcoded in the program. The @var{r} +part must be left empty. + +On some architectures, such as x86, at the architecture level, when a +breakpoint instruction executes the program counter points at the +breakpoint address plus an offset. On such targets, the stub is +responsible for adjusting the PC to point back at the breakpoint +address. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +This packet is required for correct non-stop mode operation. + +@item hwbreak +The packet indicates the target stopped for a hardware breakpoint. +The @var{r} part must be left empty. + +The same remarks about @samp{qSupported} and non-stop mode above +apply. + +@cindex fork events, remote reply +@item fork +The packet indicates that @code{fork} was called, and @var{r} is the +thread ID of the new child process, as specified in @ref{thread-id +syntax}. This packet is only applicable to targets that support fork +events. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +@cindex vfork events, remote reply +@item vfork +The packet indicates that @code{vfork} was called, and @var{r} is the +thread ID of the new child process, as specified in @ref{thread-id +syntax}. This packet is only applicable to targets that support vfork +events. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +@cindex vforkdone events, remote reply +@item vforkdone +The packet indicates that a child process created by a vfork +has either called @code{exec} or terminated, so that the +address spaces of the parent and child process are no longer +shared. The @var{r} part is ignored. This packet is only +applicable to targets that support vforkdone events. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +@cindex exec events, remote reply +@item exec +The packet indicates that @code{execve} was called, and @var{r} +is the absolute pathname of the file that was executed, in hex. +This packet is only applicable to targets that support exec events. + +This packet should not be sent by default; older @value{GDBN} versions +did not support it. @value{GDBN} requests it, by supplying an +appropriate @samp{qSupported} feature (@pxref{qSupported}). The +remote stub must also supply the appropriate @samp{qSupported} feature +indicating support. + +@cindex thread clone events, remote reply +@anchor{thread clone event} +@item clone +The packet indicates that @code{clone} was called, and @var{r} is the +thread ID of the new child thread, as specified in @ref{thread-id +syntax}. This packet is only applicable to targets that support clone +events. + +This packet should not be sent by default; @value{GDBN} requests it +with the @ref{QThreadOptions} packet. + +@cindex thread create event, remote reply +@anchor{thread create event} +@item create +The packet indicates that the thread was just created. The new thread +is stopped until @value{GDBN} sets it running with a resumption packet +(@pxref{vCont packet}). This packet should not be sent by default; +@value{GDBN} requests it with the @ref{QThreadEvents} packet. See +also the @samp{w} (@pxref{thread exit event}) remote reply below. The +@var{r} part is ignored. + +@end table + +@item W @var{AA} +@itemx W @var{AA} ; process:@var{pid} +The process exited, and @var{AA} is the exit status. This is only +applicable to certain targets. + +The second form of the response, including the process ID of the +exited process, can be used only when @value{GDBN} has reported +support for multiprocess protocol extensions; see @ref{multiprocess +extensions}. Both @var{AA} and @var{pid} are formatted as big-endian +hex strings. + +@item X @var{AA} +@itemx X @var{AA} ; process:@var{pid} +The process terminated with signal @var{AA}. + +The second form of the response, including the process ID of the +terminated process, can be used only when @value{GDBN} has reported +support for multiprocess protocol extensions; see @ref{multiprocess +extensions}. Both @var{AA} and @var{pid} are formatted as big-endian +hex strings. + +@anchor{thread exit event} +@cindex thread exit event, remote reply +@item w @var{AA} ; @var{tid} + +The thread exited, and @var{AA} is the exit status. This response +should not be sent by default; @value{GDBN} requests it with either +the @ref{QThreadEvents} or @ref{QThreadOptions} packets. See also +@ref{thread create event} above. @var{AA} is formatted as a +big-endian hex string. + +@item N +There are no resumed threads left in the target. In other words, even +though the process is alive, the last resumed thread has exited. For +example, say the target process has two threads: thread 1 and thread +2. The client leaves thread 1 stopped, and resumes thread 2, which +subsequently exits. At this point, even though the process is still +alive, and thus no @samp{W} stop reply is sent, no thread is actually +executing either. The @samp{N} stop reply thus informs the client +that it can stop waiting for stop replies. This packet should not be +sent by default; older @value{GDBN} versions did not support it. +@value{GDBN} requests it, by supplying an appropriate +@samp{qSupported} feature (@pxref{qSupported}). The remote stub must +also supply the appropriate @samp{qSupported} feature indicating +support. + +@item O @var{XX}@dots{} +@samp{@var{XX}@dots{}} is hex encoding of @sc{ascii} data, to be +written as the program's console output. This can happen at any time +while the program is running and the debugger should continue to wait +for @samp{W}, @samp{T}, etc. This reply is not permitted in non-stop mode. + +@item F @var{call-id},@var{parameter}@dots{} +@var{call-id} is the identifier which says which host system call should +be called. This is just the name of the function. Translation into the +correct system call is only applicable as it's defined in @value{GDBN}. +@xref{File-I/O Remote Protocol Extension}, for a list of implemented +system calls. + +@samp{@var{parameter}@dots{}} is a list of parameters as defined for +this very system call. + +The target replies with this packet when it expects @value{GDBN} to +call a host system call on behalf of the target. @value{GDBN} replies +with an appropriate @samp{F} packet and keeps up waiting for the next +reply packet from the target. The latest @samp{C}, @samp{c}, @samp{S} +or @samp{s} action is expected to be continued. @xref{File-I/O Remote +Protocol Extension}, for more details. + +@end table + +@node General Query Packets +@section General Query Packets +@cindex remote query requests + +Packets starting with @samp{q} are @dfn{general query packets}; +packets starting with @samp{Q} are @dfn{general set packets}. General +query and set packets are a semi-unified form for retrieving and +sending information to and from the stub. + +The initial letter of a query or set packet is followed by a name +indicating what sort of thing the packet applies to. For example, +@value{GDBN} may use a @samp{qSymbol} packet to exchange symbol +definitions with the stub. These packet names follow some +conventions: + +@itemize @bullet +@item +The name must not contain commas, colons or semicolons. +@item +Most @value{GDBN} query and set packets have a leading upper case +letter. +@item +The names of custom vendor packets should use a company prefix, in +lower case, followed by a period. For example, packets designed at +the Acme Corporation might begin with @samp{qacme.foo} (for querying +foos) or @samp{Qacme.bar} (for setting bars). +@end itemize + +The name of a query or set packet should be separated from any +parameters by a @samp{:}; the parameters themselves should be +separated by @samp{,} or @samp{;}. Stubs must be careful to match the +full packet name, and check for a separator or the end of the packet, +in case two packet names share a common prefix. New packets should not begin +with @samp{qC}, @samp{qP}, or @samp{qL}@footnote{The @samp{qP} and @samp{qL} +packets predate these conventions, and have arguments without any terminator +for the packet name; we suspect they are in widespread use in places that +are difficult to upgrade. The @samp{qC} packet has no arguments, but some +existing stubs (e.g.@: RedBoot) are known to not check for the end of the +packet.}. + +Like the descriptions of the other packets, each description here +has a template showing the packet's overall syntax, followed by an +explanation of the packet's meaning. We include spaces in some of the +templates for clarity; these are not part of the packet's syntax. No +@value{GDBN} packet uses spaces to separate its components. + +Here are the currently defined query and set packets: + +@table @samp + +@item QAgent:1 +@itemx QAgent:0 +Turn on or off the agent as a helper to perform some debugging operations +delegated from @value{GDBN} (@pxref{Control Agent}). + +@item QAllow:@var{op}:@var{val}@dots{} +@cindex @samp{QAllow} packet +Specify which operations @value{GDBN} expects to request of the +target, as a semicolon-separated list of operation name and value +pairs. Possible values for @var{op} include @samp{WriteReg}, +@samp{WriteMem}, @samp{InsertBreak}, @samp{InsertTrace}, +@samp{InsertFastTrace}, and @samp{Stop}. @var{val} is either 0, +indicating that @value{GDBN} will not request the operation, or 1, +indicating that it may. (The target can then use this to set up its +own internals optimally, for instance if the debugger never expects to +insert breakpoints, it may not need to install its own trap handler.) + +@item qC +@cindex current thread, remote request +@cindex @samp{qC} packet +Return the current thread ID. + +Reply: +@table @samp +@item QC @var{thread-id} +Where @var{thread-id} is a thread ID as documented in +@ref{thread-id syntax}. +@item @r{(anything else)} +Any other reply implies the old thread ID. +@end table + +@item qCRC:@var{addr},@var{length} +@cindex CRC of memory block, remote request +@cindex @samp{qCRC} packet +@anchor{qCRC packet} +Compute the CRC checksum of a block of memory using CRC-32 defined in +IEEE 802.3. The CRC is computed byte at a time, taking the most +significant bit of each byte first. The initial pattern code +@code{0xffffffff} is used to ensure leading zeros affect the CRC. + +@emph{Note:} This is the same CRC used in validating separate debug +files (@pxref{Separate Debug Files, , Debugging Information in Separate +Files}). However the algorithm is slightly different. When validating +separate debug files, the CRC is computed taking the @emph{least} +significant bit of each byte first, and the final result is inverted to +detect trailing zeros. + +Reply: +@table @samp +@item C @var{crc32} +The specified memory region's checksum is @var{crc32}. +@end table + +@item QDisableRandomization:@var{value} +@cindex disable address space randomization, remote request +@cindex @samp{QDisableRandomization} packet +Some target operating systems will randomize the virtual address space +of the inferior process as a security feature, but provide a feature +to disable such randomization, e.g.@: to allow for a more deterministic +debugging experience. On such systems, this packet with a @var{value} +of 1 directs the target to disable address space randomization for +processes subsequently started via @samp{vRun} packets, while a packet +with a @var{value} of 0 tells the target to enable address space +randomization. + +This packet is only available in extended mode (@pxref{extended mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +This should only be done on targets that actually support disabling +address space randomization. + +@item QStartupWithShell:@var{value} +@cindex startup with shell, remote request +@cindex @samp{QStartupWithShell} packet +On UNIX-like targets, it is possible to start the inferior using a +shell program. This is the default behavior on both @value{GDBN} and +@command{gdbserver} (@pxref{set startup-with-shell}). This packet is +used to inform @command{gdbserver} whether it should start the +inferior using a shell or not. + +If @var{value} is @samp{0}, @command{gdbserver} will not use a shell +to start the inferior. If @var{value} is @samp{1}, +@command{gdbserver} will use a shell to start the inferior. All other +values are considered an error. + +This packet is only available in extended mode (@pxref{extended +mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). This should only be done on targets that +actually support starting the inferior using a shell. + +Use of this packet is controlled by the @code{set startup-with-shell} +command; @pxref{set startup-with-shell}. + +@item QEnvironmentHexEncoded:@var{hex-value} +@anchor{QEnvironmentHexEncoded} +@cindex set environment variable, remote request +@cindex @samp{QEnvironmentHexEncoded} packet +On UNIX-like targets, it is possible to set environment variables that +will be passed to the inferior during the startup process. This +packet is used to inform @command{gdbserver} of an environment +variable that has been defined by the user on @value{GDBN} (@pxref{set +environment}). + +The packet is composed by @var{hex-value}, an hex encoded +representation of the @var{name=value} format representing an +environment variable. The name of the environment variable is +represented by @var{name}, and the value to be assigned to the +environment variable is represented by @var{value}. If the variable +has no value (i.e., the value is @code{null}), then @var{value} will +not be present. + +This packet is only available in extended mode (@pxref{extended +mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). This should only be done on targets that +actually support passing environment variables to the starting +inferior. + +This packet is related to the @code{set environment} command; +@pxref{set environment}. + +@item QEnvironmentUnset:@var{hex-value} +@anchor{QEnvironmentUnset} +@cindex unset environment variable, remote request +@cindex @samp{QEnvironmentUnset} packet +On UNIX-like targets, it is possible to unset environment variables +before starting the inferior in the remote target. This packet is +used to inform @command{gdbserver} of an environment variable that has +been unset by the user on @value{GDBN} (@pxref{unset environment}). + +The packet is composed by @var{hex-value}, an hex encoded +representation of the name of the environment variable to be unset. + +This packet is only available in extended mode (@pxref{extended +mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). This should only be done on targets that +actually support passing environment variables to the starting +inferior. + +This packet is related to the @code{unset environment} command; +@pxref{unset environment}. + +@item QEnvironmentReset +@anchor{QEnvironmentReset} +@cindex reset environment, remote request +@cindex @samp{QEnvironmentReset} packet +On UNIX-like targets, this packet is used to reset the state of +environment variables in the remote target before starting the +inferior. In this context, reset means unsetting all environment +variables that were previously set by the user (i.e., were not +initially present in the environment). It is sent to +@command{gdbserver} before the @samp{QEnvironmentHexEncoded} +(@pxref{QEnvironmentHexEncoded}) and the @samp{QEnvironmentUnset} +(@pxref{QEnvironmentUnset}) packets. + +This packet is only available in extended mode (@pxref{extended +mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). This should only be done on targets that +actually support passing environment variables to the starting +inferior. + +@item QSetWorkingDir:@r{[}@var{directory}@r{]} +@anchor{QSetWorkingDir packet} +@cindex set working directory, remote request +@cindex @samp{QSetWorkingDir} packet +This packet is used to inform the remote server of the intended +current working directory for programs that are going to be executed. + +The packet is composed by @var{directory}, an hex encoded +representation of the directory that the remote inferior will use as +its current working directory. If @var{directory} is an empty string, +the remote server should reset the inferior's current working +directory to its original, empty value. + +This packet is only available in extended mode (@pxref{extended +mode}). + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +@item qfThreadInfo +@itemx qsThreadInfo +@cindex list active threads, remote request +@cindex @samp{qfThreadInfo} packet +@cindex @samp{qsThreadInfo} packet +Obtain a list of all active thread IDs from the target (OS). Since there +may be too many active threads to fit into one reply packet, this query +works iteratively: it may require more than one query/reply sequence to +obtain the entire list of threads. The first query of the sequence will +be the @samp{qfThreadInfo} query; subsequent queries in the +sequence will be the @samp{qsThreadInfo} query. + +NOTE: This packet replaces the @samp{qL} query (see below). + +Reply: +@table @samp +@item m @var{thread-id} +A single thread ID +@item m @var{thread-id},@var{thread-id}@dots{} +a comma-separated list of thread IDs +@item l +(lower case letter @samp{L}) denotes end of list. +@end table + +In response to each query, the target will reply with a list of one or +more thread IDs, separated by commas. +@value{GDBN} will respond to each reply with a request for more thread +ids (using the @samp{qs} form of the query), until the target responds +with @samp{l} (lower-case ell, for @dfn{last}). +Refer to @ref{thread-id syntax}, for the format of the @var{thread-id} +fields. + +@emph{Note: @value{GDBN} will send the @code{qfThreadInfo} query during the +initial connection with the remote target, and the very first thread ID +mentioned in the reply will be stopped by @value{GDBN} in a subsequent +message. Therefore, the stub should ensure that the first thread ID in +the @code{qfThreadInfo} reply is suitable for being stopped by @value{GDBN}.} + +@item qGetTLSAddr:@var{thread-id},@var{offset},@var{lm} +@cindex get thread-local storage address, remote request +@cindex @samp{qGetTLSAddr} packet +Fetch the address associated with thread local storage specified +by @var{thread-id}, @var{offset}, and @var{lm}. + +@var{thread-id} is the thread ID associated with the +thread for which to fetch the TLS address. @xref{thread-id syntax}. + +@var{offset} is the (big endian, hex encoded) offset associated with the +thread local variable. (This offset is obtained from the debug +information associated with the variable.) + +@var{lm} is the (big endian, hex encoded) OS/ABI-specific encoding of the +load module associated with the thread local storage. For example, +a @sc{gnu}/Linux system will pass the link map address of the shared +object associated with the thread local storage under consideration. +Other operating environments may choose to represent the load module +differently, so the precise meaning of this parameter will vary. + +Reply: +@table @samp +@item @var{XX}@dots{} +Hex encoded (big endian) bytes representing the address of the thread +local storage requested. +@end table + +@item qGetTIBAddr:@var{thread-id} +@cindex get thread information block address +@cindex @samp{qGetTIBAddr} packet +Fetch address of the Windows OS specific Thread Information Block. + +@var{thread-id} is the thread ID associated with the thread. + +Reply: +@table @samp +@item @var{XX}@dots{} +Hex encoded (big endian) bytes representing the linear address of the +thread information block. +@end table + +@item qL @var{startflag} @var{threadcount} @var{nextthread} +Obtain thread information from RTOS. Where: @var{startflag} (one hex +digit) is one to indicate the first query and zero to indicate a +subsequent query; @var{threadcount} (two hex digits) is the maximum +number of threads the response packet can contain; and @var{nextthread} +(eight hex digits), for subsequent queries (@var{startflag} is zero), is +returned in the response as @var{argthread}. + +Don't use this packet; use the @samp{qfThreadInfo} query instead (see above). + +Reply: +@table @samp +@item qM @var{count} @var{done} @var{argthread} @var{thread}@dots{} +Where: @var{count} (two hex digits) is the number of threads being +returned; @var{done} (one hex digit) is zero to indicate more threads +and one indicates no further threads; @var{argthreadid} (eight hex +digits) is @var{nextthread} from the request packet; @var{thread}@dots{} +is a sequence of thread IDs, @var{threadid} (eight hex +digits), from the target. See @code{remote.c:parse_threadlist_response()}. +@end table + +@item qMemTags:@var{start address},@var{length}:@var{type} +@anchor{qMemTags} +@cindex fetch memory tags +@cindex @samp{qMemTags} packet +Fetch memory tags of type @var{type} from the address range +@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The +target is responsible for calculating how many tags will be returned, as this +is architecture-specific. + +@var{start address} is the starting address of the memory range. + +@var{length} is the length, in bytes, of the memory range. + +@var{type} is the type of tag the request wants to fetch. The type is a signed +integer. + +@value{GDBN} will only send this packet if the stub has advertised +support for memory tagging via @samp{qSupported}. + +Reply: +@table @samp +@item @var{mxx}@dots{} +Hex encoded sequence of uninterpreted bytes, @var{xx}@dots{}, representing the +tags found in the requested memory range. + +@end table + +@cindex check if a given address is in a memory tagged region +@cindex @samp{qIsAddressTagged} packet +@item qIsAddressTagged:@var{address} +@anchor {qIsAddressTagged} +Check if address @var{address} is in a memory tagged region; if it is, it's +said to be @dfn{tagged}. The target is responsible for checking it, as this +is architecture-specific. + +@var{address} is the address to be checked. + +Reply: +@table @samp +Replies to this packet should all be in two hex digit format, as follows: + +@item @samp{01} +Address @var{address} is tagged. + +@item @samp{00} +Address @var{address} is not tagged. +@end table + +@item QMemTags:@var{start address},@var{length}:@var{type}:@var{tag bytes} +@anchor{QMemTags} +@cindex store memory tags +@cindex @samp{QMemTags} packet +Store memory tags of type @var{type} to the address range +@w{@r{[}@var{start address}, @var{start address} + @var{length}@r{)}}. The +target is responsible for interpreting the type, the tag bytes and modifying +the memory tag granules accordingly, given this is architecture-specific. + +The interpretation of how many tags (@var{nt}) should be written to how many +memory tag granules (@var{ng}) is also architecture-specific. The behavior is +implementation-specific, but the following is suggested. + +If the number of memory tags, @var{nt}, is greater than or equal to the +number of memory tag granules, @var{ng}, only @var{ng} tags will be +stored. + +If @var{nt} is less than @var{ng}, the behavior is that of a fill operation, +and the tag bytes will be used as a pattern that will get repeated until +@var{ng} tags are stored. + +@var{start address} is the starting address of the memory range. The address +does not have any restriction on alignment or size. + +@var{length} is the length, in bytes, of the memory range. + +@var{type} is the type of tag the request wants to fetch. The type is a signed +integer. + +@var{tag bytes} is a sequence of hex encoded uninterpreted bytes which will be +interpreted by the target. Each pair of hex digits is interpreted as a +single byte. + +@value{GDBN} will only send this packet if the stub has advertised +support for memory tagging via @samp{qSupported}. + +Reply: +@table @samp +@item OK +The request was successful and the memory tag granules were modified +accordingly. +@end table + +@item qOffsets +@cindex section offsets, remote request +@cindex @samp{qOffsets} packet +Get section offsets that the target used when relocating the downloaded +image. + +Reply: +@table @samp +@item Text=@var{xxx};Data=@var{yyy}@r{[};Bss=@var{zzz}@r{]} +Relocate the @code{Text} section by @var{xxx} from its original address. +Relocate the @code{Data} section by @var{yyy} from its original address. +If the object file format provides segment information (e.g.@: @sc{elf} +@samp{PT_LOAD} program headers), @value{GDBN} will relocate entire +segments by the supplied offsets. + +@emph{Note: while a @code{Bss} offset may be included in the response, +@value{GDBN} ignores this and instead applies the @code{Data} offset +to the @code{Bss} section.} + +@item TextSeg=@var{xxx}@r{[};DataSeg=@var{yyy}@r{]} +Relocate the first segment of the object file, which conventionally +contains program code, to a starting address of @var{xxx}. If +@samp{DataSeg} is specified, relocate the second segment, which +conventionally contains modifiable data, to a starting address of +@var{yyy}. @value{GDBN} will report an error if the object file +does not contain segment information, or does not contain at least +as many segments as mentioned in the reply. Extra segments are +kept at fixed offsets relative to the last relocated segment. +@end table + +@item qP @var{mode} @var{thread-id} +@cindex thread information, remote request +@cindex @samp{qP} packet +Returns information on @var{thread-id}. Where: @var{mode} is a hex +encoded 32 bit mode; @var{thread-id} is a thread ID +(@pxref{thread-id syntax}). + +Don't use this packet; use the @samp{qThreadExtraInfo} query instead +(see below). + +Reply: see @code{remote.c:remote_unpack_thread_info_response()}. + +@item QNonStop:1 +@itemx QNonStop:0 +@cindex non-stop mode, remote request +@cindex @samp{QNonStop} packet +@anchor{QNonStop} +Enter non-stop (@samp{QNonStop:1}) or all-stop (@samp{QNonStop:0}) mode. +@xref{Remote Non-Stop}, for more information. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). +Use of this packet is controlled by the @code{set non-stop} command; +@pxref{Non-Stop Mode}. + +@item QCatchSyscalls:1 @r{[};@var{sysno}@r{]}@dots{} +@itemx QCatchSyscalls:0 +@cindex catch syscalls from inferior, remote request +@cindex @samp{QCatchSyscalls} packet +@anchor{QCatchSyscalls} +Enable (@samp{QCatchSyscalls:1}) or disable (@samp{QCatchSyscalls:0}) +catching syscalls from the inferior process. + +For @samp{QCatchSyscalls:1}, each listed syscall @var{sysno} (encoded +in hex) should be reported to @value{GDBN}. If no syscall @var{sysno} +is listed, every system call should be reported. + +Note that if a syscall not in the list is reported, @value{GDBN} will +still filter the event according to its own list from all corresponding +@code{catch syscall} commands. However, it is more efficient to only +report the requested syscalls. + +Multiple @samp{QCatchSyscalls:1} packets do not combine; any earlier +@samp{QCatchSyscalls:1} list is completely replaced by the new list. + +If the inferior process execs, the state of @samp{QCatchSyscalls} is +kept for the new process too. On targets where exec may affect syscall +numbers, for example with exec between 32 and 64-bit processes, the +client should send a new packet with the new syscall list. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +Use of this packet is controlled by the @code{set remote catch-syscalls} +command (@pxref{Remote Configuration, set remote catch-syscalls}). +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item QPassSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} +@cindex pass signals to inferior, remote request +@cindex @samp{QPassSignals} packet +@anchor{QPassSignals} +Each listed @var{signal} should be passed directly to the inferior process. +Signals are numbered identically to continue packets and stop replies +(@pxref{Stop Reply Packets}). Each @var{signal} list item should be +strictly greater than the previous item. These signals do not need to stop +the inferior, or be reported to @value{GDBN}. All other signals should be +reported to @value{GDBN}. Multiple @samp{QPassSignals} packets do not +combine; any earlier @samp{QPassSignals} list is completely replaced by the +new list. This packet improves performance when using @samp{handle +@var{signal} nostop noprint pass}. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +Use of this packet is controlled by the @code{set remote pass-signals} +command (@pxref{Remote Configuration, set remote pass-signals}). +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item QProgramSignals: @var{signal} @r{[};@var{signal}@r{]}@dots{} +@cindex signals the inferior may see, remote request +@cindex @samp{QProgramSignals} packet +@anchor{QProgramSignals} +Each listed @var{signal} may be delivered to the inferior process. +Others should be silently discarded. + +In some cases, the remote stub may need to decide whether to deliver a +signal to the program or not without @value{GDBN} involvement. One +example of that is while detaching --- the program's threads may have +stopped for signals that haven't yet had a chance of being reported to +@value{GDBN}, and so the remote stub can use the signal list specified +by this packet to know whether to deliver or ignore those pending +signals. + +This does not influence whether to deliver a signal as requested by a +resumption packet (@pxref{vCont packet}). + +Signals are numbered identically to continue packets and stop replies +(@pxref{Stop Reply Packets}). Each @var{signal} list item should be +strictly greater than the previous item. Multiple +@samp{QProgramSignals} packets do not combine; any earlier +@samp{QProgramSignals} list is completely replaced by the new list. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +Use of this packet is controlled by the @code{set remote program-signals} +command (@pxref{Remote Configuration, set remote program-signals}). +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@anchor{QThreadEvents} +@item QThreadEvents:1 +@itemx QThreadEvents:0 +@cindex thread create/exit events, remote request +@cindex @samp{QThreadEvents} packet + +Enable (@samp{QThreadEvents:1}) or disable (@samp{QThreadEvents:0}) +reporting of thread create and exit events. @xref{thread create +event}, for the reply specifications. For example, this is used in +non-stop mode when @value{GDBN} stops a set of threads and +synchronously waits for the their corresponding stop replies. Without +exit events, if one of the threads exits, @value{GDBN} would hang +forever not knowing that it should no longer expect a stop for that +same thread. @value{GDBN} does not enable this feature unless the +stub reports that it supports it by including @samp{QThreadEvents+} in +its @samp{qSupported} reply. + +This packet always enables/disables event reporting for all threads of +all processes under control of the remote stub. For per-thread +control of optional event reporting, see the @ref{QThreadOptions} +packet. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +Use of this packet is controlled by the @code{set remote thread-events} +command (@pxref{Remote Configuration, set remote thread-events}). + +@anchor{QThreadOptions} +@item QThreadOptions@r{[};@var{options}@r{[}:@var{thread-id}@r{]]}@dots{} +@cindex thread options, remote request +@cindex @samp{QThreadOptions} packet + +For each inferior thread, the last @var{options} in the list with a +matching @var{thread-id} are applied. Any options previously set on a +thread are discarded and replaced by the new options specified. +Threads that do not match any @var{thread-id} retain their +previously-set options. Thread IDs are specified using the syntax +described in @ref{thread-id syntax}. If multiprocess extensions +(@pxref{multiprocess extensions}) are supported, options can be +specified to apply to all threads of a process by using the +@samp{p@var{pid}.-1} form of @var{thread-id}. Options with no +@var{thread-id} apply to all threads. Specifying no options value is +an error. Zero is a valid value. + +@var{options} is an hexadecimal integer specifying the enabled thread +options, and is the bitwise @code{OR} of the following values. All +values are given in hexadecimal representation. + +@table @code +@item GDB_THREAD_OPTION_CLONE (0x1) +Report thread clone events (@pxref{thread clone event}). This is only +meaningful for targets that support clone events (e.g., GNU/Linux +systems). + +@item GDB_THREAD_OPTION_EXIT (0x2) +Report thread exit events (@pxref{thread exit event}). +@end table + +@noindent + +For example, @value{GDBN} enables the @code{GDB_THREAD_OPTION_EXIT} +and @code{GDB_THREAD_OPTION_CLONE} options when single-stepping a +thread past a breakpoint, for the following reasons: + +@itemize @bullet +@item +If the single-stepped thread exits (e.g., it executes a thread exit +system call), enabling @code{GDB_THREAD_OPTION_EXIT} prevents +@value{GDBN} from waiting forever, not knowing that it should no +longer expect a stop for that same thread, and blocking other threads +from progressing. + +@item +If the single-stepped thread spawns a new clone child (i.e., it +executes a clone system call), enabling @code{GDB_THREAD_OPTION_CLONE} +halts the cloned thread before it executes any instructions, and thus +prevents the following problematic situations: + +@itemize @minus +@item +If the breakpoint is stepped-over in-line, the spawned thread would +incorrectly run free while the breakpoint being stepped over is not +inserted, and thus the cloned thread may potentially run past the +breakpoint without stopping for it; + +@item +If displaced (out-of-line) stepping is used, the cloned thread starts +running at the out-of-line PC, leading to undefined behavior, usually +crashing or corrupting data. +@end itemize + +@end itemize + +New threads start with thread options cleared. + +@value{GDBN} does not enable this feature unless the stub reports that +it supports it by including +@samp{QThreadOptions=@var{supported_options}} in its @samp{qSupported} +reply. + +Reply: +@table @samp +@item OK +The request succeeded. +@end table + +Use of this packet is controlled by the @code{set remote thread-options} +command (@pxref{Remote Configuration, set remote thread-options}). + +@item qRcmd,@var{command} +@cindex execute remote command, remote request +@cindex @samp{qRcmd} packet +@var{command} (hex encoded) is passed to the local interpreter for +execution. Invalid commands should be reported using the output +string. Before the final result packet, the target may also respond +with a number of intermediate @samp{O@var{output}} console output +packets. @emph{Implementors should note that providing access to a +stubs's interpreter may have security implications}. + +Reply: +@table @samp +@item OK +A command response with no output. +@item @var{OUTPUT} +A command response with the hex encoded output string @var{OUTPUT}. +@end table + +Unlike most packets, this packet does not support +@samp{E.@var{errtext}}-style textual error replies (@pxref{textual +error reply}) by default. Stubs should be careful to only send such a +reply if @value{GDBN} reported support for it with the +@code{error-message} feature (@pxref{error-message}). + +(Note that the @code{qRcmd} packet's name is separated from the +command by a @samp{,}, not a @samp{:}, contrary to the naming +conventions above. Please don't use this packet as a model for new +packets.) + +@item qSearch:memory:@var{address};@var{length};@var{search-pattern} +@cindex searching memory, in remote debugging +@ifnotinfo +@cindex @samp{qSearch:memory} packet +@end ifnotinfo +@cindex @samp{qSearch memory} packet +@anchor{qSearch memory} +Search @var{length} bytes at @var{address} for @var{search-pattern}. +Both @var{address} and @var{length} are encoded in hex; +@var{search-pattern} is a sequence of bytes, also hex encoded. + +Reply: +@table @samp +@item 0 +The pattern was not found. +@item 1,address +The pattern was found at @var{address}. +@end table + +@item QStartNoAckMode +@cindex @samp{QStartNoAckMode} packet +@anchor{QStartNoAckMode} +Request that the remote stub disable the normal @samp{+}/@samp{-} +protocol acknowledgments (@pxref{Packet Acknowledgment}). + +Reply: +@table @samp +@item OK +The stub has switched to no-acknowledgment mode. +@value{GDBN} acknowledges this response, +but neither the stub nor @value{GDBN} shall send or expect further +@samp{+}/@samp{-} acknowledgments in the current connection. +@end table + +@item qSupported @r{[}:@var{gdbfeature} @r{[};@var{gdbfeature}@r{]}@dots{} @r{]} +@cindex supported packets, remote query +@cindex features of the remote protocol +@cindex @samp{qSupported} packet +@anchor{qSupported} +Tell the remote stub about features supported by @value{GDBN}, and +query the stub for features it supports. This packet allows +@value{GDBN} and the remote stub to take advantage of each others' +features. @samp{qSupported} also consolidates multiple feature probes +at startup, to improve @value{GDBN} performance---a single larger +packet performs better than multiple smaller probe packets on +high-latency links. Some features may enable behavior which must not +be on by default, e.g.@: because it would confuse older clients or +stubs. Other features may describe packets which could be +automatically probed for, but are not. These features must be +reported before @value{GDBN} will use them. This ``default +unsupported'' behavior is not appropriate for all packets, but it +helps to keep the initial connection time under control with new +versions of @value{GDBN} which support increasing numbers of packets. + +Reply: +@table @samp +@item @var{stubfeature} @r{[};@var{stubfeature}@r{]}@dots{} +The stub supports or does not support each returned @var{stubfeature}, +depending on the form of each @var{stubfeature} (see below for the +possible forms). +@end table + +The allowed forms for each feature (either a @var{gdbfeature} in the +@samp{qSupported} packet, or a @var{stubfeature} in the response) +are: + +@table @samp +@item @var{name}=@var{value} +The remote protocol feature @var{name} is supported, and associated +with the specified @var{value}. The format of @var{value} depends +on the feature, but it must not include a semicolon. +@item @var{name}+ +The remote protocol feature @var{name} is supported, and does not +need an associated value. +@item @var{name}- +The remote protocol feature @var{name} is not supported. +@item @var{name}? +The remote protocol feature @var{name} may be supported, and +@value{GDBN} should auto-detect support in some other way when it is +needed. This form will not be used for @var{gdbfeature} notifications, +but may be used for @var{stubfeature} responses. +@end table + +Whenever the stub receives a @samp{qSupported} request, the +supplied set of @value{GDBN} features should override any previous +request. This allows @value{GDBN} to put the stub in a known +state, even if the stub had previously been communicating with +a different version of @value{GDBN}. + +The following values of @var{gdbfeature} (for the packet sent by @value{GDBN}) +are defined: + +@table @samp +@item multiprocess +This feature indicates whether @value{GDBN} supports multiprocess +extensions to the remote protocol. @value{GDBN} does not use such +extensions unless the stub also reports that it supports them by +including @samp{multiprocess+} in its @samp{qSupported} reply. +@xref{multiprocess extensions}, for details. + +@item xmlRegisters +This feature indicates that @value{GDBN} supports the XML target +description. If the stub sees @samp{xmlRegisters=} with target +specific strings separated by a comma, it will report register +description. + +@item qRelocInsn +This feature indicates whether @value{GDBN} supports the +@samp{qRelocInsn} packet (@pxref{Tracepoint Packets,,Relocate +instruction reply packet}). + +@item swbreak +This feature indicates whether @value{GDBN} supports the swbreak stop +reason in stop replies. @xref{swbreak stop reason}, for details. + +@item hwbreak +This feature indicates whether @value{GDBN} supports the hwbreak stop +reason in stop replies. @xref{swbreak stop reason}, for details. + +@item fork-events +This feature indicates whether @value{GDBN} supports fork event +extensions to the remote protocol. @value{GDBN} does not use such +extensions unless the stub also reports that it supports them by +including @samp{fork-events+} in its @samp{qSupported} reply. + +@item vfork-events +This feature indicates whether @value{GDBN} supports vfork event +extensions to the remote protocol. @value{GDBN} does not use such +extensions unless the stub also reports that it supports them by +including @samp{vfork-events+} in its @samp{qSupported} reply. + +@item exec-events +This feature indicates whether @value{GDBN} supports exec event +extensions to the remote protocol. @value{GDBN} does not use such +extensions unless the stub also reports that it supports them by +including @samp{exec-events+} in its @samp{qSupported} reply. + +@item vContSupported +This feature indicates whether @value{GDBN} wants to know the +supported actions in the reply to @samp{vCont?} packet. + +@anchor{error-message} +@item error-message +This feature indicates whether @value{GDBN} supports accepting a reply +in @samp{E.@var{errtext}} format (@xref{textual error reply}) from the +@samp{qRcmd} and @samp{m} packets. These packets, historically, +didn't support @samp{E.@var{errtext}}, and older versions of +@value{GDBN} didn't expect to see a reply in this format. + +New packets should be written to support @samp{E.@var{errtext}} +regardless of this feature being true or not. +@end table + +Stubs should ignore any unknown values for +@var{gdbfeature}. Any @value{GDBN} which sends a @samp{qSupported} +packet supports receiving packets of unlimited length (earlier +versions of @value{GDBN} may reject overly long responses). Additional values +for @var{gdbfeature} may be defined in the future to let the stub take +advantage of new features in @value{GDBN}, e.g.@: incompatible +improvements in the remote protocol---the @samp{multiprocess} feature is +an example of such a feature. The stub's reply should be independent +of the @var{gdbfeature} entries sent by @value{GDBN}; first @value{GDBN} +describes all the features it supports, and then the stub replies with +all the features it supports. + +Similarly, @value{GDBN} will silently ignore unrecognized stub feature +responses, as long as each response uses one of the standard forms. + +Some features are flags. A stub which supports a flag feature +should respond with a @samp{+} form response. Other features +require values, and the stub should respond with an @samp{=} +form response. + +Each feature has a default value, which @value{GDBN} will use if +@samp{qSupported} is not available or if the feature is not mentioned +in the @samp{qSupported} response. The default values are fixed; a +stub is free to omit any feature responses that match the defaults. + +Not all features can be probed, but for those which can, the probing +mechanism is useful: in some cases, a stub's internal +architecture may not allow the protocol layer to know some information +about the underlying target in advance. This is especially common in +stubs which may be configured for multiple targets. + +These are the currently defined stub features and their properties: + +@multitable @columnfractions 0.35 0.2 0.12 0.2 +@c NOTE: The first row should be @headitem, but we do not yet require +@c a new enough version of Texinfo (4.7) to use @headitem. +@item Feature Name +@tab Value Required +@tab Default +@tab Probe Allowed + +@item @samp{PacketSize} +@tab Yes +@tab @samp{-} +@tab No + +@item @samp{qXfer:auxv:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:btrace:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:btrace-conf:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:exec-file:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:features:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:libraries:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:libraries-svr4:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{augmented-libraries-svr4-read} +@tab No +@tab @samp{-} +@tab No + +@item @samp{qXfer:memory-map:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:sdata:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:siginfo:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:siginfo:write} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:threads:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:traceframe-info:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:uib:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{qXfer:fdpic:read} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace:off} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace:bts} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace:pt} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace-conf:bts:size} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace-conf:pt:size} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace-conf:pt:ptwrite} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{Qbtrace-conf:pt:event-tracing} +@tab Yes +@tab @samp{-} +@tab Yes + +@item @samp{QNonStop} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{QCatchSyscalls} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{QPassSignals} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{QStartNoAckMode} +@tab No +@tab @samp{-} +@tab Yes + +@item @samp{multiprocess} +@tab No +@tab @samp{-} +@tab No + +@item @samp{ConditionalBreakpoints} +@tab No +@tab @samp{-} +@tab No + +@item @samp{ConditionalTracepoints} +@tab No +@tab @samp{-} +@tab No + +@item @samp{ReverseContinue} +@tab No +@tab @samp{-} +@tab No + +@item @samp{ReverseStep} +@tab No +@tab @samp{-} +@tab No + +@item @samp{TracepointSource} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QAgent} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QAllow} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QDisableRandomization} +@tab No +@tab @samp{-} +@tab No + +@item @samp{EnableDisableTracepoints} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QTBuffer:size} +@tab No +@tab @samp{-} +@tab No + +@item @samp{tracenz} +@tab No +@tab @samp{-} +@tab No + +@item @samp{BreakpointCommands} +@tab No +@tab @samp{-} +@tab No + +@item @samp{swbreak} +@tab No +@tab @samp{-} +@tab No + +@item @samp{hwbreak} +@tab No +@tab @samp{-} +@tab No + +@item @samp{fork-events} +@tab No +@tab @samp{-} +@tab No + +@item @samp{vfork-events} +@tab No +@tab @samp{-} +@tab No + +@item @samp{exec-events} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QThreadEvents} +@tab No +@tab @samp{-} +@tab No + +@item @samp{QThreadOptions} +@tab Yes +@tab @samp{-} +@tab No + +@item @samp{no-resumed} +@tab No +@tab @samp{-} +@tab No + +@item @samp{memory-tagging} +@tab No +@tab @samp{-} +@tab No + +@item @samp{error-message} +@tab No +@tab @samp{+} +@tab No + +@item @samp{binary-upload} +@tab No +@tab @samp{-} +@tab No + +@end multitable + +These are the currently defined stub features, in more detail: + +@table @samp +@cindex packet size, remote protocol +@item PacketSize=@var{bytes} +The remote stub can accept packets up to at least @var{bytes} in +length. @value{GDBN} will send packets up to this size for bulk +transfers, and will never send larger packets. This is a limit on the +data characters in the packet, not including the frame and checksum. +There is no trailing NUL byte in a remote protocol packet; if the stub +stores packets in a NUL-terminated format, it should allow an extra +byte in its buffer for the NUL. If this stub feature is not supported, +@value{GDBN} guesses based on the size of the @samp{g} packet response. + +@item qXfer:auxv:read +The remote stub understands the @samp{qXfer:auxv:read} packet +(@pxref{qXfer auxiliary vector read}). + +@item qXfer:btrace:read +The remote stub understands the @samp{qXfer:btrace:read} +packet (@pxref{qXfer btrace read}). + +@item qXfer:btrace-conf:read +The remote stub understands the @samp{qXfer:btrace-conf:read} +packet (@pxref{qXfer btrace-conf read}). + +@item qXfer:exec-file:read +The remote stub understands the @samp{qXfer:exec-file:read} packet +(@pxref{qXfer executable filename read}). + +@item qXfer:features:read +The remote stub understands the @samp{qXfer:features:read} packet +(@pxref{qXfer target description read}). + +@item qXfer:libraries:read +The remote stub understands the @samp{qXfer:libraries:read} packet +(@pxref{qXfer library list read}). + +@item qXfer:libraries-svr4:read +The remote stub understands the @samp{qXfer:libraries-svr4:read} packet +(@pxref{qXfer svr4 library list read}). + +@item augmented-libraries-svr4-read +The remote stub understands the augmented form of the +@samp{qXfer:libraries-svr4:read} packet +(@pxref{qXfer svr4 library list read}). + +@item qXfer:memory-map:read +The remote stub understands the @samp{qXfer:memory-map:read} packet +(@pxref{qXfer memory map read}). + +@item qXfer:sdata:read +The remote stub understands the @samp{qXfer:sdata:read} packet +(@pxref{qXfer sdata read}). + +@item qXfer:siginfo:read +The remote stub understands the @samp{qXfer:siginfo:read} packet +(@pxref{qXfer siginfo read}). + +@item qXfer:siginfo:write +The remote stub understands the @samp{qXfer:siginfo:write} packet +(@pxref{qXfer siginfo write}). + +@item qXfer:threads:read +The remote stub understands the @samp{qXfer:threads:read} packet +(@pxref{qXfer threads read}). + +@item qXfer:traceframe-info:read +The remote stub understands the @samp{qXfer:traceframe-info:read} +packet (@pxref{qXfer traceframe info read}). + +@item qXfer:uib:read +The remote stub understands the @samp{qXfer:uib:read} +packet (@pxref{qXfer unwind info block}). + +@item qXfer:fdpic:read +The remote stub understands the @samp{qXfer:fdpic:read} +packet (@pxref{qXfer fdpic loadmap read}). + +@item QNonStop +The remote stub understands the @samp{QNonStop} packet +(@pxref{QNonStop}). + +@item QCatchSyscalls +The remote stub understands the @samp{QCatchSyscalls} packet +(@pxref{QCatchSyscalls}). + +@item QPassSignals +The remote stub understands the @samp{QPassSignals} packet +(@pxref{QPassSignals}). + +@item QStartNoAckMode +The remote stub understands the @samp{QStartNoAckMode} packet and +prefers to operate in no-acknowledgment mode. @xref{Packet Acknowledgment}. + +@item multiprocess +@anchor{multiprocess extensions} +@cindex multiprocess extensions, in remote protocol +The remote stub understands the multiprocess extensions to the remote +protocol syntax. The multiprocess extensions affect the syntax of +thread IDs in both packets and replies (@pxref{thread-id syntax}), and +add process IDs to the @samp{D} packet and @samp{W} and @samp{X} +replies. Note that reporting this feature indicates support for the +syntactic extensions only, not that the stub necessarily supports +debugging of more than one process at a time. The stub must not use +multiprocess extensions in packet replies unless @value{GDBN} has also +indicated it supports them in its @samp{qSupported} request. + +@item qXfer:osdata:read +The remote stub understands the @samp{qXfer:osdata:read} packet +((@pxref{qXfer osdata read}). + +@item ConditionalBreakpoints +The target accepts and implements evaluation of conditional expressions +defined for breakpoints. The target will only report breakpoint triggers +when such conditions are true (@pxref{Conditions, ,Break Conditions}). + +@item ConditionalTracepoints +The remote stub accepts and implements conditional expressions defined +for tracepoints (@pxref{Tracepoint Conditions}). + +@item ReverseContinue +The remote stub accepts and implements the reverse continue packet +(@pxref{bc}). + +@item ReverseStep +The remote stub accepts and implements the reverse step packet +(@pxref{bs}). + +@item TracepointSource +The remote stub understands the @samp{QTDPsrc} packet that supplies +the source form of tracepoint definitions. + +@item QAgent +The remote stub understands the @samp{QAgent} packet. + +@item QAllow +The remote stub understands the @samp{QAllow} packet. + +@item QDisableRandomization +The remote stub understands the @samp{QDisableRandomization} packet. + +@item StaticTracepoint +@cindex static tracepoints, in remote protocol +The remote stub supports static tracepoints. + +@item InstallInTrace +@anchor{install tracepoint in tracing} +The remote stub supports installing tracepoint in tracing. + +@item EnableDisableTracepoints +The remote stub supports the @samp{QTEnable} (@pxref{QTEnable}) and +@samp{QTDisable} (@pxref{QTDisable}) packets that allow tracepoints +to be enabled and disabled while a trace experiment is running. + +@item QTBuffer:size +The remote stub supports the @samp{QTBuffer:size} (@pxref{QTBuffer-size}) +packet that allows to change the size of the trace buffer. + +@item tracenz +@cindex string tracing, in remote protocol +The remote stub supports the @samp{tracenz} bytecode for collecting strings. +See @ref{Bytecode Descriptions} for details about the bytecode. + +@item BreakpointCommands +@cindex breakpoint commands, in remote protocol +The remote stub supports running a breakpoint's command list itself, +rather than reporting the hit to @value{GDBN}. + +@item Qbtrace:off +The remote stub understands the @samp{Qbtrace:off} packet. + +@item Qbtrace:bts +The remote stub understands the @samp{Qbtrace:bts} packet. + +@item Qbtrace:pt +The remote stub understands the @samp{Qbtrace:pt} packet. + +@item Qbtrace-conf:bts:size +The remote stub understands the @samp{Qbtrace-conf:bts:size} packet. + +@item Qbtrace-conf:pt:size +The remote stub understands the @samp{Qbtrace-conf:pt:size} packet. + +@item Qbtrace-conf:pt:ptwrite +The remote stub understands the @samp{Qbtrace-conf:pt:ptwrite} packet. + +@item Qbtrace-conf:pt:event-tracing +The remote stub understands the @samp{Qbtrace-conf:pt:event-tracing} packet. + +@item swbreak +The remote stub reports the @samp{swbreak} stop reason for memory +breakpoints. + +@item hwbreak +The remote stub reports the @samp{hwbreak} stop reason for hardware +breakpoints. + +@item fork-events +The remote stub reports the @samp{fork} stop reason for fork events. + +@item vfork-events +The remote stub reports the @samp{vfork} stop reason for vfork events +and vforkdone events. + +@item exec-events +The remote stub reports the @samp{exec} stop reason for exec events. + +@item vContSupported +The remote stub reports the supported actions in the reply to +@samp{vCont?} packet. + +@item QThreadEvents +The remote stub understands the @samp{QThreadEvents} packet. + +@item QThreadOptions=@var{supported_options} +The remote stub understands the @samp{QThreadOptions} packet. +@var{supported_options} indicates the set of thread options the remote +stub supports. @var{supported_options} has the same format as the +@var{options} parameter of the @code{QThreadOptions} packet, described +at @ref{QThreadOptions}. + +@item no-resumed +The remote stub reports the @samp{N} stop reply. + + +@item memory-tagging +The remote stub supports and implements the required memory tagging +functionality and understands the @samp{qMemTags} (@pxref{qMemTags}) and +@samp{QMemTags} (@pxref{QMemTags}) packets. + +For AArch64 GNU/Linux systems, this feature can require access to the +@file{/proc/@var{pid}/smaps} file so memory mapping page flags can be +inspected, if @samp{qIsAddressTagged} (@pxref{qIsAddressTagged}) packet +is not supported by the stub. Access to the @file{/proc/@var{pid}/smaps} +file is done via @samp{vFile} requests. + +@item error-message +The remote stub supports replying with an error in a +@samp{E.@var{errtext}} (@xref{textual error reply}) format from the +@samp{m} and @samp{qRcmd} packets. It is not usually necessary to +send this feature back to @value{GDBN} in the @samp{qSupported} reply, +@value{GDBN} will always support @samp{E.@var{errtext}} format replies +if it sent the @samp{error-message} feature. + +@item binary-upload +The remote stub supports the @samp{x} packet (@pxref{x packet}). +@end table + +@item qSymbol:: +@cindex symbol lookup, remote request +@cindex @samp{qSymbol} packet +Notify the target that @value{GDBN} is prepared to serve symbol lookup +requests. Accept requests from the target for the values of symbols. + +Reply: +@table @samp +@item OK +The target does not need to look up any (more) symbols. +@item qSymbol:@var{sym_name} +The target requests the value of symbol @var{sym_name} (hex encoded). +@value{GDBN} may provide the value by using the +@samp{qSymbol:@var{sym_value}:@var{sym_name}} message, described +below. +@end table + +@item qSymbol:@var{sym_value}:@var{sym_name} +Set the value of @var{sym_name} to @var{sym_value}. + +@var{sym_name} (hex encoded) is the name of a symbol whose value the +target has previously requested. + +@var{sym_value} (hex) is the value for symbol @var{sym_name}. If +@value{GDBN} cannot supply a value for @var{sym_name}, then this field +will be empty. + +Reply: +@table @samp +@item OK +The target does not need to look up any (more) symbols. +@item qSymbol:@var{sym_name} +The target requests the value of a new symbol @var{sym_name} (hex +encoded). @value{GDBN} will continue to supply the values of symbols +(if available), until the target ceases to request them. +@end table + +@item qTBuffer +@itemx QTBuffer +@itemx QTDisconnected +@itemx QTDP +@itemx QTDPsrc +@itemx QTDV +@itemx qTfP +@itemx qTfV +@itemx QTFrame +@itemx qTMinFTPILen + +@xref{Tracepoint Packets}. + +@anchor{qThreadExtraInfo} +@item qThreadExtraInfo,@var{thread-id} +@cindex thread attributes info, remote request +@cindex @samp{qThreadExtraInfo} packet +Obtain from the target OS a printable string description of thread +attributes for the thread @var{thread-id}; see @ref{thread-id syntax}, +for the forms of @var{thread-id}. This +string may contain anything that the target OS thinks is interesting +for @value{GDBN} to tell the user about the thread. The string is +displayed in @value{GDBN}'s @code{info threads} display. Some +examples of possible thread extra info strings are @samp{Runnable}, or +@samp{Blocked on Mutex}. + +Reply: +@table @samp +@item @var{XX}@dots{} +Where @samp{@var{XX}@dots{}} is a hex encoding of @sc{ascii} data, +comprising the printable string containing the extra information about +the thread's attributes. +@end table + +(Note that the @code{qThreadExtraInfo} packet's name is separated from +the command by a @samp{,}, not a @samp{:}, contrary to the naming +conventions above. Please don't use this packet as a model for new +packets.) + +@item QTNotes +@itemx qTP +@itemx QTSave +@itemx qTsP +@itemx qTsV +@itemx QTStart +@itemx QTStop +@itemx QTEnable +@itemx QTDisable +@itemx QTinit +@itemx QTro +@itemx qTStatus +@itemx qTV +@itemx qTfSTM +@itemx qTsSTM +@itemx qTSTMat +@xref{Tracepoint Packets}. + +@item qXfer:@var{object}:read:@var{annex}:@var{offset},@var{length} +@cindex read special object, remote request +@cindex @samp{qXfer} packet +@anchor{qXfer read} +Read uninterpreted bytes from the target's special data area +identified by the keyword @var{object}. Request @var{length} bytes +starting at @var{offset} bytes into the data. The content and +encoding of @var{annex} is specific to @var{object}; it can supply +additional details about what data to access. + +Reply: +@table @samp +@item m @var{data} +Data @var{data} (@pxref{Binary Data}) has been read from the +target. There may be more data at a higher address (although +it is permitted to return @samp{m} even for the last valid +block of data, as long as at least one byte of data was read). +It is possible for @var{data} to have fewer bytes than the @var{length} in the +request. + +@item l @var{data} +Data @var{data} (@pxref{Binary Data}) has been read from the target. +There is no more data to be read. It is possible for @var{data} to +have fewer bytes than the @var{length} in the request. + +@item l +The @var{offset} in the request is at the end of the data. +There is no more data to be read. +@end table + +Here are the specific requests of this form defined so far. All the +@samp{qXfer:@var{object}:read:@dots{}} requests use the same reply +formats, listed above. + +@table @samp +@item qXfer:auxv:read::@var{offset},@var{length} +@anchor{qXfer auxiliary vector read} +Access the target's @dfn{auxiliary vector}. @xref{OS Information, +auxiliary vector}. Note @var{annex} must be empty. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:btrace:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer btrace read} + +Return a description of the current branch trace. +@xref{Branch Trace Format}. The annex part of the generic @samp{qXfer} +packet may have one of the following values: + +@table @code +@item all +Returns all available branch trace. + +@item new +Returns all available branch trace if the branch trace changed since +the last read request. + +@item delta +Returns the new branch trace since the last read request. Adds a new +block to the end of the trace that begins at zero and ends at the source +location of the first branch in the trace buffer. This extra block is +used to stitch traces together. + +If the trace buffer overflowed, returns an error indicating the overflow. +@end table + +This packet is not probed by default; the remote stub must request it +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:btrace-conf:read::@var{offset},@var{length} +@anchor{qXfer btrace-conf read} + +Return a description of the current branch trace configuration. +@xref{Branch Trace Configuration Format}. + +This packet is not probed by default; the remote stub must request it +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:exec-file:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer executable filename read} +Return the full absolute name of the file that was executed to create +a process running on the remote system. The annex specifies the +numeric process ID of the process to query, encoded as a hexadecimal +number. If the annex part is empty the remote stub should return the +filename corresponding to the currently executing process. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:features:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer target description read} +Access the @dfn{target description}. @xref{Target Descriptions}. The +annex specifies which XML document to access. The main description is +always loaded from the @samp{target.xml} annex. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:libraries:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer library list read} +Access the target's list of loaded libraries. @xref{Library List Format}. +The annex part of the generic @samp{qXfer} packet must be empty +(@pxref{qXfer read}). + +Targets which maintain a list of libraries in the program's memory do +not need to implement this packet; it is designed for platforms where +the operating system manages the list of loaded libraries. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:libraries-svr4:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer svr4 library list read} +Access the target's list of loaded libraries when the target is an SVR4 +platform. @xref{Library List Format for SVR4 Targets}. The annex part +of the generic @samp{qXfer} packet must be empty unless the remote +stub indicated it supports the augmented form of this packet +by supplying an appropriate @samp{qSupported} response +(@pxref{qXfer read}, @ref{qSupported}). + +This packet is optional for better performance on SVR4 targets. +@value{GDBN} uses memory read packets to read the SVR4 library list otherwise. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +If the remote stub indicates it supports the augmented form of this +packet then the annex part of the generic @samp{qXfer} packet may +contain a semicolon-separated list of @samp{@var{name}=@var{value}} +arguments. The currently supported arguments are: + +@table @code +@item start=@var{address} +A hexadecimal number specifying the address of the @samp{struct +link_map} to start reading the library list from. If unset or zero +then the first @samp{struct link_map} in the library list will be +chosen as the starting point. + +@item prev=@var{address} +A hexadecimal number specifying the address of the @samp{struct +link_map} immediately preceding the @samp{struct link_map} +specified by the @samp{start} argument. If unset or zero then +the remote stub will expect that no @samp{struct link_map} +exists prior to the starting point. + +@item lmid=@var{lmid} +A hexadecimal number specifying a namespace identifier. This is +currently only used together with @samp{start} to provide the +namespace identifier back to @value{GDBN} in the response. +@value{GDBN} will only provide values that were previously reported to +it. If unset, the response will include @samp{lmid="0x0"}. +@end table + +Arguments that are not understood by the remote stub will be silently +ignored. + +@item qXfer:memory-map:read::@var{offset},@var{length} +@anchor{qXfer memory map read} +Access the target's @dfn{memory-map}. @xref{Memory Map Format}. The +annex part of the generic @samp{qXfer} packet must be empty +(@pxref{qXfer read}). + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:sdata:read::@var{offset},@var{length} +@anchor{qXfer sdata read} + +Read contents of the extra collected static tracepoint marker +information. The annex part of the generic @samp{qXfer} packet must +be empty (@pxref{qXfer read}). @xref{Tracepoint Actions,,Tracepoint +Action Lists}. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). + +@item qXfer:siginfo:read::@var{offset},@var{length} +@anchor{qXfer siginfo read} +Read contents of the extra signal information on the target +system. The annex part of the generic @samp{qXfer} packet must be +empty (@pxref{qXfer read}). + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). + +@item qXfer:threads:read::@var{offset},@var{length} +@anchor{qXfer threads read} +Access the list of threads on target. @xref{Thread List Format}. The +annex part of the generic @samp{qXfer} packet must be empty +(@pxref{qXfer read}). + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:traceframe-info:read::@var{offset},@var{length} +@anchor{qXfer traceframe info read} + +Return a description of the current traceframe's contents. +@xref{Traceframe Info Format}. The annex part of the generic +@samp{qXfer} packet must be empty (@pxref{qXfer read}). + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:uib:read:@var{pc}:@var{offset},@var{length} +@anchor{qXfer unwind info block} + +Return the unwind information block for @var{pc}. This packet is used +on OpenVMS/ia64 to ask the kernel unwind information. + +This packet is not probed by default. + +@item qXfer:fdpic:read:@var{annex}:@var{offset},@var{length} +@anchor{qXfer fdpic loadmap read} +Read contents of @code{loadmap}s on the target system. The +annex, either @samp{exec} or @samp{interp}, specifies which @code{loadmap}, +executable @code{loadmap} or interpreter @code{loadmap} to read. + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response (@pxref{qSupported}). + +@item qXfer:osdata:read::@var{offset},@var{length} +@anchor{qXfer osdata read} +Access the target's @dfn{operating system information}. +@xref{Operating System Information}. + +@end table + +@item qXfer:@var{object}:write:@var{annex}:@var{offset}:@var{data}@dots{} +@cindex write data into object, remote request +@anchor{qXfer write} +Write uninterpreted bytes into the target's special data area +identified by the keyword @var{object}, starting at @var{offset} bytes +into the data. The binary-encoded data (@pxref{Binary Data}) to be +written is given by @var{data}@dots{}. The content and encoding of @var{annex} +is specific to @var{object}; it can supply additional details about what data +to access. + +Reply: +@table @samp +@item @var{nn} +@var{nn} (hex encoded) is the number of bytes written. +This may be fewer bytes than supplied in the request. +@end table + +Here are the specific requests of this form defined so far. All the +@samp{qXfer:@var{object}:write:@dots{}} requests use the same reply +formats, listed above. + +@table @samp +@item qXfer:siginfo:write::@var{offset}:@var{data}@dots{} +@anchor{qXfer siginfo write} +Write @var{data} to the extra signal information on the target system. +The annex part of the generic @samp{qXfer} packet must be +empty (@pxref{qXfer write}). + +This packet is not probed by default; the remote stub must request it, +by supplying an appropriate @samp{qSupported} response +(@pxref{qSupported}). +@end table + +@item qXfer:@var{object}:@var{operation}:@dots{} +Requests of this form may be added in the future. When a stub does +not recognize the @var{object} keyword, or its support for +@var{object} does not recognize the @var{operation} keyword, the stub +must respond with an empty packet. + +@item qAttached:@var{pid} +@cindex query attached, remote request +@cindex @samp{qAttached} packet +Return an indication of whether the remote server attached to an +existing process or created a new process. When the multiprocess +protocol extensions are supported (@pxref{multiprocess extensions}), +@var{pid} is an integer in hexadecimal format identifying the target +process. Otherwise, @value{GDBN} will omit the @var{pid} field and +the query packet will be simplified as @samp{qAttached}. + +This query is used, for example, to know whether the remote process +should be detached or killed when a @value{GDBN} session is ended with +the @code{quit} command. + +Reply: +@table @samp +@item 1 +The remote server attached to an existing process. +@item 0 +The remote server created a new process. +@end table + +@item Qbtrace:bts +Enable branch tracing for the current thread using Branch Trace Store. + +Reply: +@table @samp +@item OK +Branch tracing has been enabled. +@end table + +@item Qbtrace:pt +Enable branch tracing for the current thread using Intel Processor Trace. + +Reply: +@table @samp +@item OK +Branch tracing has been enabled. +@end table + +@item Qbtrace:off +Disable branch tracing for the current thread. + +Reply: +@table @samp +@item OK +Branch tracing has been disabled. +@end table + +@item Qbtrace-conf:bts:size=@var{value} +Set the requested ring buffer size for new threads that use the +btrace recording method in bts format. + +Reply: +@table @samp +@item OK +The ring buffer size has been set. +@end table + +@item Qbtrace-conf:pt:size=@var{value} +Set the requested ring buffer size for new threads that use the +btrace recording method in pt format. + +Reply: +@table @samp +@item OK +The ring buffer size has been set. +@end table + +@item Qbtrace-conf:pt:ptwrite=@var{(yes|no)} +Indicate support for @code{PTWRITE} packets. This allows for backwards +compatibility. + +Reply: +@table @samp +@item OK +The ptwrite config parameter has been set. +@item E.errtext +A badly formed request or an error was encountered. +@end table + +@item Qbtrace-conf:pt:event-tracing=@var{(yes|no)} +Indicate support for event-tracing packets. This allows for backwards +compatibility. + +Reply: +@table @samp +@item OK +The event-tracing config parameter has been set. +@item E.errtext +A badly formed request or an error was encountered. +@end table + +@end table + +@node Architecture-Specific Protocol Details +@section Architecture-Specific Protocol Details + +This section describes how the remote protocol is applied to specific +target architectures. Also see @ref{Standard Target Features}, for +details of XML target descriptions for each architecture. + +@menu +* ARM-Specific Protocol Details:: +* MIPS-Specific Protocol Details:: +@end menu + +@node ARM-Specific Protocol Details +@subsection @acronym{ARM}-specific Protocol Details + +@menu +* ARM Breakpoint Kinds:: +* ARM Memory Tag Types:: +@end menu + +@node ARM Breakpoint Kinds +@subsubsection @acronym{ARM} Breakpoint Kinds +@cindex breakpoint kinds, @acronym{ARM} + +These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. + +@table @r + +@item 2 +16-bit Thumb mode breakpoint. + +@item 3 +32-bit Thumb mode (Thumb-2) breakpoint. + +@item 4 +32-bit @acronym{ARM} mode breakpoint. + +@end table + +@node ARM Memory Tag Types +@subsubsection @acronym{ARM} Memory Tag Types +@cindex memory tag types, @acronym{ARM} + +These memory tag types are defined for the @samp{qMemTag} and @samp{QMemTag} +packets. + +@table @r + +@item 0 +MTE logical tag + +@item 1 +MTE allocation tag + +@end table + +@node MIPS-Specific Protocol Details +@subsection @acronym{MIPS}-specific Protocol Details + +@menu +* MIPS Register packet Format:: +* MIPS Breakpoint Kinds:: +@end menu + +@node MIPS Register packet Format +@subsubsection @acronym{MIPS} Register Packet Format +@cindex register packet format, @acronym{MIPS} + +The following @code{g}/@code{G} packets have previously been defined. +In the below, some thirty-two bit registers are transferred as +sixty-four bits. Those registers should be zero/sign extended (which?) +to fill the space allocated. Register bytes are transferred in target +byte order. The two nibbles within a register byte are transferred +most-significant -- least-significant. + +@table @r + +@item MIPS32 +All registers are transferred as thirty-two bit quantities in the order: +32 general-purpose; sr; lo; hi; bad; cause; pc; 32 floating-point +registers; fsr; fir; fp. + +@item MIPS64 +All registers are transferred as sixty-four bit quantities (including +thirty-two bit registers such as @code{sr}). The ordering is the same +as @code{MIPS32}. + +@end table + +@node MIPS Breakpoint Kinds +@subsubsection @acronym{MIPS} Breakpoint Kinds +@cindex breakpoint kinds, @acronym{MIPS} + +These breakpoint kinds are defined for the @samp{Z0} and @samp{Z1} packets. + +@table @r + +@item 2 +16-bit @acronym{MIPS16} mode breakpoint. + +@item 3 +16-bit @acronym{microMIPS} mode breakpoint. + +@item 4 +32-bit standard @acronym{MIPS} mode breakpoint. + +@item 5 +32-bit @acronym{microMIPS} mode breakpoint. + +@end table + +@node Tracepoint Packets +@section Tracepoint Packets +@cindex tracepoint packets +@cindex packets, tracepoint + +Here we describe the packets @value{GDBN} uses to implement +tracepoints (@pxref{Tracepoints}). + +@table @samp + +@item QTDP:@var{n}:@var{addr}:@var{ena}:@var{step}:@var{pass}[:F@var{flen}][:X@var{len},@var{bytes}]@r{[}-@r{]} +@cindex @samp{QTDP} packet +Create a new tracepoint, number @var{n}, at @var{addr}. If @var{ena} +is @samp{E}, then the tracepoint is enabled; if it is @samp{D}, then +the tracepoint is disabled. The @var{step} gives the tracepoint's step +count, and @var{pass} gives its pass count. If an @samp{F} is present, +then the tracepoint is to be a fast tracepoint, and the @var{flen} is +the number of bytes that the target should copy elsewhere to make room +for the tracepoint. If an @samp{X} is present, it introduces a +tracepoint condition, which consists of a hexadecimal length, followed +by a comma and hex-encoded bytes, in a manner similar to action +encodings as described below. If the trailing @samp{-} is present, +further @samp{QTDP} packets will follow to specify this tracepoint's +actions. + +Replies: +@table @samp +@item OK +The packet was understood and carried out. +@item qRelocInsn +@xref{Tracepoint Packets,,Relocate instruction reply packet}. +@end table + +@item QTDP:-@var{n}:@var{addr}:@r{[}S@r{]}@var{action}@dots{}@r{[}-@r{]} +Define actions to be taken when a tracepoint is hit. The @var{n} and +@var{addr} must be the same as in the initial @samp{QTDP} packet for +this tracepoint. This packet may only be sent immediately after +another @samp{QTDP} packet that ended with a @samp{-}. If the +trailing @samp{-} is present, further @samp{QTDP} packets will follow, +specifying more actions for this tracepoint. + +In the series of action packets for a given tracepoint, at most one +can have an @samp{S} before its first @var{action}. If such a packet +is sent, it and the following packets define ``while-stepping'' +actions. Any prior packets define ordinary actions --- that is, those +taken when the tracepoint is first hit. If no action packet has an +@samp{S}, then all the packets in the series specify ordinary +tracepoint actions. + +The @samp{@var{action}@dots{}} portion of the packet is a series of +actions, concatenated without separators. Each action has one of the +following forms: + +@table @samp + +@item R @var{mask} +Collect the registers whose bits are set in @var{mask}, +a hexadecimal number whose @var{i}'th bit is set if register number +@var{i} should be collected. (The least significant bit is numbered +zero.) Note that @var{mask} may be any number of digits long; it may +not fit in a 32-bit word. + +@item M @var{basereg},@var{offset},@var{len} +Collect @var{len} bytes of memory starting at the address in register +number @var{basereg}, plus @var{offset}. If @var{basereg} is +@samp{-1}, then the range has a fixed address: @var{offset} is the +address of the lowest byte to collect. The @var{basereg}, +@var{offset}, and @var{len} parameters are all unsigned hexadecimal +values (the @samp{-1} value for @var{basereg} is a special case). + +@item X @var{len},@var{expr} +Evaluate @var{expr}, whose length is @var{len}, and collect memory as +it directs. The agent expression @var{expr} is as described in +@ref{Agent Expressions}. Each byte of the expression is encoded as a +two-digit hex number in the packet; @var{len} is the number of bytes +in the expression (and thus one-half the number of hex digits in the +packet). + +@end table + +Any number of actions may be packed together in a single @samp{QTDP} +packet, as long as the packet does not exceed the maximum packet +length (400 bytes, for many stubs). There may be only one @samp{R} +action per tracepoint, and it must precede any @samp{M} or @samp{X} +actions. Any registers referred to by @samp{M} and @samp{X} actions +must be collected by a preceding @samp{R} action. (The +``while-stepping'' actions are treated as if they were attached to a +separate tracepoint, as far as these restrictions are concerned.) + +Replies: +@table @samp +@item OK +The packet was understood and carried out. +@item qRelocInsn +@xref{Tracepoint Packets,,Relocate instruction reply packet}. +@end table + +@item QTDPsrc:@var{n}:@var{addr}:@var{type}:@var{start}:@var{slen}:@var{bytes} +@cindex @samp{QTDPsrc} packet +Specify a source string of tracepoint @var{n} at address @var{addr}. +This is useful to get accurate reproduction of the tracepoints +originally downloaded at the beginning of the trace run. The @var{type} +is the name of the tracepoint part, such as @samp{cond} for the +tracepoint's conditional expression (see below for a list of types), while +@var{bytes} is the string, encoded in hexadecimal. + +@var{start} is the offset of the @var{bytes} within the overall source +string, while @var{slen} is the total length of the source string. +This is intended for handling source strings that are longer than will +fit in a single packet. +@c Add detailed example when this info is moved into a dedicated +@c tracepoint descriptions section. + +The available string types are @samp{at} for the location, +@samp{cond} for the conditional, and @samp{cmd} for an action command. +@value{GDBN} sends a separate packet for each command in the action +list, in the same order in which the commands are stored in the list. + +The target does not need to do anything with source strings except +report them back as part of the replies to the @samp{qTfP}/@samp{qTsP} +query packets. + +Although this packet is optional, and @value{GDBN} will only send it +if the target replies with @samp{TracepointSource} @xref{General +Query Packets}, it makes both disconnected tracing and trace files +much easier to use. Otherwise the user must be careful that the +tracepoints in effect while looking at trace frames are identical to +the ones in effect during the trace run; even a small discrepancy +could cause @samp{tdump} not to work, or a particular trace frame not +be found. + +@item QTDV:@var{n}:@var{value}:@var{builtin}:@var{name} +@cindex define trace state variable, remote request +@cindex @samp{QTDV} packet +Create a new trace state variable, number @var{n}, with an initial +value of @var{value}, which is a 64-bit signed integer. Both @var{n} +and @var{value} are encoded as hexadecimal values. @value{GDBN} has +the option of not using this packet for initial values of zero; the +target should simply create the trace state variables as they are +mentioned in expressions. The value @var{builtin} should be 1 (one) +if the trace state variable is builtin and 0 (zero) if it is not builtin. +@value{GDBN} only sets @var{builtin} to 1 if a previous @samp{qTfV} or +@samp{qTsV} packet had it set. The contents of @var{name} is the +hex-encoded name (without the leading @samp{$}) of the trace state +variable. + +@item QTFrame:@var{n} +@cindex @samp{QTFrame} packet +Select the @var{n}'th tracepoint frame from the buffer, and use the +register and memory contents recorded there to answer subsequent +request packets from @value{GDBN}. + +A successful reply from the stub indicates that the stub has found the +requested frame. The response is a series of parts, concatenated +without separators, describing the frame we selected. Each part has +one of the following forms: + +@table @samp +@item F @var{f} +The selected frame is number @var{n} in the trace frame buffer; +@var{f} is a hexadecimal number. If @var{f} is @samp{-1}, then there +was no frame matching the criteria in the request packet. + +@item T @var{t} +The selected trace frame records a hit of tracepoint number @var{t}; +@var{t} is a hexadecimal number. + +@end table + +@item QTFrame:pc:@var{addr} +Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the +currently selected frame whose PC is @var{addr}; +@var{addr} is a hexadecimal number. + +@item QTFrame:tdp:@var{t} +Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the +currently selected frame that is a hit of tracepoint @var{t}; @var{t} +is a hexadecimal number. + +@item QTFrame:range:@var{start}:@var{end} +Like @samp{QTFrame:@var{n}}, but select the first tracepoint frame after the +currently selected frame whose PC is between @var{start} (inclusive) +and @var{end} (inclusive); @var{start} and @var{end} are hexadecimal +numbers. + +@item QTFrame:outside:@var{start}:@var{end} +Like @samp{QTFrame:range:@var{start}:@var{end}}, but select the first +frame @emph{outside} the given range of addresses (exclusive). + +@item qTMinFTPILen +@cindex @samp{qTMinFTPILen} packet +This packet requests the minimum length of instruction at which a fast +tracepoint (@pxref{Set Tracepoints}) may be placed. For instance, on +the 32-bit x86 architecture, it is possible to use a 4-byte jump, but +it depends on the target system being able to create trampolines in +the first 64K of memory, which might or might not be possible for that +system. So the reply to this packet will be 4 if it is able to +arrange for that. + +Replies: + +@table @samp +@item 0 +The minimum instruction length is currently unknown. +@item @var{length} +The minimum instruction length is @var{length}, where @var{length} +is a hexadecimal number greater or equal to 1. A reply +of 1 means that a fast tracepoint may be placed on any instruction +regardless of size. +@item E +An error has occurred. +@end table + +@item QTStart +@cindex @samp{QTStart} packet +Begin the tracepoint experiment. Begin collecting data from +tracepoint hits in the trace frame buffer. This packet supports the +@samp{qRelocInsn} reply (@pxref{Tracepoint Packets,,Relocate +instruction reply packet}). + +@item QTStop +@cindex @samp{QTStop} packet +End the tracepoint experiment. Stop collecting trace frames. + +@item QTEnable:@var{n}:@var{addr} +@anchor{QTEnable} +@cindex @samp{QTEnable} packet +Enable tracepoint @var{n} at address @var{addr} in a started tracepoint +experiment. If the tracepoint was previously disabled, then collection +of data from it will resume. + +@item QTDisable:@var{n}:@var{addr} +@anchor{QTDisable} +@cindex @samp{QTDisable} packet +Disable tracepoint @var{n} at address @var{addr} in a started tracepoint +experiment. No more data will be collected from the tracepoint unless +@samp{QTEnable:@var{n}:@var{addr}} is subsequently issued. + +@item QTinit +@cindex @samp{QTinit} packet +Clear the table of tracepoints, and empty the trace frame buffer. + +@item QTro:@var{start1},@var{end1}:@var{start2},@var{end2}:@dots{} +@cindex @samp{QTro} packet +Establish the given ranges of memory as ``transparent''. The stub +will answer requests for these ranges from memory's current contents, +if they were not collected as part of the tracepoint hit. + +@value{GDBN} uses this to mark read-only regions of memory, like those +containing program code. Since these areas never change, they should +still have the same contents they did when the tracepoint was hit, so +there's no reason for the stub to refuse to provide their contents. + +@item QTDisconnected:@var{value} +@cindex @samp{QTDisconnected} packet +Set the choice to what to do with the tracing run when @value{GDBN} +disconnects from the target. A @var{value} of 1 directs the target to +continue the tracing run, while 0 tells the target to stop tracing if +@value{GDBN} is no longer in the picture. + +@item qTStatus +@cindex @samp{qTStatus} packet +Ask the stub if there is a trace experiment running right now. + +The reply has the form: + +@table @samp + +@item T@var{running}@r{[};@var{field}@r{]}@dots{} +@var{running} is a single digit @code{1} if the trace is presently +running, or @code{0} if not. It is followed by semicolon-separated +optional fields that an agent may use to report additional status. + +@end table + +If the trace is not running, the agent may report any of several +explanations as one of the optional fields: + +@table @samp + +@item tnotrun:0 +No trace has been run yet. + +@item tstop[:@var{text}]:0 +The trace was stopped by a user-originated stop command. The optional +@var{text} field is a user-supplied string supplied as part of the +stop command (for instance, an explanation of why the trace was +stopped manually). It is hex-encoded. + +@item tfull:0 +The trace stopped because the trace buffer filled up. + +@item tdisconnected:0 +The trace stopped because @value{GDBN} disconnected from the target. + +@item tpasscount:@var{tpnum} +The trace stopped because tracepoint @var{tpnum} exceeded its pass count. + +@item terror:@var{text}:@var{tpnum} +The trace stopped because tracepoint @var{tpnum} had an error. The +string @var{text} is available to describe the nature of the error +(for instance, a divide by zero in the condition expression); it +is hex encoded. + +@item tunknown:0 +The trace stopped for some other reason. + +@end table + +Additional optional fields supply statistical and other information. +Although not required, they are extremely useful for users monitoring +the progress of a trace run. If a trace has stopped, and these +numbers are reported, they must reflect the state of the just-stopped +trace. + +@table @samp + +@item tframes:@var{n} +The number of trace frames in the buffer. + +@item tcreated:@var{n} +The total number of trace frames created during the run. This may +be larger than the trace frame count, if the buffer is circular. + +@item tsize:@var{n} +The total size of the trace buffer, in bytes. + +@item tfree:@var{n} +The number of bytes still unused in the buffer. + +@item circular:@var{n} +The value of the circular trace buffer flag. @code{1} means that the +trace buffer is circular and old trace frames will be discarded if +necessary to make room, @code{0} means that the trace buffer is linear +and may fill up. + +@item disconn:@var{n} +The value of the disconnected tracing flag. @code{1} means that +tracing will continue after @value{GDBN} disconnects, @code{0} means +that the trace run will stop. + +@end table + +@item qTP:@var{tp}:@var{addr} +@cindex tracepoint status, remote request +@cindex @samp{qTP} packet +Ask the stub for the current state of tracepoint number @var{tp} at +address @var{addr}. + +Replies: +@table @samp +@item V@var{hits}:@var{usage} +The tracepoint has been hit @var{hits} times so far during the trace +run, and accounts for @var{usage} in the trace buffer. Note that +@code{while-stepping} steps are not counted as separate hits, but the +steps' space consumption is added into the usage number. + +@end table + +@item qTV:@var{var} +@cindex trace state variable value, remote request +@cindex @samp{qTV} packet +Ask the stub for the value of the trace state variable number @var{var}. + +Replies: +@table @samp +@item V@var{value} +The value of the variable is @var{value}. This will be the current +value of the variable if the user is examining a running target, or a +saved value if the variable was collected in the trace frame that the +user is looking at. Note that multiple requests may result in +different reply values, such as when requesting values while the +program is running. + +@item U +The value of the variable is unknown. This would occur, for example, +if the user is examining a trace frame in which the requested variable +was not collected. +@end table + +@item qTfP +@cindex @samp{qTfP} packet +@itemx qTsP +@cindex @samp{qTsP} packet +These packets request data about tracepoints that are being used by +the target. @value{GDBN} sends @code{qTfP} to get the first piece +of data, and multiple @code{qTsP} to get additional pieces. Replies +to these packets generally take the form of the @code{QTDP} packets +that define tracepoints. (FIXME add detailed syntax) + +@item qTfV +@cindex @samp{qTfV} packet +@itemx qTsV +@cindex @samp{qTsV} packet +These packets request data about trace state variables that are on the +target. @value{GDBN} sends @code{qTfV} to get the first vari of data, +and multiple @code{qTsV} to get additional variables. Replies to +these packets follow the syntax of the @code{QTDV} packets that define +trace state variables. + +@item qTfSTM +@itemx qTsSTM +@anchor{qTfSTM} +@anchor{qTsSTM} +@cindex @samp{qTfSTM} packet +@cindex @samp{qTsSTM} packet +These packets request data about static tracepoint markers that exist +in the target program. @value{GDBN} sends @code{qTfSTM} to get the +first piece of data, and multiple @code{qTsSTM} to get additional +pieces. Replies to these packets take the following form: + +Reply: +@table @samp +@item m @var{address}:@var{id}:@var{extra} +A single marker +@item m @var{address}:@var{id}:@var{extra},@var{address}:@var{id}:@var{extra}@dots{} +a comma-separated list of markers +@item l +(lower case letter @samp{L}) denotes end of list. +@end table + +The @var{address} is encoded in hex; +@var{id} and @var{extra} are strings encoded in hex. + +In response to each query, the target will reply with a list of one or +more markers, separated by commas. @value{GDBN} will respond to each +reply with a request for more markers (using the @samp{qs} form of the +query), until the target responds with @samp{l} (lower-case ell, for +@dfn{last}). + +@item qTSTMat:@var{address} +@anchor{qTSTMat} +@cindex @samp{qTSTMat} packet +This packets requests data about static tracepoint markers in the +target program at @var{address}. Replies to this packet follow the +syntax of the @samp{qTfSTM} and @code{qTsSTM} packets that list static +tracepoint markers. + +@item QTSave:@var{filename} +@cindex @samp{QTSave} packet +This packet directs the target to save trace data to the file name +@var{filename} in the target's filesystem. The @var{filename} is encoded +as a hex string; the interpretation of the file name (relative vs +absolute, wild cards, etc) is up to the target. + +@item qTBuffer:@var{offset},@var{len} +@cindex @samp{qTBuffer} packet +Return up to @var{len} bytes of the current contents of trace buffer, +starting at @var{offset}. The trace buffer is treated as if it were +a contiguous collection of traceframes, as per the trace file format. +The reply consists as many hex-encoded bytes as the target can deliver +in a packet; it is not an error to return fewer than were asked for. +A reply consisting of just @code{l} indicates that no bytes are +available. + +@item QTBuffer:circular:@var{value} +This packet directs the target to use a circular trace buffer if +@var{value} is 1, or a linear buffer if the value is 0. + +@item QTBuffer:size:@var{size} +@anchor{QTBuffer-size} +@cindex @samp{QTBuffer size} packet +This packet directs the target to make the trace buffer be of size +@var{size} if possible. A value of @code{-1} tells the target to +use whatever size it prefers. + +@item QTNotes:@r{[}@var{type}:@var{text}@r{]}@r{[};@var{type}:@var{text}@r{]}@dots{} +@cindex @samp{QTNotes} packet +This packet adds optional textual notes to the trace run. Allowable +types include @code{user}, @code{notes}, and @code{tstop}, the +@var{text} fields are arbitrary strings, hex-encoded. + +@end table + +@subsection Relocate instruction reply packet +When installing fast tracepoints in memory, the target may need to +relocate the instruction currently at the tracepoint address to a +different address in memory. For most instructions, a simple copy is +enough, but, for example, call instructions that implicitly push the +return address on the stack, and relative branches or other +PC-relative instructions require offset adjustment, so that the effect +of executing the instruction at a different address is the same as if +it had executed in the original location. + +In response to several of the tracepoint packets, the target may also +respond with a number of intermediate @samp{qRelocInsn} request +packets before the final result packet, to have @value{GDBN} handle +this relocation operation. If a packet supports this mechanism, its +documentation will explicitly say so. See for example the above +descriptions for the @samp{QTStart} and @samp{QTDP} packets. The +format of the request is: + +@table @samp +@item qRelocInsn:@var{from};@var{to} + +This requests @value{GDBN} to copy instruction at address @var{from} +to address @var{to}, possibly adjusted so that executing the +instruction at @var{to} has the same effect as executing it at +@var{from}. @value{GDBN} writes the adjusted instruction to target +memory starting at @var{to}. +@end table + +Replies: +@table @samp +@item qRelocInsn:@var{adjusted_size} +Informs the stub the relocation is complete. The @var{adjusted_size} is +the length in bytes of resulting relocated instruction sequence. +@end table + +@node Host I/O Packets +@section Host I/O Packets +@cindex Host I/O, remote protocol +@cindex file transfer, remote protocol + +The @dfn{Host I/O} packets allow @value{GDBN} to perform I/O +operations on the far side of a remote link. For example, Host I/O is +used to upload and download files to a remote target with its own +filesystem. Host I/O uses the same constant values and data structure +layout as the target-initiated File-I/O protocol. However, the +Host I/O packets are structured differently. The target-initiated +protocol relies on target memory to store parameters and buffers. +Host I/O requests are initiated by @value{GDBN}, and the +target's memory is not involved. @xref{File-I/O Remote Protocol +Extension}, for more details on the target-initiated protocol. + +The Host I/O request packets all encode a single operation along with +its arguments. They have this format: + +@table @samp + +@item vFile:@var{operation}: @var{parameter}@dots{} +@var{operation} is the name of the particular request; the target +should compare the entire packet name up to the second colon when checking +for a supported operation. The format of @var{parameter} depends on +the operation. Numbers are always passed in hexadecimal. Negative +numbers have an explicit minus sign (i.e.@: two's complement is not +used). Strings (e.g.@: filenames) are encoded as a series of +hexadecimal bytes. The last argument to a system call may be a +buffer of escaped binary data (@pxref{Binary Data}). + +@end table + +The valid responses to Host I/O packets are: + +@table @samp + +@item F @var{result} [, @var{errno}] [; @var{attachment}] +@var{result} is the integer value returned by this operation, usually +non-negative for success and -1 for errors. If an error has occurred, +@var{errno} will be included in the result specifying a +value defined by the File-I/O protocol (@pxref{Errno Values}). For +operations which return data, @var{attachment} supplies the data as a +binary buffer. Binary buffers in response packets are escaped in the +normal way (@pxref{Binary Data}). See the individual packet +documentation for the interpretation of @var{result} and +@var{attachment}. + +@item @w{} +An empty response indicates that this operation is not recognized. + +@end table + +These are the supported Host I/O operations: + +@table @samp +@item vFile:open: @var{filename}, @var{flags}, @var{mode} +Open a file at @var{filename} and return a file descriptor for it, or +return -1 if an error occurs. The @var{filename} is a string, +@var{flags} is an integer indicating a mask of open flags +(@pxref{Open Flags}), and @var{mode} is an integer indicating a mask +of mode bits to use if the file is created (@pxref{mode_t Values}). +@xref{open}, for details of the open flags and mode values. + +@item vFile:close: @var{fd} +Close the open file corresponding to @var{fd} and return 0, or +-1 if an error occurs. + +@item vFile:pread: @var{fd}, @var{count}, @var{offset} +Read data from the open file corresponding to @var{fd}. Up to +@var{count} bytes will be read from the file, starting at @var{offset} +relative to the start of the file. The target may read fewer bytes; +common reasons include packet size limits and an end-of-file +condition. The number of bytes read is returned. Zero should only be +returned for a successful read at the end of the file, or if +@var{count} was zero. + +The data read should be returned as a binary attachment on success. +If zero bytes were read, the response should include an empty binary +attachment (i.e.@: a trailing semicolon). The return value is the +number of target bytes read; the binary attachment may be longer if +some characters were escaped. + +@item vFile:pwrite: @var{fd}, @var{offset}, @var{data} +Write @var{data} (a binary buffer) to the open file corresponding +to @var{fd}. Start the write at @var{offset} from the start of the +file. Unlike many @code{write} system calls, there is no +separate @var{count} argument; the length of @var{data} in the +packet is used. @samp{vFile:pwrite} returns the number of bytes written, +which may be shorter than the length of @var{data}, or -1 if an +error occurred. + +@item vFile:fstat: @var{fd} +Get information about the open file corresponding to @var{fd}. +On success the information is returned as a binary attachment +and the return value is the size of this attachment in bytes. +If an error occurs the return value is -1. The format of the +returned binary attachment is as described in @ref{struct stat}. + +@item vFile:stat: @var{filename} +Get information about the file @var{filename} on the target. +On success the information is returned as a binary attachment +and the return value is the size of this attachment in bytes. +If an error occurs the return value is -1. The format of the +returned binary attachment is as described in @ref{struct stat}. + +@item vFile:unlink: @var{filename} +Delete the file at @var{filename} on the target. Return 0, +or -1 if an error occurs. The @var{filename} is a string. + +@item vFile:readlink: @var{filename} +Read value of symbolic link @var{filename} on the target. Return +the number of bytes read, or -1 if an error occurs. + +The data read should be returned as a binary attachment on success. +If zero bytes were read, the response should include an empty binary +attachment (i.e.@: a trailing semicolon). The return value is the +number of target bytes read; the binary attachment may be longer if +some characters were escaped. + +@item vFile:setfs: @var{pid} +Select the filesystem on which @code{vFile} operations with +@var{filename} arguments will operate. This is required for +@value{GDBN} to be able to access files on remote targets where +the remote stub does not share a common filesystem with the +inferior(s). + +If @var{pid} is nonzero, select the filesystem as seen by process +@var{pid}. If @var{pid} is zero, select the filesystem as seen by +the remote stub. Return 0 on success, or -1 if an error occurs. +If @code{vFile:setfs:} indicates success, the selected filesystem +remains selected until the next successful @code{vFile:setfs:} +operation. + +@end table + +@node Interrupts +@section Interrupts +@cindex interrupts (remote protocol) +@anchor{interrupting remote targets} + +In all-stop mode, when a program on the remote target is running, +@value{GDBN} may attempt to interrupt it by sending a @samp{Ctrl-C}, +@code{BREAK} or a @code{BREAK} followed by @code{g}, control of which +is specified via @value{GDBN}'s @samp{interrupt-sequence}. + +The precise meaning of @code{BREAK} is defined by the transport +mechanism and may, in fact, be undefined. @value{GDBN} does not +currently define a @code{BREAK} mechanism for any of the network +interfaces except for TCP, in which case @value{GDBN} sends the +@code{telnet} BREAK sequence. + +@samp{Ctrl-C}, on the other hand, is defined and implemented for all +transport mechanisms. It is represented by sending the single byte +@code{0x03} without any of the usual packet overhead described in +the Overview section (@pxref{Overview}). When a @code{0x03} byte is +transmitted as part of a packet, it is considered to be packet data +and does @emph{not} represent an interrupt. E.g., an @samp{X} packet +(@pxref{X packet}), used for binary downloads, may include an unescaped +@code{0x03} as part of its packet. + +@code{BREAK} followed by @code{g} is also known as Magic SysRq g. +When Linux kernel receives this sequence from serial port, +it stops execution and connects to gdb. + +In non-stop mode, because packet resumptions are asynchronous +(@pxref{vCont packet}), @value{GDBN} is always free to send a remote +command to the remote stub, even when the target is running. For that +reason, @value{GDBN} instead sends a regular packet (@pxref{vCtrlC +packet}) with the usual packet framing instead of the single byte +@code{0x03}. + +Stubs are not required to recognize these interrupt mechanisms and the +precise meaning associated with receipt of the interrupt is +implementation defined. If the target supports debugging of multiple +threads and/or processes, it should attempt to interrupt all +currently-executing threads and processes. +If the stub is successful at interrupting the +running program, it should send one of the stop +reply packets (@pxref{Stop Reply Packets}) to @value{GDBN} as a result +of successfully stopping the program in all-stop mode, and a stop reply +for each stopped thread in non-stop mode. +Interrupts received while the +program is stopped are queued and the program will be interrupted when +it is resumed next time. + +@node Notification Packets +@section Notification Packets +@cindex notification packets +@cindex packets, notification + +The @value{GDBN} remote serial protocol includes @dfn{notifications}, +packets that require no acknowledgment. Both the GDB and the stub +may send notifications (although the only notifications defined at +present are sent by the stub). Notifications carry information +without incurring the round-trip latency of an acknowledgment, and so +are useful for low-impact communications where occasional packet loss +is not a problem. + +A notification packet has the form @samp{% @var{data} # +@var{checksum}}, where @var{data} is the content of the notification, +and @var{checksum} is a checksum of @var{data}, computed and formatted +as for ordinary @value{GDBN} packets. A notification's @var{data} +never contains @samp{$}, @samp{%} or @samp{#} characters. Upon +receiving a notification, the recipient sends no @samp{+} or @samp{-} +to acknowledge the notification's receipt or to report its corruption. + +Every notification's @var{data} begins with a name, which contains no +colon characters, followed by a colon character. + +Recipients should silently ignore corrupted notifications and +notifications they do not understand. Recipients should restart +timeout periods on receipt of a well-formed notification, whether or +not they understand it. + +Senders should only send the notifications described here when this +protocol description specifies that they are permitted. In the +future, we may extend the protocol to permit existing notifications in +new contexts; this rule helps older senders avoid confusing newer +recipients. + +(Older versions of @value{GDBN} ignore bytes received until they see +the @samp{$} byte that begins an ordinary packet, so new stubs may +transmit notifications without fear of confusing older clients. There +are no notifications defined for @value{GDBN} to send at the moment, but we +assume that most older stubs would ignore them, as well.) + +Each notification is comprised of three parts: +@table @samp +@item @var{name}:@var{event} +The notification packet is sent by the side that initiates the +exchange (currently, only the stub does that), with @var{event} +carrying the specific information about the notification, and +@var{name} specifying the name of the notification. +@item @var{ack} +The acknowledge sent by the other side, usually @value{GDBN}, to +acknowledge the exchange and request the event. +@end table + +The purpose of an asynchronous notification mechanism is to report to +@value{GDBN} that something interesting happened in the remote stub. + +The remote stub may send notification @var{name}:@var{event} +at any time, but @value{GDBN} acknowledges the notification when +appropriate. The notification event is pending before @value{GDBN} +acknowledges. Only one notification at a time may be pending; if +additional events occur before @value{GDBN} has acknowledged the +previous notification, they must be queued by the stub for later +synchronous transmission in response to @var{ack} packets from +@value{GDBN}. Because the notification mechanism is unreliable, +the stub is permitted to resend a notification if it believes +@value{GDBN} may not have received it. + +Specifically, notifications may appear when @value{GDBN} is not +otherwise reading input from the stub, or when @value{GDBN} is +expecting to read a normal synchronous response or a +@samp{+}/@samp{-} acknowledgment to a packet it has sent. +Notification packets are distinct from any other communication from +the stub so there is no ambiguity. + +After receiving a notification, @value{GDBN} shall acknowledge it by +sending a @var{ack} packet as a regular, synchronous request to the +stub. Such acknowledgment is not required to happen immediately, as +@value{GDBN} is permitted to send other, unrelated packets to the +stub first, which the stub should process normally. + +Upon receiving a @var{ack} packet, if the stub has other queued +events to report to @value{GDBN}, it shall respond by sending a +normal @var{event}. @value{GDBN} shall then send another @var{ack} +packet to solicit further responses; again, it is permitted to send +other, unrelated packets as well which the stub should process +normally. + +If the stub receives a @var{ack} packet and there are no additional +@var{event} to report, the stub shall return an @samp{OK} response. +At this point, @value{GDBN} has finished processing a notification +and the stub has completed sending any queued events. @value{GDBN} +won't accept any new notifications until the final @samp{OK} is +received . If further notification events occur, the stub shall send +a new notification, @value{GDBN} shall accept the notification, and +the process shall be repeated. + +The process of asynchronous notification can be illustrated by the +following example: +@smallexample +<- @code{%Stop:T0505:98e7ffbf;04:4ce6ffbf;08:b1b6e54c;thread:p7526.7526;core:0;} +@code{...} +-> @code{vStopped} +<- @code{T0505:68f37db7;04:40f37db7;08:63850408;thread:p7526.7528;core:0;} +-> @code{vStopped} +<- @code{T0505:68e3fdb6;04:40e3fdb6;08:63850408;thread:p7526.7529;core:0;} +-> @code{vStopped} +<- @code{OK} +@end smallexample + +The following notifications are defined: +@multitable @columnfractions 0.12 0.12 0.38 0.38 + +@item Notification +@tab Ack +@tab Event +@tab Description + +@item Stop +@tab vStopped +@tab @var{reply}. The @var{reply} has the form of a stop reply, as +described in @ref{Stop Reply Packets}. Refer to @ref{Remote Non-Stop}, +for information on how these notifications are acknowledged by +@value{GDBN}. +@tab Report an asynchronous stop event in non-stop mode. + +@end multitable + +@node Remote Non-Stop +@section Remote Protocol Support for Non-Stop Mode + +@value{GDBN}'s remote protocol supports non-stop debugging of +multi-threaded programs, as described in @ref{Non-Stop Mode}. If the stub +supports non-stop mode, it should report that to @value{GDBN} by including +@samp{QNonStop+} in its @samp{qSupported} response (@pxref{qSupported}). + +@value{GDBN} typically sends a @samp{QNonStop} packet only when +establishing a new connection with the stub. Entering non-stop mode +does not alter the state of any currently-running threads, but targets +must stop all threads in any already-attached processes when entering +all-stop mode. @value{GDBN} uses the @samp{?} packet as necessary to +probe the target state after a mode change. + +In non-stop mode, when an attached process encounters an event that +would otherwise be reported with a stop reply, it uses the +asynchronous notification mechanism (@pxref{Notification Packets}) to +inform @value{GDBN}. In contrast to all-stop mode, where all threads +in all processes are stopped when a stop reply is sent, in non-stop +mode only the thread reporting the stop event is stopped. That is, +when reporting a @samp{S} or @samp{T} response to indicate completion +of a step operation, hitting a breakpoint, or a fault, only the +affected thread is stopped; any other still-running threads continue +to run. When reporting a @samp{W} or @samp{X} response, all running +threads belonging to other attached processes continue to run. + +In non-stop mode, the target shall respond to the @samp{?} packet as +follows. First, any incomplete stop reply notification/@samp{vStopped} +sequence in progress is abandoned. The target must begin a new +sequence reporting stop events for all stopped threads, whether or not +it has previously reported those events to @value{GDBN}. The first +stop reply is sent as a synchronous reply to the @samp{?} packet, and +subsequent stop replies are sent as responses to @samp{vStopped} packets +using the mechanism described above. The target must not send +asynchronous stop reply notifications until the sequence is complete. +If all threads are running when the target receives the @samp{?} packet, +or if the target is not attached to any process, it shall respond +@samp{OK}. + +If the stub supports non-stop mode, it should also support the +@samp{swbreak} stop reason if software breakpoints are supported, and +the @samp{hwbreak} stop reason if hardware breakpoints are supported +(@pxref{swbreak stop reason}). This is because given the asynchronous +nature of non-stop mode, between the time a thread hits a breakpoint +and the time the event is finally processed by @value{GDBN}, the +breakpoint may have already been removed from the target. Due to +this, @value{GDBN} needs to be able to tell whether a trap stop was +caused by a delayed breakpoint event, which should be ignored, as +opposed to a random trap signal, which should be reported to the user. +Note the @samp{swbreak} feature implies that the target is responsible +for adjusting the PC when a software breakpoint triggers, if +necessary, such as on the x86 architecture. + +@node Packet Acknowledgment +@section Packet Acknowledgment + +@cindex acknowledgment, for @value{GDBN} remote +@cindex packet acknowledgment, for @value{GDBN} remote +By default, when either the host or the target machine receives a packet, +the first response expected is an acknowledgment: either @samp{+} (to indicate +the package was received correctly) or @samp{-} (to request retransmission). +This mechanism allows the @value{GDBN} remote protocol to operate over +unreliable transport mechanisms, such as a serial line. + +In cases where the transport mechanism is itself reliable (such as a pipe or +TCP connection), the @samp{+}/@samp{-} acknowledgments are redundant. +It may be desirable to disable them in that case to reduce communication +overhead, or for other reasons. This can be accomplished by means of the +@samp{QStartNoAckMode} packet; @pxref{QStartNoAckMode}. + +When in no-acknowledgment mode, neither the stub nor @value{GDBN} shall send or +expect @samp{+}/@samp{-} protocol acknowledgments. The packet +and response format still includes the normal checksum, as described in +@ref{Overview}, but the checksum may be ignored by the receiver. + +If the stub supports @samp{QStartNoAckMode} and prefers to operate in +no-acknowledgment mode, it should report that to @value{GDBN} +by including @samp{QStartNoAckMode+} in its response to @samp{qSupported}; +@pxref{qSupported}. +If @value{GDBN} also supports @samp{QStartNoAckMode} and it has not been +disabled via the @code{set remote noack-packet off} command +(@pxref{Remote Configuration}), +@value{GDBN} may then send a @samp{QStartNoAckMode} packet to the stub. +Only then may the stub actually turn off packet acknowledgments. +@value{GDBN} sends a final @samp{+} acknowledgment of the stub's @samp{OK} +response, which can be safely ignored by the stub. + +Note that @code{set remote noack-packet} command only affects negotiation +between @value{GDBN} and the stub when subsequent connections are made; +it does not affect the protocol acknowledgment state for any current +connection. +Since @samp{+}/@samp{-} acknowledgments are enabled by default when a +new connection is established, +there is also no protocol request to re-enable the acknowledgments +for the current connection, once disabled. + +@node Examples +@section Examples + +Example sequence of a target being re-started. Notice how the restart +does not get any direct output: + +@smallexample +-> @code{R00} +<- @code{+} +@emph{target restarts} +-> @code{?} +<- @code{+} +<- @code{T001:1234123412341234} +-> @code{+} +@end smallexample + +Example sequence of a target being stepped by a single instruction: + +@smallexample +-> @code{G1445@dots{}} +<- @code{+} +-> @code{s} +<- @code{+} +@emph{time passes} +<- @code{T001:1234123412341234} +-> @code{+} +-> @code{g} +<- @code{+} +<- @code{1455@dots{}} +-> @code{+} +@end smallexample + +@node File-I/O Remote Protocol Extension +@section File-I/O Remote Protocol Extension +@cindex File-I/O remote protocol extension + +@menu +* File-I/O Overview:: +* Protocol Basics:: +* The F Request Packet:: +* The F Reply Packet:: +* The Ctrl-C Message:: +* Console I/O:: +* List of Supported Calls:: +* Protocol-specific Representation of Datatypes:: +* Constants:: +* File-I/O Examples:: +@end menu + +@node File-I/O Overview +@subsection File-I/O Overview +@cindex file-i/o overview + +The @dfn{File I/O remote protocol extension} (short: File-I/O) allows the +target to use the host's file system and console I/O to perform various +system calls. System calls on the target system are translated into a +remote protocol packet to the host system, which then performs the needed +actions and returns a response packet to the target system. +This simulates file system operations even on targets that lack file systems. + +The protocol is defined to be independent of both the host and target systems. +It uses its own internal representation of datatypes and values. Both +@value{GDBN} and the target's @value{GDBN} stub are responsible for +translating the system-dependent value representations into the internal +protocol representations when data is transmitted. + +The communication is synchronous. A system call is possible only when +@value{GDBN} is waiting for a response from the @samp{C}, @samp{c}, @samp{S} +or @samp{s} packets. While @value{GDBN} handles the request for a system call, +the target is stopped to allow deterministic access to the target's +memory. Therefore File-I/O is not interruptible by target signals. On +the other hand, it is possible to interrupt File-I/O by a user interrupt +(@samp{Ctrl-C}) within @value{GDBN}. + +The target's request to perform a host system call does not finish +the latest @samp{C}, @samp{c}, @samp{S} or @samp{s} action. That means, +after finishing the system call, the target returns to continuing the +previous activity (continue, step). No additional continue or step +request from @value{GDBN} is required. + +@smallexample +(@value{GDBP}) continue + <- target requests 'system call X' + target is stopped, @value{GDBN} executes system call + -> @value{GDBN} returns result + ... target continues, @value{GDBN} returns to wait for the target + <- target hits breakpoint and sends a Txx packet +@end smallexample + +The protocol only supports I/O on the console and to regular files on +the host file system. Character or block special devices, pipes, +named pipes, sockets or any other communication method on the host +system are not supported by this protocol. + +File I/O is not supported in non-stop mode. + +@node Protocol Basics +@subsection Protocol Basics +@cindex protocol basics, file-i/o + +The File-I/O protocol uses the @code{F} packet as the request as well +as reply packet. Since a File-I/O system call can only occur when +@value{GDBN} is waiting for a response from the continuing or stepping target, +the File-I/O request is a reply that @value{GDBN} has to expect as a result +of a previous @samp{C}, @samp{c}, @samp{S} or @samp{s} packet. +This @code{F} packet contains all information needed to allow @value{GDBN} +to call the appropriate host system call: + +@itemize @bullet +@item +A unique identifier for the requested system call. + +@item +All parameters to the system call. Pointers are given as addresses +in the target memory address space. Pointers to strings are given as +pointer/length pair. Numerical values are given as they are. +Numerical control flags are given in a protocol-specific representation. + +@end itemize + +At this point, @value{GDBN} has to perform the following actions. + +@itemize @bullet +@item +If the parameters include pointer values to data needed as input to a +system call, @value{GDBN} requests this data from the target with a +standard @code{m} packet request. This additional communication has to be +expected by the target implementation and is handled as any other @code{m} +packet. + +@item +@value{GDBN} translates all value from protocol representation to host +representation as needed. Datatypes are coerced into the host types. + +@item +@value{GDBN} calls the system call. + +@item +It then coerces datatypes back to protocol representation. + +@item +If the system call is expected to return data in buffer space specified +by pointer parameters to the call, the data is transmitted to the +target using a @code{M} or @code{X} packet. This packet has to be expected +by the target implementation and is handled as any other @code{M} or @code{X} +packet. + +@end itemize + +Eventually @value{GDBN} replies with another @code{F} packet which contains all +necessary information for the target to continue. This at least contains + +@itemize @bullet +@item +Return value. + +@item +@code{errno}, if has been changed by the system call. + +@item +``Ctrl-C'' flag. + +@end itemize + +After having done the needed type and value coercion, the target continues +the latest continue or step action. + +@node The F Request Packet +@subsection The @code{F} Request Packet +@cindex file-i/o request packet +@cindex @code{F} request packet + +The @code{F} request packet has the following format: + +@table @samp +@item F@var{call-id},@var{parameter@dots{}} + +@var{call-id} is the identifier to indicate the host system call to be called. +This is just the name of the function. + +@var{parameter@dots{}} are the parameters to the system call. +Parameters are hexadecimal integer values, either the actual values in case +of scalar datatypes, pointers to target buffer space in case of compound +datatypes and unspecified memory areas, or pointer/length pairs in case +of string parameters. These are appended to the @var{call-id} as a +comma-delimited list. All values are transmitted in ASCII +string representation, pointer/length pairs separated by a slash. + +@end table + + + +@node The F Reply Packet +@subsection The @code{F} Reply Packet +@cindex file-i/o reply packet +@cindex @code{F} reply packet + +The @code{F} reply packet has the following format: + +@table @samp + +@item F@var{retcode},@var{errno},@var{Ctrl-C flag};@var{call-specific attachment} + +@var{retcode} is the return code of the system call as hexadecimal value. + +@var{errno} is the @code{errno} set by the call, in protocol-specific +representation. +This parameter can be omitted if the call was successful. + +@var{Ctrl-C flag} is only sent if the user requested a break. In this +case, @var{errno} must be sent as well, even if the call was successful. +The @var{Ctrl-C flag} itself consists of the character @samp{C}: + +@smallexample +F0,0,C +@end smallexample + +@noindent +or, if the call was interrupted before the host call has been performed: + +@smallexample +F-1,4,C +@end smallexample + +@noindent +assuming 4 is the protocol-specific representation of @code{EINTR}. + +@end table + + +@node The Ctrl-C Message +@subsection The @samp{Ctrl-C} Message +@cindex ctrl-c message, in file-i/o protocol + +If the @samp{Ctrl-C} flag is set in the @value{GDBN} +reply packet (@pxref{The F Reply Packet}), +the target should behave as if it had +gotten a break message. The meaning for the target is ``system call +interrupted by @code{SIGINT}''. Consequently, the target should actually stop +(as with a break message) and return to @value{GDBN} with a @code{T02} +packet. + +It's important for the target to know in which +state the system call was interrupted. There are two possible cases: + +@itemize @bullet +@item +The system call hasn't been performed on the host yet. + +@item +The system call on the host has been finished. + +@end itemize + +These two states can be distinguished by the target by the value of the +returned @code{errno}. If it's the protocol representation of @code{EINTR}, the system +call hasn't been performed. This is equivalent to the @code{EINTR} handling +on POSIX systems. In any other case, the target may presume that the +system call has been finished --- successfully or not --- and should behave +as if the break message arrived right after the system call. + +@value{GDBN} must behave reliably. If the system call has not been called +yet, @value{GDBN} may send the @code{F} reply immediately, setting @code{EINTR} as +@code{errno} in the packet. If the system call on the host has been finished +before the user requests a break, the full action must be finished by +@value{GDBN}. This requires sending @code{M} or @code{X} packets as necessary. +The @code{F} packet may only be sent when either nothing has happened +or the full action has been completed. + +@node Console I/O +@subsection Console I/O +@cindex console i/o as part of file-i/o + +By default and if not explicitly closed by the target system, the file +descriptors 0, 1 and 2 are connected to the @value{GDBN} console. Output +on the @value{GDBN} console is handled as any other file output operation +(@code{write(1, @dots{})} or @code{write(2, @dots{})}). Console input is handled +by @value{GDBN} so that after the target read request from file descriptor +0 all following typing is buffered until either one of the following +conditions is met: + +@itemize @bullet +@item +The user types @kbd{Ctrl-c}. The behavior is as explained above, and the +@code{read} +system call is treated as finished. + +@item +The user presses @key{RET}. This is treated as end of input with a trailing +newline. + +@item +The user types @kbd{Ctrl-d}. This is treated as end of input. No trailing +character (neither newline nor @samp{Ctrl-D}) is appended to the input. + +@end itemize + +If the user has typed more characters than fit in the buffer given to +the @code{read} call, the trailing characters are buffered in @value{GDBN} until +either another @code{read(0, @dots{})} is requested by the target, or debugging +is stopped at the user's request. + + +@node List of Supported Calls +@subsection List of Supported Calls +@cindex list of supported file-i/o calls + +@menu +* open:: +* close:: +* read:: +* write:: +* lseek:: +* rename:: +* unlink:: +* stat/fstat:: +* gettimeofday:: +* isatty:: +* system:: +@end menu + +@node open +@unnumberedsubsubsec open +@cindex open, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int open(const char *pathname, int flags); +int open(const char *pathname, int flags, mode_t mode); +@end smallexample + +@item Request: +@samp{Fopen,@var{pathptr}/@var{len},@var{flags},@var{mode}} + +@noindent +@var{flags} is the bitwise @code{OR} of the following values: + +@table @code +@item O_CREAT +If the file does not exist it will be created. The host +rules apply as far as file ownership and time stamps +are concerned. + +@item O_EXCL +When used with @code{O_CREAT}, if the file already exists it is +an error and open() fails. + +@item O_TRUNC +If the file already exists and the open mode allows +writing (@code{O_RDWR} or @code{O_WRONLY} is given) it will be +truncated to zero length. + +@item O_APPEND +The file is opened in append mode. + +@item O_RDONLY +The file is opened for reading only. + +@item O_WRONLY +The file is opened for writing only. + +@item O_RDWR +The file is opened for reading and writing. +@end table + +@noindent +Other bits are silently ignored. + + +@noindent +@var{mode} is the bitwise @code{OR} of the following values: + +@table @code +@item S_IRUSR +User has read permission. + +@item S_IWUSR +User has write permission. + +@item S_IRGRP +Group has read permission. + +@item S_IWGRP +Group has write permission. + +@item S_IROTH +Others have read permission. + +@item S_IWOTH +Others have write permission. +@end table + +@noindent +Other bits are silently ignored. + + +@item Return value: +@code{open} returns the new file descriptor or -1 if an error +occurred. + +@item Errors: + +@table @code +@item EEXIST +@var{pathname} already exists and @code{O_CREAT} and @code{O_EXCL} were used. + +@item EISDIR +@var{pathname} refers to a directory. + +@item EACCES +The requested access is not allowed. + +@item ENAMETOOLONG +@var{pathname} was too long. + +@item ENOENT +A directory component in @var{pathname} does not exist. + +@item ENODEV +@var{pathname} refers to a device, pipe, named pipe or socket. + +@item EROFS +@var{pathname} refers to a file on a read-only filesystem and +write access was requested. + +@item EFAULT +@var{pathname} is an invalid pointer value. + +@item ENOSPC +No space on device to create the file. + +@item EMFILE +The process already has the maximum number of files open. + +@item ENFILE +The limit on the total number of files open on the system +has been reached. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node close +@unnumberedsubsubsec close +@cindex close, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int close(int fd); +@end smallexample + +@item Request: +@samp{Fclose,@var{fd}} + +@item Return value: +@code{close} returns zero on success, or -1 if an error occurred. + +@item Errors: + +@table @code +@item EBADF +@var{fd} isn't a valid open file descriptor. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node read +@unnumberedsubsubsec read +@cindex read, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int read(int fd, void *buf, unsigned int count); +@end smallexample + +@item Request: +@samp{Fread,@var{fd},@var{bufptr},@var{count}} + +@item Return value: +On success, the number of bytes read is returned. +Zero indicates end of file. If count is zero, read +returns zero as well. On error, -1 is returned. + +@item Errors: + +@table @code +@item EBADF +@var{fd} is not a valid file descriptor or is not open for +reading. + +@item EFAULT +@var{bufptr} is an invalid pointer value. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node write +@unnumberedsubsubsec write +@cindex write, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int write(int fd, const void *buf, unsigned int count); +@end smallexample + +@item Request: +@samp{Fwrite,@var{fd},@var{bufptr},@var{count}} + +@item Return value: +On success, the number of bytes written are returned. +Zero indicates nothing was written. On error, -1 +is returned. + +@item Errors: + +@table @code +@item EBADF +@var{fd} is not a valid file descriptor or is not open for +writing. + +@item EFAULT +@var{bufptr} is an invalid pointer value. + +@item EFBIG +An attempt was made to write a file that exceeds the +host-specific maximum file size allowed. + +@item ENOSPC +No space on device to write the data. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node lseek +@unnumberedsubsubsec lseek +@cindex lseek, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +long lseek (int fd, long offset, int flag); +@end smallexample + +@item Request: +@samp{Flseek,@var{fd},@var{offset},@var{flag}} + +@var{flag} is one of: + +@table @code +@item SEEK_SET +The offset is set to @var{offset} bytes. + +@item SEEK_CUR +The offset is set to its current location plus @var{offset} +bytes. + +@item SEEK_END +The offset is set to the size of the file plus @var{offset} +bytes. +@end table + +@item Return value: +On success, the resulting unsigned offset in bytes from +the beginning of the file is returned. Otherwise, a +value of -1 is returned. + +@item Errors: + +@table @code +@item EBADF +@var{fd} is not a valid open file descriptor. + +@item ESPIPE +@var{fd} is associated with the @value{GDBN} console. + +@item EINVAL +@var{flag} is not a proper value. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node rename +@unnumberedsubsubsec rename +@cindex rename, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int rename(const char *oldpath, const char *newpath); +@end smallexample + +@item Request: +@samp{Frename,@var{oldpathptr}/@var{len},@var{newpathptr}/@var{len}} + +@item Return value: +On success, zero is returned. On error, -1 is returned. + +@item Errors: + +@table @code +@item EISDIR +@var{newpath} is an existing directory, but @var{oldpath} is not a +directory. + +@item EEXIST +@var{newpath} is a non-empty directory. + +@item EBUSY +@var{oldpath} or @var{newpath} is a directory that is in use by some +process. + +@item EINVAL +An attempt was made to make a directory a subdirectory +of itself. + +@item ENOTDIR +A component used as a directory in @var{oldpath} or new +path is not a directory. Or @var{oldpath} is a directory +and @var{newpath} exists but is not a directory. + +@item EFAULT +@var{oldpathptr} or @var{newpathptr} are invalid pointer values. + +@item EACCES +No access to the file or the path of the file. + +@item ENAMETOOLONG + +@var{oldpath} or @var{newpath} was too long. + +@item ENOENT +A directory component in @var{oldpath} or @var{newpath} does not exist. + +@item EROFS +The file is on a read-only filesystem. + +@item ENOSPC +The device containing the file has no room for the new +directory entry. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node unlink +@unnumberedsubsubsec unlink +@cindex unlink, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int unlink(const char *pathname); +@end smallexample + +@item Request: +@samp{Funlink,@var{pathnameptr}/@var{len}} + +@item Return value: +On success, zero is returned. On error, -1 is returned. + +@item Errors: + +@table @code +@item EACCES +No access to the file or the path of the file. + +@item EPERM +The system does not allow unlinking of directories. + +@item EBUSY +The file @var{pathname} cannot be unlinked because it's +being used by another process. + +@item EFAULT +@var{pathnameptr} is an invalid pointer value. + +@item ENAMETOOLONG +@var{pathname} was too long. + +@item ENOENT +A directory component in @var{pathname} does not exist. + +@item ENOTDIR +A component of the path is not a directory. + +@item EROFS +The file is on a read-only filesystem. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node stat/fstat +@unnumberedsubsubsec stat/fstat +@cindex fstat, file-i/o system call +@cindex stat, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int stat(const char *pathname, struct stat *buf); +int fstat(int fd, struct stat *buf); +@end smallexample + +@item Request: +@samp{Fstat,@var{pathnameptr}/@var{len},@var{bufptr}}@* +@samp{Ffstat,@var{fd},@var{bufptr}} + +@item Return value: +On success, zero is returned. On error, -1 is returned. + +@item Errors: + +@table @code +@item EBADF +@var{fd} is not a valid open file. + +@item ENOENT +A directory component in @var{pathname} does not exist or the +path is an empty string. + +@item ENOTDIR +A component of the path is not a directory. + +@item EFAULT +@var{pathnameptr} is an invalid pointer value. + +@item EACCES +No access to the file or the path of the file. + +@item ENAMETOOLONG +@var{pathname} was too long. + +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@node gettimeofday +@unnumberedsubsubsec gettimeofday +@cindex gettimeofday, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int gettimeofday(struct timeval *tv, void *tz); +@end smallexample + +@item Request: +@samp{Fgettimeofday,@var{tvptr},@var{tzptr}} + +@item Return value: +On success, 0 is returned, -1 otherwise. + +@item Errors: + +@table @code +@item EINVAL +@var{tz} is a non-NULL pointer. + +@item EFAULT +@var{tvptr} and/or @var{tzptr} is an invalid pointer value. +@end table + +@end table + +@node isatty +@unnumberedsubsubsec isatty +@cindex isatty, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int isatty(int fd); +@end smallexample + +@item Request: +@samp{Fisatty,@var{fd}} + +@item Return value: +Returns 1 if @var{fd} refers to the @value{GDBN} console, 0 otherwise. + +@item Errors: + +@table @code +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +Note that the @code{isatty} call is treated as a special case: it returns +1 to the target if the file descriptor is attached +to the @value{GDBN} console, 0 otherwise. Implementing through system calls +would require implementing @code{ioctl} and would be more complex than +needed. + + +@node system +@unnumberedsubsubsec system +@cindex system, file-i/o system call + +@table @asis +@item Synopsis: +@smallexample +int system(const char *command); +@end smallexample + +@item Request: +@samp{Fsystem,@var{commandptr}/@var{len}} + +@item Return value: +If @var{len} is zero, the return value indicates whether a shell is +available. A zero return value indicates a shell is not available. +For non-zero @var{len}, the value returned is -1 on error and the +return status of the command otherwise. Only the exit status of the +command is returned, which is extracted from the host's @code{system} +return value by calling @code{WEXITSTATUS(retval)}. In case +@file{/bin/sh} could not be executed, 127 is returned. + +@item Errors: + +@table @code +@item EINTR +The call was interrupted by the user. +@end table + +@end table + +@value{GDBN} takes over the full task of calling the necessary host calls +to perform the @code{system} call. The return value of @code{system} on +the host is simplified before it's returned +to the target. Any termination signal information from the child process +is discarded, and the return value consists +entirely of the exit status of the called command. + +Due to security concerns, the @code{system} call is by default refused +by @value{GDBN}. The user has to allow this call explicitly with the +@code{set remote system-call-allowed 1} command. + +@table @code +@item set remote system-call-allowed +@kindex set remote system-call-allowed +Control whether to allow the @code{system} calls in the File I/O +protocol for the remote target. The default is zero (disabled). + +@item show remote system-call-allowed +@kindex show remote system-call-allowed +Show whether the @code{system} calls are allowed in the File I/O +protocol. +@end table + +@node Protocol-specific Representation of Datatypes +@subsection Protocol-specific Representation of Datatypes +@cindex protocol-specific representation of datatypes, in file-i/o protocol + +@menu +* Integral Datatypes:: +* Pointer Values:: +* Memory Transfer:: +* struct stat:: +* struct timeval:: +@end menu + +@node Integral Datatypes +@unnumberedsubsubsec Integral Datatypes +@cindex integral datatypes, in file-i/o protocol + +The integral datatypes used in the system calls are @code{int}, +@code{unsigned int}, @code{long}, @code{unsigned long}, +@code{mode_t}, and @code{time_t}. + +@code{int}, @code{unsigned int}, @code{mode_t} and @code{time_t} are +implemented as 32 bit values in this protocol. + +@code{long} and @code{unsigned long} are implemented as 64 bit types. + +@xref{Limits}, for corresponding MIN and MAX values (similar to those +in @file{limits.h}) to allow range checking on host and target. + +@code{time_t} datatypes are defined as seconds since the Epoch. + +All integral datatypes transferred as part of a memory read or write of a +structured datatype e.g.@: a @code{struct stat} have to be given in big endian +byte order. + +@node Pointer Values +@unnumberedsubsubsec Pointer Values +@cindex pointer values, in file-i/o protocol + +Pointers to target data are transmitted as they are. An exception +is made for pointers to buffers for which the length isn't +transmitted as part of the function call, namely strings. Strings +are transmitted as a pointer/length pair, both as hex values, e.g.@: + +@smallexample +@code{1aaf/12} +@end smallexample + +@noindent +which is a pointer to data of length 18 bytes at position 0x1aaf. +The length is defined as the full string length in bytes, including +the trailing null byte. For example, the string @code{"hello world"} +at address 0x123456 is transmitted as + +@smallexample +@code{123456/d} +@end smallexample + +@node Memory Transfer +@unnumberedsubsubsec Memory Transfer +@cindex memory transfer, in file-i/o protocol + +Structured data which is transferred using a memory read or write (for +example, a @code{struct stat}) is expected to be in a protocol-specific format +with all scalar multibyte datatypes being big endian. Translation to +this representation needs to be done both by the target before the @code{F} +packet is sent, and by @value{GDBN} before +it transfers memory to the target. Transferred pointers to structured +data should point to the already-coerced data at any time. + + +@node struct stat +@unnumberedsubsubsec struct stat +@cindex struct stat, in file-i/o protocol + +The buffer of type @code{struct stat} used by the target and @value{GDBN} +is defined as follows: + +@smallexample +struct stat @{ + unsigned int st_dev; /* device */ + unsigned int st_ino; /* inode */ + mode_t st_mode; /* protection */ + unsigned int st_nlink; /* number of hard links */ + unsigned int st_uid; /* user ID of owner */ + unsigned int st_gid; /* group ID of owner */ + unsigned int st_rdev; /* device type (if inode device) */ + unsigned long st_size; /* total size, in bytes */ + unsigned long st_blksize; /* blocksize for filesystem I/O */ + unsigned long st_blocks; /* number of blocks allocated */ + time_t st_atime; /* time of last access */ + time_t st_mtime; /* time of last modification */ + time_t st_ctime; /* time of last change */ +@}; +@end smallexample + +The integral datatypes conform to the definitions given in the +appropriate section (see @ref{Integral Datatypes}, for details) so this +structure is of size 64 bytes. + +The values of several fields have a restricted meaning and/or +range of values. + +@table @code + +@item st_dev +A value of 0 represents a file, 1 the console. + +@item st_ino +No valid meaning for the target. Transmitted unchanged. + +@item st_mode +Valid mode bits are described in @ref{Constants}. Any other +bits have currently no meaning for the target. + +@item st_uid +@itemx st_gid +@itemx st_rdev +No valid meaning for the target. Transmitted unchanged. + +@item st_atime +@itemx st_mtime +@itemx st_ctime +These values have a host and file system dependent +accuracy. Especially on Windows hosts, the file system may not +support exact timing values. +@end table + +The target gets a @code{struct stat} of the above representation and is +responsible for coercing it to the target representation before +continuing. + +Note that due to size differences between the host, target, and protocol +representations of @code{struct stat} members, these members could eventually +get truncated on the target. + +@node struct timeval +@unnumberedsubsubsec struct timeval +@cindex struct timeval, in file-i/o protocol + +The buffer of type @code{struct timeval} used by the File-I/O protocol +is defined as follows: + +@smallexample +struct timeval @{ + time_t tv_sec; /* second */ + long tv_usec; /* microsecond */ +@}; +@end smallexample + +The integral datatypes conform to the definitions given in the +appropriate section (see @ref{Integral Datatypes}, for details) so this +structure is of size 8 bytes. + +@node Constants +@subsection Constants +@cindex constants, in file-i/o protocol + +The following values are used for the constants inside of the +protocol. @value{GDBN} and target are responsible for translating these +values before and after the call as needed. + +@menu +* Open Flags:: +* mode_t Values:: +* Errno Values:: +* Lseek Flags:: +* Limits:: +@end menu + +@node Open Flags +@unnumberedsubsubsec Open Flags +@cindex open flags, in file-i/o protocol + +All values are given in hexadecimal representation. + +@smallexample + O_RDONLY 0x0 + O_WRONLY 0x1 + O_RDWR 0x2 + O_APPEND 0x8 + O_CREAT 0x200 + O_TRUNC 0x400 + O_EXCL 0x800 +@end smallexample + +@node mode_t Values +@unnumberedsubsubsec mode_t Values +@cindex mode_t values, in file-i/o protocol + +All values are given in octal representation. + +@smallexample + S_IFREG 0100000 + S_IFDIR 040000 + S_IRUSR 0400 + S_IWUSR 0200 + S_IXUSR 0100 + S_IRGRP 040 + S_IWGRP 020 + S_IXGRP 010 + S_IROTH 04 + S_IWOTH 02 + S_IXOTH 01 +@end smallexample + +@node Errno Values +@unnumberedsubsubsec Errno Values +@cindex errno values, in file-i/o protocol + +All values are given in decimal representation. + +@smallexample + EPERM 1 + ENOENT 2 + EINTR 4 + EBADF 9 + EACCES 13 + EFAULT 14 + EBUSY 16 + EEXIST 17 + ENODEV 19 + ENOTDIR 20 + EISDIR 21 + EINVAL 22 + ENFILE 23 + EMFILE 24 + EFBIG 27 + ENOSPC 28 + ESPIPE 29 + EROFS 30 + ENAMETOOLONG 91 + EUNKNOWN 9999 +@end smallexample + + @code{EUNKNOWN} is used as a fallback error value if a host system returns + any error value not in the list of supported error numbers. + +@node Lseek Flags +@unnumberedsubsubsec Lseek Flags +@cindex lseek flags, in file-i/o protocol + +@smallexample + SEEK_SET 0 + SEEK_CUR 1 + SEEK_END 2 +@end smallexample + +@node Limits +@unnumberedsubsubsec Limits +@cindex limits, in file-i/o protocol + +All values are given in decimal representation. + +@smallexample + INT_MIN -2147483648 + INT_MAX 2147483647 + UINT_MAX 4294967295 + LONG_MIN -9223372036854775808 + LONG_MAX 9223372036854775807 + ULONG_MAX 18446744073709551615 +@end smallexample + +@node File-I/O Examples +@subsection File-I/O Examples +@cindex file-i/o examples + +Example sequence of a write call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be written: + +@smallexample +<- @code{Fwrite,3,1234,6} +@emph{request memory read from target} +-> @code{m1234,6} +<- XXXXXX +@emph{return "6 bytes written"} +-> @code{F6} +@end smallexample + +Example sequence of a read call, file descriptor 3, buffer is at target +address 0x1234, 6 bytes should be read: + +@smallexample +<- @code{Fread,3,1234,6} +@emph{request memory write to target} +-> @code{X1234,6:XXXXXX} +@emph{return "6 bytes read"} +-> @code{F6} +@end smallexample + +Example sequence of a read call, call fails on the host due to invalid +file descriptor (@code{EBADF}): + +@smallexample +<- @code{Fread,3,1234,6} +-> @code{F-1,9} +@end smallexample + +Example sequence of a read call, user presses @kbd{Ctrl-c} before syscall on +host is called: + +@smallexample +<- @code{Fread,3,1234,6} +-> @code{F-1,4,C} +<- @code{T02} +@end smallexample + +Example sequence of a read call, user presses @kbd{Ctrl-c} after syscall on +host is called: + +@smallexample +<- @code{Fread,3,1234,6} +-> @code{X1234,6:XXXXXX} +<- @code{T02} +@end smallexample + +@node Library List Format +@section Library List Format +@cindex library list format, remote protocol + +On some platforms, a dynamic loader (e.g.@: @file{ld.so}) runs in the +same process as your application to manage libraries. In this case, +@value{GDBN} can use the loader's symbol table and normal memory +operations to maintain a list of shared libraries. On other +platforms, the operating system manages loaded libraries. +@value{GDBN} can not retrieve the list of currently loaded libraries +through memory operations, so it uses the @samp{qXfer:libraries:read} +packet (@pxref{qXfer library list read}) instead. The remote stub +queries the target's operating system and reports which libraries +are loaded. + +The @samp{qXfer:libraries:read} packet returns an XML document which +lists loaded libraries and their offsets. Each library has an +associated name and one or more segment or section base addresses, +which report where the library was loaded in memory. + +For the common case of libraries that are fully linked binaries, the +library should have a list of segments. If the target supports +dynamic linking of a relocatable object file, its library XML element +should instead include a list of allocated sections. The segment or +section bases are start addresses, not relocation offsets; they do not +depend on the library's link-time base addresses. + +@value{GDBN} must be linked with the Expat library to support XML +library lists. @xref{Expat}. + +A simple memory map, with one loaded library relocated by a single +offset, looks like this: + +@smallexample + + + + + +@end smallexample + +Another simple memory map, with one loaded library with three +allocated sections (.text, .data, .bss), looks like this: + +@smallexample + + +
+
+
+ + +@end smallexample + +The format of a library list is described by this DTD: + +@smallexample + + + + + + + + + +@end smallexample + +In addition, segments and section descriptors cannot be mixed within a +single library element, and you must supply at least one segment or +section for each library. + +@node Library List Format for SVR4 Targets +@section Library List Format for SVR4 Targets +@cindex library list format, remote protocol + +On SVR4 platforms @value{GDBN} can use the symbol table of a dynamic loader +(e.g.@: @file{ld.so}) and normal memory operations to maintain a list of +shared libraries. Still a special library list provided by this packet is +more efficient for the @value{GDBN} remote protocol. + +The @samp{qXfer:libraries-svr4:read} packet returns an XML document which lists +loaded libraries and their SVR4 linker parameters. For each library on SVR4 +target, the following parameters are reported: + +@itemize @minus +@item +@code{name}, the absolute file name from the @code{l_name} field of +@code{struct link_map}. +@item +@code{lm} with address of @code{struct link_map} used for TLS +(Thread Local Storage) access. +@item +@code{l_addr}, the displacement as read from the field @code{l_addr} of +@code{struct link_map}. For prelinked libraries this is not an absolute +memory address. It is a displacement of absolute memory address against +address the file was prelinked to during the library load. +@item +@code{l_ld}, which is memory address of the @code{PT_DYNAMIC} segment +@item +@code{lmid}, which is an identifier for a linker namespace, such as +the memory address of the @code{r_debug} object that contains this +namespace's load map or the namespace identifier returned by +@code{dlinfo (3)}. +@end itemize + +Additionally the single @code{main-lm} attribute specifies address of +@code{struct link_map} used for the main executable. This parameter is used +for TLS access and its presence is optional. + +@value{GDBN} must be linked with the Expat library to support XML +SVR4 library lists. @xref{Expat}. + +A simple memory map, with two loaded libraries (which do not use prelink), +looks like this: + +@smallexample + + + + +@end smallexample + +The format of an SVR4 library list is described by this DTD: + +@smallexample + + + + + + + + + + +@end smallexample + +@node Memory Map Format +@section Memory Map Format +@cindex memory map format + +To be able to write into flash memory, @value{GDBN} needs to obtain a +memory map from the target. This section describes the format of the +memory map. + +The memory map is obtained using the @samp{qXfer:memory-map:read} +(@pxref{qXfer memory map read}) packet and is an XML document that +lists memory regions. + +@value{GDBN} must be linked with the Expat library to support XML +memory maps. @xref{Expat}. + +The top-level structure of the document is shown below: + +@smallexample + + + + region... + +@end smallexample + +Each region can be either: + +@itemize + +@item +A region of RAM starting at @var{addr} and extending for @var{length} +bytes from there: + +@smallexample + +@end smallexample + + +@item +A region of read-only memory: + +@smallexample + +@end smallexample + + +@item +A region of flash memory, with erasure blocks @var{blocksize} +bytes in length: + +@smallexample + + @var{blocksize} + +@end smallexample + +@end itemize + +Regions must not overlap. @value{GDBN} assumes that areas of memory not covered +by the memory map are RAM, and uses the ordinary @samp{M} and @samp{X} +packets to write to addresses in such ranges. + +The formal DTD for memory map format is given below: + +@smallexample + + + + + + + + + + + + + + +@end smallexample + +@node Thread List Format +@section Thread List Format +@cindex thread list format + +To efficiently update the list of threads and their attributes, +@value{GDBN} issues the @samp{qXfer:threads:read} packet +(@pxref{qXfer threads read}) and obtains the XML document with +the following structure: + +@smallexample + + + + ... description ... + + +@end smallexample + +Each @samp{thread} element must have the @samp{id} attribute that +identifies the thread (@pxref{thread-id syntax}). The +@samp{core} attribute, if present, specifies which processor core +the thread was last executing on. The @samp{name} attribute, if +present, specifies the human-readable name of the thread. The content +of the of @samp{thread} element is interpreted as human-readable +auxiliary information. The @samp{handle} attribute, if present, +is a hex encoded representation of the thread handle. + + +@node Traceframe Info Format +@section Traceframe Info Format +@cindex traceframe info format + +To be able to know which objects in the inferior can be examined when +inspecting a tracepoint hit, @value{GDBN} needs to obtain the list of +memory ranges, registers and trace state variables that have been +collected in a traceframe. + +This list is obtained using the @samp{qXfer:traceframe-info:read} +(@pxref{qXfer traceframe info read}) packet and is an XML document. + +@value{GDBN} must be linked with the Expat library to support XML +traceframe info discovery. @xref{Expat}. + +The top-level structure of the document is shown below: + +@smallexample + + + + block... + +@end smallexample + +Each traceframe block can be either: + +@itemize + +@item +A region of collected memory starting at @var{addr} and extending for +@var{length} bytes from there: + +@smallexample + +@end smallexample + +@item +A block indicating trace state variable numbered @var{number} has been +collected: + +@smallexample + +@end smallexample + +@end itemize + +The formal DTD for the traceframe info format is given below: + +@smallexample + + + + + + + +@end smallexample + +@node Branch Trace Format +@section Branch Trace Format +@cindex branch trace format + +In order to display the branch trace of an inferior thread, +@value{GDBN} needs to obtain the list of branches. This list is +represented as list of sequential code blocks that are connected via +branches. The code in each block has been executed sequentially. + +This list is obtained using the @samp{qXfer:btrace:read} +(@pxref{qXfer btrace read}) packet and is an XML document. + +@value{GDBN} must be linked with the Expat library to support XML +traceframe info discovery. @xref{Expat}. + +The top-level structure of the document is shown below: + +@smallexample + + + + block... + +@end smallexample + +@itemize + +@item +A block of sequentially executed instructions starting at @var{begin} +and ending at @var{end}: + +@smallexample + +@end smallexample + +@end itemize + +The formal DTD for the branch trace format is given below: + +@smallexample + + + + + + + + + + + + + + +@end smallexample + +@node Branch Trace Configuration Format +@section Branch Trace Configuration Format +@cindex branch trace configuration format + +For each inferior thread, @value{GDBN} can obtain the branch trace +configuration using the @samp{qXfer:btrace-conf:read} +(@pxref{qXfer btrace-conf read}) packet. + +The configuration describes the branch trace format and configuration +settings for that format. The following information is described: + +@table @code +@item bts +This thread uses the @dfn{Branch Trace Store} (@acronym{BTS}) format. +@table @code +@item size +The size of the @acronym{BTS} ring buffer in bytes. +@end table +@item pt +This thread uses the @dfn{Intel Processor Trace} (@acronym{Intel +PT}) format. +@table @code +@item size +The size of the @acronym{Intel PT} ring buffer in bytes. +@end table +@end table + +@value{GDBN} must be linked with the Expat library to support XML +branch trace configuration discovery. @xref{Expat}. + +The formal DTD for the branch trace configuration format is given below: + +@smallexample + + + + + + + + + + +@end smallexample + +@include agentexpr.texi + +@node Target Descriptions +@appendix Target Descriptions +@cindex target descriptions + +One of the challenges of using @value{GDBN} to debug embedded systems +is that there are so many minor variants of each processor +architecture in use. It is common practice for vendors to start with +a standard processor core --- ARM, PowerPC, or @acronym{MIPS}, for example --- +and then make changes to adapt it to a particular market niche. Some +architectures have hundreds of variants, available from dozens of +vendors. This leads to a number of problems: + +@itemize @bullet +@item +With so many different customized processors, it is difficult for +the @value{GDBN} maintainers to keep up with the changes. +@item +Since individual variants may have short lifetimes or limited +audiences, it may not be worthwhile to carry information about every +variant in the @value{GDBN} source tree. +@item +When @value{GDBN} does support the architecture of the embedded system +at hand, the task of finding the correct architecture name to give the +@command{set architecture} command can be error-prone. +@end itemize + +To address these problems, the @value{GDBN} remote protocol allows a +target system to not only identify itself to @value{GDBN}, but to +actually describe its own features. This lets @value{GDBN} support +processor variants it has never seen before --- to the extent that the +descriptions are accurate, and that @value{GDBN} understands them. + +@value{GDBN} must be linked with the Expat library to support XML +target descriptions. @xref{Expat}. + +@menu +* Retrieving Descriptions:: How descriptions are fetched from a target. +* Target Description Format:: The contents of a target description. +* Predefined Target Types:: Standard types available for target + descriptions. +* Enum Target Types:: How to define enum target types. +* Standard Target Features:: Features @value{GDBN} knows about. +@end menu + +@node Retrieving Descriptions +@section Retrieving Descriptions + +Target descriptions can be read from the target automatically, or +specified by the user manually. The default behavior is to read the +description from the target. @value{GDBN} retrieves it via the remote +protocol using @samp{qXfer} requests (@pxref{General Query Packets, +qXfer}). The @var{annex} in the @samp{qXfer} packet will be +@samp{target.xml}. The contents of the @samp{target.xml} annex are an +XML document, of the form described in @ref{Target Description +Format}. + +Alternatively, you can specify a file to read for the target description. +If a file is set, the target will not be queried. The commands to +specify a file are: + +@table @code +@cindex set tdesc filename +@item set tdesc filename @var{path} +Read the target description from @var{path}. + +@cindex unset tdesc filename +@item unset tdesc filename +Do not read the XML target description from a file. @value{GDBN} +will use the description supplied by the current target. + +@cindex show tdesc filename +@item show tdesc filename +Show the filename to read for a target description, if any. +@end table + + +@node Target Description Format +@section Target Description Format +@cindex target descriptions, XML format + +A target description annex is an @uref{http://www.w3.org/XML/, XML} +document which complies with the Document Type Definition provided in +the @value{GDBN} sources in @file{gdb/features/gdb-target.dtd}. This +means you can use generally available tools like @command{xmllint} to +check that your feature descriptions are well-formed and valid. +However, to help people unfamiliar with XML write descriptions for +their targets, we also describe the grammar here. + +Target descriptions can identify the architecture of the remote target +and (for some architectures) provide information about custom register +sets. They can also identify the OS ABI of the remote target. +@value{GDBN} can use this information to autoconfigure for your +target, or to warn you if you connect to an unsupported target. + +Here is a simple target description: + +@smallexample + + i386:x86-64 + +@end smallexample + +@noindent +This minimal description only says that the target uses +the x86-64 architecture. + +A target description has the following overall form, with [ ] marking +optional elements and @dots{} marking repeatable elements. The elements +are explained further below. + +@smallexample + + + + @r{[}@var{architecture}@r{]} + @r{[}@var{osabi}@r{]} + @r{[}@var{compatible}@r{]} + @r{[}@var{feature}@dots{}@r{]} + +@end smallexample + +@noindent +The description is generally insensitive to whitespace and line +breaks, under the usual common-sense rules. The XML version +declaration and document type declaration can generally be omitted +(@value{GDBN} does not require them), but specifying them may be +useful for XML validation tools. The @samp{version} attribute for +@samp{} may also be omitted, but we recommend +including it; if future versions of @value{GDBN} use an incompatible +revision of @file{gdb-target.dtd}, they will detect and report +the version mismatch. + +@subsection Inclusion +@cindex target descriptions, inclusion +@cindex XInclude +@ifnotinfo +@cindex +@end ifnotinfo + +It can sometimes be valuable to split a target description up into +several different annexes, either for organizational purposes, or to +share files between different possible target descriptions. You can +divide a description into multiple files by replacing any element of +the target description with an inclusion directive of the form: + +@smallexample + +@end smallexample + +@noindent +When @value{GDBN} encounters an element of this form, it will retrieve +the named XML @var{document}, and replace the inclusion directive with +the contents of that document. If the current description was read +using @samp{qXfer}, then so will be the included document; +@var{document} will be interpreted as the name of an annex. If the +current description was read from a file, @value{GDBN} will look for +@var{document} as a file in the same directory where it found the +original description. + +@subsection Architecture +@cindex + +An @samp{} element has this form: + +@smallexample + @var{arch} +@end smallexample + +@var{arch} is one of the architectures from the set accepted by +@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). + +@subsection OS ABI +@cindex @code{} + +This optional field was introduced in @value{GDBN} version 7.0. +Previous versions of @value{GDBN} ignore it. + +An @samp{} element has this form: + +@smallexample + @var{abi-name} +@end smallexample + +@var{abi-name} is an OS ABI name from the same selection accepted by +@w{@code{set osabi}} (@pxref{ABI, ,Configuring the Current ABI}). + +@subsection Compatible Architecture +@cindex @code{} + +This optional field was introduced in @value{GDBN} version 7.0. +Previous versions of @value{GDBN} ignore it. + +A @samp{} element has this form: + +@smallexample + @var{arch} +@end smallexample + +@var{arch} is one of the architectures from the set accepted by +@code{set architecture} (@pxref{Targets, ,Specifying a Debugging Target}). + +A @samp{} element is used to specify that the target +is able to run binaries in some other than the main target architecture +given by the @samp{} element. For example, on the +Cell Broadband Engine, the main architecture is @code{powerpc:common} +or @code{powerpc:common64}, but the system is able to run binaries +in the @code{spu} architecture as well. The way to describe this +capability with @samp{} is as follows: + +@smallexample + powerpc:common + spu +@end smallexample + +@subsection Features +@cindex + +Each @samp{} describes some logical portion of the target +system. Features are currently used to describe available CPU +registers and the types of their contents. A @samp{} element +has this form: + +@smallexample + + @r{[}@var{type}@dots{}@r{]} + @var{reg}@dots{} + +@end smallexample + +@noindent +Each feature's name should be unique within the description. The name +of a feature does not matter unless @value{GDBN} has some special +knowledge of the contents of that feature; if it does, the feature +should have its standard name. @xref{Standard Target Features}. + +@subsection Types + +Any register's value is a collection of bits which @value{GDBN} must +interpret. The default interpretation is a two's complement integer, +but other types can be requested by name in the register description. +Some predefined types are provided by @value{GDBN} (@pxref{Predefined +Target Types}), and the description can define additional composite +and enum types. + +Each type element must have an @samp{id} attribute, which gives +a unique (within the containing @samp{}) name to the type. +Types must be defined before they are used. + +@cindex +Some targets offer vector registers, which can be treated as arrays +of scalar elements. These types are written as @samp{} elements, +specifying the array element type, @var{type}, and the number of elements, +@var{count}: + +@smallexample + +@end smallexample + +@cindex +If a register's value is usefully viewed in multiple ways, define it +with a union type containing the useful representations. The +@samp{} element contains one or more @samp{} elements, +each of which has a @var{name} and a @var{type}: + +@smallexample + + + @dots{} + +@end smallexample + +@cindex +@cindex +If a register's value is composed from several separate values, define +it with either a structure type or a flags type. +A flags type may only contain bitfields. +A structure type may either contain only bitfields or contain no bitfields. +If the value contains only bitfields, its total size in bytes must be +specified. + +Non-bitfield values have a @var{name} and @var{type}. + +@smallexample + + + @dots{} + +@end smallexample + +Both @var{name} and @var{type} values are required. +No implicit padding is added. + +Bitfield values have a @var{name}, @var{start}, @var{end} and @var{type}. + +@smallexample + + + @dots{} + +@end smallexample + +@smallexample + + + @dots{} + +@end smallexample + +The @var{name} value is required. +Bitfield values may be named with the empty string, @samp{""}, +in which case the field is ``filler'' and its value is not printed. +Not all bits need to be specified, so ``filler'' fields are optional. + +The @var{start} and @var{end} values are required, and @var{type} +is optional. +The field's @var{start} must be less than or equal to its @var{end}, +and zero represents the least significant bit. + +The default value of @var{type} is @code{bool} for single bit fields, +and an unsigned integer otherwise. + +Which to choose? Structures or flags? + +Registers defined with @samp{flags} have these advantages over +defining them with @samp{struct}: + +@itemize @bullet +@item +Arithmetic may be performed on them as if they were integers. +@item +They are printed in a more readable fashion. +@end itemize + +Registers defined with @samp{struct} have one advantage over +defining them with @samp{flags}: + +@itemize @bullet +@item +One can fetch individual fields like in @samp{C}. + +@smallexample +(@value{GDBP}) print $my_struct_reg.field3 +$1 = 42 +@end smallexample + +@end itemize + +@subsection Registers +@cindex + +Each register is represented as an element with this form: + +@smallexample + +@end smallexample + +@noindent +The components are as follows: + +@table @var + +@item name +The register's name; it must be unique within the target description. + +@item bitsize +The register's size, in bits. + +@item regnum +The register's number. If omitted, a register's number is one greater +than that of the previous register (either in the current feature or in +a preceding feature); the first register in the target description +defaults to zero. This register number is used to read or write +the register; e.g.@: it is used in the remote @code{p} and @code{P} +packets, and registers appear in the @code{g} and @code{G} packets +in order of increasing register number. + +@item save-restore +Whether the register should be preserved across inferior function +calls; this must be either @code{yes} or @code{no}. The default is +@code{yes}, which is appropriate for most registers except for +some system control registers; this is not related to the target's +ABI. + +@item type +The type of the register. It may be a predefined type, a type +defined in the current feature, or one of the special types @code{int} +and @code{float}. @code{int} is an integer type of the correct size +for @var{bitsize}, and @code{float} is a floating point type (in the +architecture's normal floating point format) of the correct size for +@var{bitsize}. The default is @code{int}. + +@item group +The register group to which this register belongs. It can be one of the +standard register groups @code{general}, @code{float}, @code{vector} or an +arbitrary string. Group names should be limited to alphanumeric characters. +If a group name is made up of multiple words the words may be separated by +hyphens; e.g.@: @code{special-group} or @code{ultra-special-group}. If no +@var{group} is specified, @value{GDBN} will not display the register in +@code{info registers}. + +@end table + +@node Predefined Target Types +@section Predefined Target Types +@cindex target descriptions, predefined types + +Type definitions in the self-description can build up composite types +from basic building blocks, but can not define fundamental types. Instead, +standard identifiers are provided by @value{GDBN} for the fundamental +types. The currently supported types are: + +@table @code + +@item bool +Boolean type, occupying a single bit. + +@item int8 +@itemx int16 +@itemx int24 +@itemx int32 +@itemx int64 +@itemx int128 +Signed integer types holding the specified number of bits. + +@item uint8 +@itemx uint16 +@itemx uint24 +@itemx uint32 +@itemx uint64 +@itemx uint128 +Unsigned integer types holding the specified number of bits. + +@item code_ptr +@itemx data_ptr +Pointers to unspecified code and data. The program counter and +any dedicated return address register may be marked as code +pointers; printing a code pointer converts it into a symbolic +address. The stack pointer and any dedicated address registers +may be marked as data pointers. + +@item ieee_half +Half precision IEEE floating point. + +@item ieee_single +Single precision IEEE floating point. + +@item ieee_double +Double precision IEEE floating point. + +@item bfloat16 +The 16-bit @dfn{brain floating point} format used e.g.@: by x86 and ARM. + +@item arm_fpa_ext +The 12-byte extended precision format used by ARM FPA registers. + +@item i387_ext +The 10-byte extended precision format used by x87 registers. + +@item i386_eflags +32bit @sc{eflags} register used by x86. + +@item i386_mxcsr +32bit @sc{mxcsr} register used by x86. + +@end table + +@node Enum Target Types +@section Enum Target Types +@cindex target descriptions, enum types + +Enum target types are useful in @samp{struct} and @samp{flags} +register descriptions. @xref{Target Description Format}. + +Enum types have a name, size and a list of name/value pairs. + +@smallexample + + + @dots{} + +@end smallexample + +Enums must be defined before they are used. + +@smallexample + + + + + + + + + +@end smallexample + +Given that description, a value of 3 for the @samp{flags} register +would be printed as: + +@smallexample +(@value{GDBP}) info register flags +flags 0x3 [ X LEVEL=high ] +@end smallexample + +@node Standard Target Features +@section Standard Target Features +@cindex target descriptions, standard features + +A target description must contain either no registers or all the +target's registers. If the description contains no registers, then +@value{GDBN} will assume a default register layout, selected based on +the architecture. If the description contains any registers, the +default layout will not be used; the standard registers must be +described in the target description, in such a way that @value{GDBN} +can recognize them. + +This is accomplished by giving specific names to feature elements +which contain standard registers. @value{GDBN} will look for features +with those names and verify that they contain the expected registers; +if any known feature is missing required registers, or if any required +feature is missing, @value{GDBN} will reject the target +description. You can add additional registers to any of the +standard features --- @value{GDBN} will display them just as if +they were added to an unrecognized feature. + +This section lists the known features and their expected contents. +Sample XML documents for these features are included in the +@value{GDBN} source tree, in the directory @file{gdb/features}. + +Names recognized by @value{GDBN} should include the name of the +company or organization which selected the name, and the overall +architecture to which the feature applies; so e.g.@: the feature +containing ARM core registers is named @samp{org.gnu.gdb.arm.core}. + +The names of registers are not case sensitive for the purpose +of recognizing standard features, but @value{GDBN} will only display +registers using the capitalization used in the description. + +@menu +* AArch64 Features:: +* ARC Features:: +* ARM Features:: +* i386 Features:: +* LoongArch Features:: +* MicroBlaze Features:: +* MIPS Features:: +* M68K Features:: +* NDS32 Features:: +* OpenRISC 1000 Features:: +* PowerPC Features:: +* RISC-V Features:: +* RX Features:: +* S/390 and System z Features:: +* Sparc Features:: +* TIC6x Features:: +@end menu + + +@node AArch64 Features +@subsection AArch64 Features +@cindex target descriptions, AArch64 features + +@subsubsection AArch64 core registers feature + +The @samp{org.gnu.gdb.aarch64.core} feature is required for AArch64 +targets. It must contain the following: + +@itemize @minus +@item +@samp{x0} through @samp{x30}, the general purpose registers, with size of +64 bits. Register @samp{x30} is also known as the @dfn{link register}, +or @samp{lr}. +@item +@samp{sp}, the stack pointer register or @samp{x31}. It is 64 bits in size and +has a type of @samp{data_ptr}. +@item +@samp{pc}, the program counter register. It is 64 bits in size and has a type +of @samp{code_ptr}. +@item +@samp{cpsr}, the current program status register. It is 32 bits in size +and has a custom flags type. +@end itemize + +The semantics of the individual flags and fields in @samp{cpsr} can change as +new architectural features are added. The current layout can be found in the +aarch64-core.xml file. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 floating-point registers feature + +The @samp{org.gnu.gdb.aarch64.fpu} feature is optional. If present, +it must contain the following registers: + +@itemize @minus +@item +@samp{v0} through @samp{v31}, the vector registers with size of 128 bits. The +type is a custom vector type. +@item +@samp{fpsr}, the floating-point status register. It is 32 bits in size and has +a custom flags type. +@item +@samp{fpcr}, the floating-point control register. It is 32 bits in size and has +a custom flags type. +@end itemize + +The semantics of the individual flags and fields in @samp{fpsr} and @samp{fpcr} +can change as new architectural features are added. + +The types for the vector registers, @samp{fpsr} and @samp{fpcr} registers can +be found in the aarch64-fpu.xml file. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 SVE registers feature + +The @samp{org.gnu.gdb.aarch64.sve} feature is optional. If present, +it means the target supports the Scalable Vector Extension and must contain +the following registers: + +@itemize @minus +@item +@samp{z0} through @samp{z31}, the scalable vector registers. Their sizes are +variable and a multiple of 128 bits up to a maximum of 2048 bit. Their type is +a custom union type that helps visualize different sizes of sub-vectors. +@item +@samp{fpsr}, the floating-point status register. It is 32 bits in size and has +a custom flags type. +@item +@samp{fpcr}, the floating-point control register. It is 32 bits in size and has +a custom flags type. +@item +@samp{p0} through @samp{p15}, the predicate registers. Their sizes are +variable, based on the current vector length, and a multiple of +16 bits. Their types are a custom union to help visualize sub-elements. +@item +@samp{ffr}, the First Fault register. It has a variable size based on the +current vector length and is a multiple of 16 bits. The type is the same as +the predicate registers. +@item +@samp{vg}, the vector granule. It represents the number of 64 bits chunks in +a @samp{z} register. It is closely associated with the current vector +length. It has a type of @samp{int}. +@end itemize + +When @value{GDBN} sees the SVE feature, it will assume the Scalable Vector +Extension is supported, and will adjust the sizes of the @samp{z}, @samp{p} +and @samp{ffr} registers accordingly, based on the value of @samp{vg}. + +@value{GDBN} will also create pseudo-registers equivalent to the @samp{v} +vector registers from the @samp{org.gnu.gdb.aarch64.fpu} feature. + +The first 128 bits of the @samp{z} registers overlap the 128 bits of the +@samp{v} registers, so changing one will trigger a change to the other. + +For the types of the @samp{z}, @samp{p} and @samp{ffr} registers, please +check the aarch64-sve.c file. No XML file is available for this feature +because it is dynamically generated based on the current vector length. + +The semantics of the individual flags and fields in @samp{fpsr} and @samp{fpcr} +can change as new architectural features are added. + +The types for the @samp{fpsr} and @samp{fpcr} registers can be found in the +aarch64-sve.c file, and should match what is described in aarch64-fpu.xml. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 Pointer Authentication registers feature + +The @samp{org.gnu.gdb.aarch64.pauth} optional feature was introduced so +@value{GDBN} could detect support for the Pointer Authentication +extension. If present, it must contain one of two possible register sets. + +Pointer Authentication masks for user-mode: + +@itemize @minus +@item +@samp{pauth_dmask}, the user-mode pointer authentication mask for data +pointers. It is 64 bits in size. +@item +@samp{pauth_cmask}, the user-mode pointer authentication mask for code +pointers. It is 64 bits in size. +@end itemize + +Pointer Authentication masks for user-mode and kernel-mode: + +@itemize @minus +@item +@samp{pauth_dmask}, the user-mode pointer authentication mask for data +pointers. It is 64 bits in size. +@item +@samp{pauth_cmask}, the user-mode pointer authentication mask for code +pointers. It is 64 bits in size. +@item +@samp{pauth_dmask_high}, the kernel-mode pointer authentication mask for +data pointers. It is 64 bits in size. +@item +@samp{pauth_cmask_high}, the kernel-mode pointer authentication mask for +code pointers. It is 64 bits in size. +@end itemize + +If @value{GDBN} sees any of the two sets of registers in this feature, it will +assume the target is capable of signing pointers. If so, @value{GDBN} will +decorate backtraces with a @samp{[PAC]} marker alongside a function that +has a signed link register value that needs to be unmasked/decoded. + +@value{GDBN} will also use the masks to remove non-address bits from pointers. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +Please note the @samp{org.gnu.gdb.aarch64.pauth} feature string is deprecated +and must only be used for backwards compatibility with older releases of +@value{GDBN} and @command{gdbserver}. Targets that support Pointer +Authentication must advertise such capability by using the +@samp{org.gnu.gdb.aarch64.pauth_v2} feature string instead. + +The @samp{org.gnu.gdb.aarch64.pauth_v2} feature has the exact same contents +as feature @samp{org.gnu.gdb.aarch64.pauth}. + +The reason for having feature @samp{org.gnu.gdb.aarch64.pauth_v2} is a bug in +previous versions of @value{GDBN} (versions 9, 10, 11 and 12). This bug +caused @value{GDBN} to crash whenever the target reported support for Pointer +Authentication (using feature string @samp{org.gnu.gdb.aarch64.pauth}) and also +reported additional system registers that were not accounted for by +@value{GDBN}. This is more common when using emulators and on bare-metal +debugging scenarios. + +It can also happen if a newer gdbserver is used with an old @value{GDBN} that +has the bug. In such a case, the newer gdbserver might report Pointer +Authentication support via the @samp{org.gnu.gdb.aarch64.pauth} feature string +and also report additional registers the older @value{GDBN} does not know +about, potentially leading to a crash. + +@subsubsection AArch64 TLS registers feature + +The @samp{org.gnu.gdb.aarch64.tls} optional feature was introduced to expose +the TLS registers to @value{GDBN}. If present, it must contain either one +of the following register sets. + +Only @samp{tpidr}: + +@itemize @minus +@item +@samp{tpidr}, the software thread id register. It is 64 bits in size and has a +type of @samp{data_ptr}. +@end itemize + +Both @samp{tpidr} and @samp{tpidr2}. + +@itemize @minus +@item +@samp{tpidr}, the software thread id register. It is 64 bits in size and has a +type of @samp{data_ptr}. +@item +@samp{tpidr2}, the second software thread id register. It is 64 bits in size +and has a type of @samp{data_ptr}. It may be used in the future alongside +the Scalable Matrix Extension for a lazy restore scheme. +@end itemize + +If @value{GDBN} sees this feature, it will attempt to find one of the +variations of the register set. If @samp{tpidr2} is available, +@value{GDBN} may act on it to display additional data in the future. + +There is no XML for this feature as the presence of @samp{tpidr2} is +determined dynamically at runtime. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 MTE registers feature + +The @samp{org.gnu.gdb.aarch64.mte} optional feature was introduced so +@value{GDBN} could detect support for the Memory Tagging Extension and +control memory tagging settings. If present, this feature must have the +following register: + +@itemize @minus +@item +@samp{tag_ctl}, the tag control register. It is 64 bits in size and has a type +of @samp{uint64}. +@end itemize + +Memory Tagging detection is done via a runtime check though, so the presence +of this feature and register is not enough to enable memory tagging support. + +This restriction may be lifted in the future. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection AArch64 SME registers feature + +The @samp{org.gnu.gdb.aarch64.sme} feature is optional. If present, +it should contain registers @code{ZA}, @code{SVG} and @code{SVCR}. +@xref{AArch64 SME}. + +@itemize @minus + +@item +@code{ZA} is a register represented by a vector of @var{svl}x@var{svl} +bytes. @xref{svl}. + +@item +@code{SVG} is a 64-bit register containing the value of @var{svg}. @xref{svg}. + +@item +@code{SVCR} is a 64-bit status pseudo-register with two valid bits. Bit 0 +(@sc{sm}) shows whether the streaming @acronym{SVE} mode is enabled or disabled. +Bit 1 (@sc{ZA}) shows whether the @code{ZA} register state is active (in use) or +not. +@xref{aarch64 sme svcr}. + +The rest of the unused bits of the @code{SVCR} pseudo-register is undefined +and reserved. Such bits should not be used and may be defined by future +extensions of the architecture. + +@end itemize + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +The @samp{org.gnu.gdb.aarch64.sme} feature is required when the target also +reports support for the @samp{org.gnu.gdb.aarch64.sme2} feature. + +@subsubsection AArch64 SME2 registers feature + +The @samp{org.gnu.gdb.aarch64.sme2} feature is optional. If present, +then the @samp{org.gnu.gdb.aarch64.sme} feature must also be present. The +@samp{org.gnu.gdb.aarch64.sme2} feature should contain the following: +@xref{AArch64 SME2}. + +@itemize @minus + +@item +@code{ZT0} is a register of 512 bits (64 bytes). It is defined as a vector +of bytes. + +@end itemize + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@node ARC Features +@subsection ARC Features +@cindex target descriptions, ARC Features + +ARC processors are so configurable that even core registers and their numbers +are not predetermined completely. Moreover, @emph{flags} and @emph{PC} +registers, which are important to @value{GDBN}, are not ``core'' registers in +ARC. Therefore, there are two features that their presence is mandatory: +@samp{org.gnu.gdb.arc.core} and @samp{org.gnu.gdb.arc.aux}. + +The @samp{org.gnu.gdb.arc.core} feature is required for all targets. It must +contain registers: + +@itemize @minus +@item +@samp{r0} through @samp{r25} for normal register file targets. +@item +@samp{r0} through @samp{r3}, and @samp{r10} through @samp{r15} for reduced +register file targets. +@item +@samp{gp}, @samp{fp}, @samp{sp}, @samp{r30}@footnote{Not necessary for ARCv1.}, +@samp{blink}, @samp{lp_count}, @samp{pcl}. +@end itemize + +In case of an ARCompact target (ARCv1 ISA), the @samp{org.gnu.gdb.arc.core} +feature may contain registers @samp{ilink1} and @samp{ilink2}. While in case +of ARC EM and ARC HS targets (ARCv2 ISA), register @samp{ilink} may be present. +The difference between ARCv1 and ARCv2 is the naming of registers @emph{29th} +and @emph{30th}. They are called @samp{ilink1} and @samp{ilink2} for ARCv1 and +are optional. For ARCv2, they are called @samp{ilink} and @samp{r30} and only +@samp{ilink} is optional. The optionality of @samp{ilink*} registers is +because of their inaccessibility during user space debugging sessions. + +Extension core registers @samp{r32} through @samp{r59} are optional and their +existence depends on the configuration. When debugging GNU/Linux applications, +i.e.@: user space debugging, these core registers are not available. + +The @samp{org.gnu.gdb.arc.aux} feature is required for all ARC targets. Here +is the list of registers pertinent to this feature: + +@itemize @minus +@item +mandatory: @samp{pc} and @samp{status32}. +@item +optional: @samp{lp_start}, @samp{lp_end}, and @samp{bta}. +@end itemize + +@node ARM Features +@subsection ARM Features +@cindex target descriptions, ARM features + +@subsubsection Core register set for non-M-profile + +The @samp{org.gnu.gdb.arm.core} feature is required for non-M-profile +ARM targets. It must contain the following registers: + +@itemize @minus +@item +@samp{r0} through @samp{r12}. The general purpose registers. They are 32 bits +in size and have a type of @samp{uint32}. +@item +@samp{sp}, the stack pointer register, also known as @samp{r13}. It is 32 bits +in size and has a type of @samp{data_ptr}. +@item +@samp{lr}, the link register. It is 32 bits in size. +@item +@samp{pc}, the program counter register. It is 32 bit in size and of type +@samp{code_ptr}. +@item +@samp{cpsr}, the current program status register containing all the status +bits. It is 32 bits in size. Historically this register was hardwired to +number 25, but debugging stubs that report XML do not need to use this number +anymore. +@end itemize + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection Core register set for M-profile + +For M-profile targets (e.g.@: Cortex-M3), the @samp{org.gnu.gdb.arm.core} +feature is replaced by @samp{org.gnu.gdb.arm.m-profile}, and it is a required +feature. It must contain the following registers: + +@itemize @minus +@item +@samp{r0} through @samp{r12}, the general purpose registers. They have a size +of 32 bits and a type of @samp{uint32}. +@item +@samp{sp}, the stack pointer register, also known as @samp{r13}. It has a size +of 32 bits and a type of @samp{data_ptr}. +@item +@samp{lr}, the link register. It has a size of 32 bits. +@item +@samp{pc}, the program counter register. It has a size of 32 bits and a type +of @samp{code_ptr}. +@item +@samp{xpsr}, the program status register containing all the status +bits. It has a size of 32 bits. Historically this register was hardwired to +number 25, but debugging stubs that report XML do not need to use this number +anymore. +@end itemize + +Upon seeing this feature, @value{GDBN} will acknowledge that it is dealing +with an M-profile target. This means @value{GDBN} will use hooks and +configurations that are meaningful to M-profiles. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection FPA registers feature (obsolete) + +The @samp{org.gnu.gdb.arm.fpa} feature is obsolete and should not be +advertised by debugging stubs anymore. It used to advertise registers for +the old FPA architecture that has long been discontinued in toolchains. + +It is kept in @value{GDBN} for backward compatibility purposes so older +debugging stubs that don't support XML target descriptions still work +correctly. One such example is the KGDB debugging stub from +Linux or BSD kernels. + +The description below is for historical purposes only. This feature +used to contain the following registers: + +@itemize @minus +@item +@samp{f0} through @samp{f8}. The floating point registers. They are 96 bits +in size and of type @samp{arm_fpa_ext}. @samp{f0} is pinned to register +number 16. +@item +@samp{fps}, the status register. It has a size of 32 bits. +@end itemize + +@subsubsection M-profile Vector Extension (MVE) + +Also known as Helium, the M-profile Vector Extension is advertised via the +optional @samp{org.gnu.gdb.arm.m-profile-mve} feature. + +It must contain the following: + +@itemize @minus +@item +@samp{vpr}, the vector predication status and control register. It is 32 bits +in size and has a custom flags type. The flags type is laid out in a way that +exposes the @samp{P0} field from bits 0 to 15, the @samp{MASK01} field from +bits 16 to 19 and the @samp{MASK23} field from bits 20 to 23. + +Bits 24 through 31 are reserved. +@end itemize + +When this feature is available, @value{GDBN} will synthesize the @samp{p0} +pseudo-register from @samp{vpr} contents. + +This feature must only be advertised if the target is M-profile. Advertising +this feature for targets that are not M-profile may cause @value{GDBN} to +assume the target is M-profile when it isn't. + +If the @samp{org.gnu.gdb.arm.vfp} feature is available alongside the +@samp{org.gnu.gdb.arm.m-profile-mve} feature, @value{GDBN} will +synthesize the @samp{q} pseudo-registers from @samp{d} register +contents. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection XScale iwMMXt feature + +The XScale @samp{org.gnu.gdb.xscale.iwmmxt} feature is optional. If present, +it must contain the following: + +@itemize @minus +@item +@samp{wR0} through @samp{wR15}, registers with size 64 bits and a custom type +@samp{iwmmxt_vec64i}. @samp{iwmmxt_vec64i} is a union of four other +types: @samp{uint64}, a 2-element vector of @samp{uint32}, a 4-element +vector of @samp{uint16} and a 8-element vector of @samp{uint8}. +@item +@samp{wCGR0} through @samp{wCGR3}, registers with size 32 bits and +type @samp{int}. +@end itemize + +The following registers are optional: + +@itemize @minus +@item +@samp{wCID}, register with size of 32 bits and type @samp{int}. +@item +@samp{wCon}, register with size 32 bits and type @samp{int}. +@item +@samp{wCSSF}, register with size 32 bits and type @samp{int}. +@item +@samp{wCASF}, register with size 32 bit and type @samp{int}. +@end itemize + +This feature should only be reported if the target is XScale. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection Vector Floating-Point (VFP) feature + +The @samp{org.gnu.gdb.arm.vfp} feature is optional. If present, it +should contain one of two possible sets of values depending on whether +VFP version 2 or VFP version 3 is in use. + +For VFP v2: + +@itemize @minus +@item +@samp{d0} through @samp{d15}. The double-precision registers. They are +64 bits in size and have type @samp{ieee_double}. +@item +@samp{fpscr}, the floating-point status and control register. It has a size +of 32 bits and a type of @samp{int}. +@end itemize + +For VFP v3: + +@itemize @minus +@item +@samp{d0} through @samp{d31}. The double-precision registers. They are +64 bits in size and have type @samp{ieee_double}. +@item +@samp{fpscr}, the floating-point status and control register. It has a size +of 32 bits and a type of @samp{int}. +@end itemize + +If this feature is available, @value{GDBN} will synthesize the +single-precision floating-point registers from halves of the double-precision +registers as pseudo-registers. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection NEON architecture feature + +The @samp{org.gnu.gdb.arm.neon} feature is optional. It does not +need to contain registers; it instructs @value{GDBN} to display the +VFP double-precision registers as vectors and to synthesize the +quad-precision registers from pairs of double-precision registers. +If this feature is present, @samp{org.gnu.gdb.arm.vfp} must also +be present and include 32 double-precision registers. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection M-profile Pointer Authentication and Branch Target Identification feature + +The @samp{org.gnu.gdb.arm.m-profile-pacbti} feature is optional, and +acknowledges support for the ARMv8.1-m PACBTI extensions. + +This feature doesn't contain any required registers, and it only serves as a +hint to @value{GDBN} that the debugging stub supports the ARMv8.1-m PACBTI +extensions. + +When @value{GDBN} sees this feature, it will track return address signing +states and will decorate backtraces using the [PAC] marker, similar to +AArch64's PAC extension. +@xref{AArch64 PAC}. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection M-profile system registers feature + +The @samp{org.gnu.gdb.arm.m-system} optional feature was introduced as a way to +inform @value{GDBN} about additional system registers. + +At the moment this feature must contain the following: + +@itemize @minus +@item +@samp{msp}, the main stack pointer register. It is 32 bits in size with +type @samp{data_ptr}. +@item +@samp{psp}, the process stack pointer register. It is 32 bits in size with +type @samp{data_ptr}. +@end itemize + +This feature must only be advertised for M-profile targets. When @value{GDBN} +sees this feature, it will attempt to track the values of @samp{msp} and +@samp{psp} across frames. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection M-profile Security Extensions feature + +The @samp{org.gnu.gdb.arm.secext} optional feature was introduced so +@value{GDBN} could better support the switching of stack pointers and +secure states in the Security Extensions. + +At the moment this feature must contain the following: + +@itemize @minus +@item +@samp{msp_ns}, the main stack pointer register (non-secure state). It is +32 bits in size with type @samp{data_ptr}. +@item +@samp{psp_ns}, the process stack pointer register (non-secure state). It is +32 bits in size with type @samp{data_ptr}. +@item +@samp{msp_s}, the main stack pointer register (secure state). It is 32 bits +in size with type @samp{data_ptr}. +@item +@samp{psp_s}, the process stack pointer register (secure state). It is 32 bits +in size with type @samp{data_ptr}. +@end itemize + +When @value{GDBN} sees this feature, it will attempt to track the values of +all 4 stack pointers across secure state transitions, potentially improving +unwinding when applications switch between security states. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@subsubsection TLS registers feature + +The optional @samp{org.gnu.gdb.arm.tls} feature contains TLS registers. + +Currently it contains the following: + +@itemize @minus +@item +@samp{tpidruro}, the user read-only thread id register. It is 32 bits in size +and has type @samp{data_ptr}. +@end itemize + +At the moment @value{GDBN} looks for this feature, but doesn't do anything +with it other than displaying it. + +Extra registers are allowed in this feature, but they will not affect +@value{GDBN}. + +@node i386 Features +@subsection i386 Features +@cindex target descriptions, i386 features + +The @samp{org.gnu.gdb.i386.core} feature is required for i386/amd64 +targets. It should describe the following registers: + +@itemize @minus +@item +@samp{eax} through @samp{edi} plus @samp{eip} for i386 +@item +@samp{rax} through @samp{r15} plus @samp{rip} for amd64 +@item +@samp{eflags}, @samp{cs}, @samp{ss}, @samp{ds}, @samp{es}, +@samp{fs}, @samp{gs} +@item +@samp{st0} through @samp{st7} +@item +@samp{fctrl}, @samp{fstat}, @samp{ftag}, @samp{fiseg}, @samp{fioff}, +@samp{foseg}, @samp{fooff} and @samp{fop} +@end itemize + +The register sets may be different, depending on the target. + +The @samp{org.gnu.gdb.i386.sse} feature is optional. It should +describe registers: + +@itemize @minus +@item +@samp{xmm0} through @samp{xmm7} for i386 +@item +@samp{xmm0} through @samp{xmm15} for amd64 +@item +@samp{mxcsr} +@end itemize + +The @samp{org.gnu.gdb.i386.avx} feature is optional and requires the +@samp{org.gnu.gdb.i386.sse} feature. It should +describe the upper 128 bits of @sc{ymm} registers: + +@itemize @minus +@item +@samp{ymm0h} through @samp{ymm7h} for i386 +@item +@samp{ymm0h} through @samp{ymm15h} for amd64 +@end itemize + +The @samp{org.gnu.gdb.i386.linux} feature is optional. It should +describe a single register, @samp{orig_eax}. + +The @samp{org.gnu.gdb.i386.segments} feature is optional. It should +describe two system registers: @samp{fs_base} and @samp{gs_base}. + +The @samp{org.gnu.gdb.i386.avx512} feature is optional and requires the +@samp{org.gnu.gdb.i386.avx} feature. It should +describe additional @sc{xmm} registers: + +@itemize @minus +@item +@samp{xmm16} through @samp{xmm31}, only valid for amd64. +@end itemize + +It should describe the upper 128 bits of additional @sc{ymm} registers: + +@itemize @minus +@item +@samp{ymm16h} through @samp{ymm31h}, only valid for amd64. +@end itemize + +It should +describe the upper 256 bits of @sc{zmm} registers: + +@itemize @minus +@item +@samp{zmm0h} through @samp{zmm7h} for i386. +@item +@samp{zmm0h} through @samp{zmm15h} for amd64. +@end itemize + +It should +describe the additional @sc{zmm} registers: + +@itemize @minus +@item +@samp{zmm16h} through @samp{zmm31h}, only valid for amd64. +@end itemize + +It should +describe the additional 64-bit @sc{k} registers: + +@itemize @minus +@item +@samp{k0} through @samp{k7}, valid for amd64 and i386. +@end itemize + +The @samp{org.gnu.gdb.i386.pkeys} feature is optional. It should +describe a single register, @samp{pkru}. It is a 32-bit register +valid for i386 and amd64. + +@node LoongArch Features +@subsection LoongArch Features +@cindex target descriptions, LoongArch Features + +The @samp{org.gnu.gdb.loongarch.base} feature is required for LoongArch +targets. It should contain the registers @samp{r0} through @samp{r31}, +@samp{pc}, and @samp{badv}. Either the architectural names (@samp{r0}, +@samp{r1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, etc). + +The @samp{org.gnu.gdb.loongarch.fpu} feature is optional. If present, +it should contain registers @samp{f0} through @samp{f31}, @samp{fcc}, +and @samp{fcsr}. + +@node MicroBlaze Features +@subsection MicroBlaze Features +@cindex target descriptions, MicroBlaze features + +The @samp{org.gnu.gdb.microblaze.core} feature is required for MicroBlaze +targets. It should contain registers @samp{r0} through @samp{r31}, +@samp{rpc}, @samp{rmsr}, @samp{rear}, @samp{resr}, @samp{rfsr}, @samp{rbtr}, +@samp{rpvr}, @samp{rpvr1} through @samp{rpvr11}, @samp{redr}, @samp{rpid}, +@samp{rzpr}, @samp{rtlbx}, @samp{rtlbsx}, @samp{rtlblo}, and @samp{rtlbhi}. + +The @samp{org.gnu.gdb.microblaze.stack-protect} feature is optional. +If present, it should contain registers @samp{rshr} and @samp{rslr} + +@node MIPS Features +@subsection @acronym{MIPS} Features +@cindex target descriptions, @acronym{MIPS} features + +The @samp{org.gnu.gdb.mips.cpu} feature is required for @acronym{MIPS} targets. +It should contain registers @samp{r0} through @samp{r31}, @samp{lo}, +@samp{hi}, and @samp{pc}. They may be 32-bit or 64-bit depending +on the target. + +The @samp{org.gnu.gdb.mips.cp0} feature is also required. It should +contain at least the @samp{status}, @samp{badvaddr}, and @samp{cause} +registers. They may be 32-bit or 64-bit depending on the target. + +The @samp{org.gnu.gdb.mips.fpu} feature is currently required, though +it may be optional in a future version of @value{GDBN}. It should +contain registers @samp{f0} through @samp{f31}, @samp{fcsr}, and +@samp{fir}. They may be 32-bit or 64-bit depending on the target. + +The @samp{org.gnu.gdb.mips.dsp} feature is optional. It should +contain registers @samp{hi1} through @samp{hi3}, @samp{lo1} through +@samp{lo3}, and @samp{dspctl}. The @samp{dspctl} register should +be 32-bit and the rest may be 32-bit or 64-bit depending on the target. + +The @samp{org.gnu.gdb.mips.linux} feature is optional. It should +contain a single register, @samp{restart}, which is used by the +Linux kernel to control restartable syscalls. + +@node M68K Features +@subsection M68K Features +@cindex target descriptions, M68K features + +@table @code +@item @samp{org.gnu.gdb.m68k.core} +@itemx @samp{org.gnu.gdb.coldfire.core} +@itemx @samp{org.gnu.gdb.fido.core} +One of those features must be always present. +The feature that is present determines which flavor of m68k is +used. The feature that is present should contain registers +@samp{d0} through @samp{d7}, @samp{a0} through @samp{a5}, @samp{fp}, +@samp{sp}, @samp{ps} and @samp{pc}. + +@item @samp{org.gnu.gdb.coldfire.fp} +This feature is optional. If present, it should contain registers +@samp{fp0} through @samp{fp7}, @samp{fpcontrol}, @samp{fpstatus} and +@samp{fpiaddr}. + +Note that, despite the fact that this feature's name says +@samp{coldfire}, it is used to describe any floating point registers. +The size of the registers must match the main m68k flavor; so, for +example, if the primary feature is reported as @samp{coldfire}, then +64-bit floating point registers are required. +@end table + +@node NDS32 Features +@subsection NDS32 Features +@cindex target descriptions, NDS32 features + +The @samp{org.gnu.gdb.nds32.core} feature is required for NDS32 +targets. It should contain at least registers @samp{r0} through +@samp{r10}, @samp{r15}, @samp{fp}, @samp{gp}, @samp{lp}, @samp{sp}, +and @samp{pc}. + +The @samp{org.gnu.gdb.nds32.fpu} feature is optional. If present, +it should contain 64-bit double-precision floating-point registers +@samp{fd0} through @emph{fdN}, which should be @samp{fd3}, @samp{fd7}, +@samp{fd15}, or @samp{fd31} based on the FPU configuration implemented. + +@emph{Note:} The first sixteen 64-bit double-precision floating-point +registers are overlapped with the thirty-two 32-bit single-precision +floating-point registers. The 32-bit single-precision registers, if +not being listed explicitly, will be synthesized from halves of the +overlapping 64-bit double-precision registers. Listing 32-bit +single-precision registers explicitly is deprecated, and the +support to it could be totally removed some day. + +@node OpenRISC 1000 Features +@subsection Openrisc 1000 Features +@cindex target descriptions, OpenRISC 1000 features + +The @samp{org.gnu.gdb.or1k.group0} feature is required for OpenRISC 1000 +targets. It should contain the 32 general purpose registers (@samp{r0} +through @samp{r31}), @samp{ppc}, @samp{npc} and @samp{sr}. + +@node PowerPC Features +@subsection PowerPC Features +@cindex target descriptions, PowerPC features + +The @samp{org.gnu.gdb.power.core} feature is required for PowerPC +targets. It should contain registers @samp{r0} through @samp{r31}, +@samp{pc}, @samp{msr}, @samp{cr}, @samp{lr}, @samp{ctr}, and +@samp{xer}. They may be 32-bit or 64-bit depending on the target. + +The @samp{org.gnu.gdb.power.fpu} feature is optional. It should +contain registers @samp{f0} through @samp{f31} and @samp{fpscr}. + +The @samp{org.gnu.gdb.power.altivec} feature is optional. It should +contain registers @samp{vr0} through @samp{vr31}, @samp{vscr}, and +@samp{vrsave}. @value{GDBN} will define pseudo-registers @samp{v0} +through @samp{v31} as aliases for the corresponding @samp{vrX} +registers. + +The @samp{org.gnu.gdb.power.vsx} feature is optional. It should +contain registers @samp{vs0h} through @samp{vs31h}. @value{GDBN} will +combine these registers with the floating point registers (@samp{f0} +through @samp{f31}) and the altivec registers (@samp{vr0} through +@samp{vr31}) to present the 128-bit wide registers @samp{vs0} through +@samp{vs63}, the set of vector-scalar registers for POWER7. +Therefore, this feature requires both @samp{org.gnu.gdb.power.fpu} and +@samp{org.gnu.gdb.power.altivec}. + +The @samp{org.gnu.gdb.power.spe} feature is optional. It should +contain registers @samp{ev0h} through @samp{ev31h}, @samp{acc}, and +@samp{spefscr}. SPE targets should provide 32-bit registers in +@samp{org.gnu.gdb.power.core} and provide the upper halves in +@samp{ev0h} through @samp{ev31h}. @value{GDBN} will combine +these to present registers @samp{ev0} through @samp{ev31} to the +user. + +The @samp{org.gnu.gdb.power.ppr} feature is optional. It should +contain the 64-bit register @samp{ppr}. + +The @samp{org.gnu.gdb.power.dscr} feature is optional. It should +contain the 64-bit register @samp{dscr}. + +The @samp{org.gnu.gdb.power.tar} feature is optional. It should +contain the 64-bit register @samp{tar}. + +The @samp{org.gnu.gdb.power.ebb} feature is optional. It should +contain registers @samp{bescr}, @samp{ebbhr} and @samp{ebbrr}, all +64-bit wide. + +The @samp{org.gnu.gdb.power.linux.pmu} feature is optional. It should +contain registers @samp{mmcr0}, @samp{mmcr2}, @samp{siar}, @samp{sdar} +and @samp{sier}, all 64-bit wide. This is the subset of the isa 2.07 +server PMU registers provided by @sc{gnu}/Linux. + +The @samp{org.gnu.gdb.power.htm.spr} feature is optional. It should +contain registers @samp{tfhar}, @samp{texasr} and @samp{tfiar}, all +64-bit wide. + +The @samp{org.gnu.gdb.power.htm.core} feature is optional. It should +contain the checkpointed general-purpose registers @samp{cr0} through +@samp{cr31}, as well as the checkpointed registers @samp{clr} and +@samp{cctr}. These registers may all be either 32-bit or 64-bit +depending on the target. It should also contain the checkpointed +registers @samp{ccr} and @samp{cxer}, which should both be 32-bit +wide. + +The @samp{org.gnu.gdb.power.htm.fpu} feature is optional. It should +contain the checkpointed 64-bit floating-point registers @samp{cf0} +through @samp{cf31}, as well as the checkpointed 64-bit register +@samp{cfpscr}. + +The @samp{org.gnu.gdb.power.htm.altivec} feature is optional. It +should contain the checkpointed altivec registers @samp{cvr0} through +@samp{cvr31}, all 128-bit wide. It should also contain the +checkpointed registers @samp{cvscr} and @samp{cvrsave}, both 32-bit +wide. + +The @samp{org.gnu.gdb.power.htm.vsx} feature is optional. It should +contain registers @samp{cvs0h} through @samp{cvs31h}. @value{GDBN} +will combine these registers with the checkpointed floating point +registers (@samp{cf0} through @samp{cf31}) and the checkpointed +altivec registers (@samp{cvr0} through @samp{cvr31}) to present the +128-bit wide checkpointed vector-scalar registers @samp{cvs0} through +@samp{cvs63}. Therefore, this feature requires both +@samp{org.gnu.gdb.power.htm.altivec} and +@samp{org.gnu.gdb.power.htm.fpu}. + +The @samp{org.gnu.gdb.power.htm.ppr} feature is optional. It should +contain the 64-bit checkpointed register @samp{cppr}. + +The @samp{org.gnu.gdb.power.htm.dscr} feature is optional. It should +contain the 64-bit checkpointed register @samp{cdscr}. + +The @samp{org.gnu.gdb.power.htm.tar} feature is optional. It should +contain the 64-bit checkpointed register @samp{ctar}. + + +@node RISC-V Features +@subsection RISC-V Features +@cindex target descriptions, RISC-V Features + +The @samp{org.gnu.gdb.riscv.cpu} feature is required for RISC-V +targets. It should contain the registers @samp{x0} through +@samp{x31}, and @samp{pc}. Either the architectural names (@samp{x0}, +@samp{x1}, etc) can be used, or the ABI names (@samp{zero}, @samp{ra}, +etc). + +The @samp{org.gnu.gdb.riscv.fpu} feature is optional. If present, it +should contain registers @samp{f0} through @samp{f31}, @samp{fflags}, +@samp{frm}, and @samp{fcsr}. As with the cpu feature, either the +architectural register names, or the ABI names can be used. + +The @samp{org.gnu.gdb.riscv.virtual} feature is optional. If present, +it should contain registers that are not backed by real registers on +the target, but are instead virtual, where the register value is +derived from other target state. In many ways these are like +@value{GDBN}s pseudo-registers, except implemented by the target. +Currently the only register expected in this set is the one byte +@samp{priv} register that contains the target's privilege level in the +least significant two bits. + +The @samp{org.gnu.gdb.riscv.csr} feature is optional. If present, it +should contain all of the target's standard CSRs. Standard CSRs are +those defined in the RISC-V specification documents. There is some +overlap between this feature and the fpu feature; the @samp{fflags}, +@samp{frm}, and @samp{fcsr} registers could be in either feature. The +expectation is that these registers will be in the fpu feature if the +target has floating point hardware, but can be moved into the csr +feature if the target has the floating point control registers, but no +other floating point hardware. + +The @samp{org.gnu.gdb.riscv.vector} feature is optional. If present, +it should contain registers @samp{v0} through @samp{v31}, all of which +must be the same size. + +@node RX Features +@subsection RX Features +@cindex target descriptions, RX Features + +The @samp{org.gnu.gdb.rx.core} feature is required for RX +targets. It should contain the registers @samp{r0} through +@samp{r15}, @samp{usp}, @samp{isp}, @samp{psw}, @samp{pc}, @samp{intb}, +@samp{bpsw}, @samp{bpc}, @samp{fintv}, @samp{fpsw}, and @samp{acc}. + +@node S/390 and System z Features +@subsection S/390 and System z Features +@cindex target descriptions, S/390 features +@cindex target descriptions, System z features + +The @samp{org.gnu.gdb.s390.core} feature is required for S/390 and +System z targets. It should contain the PSW and the 16 general +registers. In particular, System z targets should provide the 64-bit +registers @samp{pswm}, @samp{pswa}, and @samp{r0} through @samp{r15}. +S/390 targets should provide the 32-bit versions of these registers. +A System z target that runs in 31-bit addressing mode should provide +32-bit versions of @samp{pswm} and @samp{pswa}, as well as the general +register's upper halves @samp{r0h} through @samp{r15h}, and their +lower halves @samp{r0l} through @samp{r15l}. + +The @samp{org.gnu.gdb.s390.fpr} feature is required. It should +contain the 64-bit registers @samp{f0} through @samp{f15}, and +@samp{fpc}. + +The @samp{org.gnu.gdb.s390.acr} feature is required. It should +contain the 32-bit registers @samp{acr0} through @samp{acr15}. + +The @samp{org.gnu.gdb.s390.linux} feature is optional. It should +contain the register @samp{orig_r2}, which is 64-bit wide on System z +targets and 32-bit otherwise. In addition, the feature may contain +the @samp{last_break} register, whose width depends on the addressing +mode, as well as the @samp{system_call} register, which is always +32-bit wide. + +The @samp{org.gnu.gdb.s390.tdb} feature is optional. It should +contain the 64-bit registers @samp{tdb0}, @samp{tac}, @samp{tct}, +@samp{atia}, and @samp{tr0} through @samp{tr15}. + +The @samp{org.gnu.gdb.s390.vx} feature is optional. It should contain +64-bit wide registers @samp{v0l} through @samp{v15l}, which will be +combined by @value{GDBN} with the floating point registers @samp{f0} +through @samp{f15} to present the 128-bit wide vector registers +@samp{v0} through @samp{v15}. In addition, this feature should +contain the 128-bit wide vector registers @samp{v16} through +@samp{v31}. + +The @samp{org.gnu.gdb.s390.gs} feature is optional. It should contain +the 64-bit wide guarded-storage-control registers @samp{gsd}, +@samp{gssm}, and @samp{gsepla}. + +The @samp{org.gnu.gdb.s390.gsbc} feature is optional. It should contain +the 64-bit wide guarded-storage broadcast control registers +@samp{bc_gsd}, @samp{bc_gssm}, and @samp{bc_gsepla}. + +@node Sparc Features +@subsection Sparc Features +@cindex target descriptions, sparc32 features +@cindex target descriptions, sparc64 features +The @samp{org.gnu.gdb.sparc.cpu} feature is required for sparc32/sparc64 +targets. It should describe the following registers: + +@itemize @minus +@item +@samp{g0} through @samp{g7} +@item +@samp{o0} through @samp{o7} +@item +@samp{l0} through @samp{l7} +@item +@samp{i0} through @samp{i7} +@end itemize + +They may be 32-bit or 64-bit depending on the target. + +Also the @samp{org.gnu.gdb.sparc.fpu} feature is required for sparc32/sparc64 +targets. It should describe the following registers: + +@itemize @minus +@item +@samp{f0} through @samp{f31} +@item +@samp{f32} through @samp{f62} for sparc64 +@end itemize + +The @samp{org.gnu.gdb.sparc.cp0} feature is required for sparc32/sparc64 +targets. It should describe the following registers: + +@itemize @minus +@item +@samp{y}, @samp{psr}, @samp{wim}, @samp{tbr}, @samp{pc}, @samp{npc}, +@samp{fsr}, and @samp{csr} for sparc32 +@item +@samp{pc}, @samp{npc}, @samp{state}, @samp{fsr}, @samp{fprs}, and @samp{y} +for sparc64 +@end itemize + +@node TIC6x Features +@subsection TMS320C6x Features +@cindex target descriptions, TIC6x features +@cindex target descriptions, TMS320C6x features +The @samp{org.gnu.gdb.tic6x.core} feature is required for TMS320C6x +targets. It should contain registers @samp{A0} through @samp{A15}, +registers @samp{B0} through @samp{B15}, @samp{CSR} and @samp{PC}. + +The @samp{org.gnu.gdb.tic6x.gp} feature is optional. It should +contain registers @samp{A16} through @samp{A31} and @samp{B16} +through @samp{B31}. + +The @samp{org.gnu.gdb.tic6x.c6xp} feature is optional. It should +contain registers @samp{TSR}, @samp{ILC} and @samp{RILC}. + +@node Operating System Information +@appendix Operating System Information +@cindex operating system information + +Users of @value{GDBN} often wish to obtain information about the state of +the operating system running on the target---for example the list of +processes, or the list of open files. This section describes the +mechanism that makes it possible. This mechanism is similar to the +target features mechanism (@pxref{Target Descriptions}), but focuses +on a different aspect of target. + +Operating system information is retrieved from the target via the +remote protocol, using @samp{qXfer} requests (@pxref{qXfer osdata +read}). The object name in the request should be @samp{osdata}, and +the @var{annex} identifies the data to be fetched. + +@menu +* Process list:: +@end menu + +@node Process list +@appendixsection Process list +@cindex operating system information, process list + +When requesting the process list, the @var{annex} field in the +@samp{qXfer} request should be @samp{processes}. The returned data is +an XML document. The formal syntax of this document is defined in +@file{gdb/features/osdata.dtd}. + +An example document is: + +@smallexample + + + + + 1 + root + /sbin/init + 1,2,3 + + +@end smallexample + +Each item should include a column whose name is @samp{pid}. The value +of that column should identify the process on the target. The +@samp{user} and @samp{command} columns are optional, and will be +displayed by @value{GDBN}. The @samp{cores} column, if present, +should contain a comma-separated list of cores that this process +is running on. Target may provide additional columns, +which @value{GDBN} currently ignores. + +@node Trace File Format +@appendix Trace File Format +@cindex trace file format + +The trace file comes in three parts: a header, a textual description +section, and a trace frame section with binary data. + +The header has the form @code{\x7fTRACE0\n}. The first byte is +@code{0x7f} so as to indicate that the file contains binary data, +while the @code{0} is a version number that may have different values +in the future. + +The description section consists of multiple lines of @sc{ascii} text +separated by newline characters (@code{0xa}). The lines may include a +variety of optional descriptive or context-setting information, such +as tracepoint definitions or register set size. @value{GDBN} will +ignore any line that it does not recognize. An empty line marks the end +of this section. + +@table @code +@item R @var{size} +Specifies the size of a register block in bytes. This is equal to the +size of a @code{g} packet payload in the remote protocol. @var{size} +is an ascii decimal number. There should be only one such line in +a single trace file. + +@item status @var{status} +Trace status. @var{status} has the same format as a @code{qTStatus} +remote packet reply. There should be only one such line in a single trace +file. + +@item tp @var{payload} +Tracepoint definition. The @var{payload} has the same format as +@code{qTfP}/@code{qTsP} remote packet reply payload. A single tracepoint +may take multiple lines of definition, corresponding to the multiple +reply packets. + +@item tsv @var{payload} +Trace state variable definition. The @var{payload} has the same format as +@code{qTfV}/@code{qTsV} remote packet reply payload. A single variable +may take multiple lines of definition, corresponding to the multiple +reply packets. + +@item tdesc @var{payload} +Target description in XML format. The @var{payload} is a single line of +the XML file. All such lines should be concatenated together to get +the original XML file. This file is in the same format as @code{qXfer} +@code{features} payload, and corresponds to the main @code{target.xml} +file. Includes are not allowed. + +@end table + +The trace frame section consists of a number of consecutive frames. +Each frame begins with a two-byte tracepoint number, followed by a +four-byte size giving the amount of data in the frame. The data in +the frame consists of a number of blocks, each introduced by a +character indicating its type (at least register, memory, and trace +state variable). The data in this section is raw binary, not a +hexadecimal or other encoding; its endianness matches the target's +endianness. + +@c FIXME bi-arch may require endianness/arch info in description section + +@table @code +@item R @var{bytes} +Register block. The number and ordering of bytes matches that of a +@code{g} packet in the remote protocol. Note that these are the +actual bytes, in target order, not a hexadecimal encoding. + +@item M @var{address} @var{length} @var{bytes}... +Memory block. This is a contiguous block of memory, at the 8-byte +address @var{address}, with a 2-byte length @var{length}, followed by +@var{length} bytes. + +@item V @var{number} @var{value} +Trace state variable block. This records the 8-byte signed value +@var{value} of trace state variable numbered @var{number}. + +@end table + +Future enhancements of the trace file format may include additional types +of blocks. + +@node Index Section Format +@appendix @code{.gdb_index} section format +@cindex .gdb_index section format +@cindex index section format + +This section documents the index section that is created by @code{save +gdb-index} (@pxref{Index Files}). The index section is +DWARF-specific; some knowledge of DWARF is assumed in this +description. + +The mapped index file format is designed to be directly +@code{mmap}able on any architecture. In most cases, a datum is +represented using a little-endian 32-bit integer value, called an +@code{offset_type}. Big endian machines must byte-swap the values +before using them. Exceptions to this rule are noted. The data is +laid out such that alignment is always respected. + +A mapped index consists of several areas, laid out in order. + +@enumerate +@item +The file header. This is a sequence of values, of @code{offset_type} +unless otherwise noted: + +@enumerate +@item +The version number, currently 9. Versions 1, 2 and 3 are obsolete. +Version 4 uses a different hashing function from versions 5 and 6. +Version 6 includes symbols for inlined functions, whereas versions 4 +and 5 do not. Version 7 adds attributes to the CU indices in the +symbol table. Version 8 specifies that symbols from DWARF type units +(@samp{DW_TAG_type_unit}) refer to the type unit's symbol table and not the +compilation unit (@samp{DW_TAG_comp_unit}) using the type. Version 9 adds +the name and the language of the main function to the index. + +@value{GDBN} will only read version 4, 5, or 6 indices +by specifying @code{set use-deprecated-index-sections on}. +GDB has a workaround for potentially broken version 7 indices so it is +currently not flagged as deprecated. + +@item +The offset, from the start of the file, of the CU list. + +@item +The offset, from the start of the file, of the types CU list. Note +that this area can be empty, in which case this offset will be equal +to the next offset. + +@item +The offset, from the start of the file, of the address area. + +@item +The offset, from the start of the file, of the symbol table. + +@item +The offset, from the start of the file, of the shortcut table. + +@item +The offset, from the start of the file, of the constant pool. +@end enumerate + +@item +The CU list. This is a sequence of pairs of 64-bit little-endian +values, sorted by the CU offset. The first element in each pair is +the offset of a CU in the @code{.debug_info} section. The second +element in each pair is the length of that CU. References to a CU +elsewhere in the map are done using a CU index, which is just the +0-based index into this table. Note that if there are type CUs, then +conceptually CUs and type CUs form a single list for the purposes of +CU indices. + +@item +The types CU list. This is a sequence of triplets of 64-bit +little-endian values. In a triplet, the first value is the CU offset, +the second value is the type offset in the CU, and the third value is +the type signature. The types CU list is not sorted. + +@item +The address area. The address area consists of a sequence of address +entries. Each address entry has three elements: + +@enumerate +@item +The low address. This is a 64-bit little-endian value. + +@item +The high address. This is a 64-bit little-endian value. Like +@code{DW_AT_high_pc}, the value is one byte beyond the end. + +@item +The CU index. This is an @code{offset_type} value. +@end enumerate + +@item +The symbol table. This is an open-addressed hash table. The size of +the hash table is always a power of 2. + +Each slot in the hash table consists of a pair of @code{offset_type} +values. The first value is the offset of the symbol's name in the +constant pool. The second value is the offset of the CU vector in the +constant pool. + +If both values are 0, then this slot in the hash table is empty. This +is ok because while 0 is a valid constant pool index, it cannot be a +valid index for both a string and a CU vector. + +The hash value for a table entry is computed by applying an +iterative hash function to the symbol's name. Starting with an +initial value of @code{r = 0}, each (unsigned) character @samp{c} in +the string is incorporated into the hash using the formula depending on the +index version: + +@table @asis +@item Version 4 +The formula is @code{r = r * 67 + c - 113}. + +@item Versions 5 to 7 +The formula is @code{r = r * 67 + tolower (c) - 113}. +@end table + +The terminating @samp{\0} is not incorporated into the hash. + +The step size used in the hash table is computed via +@code{((hash * 17) & (size - 1)) | 1}, where @samp{hash} is the hash +value, and @samp{size} is the size of the hash table. The step size +is used to find the next candidate slot when handling a hash +collision. + +The names of C@t{++} symbols in the hash table are canonicalized. We +don't currently have a simple description of the canonicalization +algorithm; if you intend to create new index sections, you must read +the code. + +@item The shortcut table +This is a data structure with the following fields: + +@table @asis +@item Language of main +An @code{offset_type} value indicating the language of the main function as a +@code{DW_LANG_} constant. This value will be zero if main function information +is not present. + +@item Name of main +An @code{offset_type} value indicating the offset of the main function's name +in the constant pool. This value must be ignored if the value for the language +of main is zero. +@end table + +@item +The constant pool. This is simply a bunch of bytes. It is organized +so that alignment is correct: CU vectors are stored first, followed by +strings. + +A CU vector in the constant pool is a sequence of @code{offset_type} +values. The first value is the number of CU indices in the vector. +Each subsequent value is the index and symbol attributes of a CU in +the CU list. This element in the hash table is used to indicate which +CUs define the symbol and how the symbol is used. +See below for the format of each CU index+attributes entry. + +A string in the constant pool is zero-terminated. +@end enumerate + +Attributes were added to CU index values in @code{.gdb_index} version 7. +If a symbol has multiple uses within a CU then there is one +CU index+attributes value for each use. + +The format of each CU index+attributes entry is as follows +(bit 0 = LSB): + +@table @asis + +@item Bits 0-23 +This is the index of the CU in the CU list. +@item Bits 24-27 +These bits are reserved for future purposes and must be zero. +@item Bits 28-30 +The kind of the symbol in the CU. + +@table @asis +@item 0 +This value is reserved and should not be used. +By reserving zero the full @code{offset_type} value is backwards compatible +with previous versions of the index. +@item 1 +The symbol is a type. +@item 2 +The symbol is a variable or an enum value. +@item 3 +The symbol is a function. +@item 4 +Any other kind of symbol. +@item 5,6,7 +These values are reserved. +@end table + +@item Bit 31 +This bit is zero if the value is global and one if it is static. + +The determination of whether a symbol is global or static is complicated. +The authoritative reference is the file @file{dwarf2read.c} in +@value{GDBN} sources. + +@end table + +This pseudo-code describes the computation of a symbol's kind and +global/static attributes in the index. + +@smallexample +is_external = get_attribute (die, DW_AT_external); +language = get_attribute (cu_die, DW_AT_language); +switch (die->tag) + @{ + case DW_TAG_typedef: + case DW_TAG_base_type: + case DW_TAG_subrange_type: + kind = TYPE; + is_static = 1; + break; + case DW_TAG_enumerator: + kind = VARIABLE; + is_static = language != CPLUS; + break; + case DW_TAG_subprogram: + kind = FUNCTION; + is_static = ! (is_external || language == ADA); + break; + case DW_TAG_constant: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_variable: + kind = VARIABLE; + is_static = ! is_external; + break; + case DW_TAG_namespace: + kind = TYPE; + is_static = 0; + break; + case DW_TAG_class_type: + case DW_TAG_interface_type: + case DW_TAG_structure_type: + case DW_TAG_union_type: + case DW_TAG_enumeration_type: + kind = TYPE; + is_static = language != CPLUS; + break; + default: + assert (0); + @} +@end smallexample + +@node Debuginfod +@appendix Download debugging resources with Debuginfod +@cindex debuginfod + +@code{debuginfod} is an HTTP server for distributing ELF, DWARF and source +files. + +With the @code{debuginfod} client library, @file{libdebuginfod}, @value{GDBN} +can query servers using the build IDs associated with missing debug info, +executables and source files in order to download them on demand. + +For instructions on building @value{GDBN} with @file{libdebuginfod}, +@pxref{Configure Options,,--with-debuginfod}. @code{debuginfod} is packaged +with @code{elfutils}, starting with version 0.178. See +@uref{https://sourceware.org/elfutils/Debuginfod.html} for more information +regarding @code{debuginfod}. + +@menu +* Debuginfod Settings:: Configuring debuginfod with @value{GDBN} +@end menu + +@node Debuginfod Settings +@section Debuginfod Settings + +@value{GDBN} provides the following commands for configuring @code{debuginfod}. + +@table @code +@kindex set debuginfod enabled +@anchor{set debuginfod enabled} +@item set debuginfod enabled +@itemx set debuginfod enabled on +@cindex enable debuginfod +@value{GDBN} may query @code{debuginfod} servers for missing debug info and +source files. @value{GDBN} may also download individual ELF/DWARF sections +such as @code{.gdb_index} to help reduce the total amount of data downloaded +from @code{debuginfod} servers; this can be controlled by @w{@code{maint +set debuginfod download-sections}} (@pxref{Maintenance Commands, maint set +debuginfod download-sections}). + +@item set debuginfod enabled off +@value{GDBN} will not attempt to query @code{debuginfod} servers when missing +debug info or source files. By default, @code{debuginfod enabled} is set to +@code{off} for non-interactive sessions. + +@item set debuginfod enabled ask +@value{GDBN} will prompt the user to enable or disable @code{debuginfod} before +attempting to perform the next query. By default, @code{debuginfod enabled} +is set to @code{ask} for interactive sessions. + +@kindex show debuginfod enabled +@item show debuginfod enabled +Display whether @code{debuginfod enabled} is set to @code{on}, @code{off} or +@code{ask}. + +@kindex set debuginfod urls +@cindex configure debuginfod URLs +@item set debuginfod urls +@itemx set debuginfod urls @var{urls} +Set the space-separated list of URLs that @code{debuginfod} will attempt to +query. Only @code{http://}, @code{https://} and @code{file://} protocols +should be used. The default value of @code{debuginfod urls} is copied from +the @var{DEBUGINFOD_URLS} environment variable. + +@kindex show debuginfod urls +@item show debuginfod urls +Display the list of URLs that @code{debuginfod} will attempt to query. + +@kindex set debuginfod verbose +@cindex debuginfod verbosity +@item set debuginfod verbose +@itemx set debuginfod verbose @var{n} +Enable or disable @code{debuginfod}-related output. Use a non-zero value +to enable and @code{0} to disable. @code{debuginfod} output is shown by +default. + +@kindex show debuginfod verbose +@item show debuginfod verbose +Show the current verbosity setting. + +@end table + +@node Man Pages +@appendix Manual pages +@cindex Man pages + +@menu +* gdb man:: The GNU Debugger man page +* gdbserver man:: Remote Server for the GNU Debugger man page +* gcore man:: Generate a core file of a running program +* gstack man:: Print a stack trace of a running program +* gdbinit man:: gdbinit scripts +* gdb-add-index man:: Add index files to speed up GDB +@end menu + +@node gdb man +@heading gdb man + +@c man title gdb The GNU Debugger + +@c man begin SYNOPSIS gdb +gdb [OPTIONS] [@var{prog}|@var{prog} @var{procID}|@var{prog} @var{core}] +@c man end + +@c man begin DESCRIPTION gdb +The purpose of a debugger such as @value{GDBN} is to allow you to see what is +going on ``inside'' another program while it executes -- or what another +program was doing at the moment it crashed. + +@value{GDBN} can do four main kinds of things (plus other things in support of +these) to help you catch bugs in the act: + +@itemize @bullet +@item +Start your program, specifying anything that might affect its behavior. + +@item +Make your program stop on specified conditions. + +@item +Examine what has happened, when your program has stopped. + +@item +Change things in your program, so you can experiment with correcting the +effects of one bug and go on to learn about another. +@end itemize + +You can use @value{GDBN} to debug programs written in C, C@t{++}, Fortran and +Modula-2. + +@value{GDBN} is invoked with the shell command @code{gdb}. Once started, it reads +commands from the terminal until you tell it to exit with the @value{GDBN} +command @code{quit} or @code{exit}. You can get online help from @value{GDBN} itself +by using the command @code{help}. + +You can run @code{gdb} with no arguments or options; but the most +usual way to start @value{GDBN} is with one argument or two, specifying an +executable program as the argument: + +@smallexample +gdb program +@end smallexample + +You can also start with both an executable program and a core file specified: + +@smallexample +gdb program core +@end smallexample + +You can, instead, specify a process ID as a second argument or use option +@code{-p}, if you want to debug a running process: + +@smallexample +gdb program 1234 +gdb -p 1234 +@end smallexample + +@noindent +would attach @value{GDBN} to process @code{1234}. With option @option{-p} you +can omit the @var{program} filename. + +Here are some of the most frequently needed @value{GDBN} commands: + +@c pod2man highlights the right hand side of the @item lines. +@table @env +@item break [@var{file}:][@var{function}|@var{line}] +Set a breakpoint at @var{function} or @var{line} (in @var{file}). + +@item run [@var{arglist}] +Start your program (with @var{arglist}, if specified). + +@item bt +Backtrace: display the program stack. + +@item print @var{expr} +Display the value of an expression. + +@item c +Continue running your program (after stopping, e.g.@: at a breakpoint). + +@item next +Execute next program line (after stopping); step @emph{over} any +function calls in the line. + +@item edit [@var{file}:]@var{function} +look at the program line where it is presently stopped. + +@item list [@var{file}:]@var{function} +type the text of the program in the vicinity of where it is presently stopped. + +@item step +Execute next program line (after stopping); step @emph{into} any +function calls in the line. + +@item help [@var{name}] +Show information about @value{GDBN} command @var{name}, or general information +about using @value{GDBN}. + +@item quit +@itemx exit +Exit from @value{GDBN}. +@end table + +@ifset man +For full details on @value{GDBN}, +see @cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +by Richard M. Stallman and Roland H. Pesch. The same text is available online +as the @code{gdb} entry in the @code{info} program. +@end ifset +@c man end + +@c man begin OPTIONS gdb +Any arguments other than options specify an executable +file and core file (or process ID); that is, the first argument +encountered with no +associated option flag is equivalent to a @option{--se} option, and the second, +if any, is equivalent to a @option{-c} option if it's the name of a file. +Many options have +both long and abbreviated forms; both are shown here. The long forms are also +recognized if you truncate them, so long as enough of the option is +present to be unambiguous. + +The abbreviated forms are shown here with @samp{-} and long forms are shown +with @samp{--} to reflect how they are shown in @option{--help}. However, +@value{GDBN} recognizes all of the following conventions for most options: + +@table @code +@item --option=@var{value} +@item --option @var{value} +@item -option=@var{value} +@item -option @var{value} +@item --o=@var{value} +@item --o @var{value} +@item -o=@var{value} +@item -o @var{value} +@end table + +All the options and command line arguments you give are processed +in sequential order. The order makes a difference when the @option{-x} +option is used. + +@table @env +@item --help +@itemx -h +List all options, with brief explanations. + +@item --symbols=@var{file} +@itemx -s @var{file} +Read symbol table from @var{file}. + +@item --write +Enable writing into executable and core files. + +@item --exec=@var{file} +@itemx -e @var{file} +Use @var{file} as the executable file to execute when +appropriate, and for examining pure data in conjunction with a core +dump. + +@item --se=@var{file} +Read symbol table from @var{file} and use it as the executable +file. + +@item --core=@var{file} +@itemx -c @var{file} +Use @var{file} as a core dump to examine. + +@item --command=@var{file} +@itemx -x @var{file} +Execute @value{GDBN} commands from @var{file}. + +@item --eval-command=@var{command} +@item -ex @var{command} +Execute given @value{GDBN} @var{command}. + +@item --init-eval-command=@var{command} +@item -iex +Execute @value{GDBN} @var{command} before loading the inferior. + +@item --directory=@var{directory} +@itemx -d @var{directory} +Add @var{directory} to the path to search for source files. + +@item --nh +Do not execute commands from @file{~/.config/gdb/gdbinit}, +@file{~/.gdbinit}, @file{~/.config/gdb/gdbearlyinit}, or +@file{~/.gdbearlyinit} + +@item --nx +@itemx -n +Do not execute commands from any @file{.gdbinit} or +@file{.gdbearlyinit} initialization files. + +@item --quiet +@item --silent +@itemx -q +``Quiet''. Do not print the introductory and copyright messages. These +messages are also suppressed in batch mode. + +@item --batch +Run in batch mode. Exit with status @code{0} after processing all the command +files specified with @option{-x} (and @file{.gdbinit}, if not inhibited). +Exit with nonzero status if an error occurs in executing the @value{GDBN} +commands in the command files. + +Batch mode may be useful for running @value{GDBN} as a filter, for example to +download and run a program on another computer; in order to make this +more useful, the message + +@smallexample +Program exited normally. +@end smallexample + +@noindent +(which is ordinarily issued whenever a program running under @value{GDBN} control +terminates) is not issued when running in batch mode. + +@item --batch-silent +Run in batch mode, just like @option{--batch}, but totally silent. All @value{GDBN} +output is suppressed (stderr is unaffected). This is much quieter than +@option{--silent} and would be useless for an interactive session. + +This is particularly useful when using targets that give @samp{Loading section} +messages, for example. + +Note that targets that give their output via @value{GDBN}, as opposed to writing +directly to @code{stdout}, will also be made silent. + +@item --args @var{prog} [@var{arglist}] +Change interpretation of command line so that arguments following this +option are passed as arguments to the inferior. As an example, take +the following command: + +@smallexample +gdb ./a.out -q +@end smallexample + +@noindent +It would start @value{GDBN} with @option{-q}, not printing the introductory message. On +the other hand, using: + +@smallexample +gdb --args ./a.out -q +@end smallexample + +@noindent +starts @value{GDBN} with the introductory message, and passes the option to the inferior. + +@item --pid=@var{pid} +Attach @value{GDBN} to an already running program, with the PID @var{pid}. + +@item --tui +Open the terminal user interface. + +@item --readnow +Read all symbols from the given symfile on the first access. + +@item --readnever +Do not read symbol files. + +@item --return-child-result +@value{GDBN}'s exit code will be the same as the child's exit code. + +@item --configuration +Print details about GDB configuration and then exit. + +@item --version +Print version information and then exit. + +@item --cd=@var{directory} +Run @value{GDBN} using @var{directory} as its working directory, +instead of the current directory. + +@item --data-directory=@var{directory} +@item -D +Run @value{GDBN} using @var{directory} as its data directory. The data +directory is where @value{GDBN} searches for its auxiliary files. + +@item --fullname +@itemx -f +Emacs sets this option when it runs @value{GDBN} as a subprocess. It tells +@value{GDBN} to output the full file name and line number in a standard, +recognizable fashion each time a stack frame is displayed (which +includes each time the program stops). This recognizable format looks +like two @samp{\032} characters, followed by the file name, line number +and character position separated by colons, and a newline. The +Emacs-to-@value{GDBN} interface program uses the two @samp{\032} +characters as a signal to display the source code for the frame. + +@item -b @var{baudrate} +Set the line speed (baud rate or bits per second) of any serial +interface used by @value{GDBN} for remote debugging. + +@item -l @var{timeout} +Set timeout, in seconds, for remote debugging. + +@item --tty=@var{device} +Run using @var{device} for your program's standard input and output. +@end table +@c man end + +@c man begin SEEALSO gdb +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +@noindent +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gdbserver man +@heading gdbserver man + +@c man title gdbserver Remote Server for the GNU Debugger +@format +@c man begin SYNOPSIS gdbserver +gdbserver @var{comm} @var{prog} [@var{args}@dots{}] + +gdbserver --attach @var{comm} @var{pid} + +gdbserver --multi @var{comm} +@c man end +@end format + +@c man begin DESCRIPTION gdbserver +@command{gdbserver} is a program that allows you to run @value{GDBN} on a different machine +than the one which is running the program being debugged. + +@ifclear man +@subheading Usage (server (target) side) +@end ifclear +@ifset man +Usage (server (target) side): +@end ifset + +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, as +@command{gdbserver} doesn't care about symbols. All symbol handling is taken care of by +the @value{GDBN} running on the host system. + +To use the server, you log on to the target system, and run the @command{gdbserver} +program. You must tell it (a) how to communicate with @value{GDBN}, (b) the name of +your program, and (c) its arguments. The general syntax is: + +@smallexample +target> gdbserver @var{comm} @var{program} [@var{args} ...] +@end smallexample + +For example, using a serial port, you might say: + +@smallexample +@ifset man +@c @file would wrap it as F. +target> gdbserver /dev/com1 emacs foo.txt +@end ifset +@ifclear man +target> gdbserver @file{/dev/com1} emacs foo.txt +@end ifclear +@end smallexample + +This tells @command{gdbserver} to debug emacs with an argument of foo.txt, and +to communicate with @value{GDBN} via @file{/dev/com1}. @command{gdbserver} now +waits patiently for the host @value{GDBN} to communicate with it. + +To use a TCP connection, you could say: + +@smallexample +target> gdbserver host:2345 emacs foo.txt +@end smallexample + +This says pretty much the same thing as the last example, except that we are +going to communicate with the @code{host} @value{GDBN} via TCP. The @code{host:2345} argument means +that we are expecting to see a TCP connection from @code{host} to local TCP port +2345. (Currently, the @code{host} part is ignored.) You can choose any number you +want for the port number as long as it does not conflict with any existing TCP +ports on the target system. This same port number must be used in the host +@value{GDBN}s @code{target remote} command, which will be described shortly. Note that if +you chose a port number that conflicts with another service, @command{gdbserver} will +print an error message and exit. + +@command{gdbserver} can also attach to running programs. +This is accomplished via the @option{--attach} argument. The syntax is: + +@smallexample +target> gdbserver --attach @var{comm} @var{pid} +@end smallexample + +@var{pid} is the process ID of a currently running process. It isn't +necessary to point @command{gdbserver} at a binary for the running process. + +To start @code{gdbserver} without supplying an initial command to run +or process ID to attach, use the @option{--multi} command line option. +In such case you should connect using @kbd{target extended-remote} to start +the program you want to debug. + +@smallexample +target> gdbserver --multi @var{comm} +@end smallexample + +@ifclear man +@subheading Usage (host side) +@end ifclear +@ifset man +Usage (host side): +@end ifset + +You need an unstripped copy of the target program on your host system, since +@value{GDBN} needs to examine its symbol tables and such. Start up @value{GDBN} as you normally +would, with the target program as the first argument. (You may need to use the +@option{--baud} option if the serial line is running at anything except 9600 baud.) +That is @code{gdb TARGET-PROG}, or @code{gdb --baud BAUD TARGET-PROG}. After that, the only +new command you need to know about is @code{target remote} +(or @code{target extended-remote}). Its argument is either +a device name (usually a serial device, like @file{/dev/ttyb}), or a @code{HOST:PORT} +descriptor. For example: + +@smallexample +@ifset man +@c @file would wrap it as F. +(@value{GDBP}) target remote /dev/ttyb +@end ifset +@ifclear man +(@value{GDBP}) target remote @file{/dev/ttyb} +@end ifclear +@end smallexample + +@noindent +communicates with the server via serial line @file{/dev/ttyb}, and: + +@smallexample +(@value{GDBP}) target remote the-target:2345 +@end smallexample + +@noindent +communicates via a TCP connection to port 2345 on host `the-target', where +you previously started up @command{gdbserver} with the same port number. Note that for +TCP connections, you must start up @command{gdbserver} prior to using the `target remote' +command, otherwise you may get an error that looks something like +`Connection refused'. + +@command{gdbserver} can also debug multiple inferiors at once, +described in +@ifset man +the @value{GDBN} manual in node @code{Inferiors Connections and Programs} +-- shell command @code{info -f gdb -n 'Inferiors Connections and Programs'}. +@end ifset +@ifclear man +@ref{Inferiors Connections and Programs}. +@end ifclear +In such case use the @code{extended-remote} @value{GDBN} command variant: + +@smallexample +(@value{GDBP}) target extended-remote the-target:2345 +@end smallexample + +The @command{gdbserver} option @option{--multi} may or may not be used in such +case. +@c man end + +@c man begin OPTIONS gdbserver +There are three different modes for invoking @command{gdbserver}: + +@itemize @bullet + +@item +Debug a specific program specified by its program name: + +@smallexample +gdbserver @var{comm} @var{prog} [@var{args}@dots{}] +@end smallexample + +The @var{comm} parameter specifies how should the server communicate +with @value{GDBN}; it is either a device name (to use a serial line), +a TCP port number (@code{:1234}), or @code{-} or @code{stdio} to use +stdin/stdout of @code{gdbserver}. Specify the name of the program to +debug in @var{prog}. Any remaining arguments will be passed to the +program verbatim. When the program exits, @value{GDBN} will close the +connection, and @code{gdbserver} will exit. + +@item +Debug a specific program by specifying the process ID of a running +program: + +@smallexample +gdbserver --attach @var{comm} @var{pid} +@end smallexample + +The @var{comm} parameter is as described above. Supply the process ID +of a running program in @var{pid}; @value{GDBN} will do everything +else. Like with the previous mode, when the process @var{pid} exits, +@value{GDBN} will close the connection, and @code{gdbserver} will exit. + +@item +Multi-process mode -- debug more than one program/process: + +@smallexample +gdbserver --multi @var{comm} +@end smallexample + +In this mode, @value{GDBN} can instruct @command{gdbserver} which +command(s) to run. Unlike the other 2 modes, @value{GDBN} will not +close the connection when a process being debugged exits, so you can +debug several processes in the same session. +@end itemize + +In each of the modes you may specify these options: + +@table @env + +@item --help +List all options, with brief explanations. + +@item --version +This option causes @command{gdbserver} to print its version number and exit. + +@item --attach +@command{gdbserver} will attach to a running program. The syntax is: + +@smallexample +target> gdbserver --attach @var{comm} @var{pid} +@end smallexample + +@var{pid} is the process ID of a currently running process. It isn't +necessary to point @command{gdbserver} at a binary for the running process. + +@item --multi +To start @code{gdbserver} without supplying an initial command to run +or process ID to attach, use this command line option. +Then you can connect using @kbd{target extended-remote} and start +the program you want to debug. The syntax is: + +@smallexample +target> gdbserver --multi @var{comm} +@end smallexample + +@item --debug@r{[}=option1,option2,@dots{}@r{]} +Instruct @code{gdbserver} to display extra status information about +the debugging process. This option is intended for @code{gdbserver} +development and for bug reports to the developers. + +Each @var{option} is the name of a component for which debugging +should be enabled. The list of possible options is @option{all}, +@option{threads}, @option{event-loop}, @option{remote}. The special +option @option{all} enables all components. The option list is +processed left to right, and an option can be prefixed with the +@kbd{-} character to disable output for that component, so you could write: + +@smallexample +target> gdbserver --debug=all,-event-loop +@end smallexample + +@noindent +to turn on debug output for all components except @option{event-loop}. +If no options are passed to @option{--debug} then this is treated as +equivalent to @option{--debug=threads}. This could change in future +releases of @code{gdbserver}. + +@item --debug-file=@var{filename} +Instruct @code{gdbserver} to send any debug output to the given @var{filename}. +This option is intended for @code{gdbserver} development and for bug reports to +the developers. + +@item --debug-format=option1@r{[},option2,...@r{]} +Instruct @code{gdbserver} to include extra information in each line +of debugging output. +@xref{Other Command-Line Arguments for gdbserver}. + +@item --wrapper +Specify a wrapper to launch programs +for debugging. The option should be followed by the name of the +wrapper, then any command-line arguments to pass to the wrapper, then +@kbd{--} indicating the end of the wrapper arguments. + +@item --once +By default, @command{gdbserver} keeps the listening TCP port open, so that +additional connections are possible. However, if you start @code{gdbserver} +with the @option{--once} option, it will stop listening for any further +connection attempts after connecting to the first @value{GDBN} session. + +@c --disable-packet is not documented for users. + +@c --disable-randomization and --no-disable-randomization are superseded by +@c QDisableRandomization. + +@end table +@c man end + +@c man begin SEEALSO gdbserver +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gcore man +@heading gcore + +@c man title gcore Generate a core file of a running program + +@format +@c man begin SYNOPSIS gcore +gcore [-a] [-o @var{prefix}] [-d @var{directory}] @var{pid1} [@var{pid2}...@var{pidN}] +@c man end +@end format + +@c man begin DESCRIPTION gcore +Generate core dumps of one or more running programs with process IDs +@var{pid1}, @var{pid2}, etc. A core file produced by @command{gcore} +is equivalent to one produced by the kernel when the process crashes +(and when @kbd{ulimit -c} was used to set up an appropriate core dump +limit). However, unlike after a crash, after @command{gcore} finishes +its job the program remains running without any change. +@c man end + +@c man begin OPTIONS gcore +@table @env +@item -a +Dump all memory mappings. The actual effect of this option depends on +the Operating System. On @sc{gnu}/Linux, it will disable +@code{use-coredump-filter} (@pxref{set use-coredump-filter}) and +enable @code{dump-excluded-mappings} (@pxref{set +dump-excluded-mappings}). + +@item -o @var{prefix} +The optional argument @var{prefix} specifies the prefix to be used +when composing the file names of the core dumps. The file name is +composed as @file{@var{prefix}.@var{pid}}, where @var{pid} is the +process ID of the running program being analyzed by @command{gcore}. +If not specified, @var{prefix} defaults to @var{gcore}. + +@item -d @var{directory} +Use @var{directory} as the data directory when invoking @value{GDBN} for running +the gcore command. This argument is optional. +@end table +@c man end + +@c man begin SEEALSO gcore +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +@noindent +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gstack man +@heading gstack + +@c man title gstack Print a stack trace of a running program + +@format +@c man begin SYNOPSIS gstack +gstack [-h | --help] [-v | --version] @var{pid} +@c man end +@end format + +@c man begin DESCRIPTION gstack +Print a stack trace of a running program with process ID @var{pid}. If the process +is multi-threaded, @command{gstack} outputs backtraces for every thread which exists +in the process. + +The script invokes @value{GDBN}, attaches to the given process ID, prints the stack trace, +and detaches from the process. + +@command{gstack} exits with non-zero status if @code{gdb} was unable to attach to +the given process ID for any reason, such as a non-existent process ID or +insufficient privileges to attach to the process. +@c man end + +@c man begin OPTIONS gstack +@table @env +@item --help +@itemx -h +List all options, with brief explanations. + +@item --version +@itemx -v +Print version information and then exit. +@end table +@c man end + +@c man begin ENVIRONMENT gstack +@table @env +@item AWK +Full file name for an Awk interpreter to use. If not set, @env{PATH} will be +searched for an @code{awk} program. + +@item GDB +Full file name for a @value{GDBN} executable to use to generate stack backtraces. +If not set, @env{PATH} will be searched for a @code{gdb} program. + +@item GDBARGS +Optional arguments to be passed to the @code{gdb} program. +@end table +@c man end + +@c man begin SEEALSO gstack +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +@noindent +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gdbinit man +@heading gdbinit + +@c man title gdbinit GDB initialization scripts + +@format +@c man begin SYNOPSIS gdbinit +@ifset SYSTEM_GDBINIT +@value{SYSTEM_GDBINIT} +@end ifset + +@ifset SYSTEM_GDBINIT_DIR +@value{SYSTEM_GDBINIT_DIR}/* +@end ifset + +~/.config/gdb/gdbinit + +~/.gdbinit + +./.gdbinit +@c man end +@end format + +@c man begin DESCRIPTION gdbinit +These files contain @value{GDBN} commands to automatically execute during +@value{GDBN} startup. The lines of contents are canned sequences of commands, +described in +@ifset man +the @value{GDBN} manual in node @code{Sequences} +-- shell command @code{info -f gdb -n Sequences}. +@end ifset +@ifclear man +@ref{Sequences}. +@end ifclear + +Please read more in +@ifset man +the @value{GDBN} manual in node @code{Startup} +-- shell command @code{info -f gdb -n Startup}. +@end ifset +@ifclear man +@ref{Startup}. +@end ifclear + +@table @env +@ifset SYSTEM_GDBINIT +@item @value{SYSTEM_GDBINIT} +@end ifset +@ifclear SYSTEM_GDBINIT +@item (not enabled with @code{--with-system-gdbinit} during compilation) +@end ifclear +System-wide initialization file. It is executed unless user specified +@value{GDBN} option @code{-nx} or @code{-n}. +See more in +@ifset man +the @value{GDBN} manual in node @code{System-wide configuration} +-- shell command @code{info -f gdb -n 'System-wide configuration'}. +@end ifset +@ifset SYSTEM_GDBINIT_DIR +@item @value{SYSTEM_GDBINIT_DIR} +@end ifset +@ifclear SYSTEM_GDBINIT_DIR +@item (not enabled with @code{--with-system-gdbinit-dir} during compilation) +@end ifclear +System-wide initialization directory. All files in this directory are +executed on startup unless user specified @value{GDBN} option @code{-nx} or +@code{-n}, as long as they have a recognized file extension. +See more in +@ifset man +the @value{GDBN} manual in node @code{System-wide configuration} +-- shell command @code{info -f gdb -n 'System-wide configuration'}. +@end ifset +@ifclear man +@ref{System-wide configuration}. +@end ifclear + +@item @file{~/.config/gdb/gdbinit} or @file{~/.gdbinit} +User initialization file. It is executed unless user specified +@value{GDBN} options @code{-nx}, @code{-n} or @code{-nh}. + +@item @file{.gdbinit} +Initialization file for current directory. It may need to be enabled with +@value{GDBN} security command @code{set auto-load local-gdbinit}. +See more in +@ifset man +the @value{GDBN} manual in node @code{Init File in the Current Directory} +-- shell command @code{info -f gdb -n 'Init File in the Current Directory'}. +@end ifset +@ifclear man +@ref{Init File in the Current Directory}. +@end ifclear +@end table +@c man end + +@c man begin SEEALSO gdbinit +@ifset man +gdb(1), @code{info -f gdb -n Startup} + +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@node gdb-add-index man +@heading gdb-add-index +@pindex gdb-add-index +@anchor{gdb-add-index} + +@c man title gdb-add-index Add index files to speed up GDB + +@c man begin SYNOPSIS gdb-add-index +gdb-add-index [-dwarf-5] @var{filename} +@c man end + +@c man begin DESCRIPTION gdb-add-index +When @value{GDBN} finds a symbol file, it scans the symbols in the +file in order to construct an internal symbol table. This lets most +@value{GDBN} operations work quickly--at the cost of a delay early on. +For large programs, this delay can be quite lengthy, so @value{GDBN} +provides a way to build an index, which speeds up startup. + +To determine whether a file contains such an index, use the command +@kbd{readelf -S filename}: the index is stored in a section named +@code{.gdb_index} (pre-DWARF 5) or @code{.debug_names} and +@code{.debug_str} (DWARF 5). Indexes can only be produced on systems +which use ELF binaries and DWARF debug information (i.e., sections +named @code{.debug_*}). + +By default @command{gdb-add-index} will add a pre-DWARF 5 +@code{.gdb_index} section to @var{filename}. With @option{-dwarf-5} +DWARF 5 sections are added instead. + +@var{filename} must be writable. + +@command{gdb-add-index} uses @value{GDBN}, @command{objcopy}, and +@command{readelf} found in the @env{PATH} environment variable. If +you want to use different versions of these programs, you can specify +them through the appropriate environment variables (see below). + +@command{gdb-add-index} exits with status 0 if it succeeds in creating +the index for @var{filename} or greater than 0 if an error occurs. + +See more in +@ifset man +the @value{GDBN} manual in node @code{Index Files} +-- shell command @kbd{info -f gdb -n "Index Files"}. +@end ifset +@ifclear man +@ref{Index Files}. +@end ifclear +@c man end + +@c man begin OPTIONS gdb-add-index +@table @env +@item -dwarf-5 +Add DWARF 5 sections instead of previous @code{.debug_index} section. + +@end table +@c man end + +@c man begin ENVIRONMENT gdb-add-index +@table @env +@item GDB +Full file name of the @code{gdb} program to use for index generation. +If not set, the @env{PATH} will be searched for a @code{gdb} program. + +@item OBJCOPY +Full file name of the @code{objcopy} program to use to copy section +information into the given file. If not set, the @env{PATH} will be searched +for a @code{objcopy} program. + +@item READELF +Full file name of the @code{readelf} program to use to inspect +properties of the given file. If not set, the @env{PATH} will be searched +for a @code{readelf} program. +@end table +@c man end + +@c man begin SEEALSO gdb-add-index +@ifset man +The full documentation for @value{GDBN} is maintained as a Texinfo manual. +If the @code{info} and @code{gdb} programs and @value{GDBN}'s Texinfo +documentation are properly installed at your site, the command + +@smallexample +info gdb +@end smallexample + +should give you access to the complete manual. + +@cite{Using GDB: A Guide to the GNU Source-Level Debugger}, +Richard M. Stallman and Roland H. Pesch, July 1991. +@end ifset +@c man end + +@include gpl.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include fdl.texi + +@node Concept Index +@unnumbered Concept Index + +@printindex cp + +@node Command and Variable Index +@unnumbered Command, Variable, and Function Index + +@printindex fn + +@tex +% I think something like @@colophon should be in texinfo. In the +% meantime: +\long\def\colophon{\hbox to0pt{}\vfill +\centerline{The body of this manual is set in} +\centerline{\fontname\tenrm,} +\centerline{with headings in {\bf\fontname\tenbf}} +\centerline{and examples in {\tt\fontname\tentt}.} +\centerline{{\it\fontname\tenit\/},} +\centerline{{\bf\fontname\tenbf}, and} +\centerline{{\sl\fontname\tensl\/}} +\centerline{are used for emphasis.}\vfill} +\page\colophon +% Blame: doc@@cygnus.com, 1991. +@end tex + +@bye diff -pruN 16.3-5/gdb/doc/gdbinit.5 16.3-5ubuntu1/gdb/doc/gdbinit.5 --- 16.3-5/gdb/doc/gdbinit.5 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdbinit.5 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,222 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDBINIT 5" +.TH GDBINIT 5 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdbinit \- GDB initialization scripts +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +~/.config/gdb/gdbinit +.PP +~/.gdbinit +.PP +\&./.gdbinit +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +These files contain \s-1GDB\s0 commands to automatically execute during +\&\s-1GDB\s0 startup. The lines of contents are canned sequences of commands, +described in +the \s-1GDB\s0 manual in node \f(CW\*(C`Sequences\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n Sequences\*(C'\fR. +.PP +Please read more in +the \s-1GDB\s0 manual in node \f(CW\*(C`Startup\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n Startup\*(C'\fR. +.ie n .IP "\fB(not enabled with \f(CB""\-\-with\-system\-gdbinit""\fB during compilation)\fR" 4 +.el .IP "\fB(not enabled with \f(CB\-\-with\-system\-gdbinit\fB during compilation)\fR" 4 +.IX Item "(not enabled with --with-system-gdbinit during compilation)" +System-wide initialization file. It is executed unless user specified +\&\s-1GDB\s0 option \f(CW\*(C`\-nx\*(C'\fR or \f(CW\*(C`\-n\*(C'\fR. +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`System\-wide configuration\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqSystem\-wide configuration\*(Aq\*(C'\fR. +.ie n .IP "\fB(not enabled with \f(CB""\-\-with\-system\-gdbinit\-dir""\fB during compilation)\fR" 4 +.el .IP "\fB(not enabled with \f(CB\-\-with\-system\-gdbinit\-dir\fB during compilation)\fR" 4 +.IX Item "(not enabled with --with-system-gdbinit-dir during compilation)" +System-wide initialization directory. All files in this directory are +executed on startup unless user specified \s-1GDB\s0 option \f(CW\*(C`\-nx\*(C'\fR or +\&\f(CW\*(C`\-n\*(C'\fR, as long as they have a recognized file extension. +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`System\-wide configuration\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqSystem\-wide configuration\*(Aq\*(C'\fR. +.IP "\fB\f(BI~/.config/gdb/gdbinit\fB or \f(BI~/.gdbinit\fB\fR" 4 +.IX Item "~/.config/gdb/gdbinit or ~/.gdbinit" +User initialization file. It is executed unless user specified +\&\s-1GDB\s0 options \f(CW\*(C`\-nx\*(C'\fR, \f(CW\*(C`\-n\*(C'\fR or \f(CW\*(C`\-nh\*(C'\fR. +.IP "\fB\f(BI.gdbinit\fB\fR" 4 +.IX Item ".gdbinit" +Initialization file for current directory. It may need to be enabled with +\&\s-1GDB\s0 security command \f(CW\*(C`set auto\-load local\-gdbinit\*(C'\fR. +See more in +the \s-1GDB\s0 manual in node \f(CW\*(C`Init File in the Current Directory\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInit File in the Current Directory\*(Aq\*(C'\fR. +.SH "OPTIONS" +.IX Header "OPTIONS" +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +\&\fBgdb\fR\|(1), \f(CW\*(C`info \-f gdb \-n Startup\*(C'\fR +.PP +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/gdbserver.1 16.3-5ubuntu1/gdb/doc/gdbserver.1 --- 16.3-5/gdb/doc/gdbserver.1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gdbserver.1 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,394 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GDBSERVER 1" +.TH GDBSERVER 1 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gdbserver \- Remote Server for the GNU Debugger +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gdbserver \fIcomm\fR \fIprog\fR [\fIargs\fR...] +.PP +gdbserver \-\-attach \fIcomm\fR \fIpid\fR +.PP +gdbserver \-\-multi \fIcomm\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +\&\fBgdbserver\fR is a program that allows you to run \s-1GDB\s0 on a different machine +than the one which is running the program being debugged. +.PP +Usage (server (target) side): +.PP +First, you need to have a copy of the program you want to debug put onto +the target system. The program can be stripped to save space if needed, as +\&\fBgdbserver\fR doesn't care about symbols. All symbol handling is taken care of by +the \s-1GDB\s0 running on the host system. +.PP +To use the server, you log on to the target system, and run the \fBgdbserver\fR +program. You must tell it (a) how to communicate with \s-1GDB,\s0 (b) the name of +your program, and (c) its arguments. The general syntax is: +.PP +.Vb 1 +\& target> gdbserver [ ...] +.Ve +.PP +For example, using a serial port, you might say: +.PP +.Vb 1 +\& target> gdbserver /dev/com1 emacs foo.txt +.Ve +.PP +This tells \fBgdbserver\fR to debug emacs with an argument of foo.txt, and +to communicate with \s-1GDB\s0 via \fI/dev/com1\fR. \fBgdbserver\fR now +waits patiently for the host \s-1GDB\s0 to communicate with it. +.PP +To use a \s-1TCP\s0 connection, you could say: +.PP +.Vb 1 +\& target> gdbserver host:2345 emacs foo.txt +.Ve +.PP +This says pretty much the same thing as the last example, except that we are +going to communicate with the \f(CW\*(C`host\*(C'\fR \s-1GDB\s0 via \s-1TCP.\s0 The \f(CW\*(C`host:2345\*(C'\fR argument means +that we are expecting to see a \s-1TCP\s0 connection from \f(CW\*(C`host\*(C'\fR to local \s-1TCP\s0 port +2345. (Currently, the \f(CW\*(C`host\*(C'\fR part is ignored.) You can choose any number you +want for the port number as long as it does not conflict with any existing \s-1TCP\s0 +ports on the target system. This same port number must be used in the host +GDBs \f(CW\*(C`target remote\*(C'\fR command, which will be described shortly. Note that if +you chose a port number that conflicts with another service, \fBgdbserver\fR will +print an error message and exit. +.PP +\&\fBgdbserver\fR can also attach to running programs. +This is accomplished via the \fB\-\-attach\fR argument. The syntax is: +.PP +.Vb 1 +\& target> gdbserver \-\-attach +.Ve +.PP +\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't +necessary to point \fBgdbserver\fR at a binary for the running process. +.PP +To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run +or process \s-1ID\s0 to attach, use the \fB\-\-multi\fR command line option. +In such case you should connect using \f(CW\*(C`target extended\-remote\*(C'\fR to start +the program you want to debug. +.PP +.Vb 1 +\& target> gdbserver \-\-multi +.Ve +.PP +Usage (host side): +.PP +You need an unstripped copy of the target program on your host system, since +\&\s-1GDB\s0 needs to examine its symbol tables and such. Start up \s-1GDB\s0 as you normally +would, with the target program as the first argument. (You may need to use the +\&\fB\-\-baud\fR option if the serial line is running at anything except 9600 baud.) +That is \f(CW\*(C`gdb TARGET\-PROG\*(C'\fR, or \f(CW\*(C`gdb \-\-baud BAUD TARGET\-PROG\*(C'\fR. After that, the only +new command you need to know about is \f(CW\*(C`target remote\*(C'\fR +(or \f(CW\*(C`target extended\-remote\*(C'\fR). Its argument is either +a device name (usually a serial device, like \fI/dev/ttyb\fR), or a \f(CW\*(C`HOST:PORT\*(C'\fR +descriptor. For example: +.PP +.Vb 1 +\& (gdb) target remote /dev/ttyb +.Ve +.PP +communicates with the server via serial line \fI/dev/ttyb\fR, and: +.PP +.Vb 1 +\& (gdb) target remote the\-target:2345 +.Ve +.PP +communicates via a \s-1TCP\s0 connection to port 2345 on host `the\-target', where +you previously started up \fBgdbserver\fR with the same port number. Note that for +\&\s-1TCP\s0 connections, you must start up \fBgdbserver\fR prior to using the `target remote' +command, otherwise you may get an error that looks something like +`Connection refused'. +.PP +\&\fBgdbserver\fR can also debug multiple inferiors at once, +described in +the \s-1GDB\s0 manual in node \f(CW\*(C`Inferiors Connections and Programs\*(C'\fR +\&\*(-- shell command \f(CW\*(C`info \-f gdb \-n \*(AqInferiors Connections and Programs\*(Aq\*(C'\fR. +In such case use the \f(CW\*(C`extended\-remote\*(C'\fR \s-1GDB\s0 command variant: +.PP +.Vb 1 +\& (gdb) target extended\-remote the\-target:2345 +.Ve +.PP +The \fBgdbserver\fR option \fB\-\-multi\fR may or may not be used in such +case. +.SH "OPTIONS" +.IX Header "OPTIONS" +There are three different modes for invoking \fBgdbserver\fR: +.IP "\(bu" 4 +Debug a specific program specified by its program name: +.Sp +.Vb 1 +\& gdbserver [...] +.Ve +.Sp +The \fIcomm\fR parameter specifies how should the server communicate +with \s-1GDB\s0; it is either a device name (to use a serial line), +a \s-1TCP\s0 port number (\f(CW\*(C`:1234\*(C'\fR), or \f(CW\*(C`\-\*(C'\fR or \f(CW\*(C`stdio\*(C'\fR to use +stdin/stdout of \f(CW\*(C`gdbserver\*(C'\fR. Specify the name of the program to +debug in \fIprog\fR. Any remaining arguments will be passed to the +program verbatim. When the program exits, \s-1GDB\s0 will close the +connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit. +.IP "\(bu" 4 +Debug a specific program by specifying the process \s-1ID\s0 of a running +program: +.Sp +.Vb 1 +\& gdbserver \-\-attach +.Ve +.Sp +The \fIcomm\fR parameter is as described above. Supply the process \s-1ID\s0 +of a running program in \fIpid\fR; \s-1GDB\s0 will do everything +else. Like with the previous mode, when the process \fIpid\fR exits, +\&\s-1GDB\s0 will close the connection, and \f(CW\*(C`gdbserver\*(C'\fR will exit. +.IP "\(bu" 4 +Multi-process mode \*(-- debug more than one program/process: +.Sp +.Vb 1 +\& gdbserver \-\-multi +.Ve +.Sp +In this mode, \s-1GDB\s0 can instruct \fBgdbserver\fR which +command(s) to run. Unlike the other 2 modes, \s-1GDB\s0 will not +close the connection when a process being debugged exits, so you can +debug several processes in the same session. +.PP +In each of the modes you may specify these options: +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +List all options, with brief explanations. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +This option causes \fBgdbserver\fR to print its version number and exit. +.IP "\fB\-\-attach\fR" 4 +.IX Item "--attach" +\&\fBgdbserver\fR will attach to a running program. The syntax is: +.Sp +.Vb 1 +\& target> gdbserver \-\-attach +.Ve +.Sp +\&\fIpid\fR is the process \s-1ID\s0 of a currently running process. It isn't +necessary to point \fBgdbserver\fR at a binary for the running process. +.IP "\fB\-\-multi\fR" 4 +.IX Item "--multi" +To start \f(CW\*(C`gdbserver\*(C'\fR without supplying an initial command to run +or process \s-1ID\s0 to attach, use this command line option. +Then you can connect using \f(CW\*(C`target extended\-remote\*(C'\fR and start +the program you want to debug. The syntax is: +.Sp +.Vb 1 +\& target> gdbserver \-\-multi +.Ve +.IP "\fB\-\-debug\fR[\fB=option1,option2,...\fR]" 4 +.IX Item "--debug[=option1,option2,...]" +Instruct \f(CW\*(C`gdbserver\*(C'\fR to display extra status information about +the debugging process. This option is intended for \f(CW\*(C`gdbserver\*(C'\fR +development and for bug reports to the developers. +.Sp +Each \fIoption\fR is the name of a component for which debugging +should be enabled. The list of possible options is \fBall\fR, +\&\fBthreads\fR, \fBevent-loop\fR, \fBremote\fR. The special +option \fBall\fR enables all components. The option list is +processed left to right, and an option can be prefixed with the +\&\f(CW\*(C`\-\*(C'\fR character to disable output for that component, so you could write: +.Sp +.Vb 1 +\& target> gdbserver \-\-debug=all,\-event\-loop +.Ve +.Sp +to turn on debug output for all components except \fBevent-loop\fR. +If no options are passed to \fB\-\-debug\fR then this is treated as +equivalent to \fB\-\-debug=threads\fR. This could change in future +releases of \f(CW\*(C`gdbserver\*(C'\fR. +.IP "\fB\-\-debug\-file=\fR\fIfilename\fR" 4 +.IX Item "--debug-file=filename" +Instruct \f(CW\*(C`gdbserver\*(C'\fR to send any debug output to the given \fIfilename\fR. +This option is intended for \f(CW\*(C`gdbserver\*(C'\fR development and for bug reports to +the developers. +.IP "\fB\-\-debug\-format=option1\fR[\fB,option2,...\fR]" 4 +.IX Item "--debug-format=option1[,option2,...]" +Instruct \f(CW\*(C`gdbserver\*(C'\fR to include extra information in each line +of debugging output. +.IP "\fB\-\-wrapper\fR" 4 +.IX Item "--wrapper" +Specify a wrapper to launch programs +for debugging. The option should be followed by the name of the +wrapper, then any command-line arguments to pass to the wrapper, then +\&\f(CW\*(C`\-\-\*(C'\fR indicating the end of the wrapper arguments. +.IP "\fB\-\-once\fR" 4 +.IX Item "--once" +By default, \fBgdbserver\fR keeps the listening \s-1TCP\s0 port open, so that +additional connections are possible. However, if you start \f(CW\*(C`gdbserver\*(C'\fR +with the \fB\-\-once\fR option, it will stop listening for any further +connection attempts after connecting to the first \s-1GDB\s0 session. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/gpl.texi 16.3-5ubuntu1/gdb/doc/gpl.texi --- 16.3-5/gdb/doc/gpl.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gpl.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,735 @@ +@ignore +@c Set file name and title for man page. +@setfilename gpl +@settitle GNU General Public License +@c man begin SEEALSO +gfdl(7), fsf-funding(7). +@c man end +@c man begin COPYRIGHT +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +@c man end +@end ignore +@node Copying +@c man begin DESCRIPTION +@appendix GNU GENERAL PUBLIC LICENSE +@c The GNU General Public License. +@center Version 3, 29 June 2007 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2007 Free Software Foundation, Inc. @url{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies of this +license document, but changing it is not allowed. +@end display + +@heading Preamble + +The GNU General Public License is a free, copyleft license for +software and other kinds of works. + +The licenses for most software and other practical works are designed +to take away your freedom to share and change the works. By contrast, +the GNU General Public License is intended to guarantee your freedom +to share and change all versions of a program---to make sure it remains +free software for all its users. We, the Free Software Foundation, +use the GNU General Public License for most of our software; it +applies also to any other work released this way by its authors. You +can apply it to your programs, too. + +When we speak of free software, we are referring to freedom, not +price. Our General Public Licenses are designed to make sure that you +have the freedom to distribute copies of free software (and charge for +them if you wish), that you receive source code or can get it if you +want it, that you can change the software or use pieces of it in new +free programs, and that you know you can do these things. + +To protect your rights, we need to prevent others from denying you +these rights or asking you to surrender the rights. Therefore, you +have certain responsibilities if you distribute copies of the +software, or if you modify it: responsibilities to respect the freedom +of others. + +For example, if you distribute copies of such a program, whether +gratis or for a fee, you must pass on to the recipients the same +freedoms that you received. You must make sure that they, too, +receive or can get the source code. And you must show them these +terms so they know their rights. + +Developers that use the GNU GPL protect your rights with two steps: +(1) assert copyright on the software, and (2) offer you this License +giving you legal permission to copy, distribute and/or modify it. + +For the developers' and authors' protection, the GPL clearly explains +that there is no warranty for this free software. For both users' and +authors' sake, the GPL requires that modified versions be marked as +changed, so that their problems will not be attributed erroneously to +authors of previous versions. + +Some devices are designed to deny users access to install or run +modified versions of the software inside them, although the +manufacturer can do so. This is fundamentally incompatible with the +aim of protecting users' freedom to change the software. The +systematic pattern of such abuse occurs in the area of products for +individuals to use, which is precisely where it is most unacceptable. +Therefore, we have designed this version of the GPL to prohibit the +practice for those products. If such problems arise substantially in +other domains, we stand ready to extend this provision to those +domains in future versions of the GPL, as needed to protect the +freedom of users. + +Finally, every program is threatened constantly by software patents. +States should not allow patents to restrict development and use of +software on general-purpose computers, but in those that do, we wish +to avoid the special danger that patents applied to a free program +could make it effectively proprietary. To prevent this, the GPL +assures that patents cannot be used to render the program non-free. + +The precise terms and conditions for copying, distribution and +modification follow. + +@heading TERMS AND CONDITIONS + +@enumerate 0 +@item Definitions. + +``This License'' refers to version 3 of the GNU General Public License. + +``Copyright'' also means copyright-like laws that apply to other kinds +of works, such as semiconductor masks. + +``The Program'' refers to any copyrightable work licensed under this +License. Each licensee is addressed as ``you''. ``Licensees'' and +``recipients'' may be individuals or organizations. + +To ``modify'' a work means to copy from or adapt all or part of the work +in a fashion requiring copyright permission, other than the making of +an exact copy. The resulting work is called a ``modified version'' of +the earlier work or a work ``based on'' the earlier work. + +A ``covered work'' means either the unmodified Program or a work based +on the Program. + +To ``propagate'' a work means to do anything with it that, without +permission, would make you directly or secondarily liable for +infringement under applicable copyright law, except executing it on a +computer or modifying a private copy. Propagation includes copying, +distribution (with or without modification), making available to the +public, and in some countries other activities as well. + +To ``convey'' a work means any kind of propagation that enables other +parties to make or receive copies. Mere interaction with a user +through a computer network, with no transfer of a copy, is not +conveying. + +An interactive user interface displays ``Appropriate Legal Notices'' to +the extent that it includes a convenient and prominently visible +feature that (1) displays an appropriate copyright notice, and (2) +tells the user that there is no warranty for the work (except to the +extent that warranties are provided), that licensees may convey the +work under this License, and how to view a copy of this License. If +the interface presents a list of user commands or options, such as a +menu, a prominent item in the list meets this criterion. + +@item Source Code. + +The ``source code'' for a work means the preferred form of the work for +making modifications to it. ``Object code'' means any non-source form +of a work. + +A ``Standard Interface'' means an interface that either is an official +standard defined by a recognized standards body, or, in the case of +interfaces specified for a particular programming language, one that +is widely used among developers working in that language. + +The ``System Libraries'' of an executable work include anything, other +than the work as a whole, that (a) is included in the normal form of +packaging a Major Component, but which is not part of that Major +Component, and (b) serves only to enable use of the work with that +Major Component, or to implement a Standard Interface for which an +implementation is available to the public in source code form. A +``Major Component'', in this context, means a major essential component +(kernel, window system, and so on) of the specific operating system +(if any) on which the executable work runs, or a compiler used to +produce the work, or an object code interpreter used to run it. + +The ``Corresponding Source'' for a work in object code form means all +the source code needed to generate, install, and (for an executable +work) run the object code and to modify the work, including scripts to +control those activities. However, it does not include the work's +System Libraries, or general-purpose tools or generally available free +programs which are used unmodified in performing those activities but +which are not part of the work. For example, Corresponding Source +includes interface definition files associated with source files for +the work, and the source code for shared libraries and dynamically +linked subprograms that the work is specifically designed to require, +such as by intimate data communication or control flow between those +subprograms and other parts of the work. + +The Corresponding Source need not include anything that users can +regenerate automatically from other parts of the Corresponding Source. + +The Corresponding Source for a work in source code form is that same +work. + +@item Basic Permissions. + +All rights granted under this License are granted for the term of +copyright on the Program, and are irrevocable provided the stated +conditions are met. This License explicitly affirms your unlimited +permission to run the unmodified Program. The output from running a +covered work is covered by this License only if the output, given its +content, constitutes a covered work. This License acknowledges your +rights of fair use or other equivalent, as provided by copyright law. + +You may make, run and propagate covered works that you do not convey, +without conditions so long as your license otherwise remains in force. +You may convey covered works to others for the sole purpose of having +them make modifications exclusively for you, or provide you with +facilities for running those works, provided that you comply with the +terms of this License in conveying all material for which you do not +control copyright. Those thus making or running the covered works for +you must do so exclusively on your behalf, under your direction and +control, on terms that prohibit them from making any copies of your +copyrighted material outside their relationship with you. + +Conveying under any other circumstances is permitted solely under the +conditions stated below. Sublicensing is not allowed; section 10 +makes it unnecessary. + +@item Protecting Users' Legal Rights From Anti-Circumvention Law. + +No covered work shall be deemed part of an effective technological +measure under any applicable law fulfilling obligations under article +11 of the WIPO copyright treaty adopted on 20 December 1996, or +similar laws prohibiting or restricting circumvention of such +measures. + +When you convey a covered work, you waive any legal power to forbid +circumvention of technological measures to the extent such +circumvention is effected by exercising rights under this License with +respect to the covered work, and you disclaim any intention to limit +operation or modification of the work as a means of enforcing, against +the work's users, your or third parties' legal rights to forbid +circumvention of technological measures. + +@item Conveying Verbatim Copies. + +You may convey verbatim copies of the Program's source code as you +receive it, in any medium, provided that you conspicuously and +appropriately publish on each copy an appropriate copyright notice; +keep intact all notices stating that this License and any +non-permissive terms added in accord with section 7 apply to the code; +keep intact all notices of the absence of any warranty; and give all +recipients a copy of this License along with the Program. + +You may charge any price or no price for each copy that you convey, +and you may offer support or warranty protection for a fee. + +@item Conveying Modified Source Versions. + +You may convey a work based on the Program, or the modifications to +produce it from the Program, in the form of source code under the +terms of section 4, provided that you also meet all of these +conditions: + +@enumerate a +@item +The work must carry prominent notices stating that you modified it, +and giving a relevant date. + +@item +The work must carry prominent notices stating that it is released +under this License and any conditions added under section 7. This +requirement modifies the requirement in section 4 to ``keep intact all +notices''. + +@item +You must license the entire work, as a whole, under this License to +anyone who comes into possession of a copy. This License will +therefore apply, along with any applicable section 7 additional terms, +to the whole of the work, and all its parts, regardless of how they +are packaged. This License gives no permission to license the work in +any other way, but it does not invalidate such permission if you have +separately received it. + +@item +If the work has interactive user interfaces, each must display +Appropriate Legal Notices; however, if the Program has interactive +interfaces that do not display Appropriate Legal Notices, your work +need not make them do so. +@end enumerate + +A compilation of a covered work with other separate and independent +works, which are not by their nature extensions of the covered work, +and which are not combined with it such as to form a larger program, +in or on a volume of a storage or distribution medium, is called an +``aggregate'' if the compilation and its resulting copyright are not +used to limit the access or legal rights of the compilation's users +beyond what the individual works permit. Inclusion of a covered work +in an aggregate does not cause this License to apply to the other +parts of the aggregate. + +@item Conveying Non-Source Forms. + +You may convey a covered work in object code form under the terms of +sections 4 and 5, provided that you also convey the machine-readable +Corresponding Source under the terms of this License, in one of these +ways: + +@enumerate a +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by the +Corresponding Source fixed on a durable physical medium customarily +used for software interchange. + +@item +Convey the object code in, or embodied in, a physical product +(including a physical distribution medium), accompanied by a written +offer, valid for at least three years and valid for as long as you +offer spare parts or customer support for that product model, to give +anyone who possesses the object code either (1) a copy of the +Corresponding Source for all the software in the product that is +covered by this License, on a durable physical medium customarily used +for software interchange, for a price no more than your reasonable +cost of physically performing this conveying of source, or (2) access +to copy the Corresponding Source from a network server at no charge. + +@item +Convey individual copies of the object code with a copy of the written +offer to provide the Corresponding Source. This alternative is +allowed only occasionally and noncommercially, and only if you +received the object code with such an offer, in accord with subsection +6b. + +@item +Convey the object code by offering access from a designated place +(gratis or for a charge), and offer equivalent access to the +Corresponding Source in the same way through the same place at no +further charge. You need not require recipients to copy the +Corresponding Source along with the object code. If the place to copy +the object code is a network server, the Corresponding Source may be +on a different server (operated by you or a third party) that supports +equivalent copying facilities, provided you maintain clear directions +next to the object code saying where to find the Corresponding Source. +Regardless of what server hosts the Corresponding Source, you remain +obligated to ensure that it is available for as long as needed to +satisfy these requirements. + +@item +Convey the object code using peer-to-peer transmission, provided you +inform other peers where the object code and Corresponding Source of +the work are being offered to the general public at no charge under +subsection 6d. + +@end enumerate + +A separable portion of the object code, whose source code is excluded +from the Corresponding Source as a System Library, need not be +included in conveying the object code work. + +A ``User Product'' is either (1) a ``consumer product'', which means any +tangible personal property which is normally used for personal, +family, or household purposes, or (2) anything designed or sold for +incorporation into a dwelling. In determining whether a product is a +consumer product, doubtful cases shall be resolved in favor of +coverage. For a particular product received by a particular user, +``normally used'' refers to a typical or common use of that class of +product, regardless of the status of the particular user or of the way +in which the particular user actually uses, or expects or is expected +to use, the product. A product is a consumer product regardless of +whether the product has substantial commercial, industrial or +non-consumer uses, unless such uses represent the only significant +mode of use of the product. + +``Installation Information'' for a User Product means any methods, +procedures, authorization keys, or other information required to +install and execute modified versions of a covered work in that User +Product from a modified version of its Corresponding Source. The +information must suffice to ensure that the continued functioning of +the modified object code is in no case prevented or interfered with +solely because modification has been made. + +If you convey an object code work under this section in, or with, or +specifically for use in, a User Product, and the conveying occurs as +part of a transaction in which the right of possession and use of the +User Product is transferred to the recipient in perpetuity or for a +fixed term (regardless of how the transaction is characterized), the +Corresponding Source conveyed under this section must be accompanied +by the Installation Information. But this requirement does not apply +if neither you nor any third party retains the ability to install +modified object code on the User Product (for example, the work has +been installed in ROM). + +The requirement to provide Installation Information does not include a +requirement to continue to provide support service, warranty, or +updates for a work that has been modified or installed by the +recipient, or for the User Product in which it has been modified or +installed. Access to a network may be denied when the modification +itself materially and adversely affects the operation of the network +or violates the rules and protocols for communication across the +network. + +Corresponding Source conveyed, and Installation Information provided, +in accord with this section must be in a format that is publicly +documented (and with an implementation available to the public in +source code form), and must require no special password or key for +unpacking, reading or copying. + +@item Additional Terms. + +``Additional permissions'' are terms that supplement the terms of this +License by making exceptions from one or more of its conditions. +Additional permissions that are applicable to the entire Program shall +be treated as though they were included in this License, to the extent +that they are valid under applicable law. If additional permissions +apply only to part of the Program, that part may be used separately +under those permissions, but the entire Program remains governed by +this License without regard to the additional permissions. + +When you convey a copy of a covered work, you may at your option +remove any additional permissions from that copy, or from any part of +it. (Additional permissions may be written to require their own +removal in certain cases when you modify the work.) You may place +additional permissions on material, added by you to a covered work, +for which you have or can give appropriate copyright permission. + +Notwithstanding any other provision of this License, for material you +add to a covered work, you may (if authorized by the copyright holders +of that material) supplement the terms of this License with terms: + +@enumerate a +@item +Disclaiming warranty or limiting liability differently from the terms +of sections 15 and 16 of this License; or + +@item +Requiring preservation of specified reasonable legal notices or author +attributions in that material or in the Appropriate Legal Notices +displayed by works containing it; or + +@item +Prohibiting misrepresentation of the origin of that material, or +requiring that modified versions of such material be marked in +reasonable ways as different from the original version; or + +@item +Limiting the use for publicity purposes of names of licensors or +authors of the material; or + +@item +Declining to grant rights under trademark law for use of some trade +names, trademarks, or service marks; or + +@item +Requiring indemnification of licensors and authors of that material by +anyone who conveys the material (or modified versions of it) with +contractual assumptions of liability to the recipient, for any +liability that these contractual assumptions directly impose on those +licensors and authors. +@end enumerate + +All other non-permissive additional terms are considered ``further +restrictions'' within the meaning of section 10. If the Program as you +received it, or any part of it, contains a notice stating that it is +governed by this License along with a term that is a further +restriction, you may remove that term. If a license document contains +a further restriction but permits relicensing or conveying under this +License, you may add to a covered work material governed by the terms +of that license document, provided that the further restriction does +not survive such relicensing or conveying. + +If you add terms to a covered work in accord with this section, you +must place, in the relevant source files, a statement of the +additional terms that apply to those files, or a notice indicating +where to find the applicable terms. + +Additional terms, permissive or non-permissive, may be stated in the +form of a separately written license, or stated as exceptions; the +above requirements apply either way. + +@item Termination. + +You may not propagate or modify a covered work except as expressly +provided under this License. Any attempt otherwise to propagate or +modify it is void, and will automatically terminate your rights under +this License (including any patent licenses granted under the third +paragraph of section 11). + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, you do not qualify to receive new licenses for the same +material under section 10. + +@item Acceptance Not Required for Having Copies. + +You are not required to accept this License in order to receive or run +a copy of the Program. Ancillary propagation of a covered work +occurring solely as a consequence of using peer-to-peer transmission +to receive a copy likewise does not require acceptance. However, +nothing other than this License grants you permission to propagate or +modify any covered work. These actions infringe copyright if you do +not accept this License. Therefore, by modifying or propagating a +covered work, you indicate your acceptance of this License to do so. + +@item Automatic Licensing of Downstream Recipients. + +Each time you convey a covered work, the recipient automatically +receives a license from the original licensors, to run, modify and +propagate that work, subject to this License. You are not responsible +for enforcing compliance by third parties with this License. + +An ``entity transaction'' is a transaction transferring control of an +organization, or substantially all assets of one, or subdividing an +organization, or merging organizations. If propagation of a covered +work results from an entity transaction, each party to that +transaction who receives a copy of the work also receives whatever +licenses to the work the party's predecessor in interest had or could +give under the previous paragraph, plus a right to possession of the +Corresponding Source of the work from the predecessor in interest, if +the predecessor has it or can get it with reasonable efforts. + +You may not impose any further restrictions on the exercise of the +rights granted or affirmed under this License. For example, you may +not impose a license fee, royalty, or other charge for exercise of +rights granted under this License, and you may not initiate litigation +(including a cross-claim or counterclaim in a lawsuit) alleging that +any patent claim is infringed by making, using, selling, offering for +sale, or importing the Program or any portion of it. + +@item Patents. + +A ``contributor'' is a copyright holder who authorizes use under this +License of the Program or a work on which the Program is based. The +work thus licensed is called the contributor's ``contributor version''. + +A contributor's ``essential patent claims'' are all patent claims owned +or controlled by the contributor, whether already acquired or +hereafter acquired, that would be infringed by some manner, permitted +by this License, of making, using, or selling its contributor version, +but do not include claims that would be infringed only as a +consequence of further modification of the contributor version. For +purposes of this definition, ``control'' includes the right to grant +patent sublicenses in a manner consistent with the requirements of +this License. + +Each contributor grants you a non-exclusive, worldwide, royalty-free +patent license under the contributor's essential patent claims, to +make, use, sell, offer for sale, import and otherwise run, modify and +propagate the contents of its contributor version. + +In the following three paragraphs, a ``patent license'' is any express +agreement or commitment, however denominated, not to enforce a patent +(such as an express permission to practice a patent or covenant not to +sue for patent infringement). To ``grant'' such a patent license to a +party means to make such an agreement or commitment not to enforce a +patent against the party. + +If you convey a covered work, knowingly relying on a patent license, +and the Corresponding Source of the work is not available for anyone +to copy, free of charge and under the terms of this License, through a +publicly available network server or other readily accessible means, +then you must either (1) cause the Corresponding Source to be so +available, or (2) arrange to deprive yourself of the benefit of the +patent license for this particular work, or (3) arrange, in a manner +consistent with the requirements of this License, to extend the patent +license to downstream recipients. ``Knowingly relying'' means you have +actual knowledge that, but for the patent license, your conveying the +covered work in a country, or your recipient's use of the covered work +in a country, would infringe one or more identifiable patents in that +country that you have reason to believe are valid. + +If, pursuant to or in connection with a single transaction or +arrangement, you convey, or propagate by procuring conveyance of, a +covered work, and grant a patent license to some of the parties +receiving the covered work authorizing them to use, propagate, modify +or convey a specific copy of the covered work, then the patent license +you grant is automatically extended to all recipients of the covered +work and works based on it. + +A patent license is ``discriminatory'' if it does not include within the +scope of its coverage, prohibits the exercise of, or is conditioned on +the non-exercise of one or more of the rights that are specifically +granted under this License. You may not convey a covered work if you +are a party to an arrangement with a third party that is in the +business of distributing software, under which you make payment to the +third party based on the extent of your activity of conveying the +work, and under which the third party grants, to any of the parties +who would receive the covered work from you, a discriminatory patent +license (a) in connection with copies of the covered work conveyed by +you (or copies made from those copies), or (b) primarily for and in +connection with specific products or compilations that contain the +covered work, unless you entered into that arrangement, or that patent +license was granted, prior to 28 March 2007. + +Nothing in this License shall be construed as excluding or limiting +any implied license or other defenses to infringement that may +otherwise be available to you under applicable patent law. + +@item No Surrender of Others' Freedom. + +If conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot convey +a covered work so as to satisfy simultaneously your obligations under +this License and any other pertinent obligations, then as a +consequence you may not convey it at all. For example, if you agree +to terms that obligate you to collect a royalty for further conveying +from those to whom you convey the Program, the only way you could +satisfy both those terms and this License would be to refrain entirely +from conveying the Program. + +@item Use with the GNU Affero General Public License. + +Notwithstanding any other provision of this License, you have +permission to link or combine any covered work with a work licensed +under version 3 of the GNU Affero General Public License into a single +combined work, and to convey the resulting work. The terms of this +License will continue to apply to the part which is the covered work, +but the special requirements of the GNU Affero General Public License, +section 13, concerning interaction through a network will apply to the +combination as such. + +@item Revised Versions of this License. + +The Free Software Foundation may publish revised and/or new versions +of the GNU General Public License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Program +specifies that a certain numbered version of the GNU General Public +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that numbered version or +of any later version published by the Free Software Foundation. If +the Program does not specify a version number of the GNU General +Public License, you may choose any version ever published by the Free +Software Foundation. + +If the Program specifies that a proxy can decide which future versions +of the GNU General Public License can be used, that proxy's public +statement of acceptance of a version permanently authorizes you to +choose that version for the Program. + +Later license versions may give you additional or different +permissions. However, no additional obligations are imposed on any +author or copyright holder as a result of your choosing to follow a +later version. + +@item Disclaimer of Warranty. + +THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY +APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT +HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM ``AS IS'' WITHOUT +WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT +LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR +A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND +PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE +DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR +CORRECTION. + +@item Limitation of Liability. + +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING +WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR +CONVEYS THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, +INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES +ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT +NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR +LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM +TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER +PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +@item Interpretation of Sections 15 and 16. + +If the disclaimer of warranty and limitation of liability provided +above cannot be given local legal effect according to their terms, +reviewing courts shall apply local law that most closely approximates +an absolute waiver of all civil liability in connection with the +Program, unless a warranty or assumption of liability accompanies a +copy of the Program in return for a fee. + +@end enumerate + +@heading END OF TERMS AND CONDITIONS + +@heading How to Apply These Terms to Your New Programs + +If you develop a new program, and you want it to be of the greatest +possible use to the public, the best way to achieve this is to make it +free software which everyone can redistribute and change under these +terms. + +To do so, attach the following notices to the program. It is safest +to attach them to the start of each source file to most effectively +state the exclusion of warranty; and each file should have at least +the ``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the program's name and a brief idea of what it does.} +Copyright (C) @var{year} @var{name of author} + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation, either version 3 of the License, or (at +your option) any later version. + +This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with this program. If not, see @url{http://www.gnu.org/licenses/}. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +If the program does terminal interaction, make it output a short +notice like this when it starts in an interactive mode: + +@smallexample +@var{program} Copyright (C) @var{year} @var{name of author} +This program comes with ABSOLUTELY NO WARRANTY; for details type @samp{show w}. +This is free software, and you are welcome to redistribute it +under certain conditions; type @samp{show c} for details. +@end smallexample + +The hypothetical commands @samp{show w} and @samp{show c} should show +the appropriate parts of the General Public License. Of course, your +program's commands might be different; for a GUI interface, you would +use an ``about box''. + +You should also get your employer (if you work as a programmer) or school, +if any, to sign a ``copyright disclaimer'' for the program, if necessary. +For more information on this, and how to apply and follow the GNU GPL, see +@url{http://www.gnu.org/licenses/}. + +The GNU General Public License does not permit incorporating your +program into proprietary programs. If your program is a subroutine +library, you may consider it more useful to permit linking proprietary +applications with the library. If this is what you want to do, use +the GNU Lesser General Public License instead of this License. But +first, please read @url{http://www.gnu.org/philosophy/why-not-lgpl.html}. +@c man end diff -pruN 16.3-5/gdb/doc/gstack.1 16.3-5ubuntu1/gdb/doc/gstack.1 --- 16.3-5/gdb/doc/gstack.1 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/gstack.1 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,214 @@ +.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.42) +.\" +.\" Standard preamble: +.\" ======================================================================== +.de Sp \" Vertical space (when we can't use .PP) +.if t .sp .5v +.if n .sp +.. +.de Vb \" Begin verbatim text +.ft CW +.nf +.ne \\$1 +.. +.de Ve \" End verbatim text +.ft R +.fi +.. +.\" Set up some character translations and predefined strings. \*(-- will +.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left +.\" double quote, and \*(R" will give a right double quote. \*(C+ will +.\" give a nicer C++. Capital omega is used to do unbreakable dashes and +.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, +.\" nothing in troff, for use with C<>. +.tr \(*W- +.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' +.ie n \{\ +. ds -- \(*W- +. ds PI pi +. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch +. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch +. ds L" "" +. ds R" "" +. ds C` "" +. ds C' "" +'br\} +.el\{\ +. ds -- \|\(em\| +. ds PI \(*p +. ds L" `` +. ds R" '' +. ds C` +. ds C' +'br\} +.\" +.\" Escape single quotes in literal strings from groff's Unicode transform. +.ie \n(.g .ds Aq \(aq +.el .ds Aq ' +.\" +.\" If the F register is >0, we'll generate index entries on stderr for +.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index +.\" entries marked with X<> in POD. Of course, you'll have to process the +.\" output yourself in some meaningful fashion. +.\" +.\" Avoid warning from groff about undefined register 'F'. +.de IX +.. +.nr rF 0 +.if \n(.g .if rF .nr rF 1 +.if (\n(rF:(\n(.g==0)) \{\ +. if \nF \{\ +. de IX +. tm Index:\\$1\t\\n%\t"\\$2" +.. +. if !\nF==2 \{\ +. nr % 0 +. nr F 2 +. \} +. \} +.\} +.rr rF +.\" +.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). +.\" Fear. Run. Save yourself. No user-serviceable parts. +. \" fudge factors for nroff and troff +.if n \{\ +. ds #H 0 +. ds #V .8m +. ds #F .3m +. ds #[ \f1 +. ds #] \fP +.\} +.if t \{\ +. ds #H ((1u-(\\\\n(.fu%2u))*.13m) +. ds #V .6m +. ds #F 0 +. ds #[ \& +. ds #] \& +.\} +. \" simple accents for nroff and troff +.if n \{\ +. ds ' \& +. ds ` \& +. ds ^ \& +. ds , \& +. ds ~ ~ +. ds / +.\} +.if t \{\ +. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" +. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' +. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' +. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' +. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' +. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' +.\} +. \" troff and (daisy-wheel) nroff accents +.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' +.ds 8 \h'\*(#H'\(*b\h'-\*(#H' +.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] +.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' +.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' +.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] +.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] +.ds ae a\h'-(\w'a'u*4/10)'e +.ds Ae A\h'-(\w'A'u*4/10)'E +. \" corrections for vroff +.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' +.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' +. \" for low resolution devices (crt and lpr) +.if \n(.H>23 .if \n(.V>19 \ +\{\ +. ds : e +. ds 8 ss +. ds o a +. ds d- d\h'-1'\(ga +. ds D- D\h'-1'\(hy +. ds th \o'bp' +. ds Th \o'LP' +. ds ae ae +. ds Ae AE +.\} +.rm #[ #] #H #V #F C +.\" ======================================================================== +.\" +.IX Title "GSTACK 1" +.TH GSTACK 1 "2025-04-20" "gdb-16.3" "GNU Development Tools" +.\" For nroff, turn off justification. Always turn off hyphenation; it makes +.\" way too many mistakes in technical documents. +.if n .ad l +.nh +.SH "NAME" +gstack \- Print a stack trace of a running program +.SH "SYNOPSIS" +.IX Header "SYNOPSIS" +gstack [\-h | \-\-help] [\-v | \-\-version] \fIpid\fR +.SH "DESCRIPTION" +.IX Header "DESCRIPTION" +Print a stack trace of a running program with process \s-1ID\s0 \fIpid\fR. If the process +is multi-threaded, \fBgstack\fR outputs backtraces for every thread which exists +in the process. +.PP +The script invokes \s-1GDB,\s0 attaches to the given process \s-1ID,\s0 prints the stack trace, +and detaches from the process. +.PP +\&\fBgstack\fR exits with non-zero status if \f(CW\*(C`gdb\*(C'\fR was unable to attach to +the given process \s-1ID\s0 for any reason, such as a non-existent process \s-1ID\s0 or +insufficient privileges to attach to the process. +.SH "OPTIONS" +.IX Header "OPTIONS" +.IP "\fB\-\-help\fR" 4 +.IX Item "--help" +.PD 0 +.IP "\fB\-h\fR" 4 +.IX Item "-h" +.PD +List all options, with brief explanations. +.IP "\fB\-\-version\fR" 4 +.IX Item "--version" +.PD 0 +.IP "\fB\-v\fR" 4 +.IX Item "-v" +.PD +Print version information and then exit. +.SH "ENVIRONMENT" +.IX Header "ENVIRONMENT" +.IP "\fB\s-1AWK\s0\fR" 4 +.IX Item "AWK" +Full file name for an Awk interpreter to use. If not set, \fB\s-1PATH\s0\fR will be +searched for an \f(CW\*(C`awk\*(C'\fR program. +.IP "\fB\s-1GDB\s0\fR" 4 +.IX Item "GDB" +Full file name for a \s-1GDB\s0 executable to use to generate stack backtraces. +If not set, \fB\s-1PATH\s0\fR will be searched for a \f(CW\*(C`gdb\*(C'\fR program. +.IP "\fB\s-1GDBARGS\s0\fR" 4 +.IX Item "GDBARGS" +Optional arguments to be passed to the \f(CW\*(C`gdb\*(C'\fR program. +.SH "SEE ALSO" +.IX Header "SEE ALSO" +The full documentation for \s-1GDB\s0 is maintained as a Texinfo manual. +If the \f(CW\*(C`info\*(C'\fR and \f(CW\*(C`gdb\*(C'\fR programs and \s-1GDB\s0's Texinfo +documentation are properly installed at your site, the command +.PP +.Vb 1 +\& info gdb +.Ve +.PP +should give you access to the complete manual. +.PP +\&\fIUsing \s-1GDB: A\s0 Guide to the \s-1GNU\s0 Source-Level Debugger\fR, +Richard M. Stallman and Roland H. Pesch, July 1991. +.SH "COPYRIGHT" +.IX Header "COPYRIGHT" +Copyright (c) 1988\-2024 Free Software Foundation, Inc. +.PP +Permission is granted to copy, distribute and/or modify this document +under the terms of the \s-1GNU\s0 Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with the +Invariant Sections being \*(L"Free Software\*(R" and \*(L"Free Software Needs +Free Documentation\*(R", with the Front-Cover Texts being \*(L"A \s-1GNU\s0 Manual,\*(R" +and with the Back-Cover Texts as in (a) below. +.PP +(a) The \s-1FSF\s0's Back-Cover Text is: \*(L"You are free to copy and modify +this \s-1GNU\s0 Manual. Buying copies from \s-1GNU\s0 Press supports the \s-1FSF\s0 in +developing \s-1GNU\s0 and promoting software freedom.\*(R" diff -pruN 16.3-5/gdb/doc/guile.texi 16.3-5ubuntu1/gdb/doc/guile.texi --- 16.3-5/gdb/doc/guile.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/guile.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,3963 @@ +@c Copyright (C) 2008--2024 Free Software Foundation, Inc. +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with the +@c Invariant Sections being ``Free Software'' and ``Free Software Needs +@c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' +@c and with the Back-Cover Texts as in (a) below. +@c +@c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify +@c this GNU Manual. Buying copies from GNU Press supports the FSF in +@c developing GNU and promoting software freedom.'' +@node Guile +@section Extending @value{GDBN} using Guile +@cindex guile scripting +@cindex scripting with guile + +You can extend @value{GDBN} using the @uref{http://www.gnu.org/software/guile/, +Guile implementation of the Scheme programming language}. +This feature is available only if @value{GDBN} was configured using +@option{--with-guile}. + +@menu +* Guile Introduction:: Introduction to Guile scripting in @value{GDBN} +* Guile Commands:: Accessing Guile from @value{GDBN} +* Guile API:: Accessing @value{GDBN} from Guile +* Guile Auto-loading:: Automatically loading Guile code +* Guile Modules:: Guile modules provided by @value{GDBN} +@end menu + +@node Guile Introduction +@subsection Guile Introduction + +Guile is an implementation of the Scheme programming language +and is the GNU project's official extension language. + +Guile support in @value{GDBN} follows the Python support in @value{GDBN} +reasonably closely, so concepts there should carry over. +However, some things are done differently where it makes sense. + +@value{GDBN} requires Guile version 3.0, 2.2, or 2.0. + +@cindex guile scripts directory +Guile scripts used by @value{GDBN} should be installed in +@file{@var{data-directory}/guile}, where @var{data-directory} is +the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). +This directory, known as the @dfn{guile directory}, +is automatically added to the Guile Search Path in order to allow +the Guile interpreter to locate all scripts installed at this location. + +@node Guile Commands +@subsection Guile Commands +@cindex guile commands +@cindex commands to access guile + +@value{GDBN} provides two commands for accessing the Guile interpreter: + +@table @code +@kindex guile-repl +@kindex gr +@item guile-repl +@itemx gr +The @code{guile-repl} command can be used to start an interactive +Guile prompt or @dfn{repl}. To return to @value{GDBN}, +type @kbd{,q} or the @code{EOF} character (e.g., @kbd{Ctrl-D} on +an empty prompt). These commands do not take any arguments. + +@kindex guile +@kindex gu +@item guile @r{[}@var{scheme-expression}@r{]} +@itemx gu @r{[}@var{scheme-expression}@r{]} +The @code{guile} command can be used to evaluate a Scheme expression. + +If given an argument, @value{GDBN} will pass the argument to the Guile +interpreter for evaluation. + +@smallexample +(@value{GDBP}) guile (display (+ 20 3)) (newline) +23 +@end smallexample + +The result of the Scheme expression is displayed using normal Guile rules. + +@smallexample +(@value{GDBP}) guile (+ 20 3) +23 +@end smallexample + +If you do not provide an argument to @code{guile}, it will act as a +multi-line command, like @code{define}. In this case, the Guile +script is made up of subsequent command lines, given after the +@code{guile} command. This command list is terminated using a line +containing @code{end}. For example: + +@smallexample +(@value{GDBP}) guile +>(display 23) +>(newline) +>end +23 +@end smallexample +@end table + +It is also possible to execute a Guile script from the @value{GDBN} +interpreter: + +@table @code +@item source @file{script-name} +The script name must end with @samp{.scm} and @value{GDBN} must be configured +to recognize the script language based on filename extension using +the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}. + +@item guile (load "script-name") +This method uses the @code{load} Guile function. +It takes a string argument that is the name of the script to load. +See the Guile documentation for a description of this function. +(@pxref{Loading,,, guile, GNU Guile Reference Manual}). +@end table + +@node Guile API +@subsection Guile API +@cindex guile api +@cindex programming in guile + +You can get quick online help for @value{GDBN}'s Guile API by issuing +the command @w{@kbd{help guile}}, or by issuing the command @kbd{,help} +from an interactive Guile session. Furthermore, most Guile procedures +provided by @value{GDBN} have doc strings which can be obtained with +@kbd{,describe @var{procedure-name}} or @kbd{,d @var{procedure-name}} +from the Guile interactive prompt. + +@menu +* Basic Guile:: Basic Guile Functions +* Guile Configuration:: Guile configuration variables +* GDB Scheme Data Types:: Scheme representations of GDB objects +* Guile Exception Handling:: How Guile exceptions are translated +* Values From Inferior In Guile:: Guile representation of values +* Arithmetic In Guile:: Arithmetic in Guile +* Types In Guile:: Guile representation of types +* Guile Pretty Printing API:: Pretty-printing values with Guile +* Selecting Guile Pretty-Printers:: How GDB chooses a pretty-printer +* Writing a Guile Pretty-Printer:: Writing a pretty-printer +* Commands In Guile:: Implementing new commands in Guile +* Parameters In Guile:: Adding new @value{GDBN} parameters +* Progspaces In Guile:: Program spaces +* Objfiles In Guile:: Object files in Guile +* Frames In Guile:: Accessing inferior stack frames from Guile +* Blocks In Guile:: Accessing blocks from Guile +* Symbols In Guile:: Guile representation of symbols +* Symbol Tables In Guile:: Guile representation of symbol tables +* Breakpoints In Guile:: Manipulating breakpoints using Guile +* Lazy Strings In Guile:: Guile representation of lazy strings +* Architectures In Guile:: Guile representation of architectures +* Disassembly In Guile:: Disassembling instructions from Guile +* I/O Ports in Guile:: GDB I/O ports +* Memory Ports in Guile:: Accessing memory through ports and bytevectors +* Iterators In Guile:: Basic iterator support +@end menu + +@node Basic Guile +@subsubsection Basic Guile + +@cindex guile stdout +@cindex guile pagination +At startup, @value{GDBN} overrides Guile's @code{current-output-port} and +@code{current-error-port} to print using @value{GDBN}'s output-paging streams. +A Guile program which outputs to one of these streams may have its +output interrupted by the user (@pxref{Screen Size}). In this +situation, a Guile @code{signal} exception is thrown with value @code{SIGINT}. + +Guile's history mechanism uses the same naming as @value{GDBN}'s, +namely the user of dollar-variables (e.g., $1, $2, etc.). +The results of evaluations in Guile and in GDB are counted separately, +@code{$1} in Guile is not the same value as @code{$1} in @value{GDBN}. + +@value{GDBN} is not thread-safe. If your Guile program uses multiple +threads, you must be careful to only call @value{GDBN}-specific +functions in the @value{GDBN} thread. + +Some care must be taken when writing Guile code to run in +@value{GDBN}. Two things are worth noting in particular: + +@itemize @bullet +@item +@value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}. +Guile code must not override these, or even change the options using +@code{sigaction}. If your program changes the handling of these +signals, @value{GDBN} will most likely stop working correctly. Note +that it is unfortunately common for GUI toolkits to install a +@code{SIGCHLD} handler. + +@item +@value{GDBN} takes care to mark its internal file descriptors as +close-on-exec. However, this cannot be done in a thread-safe way on +all platforms. Your Guile programs should be aware of this and +should both create new file descriptors with the close-on-exec flag +set and arrange to close unneeded file descriptors before starting a +child process. +@end itemize + +@cindex guile gdb module +@value{GDBN} introduces a new Guile module, named @code{gdb}. All +methods and classes added by @value{GDBN} are placed in this module. +@value{GDBN} does not automatically @code{import} the @code{gdb} module, +scripts must do this themselves. There are various options for how to +import a module, so @value{GDBN} leaves the choice of how the @code{gdb} +module is imported to the user. +To simplify interactive use, it is recommended to add one of the following +to your ~/.gdbinit. + +@smallexample +guile (use-modules (gdb)) +@end smallexample + +@smallexample +guile (use-modules ((gdb) #:renamer (symbol-prefix-proc 'gdb:))) +@end smallexample + +Which one to choose depends on your preference. +The second one adds @code{gdb:} as a prefix to all module functions +and variables. + +The rest of this manual assumes the @code{gdb} module has been imported +without any prefix. See the Guile documentation for @code{use-modules} +for more information +(@pxref{Using Guile Modules,,, guile, GNU Guile Reference Manual}). + +Example: + +@smallexample +(gdb) guile (value-type (make-value 1)) +ERROR: Unbound variable: value-type +Error while executing Scheme code. +(gdb) guile (use-modules (gdb)) +(gdb) guile (value-type (make-value 1)) +int +(gdb) +@end smallexample + +The @code{(gdb)} module provides these basic Guile functions. + +@deffn {Scheme Procedure} execute command @w{@r{[}#:from-tty boolean@r{]}} @ + @w{@r{[}#:to-string boolean@r{]}} +Evaluate @var{command}, a string, as a @value{GDBN} CLI command. +If a @value{GDBN} exception happens while @var{command} runs, it is +translated as described in +@ref{Guile Exception Handling,,Guile Exception Handling}. + +@var{from-tty} specifies whether @value{GDBN} ought to consider this +command as having originated from the user invoking it interactively. +It must be a boolean value. If omitted, it defaults to @code{#f}. + +By default, any output produced by @var{command} is sent to +@value{GDBN}'s standard output (and to the log output if logging is +turned on). If the @var{to-string} parameter is +@code{#t}, then output will be collected by @code{execute} and +returned as a string. The default is @code{#f}, in which case the +return value is unspecified. If @var{to-string} is @code{#t}, the +@value{GDBN} virtual terminal will be temporarily set to unlimited width +and height, and its pagination will be disabled; @pxref{Screen Size}. +@end deffn + +@deffn {Scheme Procedure} history-ref number +Return a value from @value{GDBN}'s value history (@pxref{Value +History}). The @var{number} argument indicates which history element to return. +If @var{number} is negative, then @value{GDBN} will take its absolute value +and count backward from the last element (i.e., the most recent element) to +find the value to return. If @var{number} is zero, then @value{GDBN} will +return the most recent element. If the element specified by @var{number} +doesn't exist in the value history, a @code{gdb:error} exception will be +raised. + +If no exception is raised, the return value is always an instance of +@code{} (@pxref{Values From Inferior In Guile}). + +@emph{Note:} @value{GDBN}'s value history is independent of Guile's. +@code{$1} in @value{GDBN}'s value history contains the result of evaluating +an expression from @value{GDBN}'s command line and @code{$1} from Guile's +history contains the result of evaluating an expression from Guile's +command line. +@end deffn + +@deffn {Scheme Procedure} history-append! value +Append @var{value}, an instance of @code{}, to @value{GDBN}'s +value history. Return its index in the history. + +Putting into history values returned by Guile extensions will allow +the user convenient access to those values via CLI history +facilities. +@end deffn + +@deffn {Scheme Procedure} parse-and-eval expression +Parse @var{expression} as an expression in the current language, +evaluate it, and return the result as a @code{}. +The @var{expression} must be a string. + +This function can be useful when implementing a new command +(@pxref{Commands In Guile}), as it provides a way to parse the +command's arguments as an expression. +It is also is useful when computing values. +For example, it is the only way to get the value of a +convenience variable (@pxref{Convenience Vars}) as a @code{}. +@end deffn + +@node Guile Configuration +@subsubsection Guile Configuration +@cindex guile configuration + +@value{GDBN} provides these Scheme functions to access various configuration +parameters. + +@deffn {Scheme Procedure} data-directory +Return a string containing @value{GDBN}'s data directory. +This directory contains @value{GDBN}'s ancillary files. +@end deffn + +@deffn {Scheme Procedure} guile-data-directory +Return a string containing @value{GDBN}'s Guile data directory. +This directory contains the Guile modules provided by @value{GDBN}. +@end deffn + +@deffn {Scheme Procedure} gdb-version +Return a string containing the @value{GDBN} version. +@end deffn + +@deffn {Scheme Procedure} host-config +Return a string containing the host configuration. +This is the string passed to @code{--host} when @value{GDBN} was configured. +@end deffn + +@deffn {Scheme Procedure} target-config +Return a string containing the target configuration. +This is the string passed to @code{--target} when @value{GDBN} was configured. +@end deffn + +@node GDB Scheme Data Types +@subsubsection GDB Scheme Data Types +@cindex gdb objects + +The values exposed by @value{GDBN} to Guile are known as +@dfn{@value{GDBN} objects}. There are several kinds of @value{GDBN} +object, and each is disjoint from all other types known to Guile. + +@deffn {Scheme Procedure} gdb-object-kind object +Return the kind of the @value{GDBN} object, e.g., @code{}, +as a symbol. +@end deffn + +@value{GDBN} defines the following object types: + +@table @code +@item +@xref{Architectures In Guile}. + +@item +@xref{Blocks In Guile}. + +@item +@xref{Blocks In Guile}. + +@item +@xref{Breakpoints In Guile}. + +@item +@xref{Commands In Guile}. + +@item +@xref{Guile Exception Handling}. + +@item +@xref{Frames In Guile}. + +@item +@xref{Iterators In Guile}. + +@item +@xref{Lazy Strings In Guile}. + +@item +@xref{Objfiles In Guile}. + +@item +@xref{Parameters In Guile}. + +@item +@xref{Guile Pretty Printing API}. + +@item +@xref{Guile Pretty Printing API}. + +@item +@xref{Progspaces In Guile}. + +@item +@xref{Symbols In Guile}. + +@item +@xref{Symbol Tables In Guile}. + +@item +@xref{Symbol Tables In Guile}. + +@item +@xref{Types In Guile}. + +@item +@xref{Types In Guile}. + +@item +@xref{Values From Inferior In Guile}. +@end table + +The following @value{GDBN} objects are managed internally so that the +Scheme function @code{eq?} may be applied to them. + +@table @code +@item +@item +@item +@item +@item +@item +@item +@item +@item +@end table + +@node Guile Exception Handling +@subsubsection Guile Exception Handling +@cindex guile exceptions +@cindex exceptions, guile +@kindex set guile print-stack + +When executing the @code{guile} command, Guile exceptions +uncaught within the Guile code are translated to calls to the +@value{GDBN} error-reporting mechanism. If the command that called +@code{guile} does not handle the error, @value{GDBN} will +terminate it and report the error according to the setting of +the @code{guile print-stack} parameter. + +The @code{guile print-stack} parameter has three settings: + +@table @code +@item none +Nothing is printed. + +@item message +An error message is printed containing the Guile exception name, +the associated value, and the Guile call stack backtrace at the +point where the exception was raised. Example: + +@smallexample +(@value{GDBP}) guile (display foo) +ERROR: In procedure memoize-variable-access!: +ERROR: Unbound variable: foo +Error while executing Scheme code. +@end smallexample + +@item full +In addition to an error message a full backtrace is printed. + +@smallexample +(@value{GDBP}) set guile print-stack full +(@value{GDBP}) guile (display foo) +Guile Backtrace: +In ice-9/boot-9.scm: + 157: 10 [catch #t # ...] +In unknown file: + ?: 9 [apply-smob/1 #] +In ice-9/boot-9.scm: + 157: 8 [catch #t # ...] +In unknown file: + ?: 7 [apply-smob/1 #] + ?: 6 [call-with-input-string "(display foo)" ...] +In ice-9/boot-9.scm: +2320: 5 [save-module-excursion #] +In ice-9/eval-string.scm: + 44: 4 [read-and-eval # #:lang ...] + 37: 3 [lp (display foo)] +In ice-9/eval.scm: + 387: 2 [eval # ()] + 393: 1 [eval # ()] +In unknown file: + ?: 0 [memoize-variable-access! # ...] + +ERROR: In procedure memoize-variable-access!: +ERROR: Unbound variable: foo +Error while executing Scheme code. +@end smallexample +@end table + +@value{GDBN} errors that happen in @value{GDBN} commands invoked by +Guile code are converted to Guile exceptions. The type of the +Guile exception depends on the error. + +Guile procedures provided by @value{GDBN} can throw the standard +Guile exceptions like @code{wrong-type-arg} and @code{out-of-range}. + +User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination +prompt) is translated to a Guile @code{signal} exception with value +@code{SIGINT}. + +@value{GDBN} Guile procedures can also throw these exceptions: + +@vtable @code +@item gdb:error +This exception is a catch-all for errors generated from within @value{GDBN}. + +@item gdb:invalid-object +This exception is thrown when accessing Guile objects that wrap underlying +@value{GDBN} objects have become invalid. For example, a +@code{} object becomes invalid if the user deletes it +from the command line. The object still exists in Guile, but the +object it represents is gone. Further operations on this breakpoint +will throw this exception. + +@item gdb:memory-error +This exception is thrown when an operation tried to access invalid +memory in the inferior. + +@item gdb:pp-type-error +This exception is thrown when a Guile pretty-printer passes a bad object +to @value{GDBN}. +@end vtable + +The following exception-related procedures are provided by the +@code{(gdb)} module. + +@deffn {Scheme Procedure} make-exception key args +Return a @code{} object given by its @var{key} and +@var{args}, which are the standard Guile parameters of an exception. +See the Guile documentation for more information (@pxref{Exceptions,,, +guile, GNU Guile Reference Manual}). +@end deffn + +@deffn {Scheme Procedure} exception? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} exception-key exception +Return the @var{args} field of a @code{} object. +@end deffn + +@deffn {Scheme Procedure} exception-args exception +Return the @var{args} field of a @code{} object. +@end deffn + +@node Values From Inferior In Guile +@subsubsection Values From Inferior In Guile +@cindex values from inferior, in guile +@cindex guile, working with values from inferior + +@tindex @code{} +@value{GDBN} provides values it obtains from the inferior program in +an object of type @code{}. @value{GDBN} uses this object +for its internal bookkeeping of the inferior's values, and for +fetching values when necessary. + +@value{GDBN} does not memoize @code{} objects. +@code{make-value} always returns a fresh object. + +@smallexample +(gdb) guile (eq? (make-value 1) (make-value 1)) +$1 = #f +(gdb) guile (equal? (make-value 1) (make-value 1)) +$1 = #t +@end smallexample + +A @code{} that represents a function can be executed via +inferior function call with @code{value-call}. +Any arguments provided to the call must match the function's prototype, +and must be provided in the order specified by that prototype. + +For example, @code{some-val} is a @code{} instance +representing a function that takes two integers as arguments. To +execute this function, call it like so: + +@smallexample +(define result (value-call some-val 10 20)) +@end smallexample + +Any values returned from a function call are @code{} objects. + +Note: Unlike Python scripting in @value{GDBN}, +inferior values that are simple scalars cannot be used directly in +Scheme expressions that are valid for the value's data type. +For example, @code{(+ (parse-and-eval "int_variable") 2)} does not work. +And inferior values that are structures or instances of some class cannot +be accessed using any special syntax, instead @code{value-field} must be used. + +The following value-related procedures are provided by the +@code{(gdb)} module. + +@deffn {Scheme Procedure} value? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} make-value value @r{[}#:type type@r{]} +Many Scheme values can be converted directly to a @code{} +with this procedure. If @var{type} is specified, the result is a value +of this type, and if @var{value} can't be represented with this type +an exception is thrown. Otherwise the type of the result is determined from +@var{value} as described below. + +@xref{Architectures In Guile}, for a list of the builtin +types for an architecture. + +Here's how Scheme values are converted when @var{type} argument to +@code{make-value} is not specified: + +@table @asis +@item Scheme boolean +A Scheme boolean is converted the boolean type for the current language. + +@item Scheme integer +A Scheme integer is converted to the first of a C @code{int}, +@code{unsigned int}, @code{long}, @code{unsigned long}, +@code{long long} or @code{unsigned long long} type +for the current architecture that can represent the value. + +If the Scheme integer cannot be represented as a target integer +an @code{out-of-range} exception is thrown. + +@item Scheme real +A Scheme real is converted to the C @code{double} type for the +current architecture. + +@item Scheme string +A Scheme string is converted to a string in the current target +language using the current target encoding. +Characters that cannot be represented in the current target encoding +are replaced with the corresponding escape sequence. This is Guile's +@code{SCM_FAILED_CONVERSION_ESCAPE_SEQUENCE} conversion strategy +(@pxref{Strings,,, guile, GNU Guile Reference Manual}). + +Passing @var{type} is not supported in this case, +if it is provided a @code{wrong-type-arg} exception is thrown. + +@item @code{} +If @var{value} is a @code{} object (@pxref{Lazy Strings In +Guile}), then the @code{lazy-string->value} procedure is called, and +its result is used. + +Passing @var{type} is not supported in this case, +if it is provided a @code{wrong-type-arg} exception is thrown. + +@item Scheme bytevector +If @var{value} is a Scheme bytevector and @var{type} is provided, +@var{value} must be the same size, in bytes, of values of type @var{type}, +and the result is essentially created by using @code{memcpy}. + +If @var{value} is a Scheme bytevector and @var{type} is not provided, +the result is an array of type @code{uint8} of the same length. +@end table +@end deffn + +@cindex optimized out value in guile +@deffn {Scheme Procedure} value-optimized-out? value +Return @code{#t} if the compiler optimized out @var{value}, +thus it is not available for fetching from the inferior. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} value-address value +If @var{value} is addressable, returns a +@code{} object representing the address. +Otherwise, @code{#f} is returned. +@end deffn + +@deffn {Scheme Procedure} value-type value +Return the type of @var{value} as a @code{} object +(@pxref{Types In Guile}). +@end deffn + +@deffn {Scheme Procedure} value-dynamic-type value +Return the dynamic type of @var{value}. This uses C@t{++} run-time +type information (@acronym{RTTI}) to determine the dynamic type of the +value. If the value is of class type, it will return the class in +which the value is embedded, if any. If the value is of pointer or +reference to a class type, it will compute the dynamic type of the +referenced object, and return a pointer or reference to that type, +respectively. In all other cases, it will return the value's static +type. + +Note that this feature will only work when debugging a C@t{++} program +that includes @acronym{RTTI} for the object in question. Otherwise, +it will just return the static type of the value as in @kbd{ptype foo}. +@xref{Symbols, ptype}. +@end deffn + +@deffn {Scheme Procedure} value-cast value type +Return a new instance of @code{} that is the result of +casting @var{value} to the type described by @var{type}, which must +be a @code{} object. If the cast cannot be performed for some +reason, this method throws an exception. +@end deffn + +@deffn {Scheme Procedure} value-dynamic-cast value type +Like @code{value-cast}, but works as if the C@t{++} @code{dynamic_cast} +operator were used. Consult a C@t{++} reference for details. +@end deffn + +@deffn {Scheme Procedure} value-reinterpret-cast value type +Like @code{value-cast}, but works as if the C@t{++} @code{reinterpret_cast} +operator were used. Consult a C@t{++} reference for details. +@end deffn + +@deffn {Scheme Procedure} value-dereference value +For pointer data types, this method returns a new @code{} object +whose contents is the object pointed to by @var{value}. For example, if +@code{foo} is a C pointer to an @code{int}, declared in your C program as + +@smallexample +int *foo; +@end smallexample + +@noindent +then you can use the corresponding @code{} to access what +@code{foo} points to like this: + +@smallexample +(define bar (value-dereference foo)) +@end smallexample + +The result @code{bar} will be a @code{} object holding the +value pointed to by @code{foo}. + +A similar function @code{value-referenced-value} exists which also +returns @code{} objects corresponding to the values pointed to +by pointer values (and additionally, values referenced by reference +values). However, the behavior of @code{value-dereference} +differs from @code{value-referenced-value} by the fact that the +behavior of @code{value-dereference} is identical to applying the C +unary operator @code{*} on a given value. For example, consider a +reference to a pointer @code{ptrref}, declared in your C@t{++} program +as + +@smallexample +typedef int *intptr; +... +int val = 10; +intptr ptr = &val; +intptr &ptrref = ptr; +@end smallexample + +Though @code{ptrref} is a reference value, one can apply the method +@code{value-dereference} to the @code{} object corresponding +to it and obtain a @code{} which is identical to that +corresponding to @code{val}. However, if you apply the method +@code{value-referenced-value}, the result would be a @code{} +object identical to that corresponding to @code{ptr}. + +@smallexample +(define scm-ptrref (parse-and-eval "ptrref")) +(define scm-val (value-dereference scm-ptrref)) +(define scm-ptr (value-referenced-value scm-ptrref)) +@end smallexample + +The @code{} object @code{scm-val} is identical to that +corresponding to @code{val}, and @code{scm-ptr} is identical to that +corresponding to @code{ptr}. In general, @code{value-dereference} can +be applied whenever the C unary operator @code{*} can be applied +to the corresponding C value. For those cases where applying both +@code{value-dereference} and @code{value-referenced-value} is allowed, +the results obtained need not be identical (as we have seen in the above +example). The results are however identical when applied on +@code{} objects corresponding to pointers (@code{} +objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program. +@end deffn + +@deffn {Scheme Procedure} value-referenced-value value +For pointer or reference data types, this method returns a new +@code{} object corresponding to the value referenced by the +pointer/reference value. For pointer data types, +@code{value-dereference} and @code{value-referenced-value} produce +identical results. The difference between these methods is that +@code{value-dereference} cannot get the values referenced by reference +values. For example, consider a reference to an @code{int}, declared +in your C@t{++} program as + +@smallexample +int val = 10; +int &ref = val; +@end smallexample + +@noindent +then applying @code{value-dereference} to the @code{} object +corresponding to @code{ref} will result in an error, while applying +@code{value-referenced-value} will result in a @code{} object +identical to that corresponding to @code{val}. + +@smallexample +(define scm-ref (parse-and-eval "ref")) +(define err-ref (value-dereference scm-ref)) ;; error +(define scm-val (value-referenced-value scm-ref)) ;; ok +@end smallexample + +The @code{} object @code{scm-val} is identical to that +corresponding to @code{val}. +@end deffn + +@deffn {Scheme Procedure} value-reference-value value +Return a new @code{} object which is a reference to the value +encapsulated by @code{} object @var{value}. +@end deffn + +@deffn {Scheme Procedure} value-rvalue-reference-value value +Return a new @code{} object which is an rvalue reference to +the value encapsulated by @code{} object @var{value}. +@end deffn + +@deffn {Scheme Procedure} value-const-value value +Return a new @code{} object which is a @samp{const} version +of @code{} object @var{value}. +@end deffn + +@deffn {Scheme Procedure} value-field value field-name +Return field @var{field-name} from @code{} object @var{value}. +@end deffn + +@deffn {Scheme Procedure} value-subscript value index +Return the value of array @var{value} at index @var{index}. +The @var{value} argument must be a subscriptable @code{} object. +@end deffn + +@deffn {Scheme Procedure} value-call value arg-list +Perform an inferior function call, taking @var{value} as a pointer +to the function to call. +Each element of list @var{arg-list} must be a object or an object +that can be converted to a value. +The result is the value returned by the function. +@end deffn + +@deffn {Scheme Procedure} value->bool value +Return the Scheme boolean representing @code{} @var{value}. +The value must be ``integer like''. Pointers are ok. +@end deffn + +@deffn {Scheme Procedure} value->integer +Return the Scheme integer representing @code{} @var{value}. +The value must be ``integer like''. Pointers are ok. +@end deffn + +@deffn {Scheme Procedure} value->real +Return the Scheme real number representing @code{} @var{value}. +The value must be a number. +@end deffn + +@deffn {Scheme Procedure} value->bytevector +Return a Scheme bytevector with the raw contents of @code{} +@var{value}. No transformation, endian or otherwise, is performed. +@end deffn + +@deffn {Scheme Procedure} value->string value @ + @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:errors errors@r{]}} @ + @w{@r{[}#:length length@r{]}} +If @var{value>} represents a string, then this method +converts the contents to a Guile string. Otherwise, this method will +throw an exception. + +Values are interpreted as strings according to the rules of the +current language. If the optional length argument is given, the +string will be converted to that length, and will include any embedded +zeroes that the string may contain. Otherwise, for languages +where the string is zero-terminated, the entire string will be +converted. + +For example, in C-like languages, a value is a string if it is a pointer +to or an array of characters or ints of type @code{wchar_t}, @code{char16_t}, +or @code{char32_t}. + +If the optional @var{encoding} argument is given, it must be a string +naming the encoding of the string in the @code{}, such as +@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts +the same encodings as the corresponding argument to Guile's +@code{scm_from_stringn} function, and the Guile codec machinery will be used +to convert the string. If @var{encoding} is not given, or if +@var{encoding} is the empty string, then either the @code{target-charset} +(@pxref{Character Sets}) will be used, or a language-specific encoding +will be used, if the current language is able to supply one. + +The optional @var{errors} argument is one of @code{#f}, @code{error} or +@code{substitute}. @code{error} and @code{substitute} must be symbols. +If @var{errors} is not specified, or if its value is @code{#f}, then the +default conversion strategy is used, which is set with the Scheme function +@code{set-port-conversion-strategy!}. +If the value is @code{'error} then an exception is thrown if there is any +conversion error. If the value is @code{'substitute} then any conversion +error is replaced with question marks. +@xref{Strings,,, guile, GNU Guile Reference Manual}. + +If the optional @var{length} argument is given, the string will be +fetched and converted to the given length. +The length must be a Scheme integer and not a @code{} integer. +@end deffn + +@deffn {Scheme Procedure} value->lazy-string value @ + @w{@r{[}#:encoding encoding@r{]}} @w{@r{[}#:length length@r{]}} +If this @code{} represents a string, then this method +converts @var{value} to a @code{} integer. +@end deffn + +@deffn {Scheme Procedure} value-lazy? value +Return @code{#t} if @var{value} has not yet been fetched +from the inferior. +Otherwise return @code{#f}. +@value{GDBN} does not fetch values until necessary, for efficiency. +For example: + +@smallexample +(define myval (parse-and-eval "somevar")) +@end smallexample + +The value of @code{somevar} is not fetched at this time. It will be +fetched when the value is needed, or when the @code{fetch-lazy} +procedure is invoked. +@end deffn + +@deffn {Scheme Procedure} make-lazy-value type address +Return a @code{} that will be lazily fetched from the +target. The object of type @code{} whose value to fetch is +specified by its @var{type} and its target memory @var{address}, which +is a Scheme integer. +@end deffn + +@deffn {Scheme Procedure} value-fetch-lazy! value +If @var{value} is a lazy value (@code{(value-lazy? value)} is @code{#t}), +then the value is fetched from the inferior. +Any errors that occur in the process will produce a Guile exception. + +If @var{value} is not a lazy value, this method has no effect. + +The result of this function is unspecified. +@end deffn + +@deffn {Scheme Procedure} value-print value +Return the string representation (print form) of @code{} +@var{value}. +@end deffn + +@node Arithmetic In Guile +@subsubsection Arithmetic In Guile + +The @code{(gdb)} module provides several functions for performing +arithmetic on @code{} objects. +The arithmetic is performed as if it were done by the target, +and therefore has target semantics which are not necessarily +those of Scheme. For example operations work with a fixed precision, +not the arbitrary precision of Scheme. + +Wherever a function takes an integer or pointer as an operand, +@value{GDBN} will convert appropriate Scheme values to perform +the operation. + +@deffn {Scheme Procedure} value-add a b +@end deffn + +@deffn {Scheme Procedure} value-sub a b +@end deffn + +@deffn {Scheme Procedure} value-mul a b +@end deffn + +@deffn {Scheme Procedure} value-div a b +@end deffn + +@deffn {Scheme Procedure} value-rem a b +@end deffn + +@deffn {Scheme Procedure} value-mod a b +@end deffn + +@deffn {Scheme Procedure} value-pow a b +@end deffn + +@deffn {Scheme Procedure} value-not a +@end deffn + +@deffn {Scheme Procedure} value-neg a +@end deffn + +@deffn {Scheme Procedure} value-pos a +@end deffn + +@deffn {Scheme Procedure} value-abs a +@end deffn + +@deffn {Scheme Procedure} value-lsh a b +@end deffn + +@deffn {Scheme Procedure} value-rsh a b +@end deffn + +@deffn {Scheme Procedure} value-min a b +@end deffn + +@deffn {Scheme Procedure} value-max a b +@end deffn + +@deffn {Scheme Procedure} value-lognot a +@end deffn + +@deffn {Scheme Procedure} value-logand a b +@end deffn + +@deffn {Scheme Procedure} value-logior a b +@end deffn + +@deffn {Scheme Procedure} value-logxor a b +@end deffn + +@deffn {Scheme Procedure} value=? a b +@end deffn + +@deffn {Scheme Procedure} value? a b +@end deffn + +@deffn {Scheme Procedure} value>=? a b +@end deffn + +Scheme does not provide a @code{not-equal} function, +and thus Guile support in @value{GDBN} does not either. + +@node Types In Guile +@subsubsection Types In Guile +@cindex types in guile +@cindex guile, working with types + +@tindex +@value{GDBN} represents types from the inferior in objects of type +@code{}. + +The following type-related procedures are provided by the +@code{(gdb)} module. + +@deffn {Scheme Procedure} type? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} lookup-type name @r{[}#:block block@r{]} +This function looks up a type by its @var{name}, which must be a string. + +If @var{block} is given, it is an object of type @code{}, +and @var{name} is looked up in that scope. +Otherwise, it is searched for globally. + +Ordinarily, this function will return an instance of @code{}. +If the named type cannot be found, it will throw an exception. +@end deffn + +@deffn {Scheme Procedure} type-code type +Return the type code of @var{type}. The type code will be one of the +@code{TYPE_CODE_} constants defined below. +@end deffn + +@deffn {Scheme Procedure} type-tag type +Return the tag name of @var{type}. The tag name is the name after +@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all +languages have this concept. If this type has no tag name, then +@code{#f} is returned. +@end deffn + +@deffn {Scheme Procedure} type-name type +Return the name of @var{type}. +If this type has no name, then @code{#f} is returned. +@end deffn + +@deffn {Scheme Procedure} type-print-name type +Return the print name of @var{type}. +This returns something even for anonymous types. +For example, for an anonymous C struct @code{"struct @{...@}"} is returned. +@end deffn + +@deffn {Scheme Procedure} type-sizeof type +Return the size of this type, in target @code{char} units. Usually, a +target's @code{char} type will be an 8-bit byte. However, on some +unusual platforms, this type may have a different size. +@end deffn + +@deffn {Scheme Procedure} type-strip-typedefs type +Return a new @code{} that represents the real type of @var{type}, +after removing all layers of typedefs. +@end deffn + +@deffn {Scheme Procedure} type-array type n1 @r{[}n2@r{]} +Return a new @code{} object which represents an array of this +type. If one argument is given, it is the inclusive upper bound of +the array; in this case the lower bound is zero. If two arguments are +given, the first argument is the lower bound of the array, and the +second argument is the upper bound of the array. An array's length +must not be negative, but the bounds can be. +@end deffn + +@deffn {Scheme Procedure} type-vector type n1 @r{[}n2@r{]} +Return a new @code{} object which represents a vector of this +type. If one argument is given, it is the inclusive upper bound of +the vector; in this case the lower bound is zero. If two arguments are +given, the first argument is the lower bound of the vector, and the +second argument is the upper bound of the vector. A vector's length +must not be negative, but the bounds can be. + +The difference between an @code{array} and a @code{vector} is that +arrays behave like in C: when used in expressions they decay to a pointer +to the first element whereas vectors are treated as first class values. +@end deffn + +@deffn {Scheme Procedure} type-pointer type +Return a new @code{} object which represents a pointer to +@var{type}. +@end deffn + +@deffn {Scheme Procedure} type-range type +Return a list of two elements: the low bound and high bound of @var{type}. +If @var{type} does not have a range, an exception is thrown. +@end deffn + +@deffn {Scheme Procedure} type-reference type +Return a new @code{} object which represents a reference to +@var{type}. +@end deffn + +@deffn {Scheme Procedure} type-target type +Return a new @code{} object which represents the target type +of @var{type}. + +For a pointer type, the target type is the type of the pointed-to +object. For an array type (meaning C-like arrays), the target type is +the type of the elements of the array. For a function or method type, +the target type is the type of the return value. For a complex type, +the target type is the type of the elements. For a typedef, the +target type is the aliased type. + +If the type does not have a target, this method will throw an +exception. +@end deffn + +@deffn {Scheme Procedure} type-const type +Return a new @code{} object which represents a +@code{const}-qualified variant of @var{type}. +@end deffn + +@deffn {Scheme Procedure} type-volatile type +Return a new @code{} object which represents a +@code{volatile}-qualified variant of @var{type}. +@end deffn + +@deffn {Scheme Procedure} type-unqualified type +Return a new @code{} object which represents an unqualified +variant of @var{type}. That is, the result is neither @code{const} nor +@code{volatile}. +@end deffn + +@deffn {Scheme Procedure} type-num-fields +Return the number of fields of @code{} @var{type}. +@end deffn + +@deffn {Scheme Procedure} type-fields type +Return the fields of @var{type} as a list. +For structure and union types, @code{fields} has the usual meaning. +Range types have two fields, the minimum and maximum values. Enum types +have one field per enum constant. Function and method types have one +field per parameter. The base types of C@t{++} classes are also +represented as fields. If the type has no fields, or does not fit +into one of these categories, an empty list will be returned. +@xref{Fields of a type in Guile}. +@end deffn + +@deffn {Scheme Procedure} make-field-iterator type +Return the fields of @var{type} as a object. +@xref{Iterators In Guile}. +@end deffn + +@deffn {Scheme Procedure} type-field type field-name +Return field named @var{field-name} in @var{type}. +The result is an object of type @code{}. +@xref{Fields of a type in Guile}. +If the type does not have fields, or @var{field-name} is not a field +of @var{type}, an exception is thrown. + +For example, if @code{some-type} is a @code{} instance holding +a structure type, you can access its @code{foo} field with: + +@smallexample +(define bar (type-field some-type "foo")) +@end smallexample + +@code{bar} will be a @code{} object. +@end deffn + +@deffn {Scheme Procedure} type-has-field? type name +Return @code{#t} if @code{} @var{type} has field named @var{name}. +Otherwise return @code{#f}. +@end deffn + +Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the @code{(gdb)} module: + +@vtable @code +@item TYPE_CODE_PTR +The type is a pointer. + +@item TYPE_CODE_ARRAY +The type is an array. + +@item TYPE_CODE_STRUCT +The type is a structure. + +@item TYPE_CODE_UNION +The type is a union. + +@item TYPE_CODE_ENUM +The type is an enum. + +@item TYPE_CODE_FLAGS +A bit flags type, used for things such as status registers. + +@item TYPE_CODE_FUNC +The type is a function. + +@item TYPE_CODE_INT +The type is an integer type. + +@item TYPE_CODE_FLT +A floating point type. + +@item TYPE_CODE_VOID +The special type @code{void}. + +@item TYPE_CODE_SET +A Pascal set type. + +@item TYPE_CODE_RANGE +A range type, that is, an integer type with bounds. + +@item TYPE_CODE_STRING +A string type. Note that this is only used for certain languages with +language-defined string types; C strings are not represented this way. + +@item TYPE_CODE_BITSTRING +A string of bits. It is deprecated. + +@item TYPE_CODE_ERROR +An unknown or erroneous type. + +@item TYPE_CODE_METHOD +A method type, as found in C@t{++}. + +@item TYPE_CODE_METHODPTR +A pointer-to-member-function. + +@item TYPE_CODE_MEMBERPTR +A pointer-to-member. + +@item TYPE_CODE_REF +A reference type. + +@item TYPE_CODE_RVALUE_REF +A C@t{++}11 rvalue reference type. + +@item TYPE_CODE_CHAR +A character type. + +@item TYPE_CODE_BOOL +A boolean type. + +@item TYPE_CODE_COMPLEX +A complex float type. + +@item TYPE_CODE_TYPEDEF +A typedef to some other type. + +@item TYPE_CODE_NAMESPACE +A C@t{++} namespace. + +@item TYPE_CODE_DECFLOAT +A decimal floating point type. + +@item TYPE_CODE_INTERNAL_FUNCTION +A function internal to @value{GDBN}. This is the type used to represent +convenience functions (@pxref{Convenience Funs}). + +@vindex TYPE_CODE_XMETHOD +@item gdb.TYPE_CODE_XMETHOD +A method internal to @value{GDBN}. This is the type used to represent +xmethods (@pxref{Writing an Xmethod}). + +@vindex TYPE_CODE_FIXED_POINT +@item gdb.TYPE_CODE_FIXED_POINT +A fixed-point number. + +@vindex TYPE_CODE_NAMESPACE +@item gdb.TYPE_CODE_NAMESPACE +A Fortran namelist. +@end vtable + +Further support for types is provided in the @code{(gdb types)} +Guile module (@pxref{Guile Types Module}). + +@anchor{Fields of a type in Guile} +Each field is represented as an object of type @code{}. + +The following field-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} field? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} field-name field +Return the name of the field, or @code{#f} for anonymous fields. +@end deffn + +@deffn {Scheme Procedure} field-type field +Return the type of the field. This is usually an instance of +@code{}, but it can be @code{#f} in some situations. +@end deffn + +@deffn {Scheme Procedure} field-enumval field +Return the enum value represented by @code{} @var{field}. +@end deffn + +@deffn {Scheme Procedure} field-bitpos field +Return the bit position of @code{} @var{field}. +This attribute is not available for @code{static} fields (as in +C@t{++}). +@end deffn + +@deffn {Scheme Procedure} field-bitsize field +If the field is packed, or is a bitfield, return the size of +@code{} @var{field} in bits. Otherwise, zero is returned; +in which case the field's size is given by its type. +@end deffn + +@deffn {Scheme Procedure} field-artificial? field +Return @code{#t} if the field is artificial, usually meaning that +it was provided by the compiler and not the user. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} field-base-class? field +Return @code{#t} if the field represents a base class of a C@t{++} +structure. +Otherwise return @code{#f}. +@end deffn + +@node Guile Pretty Printing API +@subsubsection Guile Pretty Printing API +@cindex guile pretty printing api + +An example output is provided (@pxref{Pretty Printing}). + +A pretty-printer is represented by an object of type . +Pretty-printer objects are created with @code{make-pretty-printer}. + +The following pretty-printer-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} make-pretty-printer name lookup-function +Return a @code{} object named @var{name}. + +@var{lookup-function} is a function of one parameter: the value to +be printed. If the value is handled by this pretty-printer, then +@var{lookup-function} returns an object of type + to perform the actual pretty-printing. +Otherwise @var{lookup-function} returns @code{#f}. +@end deffn + +@deffn {Scheme Procedure} pretty-printer? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} pretty-printer-enabled? pretty-printer +Return @code{#t} if @var{pretty-printer} is enabled. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} set-pretty-printer-enabled! pretty-printer flag +Set the enabled flag of @var{pretty-printer} to @var{flag}. +The value returned is unspecified. +@end deffn + +@deffn {Scheme Procedure} pretty-printers +Return the list of global pretty-printers. +@end deffn + +@deffn {Scheme Procedure} set-pretty-printers! pretty-printers +Set the list of global pretty-printers to @var{pretty-printers}. +The value returned is unspecified. +@end deffn + +@deffn {Scheme Procedure} make-pretty-printer-worker display-hint to-string children +Return an object of type @code{}. + +This function takes three parameters: + +@table @samp +@item display-hint +@var{display-hint} provides a hint to @value{GDBN} or @value{GDBN} +front end via MI to change the formatting of the value being printed. +The value must be a string or @code{#f} (meaning there is no hint). +Several values for @var{display-hint} +are predefined by @value{GDBN}: + +@table @samp +@item array +Indicate that the object being printed is ``array-like''. The CLI +uses this to respect parameters such as @code{set print elements} and +@code{set print array}. + +@item map +Indicate that the object being printed is ``map-like'', and that the +children of this value can be assumed to alternate between keys and +values. + +@item string +Indicate that the object being printed is ``string-like''. If the +printer's @code{to-string} function returns a Guile string of some +kind, then @value{GDBN} will call its internal language-specific +string-printing function to format the string. For the CLI this means +adding quotation marks, possibly escaping some characters, respecting +@code{set print elements}, and the like. +@end table + +@item to-string +@var{to-string} is either a function of one parameter, the +@code{} object, or @code{#f}. + +When printing from the CLI, if the @code{to-string} method exists, +then @value{GDBN} will prepend its result to the values returned by +@code{children}. Exactly how this formatting is done is dependent on +the display hint, and may change as more hints are added. Also, +depending on the print settings (@pxref{Print Settings}), the CLI may +print just the result of @code{to-string} in a stack trace, omitting +the result of @code{children}. + +If this method returns a string, it is printed verbatim. + +Otherwise, if this method returns an instance of @code{}, +then @value{GDBN} prints this value. This may result in a call to +another pretty-printer. + +If instead the method returns a Guile value which is convertible to a +@code{}, then @value{GDBN} performs the conversion and prints +the resulting value. Again, this may result in a call to another +pretty-printer. Guile scalars (integers, floats, and booleans) and +strings are convertible to @code{}; other types are not. + +Finally, if this method returns @code{#f} then no further operations +are performed in this method and nothing is printed. + +If the result is not one of these types, an exception is raised. + +@var{to-string} may also be @code{#f} in which case it is left to +@var{children} to print the value. + +@item children +@var{children} is either a function of one parameter, the +@code{} object, or @code{#f}. + +@value{GDBN} will call this function on a pretty-printer to compute the +children of the pretty-printer's value. + +This function must return a object. +Each item returned by the iterator must be a tuple holding +two elements. The first element is the ``name'' of the child; the +second element is the child's value. The value can be any Guile +object which is convertible to a @value{GDBN} value. + +If @var{children} is @code{#f}, @value{GDBN} will act +as though the value has no children. + +Children may be hidden from display based on the value of @samp{set +print max-depth} (@pxref{Print Settings}). +@end table +@end deffn + +@value{GDBN} provides a function which can be used to look up the +default pretty-printer for a @code{}: + +@deffn {Scheme Procedure} default-visualizer value +This function takes a @code{} object as an argument. If a +pretty-printer for this value exists, then it is returned. If no such +printer exists, then this returns @code{#f}. +@end deffn + +@node Selecting Guile Pretty-Printers +@subsubsection Selecting Guile Pretty-Printers +@cindex selecting guile pretty-printers + +There are three sets of pretty-printers that @value{GDBN} searches: + +@itemize @bullet +@item +Per-objfile list of pretty-printers (@pxref{Objfiles In Guile}). +@item +Per-progspace list of pretty-printers (@pxref{Progspaces In Guile}). +@item +The global list of pretty-printers (@pxref{Guile Pretty Printing API}). +These printers are available when debugging any inferior. +@end itemize + +Pretty-printer lookup is done by passing the value to be printed to the +lookup function of each enabled object in turn. +Lookup stops when a lookup function returns a non-@code{#f} value +or when the list is exhausted. +Lookup functions must return either a @code{} +object or @code{#f}. Otherwise an exception is thrown. + +@value{GDBN} first checks the result of @code{objfile-pretty-printers} +of each @code{} in the current program space and iteratively +calls each enabled lookup function in the list for that @code{} +until a non-@code{#f} object is returned. +If no pretty-printer is found in the objfile lists, @value{GDBN} then +searches the result of @code{progspace-pretty-printers} of the current +program space, calling each enabled function until a non-@code{#f} object +is returned. +After these lists have been exhausted, it tries the global pretty-printers +list, obtained with @code{pretty-printers}, again calling each enabled +function until a non-@code{#f} object is returned. + +The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, +and iterated over sequentially until the end of the list, or a +@code{} object is returned. + +For various reasons a pretty-printer may not work. +For example, the underlying data structure may have changed and +the pretty-printer is out of date. + +The consequences of a broken pretty-printer are severe enough that +@value{GDBN} provides support for enabling and disabling individual +printers. For example, if @code{print frame-arguments} is on, +a backtrace can become highly illegible if any argument is printed +with a broken printer. + +Pretty-printers are enabled and disabled from Scheme by calling +@code{set-pretty-printer-enabled!}. +@xref{Guile Pretty Printing API}. + +@node Writing a Guile Pretty-Printer +@subsubsection Writing a Guile Pretty-Printer +@cindex writing a Guile pretty-printer + +A pretty-printer consists of two basic parts: a lookup function to determine +if the type is supported, and the printer itself. + +Here is an example showing how a @code{std::string} printer might be +written. @xref{Guile Pretty Printing API}, for details. + +@smallexample +(define (make-my-string-printer value) + "Print a my::string string" + (make-pretty-printer-worker + "string" + (lambda (printer) + (value-field value "_data")) + #f)) +@end smallexample + +And here is an example showing how a lookup function for the printer +example above might be written. + +@smallexample +(define (str-lookup-function pretty-printer value) + (let ((tag (type-tag (value-type value)))) + (and tag + (string-prefix? "std::string<" tag) + (make-my-string-printer value)))) +@end smallexample + +Then to register this printer in the global printer list: + +@smallexample +(append-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function)) +@end smallexample + +The example lookup function extracts the value's type, and attempts to +match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a object. +If not, it returns @code{#f}. + +We recommend that you put your core pretty-printers into a Guile +package. If your pretty-printers are for use with a library, we +further recommend embedding a version number into the package name. +This practice will enable @value{GDBN} to load multiple versions of +your pretty-printers at the same time, because they will have +different names. + +You should write auto-loaded code (@pxref{Guile Auto-loading}) such that it +can be evaluated multiple times without changing its meaning. An +ideal auto-load file will consist solely of @code{import}s of your +printer modules, followed by a call to a register pretty-printers with +the current objfile. + +Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Guile package name will ensure that +@value{GDBN} is able to load both sets of printers simultaneously. +Then, because the search for pretty-printers is done by objfile, and +because your auto-loaded code took care to register your library's +printers with a specific objfile, @value{GDBN} will find the correct +printers for the specific version of the library used by each +inferior. + +To continue the @code{my::string} example, +this code might appear in @code{(my-project my-library v1)}: + +@smallexample +(use-modules (gdb)) +(define (register-printers objfile) + (append-objfile-pretty-printer! + (make-pretty-printer "my-string" str-lookup-function))) +@end smallexample + +@noindent +And then the corresponding contents of the auto-load file would be: + +@smallexample +(use-modules (gdb) (my-project my-library v1)) +(register-printers (current-objfile)) +@end smallexample + +The previous example illustrates a basic pretty-printer. +There are a few things that can be improved on. +The printer only handles one type, whereas a library typically has +several types. One could install a lookup function for each desired type +in the library, but one could also have a single lookup function recognize +several types. The latter is the conventional way this is handled. +If a pretty-printer can handle multiple data types, then its +@dfn{subprinters} are the printers for the individual data types. + +The @code{(gdb printing)} module provides a formal way of solving this +problem (@pxref{Guile Printing Module}). +Here is another example that handles multiple types. + +These are the types we are going to pretty-print: + +@smallexample +struct foo @{ int a, b; @}; +struct bar @{ struct foo x, y; @}; +@end smallexample + +Here are the printers: + +@smallexample +(define (make-foo-printer value) + "Print a foo object" + (make-pretty-printer-worker + "foo" + (lambda (printer) + (format #f "a=<~a> b=<~a>" + (value-field value "a") (value-field value "a"))) + #f)) + +(define (make-bar-printer value) + "Print a bar object" + (make-pretty-printer-worker + "foo" + (lambda (printer) + (format #f "x=<~a> y=<~a>" + (value-field value "x") (value-field value "y"))) + #f)) +@end smallexample + +This example doesn't need a lookup function, that is handled by the +@code{(gdb printing)} module. Instead a function is provided to build up +the object that handles the lookup. + +@smallexample +(use-modules (gdb printing)) + +(define (build-pretty-printer) + (let ((pp (make-pretty-printer-collection "my-library"))) + (pp-collection-add-tag-printer "foo" make-foo-printer) + (pp-collection-add-tag-printer "bar" make-bar-printer) + pp)) +@end smallexample + +And here is the autoload support: + +@smallexample +(use-modules (gdb) (my-library)) +(append-objfile-pretty-printer! (current-objfile) (build-pretty-printer)) +@end smallexample + +Finally, when this printer is loaded into @value{GDBN}, here is the +corresponding output of @samp{info pretty-printer}: + +@smallexample +(gdb) info pretty-printer +my_library.so: + my-library + foo + bar +@end smallexample + +@node Commands In Guile +@subsubsection Commands In Guile + +@cindex commands in guile +@cindex guile commands +You can implement new @value{GDBN} CLI commands in Guile. A CLI +command object is created with the @code{make-command} Guile function, +and added to @value{GDBN} with the @code{register-command!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the command to @value{GDBN} from @code{make-command}. + +There is no support for multi-line commands, that is commands that +consist of multiple lines and are terminated with @code{end}. + +@deffn {Scheme Procedure} make-command name @w{@r{[}#:invoke invoke@r{]}} @ + @w{@r{[}#:command-class command-class@r{]}} @ + @w{@r{[}#:completer-class completer@r{]}} @ + @w{@r{[}#:prefix? prefix@r{]}} @w{@r{[}#:doc doc-string@r{]}} + +The argument @var{name} is the name of the command. If @var{name} consists of +multiple words, then the initial words are looked for as prefix +commands. In this case, if one of the prefix commands does not exist, +an exception is raised. + +The result is the @code{} object representing the command. +The command is not usable until it has been registered with @value{GDBN} +with @code{register-command!}. + +The rest of the arguments are optional. + +The argument @var{invoke} is a procedure of three arguments: @var{self}, +@var{args} and @var{from-tty}. The argument @var{self} is the +@code{} object representing the command. +The argument @var{args} is a string representing the arguments passed to +the command, after leading and trailing whitespace has been stripped. +The argument @var{from-tty} is a boolean flag and specifies whether the +command should consider itself to have been originated from the user +invoking it interactively. If this function throws an exception, +it is turned into a @value{GDBN} @code{error} call. +Otherwise, the return value is ignored. + +The argument @var{command-class} is one of the @samp{COMMAND_} constants +defined below. This argument tells @value{GDBN} how to categorize the +new command in the help system. The default is @code{COMMAND_NONE}. + +The argument @var{completer} is either @code{#f}, one of the @samp{COMPLETE_} +constants defined below, or a procedure, also defined below. +This argument tells @value{GDBN} how to perform completion +for this command. If not provided or if the value is @code{#f}, +then no completion is performed on the command. + +The argument @var{prefix} is a boolean flag indicating whether the new +command is a prefix command; sub-commands of this command may be +registered. + +The argument @var{doc-string} is help text for the new command. +If no documentation string is provided, the default value ``This command is +not documented.'' is used. +@end deffn + +@deffn {Scheme Procedure} register-command! command +Add @var{command}, a @code{} object, to @value{GDBN}'s +list of commands. +It is an error to register a command more than once. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} command? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@cindex don't repeat Guile command +@deffn {Scheme Procedure} dont-repeat +By default, a @value{GDBN} command is repeated when the user enters a +blank line at the command prompt. A command can suppress this +behavior by invoking the @code{dont-repeat} function. This is similar +to the user command @code{dont-repeat}, see @ref{Define, dont-repeat}. +@end deffn + +@deffn {Scheme Procedure} string->argv string +Convert a string to a list of strings split up according to +@value{GDBN}'s argv parsing rules. +It is recommended to use this for consistency. +Arguments are separated by spaces and may be quoted. +Example: + +@smallexample +scheme@@(guile-user)> (string->argv "1 2\\ \\\"3 '4 \"5' \"6 '7\"") +$1 = ("1" "2 \"3" "4 \"5" "6 '7") +@end smallexample +@end deffn + +@deffn {Scheme Procedure} throw-user-error message . args +Throw a @code{gdb:user-error} exception. +The argument @var{message} is the error message as a format string, like the +@var{fmt} argument to the @code{format} Scheme function. +@xref{Formatted Output,,, guile, GNU Guile Reference Manual}. +The argument @var{args} is a list of the optional arguments of @var{message}. + +This is used when the command detects a user error of some kind, +say a bad command argument. + +@smallexample +(gdb) guile (use-modules (gdb)) +(gdb) guile +(register-command! (make-command "test-user-error" + #:command-class COMMAND_OBSCURE + #:invoke (lambda (self arg from-tty) + (throw-user-error "Bad argument ~a" arg)))) +end +(gdb) test-user-error ugh +ERROR: Bad argument ugh +@end smallexample +@end deffn + +@cindex completion of Guile commands +@deffn completer self text word +If the @var{completer} option to @code{make-command} is a procedure, +it takes three arguments: @var{self} which is the @code{} +object, and @var{text} and @var{word} which are both strings. +The argument @var{text} holds the complete command line up to the cursor's +location. The argument @var{word} holds the last word of the command line; +this is computed using a word-breaking heuristic. + +All forms of completion are handled by this function, that is, +the @key{TAB} and @key{M-?} key bindings (@pxref{Completion}), +and the @code{complete} command (@pxref{Help, complete}). + +This procedure can return several kinds of values: + +@itemize @bullet +@item +If the return value is a list, the contents of the list are used as the +completions. It is up to @var{completer} to ensure that the +contents actually do complete the word. An empty list is +allowed, it means that there were no completions available. Only +string elements of the list are used; other elements in the +list are ignored. + +@item +If the return value is a @code{} object, it is iterated over to +obtain the completions. It is up to @code{completer-procedure} to ensure +that the results actually do complete the word. Only +string elements of the result are used; other elements in the +sequence are ignored. + +@item +All other results are treated as though there were no available +completions. +@end itemize +@end deffn + +When a new command is registered, it will have been declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the @code{gdb} module: + +@vtable @code +@item COMMAND_NONE +The command does not belong to any particular class. A command in +this category will not be displayed in any of the help categories. +This is the default. + +@item COMMAND_RUNNING +The command is related to running the inferior. For example, +@code{start}, @code{step}, and @code{continue} are in this category. +Type @kbd{help running} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_DATA +The command is related to data or variables. For example, +@code{call}, @code{find}, and @code{print} are in this category. Type +@kbd{help data} at the @value{GDBN} prompt to see a list of commands +in this category. + +@item COMMAND_STACK +The command has to do with manipulation of the stack. For example, +@code{backtrace}, @code{frame}, and @code{return} are in this +category. Type @kbd{help stack} at the @value{GDBN} prompt to see a +list of commands in this category. + +@item COMMAND_FILES +This class is used for file-related commands. For example, +@code{file}, @code{list} and @code{section} are in this category. +Type @kbd{help files} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_SUPPORT +This should be used for ``support facilities'', generally meaning +things that are useful to the user when interacting with @value{GDBN}, +but not related to the state of the inferior. For example, +@code{help}, @code{make}, and @code{shell} are in this category. Type +@kbd{help support} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_STATUS +The command is an @samp{info}-related command, that is, related to the +state of @value{GDBN} itself. For example, @code{info}, @code{macro}, +and @code{show} are in this category. Type @kbd{help status} at the +@value{GDBN} prompt to see a list of commands in this category. + +@item COMMAND_BREAKPOINTS +The command has to do with breakpoints. For example, @code{break}, +@code{clear}, and @code{delete} are in this category. Type @kbd{help +breakpoints} at the @value{GDBN} prompt to see a list of commands in +this category. + +@item COMMAND_TRACEPOINTS +The command has to do with tracepoints. For example, @code{trace}, +@code{actions}, and @code{tfind} are in this category. Type +@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of +commands in this category. + +@item COMMAND_USER +The command is a general purpose command for the user, and typically +does not fit in one of the other categories. +Type @kbd{help user-defined} at the @value{GDBN} prompt to see +a list of commands in this category, as well as the list of gdb macros +(@pxref{Sequences}). + +@item COMMAND_OBSCURE +The command is only used in unusual circumstances, or is not of +general interest to users. For example, @code{checkpoint}, +@code{fork}, and @code{stop} are in this category. Type @kbd{help +obscure} at the @value{GDBN} prompt to see a list of commands in this +category. + +@item COMMAND_MAINTENANCE +The command is only useful to @value{GDBN} maintainers. The +@code{maintenance} and @code{flushregs} commands are in this category. +Type @kbd{help internals} at the @value{GDBN} prompt to see a list of +commands in this category. +@end vtable + +A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it +from the @code{completer} procedure. These predefined completion +constants are all defined in the @code{gdb} module: + +@vtable @code +@item COMPLETE_NONE +This constant means that no completion should be done. + +@item COMPLETE_FILENAME +This constant means that filename completion should be performed. + +@item COMPLETE_LOCATION +This constant means that location completion should be done. +@xref{Location Specifications}. + +@item COMPLETE_COMMAND +This constant means that completion should examine @value{GDBN} +command names. + +@item COMPLETE_SYMBOL +This constant means that completion should be done using symbol names +as the source. + +@item COMPLETE_EXPRESSION +This constant means that completion should be done on expressions. +Often this means completing on symbol names, but some language +parsers also have support for completing on field names. +@end vtable + +The following code snippet shows how a trivial CLI command can be +implemented in Guile: + +@smallexample +(gdb) guile +(register-command! (make-command "hello-world" + #:command-class COMMAND_USER + #:doc "Greet the whole world." + #:invoke (lambda (self args from-tty) (display "Hello, World!\n")))) +end +(gdb) hello-world +Hello, World! +@end smallexample + +@node Parameters In Guile +@subsubsection Parameters In Guile + +@cindex parameters in guile +@cindex guile parameters +@tindex Parameter +You can implement new @value{GDBN} @dfn{parameters} using Guile +@footnote{Note that @value{GDBN} parameters must not be confused with +Guile’s parameter objects (@pxref{Parameters,,, guile, GNU Guile +Reference Manual}).}. + +There are many parameters that already exist and can be set in +@value{GDBN}. Two examples are: @code{set follow-fork} and +@code{set charset}. Setting these parameters influences certain +behavior in @value{GDBN}. Similarly, you can define parameters that +can be used to influence behavior in custom Guile scripts and commands. + +A new parameter is defined with the @code{make-parameter} Guile function, +and added to @value{GDBN} with the @code{register-parameter!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the parameter to @value{GDBN} from @code{make-parameter}. + +Parameters are exposed to the user via the @code{set} and +@code{show} commands. @xref{Help}. + +@deffn {Scheme Procedure} make-parameter name @ + @w{@r{[}#:command-class command-class@r{]}} @ + @w{@r{[}#:parameter-type parameter-type@r{]}} @ + @w{@r{[}#:enum-list enum-list@r{]}} @w{@r{[}#:set-func set-func@r{]}} @ + @w{@r{[}#:show-func show-func@r{]}} @w{@r{[}#:doc doc@r{]}} @ + @w{@r{[}#:set-doc set-doc@r{]}} @w{@r{[}#:show-doc show-doc@r{]}} @ + @w{@r{[}#:initial-value initial-value@r{]}} + +The argument @var{name} is the name of the new parameter. If @var{name} +consists of multiple words, then the initial words are looked for as prefix +parameters. An example of this can be illustrated with the +@code{set print} set of parameters. If @var{name} is +@code{print foo}, then @code{print} will be searched as the prefix +parameter. In this case the parameter can subsequently be accessed in +@value{GDBN} as @code{set print foo}. +If @var{name} consists of multiple words, and no prefix parameter group +can be found, an exception is raised. + +The result is the @code{} object representing the parameter. +The parameter is not usable until it has been registered with @value{GDBN} +with @code{register-parameter!}. + +The rest of the arguments are optional. + +The argument @var{command-class} should be one of the @samp{COMMAND_} constants +(@pxref{Commands In Guile}). This argument tells @value{GDBN} how to +categorize the new parameter in the help system. +The default is @code{COMMAND_NONE}. + +The argument @var{parameter-type} should be one of the @samp{PARAM_} constants +defined below. This argument tells @value{GDBN} the type of the new +parameter; this information is used for input validation and +completion. The default is @code{PARAM_BOOLEAN}. + +If @var{parameter-type} is @code{PARAM_ENUM}, then +@var{enum-list} must be a list of strings. These strings +represent the possible values for the parameter. + +If @var{parameter-type} is not @code{PARAM_ENUM}, then the presence +of @var{enum-list} will cause an exception to be thrown. + +The argument @var{set-func} is a function of one argument: @var{self} which +is the @code{} object representing the parameter. +@value{GDBN} will call this function when a @var{parameter}'s value has +been changed via the @code{set} API (for example, @kbd{set foo off}). +The value of the parameter has already been set to the new value. +This function must return a string to be displayed to the user. +@value{GDBN} will add a trailing newline if the string is non-empty. +@value{GDBN} generally doesn't print anything when a parameter is set, +thus typically this function should return @samp{""}. +A non-empty string result should typically be used for displaying warnings +and errors. + +The argument @var{show-func} is a function of two arguments: @var{self} which +is the @code{} object representing the parameter, and +@var{svalue} which is the string representation of the current value. +@value{GDBN} will call this function when a @var{parameter}'s +@code{show} API has been invoked (for example, @kbd{show foo}). +This function must return a string, and will be displayed to the user. +@value{GDBN} will add a trailing newline. + +The argument @var{doc} is the help text for the new parameter. +If there is no documentation string, a default value is used. + +The argument @var{set-doc} is the help text for this parameter's +@code{set} command. + +The argument @var{show-doc} is the help text for this parameter's +@code{show} command. + +The argument @var{initial-value} specifies the initial value of the parameter. +If it is a function, it takes one parameter, the @code{} +object and its result is used as the initial value of the parameter. +The initial value must be valid for the parameter type, +otherwise an exception is thrown. +@end deffn + +@deffn {Scheme Procedure} register-parameter! parameter +Add @var{parameter}, a @code{} object, to @value{GDBN}'s +list of parameters. +It is an error to register a parameter more than once. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} parameter? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} parameter-value parameter +Return the value of @var{parameter} which may either be +a @code{} object or a string naming the parameter. +@end deffn + +@deffn {Scheme Procedure} set-parameter-value! parameter new-value +Assign @var{parameter} the value of @var{new-value}. +The argument @var{parameter} must be an object of type @code{}. +@value{GDBN} does validation when assignments are made. +@end deffn + +When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the @code{gdb} +module: + +@vtable @code +@item PARAM_BOOLEAN +The value is a plain boolean. The Guile boolean values, @code{#t} +and @code{#f} are the only valid values. + +@item PARAM_AUTO_BOOLEAN +The value has three possible states: true, false, and @samp{auto}. In +Guile, true and false are represented using boolean constants, and +@samp{auto} is represented using @code{#:auto}. + +@item PARAM_UINTEGER +The value is an unsigned integer. The value of @code{#:unlimited} +should be interpreted to mean ``unlimited'', and the value of @samp{0} +is reserved and should not be used. + +@item PARAM_ZINTEGER +The value is an integer. + +@item PARAM_ZUINTEGER +The value is an unsigned integer. + +@item PARAM_ZUINTEGER_UNLIMITED +The value is an integer in the range @samp{[0, INT_MAX]}. The value +of @code{#:unlimited} means ``unlimited'', the value of @samp{-1} is +reserved and should not be used, and other negative numbers are not +allowed. + +@item PARAM_STRING +The value is a string. When the user modifies the string, any escape +sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are +translated into corresponding characters and encoded into the current +host charset. + +@item PARAM_STRING_NOESCAPE +The value is a string. When the user modifies the string, escapes are +passed through untranslated. + +@item PARAM_OPTIONAL_FILENAME +The value is a either a filename (a string), or @code{#f}. + +@item PARAM_FILENAME +The value is a filename. This is just like +@code{PARAM_STRING_NOESCAPE}, but uses file names for completion. + +@item PARAM_ENUM +The value is a string, which must be one of a collection of string +constants provided when the parameter is created. +@end vtable + +@node Progspaces In Guile +@subsubsection Program Spaces In Guile + +@cindex progspaces in guile +@tindex +A program space, or @dfn{progspace}, represents a symbolic view +of an address space. +It consists of all of the objfiles of the program. +@xref{Objfiles In Guile}. +@xref{Inferiors Connections and Programs, program spaces}, for more details +about program spaces. + +Each progspace is represented by an instance of the @code{} +smob. @xref{GDB Scheme Data Types}. + +The following progspace-related functions are available in the +@code{(gdb)} module: + +@deffn {Scheme Procedure} progspace? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} progspace-valid? progspace +Return @code{#t} if @var{progspace} is valid, @code{#f} if not. +A @code{} object can become invalid +if the program it refers to is not loaded in @value{GDBN} any longer. +@end deffn + +@deffn {Scheme Procedure} current-progspace +This function returns the program space of the currently selected inferior. +There is always a current progspace, this never returns @code{#f}. +@xref{Inferiors Connections and Programs}. +@end deffn + +@deffn {Scheme Procedure} progspaces +Return a list of all the progspaces currently known to @value{GDBN}. +@end deffn + +@deffn {Scheme Procedure} progspace-filename progspace +Return the absolute file name of @var{progspace} as a string. +This is the name of the file passed as the argument to the @code{file} +or @code{symbol-file} commands. +If the program space does not have an associated file name, +then @code{#f} is returned. This occurs, for example, when @value{GDBN} +is started without a program to debug. + +A @code{gdb:invalid-object-error} exception is thrown if @var{progspace} +is invalid. +@end deffn + +@deffn {Scheme Procedure} progspace-objfiles progspace +Return the list of objfiles of @var{progspace}. +The order of objfiles in the result is arbitrary. +Each element is an object of type @code{}. +@xref{Objfiles In Guile}. + +A @code{gdb:invalid-object-error} exception is thrown if @var{progspace} +is invalid. +@end deffn + +@deffn {Scheme Procedure} progspace-pretty-printers progspace +Return the list of pretty-printers of @var{progspace}. +Each element is an object of type @code{}. +@xref{Guile Pretty Printing API}, for more information. +@end deffn + +@deffn {Scheme Procedure} set-progspace-pretty-printers! progspace printer-list +Set the list of registered @code{} objects for +@var{progspace} to @var{printer-list}. +@xref{Guile Pretty Printing API}, for more information. +@end deffn + +@node Objfiles In Guile +@subsubsection Objfiles In Guile + +@cindex objfiles in guile +@tindex +@value{GDBN} loads symbols for an inferior from various +symbol-containing files (@pxref{Files}). These include the primary +executable file, any shared libraries used by the inferior, and any +separate debug info files (@pxref{Separate Debug Files}). +@value{GDBN} calls these symbol-containing files @dfn{objfiles}. + +Each objfile is represented as an object of type @code{}. + +The following objfile-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} objfile? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} objfile-valid? objfile +Return @code{#t} if @var{objfile} is valid, @code{#f} if not. +A @code{} object can become invalid +if the object file it refers to is not loaded in @value{GDBN} any +longer. All other @code{} procedures will throw an exception +if it is invalid at the time the procedure is called. +@end deffn + +@deffn {Scheme Procedure} objfile-filename objfile +Return the file name of @var{objfile} as a string, +with symbolic links resolved. +@end deffn + +@deffn {Scheme Procedure} objfile-progspace objfile +Return the @code{} that this object file lives in. +@xref{Progspaces In Guile}, for more on progspaces. +@end deffn + +@deffn {Scheme Procedure} objfile-pretty-printers objfile +Return the list of registered @code{} objects for +@var{objfile}. @xref{Guile Pretty Printing API}, for more information. +@end deffn + +@deffn {Scheme Procedure} set-objfile-pretty-printers! objfile printer-list +Set the list of registered @code{} objects for +@var{objfile} to @var{printer-list}. The +@var{printer-list} must be a list of @code{} objects. +@xref{Guile Pretty Printing API}, for more information. +@end deffn + +@deffn {Scheme Procedure} current-objfile +When auto-loading a Guile script (@pxref{Guile Auto-loading}), @value{GDBN} +sets the ``current objfile'' to the corresponding objfile. This +function returns the current objfile. If there is no current objfile, +this function returns @code{#f}. +@end deffn + +@deffn {Scheme Procedure} objfiles +Return a list of all the objfiles in the current program space. +@end deffn + +@node Frames In Guile +@subsubsection Accessing inferior stack frames from Guile. + +@cindex frames in guile +When the debugged program stops, @value{GDBN} is able to analyze its call +stack (@pxref{Frames,,Stack frames}). The @code{} class +represents a frame in the stack. A @code{} object is only valid +while its corresponding frame exists in the inferior's stack. If you try +to use an invalid frame object, @value{GDBN} will throw a +@code{gdb:invalid-object} exception (@pxref{Guile Exception Handling}). + +Two @code{} objects can be compared for equality with the +@code{equal?} function, like: + +@smallexample +(@value{GDBP}) guile (equal? (newest-frame) (selected-frame)) +#t +@end smallexample + +The following frame-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} frame? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} frame-valid? frame +Returns @code{#t} if @var{frame} is valid, @code{#f} if not. +A frame object can become invalid if the frame it refers to doesn't +exist anymore in the inferior. All @code{} procedures will throw +an exception if the frame is invalid at the time the procedure is called. +@end deffn + +@deffn {Scheme Procedure} frame-name frame +Return the function name of @var{frame}, or @code{#f} if it can't be +obtained. +@end deffn + +@deffn {Scheme Procedure} frame-arch frame +Return the @code{} object corresponding to @var{frame}'s +architecture. @xref{Architectures In Guile}. +@end deffn + +@deffn {Scheme Procedure} frame-type frame +Return the type of @var{frame}. The value can be one of: + +@table @code +@item NORMAL_FRAME +An ordinary stack frame. + +@item DUMMY_FRAME +A fake stack frame that was created by @value{GDBN} when performing an +inferior function call. + +@item INLINE_FRAME +A frame representing an inlined function. The function was inlined +into a @code{NORMAL_FRAME} that is older than this one. + +@item TAILCALL_FRAME +A frame representing a tail call. @xref{Tail Call Frames}. + +@item SIGTRAMP_FRAME +A signal trampoline frame. This is the frame created by the OS when +it calls into a signal handler. + +@item ARCH_FRAME +A fake stack frame representing a cross-architecture call. + +@item SENTINEL_FRAME +This is like @code{NORMAL_FRAME}, but it is only used for the +newest frame. +@end table +@end deffn + +@deffn {Scheme Procedure} frame-unwind-stop-reason frame +Return an integer representing the reason why it's not possible to find +more frames toward the outermost frame. Use +@code{unwind-stop-reason-string} to convert the value returned by this +function to a string. The value can be one of: + +@table @code +@item FRAME_UNWIND_NO_REASON +No particular reason (older frames should be available). + +@item FRAME_UNWIND_NULL_ID +The previous frame's analyzer returns an invalid result. + +@item FRAME_UNWIND_OUTERMOST +This frame is the outermost. + +@item FRAME_UNWIND_UNAVAILABLE +Cannot unwind further, because that would require knowing the +values of registers or memory that have not been collected. + +@item FRAME_UNWIND_INNER_ID +This frame ID looks like it ought to belong to a NEXT frame, +but we got it for a PREV frame. Normally, this is a sign of +unwinder failure. It could also indicate stack corruption. + +@item FRAME_UNWIND_SAME_ID +This frame has the same ID as the previous one. That means +that unwinding further would almost certainly give us another +frame with exactly the same ID, so break the chain. Normally, +this is a sign of unwinder failure. It could also indicate +stack corruption. + +@item FRAME_UNWIND_NO_SAVED_PC +The frame unwinder did not find any saved PC, but we needed +one to unwind further. + +@item FRAME_UNWIND_MEMORY_ERROR +The frame unwinder caused an error while trying to access memory. + +@item FRAME_UNWIND_FIRST_ERROR +Any stop reason greater or equal to this value indicates some kind +of error. This special value facilitates writing code that tests +for errors in unwinding in a way that will work correctly even if +the list of the other values is modified in future @value{GDBN} +versions. Using it, you could write: + +@smallexample +(define reason (frame-unwind-stop-readon (selected-frame))) +(define reason-str (unwind-stop-reason-string reason)) +(if (>= reason FRAME_UNWIND_FIRST_ERROR) + (format #t "An error occurred: ~s\n" reason-str)) +@end smallexample +@end table +@end deffn + +@deffn {Scheme Procedure} frame-pc frame +Return the frame's resume address. +@end deffn + +@deffn {Scheme Procedure} frame-block frame +Return the frame's code block as a @code{} object. +@xref{Blocks In Guile}. +@end deffn + +@deffn {Scheme Procedure} frame-function frame +Return the symbol for the function corresponding to this frame +as a @code{} object, or @code{#f} if there isn't one. +@xref{Symbols In Guile}. +@end deffn + +@deffn {Scheme Procedure} frame-older frame +Return the frame that called @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-newer frame +Return the frame called by @var{frame}. +@end deffn + +@deffn {Scheme Procedure} frame-sal frame +Return the frame's @code{} (symtab and line) object. +@xref{Symbol Tables In Guile}. +@end deffn + +@deffn {Scheme Procedure} frame-read-register frame register +Return the value of @var{register} in @var{frame}. @var{register} +should be a string, like @samp{pc}. +@end deffn + +@deffn {Scheme Procedure} frame-read-var frame variable @r{[}#:block block@r{]} +Return the value of @var{variable} in @var{frame}. If the optional +argument @var{block} is provided, search for the variable from that +block; otherwise start at the frame's current block (which is +determined by the frame's current program counter). The +@var{variable} must be given as a string or a @code{} +object, and @var{block} must be a @code{} object. +@end deffn + +@deffn {Scheme Procedure} frame-select frame +Set @var{frame} to be the selected frame. @xref{Stack, ,Examining the +Stack}. +@end deffn + +@deffn {Scheme Procedure} selected-frame +Return the selected frame object. @xref{Selection,,Selecting a Frame}. +@end deffn + +@deffn {Scheme Procedure} newest-frame +Return the newest frame object for the selected thread. +@end deffn + +@deffn {Scheme Procedure} unwind-stop-reason-string reason +Return a string explaining the reason why @value{GDBN} stopped unwinding +frames, as expressed by the given @var{reason} code (an integer, see the +@code{frame-unwind-stop-reason} procedure above in this section). +@end deffn + +@node Blocks In Guile +@subsubsection Accessing blocks from Guile. + +@cindex blocks in guile +@tindex + +In @value{GDBN}, symbols are stored in blocks. A block corresponds +roughly to a scope in the source code. Blocks are organized +hierarchically, and are represented individually in Guile as an object +of type @code{}. Blocks rely on debugging information being +available. + +A frame has a block. Please see @ref{Frames In Guile}, for a more +in-depth discussion of frames. + +The outermost block is known as the @dfn{global block}. The global +block typically holds public global variables and functions. + +The block nested just inside the global block is the @dfn{static +block}. The static block typically holds file-scoped variables and +functions. + +@value{GDBN} provides a method to get a block's superblock, but there +is currently no way to examine the sub-blocks of a block, or to +iterate over all the blocks in a symbol table (@pxref{Symbol Tables In +Guile}). + +Here is a short example that should help explain blocks: + +@smallexample +/* This is in the global block. */ +int global; + +/* This is in the static block. */ +static int file_scope; + +/* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ +int function (int argument) +@{ + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + @{ + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + @} +@} +@end smallexample + +The following block-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} block? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} block-valid? block +Returns @code{#t} if @code{} @var{block} is valid, +@code{#f} if not. A block object can become invalid if the block it +refers to doesn't exist anymore in the inferior. All other +@code{} methods will throw an exception if it is invalid at +the time the procedure is called. The block's validity is also checked +during iteration over symbols of the block. +@end deffn + +@deffn {Scheme Procedure} block-start block +Return the start address of @code{} @var{block}. +@end deffn + +@deffn {Scheme Procedure} block-end block +Return the end address of @code{} @var{block}. +@end deffn + +@deffn {Scheme Procedure} block-function block +Return the name of @code{} @var{block} represented as a +@code{} object. +If the block is not named, then @code{#f} is returned. + +For ordinary function blocks, the superblock is the static block. +However, you should note that it is possible for a function block to +have a superblock that is not the static block -- for instance this +happens for an inlined function. +@end deffn + +@deffn {Scheme Procedure} block-superblock block +Return the block containing @code{} @var{block}. +If the parent block does not exist, then @code{#f} is returned. +@end deffn + +@deffn {Scheme Procedure} block-global-block block +Return the global block associated with @code{} @var{block}. +@end deffn + +@deffn {Scheme Procedure} block-static-block block +Return the static block associated with @code{} @var{block}. +@end deffn + +@deffn {Scheme Procedure} block-global? block +Return @code{#t} if @code{} @var{block} is a global block. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} block-static? block +Return @code{#t} if @code{} @var{block} is a static block. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} block-symbols +Return a list of all symbols (as objects) in +@code{} @var{block}. +@end deffn + +@deffn {Scheme Procedure} make-block-symbols-iterator block +Return an object of type @code{} that will iterate +over all symbols of the block. +Guile programs should not assume that a specific block object will +always contain a given symbol, since changes in @value{GDBN} features and +infrastructure may cause symbols move across blocks in a symbol table. +@xref{Iterators In Guile}. +@end deffn + +@deffn {Scheme Procedure} block-symbols-progress? +Return #t if the object is a object. +This object would be obtained from the @code{progress} element of the +@code{} object returned by @code{make-block-symbols-iterator}. +@end deffn + +@deffn {Scheme Procedure} lookup-block pc +Return the innermost @code{} containing the given @var{pc} +value. If the block cannot be found for the @var{pc} value specified, +the function will return @code{#f}. +@end deffn + +@node Symbols In Guile +@subsubsection Guile representation of Symbols. + +@cindex symbols in guile +@tindex + +@value{GDBN} represents every variable, function and type as an +entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}. +Guile represents these symbols in @value{GDBN} with the +@code{} object. + +The following symbol-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} symbol? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symbol-valid? symbol +Return @code{#t} if the @code{} object is valid, +@code{#f} if not. A @code{} object can become invalid if +the symbol it refers to does not exist in @value{GDBN} any longer. +All other @code{} procedures will throw an exception if it is +invalid at the time the procedure is called. +@end deffn + +@deffn {Scheme Procedure} symbol-type symbol +Return the type of @var{symbol} or @code{#f} if no type is recorded. +The result is an object of type @code{}. +@xref{Types In Guile}. +@end deffn + +@deffn {Scheme Procedure} symbol-symtab symbol +Return the symbol table in which @var{symbol} appears. +The result is an object of type @code{}. +@xref{Symbol Tables In Guile}. +@end deffn + +@deffn {Scheme Procedure} symbol-line symbol +Return the line number in the source code at which @var{symbol} was defined. +This is an integer. +@end deffn + +@deffn {Scheme Procedure} symbol-name symbol +Return the name of @var{symbol} as a string. +@end deffn + +@deffn {Scheme Procedure} symbol-linkage-name symbol +Return the name of @var{symbol}, as used by the linker (i.e., may be mangled). +@end deffn + +@deffn {Scheme Procedure} symbol-print-name symbol +Return the name of @var{symbol} in a form suitable for output. This is either +@code{name} or @code{linkage_name}, depending on whether the user +asked @value{GDBN} to display demangled or mangled names. +@end deffn + +@deffn {Scheme Procedure} symbol-addr-class symbol +Return the address class of the symbol. This classifies how to find the value +of a symbol. Each address class is a constant defined in the +@code{(gdb)} module and described later in this chapter. +@end deffn + +@deffn {Scheme Procedure} symbol-needs-frame? symbol +Return @code{#t} if evaluating @var{symbol}'s value requires a frame +(@pxref{Frames In Guile}) and @code{#f} otherwise. Typically, +local variables will require a frame, but other symbols will not. +@end deffn + +@deffn {Scheme Procedure} symbol-argument? symbol +Return @code{#t} if @var{symbol} is an argument of a function. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symbol-constant? symbol +Return @code{#t} if @var{symbol} is a constant. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symbol-function? symbol +Return @code{#t} if @var{symbol} is a function or a method. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symbol-variable? symbol +Return @code{#t} if @var{symbol} is a variable. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symbol-value symbol @r{[}#:frame frame@r{]} +Compute the value of @var{symbol}, as a @code{}. For +functions, this computes the address of the function, cast to the +appropriate type. If the symbol requires a frame in order to compute +its value, then @var{frame} must be given. If @var{frame} is not +given, or if @var{frame} is invalid, then an exception is thrown. +@end deffn + +@deffn {Scheme Procedure} lookup-symbol name @w{@r{[}#:block block@r{]}} @ + @w{@r{[}#:domain domain@r{]}} +This function searches for a symbol by name. The search scope can be +restricted to the parameters defined in the optional domain and block +arguments. + +@var{name} is the name of the symbol. It must be a string. The +optional @var{block} argument restricts the search to symbols visible +in that @var{block}. The @var{block} argument must be a +@code{} object. If omitted, the block for the current frame +is used. The optional @var{domain} argument restricts +the search to the domain type. The @var{domain} argument must be a +domain constant defined in the @code{(gdb)} module and described later +in this chapter. + +The result is a list of two elements. +The first element is a @code{} object or @code{#f} if the symbol +is not found. +If the symbol is found, the second element is @code{#t} if the symbol +is a field of a method's object (e.g., @code{this} in C@t{++}), +otherwise it is @code{#f}. +If the symbol is not found, the second element is @code{#f}. +@end deffn + +@deffn {Scheme Procedure} lookup-global-symbol name @r{[}#:domain domain@r{]} +This function searches for a global symbol by name. +The search scope can be restricted by the domain argument. + +@var{name} is the name of the symbol. It must be a string. +The optional @var{domain} argument restricts the search to the domain type. +The @var{domain} argument must be a domain constant defined in the @code{(gdb)} +module and described later in this chapter. + +The result is a @code{} object or @code{#f} if the symbol +is not found. +@end deffn + +The available domain categories in @code{} are represented +as constants in the @code{(gdb)} module: + +@vtable @code +@item SYMBOL_UNDEF_DOMAIN +This is used when a domain has not been discovered or none of the +following domains apply. This usually indicates an error either +in the symbol information or in @value{GDBN}'s handling of symbols. + +@item SYMBOL_VAR_DOMAIN +This domain contains variables, function names, typedef names and enum +type values. + +@item SYMBOL_FUNCTION_DOMAIN +This domain contains functions. + +@item SYMBOL_TYPE_DOMAIN +This domain contains types. In a C-like language, types using a tag +(the name appearing after a @code{struct}, @code{union}, or +@code{enum} keyword) will not appear here; in other languages, all +types are in this domain. + +@item SYMBOL_STRUCT_DOMAIN +This domain holds struct, union and enum tag names. This domain is +only used for C-like languages. For example, in this code: +@smallexample +struct type_one @{ int x; @}; +typedef struct type_one type_two; +@end smallexample +Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but +@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}. + +@item SYMBOL_LABEL_DOMAIN +This domain contains names of labels (for gotos). + +@item SYMBOL_VARIABLES_DOMAIN +This domain holds a subset of the @code{SYMBOLS_VAR_DOMAIN}; it +contains everything minus functions and types. + +@item SYMBOL_FUNCTIONS_DOMAIN +This domain contains all functions. + +@item SYMBOL_TYPES_DOMAIN +This domain contains all types. +@end vtable + +The available address class categories in @code{} are represented +as constants in the @code{gdb} module: + +When searching for a symbol, the desired domain constant can be passed +verbatim to the lookup function. + +For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the +@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example, +@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a +search constant. + +@vtable @code +@item SYMBOL_LOC_UNDEF +If this is returned by address class, it indicates an error either in +the symbol information or in @value{GDBN}'s handling of symbols. + +@item SYMBOL_LOC_CONST +Value is constant int. + +@item SYMBOL_LOC_STATIC +Value is at a fixed address. + +@item SYMBOL_LOC_REGISTER +Value is in a register. + +@item SYMBOL_LOC_ARG +Value is an argument. This value is at the offset stored within the +symbol inside the frame's argument list. + +@item SYMBOL_LOC_REF_ARG +Value address is stored in the frame's argument list. Just like +@code{LOC_ARG} except that the value's address is stored at the +offset, not the value itself. + +@item SYMBOL_LOC_REGPARM_ADDR +Value is a specified register. Just like @code{LOC_REGISTER} except +the register holds the address of the argument instead of the argument +itself. + +@item SYMBOL_LOC_LOCAL +Value is a local variable. + +@item SYMBOL_LOC_TYPEDEF +Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all +have this class. + +@item SYMBOL_LOC_BLOCK +Value is a block. + +@item SYMBOL_LOC_CONST_BYTES +Value is a byte-sequence. + +@item SYMBOL_LOC_UNRESOLVED +Value is at a fixed address, but the address of the variable has to be +determined from the minimal symbol table whenever the variable is +referenced. + +@item SYMBOL_LOC_OPTIMIZED_OUT +The value does not actually exist in the program. + +@item SYMBOL_LOC_COMPUTED +The value's address is a computed location. +@end vtable + +@node Symbol Tables In Guile +@subsubsection Symbol table representation in Guile. + +@cindex symbol tables in guile +@tindex +@tindex + +Access to symbol table data maintained by @value{GDBN} on the inferior +is exposed to Guile via two objects: @code{} (symtab-and-line) and +@code{}. Symbol table and line data for a frame is returned +from the @code{frame-find-sal} @code{} procedure. +@xref{Frames In Guile}. + +For more information on @value{GDBN}'s symbol table management, see +@ref{Symbols, ,Examining the Symbol Table}. + +The following symtab-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} symtab? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} symtab-valid? symtab +Return @code{#t} if the @code{} object is valid, +@code{#f} if not. A @code{} object becomes invalid when +the symbol table it refers to no longer exists in @value{GDBN}. +All other @code{} procedures will throw an exception +if it is invalid at the time the procedure is called. +@end deffn + +@deffn {Scheme Procedure} symtab-filename symtab +Return the symbol table's source filename. +@end deffn + +@deffn {Scheme Procedure} symtab-fullname symtab +Return the symbol table's source absolute file name. +@end deffn + +@deffn {Scheme Procedure} symtab-objfile symtab +Return the symbol table's backing object file. @xref{Objfiles In Guile}. +@end deffn + +@deffn {Scheme Procedure} symtab-global-block symtab +Return the global block of the underlying symbol table. +@xref{Blocks In Guile}. +@end deffn + +@deffn {Scheme Procedure} symtab-static-block symtab +Return the static block of the underlying symbol table. +@xref{Blocks In Guile}. +@end deffn + +The following symtab-and-line-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} sal? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} sal-valid? sal +Return @code{#t} if @var{sal} is valid, @code{#f} if not. +A @code{} object becomes invalid when the Symbol table object +it refers to no longer exists in @value{GDBN}. All other +@code{} procedures will throw an exception if it is +invalid at the time the procedure is called. +@end deffn + +@deffn {Scheme Procedure} sal-symtab sal +Return the symbol table object (@code{}) for @var{sal}. +@end deffn + +@deffn {Scheme Procedure} sal-line sal +Return the line number for @var{sal}. +@end deffn + +@deffn {Scheme Procedure} sal-pc sal +Return the start of the address range occupied by code for @var{sal}. +@end deffn + +@deffn {Scheme Procedure} sal-last sal +Return the end of the address range occupied by code for @var{sal}. +@end deffn + +@deffn {Scheme Procedure} find-pc-line pc +Return the @code{} object corresponding to the @var{pc} value. +If an invalid value of @var{pc} is passed as an argument, then the +@code{symtab} and @code{line} attributes of the returned @code{} +object will be @code{#f} and 0 respectively. +@end deffn + +@node Breakpoints In Guile +@subsubsection Manipulating breakpoints using Guile + +@cindex breakpoints in guile +@tindex + +Breakpoints in Guile are represented by objects of type +@code{}. New breakpoints can be created with the +@code{make-breakpoint} Guile function, and then added to @value{GDBN} with the +@code{register-breakpoint!} Guile function. +This two-step approach is taken to separate out the side-effect of adding +the breakpoint to @value{GDBN} from @code{make-breakpoint}. + +Support is also provided to view and manipulate breakpoints created +outside of Guile. + +The following breakpoint-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} make-breakpoint location @w{@r{[}#:type type@r{]}} @ + @w{@r{[}#:wp-class wp-class@r{]}} @w{@r{[}#:internal internal@r{]}} @ + @w{@r{[}#:temporary temporary@r{]}} +Create a new breakpoint at @var{location}, a string naming the +location of the breakpoint, or an expression that defines a watchpoint. +The contents can be any location recognized by the @code{break} command, +or in the case of a watchpoint, by the @code{watch} command. + +The breakpoint is initially marked as @samp{invalid}. +The breakpoint is not usable until it has been registered with @value{GDBN} +with @code{register-breakpoint!}, at which point it becomes @samp{valid}. +The result is the @code{} object representing the breakpoint. + +The optional @var{type} denotes the breakpoint to create. +This argument can be either @code{BP_BREAKPOINT} or @code{BP_WATCHPOINT}, +and defaults to @code{BP_BREAKPOINT}. + +The optional @var{wp-class} argument defines the class of watchpoint to +create, if @var{type} is @code{BP_WATCHPOINT}. If a watchpoint class is +not provided, it is assumed to be a @code{WP_WRITE} class. + +The optional @var{internal} argument allows the breakpoint to become +invisible to the user. The breakpoint will neither be reported when +registered, nor will it be listed in the output from @code{info breakpoints} +(but will be listed with the @code{maint info breakpoints} command). +If an internal flag is not provided, the breakpoint is visible +(non-internal). + +The optional @var{temporary} argument makes the breakpoint a temporary +breakpoint. Temporary breakpoints are deleted after they have been hit, +after which the Guile breakpoint is no longer usable (although it may be +re-registered with @code{register-breakpoint!}). + +When a watchpoint is created, @value{GDBN} will try to create a +hardware assisted watchpoint. If successful, the type of the watchpoint +is changed from @code{BP_WATCHPOINT} to @code{BP_HARDWARE_WATCHPOINT} +for @code{WP_WRITE}, @code{BP_READ_WATCHPOINT} for @code{WP_READ}, +and @code{BP_ACCESS_WATCHPOINT} for @code{WP_ACCESS}. +If not successful, the type of the watchpoint is left as @code{WP_WATCHPOINT}. + +The available types are represented by constants defined in the @code{gdb} +module: + +@vtable @code +@item BP_BREAKPOINT +Normal code breakpoint. + +@item BP_WATCHPOINT +Watchpoint breakpoint. + +@item BP_HARDWARE_WATCHPOINT +Hardware assisted watchpoint. +This value cannot be specified when creating the breakpoint. + +@item BP_READ_WATCHPOINT +Hardware assisted read watchpoint. +This value cannot be specified when creating the breakpoint. + +@item BP_ACCESS_WATCHPOINT +Hardware assisted access watchpoint. +This value cannot be specified when creating the breakpoint. + +@item BP_CATCHPOINT +Catchpoint. +This value cannot be specified when creating the breakpoint. +@end vtable + +The available watchpoint types are represented by constants defined in the +@code{(gdb)} module: + +@vtable @code +@item WP_READ +Read only watchpoint. + +@item WP_WRITE +Write only watchpoint. + +@item WP_ACCESS +Read/Write watchpoint. +@end vtable + +@end deffn + +@deffn {Scheme Procedure} register-breakpoint! breakpoint +Add @var{breakpoint}, a @code{} object, to @value{GDBN}'s +list of breakpoints. The breakpoint must have been created with +@code{make-breakpoint}. One cannot register breakpoints that have been +created outside of Guile. Once a breakpoint is registered it becomes +@samp{valid}. +It is an error to register an already registered breakpoint. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} delete-breakpoint! breakpoint +Remove @var{breakpoint} from @value{GDBN}'s list of breakpoints. +This also invalidates the Guile @var{breakpoint} object. +Any further attempt to access the object will throw an exception. + +If @var{breakpoint} was created from Guile with @code{make-breakpoint} +it may be re-registered with @value{GDBN}, in which case the breakpoint +becomes valid again. +@end deffn + +@deffn {Scheme Procedure} breakpoints +Return a list of all breakpoints. +Each element of the list is a @code{} object. +@end deffn + +@deffn {Scheme Procedure} breakpoint? object +Return @code{#t} if @var{object} is a @code{} object, +and @code{#f} otherwise. +@end deffn + +@deffn {Scheme Procedure} breakpoint-valid? breakpoint +Return @code{#t} if @var{breakpoint} is valid, @code{#f} otherwise. +Breakpoints created with @code{make-breakpoint} are marked as invalid +until they are registered with @value{GDBN} with @code{register-breakpoint!}. +A @code{} object can become invalid +if the user deletes the breakpoint. In this case, the object still +exists, but the underlying breakpoint does not. In the cases of +watchpoint scope, the watchpoint remains valid even if execution of the +inferior leaves the scope of that watchpoint. +@end deffn + +@deffn {Scheme Procedure} breakpoint-number breakpoint +Return the breakpoint's number --- the identifier used by +the user to manipulate the breakpoint. +@end deffn + +@deffn {Scheme Procedure} breakpoint-temporary? breakpoint +Return @code{#t} if the breakpoint was created as a temporary +breakpoint. Temporary breakpoints are automatically deleted after +they've been hit. Calling this procedure, and all other procedures +other than @code{breakpoint-valid?} and @code{register-breakpoint!}, +will result in an error after the breakpoint has been hit (since it has +been automatically deleted). +@end deffn + +@deffn {Scheme Procedure} breakpoint-type breakpoint +Return the breakpoint's type --- the identifier used to +determine the actual breakpoint type or use-case. +@end deffn + +@deffn {Scheme Procedure} breakpoint-visible? breakpoint +Return @code{#t} if the breakpoint is visible to the user +when hit, or when the @samp{info breakpoints} command is run. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} breakpoint-location breakpoint +Return the location of the breakpoint, as specified by +the user. It is a string. If the breakpoint does not have a location +(that is, it is a watchpoint) return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} breakpoint-expression breakpoint +Return the breakpoint expression, as specified by the user. It is a string. +If the breakpoint does not have an expression (the breakpoint is not a +watchpoint) return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} breakpoint-enabled? breakpoint +Return @code{#t} if the breakpoint is enabled, and @code{#f} otherwise. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-enabled! breakpoint flag +Set the enabled state of @var{breakpoint} to @var{flag}. +If flag is @code{#f} it is disabled, otherwise it is enabled. +@end deffn + +@deffn {Scheme Procedure} breakpoint-silent? breakpoint +Return @code{#t} if the breakpoint is silent, and @code{#f} otherwise. + +Note that a breakpoint can also be silent if it has commands and the +first command is @code{silent}. This is not reported by the +@code{silent} attribute. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-silent! breakpoint flag +Set the silent state of @var{breakpoint} to @var{flag}. +If flag is @code{#f} the breakpoint is made silent, +otherwise it is made non-silent (or noisy). +@end deffn + +@deffn {Scheme Procedure} breakpoint-ignore-count breakpoint +Return the ignore count for @var{breakpoint}. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-ignore-count! breakpoint count +Set the ignore count for @var{breakpoint} to @var{count}. +@end deffn + +@deffn {Scheme Procedure} breakpoint-hit-count breakpoint +Return hit count of @var{breakpoint}. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-hit-count! breakpoint count +Set the hit count of @var{breakpoint} to @var{count}. +At present, @var{count} must be zero. +@end deffn + +@deffn {Scheme Procedure} breakpoint-thread breakpoint +Return the global-thread-id for thread-specific breakpoint +@var{breakpoint}. Return #f if @var{breakpoint} is not +thread-specific. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-thread! breakpoint global-thread-id|#f +Set the thread-id for @var{breakpoint} to @var{global-thread-id} If +set to @code{#f}, the breakpoint is no longer thread-specific. +@end deffn + +@deffn {Scheme Procedure} breakpoint-task breakpoint +If the breakpoint is Ada task-specific, return the Ada task id. +If the breakpoint is not task-specific (or the underlying +language is not Ada), return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-task! breakpoint task +Set the Ada task of @var{breakpoint} to @var{task}. +If set to @code{#f}, the breakpoint is no longer task-specific. +@end deffn + +@deffn {Scheme Procedure} breakpoint-condition breakpoint +Return the condition of @var{breakpoint}, as specified by the user. +It is a string. If there is no condition, return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-condition! breakpoint condition +Set the condition of @var{breakpoint} to @var{condition}, +which must be a string. If set to @code{#f} then the breakpoint +becomes unconditional. +@end deffn + +@deffn {Scheme Procedure} breakpoint-stop breakpoint +Return the stop predicate of @var{breakpoint}. +See @code{set-breakpoint-stop!} below in this section. +@end deffn + +@deffn {Scheme Procedure} set-breakpoint-stop! breakpoint procedure|#f +Set the stop predicate of @var{breakpoint}. The predicate +@var{procedure} takes one argument: the object. +If this predicate is set to a procedure then it is invoked whenever +the inferior reaches this breakpoint. If it returns @code{#t}, +or any non-@code{#f} value, then the inferior is stopped, +otherwise the inferior will continue. + +If there are multiple breakpoints at the same location with a +@code{stop} predicate, each one will be called regardless of the +return status of the previous. This ensures that all @code{stop} +predicates have a chance to execute at that location. In this scenario +if one of the methods returns @code{#t} but the others return +@code{#f}, the inferior will still be stopped. + +You should not alter the execution state of the inferior (i.e.@:, step, +next, etc.), alter the current frame context (i.e.@:, change the current +active frame), or alter, add or delete any breakpoint. As a general +rule, you should not alter any data within @value{GDBN} or the inferior +at this time. + +Example @code{stop} implementation: + +@smallexample +(define (my-stop? bkpt) + (let ((int-val (parse-and-eval "foo"))) + (value=? int-val 3))) +(define bkpt (make-breakpoint "main.c:42")) +(register-breakpoint! bkpt) +(set-breakpoint-stop! bkpt my-stop?) +@end smallexample +@end deffn + +@deffn {Scheme Procedure} breakpoint-commands breakpoint +Return the commands attached to @var{breakpoint} as a string, +or @code{#f} if there are none. +@end deffn + +@node Lazy Strings In Guile +@subsubsection Guile representation of lazy strings. + +@cindex lazy strings in guile +@tindex + +A @dfn{lazy string} is a string whose contents is not retrieved or +encoded until it is needed. + +A @code{} is represented in @value{GDBN} as an +@code{address} that points to a region of memory, an @code{encoding} +that will be used to encode that region of memory, and a @code{length} +to delimit the region of memory that represents the string. The +difference between a @code{} and a string wrapped within +a @code{} is that a @code{} will be treated +differently by @value{GDBN} when printing. A @code{} is +retrieved and encoded during printing, while a @code{} +wrapping a string is immediately retrieved and encoded on creation. + +The following lazy-string-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} lazy-string? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} lazy-string-address lazy-sring +Return the address of @var{lazy-string}. +@end deffn + +@deffn {Scheme Procedure} lazy-string-length lazy-string +Return the length of @var{lazy-string} in characters. If the +length is -1, then the string will be fetched and encoded up to the +first null of appropriate width. +@end deffn + +@deffn {Scheme Procedure} lazy-string-encoding lazy-string +Return the encoding that will be applied to @var{lazy-string} +when the string is printed by @value{GDBN}. If the encoding is not +set, or contains an empty string, then @value{GDBN} will select the +most appropriate encoding when the string is printed. +@end deffn + +@deffn {Scheme Procedure} lazy-string-type lazy-string +Return the type that is represented by @var{lazy-string}'s type. +For a lazy string this is a pointer or array type. To +resolve this to the lazy string's character type, use @code{type-target-type}. +@xref{Types In Guile}. +@end deffn + +@deffn {Scheme Procedure} lazy-string->value lazy-string +Convert the @code{} to a @code{}. This value +will point to the string in memory, but will lose all the delayed +retrieval, encoding and handling that @value{GDBN} applies to a +@code{}. +@end deffn + +@node Architectures In Guile +@subsubsection Guile representation of architectures + +@cindex guile architectures +@tindex + +@value{GDBN} uses architecture specific parameters and artifacts in a +number of its various computations. An architecture is represented +by an instance of the @code{} class. + +The following architecture-related procedures are provided by the +@code{(gdb)} module: + +@deffn {Scheme Procedure} arch? object +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} current-arch +Return the current architecture as a @code{} object. +@end deffn + +@deffn {Scheme Procedure} arch-name arch +Return the name (string value) of @code{} @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-charset arch +Return name of target character set of @code{} @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-wide-charset +Return name of target wide character set of @code{} @var{arch}. +@end deffn + +Each architecture provides a set of predefined types, obtained by +the following functions. + +@deffn {Scheme Procedure} arch-void-type arch +Return the @code{} object for a @code{void} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-char-type arch +Return the @code{} object for a @code{char} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-short-type arch +Return the @code{} object for a @code{short} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-int-type arch +Return the @code{} object for an @code{int} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-long-type arch +Return the @code{} object for a @code{long} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-schar-type arch +Return the @code{} object for a @code{signed char} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uchar-type arch +Return the @code{} object for an @code{unsigned char} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-ushort-type arch +Return the @code{} object for an @code{unsigned short} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uint-type arch +Return the @code{} object for an @code{unsigned int} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-ulong-type arch +Return the @code{} object for an @code{unsigned long} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-float-type arch +Return the @code{} object for a @code{float} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-double-type arch +Return the @code{} object for a @code{double} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-longdouble-type arch +Return the @code{} object for a @code{long double} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-bool-type arch +Return the @code{} object for a @code{bool} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-longlong-type arch +Return the @code{} object for a @code{long long} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-ulonglong-type arch +Return the @code{} object for an @code{unsigned long long} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-int8-type arch +Return the @code{} object for an @code{int8} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uint8-type arch +Return the @code{} object for a @code{uint8} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-int16-type arch +Return the @code{} object for an @code{int16} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uint16-type arch +Return the @code{} object for a @code{uint16} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-int32-type arch +Return the @code{} object for an @code{int32} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uint32-type arch +Return the @code{} object for a @code{uint32} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-int64-type arch +Return the @code{} object for an @code{int64} type +of architecture @var{arch}. +@end deffn + +@deffn {Scheme Procedure} arch-uint64-type arch +Return the @code{} object for a @code{uint64} type +of architecture @var{arch}. +@end deffn + +Example: + +@smallexample +(gdb) guile (type-name (arch-uchar-type (current-arch))) +"unsigned char" +@end smallexample + +@node Disassembly In Guile +@subsubsection Disassembly In Guile + +The disassembler can be invoked from Scheme code. +Furthermore, the disassembler can take a Guile port as input, +allowing one to disassemble from any source, and not just target memory. + +@deffn {Scheme Procedure} arch-disassemble arch start-pc @ + @w{@r{[}#:port port@r{]}} @w{@r{[}#:offset offset@r{]}} @ + @w{@r{[}#:size size@r{]}} @w{@r{[}#:count count@r{]}} +Return a list of disassembled instructions starting from the memory +address @var{start-pc}. + +The optional argument @var{port} specifies the input port to read bytes from. +If @var{port} is @code{#f} then bytes are read from target memory. + +The optional argument @var{offset} specifies the address offset of the +first byte in @var{port}. This is useful, for example, when @var{port} +specifies a @samp{bytevector} and you want the bytevector to be disassembled +as if it came from that address. The @var{start-pc} passed to the reader +for @var{port} is offset by the same amount. + +Example: +@smallexample +(gdb) guile (use-modules (rnrs io ports)) +(gdb) guile (define pc (value->integer (parse-and-eval "$pc"))) +(gdb) guile (define mem (open-memory #:start pc)) +(gdb) guile (define bv (get-bytevector-n mem 10)) +(gdb) guile (define bv-port (open-bytevector-input-port bv)) +(gdb) guile (define arch (current-arch)) +(gdb) guile (arch-disassemble arch pc #:port bv-port #:offset pc) +(((address . 4195516) (asm . "mov $0x4005c8,%edi") (length . 5))) +@end smallexample + +The optional arguments @var{size} and +@var{count} determine the number of instructions in the returned list. +If either @var{size} or @var{count} is specified as zero, then +no instructions are disassembled and an empty list is returned. +If both the optional arguments @var{size} and @var{count} are +specified, then a list of at most @var{count} disassembled instructions +whose start address falls in the closed memory address interval from +@var{start-pc} to (@var{start-pc} + @var{size} - 1) are returned. +If @var{size} is not specified, but @var{count} is specified, +then @var{count} number of instructions starting from the address +@var{start-pc} are returned. If @var{count} is not specified but +@var{size} is specified, then all instructions whose start address +falls in the closed memory address interval from @var{start-pc} to +(@var{start-pc} + @var{size} - 1) are returned. +If neither @var{size} nor @var{count} are specified, then a single +instruction at @var{start-pc} is returned. + +Each element of the returned list is an alist (associative list) +with the following keys: + +@table @code + +@item address +The value corresponding to this key is a Guile integer of +the memory address of the instruction. + +@item asm +The value corresponding to this key is a string value which represents +the instruction with assembly language mnemonics. The assembly +language flavor used is the same as that specified by the current CLI +variable @code{disassembly-flavor}. @xref{Machine Code}. + +@item length +The value corresponding to this key is the length of the instruction in bytes. + +@end table +@end deffn + +@node I/O Ports in Guile +@subsubsection I/O Ports in Guile + +@deffn {Scheme Procedure} input-port +Return @value{GDBN}'s input port as a Guile port object. +@end deffn + +@deffn {Scheme Procedure} output-port +Return @value{GDBN}'s output port as a Guile port object. +@end deffn + +@deffn {Scheme Procedure} error-port +Return @value{GDBN}'s error port as a Guile port object. +@end deffn + +@deffn {Scheme Procedure} stdio-port? object +Return @code{#t} if @var{object} is a @value{GDBN} stdio port. +Otherwise return @code{#f}. +@end deffn + +@node Memory Ports in Guile +@subsubsection Memory Ports in Guile + +@value{GDBN} provides a @code{port} interface to target memory. +This allows Guile code to read/write target memory using Guile's port and +bytevector functionality. The main routine is @code{open-memory} which +returns a port object. One can then read/write memory using that object. + +@deffn {Scheme Procedure} open-memory @w{@r{[}#:mode mode@r{]}} @ + @w{@r{[}#:start address@r{]}} @w{@r{[}#:size size@r{]}} +Return a port object that can be used for reading and writing memory. +The port will be open according to @var{mode}, which is the standard +mode argument to Guile port open routines, except that the @samp{"a"} +and @samp{"l"} modes are not supported. +@xref{File Ports,,, guile, GNU Guile Reference Manual}. +The @samp{"b"} (binary) character may be present, but is ignored: +memory ports are binary only. If @samp{"0"} is appended then +the port is marked as unbuffered. +The default is @samp{"r"}, read-only and buffered. + +The chunk of memory that can be accessed can be bounded. +If both @var{start} and @var{size} are unspecified, all of memory can be +accessed. If only @var{start} is specified, all of memory from that point +on can be accessed. If only @var{size} if specified, all memory in the +range [0,@var{size}) can be accessed. If both are specified, all memory +in the rane [@var{start},@var{start}+@var{size}) can be accessed. +@end deffn + +@deffn {Scheme Procedure} memory-port? +Return @code{#t} if @var{object} is an object of type @code{}. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} memory-port-range memory-port +Return the range of @code{} @var{memory-port} as a list +of two elements: @code{(start end)}. The range is @var{start} to @var{end} +inclusive. +@end deffn + +@deffn {Scheme Procedure} memory-port-read-buffer-size memory-port +Return the size of the read buffer of @code{} +@var{memory-port}. + +This procedure is deprecated and will be removed in @value{GDBN} 11. +It returns 0 when using Guile 2.2 or later. +@end deffn + +@deffn {Scheme Procedure} set-memory-port-read-buffer-size! memory-port size +Set the size of the read buffer of @code{} +@var{memory-port} to @var{size}. The result is unspecified. + +This procedure is deprecated and will be removed in @value{GDBN} 11. +When @value{GDBN} is built with Guile 2.2 or later, you can call +@code{setvbuf} instead (@pxref{Buffering, @code{setvbuf},, guile, GNU +Guile Reference Manual}). +@end deffn + +@deffn {Scheme Procedure} memory-port-write-buffer-size memory-port +Return the size of the write buffer of @code{} +@var{memory-port}. + +This procedure is deprecated and will be removed in @value{GDBN} 11. +It returns 0 when @value{GDBN} is built with Guile 2.2 or later. +@end deffn + +@deffn {Scheme Procedure} set-memory-port-write-buffer-size! memory-port size +Set the size of the write buffer of @code{} +@var{memory-port} to @var{size}. The result is unspecified. + +This procedure is deprecated and will be removed in @value{GDBN} 11. +When @value{GDBN} is built with Guile 2.2 or later, you can call +@code{setvbuf} instead. +@end deffn + +A memory port is closed like any other port, with @code{close-port}. + +Combined with Guile's @code{bytevectors}, memory ports provide a lot +of utility. For example, to fill a buffer of 10 integers in memory, +one can do something like the following. + +@smallexample +;; In the program: int buffer[10]; +(use-modules (rnrs bytevectors)) +(use-modules (rnrs io ports)) +(define addr (parse-and-eval "buffer")) +(define n 10) +(define byte-size (* n 4)) +(define mem-port (open-memory #:mode "r+" #:start + (value->integer addr) #:size byte-size)) +(define byte-vec (make-bytevector byte-size)) +(do ((i 0 (+ i 1))) + ((>= i n)) + (bytevector-s32-native-set! byte-vec (* i 4) (* i 42))) +(put-bytevector mem-port byte-vec) +(close-port mem-port) +@end smallexample + +@node Iterators In Guile +@subsubsection Iterators In Guile + +@cindex guile iterators +@tindex + +A simple iterator facility is provided to allow, for example, +iterating over the set of program symbols without having to first +construct a list of all of them. A useful contribution would be +to add support for SRFI 41 and SRFI 45. + +@deffn {Scheme Procedure} make-iterator object progress next! +A @code{} object is constructed with the @code{make-iterator} +procedure. It takes three arguments: the object to be iterated over, +an object to record the progress of the iteration, and a procedure to +return the next element in the iteration, or an implementation chosen value +to denote the end of iteration. + +By convention, end of iteration is marked with @code{(end-of-iteration)}, +and may be tested with the @code{end-of-iteration?} predicate. +The result of @code{(end-of-iteration)} is chosen so that it is not +otherwise used by the @code{(gdb)} module. If you are using +@code{} in your own code it is your responsibility to +maintain this invariant. + +A trivial example for illustration's sake: + +@smallexample +(use-modules (gdb iterator)) +(define my-list (list 1 2 3)) +(define iter + (make-iterator my-list my-list + (lambda (iter) + (let ((l (iterator-progress iter))) + (if (eq? l '()) + (end-of-iteration) + (begin + (set-iterator-progress! iter (cdr l)) + (car l))))))) +@end smallexample + +Here is a slightly more realistic example, which computes a list of all the +functions in @code{my-global-block}. + +@smallexample +(use-modules (gdb iterator)) +(define this-sal (find-pc-line (frame-pc (selected-frame)))) +(define this-symtab (sal-symtab this-sal)) +(define this-global-block (symtab-global-block this-symtab)) +(define syms-iter (make-block-symbols-iterator this-global-block)) +(define functions (iterator-filter symbol-function? syms-iter)) +@end smallexample +@end deffn + +@deffn {Scheme Procedure} iterator? object +Return @code{#t} if @var{object} is a @code{} object. +Otherwise return @code{#f}. +@end deffn + +@deffn {Scheme Procedure} iterator-object iterator +Return the first argument that was passed to @code{make-iterator}. +This is the object being iterated over. +@end deffn + +@deffn {Scheme Procedure} iterator-progress iterator +Return the object tracking iteration progress. +@end deffn + +@deffn {Scheme Procedure} set-iterator-progress! iterator new-value +Set the object tracking iteration progress. +@end deffn + +@deffn {Scheme Procedure} iterator-next! iterator +Invoke the procedure that was the third argument to @code{make-iterator}, +passing it one argument, the @code{} object. +The result is either the next element in the iteration, or an end +marker as implemented by the @code{next!} procedure. +By convention the end marker is the result of @code{(end-of-iteration)}. +@end deffn + +@deffn {Scheme Procedure} end-of-iteration +Return the Scheme object that denotes end of iteration. +@end deffn + +@deffn {Scheme Procedure} end-of-iteration? object +Return @code{#t} if @var{object} is the end of iteration marker. +Otherwise return @code{#f}. +@end deffn + +These functions are provided by the @code{(gdb iterator)} module to +assist in using iterators. + +@deffn {Scheme Procedure} make-list-iterator list +Return a @code{} object that will iterate over @var{list}. +@end deffn + +@deffn {Scheme Procedure} iterator->list iterator +Return the elements pointed to by @var{iterator} as a list. +@end deffn + +@deffn {Scheme Procedure} iterator-map proc iterator +Return the list of objects obtained by applying @var{proc} to the object +pointed to by @var{iterator} and to each subsequent object. +@end deffn + +@deffn {Scheme Procedure} iterator-for-each proc iterator +Apply @var{proc} to each element pointed to by @var{iterator}. +The result is unspecified. +@end deffn + +@deffn {Scheme Procedure} iterator-filter pred iterator +Return the list of elements pointed to by @var{iterator} that satisfy +@var{pred}. +@end deffn + +@deffn {Scheme Procedure} iterator-until pred iterator +Run @var{iterator} until the result of @code{(pred element)} is true +and return that as the result. Otherwise return @code{#f}. +@end deffn + +@node Guile Auto-loading +@subsection Guile Auto-loading +@cindex guile auto-loading + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for Guile support scripts in two ways: +@file{@var{objfile}-gdb.scm} and the @code{.debug_gdb_scripts} section. +@xref{Auto-loading extensions}. + +The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. + +@table @code +@anchor{set auto-load guile-scripts} +@kindex set auto-load guile-scripts +@item set auto-load guile-scripts [on|off] +Enable or disable the auto-loading of Guile scripts. + +@anchor{show auto-load guile-scripts} +@kindex show auto-load guile-scripts +@item show auto-load guile-scripts +Show whether auto-loading of Guile scripts is enabled or disabled. + +@anchor{info auto-load guile-scripts} +@kindex info auto-load guile-scripts +@cindex print list of auto-loaded Guile scripts +@item info auto-load guile-scripts [@var{regexp}] +Print the list of all Guile scripts that @value{GDBN} auto-loaded. + +Also printed is the list of Guile scripts that were mentioned in +the @code{.debug_gdb_scripts} section and were not found. +This is useful because their names are not printed when @value{GDBN} +tries to load them and fails. There may be many of them, and printing +an error message for each one is problematic. + +If @var{regexp} is supplied only Guile scripts with matching names are printed. + +Example: + +@smallexample +(gdb) info auto-load guile-scripts +Loaded Script +Yes scm-section-script.scm + full name: /tmp/scm-section-script.scm +No my-foo-pretty-printers.scm +@end smallexample +@end table + +When reading an auto-loaded file, @value{GDBN} sets the +@dfn{current objfile}. This is available via the @code{current-objfile} +procedure (@pxref{Objfiles In Guile}). This can be useful for +registering objfile-specific pretty-printers. + +@node Guile Modules +@subsection Guile Modules +@cindex guile modules + +@value{GDBN} comes with several modules to assist writing Guile code. + +@menu +* Guile Printing Module:: Building and registering pretty-printers +* Guile Types Module:: Utilities for working with types +@end menu + +@node Guile Printing Module +@subsubsection Guile Printing Module + +This module provides a collection of utilities for working with +pretty-printers. + +Usage: + +@smallexample +(use-modules (gdb printing)) +@end smallexample + +@deffn {Scheme Procedure} prepend-pretty-printer! object printer +Add @var{printer} to the front of the list of pretty-printers for +@var{object}. The @var{object} must either be a @code{} object, +or @code{#f} in which case @var{printer} is added to the global list of +printers. +@end deffn + +@deffn {Scheme Procedure} append-pretty-printer! object printer +Add @var{printer} to the end of the list of pretty-printers for +@var{object}. The @var{object} must either be a @code{} object, +or @code{#f} in which case @var{printer} is added to the global list of +printers. +@end deffn + +@node Guile Types Module +@subsubsection Guile Types Module + +This module provides a collection of utilities for working with +@code{} objects. + +Usage: + +@smallexample +(use-modules (gdb types)) +@end smallexample + +@deffn {Scheme Procedure} get-basic-type type +Return @var{type} with const and volatile qualifiers stripped, +and with typedefs and C@t{++} references converted to the underlying type. + +C@t{++} example: + +@smallexample +typedef const int const_int; +const_int foo (3); +const_int& foo_ref (foo); +int main () @{ return 0; @} +@end smallexample + +Then in gdb: + +@smallexample +(gdb) start +(gdb) guile (use-modules (gdb) (gdb types)) +(gdb) guile (define foo-ref (parse-and-eval "foo_ref")) +(gdb) guile (get-basic-type (value-type foo-ref)) +# +@end smallexample +@end deffn + +@deffn {Scheme Procedure} type-has-field-deep? type field +Return @code{#t} if @var{type}, assumed to be a type with fields +(e.g., a structure or union), has field @var{field}. +Otherwise return @code{#f}. +This searches baseclasses, whereas @code{type-has-field?} does not. +@end deffn + +@deffn {Scheme Procedure} make-enum-hashtable enum-type +Return a Guile hash table produced from @var{enum-type}. +Elements in the hash table are referenced with @code{hashq-ref}. +@end deffn diff -pruN 16.3-5/gdb/doc/python.texi 16.3-5ubuntu1/gdb/doc/python.texi --- 16.3-5/gdb/doc/python.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/python.texi 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,8771 @@ +@c Copyright (C) 2008--2024 Free Software Foundation, Inc. +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 or +@c any later version published by the Free Software Foundation; with the +@c Invariant Sections being ``Free Software'' and ``Free Software Needs +@c Free Documentation'', with the Front-Cover Texts being ``A GNU Manual,'' +@c and with the Back-Cover Texts as in (a) below. +@c +@c (a) The FSF's Back-Cover Text is: ``You are free to copy and modify +@c this GNU Manual. Buying copies from GNU Press supports the FSF in +@c developing GNU and promoting software freedom.'' +@node Python +@section Extending @value{GDBN} using Python +@cindex python scripting +@cindex scripting with python + +You can extend @value{GDBN} using the @uref{http://www.python.org/, +Python programming language}. This feature is available only if +@value{GDBN} was configured using @option{--with-python}. + +@cindex python directory +Python scripts used by @value{GDBN} should be installed in +@file{@var{data-directory}/python}, where @var{data-directory} is +the data directory as determined at @value{GDBN} startup (@pxref{Data Files}). +This directory, known as the @dfn{python directory}, +is automatically added to the Python Search Path in order to allow +the Python interpreter to locate all scripts installed at this location. + +Additionally, @value{GDBN} commands and convenience functions which +are written in Python and are located in the +@file{@var{data-directory}/python/gdb/command} or +@file{@var{data-directory}/python/gdb/function} directories are +automatically imported when @value{GDBN} starts. + +@menu +* Python Commands:: Accessing Python from @value{GDBN}. +* Python API:: Accessing @value{GDBN} from Python. +* Python Auto-loading:: Automatically loading Python code. +* Python modules:: Python modules provided by @value{GDBN}. +@end menu + +@node Python Commands +@subsection Python Commands +@cindex python commands +@cindex commands to access python + +@value{GDBN} provides two commands for accessing the Python interpreter, +and one related setting: + +@table @code +@kindex python-interactive +@kindex pi +@item python-interactive @r{[}@var{command}@r{]} +@itemx pi @r{[}@var{command}@r{]} +Without an argument, the @code{python-interactive} command can be used +to start an interactive Python prompt. To return to @value{GDBN}, +type the @code{EOF} character (e.g., @kbd{Ctrl-D} on an empty prompt). + +Alternatively, a single-line Python command can be given as an +argument and evaluated. If the command is an expression, the result +will be printed; otherwise, nothing will be printed. For example: + +@smallexample +(@value{GDBP}) python-interactive 2 + 3 +5 +@end smallexample + +@kindex python +@kindex py +@item python @r{[}@var{command}@r{]} +@itemx py @r{[}@var{command}@r{]} +The @code{python} command can be used to evaluate Python code. + +If given an argument, the @code{python} command will evaluate the +argument as a Python command. For example: + +@smallexample +(@value{GDBP}) python print 23 +23 +@end smallexample + +If you do not provide an argument to @code{python}, it will act as a +multi-line command, like @code{define}. In this case, the Python +script is made up of subsequent command lines, given after the +@code{python} command. This command list is terminated using a line +containing @code{end}. For example: + +@smallexample +(@value{GDBP}) python +>print 23 +>end +23 +@end smallexample + +@anchor{set_python_print_stack} +@kindex set python print-stack +@item set python print-stack +By default, @value{GDBN} will print only the message component of a +Python exception when an error occurs in a Python script. This can be +controlled using @code{set python print-stack}: if @code{full}, then +full Python stack printing is enabled; if @code{none}, then Python stack +and message printing is disabled; if @code{message}, the default, only +the message component of the error is printed. + +@kindex set python ignore-environment +@item set python ignore-environment @r{[}on@r{|}off@r{]} +By default this option is @samp{off}, and, when @value{GDBN} +initializes its internal Python interpreter, the Python interpreter +will check the environment for variables that will effect how it +behaves, for example @env{PYTHONHOME}, and +@env{PYTHONPATH}@footnote{See the ENVIRONMENT VARIABLES section of +@command{man 1 python} for a comprehensive list.}. + +If this option is set to @samp{on} before Python is initialized then +Python will ignore all such environment variables. As Python is +initialized early during @value{GDBN}'s startup process, then this +option must be placed into the early initialization file +(@pxref{Initialization Files}) to have the desired effect. + +This option is equivalent to passing @option{-E} to the real +@command{python} executable. + +@kindex set python dont-write-bytecode +@item set python dont-write-bytecode @r{[}auto@r{|}on@r{|}off@r{]} +When this option is @samp{off}, then, once @value{GDBN} has +initialized the Python interpreter, the interpreter will byte-compile +any Python modules that it imports and write the byte code to disk in +@file{.pyc} files. + +If this option is set to @samp{on} before Python is initialized then +Python will no longer write the byte code to disk. As Python is +initialized early during @value{GDBN}'s startup process, then this +option must be placed into the early initialization file +(@pxref{Initialization Files}) to have the desired effect. + +By default this option is set to @samp{auto}. In this mode, provided +the @code{python ignore-environment} setting is @samp{off}, the +environment variable @env{PYTHONDONTWRITEBYTECODE} is examined to see +if it should write out byte-code or not. +@env{PYTHONDONTWRITEBYTECODE} is considered to be off/disabled either +when set to the empty string or when the environment variable doesn't +exist. All other settings, including those which don't seem to make +sense, indicate that it's on/enabled. + +This option is equivalent to passing @option{-B} to the real +@command{python} executable. +@end table + +It is also possible to execute a Python script from the @value{GDBN} +interpreter: + +@table @code +@item source @file{script-name} +The script name must end with @samp{.py} and @value{GDBN} must be configured +to recognize the script language based on filename extension using +the @code{script-extension} setting. @xref{Extending GDB, ,Extending GDB}. +@end table + +The following commands are intended to help debug @value{GDBN} itself: + +@table @code +@kindex set debug py-breakpoint +@kindex show debug py-breakpoint +@item set debug py-breakpoint on@r{|}off +@itemx show debug py-breakpoint +When @samp{on}, @value{GDBN} prints debug messages related to the +Python breakpoint API. This is @samp{off} by default. + +@kindex set debug py-unwind +@kindex show debug py-unwind +@item set debug py-unwind on@r{|}off +@itemx show debug py-unwind +When @samp{on}, @value{GDBN} prints debug messages related to the +Python unwinder API. This is @samp{off} by default. +@end table + +@node Python API +@subsection Python API +@cindex python api +@cindex programming in python + +You can get quick online help for @value{GDBN}'s Python API by issuing +the command @w{@kbd{python help (gdb)}}. + +Functions and methods which have two or more optional arguments allow +them to be specified using keyword syntax. This allows passing some +optional arguments while skipping others. Example: +@w{@code{gdb.some_function ('foo', bar = 1, baz = 2)}}. + +@menu +* Basic Python:: Basic Python Functions. +* Threading in GDB:: Using Python threads in GDB. +* Exception Handling:: How Python exceptions are translated. +* Values From Inferior:: Python representation of values. +* Types In Python:: Python representation of types. +* Pretty Printing API:: Pretty-printing values. +* Selecting Pretty-Printers:: How GDB chooses a pretty-printer. +* Writing a Pretty-Printer:: Writing a Pretty-Printer. +* Type Printing API:: Pretty-printing types. +* Frame Filter API:: Filtering Frames. +* Frame Decorator API:: Decorating Frames. +* Writing a Frame Filter:: Writing a Frame Filter. +* Unwinding Frames in Python:: Writing frame unwinder. +* Xmethods In Python:: Adding and replacing methods of C++ classes. +* Xmethod API:: Xmethod types. +* Writing an Xmethod:: Writing an xmethod. +* Inferiors In Python:: Python representation of inferiors (processes) +* Events In Python:: Listening for events from @value{GDBN}. +* Threads In Python:: Accessing inferior threads from Python. +* Recordings In Python:: Accessing recordings from Python. +* CLI Commands In Python:: Implementing new CLI commands in Python. +* GDB/MI Commands In Python:: Implementing new @sc{gdb/mi} commands in Python. +* GDB/MI Notifications In Python:: Implementing new @sc{gdb/mi} notifications in Python. +* Parameters In Python:: Adding new @value{GDBN} parameters. +* Functions In Python:: Writing new convenience functions. +* Progspaces In Python:: Program spaces. +* Objfiles In Python:: Object files. +* Frames In Python:: Accessing inferior stack frames from Python. +* Blocks In Python:: Accessing blocks from Python. +* Symbols In Python:: Python representation of symbols. +* Symbol Tables In Python:: Python representation of symbol tables. +* Line Tables In Python:: Python representation of line tables. +* Breakpoints In Python:: Manipulating breakpoints using Python. +* Finish Breakpoints in Python:: Setting Breakpoints on function return + using Python. +* Lazy Strings In Python:: Python representation of lazy strings. +* Architectures In Python:: Python representation of architectures. +* Registers In Python:: Python representation of registers. +* Connections In Python:: Python representation of connections. +* TUI Windows In Python:: Implementing new TUI windows. +* Disassembly In Python:: Instruction Disassembly In Python +* Missing Debug Info In Python:: Handle missing debug info from Python. +* Missing Objfiles In Python:: Handle objfiles from Python. +@end menu + +@node Basic Python +@subsubsection Basic Python + +@cindex python stdout +@cindex python pagination +At startup, @value{GDBN} overrides Python's @code{sys.stdout} and +@code{sys.stderr} to print using @value{GDBN}'s output-paging streams. +A Python program which outputs to one of these streams may have its +output interrupted by the user (@pxref{Screen Size}). In this +situation, a Python @code{KeyboardInterrupt} exception is thrown. + +Some care must be taken when writing Python code to run in +@value{GDBN}. Two things worth noting in particular: + +@itemize @bullet +@item +@value{GDBN} installs handlers for @code{SIGCHLD} and @code{SIGINT}. +Python code must not override these, or even change the options using +@code{sigaction}. If your program changes the handling of these +signals, @value{GDBN} will most likely stop working correctly. Note +that it is unfortunately common for GUI toolkits to install a +@code{SIGCHLD} handler. When creating a new Python thread, you can +use @code{gdb.block_signals} or @code{gdb.Thread} to handle this +correctly; see @ref{Threading in GDB}. + +@item +@value{GDBN} takes care to mark its internal file descriptors as +close-on-exec. However, this cannot be done in a thread-safe way on +all platforms. Your Python programs should be aware of this and +should both create new file descriptors with the close-on-exec flag +set and arrange to close unneeded file descriptors before starting a +child process. +@end itemize + +@cindex python functions +@cindex python module +@cindex gdb module +@value{GDBN} introduces a new Python module, named @code{gdb}. All +methods and classes added by @value{GDBN} are placed in this module. +@value{GDBN} automatically @code{import}s the @code{gdb} module for +use in all scripts evaluated by the @code{python} command. + +Some types of the @code{gdb} module come with a textual representation +(accessible through the @code{repr} or @code{str} functions). These are +offered for debugging purposes only, expect them to change over time. + +@defvar gdb.PYTHONDIR +A string containing the python directory (@pxref{Python}). +@end defvar + +@defun gdb.execute (command @r{[}, from_tty @r{[}, to_string@r{]]}) +Evaluate @var{command}, a string, as a @value{GDBN} CLI command. +If a GDB exception happens while @var{command} runs, it is +translated as described in @ref{Exception Handling,,Exception Handling}. + +The @var{from_tty} flag specifies whether @value{GDBN} ought to consider this +command as having originated from the user invoking it interactively. +It must be a boolean value. If omitted, it defaults to @code{False}. + +By default, any output produced by @var{command} is sent to +@value{GDBN}'s standard output (and to the log output if logging is +turned on). If the @var{to_string} parameter is +@code{True}, then output will be collected by @code{gdb.execute} and +returned as a string. The default is @code{False}, in which case the +return value is @code{None}. If @var{to_string} is @code{True}, the +@value{GDBN} virtual terminal will be temporarily set to unlimited width +and height, and its pagination will be disabled; @pxref{Screen Size}. +@end defun + +@defun gdb.breakpoints () +Return a sequence holding all of @value{GDBN}'s breakpoints. +@xref{Breakpoints In Python}, for more information. In @value{GDBN} +version 7.11 and earlier, this function returned @code{None} if there +were no breakpoints. This peculiarity was subsequently fixed, and now +@code{gdb.breakpoints} returns an empty sequence in this case. +@end defun + +@defun gdb.rbreak (regex @r{[}, minsyms @r{[}, throttle, @r{[}, symtabs @r{]]]}) +Return a Python list holding a collection of newly set +@code{gdb.Breakpoint} objects matching function names defined by the +@var{regex} pattern. If the @var{minsyms} keyword is @code{True}, all +system functions (those not explicitly defined in the inferior) will +also be included in the match. The @var{throttle} keyword takes an +integer that defines the maximum number of pattern matches for +functions matched by the @var{regex} pattern. If the number of +matches exceeds the integer value of @var{throttle}, a +@code{RuntimeError} will be raised and no breakpoints will be created. +If @var{throttle} is not defined then there is no imposed limit on the +maximum number of matches and breakpoints to be created. The +@var{symtabs} keyword takes a Python iterable that yields a collection +of @code{gdb.Symtab} objects and will restrict the search to those +functions only contained within the @code{gdb.Symtab} objects. +@end defun + +@defun gdb.parameter (parameter) +Return the value of a @value{GDBN} @var{parameter} given by its name, +a string; the parameter name string may contain spaces if the parameter has a +multi-part name. For example, @samp{print object} is a valid +parameter name. + +If the named parameter does not exist, this function throws a +@code{gdb.error} (@pxref{Exception Handling}). Otherwise, the +parameter's value is converted to a Python value of the appropriate +type, and returned. +@end defun + +@defun gdb.set_parameter (name, value) +Sets the gdb parameter @var{name} to @var{value}. As with +@code{gdb.parameter}, the parameter name string may contain spaces if +the parameter has a multi-part name. +@end defun + +@defun gdb.with_parameter (name, value) +Create a Python context manager (for use with the Python +@command{with} statement) that temporarily sets the gdb parameter +@var{name} to @var{value}. On exit from the context, the previous +value will be restored. + +This uses @code{gdb.parameter} in its implementation, so it can throw +the same exceptions as that function. + +For example, it's sometimes useful to evaluate some Python code with a +particular gdb language: + +@smallexample +with gdb.with_parameter('language', 'pascal'): + ... language-specific operations +@end smallexample +@end defun + +@defun gdb.history (number) +Return a value from @value{GDBN}'s value history (@pxref{Value +History}). The @var{number} argument indicates which history element to return. +If @var{number} is negative, then @value{GDBN} will take its absolute value +and count backward from the last element (i.e., the most recent element) to +find the value to return. If @var{number} is zero, then @value{GDBN} will +return the most recent element. If the element specified by @var{number} +doesn't exist in the value history, a @code{gdb.error} exception will be +raised. + +If no exception is raised, the return value is always an instance of +@code{gdb.Value} (@pxref{Values From Inferior}). +@end defun + +@defun gdb.add_history (value) +Takes @var{value}, an instance of @code{gdb.Value} (@pxref{Values From +Inferior}), and appends the value this object represents to +@value{GDBN}'s value history (@pxref{Value History}), and return an +integer, its history number. If @var{value} is not a +@code{gdb.Value}, it is is converted using the @code{gdb.Value} +constructor. If @var{value} can't be converted to a @code{gdb.Value} +then a @code{TypeError} is raised. + +When a command implemented in Python prints a single @code{gdb.Value} +as its result, then placing the value into the history will allow the +user convenient access to those values via CLI history facilities. +@end defun + +@defun gdb.history_count () +Return an integer indicating the number of values in @value{GDBN}'s +value history (@pxref{Value History}). +@end defun + +@defun gdb.convenience_variable (name) +Return the value of the convenience variable (@pxref{Convenience +Vars}) named @var{name}. @var{name} must be a string. The name +should not include the @samp{$} that is used to mark a convenience +variable in an expression. If the convenience variable does not +exist, then @code{None} is returned. +@end defun + +@defun gdb.set_convenience_variable (name, value) +Set the value of the convenience variable (@pxref{Convenience Vars}) +named @var{name}. @var{name} must be a string. The name should not +include the @samp{$} that is used to mark a convenience variable in an +expression. If @var{value} is @code{None}, then the convenience +variable is removed. Otherwise, if @var{value} is not a +@code{gdb.Value} (@pxref{Values From Inferior}), it is is converted +using the @code{gdb.Value} constructor. +@end defun + +@defun gdb.parse_and_eval (expression @r{[}, global_context@r{]}) +Parse @var{expression}, which must be a string, as an expression in +the current language, evaluate it, and return the result as a +@code{gdb.Value}. + +@var{global_context}, if provided, is a boolean indicating whether the +parsing should be done in the global context. The default is +@samp{False}, meaning that the current frame or current static context +should be used. + +This function can be useful when implementing a new command +(@pxref{CLI Commands In Python}, @pxref{GDB/MI Commands In Python}), +as it provides a way to parse the +command's argument as an expression. It is also useful simply to +compute values. +@end defun + +@defun gdb.find_pc_line (pc) +Return the @code{gdb.Symtab_and_line} object corresponding to the +@var{pc} value. @xref{Symbol Tables In Python}. If an invalid +value of @var{pc} is passed as an argument, then the @code{symtab} and +@code{line} attributes of the returned @code{gdb.Symtab_and_line} object +will be @code{None} and 0 respectively. This is identical to +@code{gdb.current_progspace().find_pc_line(pc)} and is included for +historical compatibility. +@end defun + +@defun gdb.write (string @r{[}, stream@r{]}) +Print a string to @value{GDBN}'s paginated output stream. The +optional @var{stream} determines the stream to print to. The default +stream is @value{GDBN}'s standard output stream. Possible stream +values are: + +@table @code +@findex STDOUT +@findex gdb.STDOUT +@item gdb.STDOUT +@value{GDBN}'s standard output stream. + +@findex STDERR +@findex gdb.STDERR +@item gdb.STDERR +@value{GDBN}'s standard error stream. + +@findex STDLOG +@findex gdb.STDLOG +@item gdb.STDLOG +@value{GDBN}'s log stream (@pxref{Logging Output}). +@end table + +Writing to @code{sys.stdout} or @code{sys.stderr} will automatically +call this function and will automatically direct the output to the +relevant stream. +@end defun + +@defun gdb.flush (@r{[}, stream@r{]}) +Flush the buffer of a @value{GDBN} paginated stream so that the +contents are displayed immediately. @value{GDBN} will flush the +contents of a stream automatically when it encounters a newline in the +buffer. The optional @var{stream} determines the stream to flush. The +default stream is @value{GDBN}'s standard output stream. Possible +stream values are: + +@table @code +@findex STDOUT +@findex gdb.STDOUT +@item gdb.STDOUT +@value{GDBN}'s standard output stream. + +@findex STDERR +@findex gdb.STDERR +@item gdb.STDERR +@value{GDBN}'s standard error stream. + +@findex STDLOG +@findex gdb.STDLOG +@item gdb.STDLOG +@value{GDBN}'s log stream (@pxref{Logging Output}). + +@end table + +Flushing @code{sys.stdout} or @code{sys.stderr} will automatically +call this function for the relevant stream. +@end defun + +@defun gdb.target_charset () +Return the name of the current target character set (@pxref{Character +Sets}). This differs from @code{gdb.parameter('target-charset')} in +that @samp{auto} is never returned. +@end defun + +@defun gdb.target_wide_charset () +Return the name of the current target wide character set +(@pxref{Character Sets}). This differs from +@code{gdb.parameter('target-wide-charset')} in that @samp{auto} is +never returned. +@end defun + +@defun gdb.host_charset () +Return a string, the name of the current host character set +(@pxref{Character Sets}). This differs from +@code{gdb.parameter('host-charset')} in that @samp{auto} is never +returned. +@end defun + +@defun gdb.solib_name (address) +Return the name of the shared library holding the given @var{address} +as a string, or @code{None}. This is identical to +@code{gdb.current_progspace().solib_name(address)} and is included for +historical compatibility. +@end defun + +@defun gdb.decode_line (@r{[}expression@r{]}) +Return locations of the line specified by @var{expression}, or of the +current line if no argument was given. This function returns a Python +tuple containing two elements. The first element contains a string +holding any unparsed section of @var{expression} (or @code{None} if +the expression has been fully parsed). The second element contains +either @code{None} or another tuple that contains all the locations +that match the expression represented as @code{gdb.Symtab_and_line} +objects (@pxref{Symbol Tables In Python}). If @var{expression} is +provided, it is decoded the way that @value{GDBN}'s inbuilt +@code{break} or @code{edit} commands do (@pxref{Location +Specifications}). +@end defun + +@defun gdb.prompt_hook (current_prompt) +@anchor{prompt_hook} + +If @var{prompt_hook} is callable, @value{GDBN} will call the method +assigned to this operation before a prompt is displayed by +@value{GDBN}. + +The parameter @code{current_prompt} contains the current @value{GDBN} +prompt. This method must return a Python string, or @code{None}. If +a string is returned, the @value{GDBN} prompt will be set to that +string. If @code{None} is returned, @value{GDBN} will continue to use +the current prompt. + +Some prompts cannot be substituted in @value{GDBN}. Secondary prompts +such as those used by readline for command input, and annotation +related prompts are prohibited from being changed. +@end defun + +@anchor{gdb_architecture_names} +@defun gdb.architecture_names () +Return a list containing all of the architecture names that the +current build of @value{GDBN} supports. Each architecture name is a +string. The names returned in this list are the same names as are +returned from @code{gdb.Architecture.name} +(@pxref{gdbpy_architecture_name,,Architecture.name}). +@end defun + +@anchor{gdbpy_connections} +@defun gdb.connections +Return a list of @code{gdb.TargetConnection} objects, one for each +currently active connection (@pxref{Connections In Python}). The +connection objects are in no particular order in the returned list. +@end defun + +@defun gdb.format_address (address @r{[}, progspace, architecture@r{]}) +Return a string in the format @samp{@var{addr} +<@var{symbol}+@var{offset}>}, where @var{addr} is @var{address} +formatted in hexadecimal, @var{symbol} is the symbol whose address is +the nearest to @var{address} and below it in memory, and @var{offset} +is the offset from @var{symbol} to @var{address} in decimal. + +If no suitable @var{symbol} was found, then the +<@var{symbol}+@var{offset}> part is not included in the returned +string, instead the returned string will just contain the +@var{address} formatted as hexadecimal. How far @value{GDBN} looks +back for a suitable symbol can be controlled with @kbd{set print +max-symbolic-offset} (@pxref{Print Settings}). + +Additionally, the returned string can include file name and line +number information when @kbd{set print symbol-filename on} +(@pxref{Print Settings}), in this case the format of the returned +string is @samp{@var{addr} <@var{symbol}+@var{offset}> at +@var{filename}:@var{line-number}}. + + +The @var{progspace} is the gdb.Progspace in which @var{symbol} is +looked up, and @var{architecture} is used when formatting @var{addr}, +e.g.@: in order to determine the size of an address in bytes. + +If neither @var{progspace} or @var{architecture} are passed, then by +default @value{GDBN} will use the program space and architecture of +the currently selected inferior, thus, the following two calls are +equivalent: + +@smallexample +gdb.format_address(address) +gdb.format_address(address, + gdb.selected_inferior().progspace, + gdb.selected_inferior().architecture()) +@end smallexample + +It is not valid to only pass one of @var{progspace} or +@var{architecture}, either they must both be provided, or neither must +be provided (and the defaults will be used). + +This method uses the same mechanism for formatting address, symbol, +and offset information as core @value{GDBN} does in commands such as +@kbd{disassemble}. + +Here are some examples of the possible string formats: + +@smallexample +0x00001042 +0x00001042 +0x00001042 +@end smallexample +@end defun + +@defun gdb.current_language () +Return the name of the current language as a string. Unlike +@code{gdb.parameter('language')}, this function will never return +@samp{auto}. If a @code{gdb.Frame} object is available (@pxref{Frames +In Python}), the @code{language} method might be preferable in some +cases, as that is not affected by the user's language setting. +@end defun + +@node Threading in GDB +@subsubsection Threading in GDB + +@value{GDBN} is not thread-safe. If your Python program uses multiple +threads, you must be careful to only call @value{GDBN}-specific +functions in the @value{GDBN} thread. @value{GDBN} provides some +functions to help with this. + +@defun gdb.block_signals () +As mentioned earlier (@pxref{Basic Python}), certain signals must be +delivered to the @value{GDBN} main thread. The @code{block_signals} +function returns a context manager that will block these signals on +entry. This can be used when starting a new thread to ensure that the +signals are blocked there, like: + +@smallexample +with gdb.block_signals(): + start_new_thread() +@end smallexample +@end defun + +@deftp {class} gdb.Thread +This is a subclass of Python's @code{threading.Thread} class. It +overrides the @code{start} method to call @code{block_signals}, making +this an easy-to-use drop-in replacement for creating threads that will +work well in @value{GDBN}. +@end deftp + +@defun gdb.interrupt () +This causes @value{GDBN} to react as if the user had typed a control-C +character at the terminal. That is, if the inferior is running, it is +interrupted; if a @value{GDBN} command is executing, it is stopped; +and if a Python command is running, @code{KeyboardInterrupt} will be +raised. + +Unlike most Python APIs in @value{GDBN}, @code{interrupt} is +thread-safe. +@end defun + +@defun gdb.post_event (event) +Put @var{event}, a callable object taking no arguments, into +@value{GDBN}'s internal event queue. This callable will be invoked at +some later point, during @value{GDBN}'s event processing. Events +posted using @code{post_event} will be run in the order in which they +were posted; however, there is no way to know when they will be +processed relative to other events inside @value{GDBN}. + +Unlike most Python APIs in @value{GDBN}, @code{post_event} is +thread-safe. For example: + +@smallexample +(@value{GDBP}) python +>import threading +> +>class Writer(): +> def __init__(self, message): +> self.message = message; +> def __call__(self): +> gdb.write(self.message) +> +>class MyThread1 (threading.Thread): +> def run (self): +> gdb.post_event(Writer("Hello ")) +> +>class MyThread2 (threading.Thread): +> def run (self): +> gdb.post_event(Writer("World\n")) +> +>MyThread1().start() +>MyThread2().start() +>end +(@value{GDBP}) Hello World +@end smallexample +@end defun + + +@node Exception Handling +@subsubsection Exception Handling +@cindex python exceptions +@cindex exceptions, python + +When executing the @code{python} command, Python exceptions +uncaught within the Python code are translated to calls to +@value{GDBN} error-reporting mechanism. If the command that called +@code{python} does not handle the error, @value{GDBN} will +terminate it and print an error message. Exactly what will be printed +depends on @code{set python print-stack} (@pxref{Python Commands}). +Example: + +@smallexample +(@value{GDBP}) python print foo +Traceback (most recent call last): + File "", line 1, in +NameError: name 'foo' is not defined +@end smallexample + +@value{GDBN} errors that happen in @value{GDBN} commands invoked by +Python code are converted to Python exceptions. The type of the +Python exception depends on the error. + +@ftable @code +@item gdb.error +This is the base class for most exceptions generated by @value{GDBN}. +It is derived from @code{RuntimeError}, for compatibility with earlier +versions of @value{GDBN}. + +If an error occurring in @value{GDBN} does not fit into some more +specific category, then the generated exception will have this type. + +@item gdb.MemoryError +This is a subclass of @code{gdb.error} which is thrown when an +operation tried to access invalid memory in the inferior. + +@item KeyboardInterrupt +User interrupt (via @kbd{C-c} or by typing @kbd{q} at a pagination +prompt) is translated to a Python @code{KeyboardInterrupt} exception. +@end ftable + +In all cases, your exception handler will see the @value{GDBN} error +message as its value and the Python call stack backtrace at the Python +statement closest to where the @value{GDBN} error occurred as the +traceback. + + +When implementing @value{GDBN} commands in Python via +@code{gdb.Command}, or functions via @code{gdb.Function}, it is useful +to be able to throw an exception that doesn't cause a traceback to be +printed. For example, the user may have invoked the command +incorrectly. @value{GDBN} provides a special exception class that can +be used for this purpose. + +@ftable @code +@item gdb.GdbError +When thrown from a command or function, this exception will cause the +command or function to fail, but the Python stack will not be +displayed. @value{GDBN} does not throw this exception itself, but +rather recognizes it when thrown from user Python code. Example: + +@smallexample +(gdb) python +>class HelloWorld (gdb.Command): +> """Greet the whole world.""" +> def __init__ (self): +> super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) +> def invoke (self, args, from_tty): +> argv = gdb.string_to_argv (args) +> if len (argv) != 0: +> raise gdb.GdbError ("hello-world takes no arguments") +> print ("Hello, World!") +>HelloWorld () +>end +(gdb) hello-world 42 +hello-world takes no arguments +@end smallexample +@end ftable + +@node Values From Inferior +@subsubsection Values From Inferior +@cindex values from inferior, with Python +@cindex python, working with values from inferior + +@cindex @code{gdb.Value} +@value{GDBN} provides values it obtains from the inferior program in +an object of type @code{gdb.Value}. @value{GDBN} uses this object +for its internal bookkeeping of the inferior's values, and for +fetching values when necessary. + +Inferior values that are simple scalars can be used directly in +Python expressions that are valid for the value's data type. Here's +an example for an integer or floating-point value @code{some_val}: + +@smallexample +bar = some_val + 2 +@end smallexample + +@noindent +As result of this, @code{bar} will also be a @code{gdb.Value} object +whose values are of the same type as those of @code{some_val}. Valid +Python operations can also be performed on @code{gdb.Value} objects +representing a @code{struct} or @code{class} object. For such cases, +the overloaded operator (if present), is used to perform the operation. +For example, if @code{val1} and @code{val2} are @code{gdb.Value} objects +representing instances of a @code{class} which overloads the @code{+} +operator, then one can use the @code{+} operator in their Python script +as follows: + +@smallexample +val3 = val1 + val2 +@end smallexample + +@noindent +The result of the operation @code{val3} is also a @code{gdb.Value} +object corresponding to the value returned by the overloaded @code{+} +operator. In general, overloaded operators are invoked for the +following operations: @code{+} (binary addition), @code{-} (binary +subtraction), @code{*} (multiplication), @code{/}, @code{%}, @code{<<}, +@code{>>}, @code{|}, @code{&}, @code{^}. + +Inferior values that are structures or instances of some class can +be accessed using the Python @dfn{dictionary syntax}. For example, if +@code{some_val} is a @code{gdb.Value} instance holding a structure, you +can access its @code{foo} element with: + +@smallexample +bar = some_val['foo'] +@end smallexample + +@cindex getting structure elements using gdb.Field objects as subscripts +Again, @code{bar} will also be a @code{gdb.Value} object. Structure +elements can also be accessed by using @code{gdb.Field} objects as +subscripts (@pxref{Types In Python}, for more information on +@code{gdb.Field} objects). For example, if @code{foo_field} is a +@code{gdb.Field} object corresponding to element @code{foo} of the above +structure, then @code{bar} can also be accessed as follows: + +@smallexample +bar = some_val[foo_field] +@end smallexample + +If a @code{gdb.Value} has array or pointer type, an integer index can +be used to access elements. + +@smallexample +result = some_array[23] +@end smallexample + +A @code{gdb.Value} that represents a function can be executed via +inferior function call. Any arguments provided to the call must match +the function's prototype, and must be provided in the order specified +by that prototype. + +For example, @code{some_val} is a @code{gdb.Value} instance +representing a function that takes two integers as arguments. To +execute this function, call it like so: + +@smallexample +result = some_val (10,20) +@end smallexample + +Any values returned from a function call will be stored as a +@code{gdb.Value}. + +The following attributes are provided: + +@defvar Value.address +If this object is addressable, this read-only attribute holds a +@code{gdb.Value} object representing the address. Otherwise, +this attribute holds @code{None}. +@end defvar + +@cindex optimized out value in Python +@defvar Value.is_optimized_out +This read-only boolean attribute is true if the compiler optimized out +this value, thus it is not available for fetching from the inferior. +@end defvar + +@defvar Value.type +The type of this @code{gdb.Value}. The value of this attribute is a +@code{gdb.Type} object (@pxref{Types In Python}). +@end defvar + +@defvar Value.dynamic_type +The dynamic type of this @code{gdb.Value}. This uses the object's +virtual table and the C@t{++} run-time type information +(@acronym{RTTI}) to determine the dynamic type of the value. If this +value is of class type, it will return the class in which the value is +embedded, if any. If this value is of pointer or reference to a class +type, it will compute the dynamic type of the referenced object, and +return a pointer or reference to that type, respectively. In all +other cases, it will return the value's static type. + +Note that this feature will only work when debugging a C@t{++} program +that includes @acronym{RTTI} for the object in question. Otherwise, +it will just return the static type of the value as in @kbd{ptype foo} +(@pxref{Symbols, ptype}). +@end defvar + +@defvar Value.is_lazy +The value of this read-only boolean attribute is @code{True} if this +@code{gdb.Value} has not yet been fetched from the inferior. +@value{GDBN} does not fetch values until necessary, for efficiency. +For example: + +@smallexample +myval = gdb.parse_and_eval ('somevar') +@end smallexample + +The value of @code{somevar} is not fetched at this time. It will be +fetched when the value is needed, or when the @code{fetch_lazy} +method is invoked. +@end defvar + +@defvar Value.bytes +The value of this attribute is a @code{bytes} object containing the +bytes that make up this @code{Value}'s complete value in little endian +order. If the complete contents of this value are not available then +accessing this attribute will raise an exception. + +This attribute can also be assigned to. The new value should be a +buffer object (e.g.@: a @code{bytes} object), the length of the new +buffer must exactly match the length of this @code{Value}'s type. The +bytes values in the new buffer should be in little endian order. + +As with @code{Value.assign} (@pxref{Value.assign}), if this value +cannot be assigned to, then an exception will be thrown. +@end defvar + +The following methods are provided: + +@defun Value.__init__ (val) +Many Python values can be converted directly to a @code{gdb.Value} via +this object initializer. Specifically: + +@table @asis +@item Python boolean +A Python boolean is converted to the boolean type from the current +language. + +@item Python integer +A Python integer is converted to the C @code{long} type for the +current architecture. + +@item Python long +A Python long is converted to the C @code{long long} type for the +current architecture. + +@item Python float +A Python float is converted to the C @code{double} type for the +current architecture. + +@item Python string +A Python string is converted to a target string in the current target +language using the current target encoding. +If a character cannot be represented in the current target encoding, +then an exception is thrown. + +@item @code{gdb.Value} +If @code{val} is a @code{gdb.Value}, then a copy of the value is made. + +@item @code{gdb.LazyString} +If @code{val} is a @code{gdb.LazyString} (@pxref{Lazy Strings In +Python}), then the lazy string's @code{value} method is called, and +its result is used. +@end table +@end defun + +@defun Value.__init__ (val, type) +This second form of the @code{gdb.Value} constructor returns a +@code{gdb.Value} of type @var{type} where the value contents are taken +from the Python buffer object specified by @var{val}. The number of +bytes in the Python buffer object must be greater than or equal to the +size of @var{type}. + +If @var{type} is @code{None} then this version of @code{__init__} +behaves as though @var{type} was not passed at all. +@end defun + +@anchor{Value.assign} +@defun Value.assign (rhs) +Assign @var{rhs} to this value, and return @code{None}. If this value +cannot be assigned to, or if the assignment is invalid for some reason +(for example a type-checking failure), an exception will be thrown. +@end defun + +@defun Value.cast (type) +Return a new instance of @code{gdb.Value} that is the result of +casting this instance to the type described by @var{type}, which must +be a @code{gdb.Type} object. If the cast cannot be performed for some +reason, this method throws an exception. +@end defun + +@defun Value.dereference () +For pointer data types, this method returns a new @code{gdb.Value} object +whose contents is the object pointed to by the pointer. For example, if +@code{foo} is a C pointer to an @code{int}, declared in your C program as + +@smallexample +int *foo; +@end smallexample + +@noindent +then you can use the corresponding @code{gdb.Value} to access what +@code{foo} points to like this: + +@smallexample +bar = foo.dereference () +@end smallexample + +The result @code{bar} will be a @code{gdb.Value} object holding the +value pointed to by @code{foo}. + +A similar function @code{Value.referenced_value} exists which also +returns @code{gdb.Value} objects corresponding to the values pointed to +by pointer values (and additionally, values referenced by reference +values). However, the behavior of @code{Value.dereference} +differs from @code{Value.referenced_value} by the fact that the +behavior of @code{Value.dereference} is identical to applying the C +unary operator @code{*} on a given value. For example, consider a +reference to a pointer @code{ptrref}, declared in your C@t{++} program +as + +@smallexample +typedef int *intptr; +... +int val = 10; +intptr ptr = &val; +intptr &ptrref = ptr; +@end smallexample + +Though @code{ptrref} is a reference value, one can apply the method +@code{Value.dereference} to the @code{gdb.Value} object corresponding +to it and obtain a @code{gdb.Value} which is identical to that +corresponding to @code{val}. However, if you apply the method +@code{Value.referenced_value}, the result would be a @code{gdb.Value} +object identical to that corresponding to @code{ptr}. + +@smallexample +py_ptrref = gdb.parse_and_eval ("ptrref") +py_val = py_ptrref.dereference () +py_ptr = py_ptrref.referenced_value () +@end smallexample + +The @code{gdb.Value} object @code{py_val} is identical to that +corresponding to @code{val}, and @code{py_ptr} is identical to that +corresponding to @code{ptr}. In general, @code{Value.dereference} can +be applied whenever the C unary operator @code{*} can be applied +to the corresponding C value. For those cases where applying both +@code{Value.dereference} and @code{Value.referenced_value} is allowed, +the results obtained need not be identical (as we have seen in the above +example). The results are however identical when applied on +@code{gdb.Value} objects corresponding to pointers (@code{gdb.Value} +objects with type code @code{TYPE_CODE_PTR}) in a C/C@t{++} program. +@end defun + +@defun Value.referenced_value () +For pointer or reference data types, this method returns a new +@code{gdb.Value} object corresponding to the value referenced by the +pointer/reference value. For pointer data types, +@code{Value.dereference} and @code{Value.referenced_value} produce +identical results. The difference between these methods is that +@code{Value.dereference} cannot get the values referenced by reference +values. For example, consider a reference to an @code{int}, declared +in your C@t{++} program as + +@smallexample +int val = 10; +int &ref = val; +@end smallexample + +@noindent +then applying @code{Value.dereference} to the @code{gdb.Value} object +corresponding to @code{ref} will result in an error, while applying +@code{Value.referenced_value} will result in a @code{gdb.Value} object +identical to that corresponding to @code{val}. + +@smallexample +py_ref = gdb.parse_and_eval ("ref") +er_ref = py_ref.dereference () # Results in error +py_val = py_ref.referenced_value () # Returns the referenced value +@end smallexample + +The @code{gdb.Value} object @code{py_val} is identical to that +corresponding to @code{val}. +@end defun + +@defun Value.reference_value () +Return a @code{gdb.Value} object which is a reference to the value +encapsulated by this instance. +@end defun + +@defun Value.const_value () +Return a @code{gdb.Value} object which is a @code{const} version of the +value encapsulated by this instance. +@end defun + +@defun Value.dynamic_cast (type) +Like @code{Value.cast}, but works as if the C@t{++} @code{dynamic_cast} +operator were used. Consult a C@t{++} reference for details. +@end defun + +@defun Value.reinterpret_cast (type) +Like @code{Value.cast}, but works as if the C@t{++} @code{reinterpret_cast} +operator were used. Consult a C@t{++} reference for details. +@end defun + +@defun Value.format_string (...) +Convert a @code{gdb.Value} to a string, similarly to what the @code{print} +command does. Invoked with no arguments, this is equivalent to calling +the @code{str} function on the @code{gdb.Value}. The representation of +the same value may change across different versions of @value{GDBN}, so +you shouldn't, for instance, parse the strings returned by this method. + +All the arguments are keyword only. If an argument is not specified, the +current global default setting is used. + +@table @code +@item raw +@code{True} if pretty-printers (@pxref{Pretty Printing}) should not be +used to format the value. @code{False} if enabled pretty-printers +matching the type represented by the @code{gdb.Value} should be used to +format it. + +@item pretty_arrays +@code{True} if arrays should be pretty printed to be more convenient to +read, @code{False} if they shouldn't (see @code{set print array} in +@ref{Print Settings}). + +@item pretty_structs +@code{True} if structs should be pretty printed to be more convenient to +read, @code{False} if they shouldn't (see @code{set print pretty} in +@ref{Print Settings}). + +@item array_indexes +@code{True} if array indexes should be included in the string +representation of arrays, @code{False} if they shouldn't (see @code{set +print array-indexes} in @ref{Print Settings}). + +@item symbols +@code{True} if the string representation of a pointer should include the +corresponding symbol name (if one exists), @code{False} if it shouldn't +(see @code{set print symbol} in @ref{Print Settings}). + +@item unions +@code{True} if unions which are contained in other structures or unions +should be expanded, @code{False} if they shouldn't (see @code{set print +union} in @ref{Print Settings}). + +@item address +@code{True} if the string representation of a pointer should include the +address, @code{False} if it shouldn't (see @code{set print address} in +@ref{Print Settings}). + +@item nibbles +@code{True} if binary values should be displayed in groups of four bits, +known as nibbles. @code{False} if it shouldn't (@pxref{Print Settings, +set print nibbles}). + +@item deref_refs +@code{True} if C@t{++} references should be resolved to the value they +refer to, @code{False} (the default) if they shouldn't. Note that, unlike +for the @code{print} command, references are not automatically expanded +when using the @code{format_string} method or the @code{str} +function. There is no global @code{print} setting to change the default +behavior. + +@item actual_objects +@code{True} if the representation of a pointer to an object should +identify the @emph{actual} (derived) type of the object rather than the +@emph{declared} type, using the virtual function table. @code{False} if +the @emph{declared} type should be used. (See @code{set print object} in +@ref{Print Settings}). + +@item static_members +@code{True} if static members should be included in the string +representation of a C@t{++} object, @code{False} if they shouldn't (see +@code{set print static-members} in @ref{Print Settings}). + +@item max_characters +Number of string characters to print, @code{0} to follow +@code{max_elements}, or @code{UINT_MAX} to print an unlimited number +of characters (see @code{set print characters} in @ref{Print Settings}). + +@item max_elements +Number of array elements to print, or @code{0} to print an unlimited +number of elements (see @code{set print elements} in @ref{Print +Settings}). + +@item max_depth +The maximum depth to print for nested structs and unions, or @code{-1} +to print an unlimited number of elements (see @code{set print +max-depth} in @ref{Print Settings}). + +@item repeat_threshold +Set the threshold for suppressing display of repeated array elements, or +@code{0} to represent all elements, even if repeated. (See @code{set +print repeats} in @ref{Print Settings}). + +@item format +A string containing a single character representing the format to use for +the returned string. For instance, @code{'x'} is equivalent to using the +@value{GDBN} command @code{print} with the @code{/x} option and formats +the value as a hexadecimal number. + +@item styling +@code{True} if @value{GDBN} should apply styling to the returned +string. When styling is applied, the returned string might contain +ANSI terminal escape sequences. Escape sequences will only be +included if styling is turned on, see @ref{Output Styling}. +Additionally, @value{GDBN} only styles some value contents, so not +every output string will contain escape sequences. + +When @code{False}, which is the default, no output styling is applied. + +@item summary +@code{True} when just a summary should be printed. In this mode, +scalar values are printed in their entirety, but aggregates such as +structures or unions are omitted. This mode is used by @code{set +print frame-arguments scalars} (@pxref{Print Settings}). +@end table +@end defun + +@defun Value.to_array () +If this value is array-like (@pxref{Type.is_array_like}), then this +method converts it to an array, which is returned. If this value is +already an array, it is simply returned. Otherwise, an exception is +throw. +@end defun + +@defun Value.string (@r{[}encoding@r{[}, errors@r{[}, length@r{]]]}) +If this @code{gdb.Value} represents a string, then this method +converts the contents to a Python string. Otherwise, this method will +throw an exception. + +Values are interpreted as strings according to the rules of the +current language. If the optional length argument is given, the +string will be converted to that length, and will include any embedded +zeroes that the string may contain. Otherwise, for languages +where the string is zero-terminated, the entire string will be +converted. + +For example, in C-like languages, a value is a string if it is a pointer +to or an array of characters or ints of type @code{wchar_t}, @code{char16_t}, +or @code{char32_t}. + +If the optional @var{encoding} argument is given, it must be a string +naming the encoding of the string in the @code{gdb.Value}, such as +@code{"ascii"}, @code{"iso-8859-6"} or @code{"utf-8"}. It accepts +the same encodings as the corresponding argument to Python's +@code{string.decode} method, and the Python codec machinery will be used +to convert the string. If @var{encoding} is not given, or if +@var{encoding} is the empty string, then either the @code{target-charset} +(@pxref{Character Sets}) will be used, or a language-specific encoding +will be used, if the current language is able to supply one. + +The optional @var{errors} argument is the same as the corresponding +argument to Python's @code{string.decode} method. + +If the optional @var{length} argument is given, the string will be +fetched and converted to the given length. +@end defun + +@defun Value.lazy_string (@r{[}encoding @r{[}, length@r{]]}) +This method attempts to convert this @code{gdb.Value} to a +@code{gdb.LazyString} (@pxref{Lazy Strings In Python}). Values of +array or pointer type can be converted; for other types, this method +will throw an exception. + +If the optional @var{encoding} argument is given, it must be a string +naming the encoding of the @code{gdb.LazyString}. Some examples are: +@samp{ascii}, @samp{iso-8859-6} or @samp{utf-8}. If the +@var{encoding} argument is an encoding that @value{GDBN} does +recognize, @value{GDBN} will raise an error. + +When a lazy string is printed, the @value{GDBN} encoding machinery is +used to convert the string during printing. If the optional +@var{encoding} argument is not provided, or is an empty string, +@value{GDBN} will automatically select the encoding most suitable for +the string type. For further information on encoding in @value{GDBN} +please see @ref{Character Sets}. + +If the optional @var{length} argument is given, the string will be +fetched and encoded to the length of characters specified. If +the @var{length} argument is not provided, the string will be fetched +and encoded until a null of appropriate width is found. +@end defun + +@defun Value.fetch_lazy () +If the @code{gdb.Value} object is currently a lazy value +(@code{gdb.Value.is_lazy} is @code{True}), then the value is +fetched from the inferior. Any errors that occur in the process +will produce a Python exception. + +If the @code{gdb.Value} object is not a lazy value, this method +has no effect. + +This method does not return a value. +@end defun + + +@node Types In Python +@subsubsection Types In Python +@cindex types in Python +@cindex Python, working with types + +@tindex gdb.Type +@value{GDBN} represents types from the inferior using the class +@code{gdb.Type}. + +The following type-related functions are available in the @code{gdb} +module: + +@defun gdb.lookup_type (name @r{[}, block@r{]}) +This function looks up a type by its @var{name}, which must be a string. + +If @var{block} is given, then @var{name} is looked up in that scope. +Otherwise, it is searched for globally. + +Ordinarily, this function will return an instance of @code{gdb.Type}. +If the named type cannot be found, it will throw an exception. +@end defun + +Integer types can be found without looking them up by name. +@xref{Architectures In Python}, for the @code{integer_type} method. + +If the type is a structure or class type, or an enum type, the fields +of that type can be accessed using the Python @dfn{dictionary syntax}. +For example, if @code{some_type} is a @code{gdb.Type} instance holding +a structure type, you can access its @code{foo} field with: + +@smallexample +bar = some_type['foo'] +@end smallexample + +@code{bar} will be a @code{gdb.Field} object; see below under the +description of the @code{Type.fields} method for a description of the +@code{gdb.Field} class. + +An instance of @code{Type} has the following attributes: + +@defvar Type.alignof +The alignment of this type, in bytes. Type alignment comes from the +debugging information; if it was not specified, then @value{GDBN} will +use the relevant ABI to try to determine the alignment. In some +cases, even this is not possible, and zero will be returned. +@end defvar + +@defvar Type.code +The type code for this type. The type code will be one of the +@code{TYPE_CODE_} constants defined below. +@end defvar + +@defvar Type.dynamic +A boolean indicating whether this type is dynamic. In some +situations, such as Rust @code{enum} types or Ada variant records, the +concrete type of a value may vary depending on its contents. That is, +the declared type of a variable, or the type returned by +@code{gdb.lookup_type} may be dynamic; while the type of the +variable's value will be a concrete instance of that dynamic type. + +For example, consider this code: +@smallexample +int n; +int array[n]; +@end smallexample + +Here, at least conceptually (whether your compiler actually does this +is a separate issue), examining @w{@code{gdb.lookup_symbol("array", ...).type}} +could yield a @code{gdb.Type} which reports a size of @code{None}. +This is the dynamic type. + +However, examining @code{gdb.parse_and_eval("array").type} would yield +a concrete type, whose length would be known. +@end defvar + +@defvar Type.name +The name of this type. If this type has no name, then @code{None} +is returned. +@end defvar + +@defvar Type.sizeof +The size of this type, in target @code{char} units. Usually, a +target's @code{char} type will be an 8-bit byte. However, on some +unusual platforms, this type may have a different size. A dynamic +type may not have a fixed size; in this case, this attribute's value +will be @code{None}. +@end defvar + +@defvar Type.tag +The tag name for this type. The tag name is the name after +@code{struct}, @code{union}, or @code{enum} in C and C@t{++}; not all +languages have this concept. If this type has no tag name, then +@code{None} is returned. +@end defvar + +@defvar Type.objfile +The @code{gdb.Objfile} that this type was defined in, or @code{None} if +there is no associated objfile. +@end defvar + +@defvar Type.is_scalar +This property is @code{True} if the type is a scalar type, otherwise, +this property is @code{False}. Examples of non-scalar types include +structures, unions, and classes. +@end defvar + +@defvar Type.is_signed +For scalar types (those for which @code{Type.is_scalar} is +@code{True}), this property is @code{True} if the type is signed, +otherwise this property is @code{False}. + +Attempting to read this property for a non-scalar type (a type for +which @code{Type.is_scalar} is @code{False}), will raise a +@code{ValueError}. +@end defvar + +@defvar Type.is_array_like +@anchor{Type.is_array_like} +A boolean indicating whether this type is array-like. + +Some languages have array-like objects that are represented internally +as structures. For example, this is true for a Rust slice type, or +for an Ada unconstrained array. @value{GDBN} may know about these +types. This determination is done based on the language from which +the type originated. +@end defvar + +@defvar Type.is_string_like +A boolean indicating whether this type is string-like. Like +@code{Type.is_array_like}, this is determined based on the originating +language of the type. +@end defvar + +The following methods are provided: + +@defun Type.fields () + +Return the fields of this type. The behavior depends on the type code: + +@itemize @bullet + +@item +For structure and union types, this method returns the fields. + +@item +Enum types have one field per enum constant. + +@item +Function and method types have one field per parameter. The base types of +C@t{++} classes are also represented as fields. + +@item +Array types have one field representing the array's range. + +@item +If the type does not fit into one of these categories, a @code{TypeError} +is raised. + +@end itemize + +Each field is a @code{gdb.Field} object, with some pre-defined attributes: +@table @code +@item bitpos +This attribute is not available for @code{enum} or @code{static} +(as in C@t{++}) fields. The value is the position, counting +in bits, from the start of the containing type. Note that, in a +dynamic type, the position of a field may not be constant. In this +case, the value will be @code{None}. Also, a dynamic type may have +fields that do not appear in a corresponding concrete type. + +@item enumval +This attribute is only available for @code{enum} fields, and its value +is the enumeration member's integer representation. + +@item name +The name of the field, or @code{None} for anonymous fields. + +@item artificial +This is @code{True} if the field is artificial, usually meaning that +it was provided by the compiler and not the user. This attribute is +always provided, and is @code{False} if the field is not artificial. + +@item is_base_class +This is @code{True} if the field represents a base class of a C@t{++} +structure. This attribute is always provided, and is @code{False} +if the field is not a base class of the type that is the argument of +@code{fields}, or if that type was not a C@t{++} class. + +@item bitsize +If the field is packed, or is a bitfield, then this will have a +non-zero value, which is the size of the field in bits. Otherwise, +this will be zero; in this case the field's size is given by its type. + +@item type +The type of the field. This is usually an instance of @code{Type}, +but it can be @code{None} in some situations. + +@item parent_type +The type which contains this field. This is an instance of +@code{gdb.Type}. +@end table +@end defun + +@defun Type.array (n1 @r{[}, n2@r{]}) +Return a new @code{gdb.Type} object which represents an array of this +type. If one argument is given, it is the inclusive upper bound of +the array; in this case the lower bound is zero. If two arguments are +given, the first argument is the lower bound of the array, and the +second argument is the upper bound of the array. An array's length +must not be negative, but the bounds can be. +@end defun + +@defun Type.vector (n1 @r{[}, n2@r{]}) +Return a new @code{gdb.Type} object which represents a vector of this +type. If one argument is given, it is the inclusive upper bound of +the vector; in this case the lower bound is zero. If two arguments are +given, the first argument is the lower bound of the vector, and the +second argument is the upper bound of the vector. A vector's length +must not be negative, but the bounds can be. + +The difference between an @code{array} and a @code{vector} is that +arrays behave like in C: when used in expressions they decay to a pointer +to the first element whereas vectors are treated as first class values. +@end defun + +@defun Type.const () +Return a new @code{gdb.Type} object which represents a +@code{const}-qualified variant of this type. +@end defun + +@defun Type.volatile () +Return a new @code{gdb.Type} object which represents a +@code{volatile}-qualified variant of this type. +@end defun + +@defun Type.unqualified () +Return a new @code{gdb.Type} object which represents an unqualified +variant of this type. That is, the result is neither @code{const} nor +@code{volatile}. +@end defun + +@defun Type.range () +Return a Python @code{Tuple} object that contains two elements: the +low bound of the argument type and the high bound of that type. If +the type does not have a range, @value{GDBN} will raise a +@code{gdb.error} exception (@pxref{Exception Handling}). +@end defun + +@defun Type.reference () +Return a new @code{gdb.Type} object which represents a reference to this +type. +@end defun + +@defun Type.pointer () +Return a new @code{gdb.Type} object which represents a pointer to this +type. +@end defun + +@defun Type.strip_typedefs () +Return a new @code{gdb.Type} that represents the real type, +after removing all layers of typedefs. +@end defun + +@defun Type.target () +Return a new @code{gdb.Type} object which represents the target type +of this type. + +For a pointer type, the target type is the type of the pointed-to +object. For an array type (meaning C-like arrays), the target type is +the type of the elements of the array. For a function or method type, +the target type is the type of the return value. For a complex type, +the target type is the type of the elements. For a typedef, the +target type is the aliased type. + +If the type does not have a target, this method will throw an +exception. +@end defun + +@defun Type.template_argument (n @r{[}, block@r{]}) +If this @code{gdb.Type} is an instantiation of a template, this will +return a new @code{gdb.Value} or @code{gdb.Type} which represents the +value of the @var{n}th template argument (indexed starting at 0). + +If this @code{gdb.Type} is not a template type, or if the type has fewer +than @var{n} template arguments, this will throw an exception. +Ordinarily, only C@t{++} code will have template types. + +If @var{block} is given, then @var{name} is looked up in that scope. +Otherwise, it is searched for globally. +@end defun + +@defun Type.optimized_out () +Return @code{gdb.Value} instance of this type whose value is optimized +out. This allows a frame decorator to indicate that the value of an +argument or a local variable is not known. +@end defun + +Each type has a code, which indicates what category this type falls +into. The available type categories are represented by constants +defined in the @code{gdb} module: + +@vtable @code +@vindex TYPE_CODE_PTR +@item gdb.TYPE_CODE_PTR +The type is a pointer. + +@vindex TYPE_CODE_ARRAY +@item gdb.TYPE_CODE_ARRAY +The type is an array. + +@vindex TYPE_CODE_STRUCT +@item gdb.TYPE_CODE_STRUCT +The type is a structure. + +@vindex TYPE_CODE_UNION +@item gdb.TYPE_CODE_UNION +The type is a union. + +@vindex TYPE_CODE_ENUM +@item gdb.TYPE_CODE_ENUM +The type is an enum. + +@vindex TYPE_CODE_FLAGS +@item gdb.TYPE_CODE_FLAGS +A bit flags type, used for things such as status registers. + +@vindex TYPE_CODE_FUNC +@item gdb.TYPE_CODE_FUNC +The type is a function. + +@vindex TYPE_CODE_INT +@item gdb.TYPE_CODE_INT +The type is an integer type. + +@vindex TYPE_CODE_FLT +@item gdb.TYPE_CODE_FLT +A floating point type. + +@vindex TYPE_CODE_VOID +@item gdb.TYPE_CODE_VOID +The special type @code{void}. + +@vindex TYPE_CODE_SET +@item gdb.TYPE_CODE_SET +A Pascal set type. + +@vindex TYPE_CODE_RANGE +@item gdb.TYPE_CODE_RANGE +A range type, that is, an integer type with bounds. + +@vindex TYPE_CODE_STRING +@item gdb.TYPE_CODE_STRING +A string type. Note that this is only used for certain languages with +language-defined string types; C strings are not represented this way. + +@vindex TYPE_CODE_BITSTRING +@item gdb.TYPE_CODE_BITSTRING +A string of bits. It is deprecated. + +@vindex TYPE_CODE_ERROR +@item gdb.TYPE_CODE_ERROR +An unknown or erroneous type. + +@vindex TYPE_CODE_METHOD +@item gdb.TYPE_CODE_METHOD +A method type, as found in C@t{++}. + +@vindex TYPE_CODE_METHODPTR +@item gdb.TYPE_CODE_METHODPTR +A pointer-to-member-function. + +@vindex TYPE_CODE_MEMBERPTR +@item gdb.TYPE_CODE_MEMBERPTR +A pointer-to-member. + +@vindex TYPE_CODE_REF +@item gdb.TYPE_CODE_REF +A reference type. + +@vindex TYPE_CODE_RVALUE_REF +@item gdb.TYPE_CODE_RVALUE_REF +A C@t{++}11 rvalue reference type. + +@vindex TYPE_CODE_CHAR +@item gdb.TYPE_CODE_CHAR +A character type. + +@vindex TYPE_CODE_BOOL +@item gdb.TYPE_CODE_BOOL +A boolean type. + +@vindex TYPE_CODE_COMPLEX +@item gdb.TYPE_CODE_COMPLEX +A complex float type. + +@vindex TYPE_CODE_TYPEDEF +@item gdb.TYPE_CODE_TYPEDEF +A typedef to some other type. + +@vindex TYPE_CODE_NAMESPACE +@item gdb.TYPE_CODE_NAMESPACE +A C@t{++} namespace. + +@vindex TYPE_CODE_DECFLOAT +@item gdb.TYPE_CODE_DECFLOAT +A decimal floating point type. + +@vindex TYPE_CODE_INTERNAL_FUNCTION +@item gdb.TYPE_CODE_INTERNAL_FUNCTION +A function internal to @value{GDBN}. This is the type used to represent +convenience functions. + +@vindex TYPE_CODE_XMETHOD +@item gdb.TYPE_CODE_XMETHOD +A method internal to @value{GDBN}. This is the type used to represent +xmethods (@pxref{Writing an Xmethod}). + +@vindex TYPE_CODE_FIXED_POINT +@item gdb.TYPE_CODE_FIXED_POINT +A fixed-point number. + +@vindex TYPE_CODE_NAMESPACE +@item gdb.TYPE_CODE_NAMESPACE +A Fortran namelist. +@end vtable + +Further support for types is provided in the @code{gdb.types} +Python module (@pxref{gdb.types}). + +@node Pretty Printing API +@subsubsection Pretty Printing API +@cindex python pretty printing api + +A pretty-printer is just an object that holds a value and implements a +specific interface, defined here. An example output is provided +(@pxref{Pretty Printing}). + +Because @value{GDBN} did not document extensibility for +pretty-printers, by default @value{GDBN} will assume that only the +basic pretty-printer methods may be available. The basic methods are +marked as such, below. + +To allow extensibility, @value{GDBN} provides the +@code{gdb.ValuePrinter} base class. This class does not provide any +attributes or behavior, but instead serves as a tag that can be +recognized by @value{GDBN}. For such printers, @value{GDBN} reserves +all attributes starting with a lower-case letter. That is, in the +future, @value{GDBN} may add a new method or attribute to the +pretty-printer protocol, and @code{gdb.ValuePrinter}-based printers +are expected to handle this gracefully. A simple way to do this would +be to use a leading underscore (or two, following the Python +name-mangling scheme) to any attributes local to the implementation. + +@defun pretty_printer.children (self) +@value{GDBN} will call this method on a pretty-printer to compute the +children of the pretty-printer's value. + +This method must return an object conforming to the Python iterator +protocol. Each item returned by the iterator must be a tuple holding +two elements. The first element is the ``name'' of the child; the +second element is the child's value. The value can be any Python +object which is convertible to a @value{GDBN} value. + +This is a basic method, and is optional. If it does not exist, +@value{GDBN} will act as though the value has no children. + +For efficiency, the @code{children} method should lazily compute its +results. This will let @value{GDBN} read as few elements as +necessary, for example when various print settings (@pxref{Print +Settings}) or @code{-var-list-children} (@pxref{GDB/MI Variable +Objects}) limit the number of elements to be displayed. + +Children may be hidden from display based on the value of @samp{set +print max-depth} (@pxref{Print Settings}). +@end defun + +@defun pretty_printer.display_hint (self) +The CLI may call this method and use its result to change the +formatting of a value. The result will also be supplied to an MI +consumer as a @samp{displayhint} attribute of the variable being +printed. + +This is a basic method, and is optional. If it does exist, this +method must return a string or the special value @code{None}. + +Some display hints are predefined by @value{GDBN}: + +@table @samp +@item array +Indicate that the object being printed is ``array-like''. The CLI +uses this to respect parameters such as @code{set print elements} and +@code{set print array}. + +@item map +Indicate that the object being printed is ``map-like'', and that the +children of this value can be assumed to alternate between keys and +values. + +@item string +Indicate that the object being printed is ``string-like''. If the +printer's @code{to_string} method returns a Python string of some +kind, then @value{GDBN} will call its internal language-specific +string-printing function to format the string. For the CLI this means +adding quotation marks, possibly escaping some characters, respecting +@code{set print elements}, and the like. +@end table + +The special value @code{None} causes @value{GDBN} to apply the default +display rules. +@end defun + +@defun pretty_printer.to_string (self) +@value{GDBN} will call this method to display the string +representation of the value passed to the object's constructor. + +This is a basic method, and is optional. + +When printing from the CLI, if the @code{to_string} method exists, +then @value{GDBN} will prepend its result to the values returned by +@code{children}. Exactly how this formatting is done is dependent on +the display hint, and may change as more hints are added. Also, +depending on the print settings (@pxref{Print Settings}), the CLI may +print just the result of @code{to_string} in a stack trace, omitting +the result of @code{children}. + +If this method returns a string, it is printed verbatim. + +Otherwise, if this method returns an instance of @code{gdb.Value}, +then @value{GDBN} prints this value. This may result in a call to +another pretty-printer. + +If instead the method returns a Python value which is convertible to a +@code{gdb.Value}, then @value{GDBN} performs the conversion and prints +the resulting value. Again, this may result in a call to another +pretty-printer. Python scalars (integers, floats, and booleans) and +strings are convertible to @code{gdb.Value}; other types are not. + +Finally, if this method returns @code{None} then no further operations +are performed in this method and nothing is printed. + +If the result is not one of these types, an exception is raised. +@end defun + +@defun pretty_printer.num_children () +This is not a basic method, so @value{GDBN} will only ever call it for +objects derived from @code{gdb.ValuePrinter}. + +If available, this method should return the number of children. +@code{None} may be returned if the number can't readily be computed. +@end defun + +@defun pretty_printer.child (n) +This is not a basic method, so @value{GDBN} will only ever call it for +objects derived from @code{gdb.ValuePrinter}. + +If available, this method should return the child item (that is, a +tuple holding the name and value of this child) indicated by @var{n}. +Indices start at zero. +@end defun + +@value{GDBN} provides a function which can be used to look up the +default pretty-printer for a @code{gdb.Value}: + +@defun gdb.default_visualizer (value) +This function takes a @code{gdb.Value} object as an argument. If a +pretty-printer for this value exists, then it is returned. If no such +printer exists, then this returns @code{None}. +@end defun + +Normally, a pretty-printer can respect the user's print settings +(including temporarily applied settings, such as @samp{/x}) simply by +calling @code{Value.format_string} (@pxref{Values From Inferior}). +However, these settings can also be queried directly: + +@defun gdb.print_options () +Return a dictionary whose keys are the valid keywords that can be +given to @code{Value.format_string}, and whose values are the user's +settings. During a @code{print} or other operation, the values will +reflect any flags that are temporarily in effect. + +@smallexample +(gdb) python print (gdb.print_options ()['max_elements']) +200 +@end smallexample +@end defun + +@node Selecting Pretty-Printers +@subsubsection Selecting Pretty-Printers +@cindex selecting python pretty-printers + +@value{GDBN} provides several ways to register a pretty-printer: +globally, per program space, and per objfile. When choosing how to +register your pretty-printer, a good rule is to register it with the +smallest scope possible: that is prefer a specific objfile first, then +a program space, and only register a printer globally as a last +resort. + +@defvar gdb.pretty_printers +The Python list @code{gdb.pretty_printers} contains an array of +functions or callable objects that have been registered via addition +as a pretty-printer. Printers in this list are called @code{global} +printers, they're available when debugging all inferiors. +@end defvar + +Each @code{gdb.Progspace} contains a @code{pretty_printers} attribute. +Each @code{gdb.Objfile} also contains a @code{pretty_printers} +attribute. + +Each function on these lists is passed a single @code{gdb.Value} +argument and should return a pretty-printer object conforming to the +interface definition above (@pxref{Pretty Printing API}). If a function +cannot create a pretty-printer for the value, it should return +@code{None}. + +@value{GDBN} first checks the @code{pretty_printers} attribute of each +@code{gdb.Objfile} in the current program space and iteratively calls +each enabled lookup routine in the list for that @code{gdb.Objfile} +until it receives a pretty-printer object. +If no pretty-printer is found in the objfile lists, @value{GDBN} then +searches the pretty-printer list of the current program space, +calling each enabled function until an object is returned. +After these lists have been exhausted, it tries the global +@code{gdb.pretty_printers} list, again calling each enabled function until an +object is returned. + +The order in which the objfiles are searched is not specified. For a +given list, functions are always invoked from the head of the list, +and iterated over sequentially until the end of the list, or a printer +object is returned. + +For various reasons a pretty-printer may not work. +For example, the underlying data structure may have changed and +the pretty-printer is out of date. + +The consequences of a broken pretty-printer are severe enough that +@value{GDBN} provides support for enabling and disabling individual +printers. For example, if @code{print frame-arguments} is on, +a backtrace can become highly illegible if any argument is printed +with a broken printer. + +Pretty-printers are enabled and disabled by attaching an @code{enabled} +attribute to the registered function or callable object. If this attribute +is present and its value is @code{False}, the printer is disabled, otherwise +the printer is enabled. + +@node Writing a Pretty-Printer +@subsubsection Writing a Pretty-Printer +@cindex writing a pretty-printer + +A pretty-printer consists of two parts: a lookup function to detect +if the type is supported, and the printer itself. + +Here is an example showing how a @code{std::string} printer might be +written. @xref{Pretty Printing API}, for details on the API this class +must provide. Note that this example uses the @code{gdb.ValuePrinter} +base class, and is careful to use a leading underscore for its local +state. + +@smallexample +class StdStringPrinter(gdb.ValuePrinter): + "Print a std::string" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return self.__val['_M_dataplus']['_M_p'] + + def display_hint(self): + return 'string' +@end smallexample + +And here is an example showing how a lookup function for the printer +example above might be written. + +@smallexample +def str_lookup_function(val): + lookup_tag = val.type.tag + if lookup_tag is None: + return None + regex = re.compile("^std::basic_string$") + if regex.match(lookup_tag): + return StdStringPrinter(val) + return None +@end smallexample + +The example lookup function extracts the value's type, and attempts to +match it to a type that it can pretty-print. If it is a type the +printer can pretty-print, it will return a printer object. If not, it +returns @code{None}. + +We recommend that you put your core pretty-printers into a Python +package. If your pretty-printers are for use with a library, we +further recommend embedding a version number into the package name. +This practice will enable @value{GDBN} to load multiple versions of +your pretty-printers at the same time, because they will have +different names. + +You should write auto-loaded code (@pxref{Python Auto-loading}) such that it +can be evaluated multiple times without changing its meaning. An +ideal auto-load file will consist solely of @code{import}s of your +printer modules, followed by a call to a register pretty-printers with +the current objfile. + +Taken as a whole, this approach will scale nicely to multiple +inferiors, each potentially using a different library version. +Embedding a version number in the Python package name will ensure that +@value{GDBN} is able to load both sets of printers simultaneously. +Then, because the search for pretty-printers is done by objfile, and +because your auto-loaded code took care to register your library's +printers with a specific objfile, @value{GDBN} will find the correct +printers for the specific version of the library used by each +inferior. + +To continue the @code{std::string} example (@pxref{Pretty Printing API}), +this code might appear in @code{gdb.libstdcxx.v6}: + +@smallexample +def register_printers(objfile): + objfile.pretty_printers.append(str_lookup_function) +@end smallexample + +@noindent +And then the corresponding contents of the auto-load file would be: + +@smallexample +import gdb.libstdcxx.v6 +gdb.libstdcxx.v6.register_printers(gdb.current_objfile()) +@end smallexample + +The previous example illustrates a basic pretty-printer. +There are a few things that can be improved on. +The printer doesn't have a name, making it hard to identify in a +list of installed printers. The lookup function has a name, but +lookup functions can have arbitrary, even identical, names. + +Second, the printer only handles one type, whereas a library typically has +several types. One could install a lookup function for each desired type +in the library, but one could also have a single lookup function recognize +several types. The latter is the conventional way this is handled. +If a pretty-printer can handle multiple data types, then its +@dfn{subprinters} are the printers for the individual data types. + +The @code{gdb.printing} module provides a formal way of solving these +problems (@pxref{gdb.printing}). +Here is another example that handles multiple types. + +These are the types we are going to pretty-print: + +@smallexample +struct foo @{ int a, b; @}; +struct bar @{ struct foo x, y; @}; +@end smallexample + +Here are the printers: + +@smallexample +class fooPrinter(gdb.ValuePrinter): + """Print a foo object.""" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return ("a=<" + str(self.__val["a"]) + + "> b=<" + str(self.__val["b"]) + ">") + +class barPrinter(gdb.ValuePrinter): + """Print a bar object.""" + + def __init__(self, val): + self.__val = val + + def to_string(self): + return ("x=<" + str(self.__val["x"]) + + "> y=<" + str(self.__val["y"]) + ">") +@end smallexample + +This example doesn't need a lookup function, that is handled by the +@code{gdb.printing} module. Instead a function is provided to build up +the object that handles the lookup. + +@smallexample +import gdb.printing + +def build_pretty_printer(): + pp = gdb.printing.RegexpCollectionPrettyPrinter( + "my_library") + pp.add_printer('foo', '^foo$', fooPrinter) + pp.add_printer('bar', '^bar$', barPrinter) + return pp +@end smallexample + +And here is the autoload support: + +@smallexample +import gdb.printing +import my_library +gdb.printing.register_pretty_printer( + gdb.current_objfile(), + my_library.build_pretty_printer()) +@end smallexample + +Finally, when this printer is loaded into @value{GDBN}, here is the +corresponding output of @samp{info pretty-printer}: + +@smallexample +(gdb) info pretty-printer +my_library.so: + my_library + foo + bar +@end smallexample + +@node Type Printing API +@subsubsection Type Printing API +@cindex type printing API for Python + +@value{GDBN} provides a way for Python code to customize type display. +This is mainly useful for substituting canonical typedef names for +types. + +@cindex type printer +A @dfn{type printer} is just a Python object conforming to a certain +protocol. A simple base class implementing the protocol is provided; +see @ref{gdb.types}. A type printer must supply at least: + +@defivar type_printer enabled +A boolean which is True if the printer is enabled, and False +otherwise. This is manipulated by the @code{enable type-printer} +and @code{disable type-printer} commands. +@end defivar + +@defivar type_printer name +The name of the type printer. This must be a string. This is used by +the @code{enable type-printer} and @code{disable type-printer} +commands. +@end defivar + +@defmethod type_printer instantiate (self) +This is called by @value{GDBN} at the start of type-printing. It is +only called if the type printer is enabled. This method must return a +new object that supplies a @code{recognize} method, as described below. +@end defmethod + + +When displaying a type, say via the @code{ptype} command, @value{GDBN} +will compute a list of type recognizers. This is done by iterating +first over the per-objfile type printers (@pxref{Objfiles In Python}), +followed by the per-progspace type printers (@pxref{Progspaces In +Python}), and finally the global type printers. + +@value{GDBN} will call the @code{instantiate} method of each enabled +type printer. If this method returns @code{None}, then the result is +ignored; otherwise, it is appended to the list of recognizers. + +Then, when @value{GDBN} is going to display a type name, it iterates +over the list of recognizers. For each one, it calls the recognition +function, stopping if the function returns a non-@code{None} value. +The recognition function is defined as: + +@defmethod type_recognizer recognize (self, type) +If @var{type} is not recognized, return @code{None}. Otherwise, +return a string which is to be printed as the name of @var{type}. +The @var{type} argument will be an instance of @code{gdb.Type} +(@pxref{Types In Python}). +@end defmethod + +@value{GDBN} uses this two-pass approach so that type printers can +efficiently cache information without holding on to it too long. For +example, it can be convenient to look up type information in a type +printer and hold it for a recognizer's lifetime; if a single pass were +done then type printers would have to make use of the event system in +order to avoid holding information that could become stale as the +inferior changed. + +@node Frame Filter API +@subsubsection Filtering Frames +@cindex frame filters api + +Frame filters are Python objects that manipulate the visibility of a +frame or frames when a backtrace (@pxref{Backtrace}) is printed by +@value{GDBN}. + +Only commands that print a backtrace, or, in the case of @sc{gdb/mi} +commands (@pxref{GDB/MI}), those that return a collection of frames +are affected. The commands that work with frame filters are: + +@code{backtrace} (@pxref{backtrace-command,, The backtrace command}), +@code{-stack-list-frames} +(@pxref{-stack-list-frames,, The -stack-list-frames command}), +@code{-stack-list-variables} (@pxref{-stack-list-variables,, The +-stack-list-variables command}), @code{-stack-list-arguments} +@pxref{-stack-list-arguments,, The -stack-list-arguments command}) and +@code{-stack-list-locals} (@pxref{-stack-list-locals,, The +-stack-list-locals command}). + +A frame filter works by taking an iterator as an argument, applying +actions to the contents of that iterator, and returning another +iterator (or, possibly, the same iterator it was provided in the case +where the filter does not perform any operations). Typically, frame +filters utilize tools such as the Python's @code{itertools} module to +work with and create new iterators from the source iterator. +Regardless of how a filter chooses to apply actions, it must not alter +the underlying @value{GDBN} frame or frames, or attempt to alter the +call-stack within @value{GDBN}. This preserves data integrity within +@value{GDBN}. Frame filters are executed on a priority basis and care +should be taken that some frame filters may have been executed before, +and that some frame filters will be executed after. + +An important consideration when designing frame filters, and well +worth reflecting upon, is that frame filters should avoid unwinding +the call stack if possible. Some stacks can run very deep, into the +tens of thousands in some cases. To search every frame when a frame +filter executes may be too expensive at that step. The frame filter +cannot know how many frames it has to iterate over, and it may have to +iterate through them all. This ends up duplicating effort as +@value{GDBN} performs this iteration when it prints the frames. If +the filter can defer unwinding frames until frame decorators are +executed, after the last filter has executed, it should. @xref{Frame +Decorator API}, for more information on decorators. Also, there are +examples for both frame decorators and filters in later chapters. +@xref{Writing a Frame Filter}, for more information. + +The Python dictionary @code{gdb.frame_filters} contains key/object +pairings that comprise a frame filter. Frame filters in this +dictionary are called @code{global} frame filters, and they are +available when debugging all inferiors. These frame filters must +register with the dictionary directly. In addition to the +@code{global} dictionary, there are other dictionaries that are loaded +with different inferiors via auto-loading (@pxref{Python +Auto-loading}). The two other areas where frame filter dictionaries +can be found are: @code{gdb.Progspace} which contains a +@code{frame_filters} dictionary attribute, and each @code{gdb.Objfile} +object which also contains a @code{frame_filters} dictionary +attribute. + +When a command is executed from @value{GDBN} that is compatible with +frame filters, @value{GDBN} combines the @code{global}, +@code{gdb.Progspace} and all @code{gdb.Objfile} dictionaries currently +loaded. All of the @code{gdb.Objfile} dictionaries are combined, as +several frames, and thus several object files, might be in use. +@value{GDBN} then prunes any frame filter whose @code{enabled} +attribute is @code{False}. This pruned list is then sorted according +to the @code{priority} attribute in each filter. + +Once the dictionaries are combined, pruned and sorted, @value{GDBN} +creates an iterator which wraps each frame in the call stack in a +@code{FrameDecorator} object, and calls each filter in order. The +output from the previous filter will always be the input to the next +filter, and so on. + +Frame filters have a mandatory interface which each frame filter must +implement, defined here: + +@defun FrameFilter.filter (iterator) +@value{GDBN} will call this method on a frame filter when it has +reached the order in the priority list for that filter. + +For example, if there are four frame filters: + +@smallexample +Name Priority + +Filter1 5 +Filter2 10 +Filter3 100 +Filter4 1 +@end smallexample + +The order that the frame filters will be called is: + +@smallexample +Filter3 -> Filter2 -> Filter1 -> Filter4 +@end smallexample + +Note that the output from @code{Filter3} is passed to the input of +@code{Filter2}, and so on. + +This @code{filter} method is passed a Python iterator. This iterator +contains a sequence of frame decorators that wrap each +@code{gdb.Frame}, or a frame decorator that wraps another frame +decorator. The first filter that is executed in the sequence of frame +filters will receive an iterator entirely comprised of default +@code{FrameDecorator} objects. However, after each frame filter is +executed, the previous frame filter may have wrapped some or all of +the frame decorators with their own frame decorator. As frame +decorators must also conform to a mandatory interface, these +decorators can be assumed to act in a uniform manner (@pxref{Frame +Decorator API}). + +This method must return an object conforming to the Python iterator +protocol. Each item in the iterator must be an object conforming to +the frame decorator interface. If a frame filter does not wish to +perform any operations on this iterator, it should return that +iterator untouched. + +This method is not optional. If it does not exist, @value{GDBN} will +raise and print an error. +@end defun + +@defvar FrameFilter.name +The @code{name} attribute must be Python string which contains the +name of the filter displayed by @value{GDBN} (@pxref{Frame Filter +Management}). This attribute may contain any combination of letters +or numbers. Care should be taken to ensure that it is unique. This +attribute is mandatory. +@end defvar + +@defvar FrameFilter.enabled +The @code{enabled} attribute must be Python boolean. This attribute +indicates to @value{GDBN} whether the frame filter is enabled, and +should be considered when frame filters are executed. If +@code{enabled} is @code{True}, then the frame filter will be executed +when any of the backtrace commands detailed earlier in this chapter +are executed. If @code{enabled} is @code{False}, then the frame +filter will not be executed. This attribute is mandatory. +@end defvar + +@defvar FrameFilter.priority +The @code{priority} attribute must be Python integer. This attribute +controls the order of execution in relation to other frame filters. +There are no imposed limits on the range of @code{priority} other than +it must be a valid integer. The higher the @code{priority} attribute, +the sooner the frame filter will be executed in relation to other +frame filters. Although @code{priority} can be negative, it is +recommended practice to assume zero is the lowest priority that a +frame filter can be assigned. Frame filters that have the same +priority are executed in unsorted order in that priority slot. This +attribute is mandatory. 100 is a good default priority. +@end defvar + +@node Frame Decorator API +@subsubsection Decorating Frames +@cindex frame decorator api + +Frame decorators are sister objects to frame filters (@pxref{Frame +Filter API}). Frame decorators are applied by a frame filter and can +only be used in conjunction with frame filters. + +The purpose of a frame decorator is to customize the printed content +of each @code{gdb.Frame} in commands where frame filters are executed. +This concept is called decorating a frame. Frame decorators decorate +a @code{gdb.Frame} with Python code contained within each API call. +This separates the actual data contained in a @code{gdb.Frame} from +the decorated data produced by a frame decorator. This abstraction is +necessary to maintain integrity of the data contained in each +@code{gdb.Frame}. + +Frame decorators have a mandatory interface, defined below. + +@value{GDBN} already contains a frame decorator called +@code{FrameDecorator}. This contains substantial amounts of +boilerplate code to decorate the content of a @code{gdb.Frame}. It is +recommended that other frame decorators inherit and extend this +object, and only to override the methods needed. + +@tindex gdb.FrameDecorator +@code{FrameDecorator} is defined in the Python module +@code{gdb.FrameDecorator}, so your code can import it like: +@smallexample +from gdb.FrameDecorator import FrameDecorator +@end smallexample + +@defun FrameDecorator.elided (self) + +The @code{elided} method groups frames together in a hierarchical +system. An example would be an interpreter, where multiple low-level +frames make up a single call in the interpreted language. In this +example, the frame filter would elide the low-level frames and present +a single high-level frame, representing the call in the interpreted +language, to the user. + +The @code{elided} function must return an iterable and this iterable +must contain the frames that are being elided wrapped in a suitable +frame decorator. If no frames are being elided this function may +return an empty iterable, or @code{None}. Elided frames are indented +from normal frames in a @code{CLI} backtrace, or in the case of +@sc{gdb/mi}, are placed in the @code{children} field of the eliding +frame. + +It is the frame filter's task to also filter out the elided frames from +the source iterator. This will avoid printing the frame twice. +@end defun + +@defun FrameDecorator.function (self) + +This method returns the name of the function in the frame that is to +be printed. + +This method must return a Python string describing the function, or +@code{None}. + +If this function returns @code{None}, @value{GDBN} will not print any +data for this field. +@end defun + +@defun FrameDecorator.address (self) + +This method returns the address of the frame that is to be printed. + +This method must return a Python numeric integer type of sufficient +size to describe the address of the frame, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameDecorator.filename (self) + +This method returns the filename and path associated with this frame. + +This method must return a Python string containing the filename and +the path to the object file backing the frame, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameDecorator.line (self): + +This method returns the line number associated with the current +position within the function addressed by this frame. + +This method must return a Python integer type, or @code{None}. + +If this function returns a @code{None}, @value{GDBN} will not print +any data for this field. +@end defun + +@defun FrameDecorator.frame_args (self) +@anchor{frame_args} + +This method must return an iterable, or @code{None}. Returning an +empty iterable, or @code{None} means frame arguments will not be +printed for this frame. This iterable must contain objects that +implement two methods, described here. + +This object must implement a @code{symbol} method which takes a +single @code{self} parameter and must return a @code{gdb.Symbol} +(@pxref{Symbols In Python}), or a Python string. The object must also +implement a @code{value} method which takes a single @code{self} +parameter and must return a @code{gdb.Value} (@pxref{Values From +Inferior}), a Python value, or @code{None}. If the @code{value} +method returns @code{None}, and the @code{argument} method returns a +@code{gdb.Symbol}, @value{GDBN} will look-up and print the value of +the @code{gdb.Symbol} automatically. + +A brief example: + +@smallexample +class SymValueWrapper(): + + def __init__(self, symbol, value): + self.sym = symbol + self.val = value + + def value(self): + return self.val + + def symbol(self): + return self.sym + +class SomeFrameDecorator() +... +... + def frame_args(self): + args = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Only add + # symbols that are arguments. + for sym in block: + if not sym.is_argument: + continue + args.append(SymValueWrapper(sym,None)) + + # Add example synthetic argument. + args.append(SymValueWrapper(``foo'', 42)) + + return args +@end smallexample +@end defun + +@defun FrameDecorator.frame_locals (self) + +This method must return an iterable or @code{None}. Returning an +empty iterable, or @code{None} means frame local arguments will not be +printed for this frame. + +The object interface, the description of the various strategies for +reading frame locals, and the example are largely similar to those +described in the @code{frame_args} function, (@pxref{frame_args,,The +frame filter frame_args function}). Below is a modified example: + +@smallexample +class SomeFrameDecorator() +... +... + def frame_locals(self): + vars = [] + try: + block = self.inferior_frame.block() + except: + return None + + # Iterate over all symbols in a block. Add all + # symbols, except arguments. + for sym in block: + if sym.is_argument: + continue + vars.append(SymValueWrapper(sym,None)) + + # Add an example of a synthetic local variable. + vars.append(SymValueWrapper(``bar'', 99)) + + return vars +@end smallexample +@end defun + +@defun FrameDecorator.inferior_frame (self): + +This method must return the underlying @code{gdb.Frame} that this +frame decorator is decorating. @value{GDBN} requires the underlying +frame for internal frame information to determine how to print certain +values when printing a frame. +@end defun + +@node Writing a Frame Filter +@subsubsection Writing a Frame Filter +@cindex writing a frame filter + +There are three basic elements that a frame filter must implement: it +must correctly implement the documented interface (@pxref{Frame Filter +API}), it must register itself with @value{GDBN}, and finally, it must +decide if it is to work on the data provided by @value{GDBN}. In all +cases, whether it works on the iterator or not, each frame filter must +return an iterator. A bare-bones frame filter follows the pattern in +the following example. + +@smallexample +import gdb + +class FrameFilter(): + + def __init__(self): + # Frame filter attribute creation. + # + # 'name' is the name of the filter that GDB will display. + # + # 'priority' is the priority of the filter relative to other + # filters. + # + # 'enabled' is a boolean that indicates whether this filter is + # enabled and should be executed. + + self.name = "Foo" + self.priority = 100 + self.enabled = True + + # Register this frame filter with the global frame_filters + # dictionary. + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + # Just return the iterator. + return frame_iter +@end smallexample + +The frame filter in the example above implements the three +requirements for all frame filters. It implements the API, self +registers, and makes a decision on the iterator (in this case, it just +returns the iterator untouched). + +The first step is attribute creation and assignment, and as shown in +the comments the filter assigns the following attributes: @code{name}, +@code{priority} and whether the filter should be enabled with the +@code{enabled} attribute. + +The second step is registering the frame filter with the dictionary or +dictionaries that the frame filter has interest in. As shown in the +comments, this filter just registers itself with the global dictionary +@code{gdb.frame_filters}. As noted earlier, @code{gdb.frame_filters} +is a dictionary that is initialized in the @code{gdb} module when +@value{GDBN} starts. What dictionary a filter registers with is an +important consideration. Generally, if a filter is specific to a set +of code, it should be registered either in the @code{objfile} or +@code{progspace} dictionaries as they are specific to the program +currently loaded in @value{GDBN}. The global dictionary is always +present in @value{GDBN} and is never unloaded. Any filters registered +with the global dictionary will exist until @value{GDBN} exits. To +avoid filters that may conflict, it is generally better to register +frame filters against the dictionaries that more closely align with +the usage of the filter currently in question. @xref{Python +Auto-loading}, for further information on auto-loading Python scripts. + +@value{GDBN} takes a hands-off approach to frame filter registration, +therefore it is the frame filter's responsibility to ensure +registration has occurred, and that any exceptions are handled +appropriately. In particular, you may wish to handle exceptions +relating to Python dictionary key uniqueness. It is mandatory that +the dictionary key is the same as frame filter's @code{name} +attribute. When a user manages frame filters (@pxref{Frame Filter +Management}), the names @value{GDBN} will display are those contained +in the @code{name} attribute. + +The final step of this example is the implementation of the +@code{filter} method. As shown in the example comments, we define the +@code{filter} method and note that the method must take an iterator, +and also must return an iterator. In this bare-bones example, the +frame filter is not very useful as it just returns the iterator +untouched. However this is a valid operation for frame filters that +have the @code{enabled} attribute set, but decide not to operate on +any frames. + +In the next example, the frame filter operates on all frames and +utilizes a frame decorator to perform some work on the frames. +@xref{Frame Decorator API}, for further information on the frame +decorator interface. + +This example works on inlined frames. It highlights frames which are +inlined by tagging them with an ``[inlined]'' tag. By applying a +frame decorator to all frames with the Python @code{itertools imap} +method, the example defers actions to the frame decorator. Frame +decorators are only processed when @value{GDBN} prints the backtrace. + +This introduces a new decision making topic: whether to perform +decision making operations at the filtering step, or at the printing +step. In this example's approach, it does not perform any filtering +decisions at the filtering step beyond mapping a frame decorator to +each frame. This allows the actual decision making to be performed +when each frame is printed. This is an important consideration, and +well worth reflecting upon when designing a frame filter. An issue +that frame filters should avoid is unwinding the stack if possible. +Some stacks can run very deep, into the tens of thousands in some +cases. To search every frame to determine if it is inlined ahead of +time may be too expensive at the filtering step. The frame filter +cannot know how many frames it has to iterate over, and it would have +to iterate through them all. This ends up duplicating effort as +@value{GDBN} performs this iteration when it prints the frames. + +In this example decision making can be deferred to the printing step. +As each frame is printed, the frame decorator can examine each frame +in turn when @value{GDBN} iterates. From a performance viewpoint, +this is the most appropriate decision to make as it avoids duplicating +the effort that the printing step would undertake anyway. Also, if +there are many frame filters unwinding the stack during filtering, it +can substantially delay the printing of the backtrace which will +result in large memory usage, and a poor user experience. + +@smallexample +class InlineFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + frame_iter = itertools.imap(InlinedFrameDecorator, + frame_iter) + return frame_iter +@end smallexample + +This frame filter is somewhat similar to the earlier example, except +that the @code{filter} method applies a frame decorator object called +@code{InlinedFrameDecorator} to each element in the iterator. The +@code{imap} Python method is light-weight. It does not proactively +iterate over the iterator, but rather creates a new iterator which +wraps the existing one. + +Below is the frame decorator for this example. + +@smallexample +class InlinedFrameDecorator(FrameDecorator): + + def __init__(self, fobj): + super(InlinedFrameDecorator, self).__init__(fobj) + + def function(self): + frame = self.inferior_frame() + name = str(frame.name()) + + if frame.type() == gdb.INLINE_FRAME: + name = name + " [inlined]" + + return name +@end smallexample + +This frame decorator only defines and overrides the @code{function} +method. It lets the supplied @code{FrameDecorator}, which is shipped +with @value{GDBN}, perform the other work associated with printing +this frame. + +The combination of these two objects create this output from a +backtrace: + +@smallexample +#0 0x004004e0 in bar () at inline.c:11 +#1 0x00400566 in max [inlined] (b=6, a=12) at inline.c:21 +#2 0x00400566 in main () at inline.c:31 +@end smallexample + +So in the case of this example, a frame decorator is applied to all +frames, regardless of whether they may be inlined or not. As +@value{GDBN} iterates over the iterator produced by the frame filters, +@value{GDBN} executes each frame decorator which then makes a decision +on what to print in the @code{function} callback. Using a strategy +like this is a way to defer decisions on the frame content to printing +time. + +@subheading Eliding Frames + +It might be that the above example is not desirable for representing +inlined frames, and a hierarchical approach may be preferred. If we +want to hierarchically represent frames, the @code{elided} frame +decorator interface might be preferable. + +This example approaches the issue with the @code{elided} method. This +example is quite long, but very simplistic. It is out-of-scope for +this section to write a complete example that comprehensively covers +all approaches of finding and printing inlined frames. However, this +example illustrates the approach an author might use. + +This example comprises of three sections. + +@smallexample +class InlineFrameFilter(): + + def __init__(self): + self.name = "InlinedFrameFilter" + self.priority = 100 + self.enabled = True + gdb.frame_filters[self.name] = self + + def filter(self, frame_iter): + return ElidingInlineIterator(frame_iter) +@end smallexample + +This frame filter is very similar to the other examples. The only +difference is this frame filter is wrapping the iterator provided to +it (@code{frame_iter}) with a custom iterator called +@code{ElidingInlineIterator}. This again defers actions to when +@value{GDBN} prints the backtrace, as the iterator is not traversed +until printing. + +The iterator for this example is as follows. It is in this section of +the example where decisions are made on the content of the backtrace. + +@smallexample +class ElidingInlineIterator: + def __init__(self, ii): + self.input_iterator = ii + + def __iter__(self): + return self + + def next(self): + frame = next(self.input_iterator) + + if frame.inferior_frame().type() != gdb.INLINE_FRAME: + return frame + + try: + eliding_frame = next(self.input_iterator) + except StopIteration: + return frame + return ElidingFrameDecorator(eliding_frame, [frame]) +@end smallexample + +This iterator implements the Python iterator protocol. When the +@code{next} function is called (when @value{GDBN} prints each frame), +the iterator checks if this frame decorator, @code{frame}, is wrapping +an inlined frame. If it is not, it returns the existing frame decorator +untouched. If it is wrapping an inlined frame, it assumes that the +inlined frame was contained within the next oldest frame, +@code{eliding_frame}, which it fetches. It then creates and returns a +frame decorator, @code{ElidingFrameDecorator}, which contains both the +elided frame, and the eliding frame. + +@smallexample +class ElidingInlineDecorator(FrameDecorator): + + def __init__(self, frame, elided_frames): + super(ElidingInlineDecorator, self).__init__(frame) + self.frame = frame + self.elided_frames = elided_frames + + def elided(self): + return iter(self.elided_frames) +@end smallexample + +This frame decorator overrides one function and returns the inlined +frame in the @code{elided} method. As before it lets +@code{FrameDecorator} do the rest of the work involved in printing +this frame. This produces the following output. + +@smallexample +#0 0x004004e0 in bar () at inline.c:11 +#2 0x00400529 in main () at inline.c:25 + #1 0x00400529 in max (b=6, a=12) at inline.c:15 +@end smallexample + +In that output, @code{max} which has been inlined into @code{main} is +printed hierarchically. Another approach would be to combine the +@code{function} method, and the @code{elided} method to both print a +marker in the inlined frame, and also show the hierarchical +relationship. + +@node Unwinding Frames in Python +@subsubsection Unwinding Frames in Python +@cindex unwinding frames in Python + +In @value{GDBN} terminology ``unwinding'' is the process of finding +the previous frame (that is, caller's) from the current one. An +unwinder has three methods. The first one checks if it can handle +given frame (``sniff'' it). For the frames it can sniff an unwinder +provides two additional methods: it can return frame's ID, and it can +fetch registers from the previous frame. A running @value{GDBN} +maintains a list of the unwinders and calls each unwinder's sniffer in +turn until it finds the one that recognizes the current frame. There +is an API to register an unwinder. + +The unwinders that come with @value{GDBN} handle standard frames. +However, mixed language applications (for example, an application +running Java Virtual Machine) sometimes use frame layouts that cannot +be handled by the @value{GDBN} unwinders. You can write Python code +that can handle such custom frames. + +You implement a frame unwinder in Python as a class with which has two +attributes, @code{name} and @code{enabled}, with obvious meanings, and +a single method @code{__call__}, which examines a given frame and +returns an object (an instance of @code{gdb.UnwindInfo class)} +describing it. If an unwinder does not recognize a frame, it should +return @code{None}. The code in @value{GDBN} that enables writing +unwinders in Python uses this object to return frame's ID and previous +frame registers when @value{GDBN} core asks for them. + +An unwinder should do as little work as possible. Some otherwise +innocuous operations can cause problems (even crashes, as this code is +not well-hardened yet). For example, making an inferior call from +an unwinder is unadvisable, as an inferior call will reset +@value{GDBN}'s stack unwinding process, potentially causing re-entrant +unwinding. + +@subheading Unwinder Input + +An object passed to an unwinder (a @code{gdb.PendingFrame} instance) +provides a method to read frame's registers: + +@defun PendingFrame.read_register (register) +This method returns the contents of @var{register} in the +frame as a @code{gdb.Value} object. For a description of the +acceptable values of @var{register} see +@ref{gdbpy_frame_read_register,,Frame.read_register}. If @var{register} +does not name a register for the current architecture, this method +will throw an exception. + +Note that this method will always return a @code{gdb.Value} for a +valid register name. This does not mean that the value will be valid. +For example, you may request a register that an earlier unwinder could +not unwind---the value will be unavailable. Instead, the +@code{gdb.Value} returned from this method will be lazy; that is, its +underlying bits will not be fetched until it is first used. So, +attempting to use such a value will cause an exception at the point of +use. + +The type of the returned @code{gdb.Value} depends on the register and +the architecture. It is common for registers to have a scalar type, +like @code{long long}; but many other types are possible, such as +pointer, pointer-to-function, floating point or vector types. +@end defun + +It also provides a factory method to create a @code{gdb.UnwindInfo} +instance to be returned to @value{GDBN}: + +@anchor{gdb.PendingFrame.create_unwind_info} +@defun PendingFrame.create_unwind_info (frame_id) +Returns a new @code{gdb.UnwindInfo} instance identified by given +@var{frame_id}. The @var{frame_id} is used internally by @value{GDBN} +to identify the frames within the current thread's stack. The +attributes of @var{frame_id} determine what type of frame is +created within @value{GDBN}: + +@table @code +@item sp, pc +The frame is identified by the given stack address and PC. The stack +address must be chosen so that it is constant throughout the lifetime +of the frame, so a typical choice is the value of the stack pointer at +the start of the function---in the DWARF standard, this would be the +``Call Frame Address''. + +This is the most common case by far. The other cases are documented +for completeness but are only useful in specialized situations. + +@item sp, pc, special +The frame is identified by the stack address, the PC, and a +``special'' address. The special address is used on architectures +that can have frames that do not change the stack, but which are still +distinct, for example the IA-64, which has a second stack for +registers. Both @var{sp} and @var{special} must be constant +throughout the lifetime of the frame. + +@item sp +The frame is identified by the stack address only. Any other stack +frame with a matching @var{sp} will be considered to match this frame. +Inside gdb, this is called a ``wild frame''. You will never need +this. +@end table + +Each attribute value should either be an instance of @code{gdb.Value} +or an integer. + +A helper class is provided in the @code{gdb.unwinder} module that can +be used to represent a frame-id +(@pxref{gdb.unwinder.FrameId}). + +@end defun + +@defun PendingFrame.architecture () +Return the @code{gdb.Architecture} (@pxref{Architectures In Python}) +for this @code{gdb.PendingFrame}. This represents the architecture of +the particular frame being unwound. +@end defun + +@defun PendingFrame.level () +Return an integer, the stack frame level for this frame. +@xref{Frames, ,Stack Frames}. +@end defun + +@defun PendingFrame.name () +Returns the function name of this pending frame, or @code{None} if it +can't be obtained. +@end defun + +@defun PendingFrame.is_valid () +Returns true if the @code{gdb.PendingFrame} object is valid, false if +not. A pending frame object becomes invalid when the call to the +unwinder, for which the pending frame was created, returns. + +All @code{gdb.PendingFrame} methods, except this one, will raise an +exception if the pending frame object is invalid at the time the +method is called. +@end defun + +@defun PendingFrame.pc () +Returns the pending frame's resume address. +@end defun + +@defun PendingFrame.block () +Return the pending frame's code block (@pxref{Blocks In Python}). If +the frame does not have a block -- for example, if there is no +debugging information for the code in question -- then this will raise +a @code{RuntimeError} exception. +@end defun + +@defun PendingFrame.function () +Return the symbol for the function corresponding to this pending frame. +@xref{Symbols In Python}. +@end defun + +@defun PendingFrame.find_sal () +Return the pending frame's symtab and line object (@pxref{Symbol +Tables In Python}). +@end defun + +@defun PendingFrame.language () +Return the language of this frame, as a string, or None. +@end defun + +@subheading Unwinder Output: UnwindInfo + +Use @code{PendingFrame.create_unwind_info} method described above to +create a @code{gdb.UnwindInfo} instance. Use the following method to +specify caller registers that have been saved in this frame: + +@defun gdb.UnwindInfo.add_saved_register (register, value) +@var{register} identifies the register, for a description of the acceptable +values see @ref{gdbpy_frame_read_register,,Frame.read_register}. +@var{value} is a register value (a @code{gdb.Value} object). +@end defun + +@subheading The @code{gdb.unwinder} Module + +@value{GDBN} comes with a @code{gdb.unwinder} module which contains +the following classes: + +@deftp {class} gdb.unwinder.Unwinder +The @code{Unwinder} class is a base class from which user created +unwinders can derive, though it is not required that unwinders derive +from this class, so long as any user created unwinder has the required +@code{name} and @code{enabled} attributes. + +@defun gdb.unwinder.Unwinder.__init__(name) +The @var{name} is a string used to reference this unwinder within some +@value{GDBN} commands (@pxref{Managing Registered Unwinders}). +@end defun + +@defvar gdb.unwinder.name +A read-only attribute which is a string, the name of this unwinder. +@end defvar + +@defvar gdb.unwinder.enabled +A modifiable attribute containing a boolean; when @code{True}, the +unwinder is enabled, and will be used by @value{GDBN}. When +@code{False}, the unwinder has been disabled, and will not be used. +@end defvar +@end deftp + +@anchor{gdb.unwinder.FrameId} +@deftp {class} gdb.unwinder.FrameId +This is a class suitable for being used as the frame-id when calling +@code{gdb.PendingFrame.create_unwind_info}. It is not required to use +this class, any class with the required attribute +(@pxref{gdb.PendingFrame.create_unwind_info}) will be accepted, but in +most cases this class will be sufficient. + +@code{gdb.unwinder.FrameId} has the following method: + +@defun gdb.unwinder.FrameId.__init__(sp, pc, special = @code{None}) +The @var{sp} and @var{pc} arguments are required and should be either +a @code{gdb.Value} object, or an integer. + +The @var{special} argument is optional; if specified, it should be a +@code{gdb.Value} object, or an integer. +@end defun + +@code{gdb.unwinder.FrameId} has the following read-only attributes: + +@defvar gdb.unwinder.sp +The @var{sp} value passed to the constructor. +@end defvar + +@defvar gdb.unwinder.pc +The @var{pc} value passed to the constructor. +@end defvar + +@defvar gdb.unwinder.special +The @var{special} value passed to the constructor, or @code{None} if +no such value was passed. +@end defvar +@end deftp + +@subheading Registering an Unwinder + +Object files and program spaces can have unwinders registered with +them. In addition, you can register unwinders globally. + +The @code{gdb.unwinders} module provides the function to register an +unwinder: + +@defun gdb.unwinder.register_unwinder (locus, unwinder, replace=False) +@var{locus} specifies to which unwinder list to prepend the +@var{unwinder}. It can be either an object file (@pxref{Objfiles In +Python}), a program space (@pxref{Progspaces In Python}), or +@code{None}, in which case the unwinder is registered globally. The +newly added @var{unwinder} will be called before any other unwinder +from the same locus. Two unwinders in the same locus cannot have the +same name. An attempt to add an unwinder with an already existing +name raises an exception unless @var{replace} is @code{True}, in which +case the old unwinder is deleted and the new unwinder is registered in +its place. + +@value{GDBN} first calls the unwinders from all the object files in no +particular order, then the unwinders from the current program space, +then the globally registered unwinders, and finally the unwinders +builtin to @value{GDBN}. +@end defun + +@subheading Unwinder Skeleton Code + +Here is an example of how to structure a user created unwinder: + +@smallexample +from gdb.unwinder import Unwinder, FrameId + +class MyUnwinder(Unwinder): + def __init__(self): + super().__init___("MyUnwinder_Name") + + def __call__(self, pending_frame): + if not : + return None + + # Create a FrameID. Usually the frame is identified by a + # stack pointer and the function address. + sp = ... compute a stack address ... + pc = ... compute function address ... + unwind_info = pending_frame.create_unwind_info(FrameId(sp, pc)) + + # Find the values of the registers in the caller's frame and + # save them in the result: + unwind_info.add_saved_register(, ) + .... + + # Return the result: + return unwind_info + +gdb.unwinder.register_unwinder(, MyUnwinder(), ) +@end smallexample + +@anchor{Managing Registered Unwinders} +@subheading Managing Registered Unwinders +@value{GDBN} defines 3 commands to manage registered unwinders. These +are: + +@table @code +@item info unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +Lists all registered unwinders. Arguments @var{locus} and +@var{name-regexp} are both optional and can be used to filter which +unwinders are listed. + +The @var{locus} argument should be either @kbd{global}, +@kbd{progspace}, or the name of an object file. Only unwinders +registered for the specified locus will be listed. + +The @var{name-regexp} is a regular expression used to match against +unwinder names. When trying to match against unwinder names that +include a string enclose @var{name-regexp} in quotes. +@item disable unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info +unwinder} above, but instead of listing the matching unwinders, all of +the matching unwinders are disabled. The @code{enabled} field of each +matching unwinder is set to @code{False}. +@item enable unwinder @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info +unwinder} above, but instead of listing the matching unwinders, all of +the matching unwinders are enabled. The @code{enabled} field of each +matching unwinder is set to @code{True}. +@end table + +@node Xmethods In Python +@subsubsection Xmethods In Python +@cindex xmethods in Python + +@dfn{Xmethods} are additional methods or replacements for existing +methods of a C@t{++} class. This feature is useful for those cases +where a method defined in C@t{++} source code could be inlined or +optimized out by the compiler, making it unavailable to @value{GDBN}. +For such cases, one can define an xmethod to serve as a replacement +for the method defined in the C@t{++} source code. @value{GDBN} will +then invoke the xmethod, instead of the C@t{++} method, to +evaluate expressions. One can also use xmethods when debugging +with core files. Moreover, when debugging live programs, invoking an +xmethod need not involve running the inferior (which can potentially +perturb its state). Hence, even if the C@t{++} method is available, it +is better to use its replacement xmethod if one is defined. + +The xmethods feature in Python is available via the concepts of an +@dfn{xmethod matcher} and an @dfn{xmethod worker}. To +implement an xmethod, one has to implement a matcher and a +corresponding worker for it (more than one worker can be +implemented, each catering to a different overloaded instance of the +method). Internally, @value{GDBN} invokes the @code{match} method of a +matcher to match the class type and method name. On a match, the +@code{match} method returns a list of matching @emph{worker} objects. +Each worker object typically corresponds to an overloaded instance of +the xmethod. They implement a @code{get_arg_types} method which +returns a sequence of types corresponding to the arguments the xmethod +requires. @value{GDBN} uses this sequence of types to perform +overload resolution and picks a winning xmethod worker. A winner +is also selected from among the methods @value{GDBN} finds in the +C@t{++} source code. Next, the winning xmethod worker and the +winning C@t{++} method are compared to select an overall winner. In +case of a tie between a xmethod worker and a C@t{++} method, the +xmethod worker is selected as the winner. That is, if a winning +xmethod worker is found to be equivalent to the winning C@t{++} +method, then the xmethod worker is treated as a replacement for +the C@t{++} method. @value{GDBN} uses the overall winner to invoke the +method. If the winning xmethod worker is the overall winner, then +the corresponding xmethod is invoked via the @code{__call__} method +of the worker object. + +If one wants to implement an xmethod as a replacement for an +existing C@t{++} method, then they have to implement an equivalent +xmethod which has exactly the same name and takes arguments of +exactly the same type as the C@t{++} method. If the user wants to +invoke the C@t{++} method even though a replacement xmethod is +available for that method, then they can disable the xmethod. + +@xref{Xmethod API}, for API to implement xmethods in Python. +@xref{Writing an Xmethod}, for implementing xmethods in Python. + +@node Xmethod API +@subsubsection Xmethod API +@cindex xmethod API + +The @value{GDBN} Python API provides classes, interfaces and functions +to implement, register and manipulate xmethods. +@xref{Xmethods In Python}. + +An xmethod matcher should be an instance of a class derived from +@code{XMethodMatcher} defined in the module @code{gdb.xmethod}, or an +object with similar interface and attributes. An instance of +@code{XMethodMatcher} has the following attributes: + +@defvar name +The name of the matcher. +@end defvar + +@defvar enabled +A boolean value indicating whether the matcher is enabled or disabled. +@end defvar + +@defvar methods +A list of named methods managed by the matcher. Each object in the list +is an instance of the class @code{XMethod} defined in the module +@code{gdb.xmethod}, or any object with the following attributes: + +@table @code + +@item name +Name of the xmethod which should be unique for each xmethod +managed by the matcher. + +@item enabled +A boolean value indicating whether the xmethod is enabled or +disabled. + +@end table + +The class @code{XMethod} is a convenience class with same +attributes as above along with the following constructor: + +@defun XMethod.__init__ (self, name) +Constructs an enabled xmethod with name @var{name}. +@end defun +@end defvar + +@noindent +The @code{XMethodMatcher} class has the following methods: + +@defun XMethodMatcher.__init__ (self, name) +Constructs an enabled xmethod matcher with name @var{name}. The +@code{methods} attribute is initialized to @code{None}. +@end defun + +@defun XMethodMatcher.match (self, class_type, method_name) +Derived classes should override this method. It should return a +xmethod worker object (or a sequence of xmethod worker +objects) matching the @var{class_type} and @var{method_name}. +@var{class_type} is a @code{gdb.Type} object, and @var{method_name} +is a string value. If the matcher manages named methods as listed in +its @code{methods} attribute, then only those worker objects whose +corresponding entries in the @code{methods} list are enabled should be +returned. +@end defun + +An xmethod worker should be an instance of a class derived from +@code{XMethodWorker} defined in the module @code{gdb.xmethod}, +or support the following interface: + +@defun XMethodWorker.get_arg_types (self) +This method returns a sequence of @code{gdb.Type} objects corresponding +to the arguments that the xmethod takes. It can return an empty +sequence or @code{None} if the xmethod does not take any arguments. +If the xmethod takes a single argument, then a single +@code{gdb.Type} object corresponding to it can be returned. +@end defun + +@defun XMethodWorker.get_result_type (self, *args) +This method returns a @code{gdb.Type} object representing the type +of the result of invoking this xmethod. +The @var{args} argument is the same tuple of arguments that would be +passed to the @code{__call__} method of this worker. +@end defun + +@defun XMethodWorker.__call__ (self, *args) +This is the method which does the @emph{work} of the xmethod. The +@var{args} arguments is the tuple of arguments to the xmethod. Each +element in this tuple is a gdb.Value object. The first element is +always the @code{this} pointer value. +@end defun + +For @value{GDBN} to lookup xmethods, the xmethod matchers +should be registered using the following function defined in the module +@code{gdb.xmethod}: + +@defun register_xmethod_matcher (locus, matcher, replace=False) +The @code{matcher} is registered with @code{locus}, replacing an +existing matcher with the same name as @code{matcher} if +@code{replace} is @code{True}. @code{locus} can be a +@code{gdb.Objfile} object (@pxref{Objfiles In Python}), or a +@code{gdb.Progspace} object (@pxref{Progspaces In Python}), or +@code{None}. If it is @code{None}, then @code{matcher} is registered +globally. +@end defun + +@node Writing an Xmethod +@subsubsection Writing an Xmethod +@cindex writing xmethods in Python + +Implementing xmethods in Python will require implementing xmethod +matchers and xmethod workers (@pxref{Xmethods In Python}). Consider +the following C@t{++} class: + +@smallexample +class MyClass +@{ +public: + MyClass (int a) : a_(a) @{ @} + + int geta (void) @{ return a_; @} + int operator+ (int b); + +private: + int a_; +@}; + +int +MyClass::operator+ (int b) +@{ + return a_ + b; +@} +@end smallexample + +@noindent +Let us define two xmethods for the class @code{MyClass}, one +replacing the method @code{geta}, and another adding an overloaded +flavor of @code{operator+} which takes a @code{MyClass} argument (the +C@t{++} code above already has an overloaded @code{operator+} +which takes an @code{int} argument). The xmethod matcher can be +defined as follows: + +@smallexample +class MyClass_geta(gdb.xmethod.XMethod): + def __init__(self): + gdb.xmethod.XMethod.__init__(self, 'geta') + + def get_worker(self, method_name): + if method_name == 'geta': + return MyClassWorker_geta() + + +class MyClass_sum(gdb.xmethod.XMethod): + def __init__(self): + gdb.xmethod.XMethod.__init__(self, 'sum') + + def get_worker(self, method_name): + if method_name == 'operator+': + return MyClassWorker_plus() + + +class MyClassMatcher(gdb.xmethod.XMethodMatcher): + def __init__(self): + gdb.xmethod.XMethodMatcher.__init__(self, 'MyClassMatcher') + # List of methods 'managed' by this matcher + self.methods = [MyClass_geta(), MyClass_sum()] + + def match(self, class_type, method_name): + if class_type.tag != 'MyClass': + return None + workers = [] + for method in self.methods: + if method.enabled: + worker = method.get_worker(method_name) + if worker: + workers.append(worker) + + return workers +@end smallexample + +@noindent +Notice that the @code{match} method of @code{MyClassMatcher} returns +a worker object of type @code{MyClassWorker_geta} for the @code{geta} +method, and a worker object of type @code{MyClassWorker_plus} for the +@code{operator+} method. This is done indirectly via helper classes +derived from @code{gdb.xmethod.XMethod}. One does not need to use the +@code{methods} attribute in a matcher as it is optional. However, if a +matcher manages more than one xmethod, it is a good practice to list the +xmethods in the @code{methods} attribute of the matcher. This will then +facilitate enabling and disabling individual xmethods via the +@code{enable/disable} commands. Notice also that a worker object is +returned only if the corresponding entry in the @code{methods} attribute +of the matcher is enabled. + +The implementation of the worker classes returned by the matcher setup +above is as follows: + +@smallexample +class MyClassWorker_geta(gdb.xmethod.XMethodWorker): + def get_arg_types(self): + return None + + def get_result_type(self, obj): + return gdb.lookup_type('int') + + def __call__(self, obj): + return obj['a_'] + + +class MyClassWorker_plus(gdb.xmethod.XMethodWorker): + def get_arg_types(self): + return gdb.lookup_type('MyClass') + + def get_result_type(self, obj): + return gdb.lookup_type('int') + + def __call__(self, obj, other): + return obj['a_'] + other['a_'] +@end smallexample + +For @value{GDBN} to actually lookup a xmethod, it has to be +registered with it. The matcher defined above is registered with +@value{GDBN} globally as follows: + +@smallexample +gdb.xmethod.register_xmethod_matcher(None, MyClassMatcher()) +@end smallexample + +If an object @code{obj} of type @code{MyClass} is initialized in C@t{++} +code as follows: + +@smallexample +MyClass obj(5); +@end smallexample + +@noindent +then, after loading the Python script defining the xmethod matchers +and workers into @value{GDBN}, invoking the method @code{geta} or using +the operator @code{+} on @code{obj} will invoke the xmethods +defined above: + +@smallexample +(gdb) p obj.geta() +$1 = 5 + +(gdb) p obj + obj +$2 = 10 +@end smallexample + +Consider another example with a C++ template class: + +@smallexample +template +class MyTemplate +@{ +public: + MyTemplate () : dsize_(10), data_ (new T [10]) @{ @} + ~MyTemplate () @{ delete [] data_; @} + + int footprint (void) + @{ + return sizeof (T) * dsize_ + sizeof (MyTemplate); + @} + +private: + int dsize_; + T *data_; +@}; +@end smallexample + +Let us implement an xmethod for the above class which serves as a +replacement for the @code{footprint} method. The full code listing +of the xmethod workers and xmethod matchers is as follows: + +@smallexample +class MyTemplateWorker_footprint(gdb.xmethod.XMethodWorker): + def __init__(self, class_type): + self.class_type = class_type + + def get_arg_types(self): + return None + + def get_result_type(self): + return gdb.lookup_type('int') + + def __call__(self, obj): + return (self.class_type.sizeof + + obj['dsize_'] * + self.class_type.template_argument(0).sizeof) + + +class MyTemplateMatcher_footprint(gdb.xmethod.XMethodMatcher): + def __init__(self): + gdb.xmethod.XMethodMatcher.__init__(self, 'MyTemplateMatcher') + + def match(self, class_type, method_name): + if (re.match('MyTemplate<[ \t\n]*[_a-zA-Z][ _a-zA-Z0-9]*>', + class_type.tag) and + method_name == 'footprint'): + return MyTemplateWorker_footprint(class_type) +@end smallexample + +Notice that, in this example, we have not used the @code{methods} +attribute of the matcher as the matcher manages only one xmethod. The +user can enable/disable this xmethod by enabling/disabling the matcher +itself. + +@node Inferiors In Python +@subsubsection Inferiors In Python +@cindex inferiors in Python + +@findex gdb.Inferior +Programs which are being run under @value{GDBN} are called inferiors +(@pxref{Inferiors Connections and Programs}). Python scripts can access +information about and manipulate inferiors controlled by @value{GDBN} +via objects of the @code{gdb.Inferior} class. + +The following inferior-related functions are available in the @code{gdb} +module: + +@defun gdb.inferiors () +Return a tuple containing all inferior objects. +@end defun + +@defun gdb.selected_inferior () +Return an object representing the current inferior. +@end defun + +A @code{gdb.Inferior} object has the following attributes: + +@defvar Inferior.num +ID of inferior, as assigned by @value{GDBN}. You can use this to make +Python breakpoints inferior-specific, for example +(@pxref{python_breakpoint_inferior,,The Breakpoint.inferior +attribute}). +@end defvar + +@anchor{gdbpy_inferior_connection} +@defvar Inferior.connection +The @code{gdb.TargetConnection} for this inferior (@pxref{Connections +In Python}), or @code{None} if this inferior has no connection. +@end defvar + +@defvar Inferior.connection_num +ID of inferior's connection as assigned by @value{GDBN}, or None if +the inferior is not connected to a target. @xref{Inferiors Connections +and Programs}. This is equivalent to +@code{gdb.Inferior.connection.num} in the case where +@code{gdb.Inferior.connection} is not @code{None}. +@end defvar + +@defvar Inferior.pid +Process ID of the inferior, as assigned by the underlying operating +system. +@end defvar + +@defvar Inferior.was_attached +Boolean signaling whether the inferior was created using `attach', or +started by @value{GDBN} itself. +@end defvar + +@defvar Inferior.main_name +A string holding the name of this inferior's ``main'' function, if it +can be determined. If the name of main is not known, this is +@code{None}. +@end defvar + +@defvar Inferior.progspace +The inferior's program space. @xref{Progspaces In Python}. +@end defvar + +@defvar Inferior.arguments +The inferior's command line arguments, if known. This corresponds to +the @code{set args} and @code{show args} commands. @xref{Arguments}. + +When accessed, the value is a string holding all the arguments. The +contents are quoted as they would be when passed to the shell. If +there are no arguments, the value is @code{None}. + +Either a string or a sequence of strings can be assigned to this +attribute. When a string is assigned, it is assumed to have any +necessary quoting for the shell; when a sequence is assigned, the +quoting is applied by @value{GDBN}. +@end defvar + +A @code{gdb.Inferior} object has the following methods: + +@defun Inferior.is_valid () +Returns @code{True} if the @code{gdb.Inferior} object is valid, +@code{False} if not. A @code{gdb.Inferior} object will become invalid +if the inferior no longer exists within @value{GDBN}. All other +@code{gdb.Inferior} methods will throw an exception if it is invalid +at the time the method is called. +@end defun + +@defun Inferior.threads () +This method returns a tuple holding all the threads which are valid +when it is called. If there are no valid threads, the method will +return an empty tuple. +@end defun + +@defun Inferior.architecture () +Return the @code{gdb.Architecture} (@pxref{Architectures In Python}) +for this inferior. This represents the architecture of the inferior +as a whole. Some platforms can have multiple architectures in a +single address space, so this may not match the architecture of a +particular frame (@pxref{Frames In Python}). +@end defun + +@anchor{gdbpy_inferior_read_memory} +@defun Inferior.read_memory (address, length) +Read @var{length} addressable memory units from the inferior, starting +at @var{address}. Returns a @code{memoryview} object, which behaves +much like an array or a string. It can be modified and given to the +@code{Inferior.write_memory} function. +@end defun + +@defun Inferior.write_memory (address, buffer @r{[}, length@r{]}) +Write the contents of @var{buffer} to the inferior, starting at +@var{address}. The @var{buffer} parameter must be a Python object +which supports the buffer protocol, i.e., a string, an array or the +object returned from @code{Inferior.read_memory}. If given, @var{length} +determines the number of addressable memory units from @var{buffer} to be +written. +@end defun + +@defun Inferior.search_memory (address, length, pattern) +Search a region of the inferior memory starting at @var{address} with +the given @var{length} using the search pattern supplied in +@var{pattern}. The @var{pattern} parameter must be a Python object +which supports the buffer protocol, i.e., a string, an array or the +object returned from @code{gdb.read_memory}. Returns a Python @code{Long} +containing the address where the pattern was found, or @code{None} if +the pattern could not be found. +@end defun + +@findex Inferior.thread_from_thread_handle +@defun Inferior.thread_from_handle (handle) +Return the thread object corresponding to @var{handle}, a thread +library specific data structure such as @code{pthread_t} for pthreads +library implementations. + +The function @code{Inferior.thread_from_thread_handle} provides +the same functionality, but use of @code{Inferior.thread_from_thread_handle} +is deprecated. +@end defun + + +The environment that will be passed to the inferior can be changed +from Python by using the following methods. These methods only take +effect when the inferior is started -- they will not affect an +inferior that is already executing. + +@defun Inferior.clear_env () +Clear the current environment variables that will be passed to this +inferior. +@end defun + +@defun Inferior.set_env (name, value) +Set the environment variable @var{name} to have the indicated value. +Both parameters must be strings. +@end defun + +@defun Inferior.unset_env (name) +Unset the environment variable @var{name}. @var{name} must be a +string. +@end defun + +One may add arbitrary attributes to @code{gdb.Inferior} objects in the +usual Python way. This is useful if, for example, one needs to do +some extra record keeping associated with the inferior. + +@anchor{choosing attribute names} +When selecting a name for a new attribute, avoid starting the new +attribute name with a lower case letter; future attributes added by +@value{GDBN} will start with a lower case letter. Additionally, avoid +starting attribute names with two underscore characters, as these +could clash with Python builtin attribute names. + +In this contrived example we record the time when an inferior last +stopped: + +@smallexample +@group +(@value{GDBP}) python +import datetime + +def thread_stopped(event): + if event.inferior_thread is not None: + thread = event.inferior_thread + else: + thread = gdb.selected_thread() + inferior = thread.inferior + inferior._last_stop_time = datetime.datetime.today() + +gdb.events.stop.connect(thread_stopped) +@end group +@group +(@value{GDBP}) file /tmp/hello +Reading symbols from /tmp/hello... +(@value{GDBP}) start +Temporary breakpoint 1 at 0x401198: file /tmp/hello.c, line 18. +Starting program: /tmp/hello + +Temporary breakpoint 1, main () at /tmp/hello.c:18 +18 printf ("Hello World\n"); +(@value{GDBP}) python print(gdb.selected_inferior()._last_stop_time) +2024-01-04 14:48:41.347036 +@end group +@end smallexample + +@node Events In Python +@subsubsection Events In Python +@cindex inferior events in Python + +@value{GDBN} provides a general event facility so that Python code can be +notified of various state changes, particularly changes that occur in +the inferior. + +An @dfn{event} is just an object that describes some state change. The +type of the object and its attributes will vary depending on the details +of the change. All the existing events are described below. + +In order to be notified of an event, you must register an event handler +with an @dfn{event registry}. An event registry is an object in the +@code{gdb.events} module which dispatches particular events. A registry +provides methods to register and unregister event handlers: + +@defun EventRegistry.connect (object) +Add the given callable @var{object} to the registry. This object will be +called when an event corresponding to this registry occurs. +@end defun + +@defun EventRegistry.disconnect (object) +Remove the given @var{object} from the registry. Once removed, the object +will no longer receive notifications of events. +@end defun + +Here is an example: + +@smallexample +def exit_handler (event): + print ("event type: exit") + if hasattr (event, 'exit_code'): + print ("exit code: %d" % (event.exit_code)) + else: + print ("exit code not available") + +gdb.events.exited.connect (exit_handler) +@end smallexample + +In the above example we connect our handler @code{exit_handler} to the +registry @code{events.exited}. Once connected, @code{exit_handler} gets +called when the inferior exits. The argument @dfn{event} in this example is +of type @code{gdb.ExitedEvent}. As you can see in the example the +@code{ExitedEvent} object has an attribute which indicates the exit code of +the inferior. + +Some events can be thread specific when @value{GDBN} is running in +non-stop mode. When represented in Python, these events all extend +@code{gdb.ThreadEvent}. This event is a base class and is never +emitted directly; instead, events which are emitted by this or other +modules might extend this event. Examples of these events are +@code{gdb.BreakpointEvent} and @code{gdb.ContinueEvent}. +@code{gdb.ThreadEvent} holds the following attributes: + +@defvar ThreadEvent.inferior_thread +In non-stop mode this attribute will be set to the specific thread which was +involved in the emitted event. Otherwise, it will be set to @code{None}. +@end defvar + +The following is a listing of the event registries that are available and +details of the events they emit: + +@table @code + +@item events.cont +Emits @code{gdb.ContinueEvent}, which extends @code{gdb.ThreadEvent}. +This event indicates that the inferior has been continued after a +stop. For inherited attribute refer to @code{gdb.ThreadEvent} above. + +@item events.exited +Emits @code{events.ExitedEvent}, which indicates that the inferior has +exited. @code{events.ExitedEvent} has two attributes: + +@defvar ExitedEvent.exit_code +An integer representing the exit code, if available, which the inferior +has returned. (The exit code could be unavailable if, for example, +@value{GDBN} detaches from the inferior.) If the exit code is unavailable, +the attribute does not exist. +@end defvar + +@defvar ExitedEvent.inferior +A reference to the inferior which triggered the @code{exited} event. +@end defvar + +@item events.stop +Emits @code{gdb.StopEvent}, which extends @code{gdb.ThreadEvent}. + +Indicates that the inferior has stopped. All events emitted by this +registry extend @code{gdb.StopEvent}. As a child of +@code{gdb.ThreadEvent}, @code{gdb.StopEvent} will indicate the stopped +thread when @value{GDBN} is running in non-stop mode. Refer to +@code{gdb.ThreadEvent} above for more details. + +@code{gdb.StopEvent} has the following additional attributes: + +@defvar StopEvent.details +A dictionary holding any details relevant to the stop. The exact keys +and values depend on the type of stop, but are identical to the +corresponding MI output (@pxref{GDB/MI Async Records}). + +A dictionary was used for this (rather than adding attributes directly +to the event object) so that the MI keys could be used unchanged. + +When a @code{StopEvent} results from a @code{finish} command, it will +also hold the return value from the function, if that is available. +This will be an entry named @samp{return-value} in the @code{details} +dictionary. The value of this entry will be a @code{gdb.Value} +object. +@end defvar + +Emits @code{gdb.SignalEvent}, which extends @code{gdb.StopEvent}. + +This event indicates that the inferior or one of its threads has +received a signal. @code{gdb.SignalEvent} has the following +attributes: + +@defvar SignalEvent.stop_signal +A string representing the signal received by the inferior. A list of possible +signal values can be obtained by running the command @code{info signals} in +the @value{GDBN} command prompt. +@end defvar + +Also emits @code{gdb.BreakpointEvent}, which extends +@code{gdb.StopEvent}. + +@code{gdb.BreakpointEvent} event indicates that one or more breakpoints have +been hit, and has the following attributes: + +@defvar BreakpointEvent.breakpoints +A sequence containing references to all the breakpoints (type +@code{gdb.Breakpoint}) that were hit. +@xref{Breakpoints In Python}, for details of the @code{gdb.Breakpoint} object. +@end defvar + +@defvar BreakpointEvent.breakpoint +A reference to the first breakpoint that was hit. This attribute is +maintained for backward compatibility and is now deprecated in favor +of the @code{gdb.BreakpointEvent.breakpoints} attribute. +@end defvar + +@item events.new_objfile +Emits @code{gdb.NewObjFileEvent} which indicates that a new object file has +been loaded by @value{GDBN}. @code{gdb.NewObjFileEvent} has one attribute: + +@defvar NewObjFileEvent.new_objfile +A reference to the object file (@code{gdb.Objfile}) which has been loaded. +@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object. +@end defvar + +@item events.free_objfile +Emits @code{gdb.FreeObjFileEvent} which indicates that an object file +is about to be removed from @value{GDBN}. One reason this can happen +is when the inferior calls @code{dlclose}. +@code{gdb.FreeObjFileEvent} has one attribute: + +@defvar FreeObjFileEvent.objfile +A reference to the object file (@code{gdb.Objfile}) which will be unloaded. +@xref{Objfiles In Python}, for details of the @code{gdb.Objfile} object. +@end defvar + +@item events.clear_objfiles +Emits @code{gdb.ClearObjFilesEvent} which indicates that the list of object +files for a program space has been reset. +@code{gdb.ClearObjFilesEvent} has one attribute: + +@defvar ClearObjFilesEvent.progspace +A reference to the program space (@code{gdb.Progspace}) whose objfile list has +been cleared. @xref{Progspaces In Python}. +@end defvar + +@item events.inferior_call +Emits events just before and after a function in the inferior is +called by @value{GDBN}. Before an inferior call, this emits an event +of type @code{gdb.InferiorCallPreEvent}, and after an inferior call, +this emits an event of type @code{gdb.InferiorCallPostEvent}. + +@table @code +@tindex gdb.InferiorCallPreEvent +@item @code{gdb.InferiorCallPreEvent} +Indicates that a function in the inferior is about to be called. + +@defvar InferiorCallPreEvent.ptid +The thread in which the call will be run. +@end defvar + +@defvar InferiorCallPreEvent.address +The location of the function to be called. +@end defvar + +@tindex gdb.InferiorCallPostEvent +@item @code{gdb.InferiorCallPostEvent} +Indicates that a function in the inferior has just been called. + +@defvar InferiorCallPostEvent.ptid +The thread in which the call was run. +@end defvar + +@defvar InferiorCallPostEvent.address +The location of the function that was called. +@end defvar +@end table + +@item events.memory_changed +Emits @code{gdb.MemoryChangedEvent} which indicates that the memory of the +inferior has been modified by the @value{GDBN} user, for instance via a +command like @w{@code{set *addr = value}}. The event has the following +attributes: + +@defvar MemoryChangedEvent.address +The start address of the changed region. +@end defvar + +@defvar MemoryChangedEvent.length +Length in bytes of the changed region. +@end defvar + +@item events.register_changed +Emits @code{gdb.RegisterChangedEvent} which indicates that a register in the +inferior has been modified by the @value{GDBN} user. + +@defvar RegisterChangedEvent.frame +A gdb.Frame object representing the frame in which the register was modified. +@end defvar +@defvar RegisterChangedEvent.regnum +Denotes which register was modified. +@end defvar + +@item events.breakpoint_created +This is emitted when a new breakpoint has been created. The argument +that is passed is the new @code{gdb.Breakpoint} object. + +@item events.breakpoint_modified +This is emitted when a breakpoint has been modified in some way. The +argument that is passed is the new @code{gdb.Breakpoint} object. + +@item events.breakpoint_deleted +This is emitted when a breakpoint has been deleted. The argument that +is passed is the @code{gdb.Breakpoint} object. When this event is +emitted, the @code{gdb.Breakpoint} object will already be in its +invalid state; that is, the @code{is_valid} method will return +@code{False}. + +@item events.before_prompt +This event carries no payload. It is emitted each time @value{GDBN} +presents a prompt to the user. + +@item events.new_inferior +This is emitted when a new inferior is created. Note that the +inferior is not necessarily running; in fact, it may not even have an +associated executable. + +The event is of type @code{gdb.NewInferiorEvent}. This has a single +attribute: + +@defvar NewInferiorEvent.inferior +The new inferior, a @code{gdb.Inferior} object. +@end defvar + +@item events.inferior_deleted +This is emitted when an inferior has been deleted. Note that this is +not the same as process exit; it is notified when the inferior itself +is removed, say via @code{remove-inferiors}. + +The event is of type @code{gdb.InferiorDeletedEvent}. This has a single +attribute: + +@defvar InferiorDeletedEvent.inferior +The inferior that is being removed, a @code{gdb.Inferior} object. +@end defvar + +@item events.new_thread +This is emitted when @value{GDBN} notices a new thread. The event is of +type @code{gdb.NewThreadEvent}, which extends @code{gdb.ThreadEvent}. +This has a single attribute: + +@defvar NewThreadEvent.inferior_thread +The new thread. +@end defvar + +@item events.thread_exited +This is emitted when @value{GDBN} notices a thread has exited. The event +is of type @code{gdb.ThreadExitedEvent} which extends @code{gdb.ThreadEvent}. +This has a single attribute: + +@defvar ThreadExitedEvent.inferior_thread +The exiting thread. +@end defvar + +@item events.gdb_exiting +This is emitted when @value{GDBN} exits. This event is not emitted if +@value{GDBN} exits as a result of an internal error, or after an +unexpected signal. The event is of type @code{gdb.GdbExitingEvent}, +which has a single attribute: + +@defvar GdbExitingEvent.exit_code +An integer, the value of the exit code @value{GDBN} will return. +@end defvar + +@item events.connection_removed +This is emitted when @value{GDBN} removes a connection +(@pxref{Connections In Python}). The event is of type +@code{gdb.ConnectionEvent}. This has a single read-only attribute: + +@defvar ConnectionEvent.connection +The @code{gdb.TargetConnection} that is being removed. +@end defvar + +@item events.executable_changed +Emits @code{gdb.ExecutableChangedEvent} which indicates that the +@code{gdb.Progspace.executable_filename} has changed. + +This event is emitted when either the value of +@code{gdb.Progspace.executable_filename } has changed to name a +different file, or the executable file named by +@code{gdb.Progspace.executable_filename} has changed on disk, and +@value{GDBN} has therefore reloaded it. + +@defvar ExecutableChangedEvent.progspace +The @code{gdb.Progspace} in which the current executable has changed. +The file name of the updated executable will be visible in +@code{gdb.Progspace.executable_filename} (@pxref{Progspaces In Python}). +@end defvar +@defvar ExecutableChangedEvent.reload +This attribute will be @code{True} if the value of +@code{gdb.Progspace.executable_filename} didn't change, but the file +it names changed on disk instead, and @value{GDBN} reloaded it. + +When this attribute is @code{False}, the value in +@code{gdb.Progspace.executable_filename} was changed to name a +different file. +@end defvar + +Remember that @value{GDBN} tracks the executable file and the symbol +file separately, these are visible as +@code{gdb.Progspace.executable_filename} and +@code{gdb.Progspace.filename} respectively. When using the @kbd{file} +command, @value{GDBN} updates both of these fields, but the executable +file is updated first, so when this event is emitted, the executable +filename will have changed, but the symbol filename might still hold +its previous value. + +@item events.new_progspace +This is emitted when @value{GDBN} adds a new program space +(@pxref{Progspaces In Python,,Program Spaces In Python}). The event +is of type @code{gdb.NewProgspaceEvent}, and has a single read-only +attribute: + +@defvar NewProgspaceEvent.progspace +The @code{gdb.Progspace} that was added to @value{GDBN}. +@end defvar + +No @code{NewProgspaceEvent} is emitted for the very first program +space, which is assigned to the first inferior. This first program +space is created within @value{GDBN} before any Python scripts are +sourced. + +@item events.free_progspace +This is emitted when @value{GDBN} removes a program space +(@pxref{Progspaces In Python,,Program Spaces In Python}), for example +as a result of the @kbd{remove-inferiors} command +(@pxref{remove_inferiors_cli,,@kbd{remove-inferiors}}). The event is +of type @code{gdb.FreeProgspaceEvent}, and has a single read-only +attribute: + +@defvar FreeProgspaceEvent.progspace +The @code{gdb.Progspace} that is about to be removed from +@value{GDBN}. +@end defvar + +@item events.tui_enabled +This is emitted when the TUI is enabled or disabled. The event is of +type @code{gdb.TuiEnabledEvent}, which has a single read-only +attribute: + +@defvar TuiEnabledEvent.enabled +If the TUI has just been enabled, this is @code{True}; otherwise it is +@code{False}. +@end defvar + +@end table + +@node Threads In Python +@subsubsection Threads In Python +@cindex threads in python + +@findex gdb.InferiorThread +Python scripts can access information about, and manipulate inferior threads +controlled by @value{GDBN}, via objects of the @code{gdb.InferiorThread} class. + +The following thread-related functions are available in the @code{gdb} +module: + +@defun gdb.selected_thread () +This function returns the thread object for the selected thread. If there +is no selected thread, this will return @code{None}. +@end defun + +To get the list of threads for an inferior, use the @code{Inferior.threads()} +method. @xref{Inferiors In Python}. + +A @code{gdb.InferiorThread} object has the following attributes: + +@defvar InferiorThread.name +The name of the thread. If the user specified a name using +@code{thread name}, then this returns that name. Otherwise, if an +OS-supplied name is available, then it is returned. Otherwise, this +returns @code{None}. + +This attribute can be assigned to. The new value must be a string +object, which sets the new name, or @code{None}, which removes any +user-specified thread name. +@end defvar + +@defvar InferiorThread.num +The per-inferior number of the thread, as assigned by GDB. +@end defvar + +@defvar InferiorThread.global_num +The global ID of the thread, as assigned by GDB. You can use this to +make Python breakpoints thread-specific, for example +(@pxref{python_breakpoint_thread,,The Breakpoint.thread attribute}). +@end defvar + +@anchor{inferior_thread_ptid} +@defvar InferiorThread.ptid +ID of the thread, as assigned by the operating system. This attribute is a +tuple containing three integers. The first is the Process ID (PID); the second +is the Lightweight Process ID (LWPID), and the third is the Thread ID (TID). +Either the LWPID or TID may be 0, which indicates that the operating system +does not use that identifier. +@end defvar + +@defvar InferiorThread.ptid_string +This read-only attribute contains a string representing +@code{InferiorThread.ptid}. This is the string that @value{GDBN} uses +in the @samp{Target Id} column in the @kbd{info threads} output +(@pxref{info_threads,,@samp{info threads}}). +@end defvar + +@defvar InferiorThread.inferior +The inferior this thread belongs to. This attribute is represented as +a @code{gdb.Inferior} object. This attribute is not writable. +@end defvar + +@defvar InferiorThread.details +A string containing target specific thread state information. The +format of this string varies by target. If there is no additional +state information for this thread, then this attribute contains +@code{None}. + +For example, on a @sc{gnu}/Linux system, a thread that is in the +process of exiting will return the string @samp{Exiting}. For remote +targets the @code{details} string will be obtained with the +@samp{qThreadExtraInfo} remote packet, if the target supports it +(@pxref{qThreadExtraInfo,,@samp{qThreadExtraInfo}}). + +@value{GDBN} displays the @code{details} string as part of the +@samp{Target Id} column, in the @code{info threads} output +(@pxref{info_threads,,@samp{info threads}}). +@end defvar + +A @code{gdb.InferiorThread} object has the following methods: + +@defun InferiorThread.is_valid () +Returns @code{True} if the @code{gdb.InferiorThread} object is valid, +@code{False} if not. A @code{gdb.InferiorThread} object will become +invalid if the thread exits, or the inferior that the thread belongs +is deleted. All other @code{gdb.InferiorThread} methods will throw an +exception if it is invalid at the time the method is called. +@end defun + +@defun InferiorThread.switch () +This changes @value{GDBN}'s currently selected thread to the one represented +by this object. +@end defun + +@defun InferiorThread.is_stopped () +Return a Boolean indicating whether the thread is stopped. +@end defun + +@defun InferiorThread.is_running () +Return a Boolean indicating whether the thread is running. +@end defun + +@defun InferiorThread.is_exited () +Return a Boolean indicating whether the thread is exited. +@end defun + +@defun InferiorThread.handle () +Return the thread object's handle, represented as a Python @code{bytes} +object. A @code{gdb.Value} representation of the handle may be +constructed via @code{gdb.Value(bufobj, type)} where @var{bufobj} is +the Python @code{bytes} representation of the handle and @var{type} is +a @code{gdb.Type} for the handle type. +@end defun + +One may add arbitrary attributes to @code{gdb.InferiorThread} objects +in the usual Python way. This is useful if, for example, one needs to +do some extra record keeping associated with the thread. + +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + +In this contrived example we record the time when a thread last +stopped: + +@smallexample +@group +(@value{GDBP}) python +import datetime + +def thread_stopped(event): + if event.inferior_thread is not None: + thread = event.inferior_thread + else: + thread = gdb.selected_thread() + thread._last_stop_time = datetime.datetime.today() + +gdb.events.stop.connect(thread_stopped) +@end group +@group +(@value{GDBP}) file /tmp/hello +Reading symbols from /tmp/hello... +(@value{GDBP}) start +Temporary breakpoint 1 at 0x401198: file /tmp/hello.c, line 18. +Starting program: /tmp/hello + +Temporary breakpoint 1, main () at /tmp/hello.c:18 +18 printf ("Hello World\n"); +(@value{GDBP}) python print(gdb.selected_thread()._last_stop_time) +2024-01-04 14:48:41.347036 +@end group +@end smallexample + +@node Recordings In Python +@subsubsection Recordings In Python +@cindex recordings in python + +The following recordings-related functions +(@pxref{Process Record and Replay}) are available in the @code{gdb} +module: + +@defun gdb.start_recording (@r{[}method@r{]}, @r{[}format@r{]}) +Start a recording using the given @var{method} and @var{format}. If +no @var{format} is given, the default format for the recording method +is used. If no @var{method} is given, the default method will be used. +Returns a @code{gdb.Record} object on success. Throw an exception on +failure. + +The following strings can be passed as @var{method}: + +@itemize @bullet +@item +@code{"full"} +@item +@code{"btrace"}: Possible values for @var{format}: @code{"pt"}, +@code{"bts"} or leave out for default format. +@end itemize +@end defun + +@defun gdb.current_recording () +Access a currently running recording. Return a @code{gdb.Record} +object on success. Return @code{None} if no recording is currently +active. +@end defun + +@defun gdb.stop_recording () +Stop the current recording. Throw an exception if no recording is +currently active. All record objects become invalid after this call. +@end defun + +A @code{gdb.Record} object has the following attributes: + +@defvar Record.method +A string with the current recording method, e.g.@: @code{full} or +@code{btrace}. +@end defvar + +@defvar Record.format +A string with the current recording format, e.g.@: @code{bt}, @code{pts} or +@code{None}. +@end defvar + +@defvar Record.begin +A method specific instruction object representing the first instruction +in this recording. +@end defvar + +@defvar Record.end +A method specific instruction object representing the current +instruction, that is not actually part of the recording. +@end defvar + +@defvar Record.replay_position +The instruction representing the current replay position. If there is +no replay active, this will be @code{None}. +@end defvar + +@defvar Record.instruction_history +A list with all recorded instructions. +@end defvar + +@defvar Record.function_call_history +A list with all recorded function call segments. +@end defvar + +A @code{gdb.Record} object has the following methods: + +@defun Record.goto (instruction) +Move the replay position to the given @var{instruction}. +@end defun + +@defun Record.clear () +Clear the trace data of the current recording. This forces re-decoding of the +trace for successive commands. +@end defun + +The common @code{gdb.Instruction} class that recording method specific +instruction objects inherit from, has the following attributes: + +@defvar Instruction.pc +An integer representing this instruction's address. +@end defvar + +@defvar Instruction.data +A @code{memoryview} object holding the raw instruction data. +@end defvar + +@defvar Instruction.decoded +A human readable string with the disassembled instruction. +@end defvar + +@defvar Instruction.size +The size of the instruction in bytes. +@end defvar + +Additionally @code{gdb.RecordInstruction} has the following attributes: + +@defvar RecordInstruction.number +An integer identifying this instruction. @code{number} corresponds to +the numbers seen in @code{record instruction-history} +(@pxref{Process Record and Replay}). +@end defvar + +@defvar RecordInstruction.sal +A @code{gdb.Symtab_and_line} object representing the associated symtab +and line of this instruction. May be @code{None} if no debug information is +available. +@end defvar + +@defvar RecordInstruction.is_speculative +A boolean indicating whether the instruction was executed speculatively. +@end defvar + +If an error occurred during recording or decoding a recording, this error is +represented by a @code{gdb.RecordGap} object in the instruction list. It has +the following attributes: + +@defvar RecordGap.number +An integer identifying this gap. @code{number} corresponds to the numbers seen +in @code{record instruction-history} (@pxref{Process Record and Replay}). +@end defvar + +@defvar RecordGap.error_code +A numerical representation of the reason for the gap. The value is specific to +the current recording method. +@end defvar + +@defvar RecordGap.error_string +A human readable string with the reason for the gap. +@end defvar + +Some @value{GDBN} features write auxiliary information into the execution +history. This information is represented by a @code{gdb.RecordAuxiliary} object +in the instruction list. It has the following attributes: + +@defvar RecordAuxiliary.@var{number} +An integer identifying this auxiliary. @var{number} corresponds to the numbers +seen in @code{record instruction-history} (@pxref{Process Record and Replay}). +@end defvar + +@defvar RecordAuxiliary.data +A string representation of the auxiliary data. +@end defvar + +A @code{gdb.RecordFunctionSegment} object has the following attributes: + +@defvar RecordFunctionSegment.number +An integer identifying this function segment. @code{number} corresponds to +the numbers seen in @code{record function-call-history} +(@pxref{Process Record and Replay}). +@end defvar + +@defvar RecordFunctionSegment.symbol +A @code{gdb.Symbol} object representing the associated symbol. May be +@code{None} if no debug information is available. +@end defvar + +@defvar RecordFunctionSegment.level +An integer representing the function call's stack level. May be +@code{None} if the function call is a gap. +@end defvar + +@defvar RecordFunctionSegment.instructions +A list of @code{gdb.RecordInstruction} or @code{gdb.RecordGap} objects +associated with this function call. +@end defvar + +@defvar RecordFunctionSegment.up +A @code{gdb.RecordFunctionSegment} object representing the caller's +function segment. If the call has not been recorded, this will be the +function segment to which control returns. If neither the call nor the +return have been recorded, this will be @code{None}. +@end defvar + +@defvar RecordFunctionSegment.prev +A @code{gdb.RecordFunctionSegment} object representing the previous +segment of this function call. May be @code{None}. +@end defvar + +@defvar RecordFunctionSegment.next +A @code{gdb.RecordFunctionSegment} object representing the next segment of +this function call. May be @code{None}. +@end defvar + +The following example demonstrates the usage of these objects and +functions to create a function that will rewind a record to the last +time a function in a different file was executed. This would typically +be used to track the execution of user provided callback functions in a +library which typically are not visible in a back trace. + +@smallexample +def bringback (): + rec = gdb.current_recording () + if not rec: + return + + insn = rec.instruction_history + if len (insn) == 0: + return + + try: + position = insn.index (rec.replay_position) + except: + position = -1 + try: + filename = insn[position].sal.symtab.fullname () + except: + filename = None + + for i in reversed (insn[:position]): + try: + current = i.sal.symtab.fullname () + except: + current = None + + if filename == current: + continue + + rec.goto (i) + return +@end smallexample + +Another possible application is to write a function that counts the +number of code executions in a given line range. This line range can +contain parts of functions or span across several functions and is not +limited to be contiguous. + +@smallexample +def countrange (filename, linerange): + count = 0 + + def filter_only (file_name): + for call in gdb.current_recording ().function_call_history: + try: + if file_name in call.symbol.symtab.fullname (): + yield call + except: + pass + + for c in filter_only (filename): + for i in c.instructions: + try: + if i.sal.line in linerange: + count += 1 + break; + except: + pass + + return count +@end smallexample + +@node CLI Commands In Python +@subsubsection CLI Commands In Python + +@cindex CLI commands in python +@cindex commands in python, CLI +@cindex python commands, CLI +You can implement new @value{GDBN} CLI commands in Python. A CLI +command is implemented using an instance of the @code{gdb.Command} +class, most commonly using a subclass. + +@defun Command.__init__ (name, command_class @r{[}, completer_class @r{[}, prefix@r{]]}) +The object initializer for @code{Command} registers the new command +with @value{GDBN}. This initializer is normally invoked from the +subclass' own @code{__init__} method. + +@var{name} is the name of the command. If @var{name} consists of +multiple words, then the initial words are looked for as prefix +commands. In this case, if one of the prefix commands does not exist, +an exception is raised. + +There is no support for multi-line commands. + +@var{command_class} should be one of the @samp{COMMAND_} constants +defined below. This argument tells @value{GDBN} how to categorize the +new command in the help system. + +@var{completer_class} is an optional argument. If given, it should be +one of the @samp{COMPLETE_} constants defined below. This argument +tells @value{GDBN} how to perform completion for this command. If not +given, @value{GDBN} will attempt to complete using the object's +@code{complete} method (see below); if no such method is found, an +error will occur when completion is attempted. + +@var{prefix} is an optional argument. If @code{True}, then the new +command is a prefix command; sub-commands of this command may be +registered. + +The help text for the new command is taken from the Python +documentation string for the command's class, if there is one. If no +documentation string is provided, the default value ``This command is +not documented.'' is used. +@end defun + +@cindex don't repeat Python command +@defun Command.dont_repeat () +By default, a @value{GDBN} command is repeated when the user enters a +blank line at the command prompt. A command can suppress this +behavior by invoking the @code{dont_repeat} method at some point in +its @code{invoke} method (normally this is done early in case of +exception). This is similar to the user command @code{dont-repeat}, +see @ref{Define, dont-repeat}. +@end defun + +@defun Command.invoke (argument, from_tty) +This method is called by @value{GDBN} when this command is invoked. + +@var{argument} is a string. It is the argument to the command, after +leading and trailing whitespace has been stripped. + +@var{from_tty} is a boolean argument. When true, this means that the +command was entered by the user at the terminal; when false it means +that the command came from elsewhere. + +If this method throws an exception, it is turned into a @value{GDBN} +@code{error} call. Otherwise, the return value is ignored. + +@findex gdb.string_to_argv +To break @var{argument} up into an argv-like string use +@code{gdb.string_to_argv}. This function behaves identically to +@value{GDBN}'s internal argument lexer @code{buildargv}. +It is recommended to use this for consistency. +Arguments are separated by spaces and may be quoted. +Example: + +@smallexample +print gdb.string_to_argv ("1 2\ \\\"3 '4 \"5' \"6 '7\"") +['1', '2 "3', '4 "5', "6 '7"] +@end smallexample + +@end defun + +@cindex completion of Python commands +@defun Command.complete (text, word) +This method is called by @value{GDBN} when the user attempts +completion on this command. All forms of completion are handled by +this method, that is, the @key{TAB} and @key{M-?} key bindings +(@pxref{Completion}), and the @code{complete} command (@pxref{Help, +complete}). + +The arguments @var{text} and @var{word} are both strings; @var{text} +holds the complete command line up to the cursor's location, while +@var{word} holds the last word of the command line; this is computed +using a word-breaking heuristic. + +The @code{complete} method can return several values: +@itemize @bullet +@item +If the return value is a sequence, the contents of the sequence are +used as the completions. It is up to @code{complete} to ensure that the +contents actually do complete the word. A zero-length sequence is +allowed, it means that there were no completions available. Only +string elements of the sequence are used; other elements in the +sequence are ignored. + +@item +If the return value is one of the @samp{COMPLETE_} constants defined +below, then the corresponding @value{GDBN}-internal completion +function is invoked, and its result is used. + +@item +All other results are treated as though there were no available +completions. +@end itemize +@end defun + +When a new command is registered, it must be declared as a member of +some general class of commands. This is used to classify top-level +commands in the on-line help system; note that prefix commands are not +listed under their own category but rather that of their top-level +command. The available classifications are represented by constants +defined in the @code{gdb} module: + +@table @code +@findex COMMAND_NONE +@findex gdb.COMMAND_NONE +@item gdb.COMMAND_NONE +The command does not belong to any particular class. A command in +this category will not be displayed in any of the help categories. + +@findex COMMAND_RUNNING +@findex gdb.COMMAND_RUNNING +@item gdb.COMMAND_RUNNING +The command is related to running the inferior. For example, +@code{start}, @code{step}, and @code{continue} are in this category. +Type @kbd{help running} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_DATA +@findex gdb.COMMAND_DATA +@item gdb.COMMAND_DATA +The command is related to data or variables. For example, +@code{call}, @code{find}, and @code{print} are in this category. Type +@kbd{help data} at the @value{GDBN} prompt to see a list of commands +in this category. + +@findex COMMAND_STACK +@findex gdb.COMMAND_STACK +@item gdb.COMMAND_STACK +The command has to do with manipulation of the stack. For example, +@code{backtrace}, @code{frame}, and @code{return} are in this +category. Type @kbd{help stack} at the @value{GDBN} prompt to see a +list of commands in this category. + +@findex COMMAND_FILES +@findex gdb.COMMAND_FILES +@item gdb.COMMAND_FILES +This class is used for file-related commands. For example, +@code{file}, @code{list} and @code{section} are in this category. +Type @kbd{help files} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_SUPPORT +@findex gdb.COMMAND_SUPPORT +@item gdb.COMMAND_SUPPORT +This should be used for ``support facilities'', generally meaning +things that are useful to the user when interacting with @value{GDBN}, +but not related to the state of the inferior. For example, +@code{help}, @code{make}, and @code{shell} are in this category. Type +@kbd{help support} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_STATUS +@findex gdb.COMMAND_STATUS +@item gdb.COMMAND_STATUS +The command is an @samp{info}-related command, that is, related to the +state of @value{GDBN} itself. For example, @code{info}, @code{macro}, +and @code{show} are in this category. Type @kbd{help status} at the +@value{GDBN} prompt to see a list of commands in this category. + +@findex COMMAND_BREAKPOINTS +@findex gdb.COMMAND_BREAKPOINTS +@item gdb.COMMAND_BREAKPOINTS +The command has to do with breakpoints. For example, @code{break}, +@code{clear}, and @code{delete} are in this category. Type @kbd{help +breakpoints} at the @value{GDBN} prompt to see a list of commands in +this category. + +@findex COMMAND_TRACEPOINTS +@findex gdb.COMMAND_TRACEPOINTS +@item gdb.COMMAND_TRACEPOINTS +The command has to do with tracepoints. For example, @code{trace}, +@code{actions}, and @code{tfind} are in this category. Type +@kbd{help tracepoints} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_TUI +@findex gdb.COMMAND_TUI +@item gdb.COMMAND_TUI +The command has to do with the text user interface (@pxref{TUI}). +Type @kbd{help tui} at the @value{GDBN} prompt to see a list of +commands in this category. + +@findex COMMAND_USER +@findex gdb.COMMAND_USER +@item gdb.COMMAND_USER +The command is a general purpose command for the user, and typically +does not fit in one of the other categories. +Type @kbd{help user-defined} at the @value{GDBN} prompt to see +a list of commands in this category, as well as the list of gdb macros +(@pxref{Sequences}). + +@findex COMMAND_OBSCURE +@findex gdb.COMMAND_OBSCURE +@item gdb.COMMAND_OBSCURE +The command is only used in unusual circumstances, or is not of +general interest to users. For example, @code{checkpoint}, +@code{fork}, and @code{stop} are in this category. Type @kbd{help +obscure} at the @value{GDBN} prompt to see a list of commands in this +category. + +@findex COMMAND_MAINTENANCE +@findex gdb.COMMAND_MAINTENANCE +@item gdb.COMMAND_MAINTENANCE +The command is only useful to @value{GDBN} maintainers. The +@code{maintenance} and @code{flushregs} commands are in this category. +Type @kbd{help internals} at the @value{GDBN} prompt to see a list of +commands in this category. +@end table + +A new command can use a predefined completion function, either by +specifying it via an argument at initialization, or by returning it +from the @code{complete} method. These predefined completion +constants are all defined in the @code{gdb} module: + +@vtable @code +@vindex COMPLETE_NONE +@item gdb.COMPLETE_NONE +This constant means that no completion should be done. + +@vindex COMPLETE_FILENAME +@item gdb.COMPLETE_FILENAME +This constant means that filename completion should be performed. + +@vindex COMPLETE_LOCATION +@item gdb.COMPLETE_LOCATION +This constant means that location completion should be done. +@xref{Location Specifications}. + +@vindex COMPLETE_COMMAND +@item gdb.COMPLETE_COMMAND +This constant means that completion should examine @value{GDBN} +command names. + +@vindex COMPLETE_SYMBOL +@item gdb.COMPLETE_SYMBOL +This constant means that completion should be done using symbol names +as the source. + +@vindex COMPLETE_EXPRESSION +@item gdb.COMPLETE_EXPRESSION +This constant means that completion should be done on expressions. +Often this means completing on symbol names, but some language +parsers also have support for completing on field names. +@end vtable + +The following code snippet shows how a trivial CLI command can be +implemented in Python: + +@smallexample +class HelloWorld (gdb.Command): + """Greet the whole world.""" + + def __init__ (self): + super (HelloWorld, self).__init__ ("hello-world", gdb.COMMAND_USER) + + def invoke (self, arg, from_tty): + print ("Hello, World!") + +HelloWorld () +@end smallexample + +The last line instantiates the class, and is necessary to trigger the +registration of the command with @value{GDBN}. Depending on how the +Python code is read into @value{GDBN}, you may need to import the +@code{gdb} module explicitly. + +@node GDB/MI Commands In Python +@subsubsection @sc{gdb/mi} Commands In Python + +@cindex MI commands in python +@cindex commands in python, GDB/MI +@cindex python commands, GDB/MI +It is possible to add @sc{gdb/mi} (@pxref{GDB/MI}) commands +implemented in Python. A @sc{gdb/mi} command is implemented using an +instance of the @code{gdb.MICommand} class, most commonly using a +subclass. + +@defun MICommand.__init__ (name) +The object initializer for @code{MICommand} registers the new command +with @value{GDBN}. This initializer is normally invoked from the +subclass' own @code{__init__} method. + +@var{name} is the name of the command. It must be a valid name of a +@sc{gdb/mi} command, and in particular must start with a hyphen +(@code{-}). Reusing the name of a built-in @sc{gdb/mi} is not +allowed, and a @code{RuntimeError} will be raised. Using the name +of an @sc{gdb/mi} command previously defined in Python is allowed, the +previous command will be replaced with the new command. +@end defun + +@defun MICommand.invoke (arguments) +This method is called by @value{GDBN} when the new MI command is +invoked. + +@var{arguments} is a list of strings. Note, that @code{--thread} +and @code{--frame} arguments are handled by @value{GDBN} itself therefore +they do not show up in @code{arguments}. + +If this method raises an exception, then it is turned into a +@sc{gdb/mi} @code{^error} response. Only @code{gdb.GdbError} +exceptions (or its sub-classes) should be used for reporting errors to +users, any other exception type is treated as a failure of the +@code{invoke} method, and the exception will be printed to the error +stream according to the @kbd{set python print-stack} setting +(@pxref{set_python_print_stack,,@kbd{set python print-stack}}). + +If this method returns @code{None}, then the @sc{gdb/mi} command will +return a @code{^done} response with no additional values. + +Otherwise, the return value must be a dictionary, which is converted +to a @sc{gdb/mi} @var{result-record} (@pxref{GDB/MI Output Syntax}). +The keys of this dictionary must be strings, and are used as +@var{variable} names in the @var{result-record}, these strings must +comply with the naming rules detailed below. The values of this +dictionary are recursively handled as follows: + +@itemize +@item +If the value is Python sequence or iterator, it is converted to +@sc{gdb/mi} @var{list} with elements converted recursively. + +@item +If the value is Python dictionary, it is converted to +@sc{gdb/mi} @var{tuple}. Keys in that dictionary must be strings, +which comply with the @var{variable} naming rules detailed below. +Values are converted recursively. + +@item +Otherwise, value is first converted to a Python string using +@code{str ()} and then converted to @sc{gdb/mi} @var{const}. +@end itemize + +The strings used for @var{variable} names in the @sc{gdb/mi} output +must follow the following rules; the string must be at least one +character long, the first character must be in the set +@code{[a-zA-Z]}, while every subsequent character must be in the set +@code{[-_a-zA-Z0-9]}. +@end defun + +An instance of @code{MICommand} has the following attributes: + +@defvar MICommand.name +A string, the name of this @sc{gdb/mi} command, as was passed to the +@code{__init__} method. This attribute is read-only. +@end defvar + +@defvar MICommand.installed +A boolean value indicating if this command is installed ready for a +user to call from the command line. Commands are automatically +installed when they are instantiated, after which this attribute will +be @code{True}. + +If later, a new command is created with the same name, then the +original command will become uninstalled, and this attribute will be +@code{False}. + +This attribute is read-write, setting this attribute to @code{False} +will uninstall the command, removing it from the set of available +commands. Setting this attribute to @code{True} will install the +command for use. If there is already a Python command with this name +installed, the currently installed command will be uninstalled, and +this command installed in its stead. +@end defvar + +The following code snippet shows how some trivial MI commands can be +implemented in Python: + +@smallexample +class MIEcho(gdb.MICommand): + """Echo arguments passed to the command.""" + + def __init__(self, name, mode): + self._mode = mode + super(MIEcho, self).__init__(name) + + def invoke(self, argv): + if self._mode == 'dict': + return @{ 'dict': @{ 'argv' : argv @} @} + elif self._mode == 'list': + return @{ 'list': argv @} + else: + return @{ 'string': ", ".join(argv) @} + + +MIEcho("-echo-dict", "dict") +MIEcho("-echo-list", "list") +MIEcho("-echo-string", "string") +@end smallexample + +The last three lines instantiate the class three times, creating three +new @sc{gdb/mi} commands @code{-echo-dict}, @code{-echo-list}, and +@code{-echo-string}. Each time a subclass of @code{gdb.MICommand} is +instantiated, the new command is automatically registered with +@value{GDBN}. + +Depending on how the Python code is read into @value{GDBN}, you may +need to import the @code{gdb} module explicitly. + +The following example shows a @value{GDBN} session in which the above +commands have been added: + +@smallexample +(@value{GDBP}) +-echo-dict abc def ghi +^done,dict=@{argv=["abc","def","ghi"]@} +(@value{GDBP}) +-echo-list abc def ghi +^done,list=["abc","def","ghi"] +(@value{GDBP}) +-echo-string abc def ghi +^done,string="abc, def, ghi" +(@value{GDBP}) +@end smallexample + +Conversely, it is possible to execute @sc{gdb/mi} commands from +Python, with the results being a Python object and not a +specially-formatted string. This is done with the +@code{gdb.execute_mi} function. + +@defun gdb.execute_mi (command @r{[}, arg @r{]}@dots{}) +Invoke a @sc{gdb/mi} command. @var{command} is the name of the +command, a string. The arguments, @var{arg}, are passed to the +command. Each argument must also be a string. + +This function returns a Python dictionary whose contents reflect the +corresponding @sc{GDB/MI} command's output. Refer to the +documentation for these commands for details. Lists are represented +as Python lists, and tuples are represented as Python dictionaries. + +If the command fails, it will raise a Python exception. +@end defun + +Here is how this works using the commands from the example above: + +@smallexample +(@value{GDBP}) python print(gdb.execute_mi("-echo-dict", "abc", "def", "ghi")) +@{'dict': @{'argv': ['abc', 'def', 'ghi']@}@} +(@value{GDBP}) python print(gdb.execute_mi("-echo-list", "abc", "def", "ghi")) +@{'list': ['abc', 'def', 'ghi']@} +(@value{GDBP}) python print(gdb.execute_mi("-echo-string", "abc", "def", "ghi")) +@{'string': 'abc, def, ghi'@} +@end smallexample + +@node GDB/MI Notifications In Python +@subsubsection @sc{gdb/mi} Notifications In Python + +@cindex MI notifications in python +@cindex notifications in python, GDB/MI +@cindex python notifications, GDB/MI + +It is possible to emit @sc{gdb/mi} notifications from +Python. Use the @code{gdb.notify_mi} function to do that. + +@defun gdb.notify_mi (name @r{[}, data@r{]}) +Emit a @sc{gdb/mi} asynchronous notification. @var{name} is the name of the +notification, consisting of alphanumeric characters and a hyphen (@code{-}). +@var{data} is any additional data to be emitted with the notification, passed +as a Python dictionary. This argument is optional. The dictionary is converted +to a @sc{gdb/mi} @var{result} records (@pxref{GDB/MI Output Syntax}) the same way +as result of Python MI command (@pxref{GDB/MI Commands In Python}). + +If @var{data} is @code{None} then no additional values are emitted. +@end defun + +While using existing notification names (@pxref{GDB/MI Async Records}) with +@code{gdb.notify_mi} is allowed, users are encouraged to prefix user-defined +notification with a hyphen (@code{-}) to avoid possible conflict. +@value{GDBN} will never introduce notification starting with hyphen. + +Here is how to emit @code{=-connection-removed} whenever a connection to remote +GDB server is closed (@pxref{Connections In Python}): + +@smallexample +def notify_connection_removed(event): + data = @{"id": event.connection.num, "type": event.connection.type@} + gdb.notify_mi("-connection-removed", data) + + +gdb.events.connection_removed.connect(notify_connection_removed) +@end smallexample + +Then, each time a connection is closed, there will be a notification on MI channel: + +@smallexample +=-connection-removed,id="1",type="remote" +@end smallexample + +@node Parameters In Python +@subsubsection Parameters In Python + +@cindex parameters in python +@cindex python parameters +@tindex gdb.Parameter +@tindex Parameter +You can implement new @value{GDBN} parameters using Python. A new +parameter is implemented as an instance of the @code{gdb.Parameter} +class. + +Parameters are exposed to the user via the @code{set} and +@code{show} commands. @xref{Help}. + +There are many parameters that already exist and can be set in +@value{GDBN}. Two examples are: @code{set follow fork} and +@code{set charset}. Setting these parameters influences certain +behavior in @value{GDBN}. Similarly, you can define parameters that +can be used to influence behavior in custom Python scripts and commands. + +@defun Parameter.__init__ (name, command_class, parameter_class @r{[}, enum_sequence@r{]}) +The object initializer for @code{Parameter} registers the new +parameter with @value{GDBN}. This initializer is normally invoked +from the subclass' own @code{__init__} method. + +@var{name} is the name of the new parameter. If @var{name} consists +of multiple words, then the initial words are looked for as prefix +parameters. An example of this can be illustrated with the +@code{set print} set of parameters. If @var{name} is +@code{print foo}, then @code{print} will be searched as the prefix +parameter. In this case the parameter can subsequently be accessed in +@value{GDBN} as @code{set print foo}. + +If @var{name} consists of multiple words, and no prefix parameter group +can be found, an exception is raised. + +@var{command_class} should be one of the @samp{COMMAND_} constants +(@pxref{CLI Commands In Python}). This argument tells @value{GDBN} how to +categorize the new parameter in the help system. + +@var{parameter_class} should be one of the @samp{PARAM_} constants +defined below. This argument tells @value{GDBN} the type of the new +parameter; this information is used for input validation and +completion. + +If @var{parameter_class} is @code{PARAM_ENUM}, then +@var{enum_sequence} must be a sequence of strings. These strings +represent the possible values for the parameter. + +If @var{parameter_class} is not @code{PARAM_ENUM}, then the presence +of a fourth argument will cause an exception to be thrown. + +The help text for the new parameter includes the Python documentation +string from the parameter's class, if there is one. If there is no +documentation string, a default value is used. The documentation +string is included in the output of the parameters @code{help set} and +@code{help show} commands, and should be written taking this into +account. +@end defun + +@defvar Parameter.set_doc +If this attribute exists, and is a string, then its value is used as +the first part of the help text for this parameter's @code{set} +command. The second part of the help text is taken from the +documentation string for the parameter's class, if there is one. + +The value of @code{set_doc} should give a brief summary specific to +the set action, this text is only displayed when the user runs the +@code{help set} command for this parameter. The class documentation +should be used to give a fuller description of what the parameter +does, this text is displayed for both the @code{help set} and +@code{help show} commands. + +The @code{set_doc} value is examined when @code{Parameter.__init__} is +invoked; subsequent changes have no effect. +@end defvar + +@defvar Parameter.show_doc +If this attribute exists, and is a string, then its value is used as +the first part of the help text for this parameter's @code{show} +command. The second part of the help text is taken from the +documentation string for the parameter's class, if there is one. + +The value of @code{show_doc} should give a brief summary specific to +the show action, this text is only displayed when the user runs the +@code{help show} command for this parameter. The class documentation +should be used to give a fuller description of what the parameter +does, this text is displayed for both the @code{help set} and +@code{help show} commands. + +The @code{show_doc} value is examined when @code{Parameter.__init__} +is invoked; subsequent changes have no effect. +@end defvar + +@defvar Parameter.value +The @code{value} attribute holds the underlying value of the +parameter. It can be read and assigned to just as any other +attribute. @value{GDBN} does validation when assignments are made. +@end defvar + +There are two methods that may be implemented in any @code{Parameter} +class. These are: + +@defun Parameter.get_set_string (self) +If this method exists, @value{GDBN} will call it when a +@var{parameter}'s value has been changed via the @code{set} API (for +example, @kbd{set foo off}). The @code{value} attribute has already +been populated with the new value and may be used in output. This +method must return a string. If the returned string is not empty, +@value{GDBN} will present it to the user. + +If this method raises the @code{gdb.GdbError} exception +(@pxref{Exception Handling}), then @value{GDBN} will print the +exception's string and the @code{set} command will fail. Note, +however, that the @code{value} attribute will not be reset in this +case. So, if your parameter must validate values, it should store the +old value internally and reset the exposed value, like so: + +@smallexample +class ExampleParam (gdb.Parameter): + def __init__ (self, name): + super (ExampleParam, self).__init__ (name, + gdb.COMMAND_DATA, + gdb.PARAM_BOOLEAN) + self.value = True + self.saved_value = True + def validate(self): + return False + def get_set_string (self): + if not self.validate(): + self.value = self.saved_value + raise gdb.GdbError('Failed to validate') + self.saved_value = self.value + return "" +@end smallexample +@end defun + +@defun Parameter.get_show_string (self, svalue) +@value{GDBN} will call this method when a @var{parameter}'s +@code{show} API has been invoked (for example, @kbd{show foo}). The +argument @code{svalue} receives the string representation of the +current value. This method must return a string. +@end defun + +When a new parameter is defined, its type must be specified. The +available types are represented by constants defined in the @code{gdb} +module: + +@table @code +@findex PARAM_BOOLEAN +@findex gdb.PARAM_BOOLEAN +@item gdb.PARAM_BOOLEAN +The value is a plain boolean. The Python boolean values, @code{True} +and @code{False} are the only valid values. + +@findex PARAM_AUTO_BOOLEAN +@findex gdb.PARAM_AUTO_BOOLEAN +@item gdb.PARAM_AUTO_BOOLEAN +The value has three possible states: true, false, and @samp{auto}. In +Python, true and false are represented using boolean constants, and +@samp{auto} is represented using @code{None}. + +@findex PARAM_UINTEGER +@findex gdb.PARAM_UINTEGER +@item gdb.PARAM_UINTEGER +The value is an unsigned integer. The value of @code{None} should be +interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also +be used to set that value), and the value of 0 is reserved and should +not be used. + +@findex PARAM_INTEGER +@findex gdb.PARAM_INTEGER +@item gdb.PARAM_INTEGER +The value is a signed integer. The value of @code{None} should be +interpreted to mean ``unlimited'' (literal @code{'unlimited'} can also +be used to set that value), and the value of 0 is reserved and should +not be used. + +@findex PARAM_STRING +@findex gdb.PARAM_STRING +@item gdb.PARAM_STRING +The value is a string. When the user modifies the string, any escape +sequences, such as @samp{\t}, @samp{\f}, and octal escapes, are +translated into corresponding characters and encoded into the current +host charset. + +@findex PARAM_STRING_NOESCAPE +@findex gdb.PARAM_STRING_NOESCAPE +@item gdb.PARAM_STRING_NOESCAPE +The value is a string. When the user modifies the string, escapes are +passed through untranslated. + +@findex PARAM_OPTIONAL_FILENAME +@findex gdb.PARAM_OPTIONAL_FILENAME +@item gdb.PARAM_OPTIONAL_FILENAME +The value is a either a filename (a string), or @code{None}. + +@findex PARAM_FILENAME +@findex gdb.PARAM_FILENAME +@item gdb.PARAM_FILENAME +The value is a filename. This is just like +@code{PARAM_STRING_NOESCAPE}, but uses file names for completion. + +@findex PARAM_ZINTEGER +@findex gdb.PARAM_ZINTEGER +@item gdb.PARAM_ZINTEGER +The value is a signed integer. This is like @code{PARAM_INTEGER}, +except that 0 is allowed and the value of @code{None} is not supported. + +@findex PARAM_ZUINTEGER +@findex gdb.PARAM_ZUINTEGER +@item gdb.PARAM_ZUINTEGER +The value is an unsigned integer. This is like @code{PARAM_UINTEGER}, +except that 0 is allowed and the value of @code{None} is not supported. + +@findex PARAM_ZUINTEGER_UNLIMITED +@findex gdb.PARAM_ZUINTEGER_UNLIMITED +@item gdb.PARAM_ZUINTEGER_UNLIMITED +The value is a signed integer. This is like @code{PARAM_INTEGER} +including that the value of @code{None} should be interpreted to mean +``unlimited'' (literal @code{'unlimited'} can also be used to set that +value), except that 0 is allowed, and the value cannot be negative, +except the special value -1 is returned for the setting of ``unlimited''. + +@findex PARAM_ENUM +@findex gdb.PARAM_ENUM +@item gdb.PARAM_ENUM +The value is a string, which must be one of a collection string +constants provided when the parameter is created. +@end table + +@node Functions In Python +@subsubsection Writing new convenience functions + +@cindex writing convenience functions +@cindex convenience functions in python +@cindex python convenience functions +@tindex gdb.Function +@tindex Function +You can implement new convenience functions (@pxref{Convenience Vars}) +in Python. A convenience function is an instance of a subclass of the +class @code{gdb.Function}. + +@defun Function.__init__ (name) +The initializer for @code{Function} registers the new function with +@value{GDBN}. The argument @var{name} is the name of the function, +a string. The function will be visible to the user as a convenience +variable of type @code{internal function}, whose name is the same as +the given @var{name}. + +The documentation for the new function is taken from the documentation +string for the new class. +@end defun + +@defun Function.invoke (*args) +When a convenience function is evaluated, its arguments are converted +to instances of @code{gdb.Value}, and then the function's +@code{invoke} method is called. Note that @value{GDBN} does not +predetermine the arity of convenience functions. Instead, all +available arguments are passed to @code{invoke}, following the +standard Python calling convention. In particular, a convenience +function can have default values for parameters without ill effect. + +The return value of this method is used as its value in the enclosing +expression. If an ordinary Python value is returned, it is converted +to a @code{gdb.Value} following the usual rules. +@end defun + +The following code snippet shows how a trivial convenience function can +be implemented in Python: + +@smallexample +class Greet (gdb.Function): + """Return string to greet someone. +Takes a name as argument.""" + + def __init__ (self): + super (Greet, self).__init__ ("greet") + + def invoke (self, name): + return "Hello, %s!" % name.string () + +Greet () +@end smallexample + +The last line instantiates the class, and is necessary to trigger the +registration of the function with @value{GDBN}. Depending on how the +Python code is read into @value{GDBN}, you may need to import the +@code{gdb} module explicitly. + +Now you can use the function in an expression: + +@smallexample +(gdb) print $greet("Bob") +$1 = "Hello, Bob!" +@end smallexample + +@node Progspaces In Python +@subsubsection Program Spaces In Python + +@cindex progspaces in python +@tindex gdb.Progspace +@tindex Progspace +A program space, or @dfn{progspace}, represents a symbolic view +of an address space. +It consists of all of the objfiles of the program. +@xref{Objfiles In Python}. +@xref{Inferiors Connections and Programs, program spaces}, for more details +about program spaces. + +The following progspace-related functions are available in the +@code{gdb} module: + +@defun gdb.current_progspace () +This function returns the program space of the currently selected inferior. +@xref{Inferiors Connections and Programs}. This is identical to +@code{gdb.selected_inferior().progspace} (@pxref{Inferiors In Python}) and is +included for historical compatibility. +@end defun + +@defun gdb.progspaces () +Return a sequence of all the progspaces currently known to @value{GDBN}. +@end defun + +Each progspace is represented by an instance of the @code{gdb.Progspace} +class. + +@defvar Progspace.filename +The file name, as a string, of the main symbol file (from which debug +symbols have been loaded) for the progspace, e.g.@: the argument to +the @kbd{symbol-file} or @kbd{file} commands. + +If there is no main symbol table currently loaded, then this attribute +will be @code{None}. +@end defvar + +@defvar Progspace.symbol_file +The @code{gdb.Objfile} representing the main symbol file (from which +debug symbols have been loaded) for the @code{gdb.Progspace}. This is +the symbol file set by the @kbd{symbol-file} or @kbd{file} commands. + +This will be the @code{gdb.Objfile} representing +@code{Progspace.filename} when @code{Progspace.filename} is not +@code{None}. + +If there is no main symbol table currently loaded, then this attribute +will be @code{None}. + +If the @code{Progspace} is invalid, i.e.@:, when +@code{Progspace.is_valid()} returns @code{False}, then attempting to +access this attribute will raise a @code{RuntimeError} exception. +@end defvar + +@defvar Progspace.executable_filename +The file name, as a string, of the executable file in use by this +program space. The executable file is the file that @value{GDBN} will +invoke in order to start an inferior when using a native target. The +file name within this attribute is updated by the @kbd{exec-file} and +@kbd{file} commands. + +If no executable is currently set within this @code{Progspace} then +this attribute contains @code{None}. + +If the @code{Progspace} is invalid, i.e.@:, when +@code{Progspace.is_valid()} returns @code{False}, then attempting to +access this attribute will raise a @code{RuntimeError} exception. +@end defvar + +@defvar Progspace.pretty_printers +The @code{pretty_printers} attribute is a list of functions. It is +used to look up pretty-printers. A @code{Value} is passed to each +function in order; if the function returns @code{None}, then the +search continues. Otherwise, the return value should be an object +which is used to format the value. @xref{Pretty Printing API}, for more +information. +@end defvar + +@defvar Progspace.type_printers +The @code{type_printers} attribute is a list of type printer objects. +@xref{Type Printing API}, for more information. +@end defvar + +@defvar Progspace.frame_filters +The @code{frame_filters} attribute is a dictionary of frame filter +objects. @xref{Frame Filter API}, for more information. +@end defvar + +@defvar Progspace.missing_file_handlers +The @code{missing_file_handlers} attribute is a list of tuples. Each +tuple holds a missing-file handler object for this program space. For +more information, @pxref{Missing Debug Info In Python}, and +@ref{Missing Objfiles In Python}. +@end defvar + +A program space has the following methods: + +@defun Progspace.block_for_pc (pc) +Return the innermost @code{gdb.Block} containing the given @var{pc} +value. If the block cannot be found for the @var{pc} value specified, +the function will return @code{None}. +@end defun + +@defun Progspace.find_pc_line (pc) +Return the @code{gdb.Symtab_and_line} object corresponding to the +@var{pc} value. @xref{Symbol Tables In Python}. If an invalid value +of @var{pc} is passed as an argument, then the @code{symtab} and +@code{line} attributes of the returned @code{gdb.Symtab_and_line} +object will be @code{None} and 0 respectively. +@end defun + +@defun Progspace.is_valid () +Returns @code{True} if the @code{gdb.Progspace} object is valid, +@code{False} if not. A @code{gdb.Progspace} object can become invalid +if the program space file it refers to is not referenced by any +inferior. All other @code{gdb.Progspace} methods will throw an +exception if it is invalid at the time the method is called. +@end defun + +@defun Progspace.objfiles () +Return a sequence of all the objfiles referenced by this program +space. @xref{Objfiles In Python}. +@end defun + +@defun Progspace.solib_name (address) +Return the name of the shared library holding the given @var{address} +as a string, or @code{None}. +@end defun + +@defun Progspace.objfile_for_address (address) +Return the @code{gdb.Objfile} holding the given address, or +@code{None} if no objfile covers it. +@end defun + +One may add arbitrary attributes to @code{gdb.Progspace} objects +in the usual Python way. +This is useful if, for example, one needs to do some extra record keeping +associated with the program space. + +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + +In this contrived example, we want to perform some processing when +an objfile with a certain symbol is loaded, but we only want to do +this once because it is expensive. To achieve this we record the results +with the program space because we can't predict when the desired objfile +will be loaded. + +@smallexample +(@value{GDBP}) python +@group +def clear_objfiles_handler(event): + event.progspace.expensive_computation = None +def expensive(symbol): + """A mock routine to perform an "expensive" computation on symbol.""" + print ("Computing the answer to the ultimate question ...") + return 42 +@end group +@group +def new_objfile_handler(event): + objfile = event.new_objfile + progspace = objfile.progspace + if not hasattr(progspace, 'expensive_computation') or \ + progspace.expensive_computation is None: + # We use 'main' for the symbol to keep the example simple. + # Note: There's no current way to constrain the lookup + # to one objfile. + symbol = gdb.lookup_global_symbol('main') + if symbol is not None: + progspace.expensive_computation = expensive(symbol) +gdb.events.clear_objfiles.connect(clear_objfiles_handler) +gdb.events.new_objfile.connect(new_objfile_handler) +end +@end group +@group +(@value{GDBP}) file /tmp/hello +Reading symbols from /tmp/hello... +Computing the answer to the ultimate question ... +(@value{GDBP}) python print(gdb.current_progspace().expensive_computation) +42 +(@value{GDBP}) run +Starting program: /tmp/hello +Hello. +[Inferior 1 (process 4242) exited normally] +@end group +@end smallexample + +@node Objfiles In Python +@subsubsection Objfiles In Python + +@cindex objfiles in python +@tindex gdb.Objfile +@tindex Objfile +@value{GDBN} loads symbols for an inferior from various +symbol-containing files (@pxref{Files}). These include the primary +executable file, any shared libraries used by the inferior, and any +separate debug info files (@pxref{Separate Debug Files}). +@value{GDBN} calls these symbol-containing files @dfn{objfiles}. + +The following objfile-related functions are available in the +@code{gdb} module: + +@defun gdb.current_objfile () +When auto-loading a Python script (@pxref{Python Auto-loading}), @value{GDBN} +sets the ``current objfile'' to the corresponding objfile. This +function returns the current objfile. If there is no current objfile, +this function returns @code{None}. +@end defun + +@defun gdb.objfiles () +Return a sequence of objfiles referenced by the current program space. +@xref{Objfiles In Python}, and @ref{Progspaces In Python}. This is identical +to @code{gdb.selected_inferior().progspace.objfiles()} and is included for +historical compatibility. +@end defun + +@defun gdb.lookup_objfile (name @r{[}, by_build_id@r{]}) +Look up @var{name}, a file name or build ID, in the list of objfiles +for the current program space (@pxref{Progspaces In Python}). +If the objfile is not found throw the Python @code{ValueError} exception. + +If @var{name} is a relative file name, then it will match any +source file name with the same trailing components. For example, if +@var{name} is @samp{gcc/expr.c}, then it will match source file +name of @file{/build/trunk/gcc/expr.c}, but not +@file{/build/trunk/libcpp/expr.c} or @file{/build/trunk/gcc/x-expr.c}. + +If @var{by_build_id} is provided and is @code{True} then @var{name} +is the build ID of the objfile. Otherwise, @var{name} is a file name. +This is supported only on some operating systems, notably those which use +the ELF format for binary files and the @sc{gnu} Binutils. For more details +about this feature, see the description of the @option{--build-id} +command-line option in @ref{Options, , Command Line Options, ld, +The GNU Linker}. +@end defun + +Each objfile is represented by an instance of the @code{gdb.Objfile} +class. + +@defvar Objfile.filename +The file name of the objfile as a string, with symbolic links resolved. + +The value is @code{None} if the objfile is no longer valid. +See the @code{gdb.Objfile.is_valid} method, described below. +@end defvar + +@defvar Objfile.username +The file name of the objfile as specified by the user as a string. + +The value is @code{None} if the objfile is no longer valid. +See the @code{gdb.Objfile.is_valid} method, described below. +@end defvar + +@defvar Objfile.is_file +An objfile often comes from an ordinary file, but in some cases it may +be constructed from the contents of memory. This attribute is +@code{True} for file-backed objfiles, and @code{False} for other +kinds. +@end defvar + +@defvar Objfile.owner +For separate debug info objfiles this is the corresponding @code{gdb.Objfile} +object that debug info is being provided for. +Otherwise this is @code{None}. +Separate debug info objfiles are added with the +@code{gdb.Objfile.add_separate_debug_file} method, described below. +@end defvar + +@anchor{Objfile.build_id} +@defvar Objfile.build_id +The build ID of the objfile as a string. +If the objfile does not have a build ID then the value is @code{None}. + +This is supported only on some operating systems, notably those which use +the ELF format for binary files and the @sc{gnu} Binutils. For more details +about this feature, see the description of the @option{--build-id} +command-line option in @ref{Options, , Command Line Options, ld, +The GNU Linker}. +@end defvar + +@defvar Objfile.progspace +The containing program space of the objfile as a @code{gdb.Progspace} +object. @xref{Progspaces In Python}. +@end defvar + +@defvar Objfile.pretty_printers +The @code{pretty_printers} attribute is a list of functions. It is +used to look up pretty-printers. A @code{Value} is passed to each +function in order; if the function returns @code{None}, then the +search continues. Otherwise, the return value should be an object +which is used to format the value. @xref{Pretty Printing API}, for more +information. +@end defvar + +@defvar Objfile.type_printers +The @code{type_printers} attribute is a list of type printer objects. +@xref{Type Printing API}, for more information. +@end defvar + +@defvar Objfile.frame_filters +The @code{frame_filters} attribute is a dictionary of frame filter +objects. @xref{Frame Filter API}, for more information. +@end defvar + +One may add arbitrary attributes to @code{gdb.Objfile} objects +in the usual Python way. +This is useful if, for example, one needs to do some extra record keeping +associated with the objfile. + +@xref{choosing attribute names}, for guidance on selecting a suitable +name for new attributes. + +In this contrived example we record the time when @value{GDBN} +loaded the objfile. + +@smallexample +@group +(@value{GDBP}) python +import datetime +def new_objfile_handler(event): + # Set the time_loaded attribute of the new objfile. + event.new_objfile.time_loaded = datetime.datetime.today() +gdb.events.new_objfile.connect(new_objfile_handler) +end +@end group +@group +(@value{GDBP}) file ./hello +Reading symbols from ./hello... +(@value{GDBP}) python print(gdb.objfiles()[0].time_loaded) +2014-10-09 11:41:36.770345 +@end group +@end smallexample + +A @code{gdb.Objfile} object has the following methods: + +@defun Objfile.is_valid () +Returns @code{True} if the @code{gdb.Objfile} object is valid, +@code{False} if not. A @code{gdb.Objfile} object can become invalid +if the object file it refers to is not loaded in @value{GDBN} any +longer. All other @code{gdb.Objfile} methods will throw an exception +if it is invalid at the time the method is called. +@end defun + +@defun Objfile.add_separate_debug_file (file) +Add @var{file} to the list of files that @value{GDBN} will search for +debug information for the objfile. +This is useful when the debug info has been removed from the program +and stored in a separate file. @value{GDBN} has built-in support for +finding separate debug info files (@pxref{Separate Debug Files}), but if +the file doesn't live in one of the standard places that @value{GDBN} +searches then this function can be used to add a debug info file +from a different place. +@end defun + +@defun Objfile.lookup_global_symbol (name @r{[}, domain@r{]}) +Search for a global symbol named @var{name} in this objfile. Optionally, the +search scope can be restricted with the @var{domain} argument. +The @var{domain} argument must be a domain constant defined in the @code{gdb} +module and described in @ref{Symbols In Python}. This function is similar to +@code{gdb.lookup_global_symbol}, except that the search is limited to this +objfile. + +The result is a @code{gdb.Symbol} object or @code{None} if the symbol +is not found. +@end defun + +@defun Objfile.lookup_static_symbol (name @r{[}, domain@r{]}) +Like @code{Objfile.lookup_global_symbol}, but searches for a global +symbol with static linkage named @var{name} in this objfile. +@end defun + +@node Frames In Python +@subsubsection Accessing inferior stack frames from Python + +@cindex frames in python +When the debugged program stops, @value{GDBN} is able to analyze its call +stack (@pxref{Frames,,Stack frames}). The @code{gdb.Frame} class +represents a frame in the stack. A @code{gdb.Frame} object is only valid +while its corresponding frame exists in the inferior's stack. If you try +to use an invalid frame object, @value{GDBN} will throw a @code{gdb.error} +exception (@pxref{Exception Handling}). + +Two @code{gdb.Frame} objects can be compared for equality with the @code{==} +operator, like: + +@smallexample +(@value{GDBP}) python print gdb.newest_frame() == gdb.selected_frame () +True +@end smallexample + +The following frame-related functions are available in the @code{gdb} module: + +@defun gdb.selected_frame () +Return the selected frame object. (@pxref{Selection,,Selecting a Frame}). +@end defun + +@defun gdb.newest_frame () +Return the newest frame object for the selected thread. +@end defun + +@defun gdb.frame_stop_reason_string (reason) +Return a string explaining the reason why @value{GDBN} stopped unwinding +frames, as expressed by the given @var{reason} code (an integer, see the +@code{unwind_stop_reason} method further down in this section). +@end defun + +@defun gdb.invalidate_cached_frames +@value{GDBN} internally keeps a cache of the frames that have been +unwound. This function invalidates this cache. + +This function should not generally be called by ordinary Python code. +It is documented for the sake of completeness. +@end defun + +A @code{gdb.Frame} object has the following methods: + +@defun Frame.is_valid () +Returns true if the @code{gdb.Frame} object is valid, false if not. +A frame object can become invalid if the frame it refers to doesn't +exist anymore in the inferior. All @code{gdb.Frame} methods will throw +an exception if it is invalid at the time the method is called. +@end defun + +@defun Frame.name () +Returns the function name of the frame, or @code{None} if it can't be +obtained. +@end defun + +@defun Frame.architecture () +Returns the @code{gdb.Architecture} object corresponding to the frame's +architecture. @xref{Architectures In Python}. +@end defun + +@defun Frame.type () +Returns the type of the frame. The value can be one of: +@table @code +@item gdb.NORMAL_FRAME +An ordinary stack frame. + +@item gdb.DUMMY_FRAME +A fake stack frame that was created by @value{GDBN} when performing an +inferior function call. + +@item gdb.INLINE_FRAME +A frame representing an inlined function. The function was inlined +into a @code{gdb.NORMAL_FRAME} that is older than this one. + +@item gdb.TAILCALL_FRAME +A frame representing a tail call. @xref{Tail Call Frames}. + +@item gdb.SIGTRAMP_FRAME +A signal trampoline frame. This is the frame created by the OS when +it calls into a signal handler. + +@item gdb.ARCH_FRAME +A fake stack frame representing a cross-architecture call. + +@item gdb.SENTINEL_FRAME +This is like @code{gdb.NORMAL_FRAME}, but it is only used for the +newest frame. +@end table +@end defun + +@defun Frame.unwind_stop_reason () +Return an integer representing the reason why it's not possible to find +more frames toward the outermost frame. Use +@code{gdb.frame_stop_reason_string} to convert the value returned by this +function to a string. The value can be one of: + +@table @code +@item gdb.FRAME_UNWIND_NO_REASON +No particular reason (older frames should be available). + +@item gdb.FRAME_UNWIND_NULL_ID +The previous frame's analyzer returns an invalid result. This is no +longer used by @value{GDBN}, and is kept only for backward +compatibility. + +@item gdb.FRAME_UNWIND_OUTERMOST +This frame is the outermost. + +@item gdb.FRAME_UNWIND_UNAVAILABLE +Cannot unwind further, because that would require knowing the +values of registers or memory that have not been collected. + +@item gdb.FRAME_UNWIND_INNER_ID +This frame ID looks like it ought to belong to a NEXT frame, +but we got it for a PREV frame. Normally, this is a sign of +unwinder failure. It could also indicate stack corruption. + +@item gdb.FRAME_UNWIND_SAME_ID +This frame has the same ID as the previous one. That means +that unwinding further would almost certainly give us another +frame with exactly the same ID, so break the chain. Normally, +this is a sign of unwinder failure. It could also indicate +stack corruption. + +@item gdb.FRAME_UNWIND_NO_SAVED_PC +The frame unwinder did not find any saved PC, but we needed +one to unwind further. + +@item gdb.FRAME_UNWIND_MEMORY_ERROR +The frame unwinder caused an error while trying to access memory. + +@item gdb.FRAME_UNWIND_FIRST_ERROR +Any stop reason greater or equal to this value indicates some kind +of error. This special value facilitates writing code that tests +for errors in unwinding in a way that will work correctly even if +the list of the other values is modified in future @value{GDBN} +versions. Using it, you could write: +@smallexample +reason = gdb.selected_frame().unwind_stop_reason () +reason_str = gdb.frame_stop_reason_string (reason) +if reason >= gdb.FRAME_UNWIND_FIRST_ERROR: + print ("An error occurred: %s" % reason_str) +@end smallexample +@end table + +@end defun + +@defun Frame.pc () +Returns the frame's resume address. +@end defun + +@defun Frame.block () +Return the frame's code block. @xref{Blocks In Python}. If the frame +does not have a block -- for example, if there is no debugging +information for the code in question -- then this will throw an +exception. +@end defun + +@defun Frame.function () +Return the symbol for the function corresponding to this frame. +@xref{Symbols In Python}. +@end defun + +@defun Frame.older () +Return the frame that called this frame. If this is the oldest frame, +return @code{None}. +@end defun + +@defun Frame.newer () +Return the frame called by this frame. If this is the newest frame, +return @code{None}. +@end defun + +@defun Frame.find_sal () +Return the frame's symtab and line object. +@xref{Symbol Tables In Python}. +@end defun + +@anchor{gdbpy_frame_read_register} +@defun Frame.read_register (register) +Return the value of @var{register} in this frame. Returns a +@code{Gdb.Value} object. Throws an exception if @var{register} does +not exist. The @var{register} argument must be one of the following: +@enumerate +@item +A string that is the name of a valid register (e.g., @code{'sp'} or +@code{'rax'}). +@item +A @code{gdb.RegisterDescriptor} object (@pxref{Registers In Python}). +@item +A @value{GDBN} internal, platform specific number. Using these +numbers is supported for historic reasons, but is not recommended as +future changes to @value{GDBN} could change the mapping between +numbers and the registers they represent, breaking any Python code +that uses the platform-specific numbers. The numbers are usually +found in the corresponding @file{@var{platform}-tdep.h} file in the +@value{GDBN} source tree. +@end enumerate +Using a string to access registers will be slightly slower than the +other two methods as @value{GDBN} must look up the mapping between +name and internal register number. If performance is critical +consider looking up and caching a @code{gdb.RegisterDescriptor} +object. +@end defun + +@defun Frame.read_var (variable @r{[}, block@r{]}) +Return the value of @var{variable} in this frame. If the optional +argument @var{block} is provided, search for the variable from that +block; otherwise start at the frame's current block (which is +determined by the frame's current program counter). The @var{variable} +argument must be a string or a @code{gdb.Symbol} object; @var{block} must be a +@code{gdb.Block} object. +@end defun + +@defun Frame.select () +Set this frame to be the selected frame. @xref{Stack, ,Examining the +Stack}. +@end defun + +@defun Frame.static_link () +In some languages (e.g., Ada, but also a GNU C extension), a nested +function can access the variables in the outer scope. This is done +via a ``static link'', which is a reference from the nested frame to +the appropriate outer frame. + +This method returns this frame's static link frame, if one exists. If +there is no static link, this method returns @code{None}. +@end defun + +@defun Frame.level () +Return an integer, the stack frame level for this frame. @xref{Frames, ,Stack Frames}. +@end defun + +@defun Frame.language () +Return a string, the source language for this frame. +@end defun + +@node Blocks In Python +@subsubsection Accessing blocks from Python + +@cindex blocks in python +@tindex gdb.Block + +In @value{GDBN}, symbols are stored in blocks. A block corresponds +roughly to a scope in the source code. Blocks are organized +hierarchically, and are represented individually in Python as a +@code{gdb.Block}. Blocks rely on debugging information being +available. + +A frame has a block. Please see @ref{Frames In Python}, for a more +in-depth discussion of frames. + +The outermost block is known as the @dfn{global block}. The global +block typically holds public global variables and functions. + +The block nested just inside the global block is the @dfn{static +block}. The static block typically holds file-scoped variables and +functions. + +@value{GDBN} provides a method to get a block's superblock, but there +is currently no way to examine the sub-blocks of a block, or to +iterate over all the blocks in a symbol table (@pxref{Symbol Tables In +Python}). + +Here is a short example that should help explain blocks: + +@smallexample +/* This is in the global block. */ +int global; + +/* This is in the static block. */ +static int file_scope; + +/* 'function' is in the global block, and 'argument' is + in a block nested inside of 'function'. */ +int function (int argument) +@{ + /* 'local' is in a block inside 'function'. It may or may + not be in the same block as 'argument'. */ + int local; + + @{ + /* 'inner' is in a block whose superblock is the one holding + 'local'. */ + int inner; + + /* If this call is expanded by the compiler, you may see + a nested block here whose function is 'inline_function' + and whose superblock is the one holding 'inner'. */ + inline_function (); + @} +@} +@end smallexample + +A @code{gdb.Block} is iterable. The iterator returns the symbols +(@pxref{Symbols In Python}) local to the block. Python programs +should not assume that a specific block object will always contain a +given symbol, since changes in @value{GDBN} features and +infrastructure may cause symbols move across blocks in a symbol +table. You can also use Python's @dfn{dictionary syntax} to access +variables in this block, e.g.: + +@smallexample +symbol = some_block['variable'] # symbol is of type gdb.Symbol +@end smallexample + +The following block-related functions are available in the @code{gdb} +module: + +@defun gdb.block_for_pc (pc) +Return the innermost @code{gdb.Block} containing the given @var{pc} +value. If the block cannot be found for the @var{pc} value specified, +the function will return @code{None}. This is identical to +@code{gdb.current_progspace().block_for_pc(pc)} and is included for +historical compatibility. +@end defun + +A @code{gdb.Block} object has the following methods: + +@defun Block.is_valid () +Returns @code{True} if the @code{gdb.Block} object is valid, +@code{False} if not. A block object can become invalid if the block it +refers to doesn't exist anymore in the inferior. All other +@code{gdb.Block} methods will throw an exception if it is invalid at +the time the method is called. The block's validity is also checked +during iteration over symbols of the block. +@end defun + +A @code{gdb.Block} object has the following attributes: + +@defvar Block.start +The start address of the block. This attribute is not writable. +@end defvar + +@defvar Block.end +One past the last address that appears in the block. This attribute +is not writable. +@end defvar + +@defvar Block.function +The name of the block represented as a @code{gdb.Symbol}. If the +block is not named, then this attribute holds @code{None}. This +attribute is not writable. + +For ordinary function blocks, the superblock is the static block. +However, you should note that it is possible for a function block to +have a superblock that is not the static block -- for instance this +happens for an inlined function. +@end defvar + +@defvar Block.superblock +The block containing this block. If this parent block does not exist, +this attribute holds @code{None}. This attribute is not writable. +@end defvar + +@defvar Block.global_block +The global block associated with this block. This attribute is not +writable. +@end defvar + +@defvar Block.static_block +The static block associated with this block. This attribute is not +writable. +@end defvar + +@defvar Block.is_global +@code{True} if the @code{gdb.Block} object is a global block, +@code{False} if not. This attribute is not +writable. +@end defvar + +@defvar Block.is_static +@code{True} if the @code{gdb.Block} object is a static block, +@code{False} if not. This attribute is not writable. +@end defvar + +@node Symbols In Python +@subsubsection Python representation of Symbols + +@cindex symbols in python +@tindex gdb.Symbol + +@value{GDBN} represents every variable, function and type as an +entry in a symbol table. @xref{Symbols, ,Examining the Symbol Table}. +Similarly, Python represents these symbols in @value{GDBN} with the +@code{gdb.Symbol} object. + +The following symbol-related functions are available in the @code{gdb} +module: + +@defun gdb.lookup_symbol (name @r{[}, block @r{[}, domain@r{]]}) +This function searches for a symbol by name. The search scope can be +restricted to the parameters defined in the optional domain and block +arguments. + +@var{name} is the name of the symbol. It must be a string. The +optional @var{block} argument restricts the search to symbols visible +in that @var{block}. The @var{block} argument must be a +@code{gdb.Block} object. If omitted, the block for the current frame +is used. The optional @var{domain} argument restricts +the search to the domain type. The @var{domain} argument must be a +domain constant defined in the @code{gdb} module and described later +in this chapter. + +The result is a tuple of two elements. +The first element is a @code{gdb.Symbol} object or @code{None} if the symbol +is not found. +If the symbol is found, the second element is @code{True} if the symbol +is a field of a method's object (e.g., @code{this} in C@t{++}), +otherwise it is @code{False}. +If the symbol is not found, the second element is @code{False}. +@end defun + +@defun gdb.lookup_global_symbol (name @r{[}, domain@r{]}) +This function searches for a global symbol by name. +The search scope can be restricted to by the domain argument. + +@var{name} is the name of the symbol. It must be a string. +The optional @var{domain} argument restricts the search to the domain type. +The @var{domain} argument must be a domain constant defined in the @code{gdb} +module and described later in this chapter. + +The result is a @code{gdb.Symbol} object or @code{None} if the symbol +is not found. +@end defun + +@defun gdb.lookup_static_symbol (name @r{[}, domain@r{]}) +This function searches for a global symbol with static linkage by name. +The search scope can be restricted to by the domain argument. + +@var{name} is the name of the symbol. It must be a string. +The optional @var{domain} argument restricts the search to the domain type. +The @var{domain} argument must be a domain constant defined in the @code{gdb} +module and described later in this chapter. + +The result is a @code{gdb.Symbol} object or @code{None} if the symbol +is not found. + +Note that this function will not find function-scoped static variables. To look +up such variables, iterate over the variables of the function's +@code{gdb.Block} and check that @code{block.addr_class} is +@code{gdb.SYMBOL_LOC_STATIC}. + +There can be multiple global symbols with static linkage with the same +name. This function will only return the first matching symbol that +it finds. Which symbol is found depends on where @value{GDBN} is +currently stopped, as @value{GDBN} will first search for matching +symbols in the current object file, and then search all other object +files. If the application is not yet running then @value{GDBN} will +search all object files in the order they appear in the debug +information. +@end defun + +@defun gdb.lookup_static_symbols (name @r{[}, domain@r{]}) +Similar to @code{gdb.lookup_static_symbol}, this function searches for +global symbols with static linkage by name, and optionally restricted +by the domain argument. However, this function returns a list of all +matching symbols found, not just the first one. + +@var{name} is the name of the symbol. It must be a string. +The optional @var{domain} argument restricts the search to the domain type. +The @var{domain} argument must be a domain constant defined in the @code{gdb} +module and described later in this chapter. + +The result is a list of @code{gdb.Symbol} objects which could be empty +if no matching symbols were found. + +Note that this function will not find function-scoped static variables. To look +up such variables, iterate over the variables of the function's +@code{gdb.Block} and check that @code{block.addr_class} is +@code{gdb.SYMBOL_LOC_STATIC}. +@end defun + +A @code{gdb.Symbol} object has the following attributes: + +@defvar Symbol.type +The type of the symbol or @code{None} if no type is recorded. +This attribute is represented as a @code{gdb.Type} object. +@xref{Types In Python}. This attribute is not writable. +@end defvar + +@defvar Symbol.symtab +The symbol table in which the symbol appears. This attribute is +represented as a @code{gdb.Symtab} object. @xref{Symbol Tables In +Python}. This attribute is not writable. +@end defvar + +@defvar Symbol.line +The line number in the source code at which the symbol was defined. +This is an integer. +@end defvar + +@defvar Symbol.name +The name of the symbol as a string. This attribute is not writable. +@end defvar + +@defvar Symbol.linkage_name +The name of the symbol, as used by the linker (i.e., may be mangled). +This attribute is not writable. +@end defvar + +@defvar Symbol.print_name +The name of the symbol in a form suitable for output. This is either +@code{name} or @code{linkage_name}, depending on whether the user +asked @value{GDBN} to display demangled or mangled names. +@end defvar + +@defvar Symbol.addr_class +The address class of the symbol. This classifies how to find the value +of a symbol. Each address class is a constant defined in the +@code{gdb} module and described later in this chapter. +@end defvar + +@defvar Symbol.needs_frame +This is @code{True} if evaluating this symbol's value requires a frame +(@pxref{Frames In Python}) and @code{False} otherwise. Typically, +local variables will require a frame, but other symbols will not. +@end defvar + +@defvar Symbol.is_argument +@code{True} if the symbol is an argument of a function. +@end defvar + +@defvar Symbol.is_artificial +@code{True} if the symbol is artificial. An artificial symbol is one +that is introduced by the compiler. +@end defvar + +@defvar Symbol.is_constant +@code{True} if the symbol is a constant. +@end defvar + +@defvar Symbol.is_function +@code{True} if the symbol is a function or a method. +@end defvar + +@defvar Symbol.is_variable +@code{True} if the symbol is a variable, as opposed to something like +a function or type. Note that this also returns @code{False} for +arguments. +@end defvar + +A @code{gdb.Symbol} object has the following methods: + +@defun Symbol.is_valid () +Returns @code{True} if the @code{gdb.Symbol} object is valid, +@code{False} if not. A @code{gdb.Symbol} object can become invalid if +the symbol it refers to does not exist in @value{GDBN} any longer. +All other @code{gdb.Symbol} methods will throw an exception if it is +invalid at the time the method is called. +@end defun + +@defun Symbol.value (@r{[}frame@r{]}) +Compute the value of the symbol, as a @code{gdb.Value}. For +functions, this computes the address of the function, cast to the +appropriate type. If the symbol requires a frame in order to compute +its value, then @var{frame} must be given. If @var{frame} is not +given, or if @var{frame} is invalid, then this method will throw an +exception. +@end defun + +The available domain categories in @code{gdb.Symbol} are represented +as constants in the @code{gdb} module: + +@vtable @code +@vindex SYMBOL_UNDEF_DOMAIN +@item gdb.SYMBOL_UNDEF_DOMAIN +This is used when a domain has not been discovered or none of the +following domains apply. This usually indicates an error either +in the symbol information or in @value{GDBN}'s handling of symbols. + +@vindex SYMBOL_VAR_DOMAIN +@item gdb.SYMBOL_VAR_DOMAIN +This domain contains variables. + +@vindex SYMBOL_FUNCTION_DOMAIN +@item gdb.SYMBOL_FUNCTION_DOMAIN +This domain contains functions. + +@vindex SYMBOL_TYPE_DOMAIN +@item gdb.SYMBOL_TYPE_DOMAIN +This domain contains types. In a C-like language, types using a tag +(the name appearing after a @code{struct}, @code{union}, or +@code{enum} keyword) will not appear here; in other languages, all +types are in this domain. + +@vindex SYMBOL_STRUCT_DOMAIN +@item gdb.SYMBOL_STRUCT_DOMAIN +This domain holds struct, union and enum tag names. This domain is +only used for C-like languages. For example, in this code: +@smallexample +struct type_one @{ int x; @}; +typedef struct type_one type_two; +@end smallexample +Here @code{type_one} will be in @code{SYMBOL_STRUCT_DOMAIN}, but +@code{type_two} will be in @code{SYMBOL_TYPE_DOMAIN}. + +@vindex SYMBOL_LABEL_DOMAIN +@item gdb.SYMBOL_LABEL_DOMAIN +This domain contains names of labels (for gotos). + +@vindex SYMBOL_MODULE_DOMAIN +@item gdb.SYMBOL_MODULE_DOMAIN +This domain contains names of Fortran module types. + +@vindex SYMBOL_COMMON_BLOCK_DOMAIN +@item gdb.SYMBOL_COMMON_BLOCK_DOMAIN +This domain contains names of Fortran common blocks. +@end vtable + +When searching for a symbol, the desired domain constant can be passed +verbatim to the lookup function. For example: +@smallexample +symbol = gdb.lookup_symbol ("name", domain=gdb.SYMBOL_VAR_DOMAIN) +@end smallexample + +For more complex searches, there is a corresponding set of constants, +each named after one of the preceding constants, but with the +@samp{SEARCH} prefix replacing the @samp{SYMBOL} prefix; for example, +@code{SEARCH_LABEL_DOMAIN}. These may be or'd together to form a +search constant, e.g.: +@smallexample +symbol = gdb.lookup_symbol ("name", + domain=gdb.SEARCH_VAR_DOMAIN | gdb.SEARCH_TYPE_DOMAIN) +@end smallexample + +The available address class categories in @code{gdb.Symbol} are represented +as constants in the @code{gdb} module: + +@vtable @code +@vindex SYMBOL_LOC_UNDEF +@item gdb.SYMBOL_LOC_UNDEF +If this is returned by address class, it indicates an error either in +the symbol information or in @value{GDBN}'s handling of symbols. + +@vindex SYMBOL_LOC_CONST +@item gdb.SYMBOL_LOC_CONST +Value is constant int. + +@vindex SYMBOL_LOC_STATIC +@item gdb.SYMBOL_LOC_STATIC +Value is at a fixed address. + +@vindex SYMBOL_LOC_REGISTER +@item gdb.SYMBOL_LOC_REGISTER +Value is in a register. + +@vindex SYMBOL_LOC_ARG +@item gdb.SYMBOL_LOC_ARG +Value is an argument. This value is at the offset stored within the +symbol inside the frame's argument list. + +@vindex SYMBOL_LOC_REF_ARG +@item gdb.SYMBOL_LOC_REF_ARG +Value address is stored in the frame's argument list. Just like +@code{LOC_ARG} except that the value's address is stored at the +offset, not the value itself. + +@vindex SYMBOL_LOC_REGPARM_ADDR +@item gdb.SYMBOL_LOC_REGPARM_ADDR +Value is a specified register. Just like @code{LOC_REGISTER} except +the register holds the address of the argument instead of the argument +itself. + +@vindex SYMBOL_LOC_LOCAL +@item gdb.SYMBOL_LOC_LOCAL +Value is a local variable. + +@vindex SYMBOL_LOC_TYPEDEF +@item gdb.SYMBOL_LOC_TYPEDEF +Value not used. Symbols in the domain @code{SYMBOL_STRUCT_DOMAIN} all +have this class. + +@vindex SYMBOL_LOC_LABEL +@item gdb.SYMBOL_LOC_LABEL +Value is a label. + +@vindex SYMBOL_LOC_BLOCK +@item gdb.SYMBOL_LOC_BLOCK +Value is a block. + +@vindex SYMBOL_LOC_CONST_BYTES +@item gdb.SYMBOL_LOC_CONST_BYTES +Value is a byte-sequence. + +@vindex SYMBOL_LOC_UNRESOLVED +@item gdb.SYMBOL_LOC_UNRESOLVED +Value is at a fixed address, but the address of the variable has to be +determined from the minimal symbol table whenever the variable is +referenced. + +@vindex SYMBOL_LOC_OPTIMIZED_OUT +@item gdb.SYMBOL_LOC_OPTIMIZED_OUT +The value does not actually exist in the program. + +@vindex SYMBOL_LOC_COMPUTED +@item gdb.SYMBOL_LOC_COMPUTED +The value's address is a computed location. + +@vindex SYMBOL_LOC_COMMON_BLOCK +@item gdb.SYMBOL_LOC_COMMON_BLOCK +The value's address is a symbol. This is only used for Fortran common +blocks. +@end vtable + +@node Symbol Tables In Python +@subsubsection Symbol table representation in Python + +@cindex symbol tables in python +@tindex gdb.Symtab +@tindex gdb.Symtab_and_line + +Access to symbol table data maintained by @value{GDBN} on the inferior +is exposed to Python via two objects: @code{gdb.Symtab_and_line} and +@code{gdb.Symtab}. Symbol table and line data for a frame is returned +from the @code{find_sal} method in @code{gdb.Frame} object. +@xref{Frames In Python}. + +For more information on @value{GDBN}'s symbol table management, see +@ref{Symbols, ,Examining the Symbol Table}, for more information. + +A @code{gdb.Symtab_and_line} object has the following attributes: + +@defvar Symtab_and_line.symtab +The symbol table object (@code{gdb.Symtab}) for this frame. +This attribute is not writable. +@end defvar + +@defvar Symtab_and_line.pc +Indicates the start of the address range occupied by code for the +current source line. This attribute is not writable. +@end defvar + +@defvar Symtab_and_line.last +Indicates the end of the address range occupied by code for the current +source line. This attribute is not writable. +@end defvar + +@defvar Symtab_and_line.line +Indicates the current line number for this object. This +attribute is not writable. +@end defvar + +A @code{gdb.Symtab_and_line} object has the following methods: + +@defun Symtab_and_line.is_valid () +Returns @code{True} if the @code{gdb.Symtab_and_line} object is valid, +@code{False} if not. A @code{gdb.Symtab_and_line} object can become +invalid if the Symbol table and line object it refers to does not +exist in @value{GDBN} any longer. All other +@code{gdb.Symtab_and_line} methods will throw an exception if it is +invalid at the time the method is called. +@end defun + +A @code{gdb.Symtab} object has the following attributes: + +@defvar Symtab.filename +The symbol table's source filename. This attribute is not writable. +@end defvar + +@defvar Symtab.objfile +The symbol table's backing object file. @xref{Objfiles In Python}. +This attribute is not writable. +@end defvar + +@defvar Symtab.producer +The name and possibly version number of the program that +compiled the code in the symbol table. +The contents of this string is up to the compiler. +If no producer information is available then @code{None} is returned. +This attribute is not writable. +@end defvar + +A @code{gdb.Symtab} object has the following methods: + +@defun Symtab.is_valid () +Returns @code{True} if the @code{gdb.Symtab} object is valid, +@code{False} if not. A @code{gdb.Symtab} object can become invalid if +the symbol table it refers to does not exist in @value{GDBN} any +longer. All other @code{gdb.Symtab} methods will throw an exception +if it is invalid at the time the method is called. +@end defun + +@defun Symtab.fullname () +Return the symbol table's source absolute file name. +@end defun + +@defun Symtab.global_block () +Return the global block of the underlying symbol table. +@xref{Blocks In Python}. +@end defun + +@defun Symtab.static_block () +Return the static block of the underlying symbol table. +@xref{Blocks In Python}. +@end defun + +@defun Symtab.linetable () +Return the line table associated with the symbol table. +@xref{Line Tables In Python}. +@end defun + +@node Line Tables In Python +@subsubsection Manipulating line tables using Python + +@cindex line tables in python +@tindex gdb.LineTable + +Python code can request and inspect line table information from a +symbol table that is loaded in @value{GDBN}. A line table is a +mapping of source lines to their executable locations in memory. To +acquire the line table information for a particular symbol table, use +the @code{linetable} function (@pxref{Symbol Tables In Python}). + +A @code{gdb.LineTable} is iterable. The iterator returns +@code{LineTableEntry} objects that correspond to the source line and +address for each line table entry. @code{LineTableEntry} objects have +the following attributes: + +@defvar LineTableEntry.line +The source line number for this line table entry. This number +corresponds to the actual line of source. This attribute is not +writable. +@end defvar + +@defvar LineTableEntry.pc +The address that is associated with the line table entry where the +executable code for that source line resides in memory. This +attribute is not writable. +@end defvar + +As there can be multiple addresses for a single source line, you may +receive multiple @code{LineTableEntry} objects with matching +@code{line} attributes, but with different @code{pc} attributes. The +iterator is sorted in ascending @code{pc} order. Here is a small +example illustrating iterating over a line table. + +@smallexample +symtab = gdb.selected_frame().find_sal().symtab +linetable = symtab.linetable() +for line in linetable: + print ("Line: "+str(line.line)+" Address: "+hex(line.pc)) +@end smallexample + +This will have the following output: + +@smallexample +Line: 33 Address: 0x4005c8L +Line: 37 Address: 0x4005caL +Line: 39 Address: 0x4005d2L +Line: 40 Address: 0x4005f8L +Line: 42 Address: 0x4005ffL +Line: 44 Address: 0x400608L +Line: 42 Address: 0x40060cL +Line: 45 Address: 0x400615L +@end smallexample + +In addition to being able to iterate over a @code{LineTable}, it also +has the following direct access methods: + +@defun LineTable.line (line) +Return a Python @code{Tuple} of @code{LineTableEntry} objects for any +entries in the line table for the given @var{line}, which specifies +the source code line. If there are no entries for that source code +@var{line}, the Python @code{None} is returned. +@end defun + +@defun LineTable.has_line (line) +Return a Python @code{Boolean} indicating whether there is an entry in +the line table for this source line. Return @code{True} if an entry +is found, or @code{False} if not. +@end defun + +@defun LineTable.source_lines () +Return a Python @code{List} of the source line numbers in the symbol +table. Only lines with executable code locations are returned. The +contents of the @code{List} will just be the source line entries +represented as Python @code{Long} values. +@end defun + +@node Breakpoints In Python +@subsubsection Manipulating breakpoints using Python + +@cindex breakpoints in python +@tindex gdb.Breakpoint + +Python code can manipulate breakpoints via the @code{gdb.Breakpoint} +class. + +A breakpoint can be created using one of the two forms of the +@code{gdb.Breakpoint} constructor. The first one accepts a string +like one would pass to the @code{break} +(@pxref{Set Breaks,,Setting Breakpoints}) and @code{watch} +(@pxref{Set Watchpoints, , Setting Watchpoints}) commands, and can be used to +create both breakpoints and watchpoints. The second accepts separate Python +arguments similar to @ref{Explicit Locations}, and can only be used to create +breakpoints. + +@defun Breakpoint.__init__ (spec @r{[}, type @r{][}, wp_class @r{][}, internal @r{][}, temporary @r{][}, qualified @r{]}) +Create a new breakpoint according to @var{spec}, which is a string naming the +location of a breakpoint, or an expression that defines a watchpoint. The +string should describe a location in a format recognized by the @code{break} +command (@pxref{Set Breaks,,Setting Breakpoints}) or, in the case of a +watchpoint, by the @code{watch} command +(@pxref{Set Watchpoints, , Setting Watchpoints}). + +The optional @var{type} argument specifies the type of the breakpoint to create, +as defined below. + +The optional @var{wp_class} argument defines the class of watchpoint to create, +if @var{type} is @code{gdb.BP_WATCHPOINT}. If @var{wp_class} is omitted, it +defaults to @code{gdb.WP_WRITE}. + +The optional @var{internal} argument allows the breakpoint to become invisible +to the user. The breakpoint will neither be reported when created, nor will it +be listed in the output from @code{info breakpoints} (but will be listed with +the @code{maint info breakpoints} command). + +The optional @var{temporary} argument makes the breakpoint a temporary +breakpoint. Temporary breakpoints are deleted after they have been hit. Any +further access to the Python breakpoint after it has been hit will result in a +runtime error (as that breakpoint has now been automatically deleted). + +The optional @var{qualified} argument is a boolean that allows interpreting +the function passed in @code{spec} as a fully-qualified name. It is equivalent +to @code{break}'s @code{-qualified} flag (@pxref{Linespec Locations} and +@ref{Explicit Locations}). + +@end defun + +@defun Breakpoint.__init__ (@r{[} source @r{][}, function @r{][}, label @r{][}, line @r{]}, @r{][} internal @r{][}, temporary @r{][}, qualified @r{]}) +This second form of creating a new breakpoint specifies the explicit +location (@pxref{Explicit Locations}) using keywords. The new breakpoint will +be created in the specified source file @var{source}, at the specified +@var{function}, @var{label} and @var{line}. + +@var{internal}, @var{temporary} and @var{qualified} have the same usage as +explained previously. +@end defun + +The available types are represented by constants defined in the @code{gdb} +module: + +@vtable @code +@vindex BP_BREAKPOINT +@item gdb.BP_BREAKPOINT +Normal code breakpoint. + +@vindex BP_HARDWARE_BREAKPOINT +@item gdb.BP_HARDWARE_BREAKPOINT +Hardware assisted code breakpoint. + +@vindex BP_WATCHPOINT +@item gdb.BP_WATCHPOINT +Watchpoint breakpoint. + +@vindex BP_HARDWARE_WATCHPOINT +@item gdb.BP_HARDWARE_WATCHPOINT +Hardware assisted watchpoint. + +@vindex BP_READ_WATCHPOINT +@item gdb.BP_READ_WATCHPOINT +Hardware assisted read watchpoint. + +@vindex BP_ACCESS_WATCHPOINT +@item gdb.BP_ACCESS_WATCHPOINT +Hardware assisted access watchpoint. + +@vindex BP_CATCHPOINT +@item gdb.BP_CATCHPOINT +Catchpoint. Currently, this type can't be used when creating +@code{gdb.Breakpoint} objects, but will be present in +@code{gdb.Breakpoint} objects reported from +@code{gdb.BreakpointEvent}s (@pxref{Events In Python}). +@end vtable + +The available watchpoint types are represented by constants defined in the +@code{gdb} module: + +@vtable @code +@vindex WP_READ +@item gdb.WP_READ +Read only watchpoint. + +@vindex WP_WRITE +@item gdb.WP_WRITE +Write only watchpoint. + +@vindex WP_ACCESS +@item gdb.WP_ACCESS +Read/Write watchpoint. +@end vtable + +@defun Breakpoint.stop (self) +The @code{gdb.Breakpoint} class can be sub-classed and, in +particular, you may choose to implement the @code{stop} method. +If this method is defined in a sub-class of @code{gdb.Breakpoint}, +it will be called when the inferior reaches any location of a +breakpoint which instantiates that sub-class. If the method returns +@code{True}, the inferior will be stopped at the location of the +breakpoint, otherwise the inferior will continue. + +If there are multiple breakpoints at the same location with a +@code{stop} method, each one will be called regardless of the +return status of the previous. This ensures that all @code{stop} +methods have a chance to execute at that location. In this scenario +if one of the methods returns @code{True} but the others return +@code{False}, the inferior will still be stopped. + +You should not alter the execution state of the inferior (i.e.@:, step, +next, etc.), alter the current frame context (i.e.@:, change the current +active frame), or alter, add or delete any breakpoint. As a general +rule, you should not alter any data within @value{GDBN} or the inferior +at this time. + +Example @code{stop} implementation: + +@smallexample +class MyBreakpoint (gdb.Breakpoint): + def stop (self): + inf_val = gdb.parse_and_eval("foo") + if inf_val == 3: + return True + return False +@end smallexample +@end defun + +@defun Breakpoint.is_valid () +Return @code{True} if this @code{Breakpoint} object is valid, +@code{False} otherwise. A @code{Breakpoint} object can become invalid +if the user deletes the breakpoint. In this case, the object still +exists, but the underlying breakpoint does not. In the cases of +watchpoint scope, the watchpoint remains valid even if execution of the +inferior leaves the scope of that watchpoint. +@end defun + +@defun Breakpoint.delete () +Permanently deletes the @value{GDBN} breakpoint. This also +invalidates the Python @code{Breakpoint} object. Any further access +to this object's attributes or methods will raise an error. +@end defun + +@defvar Breakpoint.enabled +This attribute is @code{True} if the breakpoint is enabled, and +@code{False} otherwise. This attribute is writable. You can use it to enable +or disable the breakpoint. +@end defvar + +@defvar Breakpoint.silent +This attribute is @code{True} if the breakpoint is silent, and +@code{False} otherwise. This attribute is writable. + +Note that a breakpoint can also be silent if it has commands and the +first command is @code{silent}. This is not reported by the +@code{silent} attribute. +@end defvar + +@defvar Breakpoint.pending +This attribute is @code{True} if the breakpoint is pending, and +@code{False} otherwise. @xref{Set Breaks}. This attribute is +read-only. +@end defvar + +@anchor{python_breakpoint_thread} +@defvar Breakpoint.thread +If the breakpoint is thread-specific (@pxref{Thread-Specific +Breakpoints}), this attribute holds the thread's global id. If the +breakpoint is not thread-specific, this attribute is @code{None}. +This attribute is writable. + +Only one of @code{Breakpoint.thread} or @code{Breakpoint.inferior} can +be set to a valid id at any time, that is, a breakpoint can be thread +specific, or inferior specific, but not both. +@end defvar + +@anchor{python_breakpoint_inferior} +@defvar Breakpoint.inferior +If the breakpoint is inferior-specific (@pxref{Inferior-Specific +Breakpoints}), this attribute holds the inferior's id. If the +breakpoint is not inferior-specific, this attribute is @code{None}. + +This attribute can be written for breakpoints of type +@code{gdb.BP_BREAKPOINT} and @code{gdb.BP_HARDWARE_BREAKPOINT}. +@end defvar + +@defvar Breakpoint.task +If the breakpoint is Ada task-specific, this attribute holds the Ada task +id. If the breakpoint is not task-specific (or the underlying +language is not Ada), this attribute is @code{None}. This attribute +is writable. +@end defvar + +@defvar Breakpoint.ignore_count +This attribute holds the ignore count for the breakpoint, an integer. +This attribute is writable. +@end defvar + +@defvar Breakpoint.number +This attribute holds the breakpoint's number --- the identifier used by +the user to manipulate the breakpoint. This attribute is not writable. +@end defvar + +@defvar Breakpoint.type +This attribute holds the breakpoint's type --- the identifier used to +determine the actual breakpoint type or use-case. This attribute is not +writable. +@end defvar + +@defvar Breakpoint.visible +This attribute tells whether the breakpoint is visible to the user +when set, or when the @samp{info breakpoints} command is run. This +attribute is not writable. +@end defvar + +@defvar Breakpoint.temporary +This attribute indicates whether the breakpoint was created as a +temporary breakpoint. Temporary breakpoints are automatically deleted +after that breakpoint has been hit. Access to this attribute, and all +other attributes and functions other than the @code{is_valid} +function, will result in an error after the breakpoint has been hit +(as it has been automatically deleted). This attribute is not +writable. +@end defvar + +@defvar Breakpoint.hit_count +This attribute holds the hit count for the breakpoint, an integer. +This attribute is writable, but currently it can only be set to zero. +@end defvar + +@defvar Breakpoint.location +This attribute holds the location of the breakpoint, as specified by +the user. It is a string. If the breakpoint does not have a location +(that is, it is a watchpoint) the attribute's value is @code{None}. This +attribute is not writable. +@end defvar + +@defvar Breakpoint.locations +Get the most current list of breakpoint locations that are inserted for this +breakpoint, with elements of type @code{gdb.BreakpointLocation} +(described below). This functionality matches that of the +@code{info breakpoint} command (@pxref{Set Breaks}), in that it only retrieves +the most current list of locations, thus the list itself when returned is +not updated behind the scenes. This attribute is not writable. +@end defvar + +@defvar Breakpoint.expression +This attribute holds a breakpoint expression, as specified by +the user. It is a string. If the breakpoint does not have an +expression (the breakpoint is not a watchpoint) the attribute's value +is @code{None}. This attribute is not writable. +@end defvar + +@defvar Breakpoint.condition +This attribute holds the condition of the breakpoint, as specified by +the user. It is a string. If there is no condition, this attribute's +value is @code{None}. This attribute is writable. +@end defvar + +@defvar Breakpoint.commands +This attribute holds the commands attached to the breakpoint. If +there are commands, this attribute's value is a string holding all the +commands, separated by newlines. If there are no commands, this +attribute is @code{None}. This attribute is writable. +@end defvar + +@subheading Breakpoint Locations + +A breakpoint location is one of the actual places where a breakpoint has been +set, represented in the Python API by the @code{gdb.BreakpointLocation} +type. This type is never instantiated by the user directly, but is retrieved +from @code{Breakpoint.locations} which returns a list of breakpoint +locations where it is currently set. Breakpoint locations can become +invalid if new symbol files are loaded or dynamically loaded libraries are +closed. Accessing the attributes of an invalidated breakpoint location will +throw a @code{RuntimeError} exception. Access the @code{Breakpoint.locations} +attribute again to retrieve the new and valid breakpoints location list. + +@defvar BreakpointLocation.source +This attribute returns the source file path and line number where this location +was set. The type of the attribute is a tuple of @var{string} and +@var{long}. If the breakpoint location doesn't have a source location, +it returns None, which is the case for watchpoints and catchpoints. +This will throw a @code{RuntimeError} exception if the location +has been invalidated. This attribute is not writable. +@end defvar + +@defvar BreakpointLocation.address +This attribute returns the address where this location was set. +This attribute is of type long. This will throw a @code{RuntimeError} +exception if the location has been invalidated. This attribute is +not writable. +@end defvar + +@defvar BreakpointLocation.enabled +This attribute holds the value for whether or not this location is enabled. +This attribute is writable (boolean). This will throw a @code{RuntimeError} +exception if the location has been invalidated. +@end defvar + +@defvar BreakpointLocation.owner +This attribute holds a reference to the @code{gdb.Breakpoint} owner object, +from which this @code{gdb.BreakpointLocation} was retrieved from. +This will throw a @code{RuntimeError} exception if the location has been +invalidated. This attribute is not writable. +@end defvar + +@defvar BreakpointLocation.function +This attribute gets the name of the function where this location was set. +If no function could be found this attribute returns @code{None}. +This will throw a @code{RuntimeError} exception if the location has +been invalidated. This attribute is not writable. +@end defvar + +@defvar BreakpointLocation.fullname +This attribute gets the full name of where this location was set. If no +full name could be found, this attribute returns @code{None}. +This will throw a @code{RuntimeError} exception if the location has +been invalidated. This attribute is not writable. +@end defvar + +@defvar BreakpointLocation.thread_groups +This attribute gets the thread groups it was set in. It returns a @code{List} +of the thread group ID's. This will throw a @code{RuntimeError} +exception if the location has been invalidated. This attribute +is not writable. +@end defvar + +@node Finish Breakpoints in Python +@subsubsection Finish Breakpoints + +@cindex python finish breakpoints +@tindex gdb.FinishBreakpoint + +A finish breakpoint is a temporary breakpoint set at the return address of +a frame, based on the @code{finish} command. @code{gdb.FinishBreakpoint} +extends @code{gdb.Breakpoint}. The underlying breakpoint will be disabled +and deleted when the execution will run out of the breakpoint scope (i.e.@: +@code{Breakpoint.stop} or @code{FinishBreakpoint.out_of_scope} triggered). +Finish breakpoints are thread specific and must be create with the right +thread selected. + +@defun FinishBreakpoint.__init__ (@r{[}frame@r{]} @r{[}, internal@r{]}) +Create a finish breakpoint at the return address of the @code{gdb.Frame} +object @var{frame}. If @var{frame} is not provided, this defaults to the +newest frame. The optional @var{internal} argument allows the breakpoint to +become invisible to the user. @xref{Breakpoints In Python}, for further +details about this argument. +@end defun + +@defun FinishBreakpoint.out_of_scope (self) +In some circumstances (e.g.@: @code{longjmp}, C@t{++} exceptions, @value{GDBN} +@code{return} command, @dots{}), a function may not properly terminate, and +thus never hit the finish breakpoint. When @value{GDBN} notices such a +situation, the @code{out_of_scope} callback will be triggered. + +You may want to sub-class @code{gdb.FinishBreakpoint} and override this +method: + +@smallexample +class MyFinishBreakpoint (gdb.FinishBreakpoint) + def stop (self): + print ("normal finish") + return True + + def out_of_scope (): + print ("abnormal finish") +@end smallexample +@end defun + +@defvar FinishBreakpoint.return_value +When @value{GDBN} is stopped at a finish breakpoint and the frame +used to build the @code{gdb.FinishBreakpoint} object had debug symbols, this +attribute will contain a @code{gdb.Value} object corresponding to the return +value of the function. The value will be @code{None} if the function return +type is @code{void} or if the return value was not computable. This attribute +is not writable. +@end defvar + +@node Lazy Strings In Python +@subsubsection Python representation of lazy strings + +@cindex lazy strings in python +@tindex gdb.LazyString + +A @dfn{lazy string} is a string whose contents is not retrieved or +encoded until it is needed. + +A @code{gdb.LazyString} is represented in @value{GDBN} as an +@code{address} that points to a region of memory, an @code{encoding} +that will be used to encode that region of memory, and a @code{length} +to delimit the region of memory that represents the string. The +difference between a @code{gdb.LazyString} and a string wrapped within +a @code{gdb.Value} is that a @code{gdb.LazyString} will only be +retrieved and encoded during printing, while a @code{gdb.Value} +wrapping a string is immediately retrieved and encoded on creation. + +A @code{gdb.LazyString} can be created using the +@code{gdb.Value.lazy_string} method (@pxref{Values From Inferior}). + +A @code{gdb.LazyString} object has the following functions: + +@defun LazyString.value () +Convert the @code{gdb.LazyString} to a @code{gdb.Value}. This value +will point to the string in memory, but will lose all the delayed +retrieval, encoding and handling that @value{GDBN} applies to a +@code{gdb.LazyString}. +@end defun + +@defvar LazyString.address +This attribute holds the address of the string. This attribute is not +writable. +@end defvar + +@defvar LazyString.length +This attribute holds the length of the string in characters. If the +length is -1, then the string will be fetched and encoded up to the +first null of appropriate width. This attribute is not writable. +@end defvar + +@defvar LazyString.encoding +This attribute holds the encoding that will be applied to the string +when the string is printed by @value{GDBN}. If the encoding is not +set, or contains an empty string, then @value{GDBN} will select the +most appropriate encoding when the string is printed. This attribute +is not writable. +@end defvar + +@defvar LazyString.type +This attribute holds the type that is represented by the lazy string's +type. For a lazy string this is a pointer or array type. To +resolve this to the lazy string's character type, use the type's +@code{target} method. @xref{Types In Python}. This attribute is not +writable. +@end defvar + +@node Architectures In Python +@subsubsection Python representation of architectures +@cindex Python architectures + +@value{GDBN} uses architecture specific parameters and artifacts in a +number of its various computations. An architecture is represented +by an instance of the @code{gdb.Architecture} class. + +A @code{gdb.Architecture} class has the following methods: + +@anchor{gdbpy_architecture_name} +@defun Architecture.name () +Return the name (string value) of the architecture. +@end defun + +@defun Architecture.disassemble (start_pc @r{[}, end_pc @r{[}, count@r{]]}) +Return a list of disassembled instructions starting from the memory +address @var{start_pc}. The optional arguments @var{end_pc} and +@var{count} determine the number of instructions in the returned list. +If both the optional arguments @var{end_pc} and @var{count} are +specified, then a list of at most @var{count} disassembled instructions +whose start address falls in the closed memory address interval from +@var{start_pc} to @var{end_pc} are returned. If @var{end_pc} is not +specified, but @var{count} is specified, then @var{count} number of +instructions starting from the address @var{start_pc} are returned. If +@var{count} is not specified but @var{end_pc} is specified, then all +instructions whose start address falls in the closed memory address +interval from @var{start_pc} to @var{end_pc} are returned. If neither +@var{end_pc} nor @var{count} are specified, then a single instruction at +@var{start_pc} is returned. For all of these cases, each element of the +returned list is a Python @code{dict} with the following string keys: + +@table @code + +@item addr +The value corresponding to this key is a Python long integer capturing +the memory address of the instruction. + +@item asm +The value corresponding to this key is a string value which represents +the instruction with assembly language mnemonics. The assembly +language flavor used is the same as that specified by the current CLI +variable @code{disassembly-flavor}. @xref{Machine Code}. + +@item length +The value corresponding to this key is the length (integer value) of the +instruction in bytes. + +@end table +@end defun + +@defun Architecture.integer_type (size @r{[}, signed@r{]}) +This function looks up an integer type by its @var{size}, and +optionally whether or not it is signed. + +@var{size} is the size, in bits, of the desired integer type. Only +certain sizes are currently supported: 0, 8, 16, 24, 32, 64, and 128. + +If @var{signed} is not specified, it defaults to @code{True}. If +@var{signed} is @code{False}, the returned type will be unsigned. + +If the indicated type cannot be found, this function will throw a +@code{ValueError} exception. +@end defun + +@anchor{gdbpy_architecture_registers} +@defun Architecture.registers (@r{[} reggroup @r{]}) +Return a @code{gdb.RegisterDescriptorIterator} (@pxref{Registers In +Python}) for all of the registers in @var{reggroup}, a string that is +the name of a register group. If @var{reggroup} is omitted, or is the +empty string, then the register group @samp{all} is assumed. +@end defun + +@anchor{gdbpy_architecture_reggroups} +@defun Architecture.register_groups () +Return a @code{gdb.RegisterGroupsIterator} (@pxref{Registers In +Python}) for all of the register groups available for the +@code{gdb.Architecture}. +@end defun + +@node Registers In Python +@subsubsection Registers In Python +@cindex Registers In Python + +Python code can request from a @code{gdb.Architecture} information +about the set of registers available +(@pxref{gdbpy_architecture_registers,,@code{Architecture.registers}}). +The register information is returned as a +@code{gdb.RegisterDescriptorIterator}, which is an iterator that in +turn returns @code{gdb.RegisterDescriptor} objects. + +A @code{gdb.RegisterDescriptor} does not provide the value of a +register (@pxref{gdbpy_frame_read_register,,@code{Frame.read_register}} +for reading a register's value), instead the @code{RegisterDescriptor} +is a way to discover which registers are available for a particular +architecture. + +A @code{gdb.RegisterDescriptor} has the following read-only properties: + +@defvar RegisterDescriptor.name +The name of this register. +@end defvar + +It is also possible to lookup a register descriptor based on its name +using the following @code{gdb.RegisterDescriptorIterator} function: + +@defun RegisterDescriptorIterator.find (name) +Takes @var{name} as an argument, which must be a string, and returns a +@code{gdb.RegisterDescriptor} for the register with that name, or +@code{None} if there is no register with that name. +@end defun + +Python code can also request from a @code{gdb.Architecture} +information about the set of register groups available on a given +architecture +(@pxref{gdbpy_architecture_reggroups,,@code{Architecture.register_groups}}). + +Every register can be a member of zero or more register groups. Some +register groups are used internally within @value{GDBN} to control +things like which registers must be saved when calling into the +program being debugged (@pxref{Calling,,Calling Program Functions}). +Other register groups exist to allow users to easily see related sets +of registers in commands like @code{info registers} +(@pxref{info_registers_reggroup,,@code{info registers +@var{reggroup}}}). + +The register groups information is returned as a +@code{gdb.RegisterGroupsIterator}, which is an iterator that in turn +returns @code{gdb.RegisterGroup} objects. + +A @code{gdb.RegisterGroup} object has the following read-only +properties: + +@defvar RegisterGroup.name +A string that is the name of this register group. +@end defvar + +@node Connections In Python +@subsubsection Connections In Python +@cindex connections in python +@value{GDBN} lets you run and debug multiple programs in a single +session. Each program being debugged has a connection, the connection +describes how @value{GDBN} controls the program being debugged. +Examples of different connection types are @samp{native} and +@samp{remote}. @xref{Inferiors Connections and Programs}. + +Connections in @value{GDBN} are represented as instances of +@code{gdb.TargetConnection}, or as one of its sub-classes. To get a +list of all connections use @code{gdb.connections} +(@pxref{gdbpy_connections,,gdb.connections}). + +To get the connection for a single @code{gdb.Inferior} read its +@code{gdb.Inferior.connection} attribute +(@pxref{gdbpy_inferior_connection,,gdb.Inferior.connection}). + +Currently there is only a single sub-class of +@code{gdb.TargetConnection}, @code{gdb.RemoteTargetConnection}, +however, additional sub-classes may be added in future releases of +@value{GDBN}. As a result you should avoid writing code like: + +@smallexample +conn = gdb.selected_inferior().connection +if type(conn) is gdb.RemoteTargetConnection: + print("This is a remote target connection") +@end smallexample + +@noindent +as this may fail when more connection types are added. Instead, you +should write: + +@smallexample +conn = gdb.selected_inferior().connection +if isinstance(conn, gdb.RemoteTargetConnection): + print("This is a remote target connection") +@end smallexample + +A @code{gdb.TargetConnection} has the following method: + +@defun TargetConnection.is_valid () +Return @code{True} if the @code{gdb.TargetConnection} object is valid, +@code{False} if not. A @code{gdb.TargetConnection} will become +invalid if the connection no longer exists within @value{GDBN}, this +might happen when no inferiors are using the connection, but could be +delayed until the user replaces the current target. + +Reading any of the @code{gdb.TargetConnection} properties will throw +an exception if the connection is invalid. +@end defun + +A @code{gdb.TargetConnection} has the following read-only properties: + +@defvar TargetConnection.num +An integer assigned by @value{GDBN} to uniquely identify this +connection. This is the same value as displayed in the @samp{Num} +column of the @code{info connections} command output (@pxref{Inferiors +Connections and Programs,,info connections}). +@end defvar + +@defvar TargetConnection.type +A string that describes what type of connection this is. This string +will be one of the valid names that can be passed to the @code{target} +command (@pxref{Target Commands,,target command}). +@end defvar + +@defvar TargetConnection.description +A string that gives a short description of this target type. This is +the same string that is displayed in the @samp{Description} column of +the @code{info connection} command output (@pxref{Inferiors +Connections and Programs,,info connections}). +@end defvar + +@defvar TargetConnection.details +An optional string that gives additional information about this +connection. This attribute can be @code{None} if there are no +additional details for this connection. + +An example of a connection type that might have additional details is +the @samp{remote} connection, in this case the details string can +contain the @samp{@var{hostname}:@var{port}} that was used to connect +to the remote target. +@end defvar + +The @code{gdb.RemoteTargetConnection} class is a sub-class of +@code{gdb.TargetConnection}, and is used to represent @samp{remote} +and @samp{extended-remote} connections. In addition to the attributes +and methods available from the @code{gdb.TargetConnection} base class, +a @code{gdb.RemoteTargetConnection} has the following method: + +@kindex maint packet +@defun RemoteTargetConnection.send_packet (packet) +This method sends @var{packet} to the remote target and returns the +response. The @var{packet} should either be a @code{bytes} object, or +a @code{Unicode} string. + +If @var{packet} is a @code{Unicode} string, then the string is encoded +to a @code{bytes} object using the @sc{ascii} codec. If the string +can't be encoded then an @code{UnicodeError} is raised. + +If @var{packet} is not a @code{bytes} object, or a @code{Unicode} +string, then a @code{TypeError} is raised. If @var{packet} is empty +then a @code{ValueError} is raised. + +The response is returned as a @code{bytes} object. If it is known +that the response can be represented as a string then this can be +decoded from the buffer. For example, if it is known that the +response is an @sc{ascii} string: + +@smallexample +remote_connection.send_packet("some_packet").decode("ascii") +@end smallexample + +The prefix, suffix, and checksum (as required by the remote serial +protocol) are automatically added to the outgoing packet, and removed +from the incoming packet before the contents of the reply are +returned. + +This is equivalent to the @code{maintenance packet} command +(@pxref{maint packet}). +@end defun + +@node TUI Windows In Python +@subsubsection Implementing new TUI windows +@cindex Python TUI Windows + +New TUI (@pxref{TUI}) windows can be implemented in Python. + +@defun gdb.register_window_type (name, factory) +Because TUI windows are created and destroyed depending on the layout +the user chooses, new window types are implemented by registering a +factory function with @value{GDBN}. + +@var{name} is the name of the new window. It's an error to try to +replace one of the built-in windows, but other window types can be +replaced. The @var{name} should match the regular expression +@code{[a-zA-Z][-_.a-zA-Z0-9]*}, it is an error to try and create a +window with an invalid name. + +@var{function} is a factory function that is called to create the TUI +window. This is called with a single argument of type +@code{gdb.TuiWindow}, described below. It should return an object +that implements the TUI window protocol, also described below. +@end defun + +As mentioned above, when a factory function is called, it is passed +an object of type @code{gdb.TuiWindow}. This object has these +methods and attributes: + +@defun TuiWindow.is_valid () +This method returns @code{True} when this window is valid. When the +user changes the TUI layout, windows no longer visible in the new +layout will be destroyed. At this point, the @code{gdb.TuiWindow} +will no longer be valid, and methods (and attributes) other than +@code{is_valid} will throw an exception. + +When the TUI is disabled using @code{tui disable} (@pxref{TUI +Commands,,tui disable}) the window is hidden rather than destroyed, +but @code{is_valid} will still return @code{False} and other methods +(and attributes) will still throw an exception. +@end defun + +@defvar TuiWindow.width +This attribute holds the width of the window. It is not writable. +@end defvar + +@defvar TuiWindow.height +This attribute holds the height of the window. It is not writable. +@end defvar + +@defvar TuiWindow.title +This attribute holds the window's title, a string. This is normally +displayed above the window. This attribute can be modified. +@end defvar + +@defun TuiWindow.erase () +Remove all the contents of the window. +@end defun + +@defun TuiWindow.write (string @r{[}, full_window@r{]}) +Write @var{string} to the window. @var{string} can contain ANSI +terminal escape styling sequences; @value{GDBN} will translate these +as appropriate for the terminal. + +If the @var{full_window} parameter is @code{True}, then @var{string} +contains the full contents of the window. This is similar to calling +@code{erase} before @code{write}, but avoids the flickering. +@end defun + +The factory function that you supply should return an object +conforming to the TUI window protocol. These are the methods that can +be called on this object, which is referred to below as the ``window +object''. The methods documented below are optional; if the object +does not implement one of these methods, @value{GDBN} will not attempt +to call it. Additional new methods may be added to the window +protocol in the future. @value{GDBN} guarantees that they will begin +with a lower-case letter, so you can start implementation methods with +upper-case letters or underscore to avoid any future conflicts. + +@defun Window.close () +When the TUI window is closed, the @code{gdb.TuiWindow} object will be +put into an invalid state. At this time, @value{GDBN} will call +@code{close} method on the window object. + +After this method is called, @value{GDBN} will discard any references +it holds on this window object, and will no longer call methods on +this object. +@end defun + +@defun Window.render () +In some situations, a TUI window can change size. For example, this +can happen if the user resizes the terminal, or changes the layout. +When this happens, @value{GDBN} will call the @code{render} method on +the window object. + +If your window is intended to update in response to changes in the +inferior, you will probably also want to register event listeners and +send output to the @code{gdb.TuiWindow}. +@end defun + +@defun Window.hscroll (num) +This is a request to scroll the window horizontally. @var{num} is the +amount by which to scroll, with negative numbers meaning to scroll +right. In the TUI model, it is the viewport that moves, not the +contents. A positive argument should cause the viewport to move +right, and so the content should appear to move to the left. +@end defun + +@defun Window.vscroll (num) +This is a request to scroll the window vertically. @var{num} is the +amount by which to scroll, with negative numbers meaning to scroll +backward. In the TUI model, it is the viewport that moves, not the +contents. A positive argument should cause the viewport to move down, +and so the content should appear to move up. +@end defun + +@anchor{python-window-click} +@defun Window.click (x, y, button) +This is called on a mouse click in this window. @var{x} and @var{y} are +the mouse coordinates inside the window (0-based, from the top left +corner), and @var{button} specifies which mouse button was used, whose +values can be 1 (left), 2 (middle), or 3 (right). + +When TUI mouse events are disabled by turning off the @code{tui mouse-events} +setting (@pxref{tui-mouse-events,,set tui mouse-events}), then @code{click} will +not be called. +@end defun + +@node Disassembly In Python +@subsubsection Instruction Disassembly In Python +@cindex python instruction disassembly + +@value{GDBN}'s builtin disassembler can be extended, or even replaced, +using the Python API. The disassembler related features are contained +within the @code{gdb.disassembler} module: + +@anchor{DisassembleInfo Class} +@deftp {class} gdb.disassembler.DisassembleInfo +Disassembly is driven by instances of this class. Each time +@value{GDBN} needs to disassemble an instruction, an instance of this +class is created and passed to a registered disassembler. The +disassembler is then responsible for disassembling an instruction and +returning a result. + +Instances of this type are usually created within @value{GDBN}, +however, it is possible to create a copy of an instance of this type, +see the description of @code{__init__} for more details. + +This class has the following properties and methods: + +@defvar DisassembleInfo.address +A read-only integer containing the address at which @value{GDBN} +wishes to disassemble a single instruction. +@end defvar + +@defvar DisassembleInfo.architecture +The @code{gdb.Architecture} (@pxref{Architectures In Python}) for +which @value{GDBN} is currently disassembling, this property is +read-only. +@end defvar + +@defvar DisassembleInfo.progspace +The @code{gdb.Progspace} (@pxref{Progspaces In Python,,Program Spaces +In Python}) for which @value{GDBN} is currently disassembling, this +property is read-only. +@end defvar + +@defun DisassembleInfo.is_valid () +Returns @code{True} if the @code{DisassembleInfo} object is valid, +@code{False} if not. A @code{DisassembleInfo} object will become +invalid once the disassembly call for which the @code{DisassembleInfo} +was created, has returned. Calling other @code{DisassembleInfo} +methods, or accessing @code{DisassembleInfo} properties, will raise a +@code{RuntimeError} exception if it is invalid. +@end defun + +@defun DisassembleInfo.__init__ (info) +This can be used to create a new @code{DisassembleInfo} object that is +a copy of @var{info}. The copy will have the same @code{address}, +@code{architecture}, and @code{progspace} values as @var{info}, and +will become invalid at the same time as @var{info}. + +This method exists so that sub-classes of @code{DisassembleInfo} can +be created, these sub-classes must be initialized as copies of an +existing @code{DisassembleInfo} object, but sub-classes might choose +to override the @code{read_memory} method, and so control what +@value{GDBN} sees when reading from memory +(@pxref{builtin_disassemble}). +@end defun + +@defun DisassembleInfo.read_memory (length, offset) +This method allows the disassembler to read the bytes of the +instruction to be disassembled. The method reads @var{length} bytes, +starting at @var{offset} from +@code{DisassembleInfo.address}. + +It is important that the disassembler read the instruction bytes using +this method, rather than reading inferior memory directly, as in some +cases @value{GDBN} disassembles from an internal buffer rather than +directly from inferior memory, calling this method handles this +detail. + +Returns a buffer object, which behaves much like an array or a string, +just as @code{Inferior.read_memory} does +(@pxref{gdbpy_inferior_read_memory,,Inferior.read_memory}). The +length of the returned buffer will always be exactly @var{length}. + +If @value{GDBN} is unable to read the required memory then a +@code{gdb.MemoryError} exception is raised (@pxref{Exception +Handling}). + +This method can be overridden by a sub-class in order to control what +@value{GDBN} sees when reading from memory +(@pxref{builtin_disassemble}). When overriding this method it is +important to understand how @code{builtin_disassemble} makes use of +this method. + +While disassembling a single instruction there could be multiple calls +to this method, and the same bytes might be read multiple times. Any +single call might only read a subset of the total instruction bytes. + +If an implementation of @code{read_memory} is unable to read the +requested memory contents, for example, if there's a request to read +from an invalid memory address, then a @code{gdb.MemoryError} should +be raised. + +Raising a @code{MemoryError} inside @code{read_memory} does not +automatically mean a @code{MemoryError} will be raised by +@code{builtin_disassemble}. It is possible the @value{GDBN}'s builtin +disassembler is probing to see how many bytes are available. When +@code{read_memory} raises the @code{MemoryError} the builtin +disassembler might be able to perform a complete disassembly with the +bytes it has available, in this case @code{builtin_disassemble} will +not itself raise a @code{MemoryError}. + +Any other exception type raised in @code{read_memory} will propagate +back and be re-raised by @code{builtin_disassemble}. +@end defun + +@defun DisassembleInfo.text_part (style, string) +Create a new @code{DisassemblerTextPart} representing a piece of a +disassembled instruction. @var{string} should be a non-empty string, +and @var{style} should be an appropriate style constant +(@pxref{Disassembler Style Constants}). + +Disassembler parts are used when creating a @code{DisassemblerResult} +in order to represent the styling within an instruction +(@pxref{DisassemblerResult Class}). +@end defun + +@defun DisassembleInfo.address_part (address) +Create a new @code{DisassemblerAddressPart}. @var{address} is the +value of the absolute address this part represents. A +@code{DisassemblerAddressPart} is displayed as an absolute address and +an associated symbol, the address and symbol are styled appropriately. +@end defun + +@end deftp + +@anchor{Disassembler Class} +@deftp {class} gdb.disassembler.Disassembler +This is a base class from which all user implemented disassemblers +must inherit. + +@defun Disassembler.__init__ (name) +The constructor takes @var{name}, a string, which should be a short +name for this disassembler. +@end defun + +@defun Disassembler.__call__ (info) +The @code{__call__} method must be overridden by sub-classes to +perform disassembly. Calling @code{__call__} on this base class will +raise a @code{NotImplementedError} exception. + +The @var{info} argument is an instance of @code{DisassembleInfo}, and +describes the instruction that @value{GDBN} wants disassembling. + +If this function returns @code{None}, this indicates to @value{GDBN} +that this sub-class doesn't wish to disassemble the requested +instruction. @value{GDBN} will then use its builtin disassembler to +perform the disassembly. + +Alternatively, this function can return a @code{DisassemblerResult} +that represents the disassembled instruction, this type is described +in more detail below. + +The @code{__call__} method can raise a @code{gdb.MemoryError} +exception (@pxref{Exception Handling}) to indicate to @value{GDBN} +that there was a problem accessing the required memory, this will then +be displayed by @value{GDBN} within the disassembler output. + +Ideally, the only three outcomes from invoking @code{__call__} would +be a return of @code{None}, a successful disassembly returned in a +@code{DisassemblerResult}, or a @code{MemoryError} indicating that +there was a problem reading memory. + +However, as an implementation of @code{__call__} could fail due to +other reasons, e.g.@: some external resource required to perform +disassembly is temporarily unavailable, then, if @code{__call__} +raises a @code{GdbError}, the exception will be converted to a string +and printed at the end of the disassembly output, the disassembly +request will then stop. + +Any other exception type raised by the @code{__call__} method is +considered an error in the user code, the exception will be printed to +the error stream according to the @kbd{set python print-stack} setting +(@pxref{set_python_print_stack,,@kbd{set python print-stack}}). +@end defun +@end deftp + +@anchor{DisassemblerResult Class} +@deftp {class} gdb.disassembler.DisassemblerResult +This class represents the result of disassembling a single +instruction. An instance of this class will be returned from +@code{builtin_disassemble} (@pxref{builtin_disassemble}), and an +instance of this class should be returned from +@w{@code{Disassembler.__call__}} (@pxref{Disassembler Class}) if an +instruction was successfully disassembled. + +It is not possible to sub-class the @code{DisassemblerResult} class. + +The @code{DisassemblerResult} class has the following properties and +methods: + +@defun DisassemblerResult.__init__ (length, string, parts) +Initialize an instance of this class, @var{length} is the length of +the disassembled instruction in bytes, which must be greater than +zero. + +Only one of @var{string} or @var{parts} should be used to initialize a +new @code{DisassemblerResult}; the other one should be passed the +value @code{None}. Alternatively, the arguments can be passed by +name, and the unused argument can be ignored. + +The @var{string} argument, if not @code{None}, is a non-empty string +that represents the entire disassembled instruction. Building a result +object using the @var{string} argument does not allow for any styling +information to be included in the result. @value{GDBN} will style the +result as a single @code{DisassemblerTextPart} with @code{STYLE_TEXT} +style (@pxref{Disassembler Styling Parts}). + +The @var{parts} argument, if not @code{None}, is a non-empty sequence +of @code{DisassemblerPart} objects. Each part represents a small part +of the disassembled instruction along with associated styling +information. A result object built using @var{parts} can be displayed +by @value{GDBN} with full styling information +(@pxref{style_disassembler_enabled,,@kbd{set style disassembler +enabled}}). +@end defun + +@defvar DisassemblerResult.length +A read-only property containing the length of the disassembled +instruction in bytes, this will always be greater than zero. +@end defvar + +@defvar DisassemblerResult.string +A read-only property containing a non-empty string representing the +disassembled instruction. The @var{string} is a representation of the +disassembled instruction without any styling information. To see how +the instruction will be styled use the @var{parts} property. + +If this instance was initialized using separate +@code{DisassemblerPart} objects, the @var{string} property will still +be valid. The @var{string} value is created by concatenating the +@code{DisassemblerPart.string} values of each component part +(@pxref{Disassembler Styling Parts}). +@end defvar + +@defvar DisassemblerResult.parts +A read-only property containing a non-empty sequence of +@code{DisassemblerPart} objects. Each @code{DisassemblerPart} object +contains a small part of the instruction along with information about +how that part should be styled. @value{GDBN} uses this information to +create styled disassembler output +(@pxref{style_disassembler_enabled,,@kbd{set style disassembler +enabled}}). + +If this instance was initialized using a single string rather than +with a sequence of @code{DisassemblerPart} objects, the @var{parts} +property will still be valid. In this case the @var{parts} property +will hold a sequence containing a single @code{DisassemblerTextPart} +object, the string of which will represent the entire instruction, and +the style of which will be @code{STYLE_TEXT}. +@end defvar +@end deftp + +@anchor{Disassembler Styling Parts} +@deftp {class} gdb.disassembler.DisassemblerPart +This is a parent class from which the different part sub-classes +inherit. Only instances of the sub-classes detailed below will be +returned by the Python API. + +It is not possible to directly create instances of either this parent +class, or any of the sub-classes listed below. Instances of the +sub-classes listed below are created by calling +@code{builtin_disassemble} (@pxref{builtin_disassemble}) and are +returned within the @code{DisassemblerResult} object, or can be +created by calling the @code{text_part} and @code{address_part} +methods on the @code{DisassembleInfo} class (@pxref{DisassembleInfo +Class}). + +The @code{DisassemblerPart} class has a single property: + +@defvar DisassemblerPart.string +A read-only property that contains a non-empty string representing +this part of the disassembled instruction. The string within this +property doesn't include any styling information. +@end defvar +@end deftp + +@deftp {class} gdb.disassembler.DisassemblerTextPart +The @code{DisassemblerTextPart} class represents a piece of the +disassembled instruction and the associated style for that piece. +Instances of this class can't be created directly, instead call +@code{DisassembleInfo.text_part} to create a new instance of this +class (@pxref{DisassembleInfo Class}). + +As well as the properties of its parent class, the +@code{DisassemblerTextPart} has the following additional property: + +@defvar DisassemblerTextPart.style +A read-only property that contains one of the defined style constants. +@value{GDBN} will use this style when styling this part of the +disassembled instruction (@pxref{Disassembler Style Constants}). +@end defvar +@end deftp + +@deftp {class} gdb.disassembler.DisassemblerAddressPart +The @code{DisassemblerAddressPart} class represents an absolute +address within a disassembled instruction. Using a +@code{DisassemblerAddressPart} instead of a +@code{DisassemblerTextPart} with @code{STYLE_ADDRESS} is preferred, +@value{GDBN} will display the address as both an absolute address, and +will look up a suitable symbol to display next to the address. Using +@code{DisassemblerAddressPart} also ensures that user settings such as +@code{set print max-symbolic-offset} are respected. + +Here is an example of an x86-64 instruction: + +@smallexample +call 0x401136 +@end smallexample + +@noindent +In this instruction the @code{0x401136 } was generated from a +single @code{DisassemblerAddressPart}. The @code{0x401136} will be +styled with @code{STYLE_ADDRESS}, and @code{foo} will be styled with +@code{STYLE_SYMBOL}. The @code{<} and @code{>} will be styled as +@code{STYLE_TEXT}. + +If the inclusion of the symbol name is not required then a +@code{DisassemblerTextPart} with style @code{STYLE_ADDRESS} can be +used instead. + +Instances of this class can't be created directly, instead call +@code{DisassembleInfo.address_part} to create a new instance of this +class (@pxref{DisassembleInfo Class}). + +As well as the properties of its parent class, the +@code{DisassemblerAddressPart} has the following additional property: + +@defvar DisassemblerAddressPart.address +A read-only property that contains the @var{address} passed to this +object's @code{__init__} method. +@end defvar +@end deftp + +@anchor{Disassembler Style Constants} + +The following table lists all of the disassembler styles that are +available. @value{GDBN} maps these style constants onto its style +settings (@pxref{Output Styling}). In some cases, several style +constants produce the same style settings, and thus will produce the +same visual effect on the screen. This could change in future +releases of @value{GDBN}, so care should be taken to select the +correct style constant to ensure correct output styling in future +releases of @value{GDBN}. + +@vtable @code +@vindex STYLE_TEXT +@item gdb.disassembler.STYLE_TEXT +This is the default style used by @value{GDBN} when styling +disassembler output. This style should be used for any parts of the +instruction that don't fit any of the other styles listed below. +@value{GDBN} styles text with this style using its default style. + +@vindex STYLE_MNEMONIC +@item gdb.disassembler.STYLE_MNEMONIC +This style is used for styling the primary instruction mnemonic, which +usually appears at, or near, the start of the disassembled instruction +string. + +@value{GDBN} styles text with this style using the @code{disassembler +mnemonic} style setting. + +@vindex STYLE_SUB_MNEMONIC +@item gdb.disassembler.STYLE_SUB_MNEMONIC +This style is used for styling any sub-mnemonics within a disassembled +instruction. A sub-mnemonic is any text within the instruction that +controls the function of the instruction, but which is disjoint from +the primary mnemonic (which will have styled @code{STYLE_MNEMONIC}). + +As an example, consider this AArch64 instruction: + +@smallexample +add w16, w7, w1, lsl #1 +@end smallexample + +@noindent +The @code{add} is the primary instruction mnemonic, and would be given +style @code{STYLE_MNEMONIC}, while @code{lsl} is the sub-mnemonic, and +would be given the style @code{STYLE_SUB_MNEMONIC}. + +@value{GDBN} styles text with this style using the @code{disassembler +mnemonic} style setting. + +@vindex STYLE_ASSEMBLER_DIRECTIVE +@item gdb.disassembler.STYLE_ASSEMBLER_DIRECTIVE +Sometimes a series of bytes doesn't decode to a valid instruction. In +this case the disassembler may choose to represent the result of +disassembling using an assembler directive, for example: + +@smallexample +.word 0x1234 +@end smallexample + +@noindent +In this case, the @code{.word} would be give the +@code{STYLE_ASSEMBLER_DIRECTIVE} style. An assembler directive is +similar to a mnemonic in many ways but is something that is not part +of the architecture's instruction set. + +@value{GDBN} styles text with this style using the @code{disassembler +mnemonic} style setting. + +@vindex STYLE_REGISTER +@item gdb.disassembler.STYLE_REGISTER +This style is used for styling any text that represents a register +name, or register number, within a disassembled instruction. + +@value{GDBN} styles text with this style using the @code{disassembler +register} style setting. + +@vindex STYLE_ADDRESS +@item gdb.disassembler.STYLE_ADDRESS +This style is used for styling numerical values that represent +absolute addresses within the disassembled instruction. + +When creating a @code{DisassemblerTextPart} with this style, you +should consider if a @code{DisassemblerAddressPart} would be more +appropriate. See @ref{Disassembler Styling Parts} for a description +of what each part offers. + +@value{GDBN} styles text with this style using the @code{disassembler +address} style setting. + +@vindex STYLE_ADDRESS_OFFSET +@item gdb.disassembler.STYLE_ADDRESS_OFFSET +This style is used for styling numerical values that represent offsets +to addresses within the disassembled instruction. A value is +considered an address offset when the instruction itself is going to +access memory, and the value is being used to offset which address is +accessed. + +For example, an architecture might have an instruction that loads from +memory using an address within a register. If that instruction also +allowed for an immediate offset to be encoded into the instruction, +this would be an address offset. Similarly, a branch instruction +might jump to an address in a register plus an address offset that is +encoded into the instruction. + +@value{GDBN} styles text with this style using the @code{disassembler +immediate} style setting. + +@vindex STYLE_IMMEDIATE +@item gdb.disassembler.STYLE_IMMEDIATE +Use @code{STYLE_IMMEDIATE} for any numerical values within a +disassembled instruction when those values are not addresses, address +offsets, or register numbers (The styles @code{STYLE_ADDRESS}, +@code{STYLE_ADDRESS_OFFSET}, or @code{STYLE_REGISTER} can be used in +those cases). + +@value{GDBN} styles text with this style using the @code{disassembler +immediate} style setting. + +@vindex STYLE_SYMBOL +@item gdb.disassembler.STYLE_SYMBOL +This style is used for styling the textual name of a symbol that is +included within a disassembled instruction. A symbol name is often +included next to an absolute address within a disassembled instruction +to make it easier for the user to understand what the address is +referring too. For example: + +@smallexample +call 0x401136 +@end smallexample + +@noindent +Here @code{foo} is the name of a symbol, and should be given the +@code{STYLE_SYMBOL} style. + +Adding symbols next to absolute addresses like this is handled +automatically by the @code{DisassemblerAddressPart} class +(@pxref{Disassembler Styling Parts}). + +@value{GDBN} styles text with this style using the @code{disassembler +symbol} style setting. + +@vindex STYLE_COMMENT_START +@item gdb.disassembler.STYLE_COMMENT_START +This style is used to start a line comment in the disassembly output. +Unlike other styles, which only apply to the single +@code{DisassemblerTextPiece} to which they are applied, the comment +style is sticky, and overrides the style of any further pieces within +this instruction. + +This means that, after a @code{STYLE_COMMENT_START} piece has been +seen, @value{GDBN} will apply the comment style until the end of the +line, ignoring the specific style within a piece. + +@value{GDBN} styles text with this style using the @code{disassembler +comment} style setting. +@end vtable + +The following functions are also contained in the +@code{gdb.disassembler} module: + +@defun register_disassembler (disassembler, architecture) +The @var{disassembler} must be a sub-class of +@code{gdb.disassembler.Disassembler} or @code{None}. + +The optional @var{architecture} is either a string, or the value +@code{None}. If it is a string, then it should be the name of an +architecture known to @value{GDBN}, as returned either from +@code{gdb.Architecture.name} +(@pxref{gdbpy_architecture_name,,gdb.Architecture.name}), or from +@code{gdb.architecture_names} +(@pxref{gdb_architecture_names,,gdb.architecture_names}). + +The @var{disassembler} will be installed for the architecture named by +@var{architecture}, or if @var{architecture} is @code{None}, then +@var{disassembler} will be installed as a global disassembler for use +by all architectures. + +@cindex disassembler in Python, global vs.@: specific +@cindex search order for disassembler in Python +@cindex look up of disassembler in Python +@value{GDBN} only records a single disassembler for each architecture, +and a single global disassembler. Calling +@code{register_disassembler} for an architecture, or for the global +disassembler, will replace any existing disassembler registered for +that @var{architecture} value. The previous disassembler is returned. + +If @var{disassembler} is @code{None} then any disassembler currently +registered for @var{architecture} is deregistered and returned. + +When @value{GDBN} is looking for a disassembler to use, @value{GDBN} +first looks for an architecture specific disassembler. If none has +been registered then @value{GDBN} looks for a global disassembler (one +registered with @var{architecture} set to @code{None}). Only one +disassembler is called to perform disassembly, so, if there is both an +architecture specific disassembler, and a global disassembler +registered, it is the architecture specific disassembler that will be +used. + +@value{GDBN} tracks the architecture specific, and global +disassemblers separately, so it doesn't matter in which order +disassemblers are created or registered; an architecture specific +disassembler, if present, will always be used in preference to a +global disassembler. + +You can use the @kbd{maint info python-disassemblers} command +(@pxref{maint info python-disassemblers}) to see which disassemblers +have been registered. +@end defun + +@anchor{builtin_disassemble} +@defun builtin_disassemble (info) +This function calls back into @value{GDBN}'s builtin disassembler to +disassemble the instruction identified by @var{info}, an instance, or +sub-class, of @code{DisassembleInfo}. + +When the builtin disassembler needs to read memory the +@code{read_memory} method on @var{info} will be called. By +sub-classing @code{DisassembleInfo} and overriding the +@code{read_memory} method, it is possible to intercept calls to +@code{read_memory} from the builtin disassembler, and to modify the +values returned. + +It is important to understand that, even when +@code{DisassembleInfo.read_memory} raises a @code{gdb.MemoryError}, it +is the internal disassembler itself that reports the memory error to +@value{GDBN}. The reason for this is that the disassembler might +probe memory to see if a byte is readable or not; if the byte can't be +read then the disassembler may choose not to report an error, but +instead to disassemble the bytes that it does have available. + +If the builtin disassembler is successful then an instance of +@code{DisassemblerResult} is returned from @code{builtin_disassemble}, +alternatively, if something goes wrong, an exception will be raised. + +A @code{MemoryError} will be raised if @code{builtin_disassemble} is +unable to read some memory that is required in order to perform +disassembly correctly. + +Any exception that is not a @code{MemoryError}, that is raised in a +call to @code{read_memory}, will pass through +@code{builtin_disassemble}, and be visible to the caller. + +Finally, there are a few cases where @value{GDBN}'s builtin +disassembler can fail for reasons that are not covered by +@code{MemoryError}. In these cases, a @code{GdbError} will be raised. +The contents of the exception will be a string describing the problem +the disassembler encountered. +@end defun + +Here is an example that registers a global disassembler. The new +disassembler invokes the builtin disassembler, and then adds a +comment, @code{## Comment}, to each line of disassembly output: + +@smallexample +class ExampleDisassembler(gdb.disassembler.Disassembler): + def __init__(self): + super().__init__("ExampleDisassembler") + + def __call__(self, info): + result = gdb.disassembler.builtin_disassemble(info) + length = result.length + text = result.string + "\t## Comment" + return gdb.disassembler.DisassemblerResult(length, text) + +gdb.disassembler.register_disassembler(ExampleDisassembler()) +@end smallexample + +The following example creates a sub-class of @code{DisassembleInfo} in +order to intercept the @code{read_memory} calls, within +@code{read_memory} any bytes read from memory have the two 4-bit +nibbles swapped around. This isn't a very useful adjustment, but +serves as an example. + +@smallexample +class MyInfo(gdb.disassembler.DisassembleInfo): + def __init__(self, info): + super().__init__(info) + + def read_memory(self, length, offset): + buffer = super().read_memory(length, offset) + result = bytearray() + for b in buffer: + v = int.from_bytes(b, 'little') + v = (v << 4) & 0xf0 | (v >> 4) + result.append(v) + return memoryview(result) + +class NibbleSwapDisassembler(gdb.disassembler.Disassembler): + def __init__(self): + super().__init__("NibbleSwapDisassembler") + + def __call__(self, info): + info = MyInfo(info) + return gdb.disassembler.builtin_disassemble(info) + +gdb.disassembler.register_disassembler(NibbleSwapDisassembler()) +@end smallexample + +@node Missing Debug Info In Python +@subsubsection Missing Debug Info In Python +@cindex python, handle missing debug information + +When @value{GDBN} encounters a new objfile (@pxref{Objfiles In +Python}), e.g.@: the primary executable, or any shared libraries used +by the inferior, @value{GDBN} will attempt to load the corresponding +debug information for that objfile. The debug information might be +found within the objfile itself, or within a separate objfile which +@value{GDBN} will automatically locate and load. + +Sometimes though, @value{GDBN} might not find any debug information +for an objfile, in this case the debugging experience will be +restricted. + +If @value{GDBN} fails to locate any debug information for a particular +objfile, there is an opportunity for a Python extension to step in. A +Python extension can potentially locate the missing debug information +using some platform- or project-specific steps, and inform +@value{GDBN} of its location. Or a Python extension might provide +some platform- or project-specific advice to the user about how to +obtain the missing debug information. + +A missing debug information Python extension consists of a handler +object which has the @code{name} and @code{enabled} attributes, and +implements the @code{__call__} method. When @value{GDBN} encounters +an objfile for which it is unable to find any debug information, it +invokes the @code{__call__} method. Full details of how handlers are +written can be found below. + +@subheading The @code{gdb.missing_debug} Module + +@value{GDBN} comes with a @code{gdb.missing_debug} module which +contains the following class and global function: + +@deftp{class} gdb.missing_debug.MissingDebugHandler + +@code{MissingDebugHandler} is a base class from which user-created +handlers can derive, though it is not required that handlers derive +from this class, so long as any user created handler has the +@code{name} and @code{enabled} attributes, and implements the +@code{__call__} method. + +@defun MissingDebugHandler.__init__ (name) +The @var{name} is a string used to reference this missing debug +handler within some @value{GDBN} commands. Valid names consist of the +characters @code{[-_a-zA-Z0-9]}, creating a handler with an invalid +name raises a @code{ValueError} exception. +@end defun + +@defun MissingDebugHandler.__call__ (objfile) +Sub-classes must override the @code{__call__} method. The +@var{objfile} argument will be a @code{gdb.Objfile}, this is the +objfile for which @value{GDBN} was unable to find any debug +information. + +The return value from the @code{__call__} method indicates what +@value{GDBN} should do next. The possible return values are: + +@itemize @bullet +@item @code{None} + +This indicates that this handler could not help with @var{objfile}, +@value{GDBN} should call any other registered handlers. + +@item @code{True} + +This indicates that this handler has installed the debug information +into a location where @value{GDBN} would normally expect to find it +when looking for separate debug information files (@pxref{Separate +Debug Files}). @value{GDBN} will repeat the normal lookup process, +which should now find the separate debug file. + +If @value{GDBN} still doesn't find the separate debug information file +after this second attempt, then the Python missing debug information +handlers are not invoked a second time, this prevents a badly behaved +handler causing @value{GDBN} to get stuck in a loop. @value{GDBN} +will continue without any debug information for @var{objfile}. + +@item @code{False} + +This indicates that this handler has done everything that it intends +to do with @var{objfile}, but no separate debug information can be +found. @value{GDBN} will not call any other registered handlers for +@var{objfile}. @value{GDBN} will continue without debugging +information for @var{objfile}. + +@item A string + +The returned string should contain a filename. @value{GDBN} will not +call any further registered handlers, and will instead load the debug +information from the file identified by the returned filename. +@end itemize + +Invoking the @code{__call__} method from this base class will raise a +@code{NotImplementedError} exception. +@end defun + +@defvar MissingDebugHandler.name +A read-only attribute which is a string, the name of this handler +passed to the @code{__init__} method. +@end defvar + +@defvar MissingDebugHandler.enabled +A modifiable attribute containing a boolean; when @code{True}, the +handler is enabled, and will be used by @value{GDBN}. When +@code{False}, the handler has been disabled, and will not be used. +@end defvar +@end deftp + +@defun gdb.missing_debug.register_handler (locus, handler, replace=@code{False}) +Register a new missing debug handler with @value{GDBN}. + +@var{handler} is an instance of a sub-class of +@code{MissingDebugHandler}, or at least an instance of an object that +has the same attributes and methods as @code{MissingDebugHandler}. + +@var{locus} specifies to which handler list to prepend @var{handler}. +It can be either a @code{gdb.Progspace} (@pxref{Progspaces In Python}) +or @code{None}, in which case the handler is registered globally. The +newly registered @var{handler} will be called before any other handler +from the same locus. Two handlers in the same locus cannot have the +same name, an attempt to add a handler with an already existing name +raises an exception unless @var{replace} is @code{True}, in which case +the old handler is deleted and the new handler is prepended to the +selected handler list. + +@value{GDBN} first calls the handlers for the current program space, +and then the globally registered handlers. As soon as a handler +returns a value other than @code{None}, no further handlers are called +for this objfile. +@end defun + +@node Missing Objfiles In Python +@subsubsection Missing Objfiles In Python +@cindex python, handle missing objfiles + +When @value{GDBN} opens a core file, for example with the +@kbd{core-file} command (@pxref{core-file command}), @value{GDBN} will +attempt to load the corresponding executable and shared libraries. +Often these files can be found on the local machine, but sometimes +these files cannot be found, in which case the debugging experience +will be restricted. + +If @value{GDBN} fails to locate a particular file then there is an +opportunity for a Python extension to step in. A Python extension can +potentially locate the missing file using some platform- or +project-specific steps, and inform @value{GDBN} of its location. Or a +Python extension might provide some platform- or project-specific +advice to the user about how to obtain the missing file. + +A missing-objfile Python extension consists of a handler object which +has the @code{name} and @code{enabled} attributes, and implements the +@code{__call__} method. When @value{GDBN} encounters a situation +where a file cannot be found, but the build-id (@pxref{build ID}) for +the missing file is known, then the @code{__call__} method is invoked +to try and find the file. Full details of how handlers are written +can be found below. + +@subheading The @code{gdb.missing_objfile} Module + +@value{GDBN} comes with a @code{gdb.missing_objfile} module which +contains the following class and global function: + +@deftp{class} gdb.missing_objfile.MissingObjfileHandler + +@code{MissingObjfileHandler} is a base class from which user-created +handlers can derive, though it is not required that handlers derive +from this class, so long as any user created handler has the +@code{name} and @code{enabled} attributes, and implements the +@code{__call__} method. + +@defun MissingObjfileHandler.__init__ (name) +The @var{name} is a string used to reference this missing-objfile +handler within some @value{GDBN} commands. Valid names consist of the +characters @samp{[-_a-zA-Z0-9]}, creating a handler with an invalid +name raises a @code{ValueError} exception. +@end defun + +@defun MissingObjfileHandler.__call__ (pspace, build_id, filename) + +Sub-classes must override the @code{__call__} method. The +@var{pspace} argument will be a @code{gdb.Progspace} +(@pxref{Progspaces In Python}), this is the program space in which +@value{GDBN} is looking for the missing file. + +The @var{build_id} argument is a string containing the build-id of the +file that is missing, this will be in the same format as returned by +@code{Objfile.build_id} (@pxref{Objfile.build_id}). + +The @var{filename} argument contains the name of the file that +@value{GDBN} is looking for. This information is provided to allow +handlers to generate informative messages for the user. A handler is +not required to place the missing file at this location. There might +already be a file present at this location, but it might not match the +required build-id, in which case @value{GDBN} will have ignored it. +In some limited cases @value{GDBN} might not be able to establish the +@var{filename} of the file it is searching for, in this case +@value{GDBN} will use a string @samp{with build-id @var{build_id}} as a +replacement. + +The return value from the @code{__call__} method indicates what +@value{GDBN} should do next. The possible return values are: + +@itemize @bullet +@item @code{None} + +This indicates that this handler could not locate the missing file and +@value{GDBN} should call any other registered handlers. + +@item @code{True} + +This indicates that this handler has installed the missing file into a +location where @value{GDBN} would normally expect to find it. The +only location in which @value{GDBN} will look is within the +@file{.build-id} sub-directory within the @var{debug-file-directory} +(@pxref{debug-file-directory}). + +@value{GDBN} will repeat the normal lookup process, which should now +find the previously missing file. + +If @value{GDBN} still doesn't find file after this second attempt, +then the Python missing-objfile handlers are not invoked a second +time, this prevents a badly behaved handler causing @value{GDBN} to +get stuck in a loop. @value{GDBN} will continue without the missing +file, though this will degrade the debugging experience. + +@item @code{False} + +This indicates that this handler has done everything that it intends +to do but the missing file could not be found. @value{GDBN} will not +call any other registered handlers to look for the missing file. +@value{GDBN} will continue without the missing file, though this will +degrade the debugging experience. + +@item A string + +The returned string should contain a filename. @value{GDBN} will not +call any further registered handlers, and will instead use the +returned filename as the missing file. +@end itemize + +Invoking the @code{__call__} method from this base class will raise a +@code{NotImplementedError} exception. +@end defun + +@defvar MissingObjfileHandler.name +A read-only attribute which is a string, the name of this handler +passed to the @code{__init__} method. +@end defvar + +@defvar MissingObjfileHandler.enabled +A modifiable attribute containing a boolean; when @code{True}, the +handler is enabled, and will be used by @value{GDBN}. When +@code{False}, the handler has been disabled, and will not be used. +@end defvar +@end deftp + +@defun gdb.missing_objfile.register_handler (locus, handler, replace=@code{False}) +Register a new missing-objfile handler with @value{GDBN}. + +@var{handler} is an instance of a sub-class of +@code{MissingObjfileHandler}, or at least an instance of an object that +has the same attributes and methods as @code{MissingObjfileHandler}. + +@var{locus} specifies to which handler list to prepend @var{handler}. +It can be either a @code{gdb.Progspace} (@pxref{Progspaces In Python}) +or @code{None}, in which case the handler is registered globally. The +newly registered @var{handler} will be called before any other handler +from the same locus. Two handlers in the same locus cannot have the +same name, an attempt to add a handler with an already existing name +raises an exception unless @var{replace} is @code{True}, in which case +the old handler is deleted and the new handler is prepended to the +selected handler list. + +@value{GDBN} first calls the handlers for the current program space, +and then the globally registered handlers. As soon as a handler +returns a value other than @code{None}, no further handlers are +called. +@end defun + +@subheading Managing Missing-Objfile Handlers + +@value{GDBN} defines the following commands to manage registered +missing-objfile handlers: + +@table @code + +@kindex info missing-objfile-handlers +@item info missing-objfile-handlers @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +Lists all registered missing-objfile handlers. Arguments @var{locus} +and @var{name-regexp} are both optional and can be used to filter +which handlers are listed. + +The @var{locus} argument should be either @kbd{global}, +@kbd{progspace}, or the name of an object file. Only handlers +registered for the specified locus will be listed. + +The @var{name-regexp} is a regular expression used to match against +handler names. + +@kindex disable missing-objfile-handler +@item disable missing-objfile-handler @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info +missing-objfile-handlers} above, but instead of listing the matching +handlers, all of the matching handlers are disabled. The +@code{enabled} field of each matching handler is set to @code{False}. + +@kindex enable missing-objfile-handler +@item enable missing-objfile-handler @r{[} @var{locus} @r{[} @var{name-regexp} @r{]} @r{]} +The @var{locus} and @var{name-regexp} are interpreted as in @kbd{info +missing-objfile-handlers} above, but instead of listing the matching +handlers, all of the matching handlers are enabled. The +@code{enabled} field of each matching handler is set to @code{True}. +@end table + +@node Python Auto-loading +@subsection Python Auto-loading +@cindex Python auto-loading + +When a new object file is read (for example, due to the @code{file} +command, or because the inferior has loaded a shared library), +@value{GDBN} will look for Python support scripts in several ways: +@file{@var{objfile}-gdb.py} and @code{.debug_gdb_scripts} section. +@xref{Auto-loading extensions}. + +The auto-loading feature is useful for supplying application-specific +debugging commands and scripts. + +Auto-loading can be enabled or disabled, +and the list of auto-loaded scripts can be printed. + +@table @code +@anchor{set auto-load python-scripts} +@kindex set auto-load python-scripts +@item set auto-load python-scripts [on|off] +Enable or disable the auto-loading of Python scripts. + +@anchor{show auto-load python-scripts} +@kindex show auto-load python-scripts +@item show auto-load python-scripts +Show whether auto-loading of Python scripts is enabled or disabled. + +@anchor{info auto-load python-scripts} +@kindex info auto-load python-scripts +@cindex print list of auto-loaded Python scripts +@item info auto-load python-scripts [@var{regexp}] +Print the list of all Python scripts that @value{GDBN} auto-loaded. + +Also printed is the list of Python scripts that were mentioned in +the @code{.debug_gdb_scripts} section and were either not found +(@pxref{dotdebug_gdb_scripts section}) or were not auto-loaded due to +@code{auto-load safe-path} rejection (@pxref{Auto-loading}). +This is useful because their names are not printed when @value{GDBN} +tries to load them and fails. There may be many of them, and printing +an error message for each one is problematic. + +If @var{regexp} is supplied only Python scripts with matching names are printed. + +Example: + +@smallexample +(gdb) info auto-load python-scripts +Loaded Script +Yes py-section-script.py + full name: /tmp/py-section-script.py +No my-foo-pretty-printers.py +@end smallexample +@end table + +When reading an auto-loaded file or script, @value{GDBN} sets the +@dfn{current objfile}. This is available via the @code{gdb.current_objfile} +function (@pxref{Objfiles In Python}). This can be useful for +registering objfile-specific pretty-printers and frame-filters. + +@node Python modules +@subsection Python modules +@cindex python modules + +@value{GDBN} comes with several modules to assist writing Python code. + +@menu +* gdb.printing:: Building and registering pretty-printers. +* gdb.types:: Utilities for working with types. +* gdb.prompt:: Utilities for prompt value substitution. +* gdb.ptwrite:: Utilities for PTWRITE filter registration. +@end menu + +@node gdb.printing +@subsubsection gdb.printing +@cindex gdb.printing + +This module provides a collection of utilities for working with +pretty-printers. + +@table @code +@item PrettyPrinter (@var{name}, @var{subprinters}=None) +This class specifies the API that makes @samp{info pretty-printer}, +@samp{enable pretty-printer} and @samp{disable pretty-printer} work. +Pretty-printers should generally inherit from this class. + +@item SubPrettyPrinter (@var{name}) +For printers that handle multiple types, this class specifies the +corresponding API for the subprinters. + +@item RegexpCollectionPrettyPrinter (@var{name}) +Utility class for handling multiple printers, all recognized via +regular expressions. +@xref{Writing a Pretty-Printer}, for an example. + +@item FlagEnumerationPrinter (@var{name}) +A pretty-printer which handles printing of @code{enum} values. Unlike +@value{GDBN}'s built-in @code{enum} printing, this printer attempts to +work properly when there is some overlap between the enumeration +constants. The argument @var{name} is the name of the printer and +also the name of the @code{enum} type to look up. + +@item register_pretty_printer (@var{obj}, @var{printer}, @var{replace}=False) +Register @var{printer} with the pretty-printer list of @var{obj}. +If @var{replace} is @code{True} then any existing copy of the printer +is replaced. Otherwise a @code{RuntimeError} exception is raised +if a printer with the same name already exists. +@end table + +@node gdb.types +@subsubsection gdb.types +@cindex gdb.types + +This module provides a collection of utilities for working with +@code{gdb.Type} objects. + +@table @code +@item get_basic_type (@var{type}) +Return @var{type} with const and volatile qualifiers stripped, +and with typedefs and C@t{++} references converted to the underlying type. + +C@t{++} example: + +@smallexample +typedef const int const_int; +const_int foo (3); +const_int& foo_ref (foo); +int main () @{ return 0; @} +@end smallexample + +Then in gdb: + +@smallexample +(gdb) start +(gdb) python import gdb.types +(gdb) python foo_ref = gdb.parse_and_eval("foo_ref") +(gdb) python print gdb.types.get_basic_type(foo_ref.type) +int +@end smallexample + +@item has_field (@var{type}, @var{field}) +Return @code{True} if @var{type}, assumed to be a type with fields +(e.g., a structure or union), has field @var{field}. + +@item make_enum_dict (@var{enum_type}) +Return a Python @code{dictionary} type produced from @var{enum_type}. + +@item deep_items (@var{type}) +Returns a Python iterator similar to the standard +@code{gdb.Type.iteritems} method, except that the iterator returned +by @code{deep_items} will recursively traverse anonymous struct or +union fields. For example: + +@smallexample +struct A +@{ + int a; + union @{ + int b0; + int b1; + @}; +@}; +@end smallexample + +@noindent +Then in @value{GDBN}: +@smallexample +(@value{GDBP}) python import gdb.types +(@value{GDBP}) python struct_a = gdb.lookup_type("struct A") +(@value{GDBP}) python print struct_a.keys () +@{['a', '']@} +(@value{GDBP}) python print [k for k,v in gdb.types.deep_items(struct_a)] +@{['a', 'b0', 'b1']@} +@end smallexample + +@item get_type_recognizers () +Return a list of the enabled type recognizers for the current context. +This is called by @value{GDBN} during the type-printing process +(@pxref{Type Printing API}). + +@item apply_type_recognizers (recognizers, type_obj) +Apply the type recognizers, @var{recognizers}, to the type object +@var{type_obj}. If any recognizer returns a string, return that +string. Otherwise, return @code{None}. This is called by +@value{GDBN} during the type-printing process (@pxref{Type Printing +API}). + +@item register_type_printer (locus, printer) +This is a convenience function to register a type printer +@var{printer}. The printer must implement the type printer protocol. +The @var{locus} argument is either a @code{gdb.Objfile}, in which case +the printer is registered with that objfile; a @code{gdb.Progspace}, +in which case the printer is registered with that progspace; or +@code{None}, in which case the printer is registered globally. + +@item TypePrinter +This is a base class that implements the type printer protocol. Type +printers are encouraged, but not required, to derive from this class. +It defines a constructor: + +@defmethod TypePrinter __init__ (self, name) +Initialize the type printer with the given name. The new printer +starts in the enabled state. +@end defmethod + +@end table + +@node gdb.prompt +@subsubsection gdb.prompt +@cindex gdb.prompt + +This module provides a method for prompt value-substitution. + +@table @code +@item substitute_prompt (@var{string}) +Return @var{string} with escape sequences substituted by values. Some +escape sequences take arguments. You can specify arguments inside +``@{@}'' immediately following the escape sequence. + +The escape sequences you can pass to this function are: + +@table @code +@item \\ +Substitute a backslash. +@item \e +Substitute an ESC character. +@item \f +Substitute the selected frame; an argument names a frame parameter. +@item \n +Substitute a newline. +@item \p +Substitute a parameter's value; the argument names the parameter. +@item \r +Substitute a carriage return. +@item \t +Substitute the selected thread; an argument names a thread parameter. +@item \v +Substitute the version of GDB. +@item \w +Substitute the current working directory. +@item \[ +Begin a sequence of non-printing characters. These sequences are +typically used with the ESC character, and are not counted in the string +length. Example: ``\[\e[0;34m\](gdb)\[\e[0m\]'' will return a +blue-colored ``(gdb)'' prompt where the length is five. +@item \] +End a sequence of non-printing characters. +@end table + +For example: + +@smallexample +substitute_prompt ("frame: \f, args: \p@{print frame-arguments@}") +@end smallexample + +@exdent will return the string: + +@smallexample +"frame: main, args: scalars" +@end smallexample +@end table + +@node gdb.ptwrite +@subsubsection gdb.ptwrite +@cindex gdb.ptwrite + +This module provides additional functionality for recording programs that +make use of the @code{PTWRITE} instruction. @code{PTWRITE} is a x86 +instruction that allows to write values into the Intel Processor Trace +(@pxref{Process Record and Replay}). +The @value{NGCC} intrinsics for it are: +@smallexample +void _ptwrite32 (unsigned int a) +void _ptwrite64 (unsigned __int64 a) +@end smallexample + +If an inferior uses the instruction, @value{GDBN} by default inserts the +raw payload value as auxiliary information into the execution history. +Auxiliary information is by default printed during +@code{record instruction-history}, @code{record function-call-history}, +and all stepping commands, and is accessible in Python as a +@code{RecordAuxiliary} object (@pxref{Recordings In Python}). + +@exdent Sample program: +@smallexample +@group +#include + +void +ptwrite64 (unsigned long long value) +@{ + _ptwrite64 (value); +@} +@end group + +@group +int +main (void) +@{ + ptwrite64 (0x42); + return 0; /* break here. */ +@} +@end group +@end smallexample + + +@exdent @value{GDBN} output after recording the sample program in pt format: +@smallexample +@group +(gdb) record instruction-history 12,14 +12 0x0040074c : ptwrite %rbx +13 [0x42] +14 0x00400751 : mov -0x8(%rbp),%rbx +(gdb) record function-call-history +1 main +2 ptwrite64 + [0x42] +3 main +@end group +@end smallexample + +The @code{gdb.ptwrite} module allows customizing the default output of +@code{PTWRITE} auxiliary information. A custom Python function can be +registered as the @code{PTWRITE} filter function. This function will be +called with the @code{PTWRITE} payload and PC as arguments during trace +decoding. The function can return a string, which will be printed by +@value{GDBN} during the aforementioned commands, or @code{None}, resulting +in no output. To register such a filter function, the user needs to +provide a filter factory function, which returns a new filter function +object to be called by @value{GDBN}. + +@findex gdb.ptwrite.register_filter_factory +@defun register_filter_factory (filter_factory) +Used to register the @code{PTWRITE} filter factory. This filter factory can +be any callable object that accepts one argument, the current thread as +a @code{gdb.InferiorThread}. +It can return None or a callable. This callable is the @code{PTWRITE} filter +function for the specified thread. If @code{None} is returned by the factory +function, the default auxiliary information will be printed. +@end defun + +@findex gdb.ptwrite.get_filter +@defun get_filter () +Return the currently active @code{PTWRITE} filter function. +@end defun + +An example: + +@smallexample +@group +(gdb) python-interactive +>>> class my_filter(): +... def __init__(self): +... self.var = 0 +... def __call__(self, payload, ip): +... self.var += 1 +... return f"counter: @{self.var@}, ip: @{ip:#x@}" +... +>>> def my_filter_factory(thread): +... if thread.global_num == 1: +... return my_filter() +... else: +... return None +... +>>> import gdb.ptwrite +>>> gdb.ptwrite.register_filter_factory(my_filter_factory) +>>> +@end group + +@group +(gdb) record function-call-history 59,64 +59 pthread_create@@GLIBC_2.2.5 +60 job() +61 task(void*) +62 ptwrite64(unsigned long) + [counter: 1, ip: 0x401156] +63 task(void*) +64 ptwrite32(unsigned int) + [counter: 2, ip: 0x40116c] +@end group + +@group +(gdb) info threads +* 1 Thread 0x7ffff7fd8740 (LWP 25796) "ptw_threads" task () + at bin/ptwrite/ptw_threads.c:45 + 2 Thread 0x7ffff6eb8700 (LWP 25797) "ptw_threads" task () + at bin/ptwrite/ptw_threads.c:45 +@end group + +@group +(gdb) thread 2 +[Switching to thread 2 (Thread 0x7ffff6eb8700 (LWP 25797))] +#0 task (arg=0x0) at ptwrite_threads.c:45 +45 return NULL; +@end group + +@group +(gdb) record function-call-history 10,14 +10 start_thread +11 task(void*) +12 ptwrite64(unsigned long) + [0x42] +13 task(void*) +14 ptwrite32(unsigned int) + [0x43] +@end group +@end smallexample + +This @value{GDBN} feature is dependent on hardware and operating system +support and requires the Intel Processor Trace decoder library in version +2.0.0 or newer. diff -pruN 16.3-5/gdb/doc/stabs.info 16.3-5ubuntu1/gdb/doc/stabs.info --- 16.3-5/gdb/doc/stabs.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/stabs.info 2025-04-20 17:25:34.000000000 +0000 @@ -0,0 +1,4584 @@ +This is stabs.info, produced by makeinfo version 6.8 from stabs.texinfo. + +Copyright (C) 1992-2024 Free Software Foundation, Inc. Contributed by +Cygnus Support. Written by Julia Menapace, Jim Kingdon, and David +MacKenzie. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* Stabs: (stabs). The "stabs" debugging information format. +END-INFO-DIR-ENTRY + + This document describes the stabs debugging symbol tables. + + Copyright (C) 1992-2024 Free Software Foundation, Inc. Contributed +by Cygnus Support. Written by Julia Menapace, Jim Kingdon, and David +MacKenzie. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled "GNU +Free Documentation License". + + +File: stabs.info, Node: Top, Next: Overview, Up: (dir) + +The "stabs" representation of debugging information +*************************************************** + +This document describes the stabs debugging format. + +* Menu: + +* Overview:: Overview of stabs +* Program Structure:: Encoding of the structure of the program +* Constants:: Constants +* Variables:: +* Types:: Type definitions +* Macro define and undefine:: Representation of #define and #undef +* Symbol Tables:: Symbol information in symbol tables +* Cplusplus:: Stabs specific to C++ +* Stab Types:: Symbol types in a.out files +* Symbol Descriptors:: Table of symbol descriptors +* Type Descriptors:: Table of type descriptors +* Expanded Reference:: Reference information by stab type +* Questions:: Questions and anomalies +* Stab Sections:: In some object file formats, stabs are + in sections. +* GNU Free Documentation License:: The license for this documentation +* Symbol Types Index:: Index of symbolic stab symbol type names. + + +File: stabs.info, Node: Overview, Next: Program Structure, Prev: Top, Up: Top + +1 Overview of Stabs +******************* + +"Stabs" refers to a format for information that describes a program to a +debugger. This format was apparently invented by Peter Kessler at the +University of California at Berkeley, for the 'pdx' Pascal debugger; the +format has spread widely since then. + + This document is one of the few published sources of documentation on +stabs. It is believed to be comprehensive for stabs used by C. The +lists of symbol descriptors (*note Symbol Descriptors::) and type +descriptors (*note Type Descriptors::) are believed to be completely +comprehensive. Stabs for COBOL-specific features and for variant +records (used by Pascal and Modula-2) are poorly documented here. + + Other sources of information on stabs are 'Dbx and Dbxtool +Interfaces', 2nd edition, by Sun, 1988, and 'AIX Version 3.2 Files +Reference', Fourth Edition, September 1992, "dbx Stabstring Grammar" in +the a.out section, page 2-31. This document is believed to incorporate +the information from those two sources except where it explicitly +directs you to them for more information. + +* Menu: + +* Flow:: Overview of debugging information flow +* Stabs Format:: Overview of stab format +* String Field:: The string field +* C Example:: A simple example in C source +* Assembly Code:: The simple example at the assembly level + + +File: stabs.info, Node: Flow, Next: Stabs Format, Up: Overview + +1.1 Overview of Debugging Information Flow +========================================== + +The GNU C compiler compiles C source in a '.c' file into assembly +language in a '.s' file, which the assembler translates into a '.o' +file, which the linker combines with other '.o' files and libraries to +produce an executable file. + + With the '-g' option, GCC puts in the '.s' file additional debugging +information, which is slightly transformed by the assembler and linker, +and carried through into the final executable. This debugging +information describes features of the source file like line numbers, the +types and scopes of variables, and function names, parameters, and +scopes. + + For some object file formats, the debugging information is +encapsulated in assembler directives known collectively as "stab" +(symbol table) directives, which are interspersed with the generated +code. Stabs are the native format for debugging information in the +a.out and XCOFF object file formats. The GNU tools can also emit stabs +in the COFF and ECOFF object file formats. + + The assembler adds the information from stabs to the symbol +information it places by default in the symbol table and the string +table of the '.o' file it is building. The linker consolidates the '.o' +files into one executable file, with one symbol table and one string +table. Debuggers use the symbol and string tables in the executable as +a source of debugging information about the program. + + +File: stabs.info, Node: Stabs Format, Next: String Field, Prev: Flow, Up: Overview + +1.2 Overview of Stab Format +=========================== + +There are three overall formats for stab assembler directives, +differentiated by the first word of the stab. The name of the directive +describes which combination of four possible data fields follows. It is +either '.stabs' (string), '.stabn' (number), or '.stabd' (dot). IBM's +XCOFF assembler uses '.stabx' (and some other directives such as '.file' +and '.bi') instead of '.stabs', '.stabn' or '.stabd'. + + The overall format of each class of stab is: + + .stabs "STRING",TYPE,OTHER,DESC,VALUE + .stabn TYPE,OTHER,DESC,VALUE + .stabd TYPE,OTHER,DESC + .stabx "STRING",VALUE,TYPE,SDB-TYPE + + For '.stabn' and '.stabd', there is no STRING (the 'n_strx' field is +zero; see *note Symbol Tables::). For '.stabd', the VALUE field is +implicit and has the value of the current file location. For '.stabx', +the SDB-TYPE field is unused for stabs and can always be set to zero. +The OTHER field is almost always unused and can be set to zero. + + The number in the TYPE field gives some basic information about which +type of stab this is (or whether it _is_ a stab, as opposed to an +ordinary symbol). Each valid type number defines a different stab type; +further, the stab type defines the exact interpretation of, and possible +values for, any remaining STRING, DESC, or VALUE fields present in the +stab. *Note Stab Types::, for a list in numeric order of the valid TYPE +field values for stab directives. + + +File: stabs.info, Node: String Field, Next: C Example, Prev: Stabs Format, Up: Overview + +1.3 The String Field +==================== + +For most stabs the string field holds the meat of the debugging +information. The flexible nature of this field is what makes stabs +extensible. For some stab types the string field contains only a name. +For other stab types the contents can be a great deal more complex. + + The overall format of the string field for most stab types is: + + "NAME:SYMBOL-DESCRIPTOR TYPE-INFORMATION" + + NAME is the name of the symbol represented by the stab; it can +contain a pair of colons (*note Nested Symbols::). NAME can be omitted, +which means the stab represents an unnamed object. For example, +':t10=*2' defines type 10 as a pointer to type 2, but does not give the +type a name. Omitting the NAME field is supported by AIX dbx and GDB +after about version 4.8, but not other debuggers. GCC sometimes uses a +single space as the name instead of omitting the name altogether; +apparently that is supported by most debuggers. + + The SYMBOL-DESCRIPTOR following the ':' is an alphabetic character +that tells more specifically what kind of symbol the stab represents. +If the SYMBOL-DESCRIPTOR is omitted, but type information follows, then +the stab represents a local variable. For a list of symbol descriptors, +see *note Symbol Descriptors::. The 'c' symbol descriptor is an +exception in that it is not followed by type information. *Note +Constants::. + + TYPE-INFORMATION is either a TYPE-NUMBER, or 'TYPE-NUMBER='. A +TYPE-NUMBER alone is a type reference, referring directly to a type that +has already been defined. + + The 'TYPE-NUMBER=' form is a type definition, where the number +represents a new type which is about to be defined. The type definition +may refer to other types by number, and those type numbers may be +followed by '=' and nested definitions. Also, the Lucid compiler will +repeat 'TYPE-NUMBER=' more than once if it wants to define several type +numbers at once. + + In a type definition, if the character that follows the equals sign +is non-numeric then it is a TYPE-DESCRIPTOR, and tells what kind of type +is about to be defined. Any other values following the TYPE-DESCRIPTOR +vary, depending on the TYPE-DESCRIPTOR. *Note Type Descriptors::, for a +list of TYPE-DESCRIPTOR values. If a number follows the '=' then the +number is a TYPE-REFERENCE. For a full description of types, *note +Types::. + + A TYPE-NUMBER is often a single number. The GNU and Sun tools +additionally permit a TYPE-NUMBER to be a pair +(FILE-NUMBER,FILETYPE-NUMBER) (the parentheses appear in the string, and +serve to distinguish the two cases). The FILE-NUMBER is 0 for the base +source file, 1 for the first included file, 2 for the next, and so on. +The FILETYPE-NUMBER is a number starting with 1 which is incremented for +each new type defined in the file. (Separating the file number and the +type number permits the 'N_BINCL' optimization to succeed more often; +see *note Include Files::). + + There is an AIX extension for type attributes. Following the '=' are +any number of type attributes. Each one starts with '@' and ends with +';'. Debuggers, including AIX's dbx and GDB 4.10, skip any type +attributes they do not recognize. GDB 4.9 and other versions of dbx may +not do this. Because of a conflict with C++ (*note Cplusplus::), new +attributes should not be defined which begin with a digit, '(', or '-'; +GDB may be unable to distinguish those from the C++ type descriptor '@'. +The attributes are: + +'aBOUNDARY' + BOUNDARY is an integer specifying the alignment. I assume it + applies to all variables of this type. + +'pINTEGER' + Pointer class (for checking). Not sure what this means, or how + INTEGER is interpreted. + +'P' + Indicate this is a packed type, meaning that structure fields or + array elements are placed more closely in memory, to save memory at + the expense of speed. + +'sSIZE' + Size in bits of a variable of this type. This is fully supported + by GDB 4.11 and later. + +'S' + Indicate that this type is a string instead of an array of + characters, or a bitstring instead of a set. It doesn't change the + layout of the data being represented, but does enable the debugger + to know which type it is. + +'V' + Indicate that this type is a vector instead of an array. The only + major difference between vectors and arrays is that vectors are + passed by value instead of by reference (vector coprocessor + extension). + + All of this can make the string field quite long. All versions of +GDB, and some versions of dbx, can handle arbitrarily long strings. But +many versions of dbx (or assemblers or linkers, I'm not sure which) +cretinously limit the strings to about 80 characters, so compilers which +must work with such systems need to split the '.stabs' directive into +several '.stabs' directives. Each stab duplicates every field except +the string field. The string field of every stab except the last is +marked as continued with a backslash at the end (in the assembly code +this may be written as a double backslash, depending on the assembler). +Removing the backslashes and concatenating the string fields of each +stab produces the original, long string. Just to be incompatible (or so +they don't have to worry about what the assembler does with +backslashes), AIX can use '?' instead of backslash. + + +File: stabs.info, Node: C Example, Next: Assembly Code, Prev: String Field, Up: Overview + +1.4 A Simple Example in C Source +================================ + +To get the flavor of how stabs describe source information for a C +program, let's look at the simple program: + + main() + { + printf("Hello world"); + } + + When compiled with '-g', the program above yields the following '.s' +file. Line numbers have been added to make it easier to refer to parts +of the '.s' file in the description of the stabs that follows. + + +File: stabs.info, Node: Assembly Code, Prev: C Example, Up: Overview + +1.5 The Simple Example at the Assembly Level +============================================ + +This simple "hello world" example demonstrates several of the stab types +used to describe C language source files. + + 1 gcc2_compiled.: + 2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 + 3 .stabs "hello.c",100,0,0,Ltext0 + 4 .text + 5 Ltext0: + 6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 + 7 .stabs "char:t2=r2;0;127;",128,0,0,0 + 8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 + 9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 + 10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 + 11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 + 12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 + 13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 + 14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 + 15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 + 16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 + 17 .stabs "float:t12=r1;4;0;",128,0,0,0 + 18 .stabs "double:t13=r1;8;0;",128,0,0,0 + 19 .stabs "long double:t14=r1;8;0;",128,0,0,0 + 20 .stabs "void:t15=15",128,0,0,0 + 21 .align 4 + 22 LC0: + 23 .ascii "Hello, world!\12\0" + 24 .align 4 + 25 .global _main + 26 .proc 1 + 27 _main: + 28 .stabn 68,0,4,LM1 + 29 LM1: + 30 !#PROLOGUE# 0 + 31 save %sp,-136,%sp + 32 !#PROLOGUE# 1 + 33 call ___main,0 + 34 nop + 35 .stabn 68,0,5,LM2 + 36 LM2: + 37 LBB2: + 38 sethi %hi(LC0),%o1 + 39 or %o1,%lo(LC0),%o0 + 40 call _printf,0 + 41 nop + 42 .stabn 68,0,6,LM3 + 43 LM3: + 44 LBE2: + 45 .stabn 68,0,6,LM4 + 46 LM4: + 47 L1: + 48 ret + 49 restore + 50 .stabs "main:F1",36,0,0,_main + 51 .stabn 192,0,0,LBB2 + 52 .stabn 224,0,0,LBE2 + + +File: stabs.info, Node: Program Structure, Next: Constants, Prev: Overview, Up: Top + +2 Encoding the Structure of the Program +*************************************** + +The elements of the program structure that stabs encode include the name +of the main function, the names of the source and include files, the +line numbers, procedure names and types, and the beginnings and ends of +blocks of code. + +* Menu: + +* Main Program:: Indicate what the main program is +* Source Files:: The path and name of the source file +* Include Files:: Names of include files +* Line Numbers:: +* Procedures:: +* Nested Procedures:: +* Block Structure:: +* Alternate Entry Points:: Entering procedures except at the beginning. + + +File: stabs.info, Node: Main Program, Next: Source Files, Up: Program Structure + +2.1 Main Program +================ + +Most languages allow the main program to have any name. The 'N_MAIN' +stab type tells the debugger the name that is used in this program. +Only the string field is significant; it is the name of a function which +is the main program. Most C compilers do not use this stab (they expect +the debugger to assume that the name is 'main'), but some C compilers +emit an 'N_MAIN' stab for the 'main' function. I'm not sure how XCOFF +handles this. + + +File: stabs.info, Node: Source Files, Next: Include Files, Prev: Main Program, Up: Program Structure + +2.2 Paths and Names of the Source Files +======================================= + +Before any other stabs occur, there must be a stab specifying the source +file. This information is contained in a symbol of stab type 'N_SO'; +the string field contains the name of the file. The value of the symbol +is the start address of the portion of the text section corresponding to +that file. + + Some compilers use the desc field to indicate the language of the +source file. Sun's compilers started this usage, and the first +constants are derived from their documentation. Languages added by +gcc/gdb start at 0x32 to avoid conflict with languages Sun may add in +the future. A desc field with a value 0 indicates that no language has +been specified via this mechanism. + +'N_SO_AS' (0x1) + Assembly language +'N_SO_C' (0x2) + K&R traditional C +'N_SO_ANSI_C' (0x3) + ANSI C +'N_SO_CC' (0x4) + C++ +'N_SO_FORTRAN' (0x5) + Fortran +'N_SO_PASCAL' (0x6) + Pascal +'N_SO_FORTRAN90' (0x7) + Fortran90 +'N_SO_OBJC' (0x32) + Objective-C +'N_SO_OBJCPLUS' (0x33) + Objective-C++ + + Some compilers (for example, GCC2 and SunOS4 '/bin/cc') also include +the directory in which the source was compiled, in a second 'N_SO' +symbol preceding the one containing the file name. This symbol can be +distinguished by the fact that it ends in a slash. Code from the +'cfront' C++ compiler can have additional 'N_SO' symbols for nonexistent +source files after the 'N_SO' for the real source file; these are +believed to contain no useful information. + + For example: + + .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # 100 is N_SO + .stabs "hello.c",100,0,0,Ltext0 + .text + Ltext0: + + Instead of 'N_SO' symbols, XCOFF uses a '.file' assembler directive +which assembles to a 'C_FILE' symbol; explaining this in detail is +outside the scope of this document. + + If it is useful to indicate the end of a source file, this is done +with an 'N_SO' symbol with an empty string for the name. The value is +the address of the end of the text section for the file. For some +systems, there is no indication of the end of a source file, and you +just need to figure it ended when you see an 'N_SO' for a different +source file, or a symbol ending in '.o' (which at least some linkers +insert to mark the start of a new '.o' file). + + +File: stabs.info, Node: Include Files, Next: Line Numbers, Prev: Source Files, Up: Program Structure + +2.3 Names of Include Files +========================== + +There are several schemes for dealing with include files: the +traditional 'N_SOL' approach, Sun's 'N_BINCL' approach, and the XCOFF +'C_BINCL' approach (which despite the similar name has little in common +with 'N_BINCL'). + + An 'N_SOL' symbol specifies which include file subsequent symbols +refer to. The string field is the name of the file and the value is the +text address corresponding to the end of the previous include file and +the start of this one. To specify the main source file again, use an +'N_SOL' symbol with the name of the main source file. + + The 'N_BINCL' approach works as follows. An 'N_BINCL' symbol +specifies the start of an include file. In an object file, only the +string is significant; the linker puts data into some of the other +fields. The end of the include file is marked by an 'N_EINCL' symbol +(which has no string field). In an object file, there is no significant +data in the 'N_EINCL' symbol. 'N_BINCL' and 'N_EINCL' can be nested. + + If the linker detects that two source files have identical stabs +between an 'N_BINCL' and 'N_EINCL' pair (as will generally be the case +for a header file), then it only puts out the stabs once. Each +additional occurrence is replaced by an 'N_EXCL' symbol. I believe the +GNU linker and the Sun (both SunOS4 and Solaris) linker are the only +ones which supports this feature. + + A linker which supports this feature will set the value of a +'N_BINCL' symbol to the total of all the characters in the stabs strings +included in the header file, omitting any file numbers. The value of an +'N_EXCL' symbol is the same as the value of the 'N_BINCL' symbol it +replaces. This information can be used to match up 'N_EXCL' and +'N_BINCL' symbols which have the same filename. The 'N_EINCL' value, +and the values of the other and description fields for all three, appear +to always be zero. + + For the start of an include file in XCOFF, use the '.bi' assembler +directive, which generates a 'C_BINCL' symbol. A '.ei' directive, which +generates a 'C_EINCL' symbol, denotes the end of the include file. Both +directives are followed by the name of the source file in quotes, which +becomes the string for the symbol. The value of each symbol, produced +automatically by the assembler and linker, is the offset into the +executable of the beginning (inclusive, as you'd expect) or end +(inclusive, as you would not expect) of the portion of the COFF line +table that corresponds to this include file. 'C_BINCL' and 'C_EINCL' do +not nest. + + +File: stabs.info, Node: Line Numbers, Next: Procedures, Prev: Include Files, Up: Program Structure + +2.4 Line Numbers +================ + +An 'N_SLINE' symbol represents the start of a source line. The desc +field contains the line number and the value contains the code address +for the start of that source line. On most machines the address is +absolute; for stabs in sections (*note Stab Sections::), it is relative +to the function in which the 'N_SLINE' symbol occurs. + + GNU documents 'N_DSLINE' and 'N_BSLINE' symbols for line numbers in +the data or bss segments, respectively. They are identical to 'N_SLINE' +but are relocated differently by the linker. They were intended to be +used to describe the source location of a variable declaration, but I +believe that GCC2 actually puts the line number in the desc field of the +stab for the variable itself. GDB has been ignoring these symbols +(unless they contain a string field) since at least GDB 3.5. + + For single source lines that generate discontiguous code, such as +flow of control statements, there may be more than one line number entry +for the same source line. In this case there is a line number entry at +the start of each code range, each with the same line number. + + XCOFF does not use stabs for line numbers. Instead, it uses COFF +line numbers (which are outside the scope of this document). Standard +COFF line numbers cannot deal with include files, but in XCOFF this is +fixed with the 'C_BINCL' method of marking include files (*note Include +Files::). + + +File: stabs.info, Node: Procedures, Next: Nested Procedures, Prev: Line Numbers, Up: Program Structure + +2.5 Procedures +============== + +All of the following stabs normally use the 'N_FUN' symbol type. +However, Sun's 'acc' compiler on SunOS4 uses 'N_GSYM' and 'N_STSYM', +which means that the value of the stab for the function is useless and +the debugger must get the address of the function from the non-stab +symbols instead. On systems where non-stab symbols have leading +underscores, the stabs will lack underscores and the debugger needs to +know about the leading underscore to match up the stab and the non-stab +symbol. BSD Fortran is said to use 'N_FNAME' with the same restriction; +the value of the symbol is not useful (I'm not sure it really does use +this, because GDB doesn't handle this and no one has complained). + + A function is represented by an 'F' symbol descriptor for a global +(extern) function, and 'f' for a static (local) function. For a.out, +the value of the symbol is the address of the start of the function; it +is already relocated. For stabs in ELF, the SunPRO compiler version +2.0.1 and GCC put out an address which gets relocated by the linker. In +a future release SunPRO is planning to put out zero, in which case the +address can be found from the ELF (non-stab) symbol. Because looking +things up in the ELF symbols would probably be slow, I'm not sure how to +find which symbol of that name is the right one, and this doesn't +provide any way to deal with nested functions, it would probably be +better to make the value of the stab an address relative to the start of +the file, or just absolute. See *note ELF Linker Relocation:: for more +information on linker relocation of stabs in ELF files. For XCOFF, the +stab uses the 'C_FUN' storage class and the value of the stab is +meaningless; the address of the function can be found from the csect +symbol (XTY_LD/XMC_PR). + + The type information of the stab represents the return type of the +function; thus 'foo:f5' means that foo is a function returning type 5. +There is no need to try to get the line number of the start of the +function from the stab for the function; it is in the next 'N_SLINE' +symbol. + + Some compilers (such as Sun's Solaris compiler) support an extension +for specifying the types of the arguments. I suspect this extension is +not used for old (non-prototyped) function definitions in C. If the +extension is in use, the type information of the stab for the function +is followed by type information for each argument, with each argument +preceded by ';'. An argument type of 0 means that additional arguments +are being passed, whose types and number may vary ('...' in ANSI C). GDB +has tolerated this extension (parsed the syntax, if not necessarily used +the information) since at least version 4.8; I don't know whether all +versions of dbx tolerate it. The argument types given here are not +redundant with the symbols for the formal parameters (*note +Parameters::); they are the types of the arguments as they are passed, +before any conversions might take place. For example, if a C function +which is declared without a prototype takes a 'float' argument, the +value is passed as a 'double' but then converted to a 'float'. +Debuggers need to use the types given in the arguments when printing +values, but when calling the function they need to use the types given +in the symbol defining the function. + + If the return type and types of arguments of a function which is +defined in another source file are specified (i.e., a function prototype +in ANSI C), traditionally compilers emit no stab; the only way for the +debugger to find the information is if the source file where the +function is defined was also compiled with debugging symbols. As an +extension the Solaris compiler uses symbol descriptor 'P' followed by +the return type of the function, followed by the arguments, each +preceded by ';', as in a stab with symbol descriptor 'f' or 'F'. This +use of symbol descriptor 'P' can be distinguished from its use for +register parameters (*note Register Parameters::) by the fact that it +has symbol type 'N_FUN'. + + The AIX documentation also defines symbol descriptor 'J' as an +internal function. I assume this means a function nested within another +function. It also says symbol descriptor 'm' is a module in Modula-2 or +extended Pascal. + + Procedures (functions which do not return values) are represented as +functions returning the 'void' type in C. I don't see why this couldn't +be used for all languages (inventing a 'void' type for this purpose if +necessary), but the AIX documentation defines 'I', 'P', and 'Q' for +internal, global, and static procedures, respectively. These symbol +descriptors are unusual in that they are not followed by type +information. + + The following example shows a stab for a function 'main' which +returns type number '1'. The '_main' specified for the value is a +reference to an assembler label which is used to fill in the start +address of the function. + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + + The stab representing a procedure is located immediately following +the code of the procedure. This stab is in turn directly followed by a +group of other stabs describing elements of the procedure. These other +stabs describe the procedure's parameters, its block local variables, +and its block structure. + + If functions can appear in different sections, then the debugger may +not be able to find the end of a function. Recent versions of GCC will +mark the end of a function with an 'N_FUN' symbol with an empty string +for the name. The value is the address of the end of the current +function. Without such a symbol, there is no indication of the address +of the end of a function, and you must assume that it ended at the +starting address of the next function or at the end of the text section +for the program. + + +File: stabs.info, Node: Nested Procedures, Next: Block Structure, Prev: Procedures, Up: Program Structure + +2.6 Nested Procedures +===================== + +For any of the symbol descriptors representing procedures, after the +symbol descriptor and the type information is optionally a scope +specifier. This consists of a comma, the name of the procedure, another +comma, and the name of the enclosing procedure. The first name is local +to the scope specified, and seems to be redundant with the name of the +symbol (before the ':'). This feature is used by GCC, and presumably +Pascal, Modula-2, etc., compilers, for nested functions. + + If procedures are nested more than one level deep, only the +immediately containing scope is specified. For example, this code: + + int + foo (int x) + { + int bar (int y) + { + int baz (int z) + { + return x + y + z; + } + return baz (x + 2 * y); + } + return x + bar (3 * x); + } + +produces the stabs: + + .stabs "baz:f1,baz,bar",36,0,0,_baz.15 # 36 is N_FUN + .stabs "bar:f1,bar,foo",36,0,0,_bar.12 + .stabs "foo:F1",36,0,0,_foo + + +File: stabs.info, Node: Block Structure, Next: Alternate Entry Points, Prev: Nested Procedures, Up: Program Structure + +2.7 Block Structure +=================== + +The program's block structure is represented by the 'N_LBRAC' (left +brace) and the 'N_RBRAC' (right brace) stab types. The variables +defined inside a block precede the 'N_LBRAC' symbol for most compilers, +including GCC. Other compilers, such as the Convex, Acorn RISC machine, +and Sun 'acc' compilers, put the variables after the 'N_LBRAC' symbol. +The values of the 'N_LBRAC' and 'N_RBRAC' symbols are the start and end +addresses of the code of the block, respectively. For most machines, +they are relative to the starting address of this source file. For the +Gould NP1, they are absolute. For stabs in sections (*note Stab +Sections::), they are relative to the function in which they occur. + + The 'N_LBRAC' and 'N_RBRAC' stabs that describe the block scope of a +procedure are located after the 'N_FUN' stab that represents the +procedure itself. + + Sun documents the desc field of 'N_LBRAC' and 'N_RBRAC' symbols as +containing the nesting level of the block. However, dbx seems to not +care, and GCC always sets desc to zero. + + For XCOFF, block scope is indicated with 'C_BLOCK' symbols. If the +name of the symbol is '.bb', then it is the beginning of the block; if +the name of the symbol is '.be'; it is the end of the block. + + +File: stabs.info, Node: Alternate Entry Points, Prev: Block Structure, Up: Program Structure + +2.8 Alternate Entry Points +========================== + +Some languages, like Fortran, have the ability to enter procedures at +some place other than the beginning. One can declare an alternate entry +point. The 'N_ENTRY' stab is for this; however, the Sun FORTRAN +compiler doesn't use it. According to AIX documentation, only the name +of a 'C_ENTRY' stab is significant; the address of the alternate entry +point comes from the corresponding external symbol. A previous revision +of this document said that the value of an 'N_ENTRY' stab was the +address of the alternate entry point, but I don't know the source for +that information. + + +File: stabs.info, Node: Constants, Next: Variables, Prev: Program Structure, Up: Top + +3 Constants +*********** + +The 'c' symbol descriptor indicates that this stab represents a +constant. This symbol descriptor is an exception to the general rule +that symbol descriptors are followed by type information. Instead, it +is followed by '=' and one of the following: + +'b VALUE' + Boolean constant. VALUE is a numeric value; I assume it is 0 for + false or 1 for true. + +'c VALUE' + Character constant. VALUE is the numeric value of the constant. + +'e TYPE-INFORMATION , VALUE' + Constant whose value can be represented as integral. + TYPE-INFORMATION is the type of the constant, as it would appear + after a symbol descriptor (*note String Field::). VALUE is the + numeric value of the constant. GDB 4.9 does not actually get the + right value if VALUE does not fit in a host 'int', but it does not + do anything violent, and future debuggers could be extended to + accept integers of any size (whether unsigned or not). This + constant type is usually documented as being only for enumeration + constants, but GDB has never imposed that restriction; I don't know + about other debuggers. + +'i VALUE' + Integer constant. VALUE is the numeric value. The type is some + sort of generic integer type (for GDB, a host 'int'); to specify + the type explicitly, use 'e' instead. + +'r VALUE' + Real constant. VALUE is the real value, which can be 'INF' + (optionally preceded by a sign) for infinity, 'QNAN' for a quiet + NaN (not-a-number), or 'SNAN' for a signalling NaN. If it is a + normal number the format is that accepted by the C library function + 'atof'. + +'s STRING' + String constant. STRING is a string enclosed in either ''' (in + which case ''' characters within the string are represented as '\'' + or '"' (in which case '"' characters within the string are + represented as '\"'). + +'S TYPE-INFORMATION , ELEMENTS , BITS , PATTERN' + Set constant. TYPE-INFORMATION is the type of the constant, as it + would appear after a symbol descriptor (*note String Field::). + ELEMENTS is the number of elements in the set (does this means how + many bits of PATTERN are actually used, which would be redundant + with the type, or perhaps the number of bits set in PATTERN? I + don't get it), BITS is the number of bits in the constant (meaning + it specifies the length of PATTERN, I think), and PATTERN is a + hexadecimal representation of the set. AIX documentation refers to + a limit of 32 bytes, but I see no reason why this limit should + exist. This form could probably be used for arbitrary constants, + not just sets; the only catch is that PATTERN should be understood + to be target, not host, byte order and format. + + The boolean, character, string, and set constants are not supported +by GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error +message and refused to read symbols from the file containing the +constants. + + The above information is followed by ';'. + + +File: stabs.info, Node: Variables, Next: Types, Prev: Constants, Up: Top + +4 Variables +*********** + +Different types of stabs describe the various ways that variables can be +allocated: on the stack, globally, in registers, in common blocks, +statically, or as arguments to a function. + +* Menu: + +* Stack Variables:: Variables allocated on the stack. +* Global Variables:: Variables used by more than one source file. +* Register Variables:: Variables in registers. +* Common Blocks:: Variables statically allocated together. +* Statics:: Variables local to one source file. +* Based Variables:: Fortran pointer based variables. +* Parameters:: Variables for arguments to functions. + + +File: stabs.info, Node: Stack Variables, Next: Global Variables, Up: Variables + +4.1 Automatic Variables Allocated on the Stack +============================================== + +If a variable's scope is local to a function and its lifetime is only as +long as that function executes (C calls such variables "automatic"), it +can be allocated in a register (*note Register Variables::) or on the +stack. + + Each variable allocated on the stack has a stab with the symbol +descriptor omitted. Since type information should begin with a digit, +'-', or '(', only those characters precluded from being used for symbol +descriptors. However, the Acorn RISC machine (ARM) is said to get this +wrong: it puts out a mere type definition here, without the preceding +'TYPE-NUMBER='. This is a bad idea; there is no guarantee that type +descriptors are distinct from symbol descriptors. Stabs for stack +variables use the 'N_LSYM' stab type, or 'C_LSYM' for XCOFF. + + The value of the stab is the offset of the variable within the local +variables. On most machines this is an offset from the frame pointer +and is negative. The location of the stab specifies which block it is +defined in; see *note Block Structure::. + + For example, the following C code: + + int + main () + { + int x; + } + + produces the following stabs: + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + .stabs "x:1",128,0,0,-12 # 128 is N_LSYM + .stabn 192,0,0,LBB2 # 192 is N_LBRAC + .stabn 224,0,0,LBE2 # 224 is N_RBRAC + + See *note Procedures:: for more information on the 'N_FUN' stab, and +*note Block Structure:: for more information on the 'N_LBRAC' and +'N_RBRAC' stabs. + + +File: stabs.info, Node: Global Variables, Next: Register Variables, Prev: Stack Variables, Up: Variables + +4.2 Global Variables +==================== + +A variable whose scope is not specific to just one source file is +represented by the 'G' symbol descriptor. These stabs use the 'N_GSYM' +stab type (C_GSYM for XCOFF). The type information for the stab (*note +String Field::) gives the type of the variable. + + For example, the following source code: + + char g_foo = 'c'; + +yields the following assembly code: + + .stabs "g_foo:G2",32,0,0,0 # 32 is N_GSYM + .global _g_foo + .data + _g_foo: + .byte 99 + + The address of the variable represented by the 'N_GSYM' is not +contained in the 'N_GSYM' stab. The debugger gets this information from +the external symbol for the global variable. In the example above, the +'.global _g_foo' and '_g_foo:' lines tell the assembler to produce an +external symbol. + + Some compilers, like GCC, output 'N_GSYM' stabs only once, where the +variable is defined. Other compilers, like SunOS4 /bin/cc, output a +'N_GSYM' stab for each compilation unit which references the variable. + + +File: stabs.info, Node: Register Variables, Next: Common Blocks, Prev: Global Variables, Up: Variables + +4.3 Register Variables +====================== + +Register variables have their own stab type, 'N_RSYM' ('C_RSYM' for +XCOFF), and their own symbol descriptor, 'r'. The stab's value is the +number of the register where the variable data will be stored. + + AIX defines a separate symbol descriptor 'd' for floating point +registers. This seems unnecessary; why not just just give floating +point registers different register numbers? I have not verified whether +the compiler actually uses 'd'. + + If the register is explicitly allocated to a global variable, but not +initialized, as in: + + register int g_bar asm ("%g5"); + +then the stab may be emitted at the end of the object file, with the +other bss symbols. + + +File: stabs.info, Node: Common Blocks, Next: Statics, Prev: Register Variables, Up: Variables + +4.4 Common Blocks +================= + +A common block is a statically allocated section of memory which can be +referred to by several source files. It may contain several variables. +I believe Fortran is the only language with this feature. + + A 'N_BCOMM' stab begins a common block and an 'N_ECOMM' stab ends it. +The only field that is significant in these two stabs is the string, +which names a normal (non-debugging) symbol that gives the address of +the common block. According to IBM documentation, only the 'N_BCOMM' +has the name of the common block (even though their compiler actually +puts it both places). + + The stabs for the members of the common block are between the +'N_BCOMM' and the 'N_ECOMM'; the value of each stab is the offset within +the common block of that variable. IBM uses the 'C_ECOML' stab type, +and there is a corresponding 'N_ECOML' stab type, but Sun's Fortran +compiler uses 'N_GSYM' instead. The variables within a common block use +the 'V' symbol descriptor (I believe this is true of all Fortran +variables). Other stabs (at least type declarations using 'C_DECL') can +also be between the 'N_BCOMM' and the 'N_ECOMM'. + + +File: stabs.info, Node: Statics, Next: Based Variables, Prev: Common Blocks, Up: Variables + +4.5 Static Variables +==================== + +Initialized static variables are represented by the 'S' and 'V' symbol +descriptors. 'S' means file scope static, and 'V' means procedure scope +static. One exception: in XCOFF, IBM's xlc compiler always uses 'V', +and whether it is file scope or not is distinguished by whether the stab +is located within a function. + + In a.out files, 'N_STSYM' means the data section, 'N_FUN' means the +text section, and 'N_LCSYM' means the bss section. For those systems +with a read-only data section separate from the text section (Solaris), +'N_ROSYM' means the read-only data section. + + For example, the source lines: + + static const int var_const = 5; + static int var_init = 2; + static int var_noinit; + +yield the following stabs: + + .stabs "var_const:S1",36,0,0,_var_const # 36 is N_FUN + ... + .stabs "var_init:S1",38,0,0,_var_init # 38 is N_STSYM + ... + .stabs "var_noinit:S1",40,0,0,_var_noinit # 40 is N_LCSYM + + In XCOFF files, the stab type need not indicate the section; +'C_STSYM' can be used for all statics. Also, each static variable is +enclosed in a static block. A 'C_BSTAT' (emitted with a '.bs' assembler +directive) symbol begins the static block; its value is the symbol +number of the csect symbol whose value is the address of the static +block, its section is the section of the variables in that static block, +and its name is '.bs'. A 'C_ESTAT' (emitted with a '.es' assembler +directive) symbol ends the static block; its name is '.es' and its value +and section are ignored. + + In ECOFF files, the storage class is used to specify the section, so +the stab type need not indicate the section. + + In ELF files, for the SunPRO compiler version 2.0.1, symbol +descriptor 'S' means that the address is absolute (the linker relocates +it) and symbol descriptor 'V' means that the address is relative to the +start of the relevant section for that compilation unit. SunPRO has +plans to have the linker stop relocating stabs; I suspect that their the +debugger gets the address from the corresponding ELF (not stab) symbol. +I'm not sure how to find which symbol of that name is the right one. +The clean way to do all this would be to have the value of a symbol +descriptor 'S' symbol be an offset relative to the start of the file, +just like everything else, but that introduces obvious compatibility +problems. For more information on linker stab relocation, *Note ELF +Linker Relocation::. + + +File: stabs.info, Node: Based Variables, Next: Parameters, Prev: Statics, Up: Variables + +4.6 Fortran Based Variables +=========================== + +Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature +which allows allocating arrays with 'malloc', but which avoids blurring +the line between arrays and pointers the way that C does. In stabs such +a variable uses the 'b' symbol descriptor. + + For example, the Fortran declarations + + real foo, foo10(10), foo10_5(10,5) + pointer (foop, foo) + pointer (foo10p, foo10) + pointer (foo105p, foo10_5) + + produce the stabs + + foo:b6 + foo10:bar3;1;10;6 + foo10_5:bar3;1;5;ar3;1;10;6 + + In this example, 'real' is type 6 and type 3 is an integral type +which is the type of the subscripts of the array (probably 'integer'). + + The 'b' symbol descriptor is like 'V' in that it denotes a statically +allocated symbol whose scope is local to a function; see *Note +Statics::. The value of the symbol, instead of being the address of the +variable itself, is the address of a pointer to that variable. So in +the above example, the value of the 'foo' stab is the address of a +pointer to a real, the value of the 'foo10' stab is the address of a +pointer to a 10-element array of reals, and the value of the 'foo10_5' +stab is the address of a pointer to a 5-element array of 10-element +arrays of reals. + + +File: stabs.info, Node: Parameters, Prev: Based Variables, Up: Variables + +4.7 Parameters +============== + +Formal parameters to a function are represented by a stab (or sometimes +two; see below) for each parameter. The stabs are in the order in which +the debugger should print the parameters (i.e., the order in which the +parameters are declared in the source file). The exact form of the stab +depends on how the parameter is being passed. + + Parameters passed on the stack use the symbol descriptor 'p' and the +'N_PSYM' symbol type (or 'C_PSYM' for XCOFF). The value of the symbol is +an offset used to locate the parameter on the stack; its exact meaning +is machine-dependent, but on most machines it is an offset from the +frame pointer. + + As a simple example, the code: + + main (argc, argv) + int argc; + char **argv; + + produces the stabs: + + .stabs "main:F1",36,0,0,_main # 36 is N_FUN + .stabs "argc:p1",160,0,0,68 # 160 is N_PSYM + .stabs "argv:p20=*21=*2",160,0,0,72 + + The type definition of 'argv' is interesting because it contains +several type definitions. Type 21 is pointer to type 2 (char) and +'argv' (type 20) is pointer to type 21. + + The following symbol descriptors are also said to go with 'N_PSYM'. +The value of the symbol is said to be an offset from the argument +pointer (I'm not sure whether this is true or not). + + pP (<>) + pF Fortran function parameter + X (function result variable) + +* Menu: + +* Register Parameters:: +* Local Variable Parameters:: +* Reference Parameters:: +* Conformant Arrays:: + + +File: stabs.info, Node: Register Parameters, Next: Local Variable Parameters, Up: Parameters + +4.7.1 Passing Parameters in Registers +------------------------------------- + +If the parameter is passed in a register, then traditionally there are +two symbols for each argument: + + .stabs "arg:p1" . . . ; N_PSYM + .stabs "arg:r1" . . . ; N_RSYM + + Debuggers use the second one to find the value, and the first one to +know that it is an argument. + + Because that approach is kind of ugly, some compilers use symbol +descriptor 'P' or 'R' to indicate an argument which is in a register. +Symbol type 'C_RPSYM' is used in XCOFF and 'N_RSYM' is used otherwise. +The symbol's value is the register number. 'P' and 'R' mean the same +thing; the difference is that 'P' is a GNU invention and 'R' is an IBM +(XCOFF) invention. As of version 4.9, GDB should handle either one. + + There is at least one case where GCC uses a 'p' and 'r' pair rather +than 'P'; this is where the argument is passed in the argument list and +then loaded into a register. + + According to the AIX documentation, symbol descriptor 'D' is for a +parameter passed in a floating point register. This seems +unnecessary--why not just use 'R' with a register number which indicates +that it's a floating point register? I haven't verified whether the +system actually does what the documentation indicates. + + On the sparc and hppa, for a 'P' symbol whose type is a structure or +union, the register contains the address of the structure. On the +sparc, this is also true of a 'p' and 'r' pair (using Sun 'cc') or a 'p' +symbol. However, if a (small) structure is really in a register, 'r' is +used. And, to top it all off, on the hppa it might be a structure which +was passed on the stack and loaded into a register and for which there +is a 'p' and 'r' pair! I believe that symbol descriptor 'i' is supposed +to deal with this case (it is said to mean "value parameter by +reference, indirect access"; I don't know the source for this +information), but I don't know details or what compilers or debuggers +use it, if any (not GDB or GCC). It is not clear to me whether this case +needs to be dealt with differently than parameters passed by reference +(*note Reference Parameters::). + + +File: stabs.info, Node: Local Variable Parameters, Next: Reference Parameters, Prev: Register Parameters, Up: Parameters + +4.7.2 Storing Parameters as Local Variables +------------------------------------------- + +There is a case similar to an argument in a register, which is an +argument that is actually stored as a local variable. Sometimes this +happens when the argument was passed in a register and then the compiler +stores it as a local variable. If possible, the compiler should claim +that it's in a register, but this isn't always done. + + If a parameter is passed as one type and converted to a smaller type +by the prologue (for example, the parameter is declared as a 'float', +but the calling conventions specify that it is passed as a 'double'), +then GCC2 (sometimes) uses a pair of symbols. The first symbol uses +symbol descriptor 'p' and the type which is passed. The second symbol +has the type and location which the parameter actually has after the +prologue. For example, suppose the following C code appears with no +prototypes involved: + + void + subr (f) + float f; + { + + if 'f' is passed as a double at stack offset 8, and the prologue +converts it to a float in register number 0, then the stabs look like: + + .stabs "f:p13",160,0,3,8 # 160 is 'N_PSYM', here 13 is 'double' + .stabs "f:r12",64,0,3,0 # 64 is 'N_RSYM', here 12 is 'float' + + In both stabs 3 is the line number where 'f' is declared (*note Line +Numbers::). + + GCC, at least on the 960, has another solution to the same problem. +It uses a single 'p' symbol descriptor for an argument which is stored +as a local variable but uses 'N_LSYM' instead of 'N_PSYM'. In this +case, the value of the symbol is an offset relative to the local +variables for that function, not relative to the arguments; on some +machines those are the same thing, but not on all. + + On the VAX or on other machines in which the calling convention +includes the number of words of arguments actually passed, the debugger +(GDB at least) uses the parameter symbols to keep track of whether it +needs to print nameless arguments in addition to the formal parameters +which it has printed because each one has a stab. For example, in + + extern int fprintf (FILE *stream, char *format, ...); + ... + fprintf (stdout, "%d\n", x); + + there are stabs for 'stream' and 'format'. On most machines, the +debugger can only print those two arguments (because it has no way of +knowing that additional arguments were passed), but on the VAX or other +machines with a calling convention which indicates the number of words +of arguments, the debugger can print all three arguments. To do so, the +parameter symbol (symbol descriptor 'p') (not necessarily 'r' or symbol +descriptor omitted symbols) needs to contain the actual type as passed +(for example, 'double' not 'float' if it is passed as a double and +converted to a float). + + +File: stabs.info, Node: Reference Parameters, Next: Conformant Arrays, Prev: Local Variable Parameters, Up: Parameters + +4.7.3 Passing Parameters by Reference +------------------------------------- + +If the parameter is passed by reference (e.g., Pascal 'VAR' parameters), +then the symbol descriptor is 'v' if it is in the argument list, or 'a' +if it in a register. Other than the fact that these contain the address +of the parameter rather than the parameter itself, they are identical to +'p' and 'R', respectively. I believe 'a' is an AIX invention; 'v' is +supported by all stabs-using systems as far as I know. + + +File: stabs.info, Node: Conformant Arrays, Prev: Reference Parameters, Up: Parameters + +4.7.4 Passing Conformant Array Parameters +----------------------------------------- + +Conformant arrays are a feature of Modula-2, and perhaps other +languages, in which the size of an array parameter is not known to the +called function until run-time. Such parameters have two stabs: a 'x' +for the array itself, and a 'C', which represents the size of the array. +The value of the 'x' stab is the offset in the argument list where the +address of the array is stored (it this right? it is a guess); the +value of the 'C' stab is the offset in the argument list where the size +of the array (in elements? in bytes?) is stored. + + +File: stabs.info, Node: Types, Next: Macro define and undefine, Prev: Variables, Up: Top + +5 Defining Types +**************** + +The examples so far have described types as references to previously +defined types, or defined in terms of subranges of or pointers to +previously defined types. This chapter describes the other type +descriptors that may follow the '=' in a type definition. + +* Menu: + +* Builtin Types:: Integers, floating point, void, etc. +* Miscellaneous Types:: Pointers, sets, files, etc. +* Cross-References:: Referring to a type not yet defined. +* Subranges:: A type with a specific range. +* Arrays:: An aggregate type of same-typed elements. +* Strings:: Like an array but also has a length. +* Enumerations:: Like an integer but the values have names. +* Structures:: An aggregate type of different-typed elements. +* Typedefs:: Giving a type a name. +* Unions:: Different types sharing storage. +* Function Types:: + + +File: stabs.info, Node: Builtin Types, Next: Miscellaneous Types, Up: Types + +5.1 Builtin Types +================= + +Certain types are built in ('int', 'short', 'void', 'float', etc.); the +debugger recognizes these types and knows how to handle them. Thus, +don't be surprised if some of the following ways of specifying builtin +types do not specify everything that a debugger would need to know about +the type--in some cases they merely specify enough information to +distinguish the type from other types. + + The traditional way to define builtin types is convoluted, so new +ways have been invented to describe them. Sun's 'acc' uses special +builtin type descriptors ('b' and 'R'), and IBM uses negative type +numbers. GDB accepts all three ways, as of version 4.8; dbx just +accepts the traditional builtin types and perhaps one of the other two +formats. The following sections describe each of these formats. + +* Menu: + +* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery +* Builtin Type Descriptors:: Builtin types with special type descriptors +* Negative Type Numbers:: Builtin types using negative type numbers + + +File: stabs.info, Node: Traditional Builtin Types, Next: Builtin Type Descriptors, Up: Builtin Types + +5.1.1 Traditional Builtin Types +------------------------------- + +This is the traditional, convoluted method for defining builtin types. +There are several classes of such type definitions: integer, floating +point, and 'void'. + +* Menu: + +* Traditional Integer Types:: +* Traditional Other Types:: + + +File: stabs.info, Node: Traditional Integer Types, Next: Traditional Other Types, Up: Traditional Builtin Types + +5.1.1.1 Traditional Integer Types +................................. + +Often types are defined as subranges of themselves. If the bounding +values fit within an 'int', then they are given normally. For example: + + .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # 128 is N_LSYM + .stabs "char:t2=r2;0;127;",128,0,0,0 + + Builtin types can also be described as subranges of 'int': + + .stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 + + If the lower bound of a subrange is 0 and the upper bound is -1, the +type is an unsigned integral type whose bounds are too big to describe +in an 'int'. Traditionally this is only used for 'unsigned int' and +'unsigned long': + + .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 + + For larger types, GCC 2.4.5 puts out bounds in octal, with one or +more leading zeroes. In this case a negative bound consists of a number +which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in +the number (except the sign bit), and a positive bound is one which is a +1 bit for each bit in the number (except possibly the sign bit). All +known versions of dbx and GDB version 4 accept this (at least in the +sense of not refusing to process the file), but GDB 3.5 refuses to read +the whole file containing such symbols. So GCC 2.3.3 did not output the +proper size for these types. As an example of octal bounds, the string +fields of the stabs for 64 bit integer types look like: + + long int:t3=r1;001000000000000000000000;000777777777777777777777; + long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; + + If the lower bound of a subrange is 0 and the upper bound is +negative, the type is an unsigned integral type whose size in bytes is +the absolute value of the upper bound. I believe this is a Convex +convention for 'unsigned long long'. + + If the lower bound of a subrange is negative and the upper bound is +0, the type is a signed integral type whose size in bytes is the +absolute value of the lower bound. I believe this is a Convex +convention for 'long long'. To distinguish this from a legitimate +subrange, the type should be a subrange of itself. I'm not sure whether +this is the case for Convex. + + +File: stabs.info, Node: Traditional Other Types, Prev: Traditional Integer Types, Up: Traditional Builtin Types + +5.1.1.2 Traditional Other Types +............................... + +If the upper bound of a subrange is 0 and the lower bound is positive, +the type is a floating point type, and the lower bound of the subrange +indicates the number of bytes in the type: + + .stabs "float:t12=r1;4;0;",128,0,0,0 + .stabs "double:t13=r1;8;0;",128,0,0,0 + + However, GCC writes 'long double' the same way it writes 'double', so +there is no way to distinguish. + + .stabs "long double:t14=r1;8;0;",128,0,0,0 + + Complex types are defined the same way as floating-point types; there +is no way to distinguish a single-precision complex from a +double-precision floating-point type. + + The C 'void' type is defined as itself: + + .stabs "void:t15=15",128,0,0,0 + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Builtin Type Descriptors, Next: Negative Type Numbers, Prev: Traditional Builtin Types, Up: Builtin Types + +5.1.2 Defining Builtin Types Using Builtin Type Descriptors +----------------------------------------------------------- + +This is the method used by Sun's 'acc' for defining builtin types. +These are the type descriptors to define builtin types: + +'b SIGNED CHAR-FLAG WIDTH ; OFFSET ; NBITS ;' + Define an integral type. SIGNED is 'u' for unsigned or 's' for + signed. CHAR-FLAG is 'c' which indicates this is a character type, + or is omitted. I assume this is to distinguish an integral type + from a character type of the same size, for example it might make + sense to set it for the C type 'wchar_t' so the debugger can print + such variables differently (Solaris does not do this). Sun sets it + on the C types 'signed char' and 'unsigned char' which arguably is + wrong. WIDTH and OFFSET appear to be for small objects stored in + larger ones, for example a 'short' in an 'int' register. WIDTH is + normally the number of bytes in the type. OFFSET seems to always + be zero. NBITS is the number of bits in the type. + + Note that type descriptor 'b' used for builtin types conflicts with + its use for Pascal space types (*note Miscellaneous Types::); they + can be distinguished because the character following the type + descriptor will be a digit, '(', or '-' for a Pascal space type, or + 'u' or 's' for a builtin type. + +'w' + Documented by AIX to define a wide character type, but their + compiler actually uses negative type numbers (*note Negative Type + Numbers::). + +'R FP-TYPE ; BYTES ;' + Define a floating point type. FP-TYPE has one of the following + values: + + '1 (NF_SINGLE)' + IEEE 32-bit (single precision) floating point format. + + '2 (NF_DOUBLE)' + IEEE 64-bit (double precision) floating point format. + + '3 (NF_COMPLEX)' + '4 (NF_COMPLEX16)' + '5 (NF_COMPLEX32)' + These are for complex numbers. A comment in the GDB source + describes them as Fortran 'complex', 'double complex', and + 'complex*16', respectively, but what does that mean? (i.e., + Single precision? Double precision?). + + '6 (NF_LDOUBLE)' + Long double. This should probably only be used for Sun format + 'long double', and new codes should be used for other floating + point formats ('NF_DOUBLE' can be used if a 'long double' is + really just an IEEE double, of course). + + BYTES is the number of bytes occupied by the type. This allows a + debugger to perform some operations with the type even if it + doesn't understand FP-TYPE. + +'g TYPE-INFORMATION ; NBITS' + Documented by AIX to define a floating type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::). + +'c TYPE-INFORMATION ; NBITS' + Documented by AIX to define a complex type, but their compiler + actually uses negative type numbers (*note Negative Type + Numbers::). + + The C 'void' type is defined as a signed integral type 0 bits long: + .stabs "void:t19=bs0;0;0",128,0,0,0 + The Solaris compiler seems to omit the trailing semicolon in this +case. Getting sloppy in this way is not a swift move because if a type +is embedded in a more complex expression it is necessary to be able to +tell where it ends. + + I'm not sure how a boolean type is represented. + + +File: stabs.info, Node: Negative Type Numbers, Prev: Builtin Type Descriptors, Up: Builtin Types + +5.1.3 Negative Type Numbers +--------------------------- + +This is the method used in XCOFF for defining builtin types. Since the +debugger knows about the builtin types anyway, the idea of negative type +numbers is simply to give a special type number which indicates the +builtin type. There is no stab defining these types. + + There are several subtle issues with negative type numbers. + + One is the size of the type. A builtin type (for example the C types +'int' or 'long') might have different sizes depending on compiler +options, the target architecture, the ABI, etc. This issue doesn't come +up for IBM tools since (so far) they just target the RS/6000; the sizes +indicated below for each size are what the IBM RS/6000 tools use. To +deal with differing sizes, either define separate negative type numbers +for each size (which works but requires changing the debugger, and, +unless you get both AIX dbx and GDB to accept the change, introduces an +incompatibility), or use a type attribute (*note String Field::) to +define a new type with the appropriate size (which merely requires a +debugger which understands type attributes, like AIX dbx or GDB). For +example, + + .stabs "boolean:t10=@s8;-16",128,0,0,0 + + defines an 8-bit boolean type, and + + .stabs "boolean:t10=@s64;-16",128,0,0,0 + + defines a 64-bit boolean type. + + A similar issue is the format of the type. This comes up most often +for floating-point types, which could have various formats (particularly +extended doubles, which vary quite a bit even among IEEE systems). +Again, it is best to define a new negative type number for each +different format; changing the format based on the target system has +various problems. One such problem is that the Alpha has both VAX and +IEEE floating types. One can easily imagine one library using the VAX +types and another library in the same executable using the IEEE types. +Another example is that the interpretation of whether a boolean is true +or false can be based on the least significant bit, most significant +bit, whether it is zero, etc., and different compilers (or different +options to the same compiler) might provide different kinds of boolean. + + The last major issue is the names of the types. The name of a given +type depends _only_ on the negative type number given; these do not vary +depending on the language, the target system, or anything else. One can +always define separate type numbers--in the following list you will see +for example separate 'int' and 'integer*4' types which are identical +except for the name. But compatibility can be maintained by not +inventing new negative type numbers and instead just defining a new type +with a new name. For example: + + .stabs "CARDINAL:t10=-8",128,0,0,0 + + Here is the list of negative type numbers. The phrase "integral +type" is used to mean twos-complement (I strongly suspect that all +machines which use stabs use twos-complement; most machines use +twos-complement these days). + +'-1' + 'int', 32 bit signed integral type. + +'-2' + 'char', 8 bit type holding a character. Both GDB and dbx on AIX + treat this as signed. GCC uses this type whether 'char' is signed + or not, which seems like a bad idea. The AIX compiler ('xlc') + seems to avoid this type; it uses -5 instead for 'char'. + +'-3' + 'short', 16 bit signed integral type. + +'-4' + 'long', 32 bit signed integral type. + +'-5' + 'unsigned char', 8 bit unsigned integral type. + +'-6' + 'signed char', 8 bit signed integral type. + +'-7' + 'unsigned short', 16 bit unsigned integral type. + +'-8' + 'unsigned int', 32 bit unsigned integral type. + +'-9' + 'unsigned', 32 bit unsigned integral type. + +'-10' + 'unsigned long', 32 bit unsigned integral type. + +'-11' + 'void', type indicating the lack of a value. + +'-12' + 'float', IEEE single precision. + +'-13' + 'double', IEEE double precision. + +'-14' + 'long double', IEEE double precision. The compiler claims the size + will increase in a future release, and for binary compatibility you + have to avoid using 'long double'. I hope when they increase it + they use a new negative type number. + +'-15' + 'integer'. 32 bit signed integral type. + +'-16' + 'boolean'. 32 bit type. GDB and GCC assume that zero is false, + one is true, and other values have unspecified meaning. I hope + this agrees with how the IBM tools use the type. + +'-17' + 'short real'. IEEE single precision. + +'-18' + 'real'. IEEE double precision. + +'-19' + 'stringptr'. *Note Strings::. + +'-20' + 'character', 8 bit unsigned character type. + +'-21' + 'logical*1', 8 bit type. This Fortran type has a split personality + in that it is used for boolean variables, but can also be used for + unsigned integers. 0 is false, 1 is true, and other values are + non-boolean. + +'-22' + 'logical*2', 16 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +'-23' + 'logical*4', 32 bit type. This Fortran type has a split + personality in that it is used for boolean variables, but can also + be used for unsigned integers. 0 is false, 1 is true, and other + values are non-boolean. + +'-24' + 'logical', 32 bit type. This Fortran type has a split personality + in that it is used for boolean variables, but can also be used for + unsigned integers. 0 is false, 1 is true, and other values are + non-boolean. + +'-25' + 'complex'. A complex type consisting of two IEEE single-precision + floating point values. + +'-26' + 'complex'. A complex type consisting of two IEEE double-precision + floating point values. + +'-27' + 'integer*1', 8 bit signed integral type. + +'-28' + 'integer*2', 16 bit signed integral type. + +'-29' + 'integer*4', 32 bit signed integral type. + +'-30' + 'wchar'. Wide character, 16 bits wide, unsigned (what format? + Unicode?). + +'-31' + 'long long', 64 bit signed integral type. + +'-32' + 'unsigned long long', 64 bit unsigned integral type. + +'-33' + 'logical*8', 64 bit unsigned integral type. + +'-34' + 'integer*8', 64 bit signed integral type. + + +File: stabs.info, Node: Miscellaneous Types, Next: Cross-References, Prev: Builtin Types, Up: Types + +5.2 Miscellaneous Types +======================= + +'b TYPE-INFORMATION ; BYTES' + Pascal space type. This is documented by IBM; what does it mean? + + This use of the 'b' type descriptor can be distinguished from its + use for builtin integral types (*note Builtin Type Descriptors::) + because the character following the type descriptor is always a + digit, '(', or '-'. + +'B TYPE-INFORMATION' + A volatile-qualified version of TYPE-INFORMATION. This is a Sun + extension. References and stores to a variable with a + volatile-qualified type must not be optimized or cached; they must + occur as the user specifies them. + +'d TYPE-INFORMATION' + File of type TYPE-INFORMATION. As far as I know this is only used + by Pascal. + +'k TYPE-INFORMATION' + A const-qualified version of TYPE-INFORMATION. This is a Sun + extension. A variable with a const-qualified type cannot be + modified. + +'M TYPE-INFORMATION ; LENGTH' + Multiple instance type. The type seems to composed of LENGTH + repetitions of TYPE-INFORMATION, for example 'character*3' is + represented by 'M-2;3', where '-2' is a reference to a character + type (*note Negative Type Numbers::). I'm not sure how this + differs from an array. This appears to be a Fortran feature. + LENGTH is a bound, like those in range types; see *note + Subranges::. + +'S TYPE-INFORMATION' + Pascal set type. TYPE-INFORMATION must be a small type such as an + enumeration or a subrange, and the type is a bitmask whose length + is specified by the number of elements in TYPE-INFORMATION. + + In CHILL, if it is a bitstring instead of a set, also use the 'S' + type attribute (*note String Field::). + +'* TYPE-INFORMATION' + Pointer to TYPE-INFORMATION. + + +File: stabs.info, Node: Cross-References, Next: Subranges, Prev: Miscellaneous Types, Up: Types + +5.3 Cross-References to Other Types +=================================== + +A type can be used before it is defined; one common way to deal with +that situation is just to use a type reference to a type which has not +yet been defined. + + Another way is with the 'x' type descriptor, which is followed by 's' +for a structure tag, 'u' for a union tag, or 'e' for a enumerator tag, +followed by the name of the tag, followed by ':'. If the name contains +'::' between a '<' and '>' pair (for C++ templates), such a '::' does +not end the name--only a single ':' ends the name; see *note Nested +Symbols::. + + For example, the following C declarations: + + struct foo; + struct foo *bar; + +produce: + + .stabs "bar:G16=*17=xsfoo:",32,0,0,0 + + Not all debuggers support the 'x' type descriptor, so on some +machines GCC does not use it. I believe that for the above example it +would just emit a reference to type 17 and never define it, but I +haven't verified that. + + Modula-2 imported types, at least on AIX, use the 'i' type +descriptor, which is followed by the name of the module from which the +type is imported, followed by ':', followed by the name of the type. +There is then optionally a comma followed by type information for the +type. This differs from merely naming the type (*note Typedefs::) in +that it identifies the module; I don't understand whether the name of +the type given here is always just the same as the name we are giving +it, or whether this type descriptor is used with a nameless stab (*note +String Field::), or what. The symbol ends with ';'. + + +File: stabs.info, Node: Subranges, Next: Arrays, Prev: Cross-References, Up: Types + +5.4 Subrange Types +================== + +The 'r' type descriptor defines a type as a subrange of another type. +It is followed by type information for the type of which it is a +subrange, a semicolon, an integral lower bound, a semicolon, an integral +upper bound, and a semicolon. The AIX documentation does not specify +the trailing semicolon, in an effort to specify array indexes more +cleanly, but a subrange which is not an array index has always included +a trailing semicolon (*note Arrays::). + + Instead of an integer, either bound can be one of the following: + +'A OFFSET' + The bound is passed by reference on the stack at offset OFFSET from + the argument list. *Note Parameters::, for more information on + such offsets. + +'T OFFSET' + The bound is passed by value on the stack at offset OFFSET from the + argument list. + +'a REGISTER-NUMBER' + The bound is passed by reference in register number + REGISTER-NUMBER. + +'t REGISTER-NUMBER' + The bound is passed by value in register number REGISTER-NUMBER. + +'J' + There is no bound. + + Subranges are also used for builtin types; see *note Traditional +Builtin Types::. + + +File: stabs.info, Node: Arrays, Next: Strings, Prev: Subranges, Up: Types + +5.5 Array Types +=============== + +Arrays use the 'a' type descriptor. Following the type descriptor is +the type of the index and the type of the array elements. If the index +type is a range type, it ends in a semicolon; otherwise (for example, if +it is a type reference), there does not appear to be any way to tell +where the types are separated. In an effort to clean up this mess, IBM +documents the two types as being separated by a semicolon, and a range +type as not ending in a semicolon (but this is not right for range types +which are not array indexes, *note Subranges::). I think probably the +best solution is to specify that a semicolon ends a range type, and that +the index type and element type of an array are separated by a +semicolon, but that if the index type is a range type, the extra +semicolon can be omitted. GDB (at least through version 4.9) doesn't +support any kind of index type other than a range anyway; I'm not sure +about dbx. + + It is well established, and widely used, that the type of the index, +unlike most types found in the stabs, is merely a type definition, not +type information (*note String Field::) (that is, it need not start with +'TYPE-NUMBER=' if it is defining a new type). According to a comment in +GDB, this is also true of the type of the array elements; it gives +'ar1;1;10;ar1;1;10;4' as a legitimate way to express a two dimensional +array. According to AIX documentation, the element type must be type +information. GDB accepts either. + + The type of the index is often a range type, expressed as the type +descriptor 'r' and some parameters. It defines the size of the array. +In the example below, the range 'r1;0;2;' defines an index type which is +a subrange of type 1 (integer), with a lower bound of 0 and an upper +bound of 2. This defines the valid range of subscripts of a +three-element C array. + + For example, the definition: + + char char_vec[3] = {'a','b','c'}; + +produces the output: + + .stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 + .global _char_vec + .align 4 + _char_vec: + .byte 97 + .byte 98 + .byte 99 + + If an array is "packed", the elements are spaced more closely than +normal, saving memory at the expense of speed. For example, an array of +3-byte objects might, if unpacked, have each element aligned on a 4-byte +boundary, but if packed, have no padding. One way to specify that +something is packed is with type attributes (*note String Field::). In +the case of arrays, another is to use the 'P' type descriptor instead of +'a'. Other than specifying a packed array, 'P' is identical to 'a'. + + An open array is represented by the 'A' type descriptor followed by +type information specifying the type of the array elements. + + An N-dimensional dynamic array is represented by + + D DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + A subarray of an N-dimensional array is represented by + + E DIMENSIONS ; TYPE-INFORMATION + + DIMENSIONS is the number of dimensions; TYPE-INFORMATION specifies +the type of the array elements. + + +File: stabs.info, Node: Strings, Next: Enumerations, Prev: Arrays, Up: Types + +5.6 Strings +=========== + +Some languages, like C or the original Pascal, do not have string types, +they just have related things like arrays of characters. But most +Pascals and various other languages have string types, which are +indicated as follows: + +'n TYPE-INFORMATION ; BYTES' + BYTES is the maximum length. I'm not sure what TYPE-INFORMATION + is; I suspect that it means that this is a string of + TYPE-INFORMATION (thus allowing a string of integers, a string of + wide characters, etc., as well as a string of characters). Not + sure what the format of this type is. This is an AIX feature. + +'z TYPE-INFORMATION ; BYTES' + Just like 'n' except that this is a gstring, not an ordinary + string. I don't know the difference. + +'N' + Pascal Stringptr. What is this? This is an AIX feature. + + Languages, such as CHILL which have a string type which is basically +just an array of characters use the 'S' type attribute (*note String +Field::). + + +File: stabs.info, Node: Enumerations, Next: Structures, Prev: Strings, Up: Types + +5.7 Enumerations +================ + +Enumerations are defined with the 'e' type descriptor. + + The source line below declares an enumeration type at file scope. +The type definition is located after the 'N_RBRAC' that marks the end of +the previous procedure's block scope, and before the 'N_FUN' that marks +the beginning of the next procedure's block scope. Therefore it does +not describe a block local symbol, but a file local one. + + The source line: + + enum e_places {first,second=3,last}; + +generates the following stab: + + .stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 + + The symbol descriptor ('T') says that the stab describes a structure, +enumeration, or union tag. The type descriptor 'e', following the '22=' +of the type definition narrows it down to an enumeration type. +Following the 'e' is a list of the elements of the enumeration. The +format is 'NAME:VALUE,'. The list of elements ends with ';'. The fact +that VALUE is specified as an integer can cause problems if the value is +large. GCC 2.5.2 tries to output it in octal in that case with a +leading zero, which is probably a good thing, although GDB 4.11 supports +octal only in cases where decimal is perfectly good. Negative decimal +values are supported by both GDB and dbx. + + There is no standard way to specify the size of an enumeration type; +it is determined by the architecture (normally all enumerations types +are 32 bits). Type attributes can be used to specify an enumeration +type of another size for debuggers which support them; see *note String +Field::. + + Enumeration types are unusual in that they define symbols for the +enumeration values ('first', 'second', and 'third' in the above +example), and even though these symbols are visible in the file as a +whole (rather than being in a more local namespace like structure member +names), they are defined in the type definition for the enumeration type +rather than each having their own symbol. In order to be fast, GDB will +only get symbols from such types (in its initial scan of the stabs) if +the type is the first thing defined after a 'T' or 't' symbol descriptor +(the above example fulfills this requirement). If the type does not +have a name, the compiler should emit it in a nameless stab (*note +String Field::); GCC does this. + + +File: stabs.info, Node: Structures, Next: Typedefs, Prev: Enumerations, Up: Types + +5.8 Structures +============== + +The encoding of structures in stabs can be shown with an example. + + The following source code declares a structure tag and defines an +instance of the structure in global scope. Then a 'typedef' equates the +structure tag with a new type. Separate stabs are generated for the +structure tag, the structure 'typedef', and the structure instance. The +stabs for the tag and the 'typedef' are emitted when the definitions are +encountered. Since the structure elements are not initialized, the stab +and code for the structure variable itself is located at the end of the +program in the bss section. + + struct s_tag { + int s_int; + float s_float; + char s_char_vec[8]; + struct s_tag* s_next; + } g_an_s; + + typedef struct s_tag s_typedef; + + The structure tag has an 'N_LSYM' stab type because, like the +enumeration, the symbol has file scope. Like the enumeration, the +symbol descriptor is 'T', for enumeration, structure, or tag type. The +type descriptor 's' following the '16=' of the type definition narrows +the symbol type to structure. + + Following the 's' type descriptor is the number of bytes the +structure occupies, followed by a description of each structure element. +The structure element descriptions are of the form 'NAME:TYPE, BIT +OFFSET FROM THE START OF THE STRUCT, NUMBER OF BITS IN THE ELEMENT'. + + # 128 is N_LSYM + .stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; + s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 + + In this example, the first two structure elements are previously +defined types. For these, the type following the 'NAME:' part of the +element description is a simple type reference. The other two structure +elements are new types. In this case there is a type definition +embedded after the 'NAME:'. The type definition for the array element +looks just like a type definition for a stand-alone array. The 's_next' +field is a pointer to the same kind of structure that the field is an +element of. So the definition of structure type 16 contains a type +definition for an element which is a pointer to type 16. + + If a field is a static member (this is a C++ feature in which a +single variable appears to be a field of every structure of a given +type) it still starts out with the field name, a colon, and the type, +but then instead of a comma, bit position, comma, and bit size, there is +a colon followed by the name of the variable which each such field +refers to. + + If the structure has methods (a C++ feature), they follow the +non-method fields; see *note Cplusplus::. + + +File: stabs.info, Node: Typedefs, Next: Unions, Prev: Structures, Up: Types + +5.9 Giving a Type a Name +======================== + +To give a type a name, use the 't' symbol descriptor. The type is +specified by the type information (*note String Field::) for the stab. +For example, + + .stabs "s_typedef:t16",128,0,0,0 # 128 is N_LSYM + + specifies that 's_typedef' refers to type number 16. Such stabs have +symbol type 'N_LSYM' (or 'C_DECL' for XCOFF). (The Sun documentation +mentions using 'N_GSYM' in some cases). + + If you are specifying the tag name for a structure, union, or +enumeration, use the 'T' symbol descriptor instead. I believe C is the +only language with this feature. + + If the type is an opaque type (I believe this is a Modula-2 feature), +AIX provides a type descriptor to specify it. The type descriptor is +'o' and is followed by a name. I don't know what the name means--is it +always the same as the name of the type, or is this type descriptor used +with a nameless stab (*note String Field::)? There optionally follows a +comma followed by type information which defines the type of this type. +If omitted, a semicolon is used in place of the comma and the type +information, and the type is much like a generic pointer type--it has a +known size but little else about it is specified. + + +File: stabs.info, Node: Unions, Next: Function Types, Prev: Typedefs, Up: Types + +5.10 Unions +=========== + + union u_tag { + int u_int; + float u_float; + char* u_char; + } an_u; + + This code generates a stab for a union tag and a stab for a union +variable. Both use the 'N_LSYM' stab type. If a union variable is +scoped locally to the procedure in which it is defined, its stab is +located immediately preceding the 'N_LBRAC' for the procedure's block +start. + + The stab for the union tag, however, is located preceding the code +for the procedure in which it is defined. The stab type is 'N_LSYM'. +This would seem to imply that the union type is file scope, like the +struct type 's_tag'. This is not true. The contents and position of +the stab for 'u_type' do not convey any information about its procedure +local scope. + + # 128 is N_LSYM + .stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", + 128,0,0,0 + + The symbol descriptor 'T', following the 'name:' means that the stab +describes an enumeration, structure, or union tag. The type descriptor +'u', following the '23=' of the type definition, narrows it down to a +union type definition. Following the 'u' is the number of bytes in the +union. After that is a list of union element descriptions. Their +format is 'NAME:TYPE, BIT OFFSET INTO THE UNION, NUMBER OF BYTES FOR THE +ELEMENT;'. + + The stab for the union variable is: + + .stabs "an_u:23",128,0,0,-20 # 128 is N_LSYM + + '-20' specifies where the variable is stored (*note Stack +Variables::). + + +File: stabs.info, Node: Function Types, Prev: Unions, Up: Types + +5.11 Function Types +=================== + +Various types can be defined for function variables. These types are +not used in defining functions (*note Procedures::); they are used for +things like pointers to functions. + + The simple, traditional, type is type descriptor 'f' is followed by +type information for the return type of the function, followed by a +semicolon. + + This does not deal with functions for which the number and types of +the parameters are part of the type, as in Modula-2 or ANSI C. AIX +provides extensions to specify these, using the 'f', 'F', 'p', and 'R' +type descriptors. + + First comes the type descriptor. If it is 'f' or 'F', this type +involves a function rather than a procedure, and the type information +for the return type of the function follows, followed by a comma. Then +comes the number of parameters to the function and a semicolon. Then, +for each parameter, there is the name of the parameter followed by a +colon (this is only present for type descriptors 'R' and 'F' which +represent Pascal function or procedure parameters), type information for +the parameter, a comma, 0 if passed by reference or 1 if passed by +value, and a semicolon. The type definition ends with a semicolon. + + For example, this variable definition: + + int (*g_pf)(); + +generates the following code: + + .stabs "g_pf:G24=*25=f1",32,0,0,0 + .common _g_pf,4,"bss" + + The variable defines a new type, 24, which is a pointer to another +new type, 25, which is a function returning 'int'. + + +File: stabs.info, Node: Macro define and undefine, Next: Symbol Tables, Prev: Types, Up: Top + +6 Representation of #define and #undef +************************************** + +This section describes the stabs support for macro define and undefine +information, supported on some systems. (e.g., with '-g3' '-gstabs' +when using GCC). + + A '#define MACRO-NAME MACRO-BODY' is represented with an +'N_MAC_DEFINE' stab with a string field of 'MACRO-NAME MACRO-BODY'. + + An '#undef MACRO-NAME' is represented with an 'N_MAC_UNDEF' stabs +with a string field of simply 'MACRO-NAME'. + + For both 'N_MAC_DEFINE' and 'N_MAC_UNDEF', the desc field is the line +number within the file where the corresponding '#define' or '#undef' +occurred. + + For example, the following C code: + + #define NONE 42 + #define TWO(a, b) (a + (a) + 2 * b) + #define ONE(c) (c + 19) + + main(int argc, char *argv[]) + { + func(NONE, TWO(10, 11)); + func(NONE, ONE(23)); + + #undef ONE + #define ONE(c) (c + 23) + + func(NONE, ONE(-23)); + + return (0); + } + + int global; + + func(int arg1, int arg2) + { + global = arg1 + arg2; + } + +produces the following stabs (as well as many others): + + .stabs "NONE 42",54,0,1,0 + .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0 + .stabs "ONE(c) (c + 19)",54,0,3,0 + .stabs "ONE",58,0,10,0 + .stabs "ONE(c) (c + 23)",54,0,11,0 + +NOTE: In the above example, '54' is 'N_MAC_DEFINE' and '58' is +'N_MAC_UNDEF'. + + +File: stabs.info, Node: Symbol Tables, Next: Cplusplus, Prev: Macro define and undefine, Up: Top + +7 Symbol Information in Symbol Tables +************************************* + +This chapter describes the format of symbol table entries and how stab +assembler directives map to them. It also describes the transformations +that the assembler and linker make on data from stabs. + +* Menu: + +* Symbol Table Format:: +* Transformations On Symbol Tables:: + + +File: stabs.info, Node: Symbol Table Format, Next: Transformations On Symbol Tables, Up: Symbol Tables + +7.1 Symbol Table Format +======================= + +Each time the assembler encounters a stab directive, it puts each field +of the stab into a corresponding field in a symbol table entry of its +output file. If the stab contains a string field, the symbol table +entry for that stab points to a string table entry containing the string +data from the stab. Assembler labels become relocatable addresses. +Symbol table entries in a.out have the format: + + struct internal_nlist { + unsigned long n_strx; /* index into string table of name */ + unsigned char n_type; /* type of symbol */ + unsigned char n_other; /* misc info (usually empty) */ + unsigned short n_desc; /* description field */ + bfd_vma n_value; /* value of symbol */ + }; + + If the stab has a string, the 'n_strx' field holds the offset in +bytes of the string within the string table. The string is terminated +by a NUL character. If the stab lacks a string (for example, it was +produced by a '.stabn' or '.stabd' directive), the 'n_strx' field is +zero. + + Symbol table entries with 'n_type' field values greater than 0x1f +originated as stabs generated by the compiler (with one random +exception). The other entries were placed in the symbol table of the +executable by the assembler or the linker. + + +File: stabs.info, Node: Transformations On Symbol Tables, Prev: Symbol Table Format, Up: Symbol Tables + +7.2 Transformations on Symbol Tables +==================================== + +The linker concatenates object files and does fixups of externally +defined symbols. + + You can see the transformations made on stab data by the assembler +and linker by examining the symbol table after each pass of the build. +To do this, use 'nm -ap', which dumps the symbol table, including +debugging information, unsorted. For stab entries the columns are: +VALUE, OTHER, DESC, TYPE, STRING. For assembler and linker symbols, the +columns are: VALUE, TYPE, STRING. + + The low 5 bits of the stab type tell the linker how to relocate the +value of the stab. Thus for stab types like 'N_RSYM' and 'N_LSYM', +where the value is an offset or a register number, the low 5 bits are +'N_ABS', which tells the linker not to relocate the value. + + Where the value of a stab contains an assembly language label, it is +transformed by each build step. The assembler turns it into a +relocatable address and the linker turns it into an absolute address. + +* Menu: + +* Transformations On Static Variables:: +* Transformations On Global Variables:: +* Stab Section Transformations:: For some object file formats, + things are a bit different. + + +File: stabs.info, Node: Transformations On Static Variables, Next: Transformations On Global Variables, Up: Transformations On Symbol Tables + +7.2.1 Transformations on Static Variables +----------------------------------------- + +This source line defines a static variable at file scope: + + static int s_g_repeat + +The following stab describes the symbol: + + .stabs "s_g_repeat:S1",38,0,0,_s_g_repeat + +The assembler transforms the stab into this symbol table entry in the +'.o' file. The location is expressed as a data segment offset. + + 00000084 - 00 0000 STSYM s_g_repeat:S1 + +In the symbol table entry from the executable, the linker has made the +relocatable address absolute. + + 0000e00c - 00 0000 STSYM s_g_repeat:S1 + + +File: stabs.info, Node: Transformations On Global Variables, Next: Stab Section Transformations, Prev: Transformations On Static Variables, Up: Transformations On Symbol Tables + +7.2.2 Transformations on Global Variables +----------------------------------------- + +Stabs for global variables do not contain location information. In this +case, the debugger finds location information in the assembler or linker +symbol table entry describing the variable. The source line: + + char g_foo = 'c'; + +generates the stab: + + .stabs "g_foo:G2",32,0,0,0 + + The variable is represented by two symbol table entries in the object +file (see below). The first one originated as a stab. The second one +is an external symbol. The upper case 'D' signifies that the 'n_type' +field of the symbol table contains 7, 'N_DATA' with local linkage. The +stab's value is zero since the value is not used for 'N_GSYM' stabs. +The value of the linker symbol is the relocatable address corresponding +to the variable. + + 00000000 - 00 0000 GSYM g_foo:G2 + 00000080 D _g_foo + +These entries as transformed by the linker. The linker symbol table +entry now holds an absolute address: + + 00000000 - 00 0000 GSYM g_foo:G2 + ... + 0000e008 D _g_foo + + +File: stabs.info, Node: Stab Section Transformations, Prev: Transformations On Global Variables, Up: Transformations On Symbol Tables + +7.2.3 Transformations of Stabs in separate sections +--------------------------------------------------- + +For object file formats using stabs in separate sections (*note Stab +Sections::), use 'objdump --stabs' instead of 'nm' to show the stabs in +an object or executable file. 'objdump' is a GNU utility; Sun does not +provide any equivalent. + + The following example is for a stab whose value is an address is +relative to the compilation unit (*note ELF Linker Relocation::). For +example, if the source line + + static int ld = 5; + + appears within a function, then the assembly language output from the +compiler contains: + + .Ddata.data: + ... + .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # 0x26 is N_STSYM + ... + .L18: + .align 4 + .word 0x5 + + Because the value is formed by subtracting one symbol from another, +the value is absolute, not relocatable, and so the object file contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + without any relocations, and the executable file also contains + + Symnum n_type n_othr n_desc n_value n_strx String + 31 STSYM 0 4 00000004 680 ld:V(0,3) + + +File: stabs.info, Node: Cplusplus, Next: Stab Types, Prev: Symbol Tables, Up: Top + +8 GNU C++ Stabs +*************** + +* Menu: + +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: +* Methods:: Method definition +* Method Type Descriptor:: The '#' type descriptor +* Member Type Descriptor:: The '@' type descriptor +* Protections:: +* Method Modifiers:: +* Virtual Methods:: +* Inheritance:: +* Virtual Base Classes:: +* Static Members:: + + +File: stabs.info, Node: Class Names, Next: Nested Symbols, Up: Cplusplus + +8.1 C++ Class Names +=================== + +In C++, a class name which is declared with 'class', 'struct', or +'union', is not only a tag, as in C, but also a type name. Thus there +should be stabs with both 't' and 'T' symbol descriptors (*note +Typedefs::). + + To save space, there is a special abbreviation for this case. If the +'T' symbol descriptor is followed by 't', then the stab defines both a +type name and a tag. + + For example, the C++ code + + struct foo {int x;}; + + can be represented as either + + .stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # 128 is N_LSYM + .stabs "foo:t19",128,0,0,0 + + or + + .stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 + + +File: stabs.info, Node: Nested Symbols, Next: Basic Cplusplus Types, Prev: Class Names, Up: Cplusplus + +8.2 Defining a Symbol Within Another Type +========================================= + +In C++, a symbol (such as a type name) can be defined within another +type. + + In stabs, this is sometimes represented by making the name of a +symbol which contains '::'. Such a pair of colons does not end the name +of the symbol, the way a single colon would (*note String Field::). I'm +not sure how consistently used or well thought out this mechanism is. +So that a pair of colons in this position always has this meaning, ':' +cannot be used as a symbol descriptor. + + For example, if the string for a stab is 'foo::bar::baz:t5=*6', then +'foo::bar::baz' is the name of the symbol, 't' is the symbol descriptor, +and '5=*6' is the type information. + + +File: stabs.info, Node: Basic Cplusplus Types, Next: Simple Classes, Prev: Nested Symbols, Up: Cplusplus + +8.3 Basic Types For C++ +======================= + +<< the examples that follow are based on a01.C >> + + C++ adds two more builtin types to the set defined for C. These are +the unknown type and the vtable record type. The unknown type, type 16, +is defined in terms of itself like the void type. + + The vtable record type, type 17, is defined as a structure type and +then as a structure tag. The structure has four fields: delta, index, +pfn, and delta2. pfn is the function pointer. + + << In boilerplate $vtbl_ptr_type, what are the fields delta, index, +and delta2 used for? >> + + This basic type is present in all C++ programs even if there are no +virtual methods defined. + + .stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) + elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); + elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); + elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), + bit_offset(32),field_bits(32); + elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" + N_LSYM, NIL, NIL + + .stabs "$vtbl_ptr_type:t17=s8 + delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" + ,128,0,0,0 + + .stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL + + .stabs "$vtbl_ptr_type:T17",128,0,0,0 + + +File: stabs.info, Node: Simple Classes, Next: Class Instance, Prev: Basic Cplusplus Types, Up: Cplusplus + +8.4 Simple Class Definition +=========================== + +The stabs describing C++ language features are an extension of the stabs +describing C. Stabs representing C++ class types elaborate extensively +on the stab format used to describe structure types in C. Stabs +representing class type variables look just like stabs representing C +language variables. + + Consider the following very simple class definition. + + class baseA { + public: + int Adat; + int Ameth(int in, char other); + }; + + The class 'baseA' is represented by two stabs. The first stab +describes the class as a structure type. The second stab describes a +structure tag of the class type. Both stabs are of stab type 'N_LSYM'. +Since the stab is not located between an 'N_FUN' and an 'N_LBRAC' stab +this indicates that the class is defined at file scope. If it were, +then the 'N_LSYM' would signify a local variable. + + A stab describing a C++ class type is similar in format to a stab +describing a C struct, with each class member shown as a field in the +structure. The part of the struct format describing fields is expanded +to include extra information relevant to C++ class members. In +addition, if the class has multiple base classes or virtual functions +the struct format outside of the field parts is also augmented. + + In this simple example the field part of the C++ class stab +representing member data looks just like the field part of a C struct +stab. The section on protections describes how its format is sometimes +extended for member data. + + The field part of a C++ class stab representing a member function +differs substantially from the field part of a C struct stab. It still +begins with 'name:' but then goes on to define a new type number for the +member function, describe its return type, its argument types, its +protection level, any qualifiers applied to the method definition, and +whether the method is virtual or not. If the method is virtual then the +method description goes on to give the vtable index of the method, and +the type number of the first base class defining the method. + + When the field name is a method name it is followed by two colons +rather than one. This is followed by a new type definition for the +method. This is a number followed by an equal sign and the type of the +method. Normally this will be a type declared using the '#' type +descriptor; see *note Method Type Descriptor::; static member functions +are declared using the 'f' type descriptor instead; see *note Function +Types::. + + The format of an overloaded operator method name differs from that of +other methods. It is 'op$::OPERATOR-NAME.' where OPERATOR-NAME is the +operator name such as '+' or '+='. The name ends with a period, and any +characters except the period can occur in the OPERATOR-NAME string. + + The next part of the method description represents the arguments to +the method, preceded by a colon and ending with a semi-colon. The types +of the arguments are expressed in the same way argument types are +expressed in C++ name mangling. In this example an 'int' and a 'char' +map to 'ic'. + + This is followed by a number, a letter, and an asterisk or period, +followed by another semicolon. The number indicates the protections +that apply to the member function. Here the 2 means public. The letter +encodes any qualifier applied to the method definition. In this case, +'A' means that it is a normal function definition. The dot shows that +the method is not virtual. The sections that follow elaborate further +on these fields and describe the additional information present for +virtual methods. + + .stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) + field_name(Adat):type(int),bit_offset(0),field_bits(32); + + method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); + :arg_types(int char); + protection(public)qualifier(normal)virtual(no);;" + N_LSYM,NIL,NIL,NIL + + .stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 + + .stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL + + .stabs "baseA:T20",128,0,0,0 + + +File: stabs.info, Node: Class Instance, Next: Methods, Prev: Simple Classes, Up: Cplusplus + +8.5 Class Instance +================== + +As shown above, describing even a simple C++ class definition is +accomplished by massively extending the stab format used in C to +describe structure types. However, once the class is defined, C stabs +with no modifications can be used to describe class instances. The +following source: + + main () { + baseA AbaseA; + } + +yields the following stab describing the class instance. It looks no +different from a standard C stab describing a local variable. + + .stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset + + .stabs "AbaseA:20",128,0,0,-20 + + +File: stabs.info, Node: Methods, Next: Method Type Descriptor, Prev: Class Instance, Up: Cplusplus + +8.6 Method Definition +===================== + +The class definition shown above declares Ameth. The C++ source below +defines Ameth: + + int + baseA::Ameth(int in, char other) + { + return in; + }; + + This method definition yields three stabs following the code of the +method. One stab describes the method itself and following two describe +its parameters. Although there is only one formal argument all methods +have an implicit argument which is the 'this' pointer. The 'this' +pointer is a pointer to the object on which the method was called. Note +that the method name is mangled to encode the class name and argument +types. Name mangling is described in the ARM ('The Annotated C++ +Reference Manual', by Ellis and Stroustrup, ISBN 0-201-51459-1); +'gpcompare.texi' in Cygnus GCC distributions describes the differences +between GNU mangling and ARM mangling. + + .stabs "name:symbol_descriptor(global function)return_type(int)", + N_FUN, NIL, NIL, code_addr_of_method_start + + .stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic + + Here is the stab for the 'this' pointer implicit argument. The name +of the 'this' pointer is always 'this'. Type 19, the 'this' pointer is +defined as a pointer to type 20, 'baseA', but a stab defining 'baseA' +has not yet been emitted. Since the compiler knows it will be emitted +shortly, here it just outputs a cross reference to the undefined symbol, +by prefixing the symbol name with 'xs'. + + .stabs "name:sym_desc(register param)type_def(19)= + type_desc(ptr to)type_ref(baseA)= + type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number + + .stabs "this:P19=*20=xsbaseA:",64,0,0,8 + + The stab for the explicit integer argument looks just like a +parameter to a C function. The last field of the stab is the offset +from the argument pointer, which in most systems is the same as the +frame pointer. + + .stabs "name:sym_desc(value parameter)type_ref(int)", + N_PSYM,NIL,NIL,offset_from_arg_ptr + + .stabs "in:p1",160,0,0,72 + + << The examples that follow are based on A1.C >> + + +File: stabs.info, Node: Method Type Descriptor, Next: Member Type Descriptor, Prev: Methods, Up: Cplusplus + +8.7 The '#' Type Descriptor +=========================== + +This is used to describe a class method. This is a function which takes +an extra argument as its first argument, for the 'this' pointer. + + If the '#' is immediately followed by another '#', the second one +will be followed by the return type and a semicolon. The class and +argument types are not specified, and must be determined by demangling +the name of the method if it is available. + + Otherwise, the single '#' is followed by the class type, a comma, the +return type, a comma, and zero or more parameter types separated by +commas. The list of arguments is terminated by a semicolon. In the +debugging output generated by gcc, a final argument type of 'void' +indicates a method which does not take a variable number of arguments. +If the final argument type of 'void' does not appear, the method was +declared with an ellipsis. + + Note that although such a type will normally be used to describe +fields in structures, unions, or classes, for at least some versions of +the compiler it can also be used in other contexts. + + +File: stabs.info, Node: Member Type Descriptor, Next: Protections, Prev: Method Type Descriptor, Up: Cplusplus + +8.8 The '@' Type Descriptor +=========================== + +The '@' type descriptor is used for a pointer-to-non-static-member-data +type. It is followed by type information for the class (or union), a +comma, and type information for the member data. + + The following C++ source: + + typedef int A::*int_in_a; + + generates the following stab: + + .stabs "int_in_a:t20=21=@19,1",128,0,0,0 + + Note that there is a conflict between this and type attributes (*note +String Field::); both use type descriptor '@'. Fortunately, the '@' +type descriptor used in this C++ sense always will be followed by a +digit, '(', or '-', and type attributes never start with those things. + + +File: stabs.info, Node: Protections, Next: Method Modifiers, Prev: Member Type Descriptor, Up: Cplusplus + +8.9 Protections +=============== + +In the simple class definition shown above all member data and functions +were publicly accessible. The example that follows contrasts public, +protected and privately accessible fields and shows how these +protections are encoded in C++ stabs. + + If the character following the 'FIELD-NAME:' part of the string is +'/', then the next character is the visibility. '0' means private, '1' +means protected, and '2' means public. Debuggers should ignore +visibility characters they do not recognize, and assume a reasonable +default (such as public) (GDB 4.11 does not, but this should be fixed in +the next GDB release). If no visibility is specified the field is +public. The visibility '9' means that the field has been optimized out +and is public (there is no way to specify an optimized out field with a +private or protected visibility). Visibility '9' is not supported by +GDB 4.11; this should be fixed in the next GDB release. + + The following C++ source: + + class vis { + private: + int priv; + protected: + char prot; + public: + float pub; + }; + +generates the following stab: + + # 128 is N_LSYM + .stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 + + 'vis:T19=s12' indicates that type number 19 is a 12 byte structure +named 'vis' The 'priv' field has public visibility ('/0'), type int +('1'), and offset and size ',0,32;'. The 'prot' field has protected +visibility ('/1'), type char ('2') and offset and size ',32,8;'. The +'pub' field has type float ('12'), and offset and size ',64,32;'. + + Protections for member functions are signified by one digit embedded +in the field part of the stab describing the method. The digit is 0 if +private, 1 if protected and 2 if public. Consider the C++ class +definition below: + + class all_methods { + private: + int priv_meth(int in){return in;}; + protected: + char protMeth(char in){return in;}; + public: + float pubMeth(float in){return in;}; + }; + + It generates the following stab. The digit in question is to the +left of an 'A' in each case. Notice also that in this case two symbol +descriptors apply to the class name struct tag and struct type. + + .stabs "class_name:sym_desc(struct tag&type)type_def(21)= + sym_desc(struct)struct_bytes(1) + meth_name::type_def(22)=sym_desc(method)returning(int); + :args(int);protection(private)modifier(normal)virtual(no); + meth_name::type_def(23)=sym_desc(method)returning(char); + :args(char);protection(protected)modifier(normal)virtual(no); + meth_name::type_def(24)=sym_desc(method)returning(float); + :args(float);protection(public)modifier(normal)virtual(no);;", + N_LSYM,NIL,NIL,NIL + + .stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; + pubMeth::24=##12;:f;2A.;;",128,0,0,0 + + +File: stabs.info, Node: Method Modifiers, Next: Virtual Methods, Prev: Protections, Up: Cplusplus + +8.10 Method Modifiers ('const', 'volatile', 'const volatile') +============================================================= + +<< based on a6.C >> + + In the class example described above all the methods have the normal +modifier. This method modifier information is located just after the +protection information for the method. This field has four possible +character values. Normal methods use 'A', const methods use 'B', +volatile methods use 'C', and const volatile methods use 'D'. Consider +the class definition below: + + class A { + public: + int ConstMeth (int arg) const { return arg; }; + char VolatileMeth (char arg) volatile { return arg; }; + float ConstVolMeth (float arg) const volatile {return arg; }; + }; + + This class is described by the following stab: + + .stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) + meth_name(ConstMeth)::type_def(21)sym_desc(method) + returning(int);:arg(int);protection(public)modifier(const)virtual(no); + meth_name(VolatileMeth)::type_def(22)=sym_desc(method) + returning(char);:arg(char);protection(public)modifier(volatile)virt(no) + meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) + returning(float);:arg(float);protection(public)modifier(const volatile) + virtual(no);;", ... + + .stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; + ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 + + +File: stabs.info, Node: Virtual Methods, Next: Inheritance, Prev: Method Modifiers, Up: Cplusplus + +8.11 Virtual Methods +==================== + +<< The following examples are based on a4.C >> + + The presence of virtual methods in a class definition adds additional +data to the class description. The extra data is appended to the +description of the virtual method and to the end of the class +description. Consider the class definition below: + + class A { + public: + int Adat; + virtual int A_virt (int arg) { return arg; }; + }; + + This results in the stab below describing class A. It defines a new +type (20) which is an 8 byte structure. The first field of the class +struct is 'Adat', an integer, starting at structure offset 0 and +occupying 32 bits. + + The second field in the class struct is not explicitly defined by the +C++ class definition but is implied by the fact that the class contains +a virtual method. This field is the vtable pointer. The name of the +vtable pointer field starts with '$vf' and continues with a type +reference to the class it is part of. In this example the type +reference for class A is 20 so the name of its vtable pointer field is +'$vf20', followed by the usual colon. + + Next there is a type definition for the vtable pointer type (21). +This is in turn defined as a pointer to another new type (22). + + Type 22 is the vtable itself, which is defined as an array, indexed +by a range of integers between 0 and 1, and whose elements are of type +17. Type 17 was the vtable record type defined by the boilerplate C++ +type definitions, as shown earlier. + + The bit offset of the vtable pointer field is 32. The number of bits +in the field are not specified when the field is a vtable pointer. + + Next is the method definition for the virtual member function +'A_virt'. Its description starts out using the same format as the +non-virtual member functions described above, except instead of a dot +after the 'A' there is an asterisk, indicating that the function is +virtual. Since is is virtual some addition information is appended to +the end of the method description. + + The first number represents the vtable index of the method. This is +a 32 bit unsigned number with the high bit set, followed by a +semi-colon. + + The second number is a type reference to the first base class in the +inheritance hierarchy defining the virtual member function. In this +case the class stab describes a base class so the virtual function is +not overriding any other definition of the method. Therefore the +reference is to the type number of the class that the stab is describing +(20). + + This is followed by three semi-colons. One marks the end of the +current sub-section, one marks the end of the method field, and the +third marks the end of the struct definition. + + For classes containing virtual functions the very last section of the +string part of the stab holds a type reference to the first base class. +This is preceded by '~%' and followed by a final semi-colon. + + .stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) + field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); + field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= + sym_desc(array)index_type_ref(range of int from 0 to 1); + elem_type_ref(vtbl elem type), + bit_offset(32); + meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); + :arg_type(int),protection(public)normal(yes)virtual(yes) + vtable_index(1);class_first_defining(A);;;~%first_base(A);", + N_LSYM,NIL,NIL,NIL + + .stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + + +File: stabs.info, Node: Inheritance, Next: Virtual Base Classes, Prev: Virtual Methods, Up: Cplusplus + +8.12 Inheritance +================ + +Stabs describing C++ derived classes include additional sections that +describe the inheritance hierarchy of the class. A derived class stab +also encodes the number of base classes. For each base class it tells +if the base class is virtual or not, and if the inheritance is private +or public. It also gives the offset into the object of the portion of +the object corresponding to each base class. + + This additional information is embedded in the class stab following +the number of bytes in the struct. First the number of base classes +appears bracketed by an exclamation point and a comma. + + Then for each base type there repeats a series: a virtual character, +a visibility character, a number, a comma, another number, and a +semi-colon. + + The virtual character is '1' if the base class is virtual and '0' if +not. The visibility character is '2' if the derivation is public, '1' +if it is protected, and '0' if it is private. Debuggers should ignore +virtual or visibility characters they do not recognize, and assume a +reasonable default (such as public and non-virtual) (GDB 4.11 does not, +but this should be fixed in the next GDB release). + + The number following the virtual and visibility characters is the +offset from the start of the object to the part of the object pertaining +to the base class. + + After the comma, the second number is a type_descriptor for the base +type. Finally a semi-colon ends the series, which repeats for each base +class. + + The source below defines three base classes 'A', 'B', and 'C' and the +derived class 'D'. + + class A { + public: + int Adat; + virtual int A_virt (int arg) { return arg; }; + }; + + class B { + public: + int B_dat; + virtual int B_virt (int arg) {return arg; }; + }; + + class C { + public: + int Cdat; + virtual int C_virt (int arg) {return arg; }; + }; + + class D : A, virtual B, public C { + public: + int Ddat; + virtual int A_virt (int arg ) { return arg+1; }; + virtual int B_virt (int arg) { return arg+2; }; + virtual int C_virt (int arg) { return arg+3; }; + virtual int D_virt (int arg) { return arg; }; + }; + + Class stabs similar to the ones described earlier are generated for +each base class. + + .stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + + .stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; + :i;2A*-2147483647;25;;;~%25;",128,0,0,0 + + .stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; + :i;2A*-2147483647;28;;;~%28;",128,0,0,0 + + In the stab describing derived class 'D' below, the information about +the derivation of this class is encoded as follows. + + .stabs "derived_class_name:symbol_descriptors(struct tag&type)= + type_descriptor(struct)struct_bytes(32)!num_bases(3), + base_virtual(no)inheritance_public(no)base_offset(0), + base_class_type_ref(A); + base_virtual(yes)inheritance_public(no)base_offset(NIL), + base_class_type_ref(B); + base_virtual(no)inheritance_public(yes)base_offset(64), + base_class_type_ref(C); ... + + .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: + 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: + :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; + 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 + + +File: stabs.info, Node: Virtual Base Classes, Next: Static Members, Prev: Inheritance, Up: Cplusplus + +8.13 Virtual Base Classes +========================= + +A derived class object consists of a concatenation in memory of the data +areas defined by each base class, starting with the leftmost and ending +with the rightmost in the list of base classes. The exception to this +rule is for virtual inheritance. In the example above, class 'D' +inherits virtually from base class 'B'. This means that an instance of +a 'D' object will not contain its own 'B' part but merely a pointer to a +'B' part, known as a virtual base pointer. + + In a derived class stab, the base offset part of the derivation +information, described above, shows how the base class parts are +ordered. The base offset for a virtual base class is always given as 0. +Notice that the base offset for 'B' is given as 0 even though 'B' is not +the first base class. The first base class 'A' starts at offset 0. + + The field information part of the stab for class 'D' describes the +field which is the pointer to the virtual base class 'B'. The vbase +pointer name is '$vb' followed by a type reference to the virtual base +class. Since the type id for 'B' in this example is 25, the vbase +pointer name is '$vb25'. + + .stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, + 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; + 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: + :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 + + Following the name and a semicolon is a type reference describing the +type of the virtual base class pointer, in this case 24. Type 24 was +defined earlier as the type of the 'B' class 'this' pointer. The 'this' +pointer for a class is a pointer to the class type. + + .stabs "this:P24=*25=xsB:",64,0,0,8 + + Finally the field offset part of the vbase pointer field description +shows that the vbase pointer is the first field in the 'D' object, +before any data fields defined by the class. The layout of a 'D' class +object is a follows, 'Adat' at 0, the vtable pointer for 'A' at 32, +'Cdat' at 64, the vtable pointer for C at 96, the virtual base pointer +for 'B' at 128, and 'Ddat' at 160. + + +File: stabs.info, Node: Static Members, Prev: Virtual Base Classes, Up: Cplusplus + +8.14 Static Members +=================== + +The data area for a class is a concatenation of the space used by the +data members of the class. If the class has virtual methods, a vtable +pointer follows the class data. The field offset part of each field +description in the class stab shows this ordering. + + << How is this reflected in stabs? See Cygnus bug #677 for some +info. >> + + +File: stabs.info, Node: Stab Types, Next: Symbol Descriptors, Prev: Cplusplus, Up: Top + +Appendix A Table of Stab Types +****************************** + +The following are all the possible values for the stab type field, for +a.out files, in numeric order. This does not apply to XCOFF, but it +does apply to stabs in sections (*note Stab Sections::). Stabs in ECOFF +use these values but add 0x8f300 to distinguish them from non-stab +symbols. + + The symbolic names are defined in the file 'include/aout/stabs.def'. + +* Menu: + +* Non-Stab Symbol Types:: Types from 0 to 0x1f +* Stab Symbol Types:: Types from 0x20 to 0xff + + +File: stabs.info, Node: Non-Stab Symbol Types, Next: Stab Symbol Types, Up: Stab Types + +A.1 Non-Stab Symbol Types +========================= + +The following types are used by the linker and assembler, not by stab +directives. Since this document does not attempt to describe aspects of +object file format other than the debugging format, no details are +given. + +'0x0 N_UNDF' + Undefined symbol + +'0x2 N_ABS' + File scope absolute symbol + +'0x3 N_ABS | N_EXT' + External absolute symbol + +'0x4 N_TEXT' + File scope text symbol + +'0x5 N_TEXT | N_EXT' + External text symbol + +'0x6 N_DATA' + File scope data symbol + +'0x7 N_DATA | N_EXT' + External data symbol + +'0x8 N_BSS' + File scope BSS symbol + +'0x9 N_BSS | N_EXT' + External BSS symbol + +'0x0c N_FN_SEQ' + Same as 'N_FN', for Sequent compilers + +'0x0a N_INDR' + Symbol is indirected to another symbol + +'0x12 N_COMM' + Common--visible after shared library dynamic link + +'0x14 N_SETA' +'0x15 N_SETA | N_EXT' + Absolute set element + +'0x16 N_SETT' +'0x17 N_SETT | N_EXT' + Text segment set element + +'0x18 N_SETD' +'0x19 N_SETD | N_EXT' + Data segment set element + +'0x1a N_SETB' +'0x1b N_SETB | N_EXT' + BSS segment set element + +'0x1c N_SETV' +'0x1d N_SETV | N_EXT' + Pointer to set vector + +'0x1e N_WARNING' + Print a warning message during linking + +'0x1f N_FN' + File name of a '.o' file + + +File: stabs.info, Node: Stab Symbol Types, Prev: Non-Stab Symbol Types, Up: Stab Types + +A.2 Stab Symbol Types +===================== + +The following symbol types indicate that this is a stab. This is the +full list of stab numbers, including stab types that are used in +languages other than C. + +'0x20 N_GSYM' + Global symbol; see *note Global Variables::. + +'0x22 N_FNAME' + Function name (for BSD Fortran); see *note Procedures::. + +'0x24 N_FUN' + Function name (*note Procedures::) or text segment variable (*note + Statics::). + +'0x26 N_STSYM' + Data segment file-scope variable; see *note Statics::. + +'0x28 N_LCSYM' + BSS segment file-scope variable; see *note Statics::. + +'0x2a N_MAIN' + Name of main routine; see *note Main Program::. + +'0x2c N_ROSYM' + Variable in '.rodata' section; see *note Statics::. + +'0x30 N_PC' + Global symbol (for Pascal); see *note N_PC::. + +'0x32 N_NSYMS' + Number of symbols (according to Ultrix V4.0); see *note N_NSYMS::. + +'0x34 N_NOMAP' + No DST map; see *note N_NOMAP::. + +'0x36 N_MAC_DEFINE' + Name and body of a '#define'd macro; see *note Macro define and + undefine::. + +'0x38 N_OBJ' + Object file (Solaris2). + +'0x3a N_MAC_UNDEF' + Name of an '#undef'ed macro; see *note Macro define and undefine::. + +'0x3c N_OPT' + Debugger options (Solaris2). + +'0x40 N_RSYM' + Register variable; see *note Register Variables::. + +'0x42 N_M2C' + Modula-2 compilation unit; see *note N_M2C::. + +'0x44 N_SLINE' + Line number in text segment; see *note Line Numbers::. + +'0x46 N_DSLINE' + Line number in data segment; see *note Line Numbers::. + +'0x48 N_BSLINE' + Line number in bss segment; see *note Line Numbers::. + +'0x48 N_BROWS' + Sun source code browser, path to '.cb' file; see *note N_BROWS::. + +'0x4a N_DEFD' + GNU Modula2 definition module dependency; see *note N_DEFD::. + +'0x4c N_FLINE' + Function start/body/end line numbers (Solaris2). + +'0x50 N_EHDECL' + GNU C++ exception variable; see *note N_EHDECL::. + +'0x50 N_MOD2' + Modula2 info "for imc" (according to Ultrix V4.0); see *note + N_MOD2::. + +'0x54 N_CATCH' + GNU C++ 'catch' clause; see *note N_CATCH::. + +'0x60 N_SSYM' + Structure of union element; see *note N_SSYM::. + +'0x62 N_ENDM' + Last stab for module (Solaris2). + +'0x64 N_SO' + Path and name of source file; see *note Source Files::. + +'0x80 N_LSYM' + Stack variable (*note Stack Variables::) or type (*note + Typedefs::). + +'0x82 N_BINCL' + Beginning of an include file (Sun only); see *note Include Files::. + +'0x84 N_SOL' + Name of include file; see *note Include Files::. + +'0xa0 N_PSYM' + Parameter variable; see *note Parameters::. + +'0xa2 N_EINCL' + End of an include file; see *note Include Files::. + +'0xa4 N_ENTRY' + Alternate entry point; see *note Alternate Entry Points::. + +'0xc0 N_LBRAC' + Beginning of a lexical block; see *note Block Structure::. + +'0xc2 N_EXCL' + Place holder for a deleted include file; see *note Include Files::. + +'0xc4 N_SCOPE' + Modula2 scope information (Sun linker); see *note N_SCOPE::. + +'0xe0 N_RBRAC' + End of a lexical block; see *note Block Structure::. + +'0xe2 N_BCOMM' + Begin named common block; see *note Common Blocks::. + +'0xe4 N_ECOMM' + End named common block; see *note Common Blocks::. + +'0xe8 N_ECOML' + Member of a common block; see *note Common Blocks::. + +'0xea N_WITH' + Pascal 'with' statement: type,,0,0,offset (Solaris2). + +'0xf0 N_NBTEXT' + Gould non-base registers; see *note Gould::. + +'0xf2 N_NBDATA' + Gould non-base registers; see *note Gould::. + +'0xf4 N_NBBSS' + Gould non-base registers; see *note Gould::. + +'0xf6 N_NBSTS' + Gould non-base registers; see *note Gould::. + +'0xf8 N_NBLCS' + Gould non-base registers; see *note Gould::. + + +File: stabs.info, Node: Symbol Descriptors, Next: Type Descriptors, Prev: Stab Types, Up: Top + +Appendix B Table of Symbol Descriptors +************************************** + +The symbol descriptor is the character which follows the colon in many +stabs, and which tells what kind of stab it is. *Note String Field::, +for more information about their use. + +'DIGIT' +'(' +'-' + Variable on the stack; see *note Stack Variables::. + +':' + C++ nested symbol; see *Note Nested Symbols::. + +'a' + Parameter passed by reference in register; see *note Reference + Parameters::. + +'b' + Based variable; see *note Based Variables::. + +'c' + Constant; see *note Constants::. + +'C' + Conformant array bound (Pascal, maybe other languages); *note + Conformant Arrays::. Name of a caught exception (GNU C++). These + can be distinguished because the latter uses 'N_CATCH' and the + former uses another symbol type. + +'d' + Floating point register variable; see *note Register Variables::. + +'D' + Parameter in floating point register; see *note Register + Parameters::. + +'f' + File scope function; see *note Procedures::. + +'F' + Global function; see *note Procedures::. + +'G' + Global variable; see *note Global Variables::. + +'i' + *Note Register Parameters::. + +'I' + Internal (nested) procedure; see *note Nested Procedures::. + +'J' + Internal (nested) function; see *note Nested Procedures::. + +'L' + Label name (documented by AIX, no further information known). + +'m' + Module; see *note Procedures::. + +'p' + Argument list parameter; see *note Parameters::. + +'pP' + *Note Parameters::. + +'pF' + Fortran Function parameter; see *note Parameters::. + +'P' + Unfortunately, three separate meanings have been independently + invented for this symbol descriptor. At least the GNU and Sun uses + can be distinguished by the symbol type. Global Procedure (AIX) + (symbol type used unknown); see *note Procedures::. Register + parameter (GNU) (symbol type 'N_PSYM'); see *note Parameters::. + Prototype of function referenced by this file (Sun 'acc') (symbol + type 'N_FUN'). + +'Q' + Static Procedure; see *note Procedures::. + +'R' + Register parameter; see *note Register Parameters::. + +'r' + Register variable; see *note Register Variables::. + +'S' + File scope variable; see *note Statics::. + +'s' + Local variable (OS9000). + +'t' + Type name; see *note Typedefs::. + +'T' + Enumeration, structure, or union tag; see *note Typedefs::. + +'v' + Parameter passed by reference; see *note Reference Parameters::. + +'V' + Procedure scope static variable; see *note Statics::. + +'x' + Conformant array; see *note Conformant Arrays::. + +'X' + Function return variable; see *note Parameters::. + + +File: stabs.info, Node: Type Descriptors, Next: Expanded Reference, Prev: Symbol Descriptors, Up: Top + +Appendix C Table of Type Descriptors +************************************ + +The type descriptor is the character which follows the type number and +an equals sign. It specifies what kind of type is being defined. *Note +String Field::, for more information about their use. + +'DIGIT' +'(' + Type reference; see *note String Field::. + +'-' + Reference to builtin type; see *note Negative Type Numbers::. + +'#' + Method (C++); see *note Method Type Descriptor::. + +'*' + Pointer; see *note Miscellaneous Types::. + +'&' + Reference (C++). + +'@' + Type Attributes (AIX); see *note String Field::. Member (class and + variable) type (GNU C++); see *note Member Type Descriptor::. + +'a' + Array; see *note Arrays::. + +'A' + Open array; see *note Arrays::. + +'b' + Pascal space type (AIX); see *note Miscellaneous Types::. Builtin + integer type (Sun); see *note Builtin Type Descriptors::. Const + and volatile qualified type (OS9000). + +'B' + Volatile-qualified type; see *note Miscellaneous Types::. + +'c' + Complex builtin type (AIX); see *note Builtin Type Descriptors::. + Const-qualified type (OS9000). + +'C' + COBOL Picture type. See AIX documentation for details. + +'d' + File type; see *note Miscellaneous Types::. + +'D' + N-dimensional dynamic array; see *note Arrays::. + +'e' + Enumeration type; see *note Enumerations::. + +'E' + N-dimensional subarray; see *note Arrays::. + +'f' + Function type; see *note Function Types::. + +'F' + Pascal function parameter; see *note Function Types:: + +'g' + Builtin floating point type; see *note Builtin Type Descriptors::. + +'G' + COBOL Group. See AIX documentation for details. + +'i' + Imported type (AIX); see *note Cross-References::. + Volatile-qualified type (OS9000). + +'k' + Const-qualified type; see *note Miscellaneous Types::. + +'K' + COBOL File Descriptor. See AIX documentation for details. + +'M' + Multiple instance type; see *note Miscellaneous Types::. + +'n' + String type; see *note Strings::. + +'N' + Stringptr; see *note Strings::. + +'o' + Opaque type; see *note Typedefs::. + +'p' + Procedure; see *note Function Types::. + +'P' + Packed array; see *note Arrays::. + +'r' + Range type; see *note Subranges::. + +'R' + Builtin floating type; see *note Builtin Type Descriptors:: (Sun). + Pascal subroutine parameter; see *note Function Types:: (AIX). + Detecting this conflict is possible with careful parsing (hint: a + Pascal subroutine parameter type will always contain a comma, and a + builtin type descriptor never will). + +'s' + Structure type; see *note Structures::. + +'S' + Set type; see *note Miscellaneous Types::. + +'u' + Union; see *note Unions::. + +'v' + Variant record. This is a Pascal and Modula-2 feature which is + like a union within a struct in C. See AIX documentation for + details. + +'w' + Wide character; see *note Builtin Type Descriptors::. + +'x' + Cross-reference; see *note Cross-References::. + +'Y' + Used by IBM's xlC C++ compiler (for structures, I think). + +'z' + gstring; see *note Strings::. + + +File: stabs.info, Node: Expanded Reference, Next: Questions, Prev: Type Descriptors, Up: Top + +Appendix D Expanded Reference by Stab Type +****************************************** + +For a full list of stab types, and cross-references to where they are +described, see *note Stab Types::. This appendix just covers certain +stabs which are not yet described in the main body of this document; +eventually the information will all be in one place. + + Format of an entry: + + The first line is the symbol type (see 'include/aout/stab.def'). + + The second line describes the language constructs the symbol type +represents. + + The third line is the stab format with the significant stab fields +named and the rest NIL. + + Subsequent lines expand upon the meaning and possible values for each +significant stab field. + + Finally, any further information. + +* Menu: + +* N_PC:: Pascal global symbol +* N_NSYMS:: Number of symbols +* N_NOMAP:: No DST map +* N_M2C:: Modula-2 compilation unit +* N_BROWS:: Path to .cb file for Sun source code browser +* N_DEFD:: GNU Modula2 definition module dependency +* N_EHDECL:: GNU C++ exception variable +* N_MOD2:: Modula2 information "for imc" +* N_CATCH:: GNU C++ "catch" clause +* N_SSYM:: Structure or union element +* N_SCOPE:: Modula2 scope information (Sun only) +* Gould:: non-base register symbols used on Gould systems +* N_LENG:: Length of preceding entry + + +File: stabs.info, Node: N_PC, Next: N_NSYMS, Up: Expanded Reference + +D.1 N_PC +======== + + -- .stabs: N_PC + Global symbol (for Pascal). + + "name" -> "symbol_name" <> + value -> supposedly the line number (stab.def is skeptical) + + 'stabdump.c' says: + + global pascal symbol: name,,0,subtype,line + << subtype? >> + + +File: stabs.info, Node: N_NSYMS, Next: N_NOMAP, Prev: N_PC, Up: Expanded Reference + +D.2 N_NSYMS +=========== + + -- .stabn: N_NSYMS + Number of symbols (according to Ultrix V4.0). + + 0, files,,funcs,lines (stab.def) + + +File: stabs.info, Node: N_NOMAP, Next: N_M2C, Prev: N_NSYMS, Up: Expanded Reference + +D.3 N_NOMAP +=========== + + -- .stabs: N_NOMAP + No DST map for symbol (according to Ultrix V4.0). I think this + means a variable has been optimized out. + + name, ,0,type,ignored (stab.def) + + +File: stabs.info, Node: N_M2C, Next: N_BROWS, Prev: N_NOMAP, Up: Expanded Reference + +D.4 N_M2C +========= + + -- .stabs: N_M2C + Modula-2 compilation unit. + + "string" -> "unit_name,unit_time_stamp[,code_time_stamp]" + desc -> unit_number + value -> 0 (main unit) + 1 (any other unit) + + See 'Dbx and Dbxtool Interfaces', 2nd edition, by Sun, 1988, for + more information. + + +File: stabs.info, Node: N_BROWS, Next: N_DEFD, Prev: N_M2C, Up: Expanded Reference + +D.5 N_BROWS +=========== + + -- .stabs: N_BROWS + Sun source code browser, path to '.cb' file + + <> "path to associated '.cb' file" + + Note: N_BROWS has the same value as N_BSLINE. + + +File: stabs.info, Node: N_DEFD, Next: N_EHDECL, Prev: N_BROWS, Up: Expanded Reference + +D.6 N_DEFD +========== + + -- .stabn: N_DEFD + GNU Modula2 definition module dependency. + + GNU Modula-2 definition module dependency. The value is the + modification time of the definition file. The other field is + non-zero if it is imported with the GNU M2 keyword '%INITIALIZE'. + Perhaps 'N_M2C' can be used if there are enough empty fields? + + +File: stabs.info, Node: N_EHDECL, Next: N_MOD2, Prev: N_DEFD, Up: Expanded Reference + +D.7 N_EHDECL +============ + + -- .stabs: N_EHDECL + GNU C++ exception variable <>. + + "STRING is variable name" + + Note: conflicts with 'N_MOD2'. + + +File: stabs.info, Node: N_MOD2, Next: N_CATCH, Prev: N_EHDECL, Up: Expanded Reference + +D.8 N_MOD2 +========== + + -- .stab?: N_MOD2 + Modula2 info "for imc" (according to Ultrix V4.0) + + Note: conflicts with 'N_EHDECL' <> + + +File: stabs.info, Node: N_CATCH, Next: N_SSYM, Prev: N_MOD2, Up: Expanded Reference + +D.9 N_CATCH +=========== + + -- .stabn: N_CATCH + GNU C++ 'catch' clause + + GNU C++ 'catch' clause. The value is its address. The desc field + is nonzero if this entry is immediately followed by a 'CAUGHT' stab + saying what exception was caught. Multiple 'CAUGHT' stabs means + that multiple exceptions can be caught here. If desc is 0, it + means all exceptions are caught here. + + +File: stabs.info, Node: N_SSYM, Next: N_SCOPE, Prev: N_CATCH, Up: Expanded Reference + +D.10 N_SSYM +=========== + + -- .stabn: N_SSYM + Structure or union element. + + The value is the offset in the structure. + + <> + + +File: stabs.info, Node: N_SCOPE, Next: Gould, Prev: N_SSYM, Up: Expanded Reference + +D.11 N_SCOPE +============ + + -- .stab?: N_SCOPE + Modula2 scope information (Sun linker) <> + + +File: stabs.info, Node: Gould, Next: N_LENG, Prev: N_SCOPE, Up: Expanded Reference + +D.12 Non-base registers on Gould systems +======================================== + + -- .stab?: N_NBTEXT + -- .stab?: N_NBDATA + -- .stab?: N_NBBSS + -- .stab?: N_NBSTS + -- .stab?: N_NBLCS + These are used on Gould systems for non-base registers syms. + + However, the following values are not the values used by Gould; + they are the values which GNU has been documenting for these values + for a long time, without actually checking what Gould uses. I + include these values only because perhaps some someone actually did + something with the GNU information (I hope not, why GNU knowingly + assigned wrong values to these in the header file is a complete + mystery to me). + + 240 0xf0 N_NBTEXT ?? + 242 0xf2 N_NBDATA ?? + 244 0xf4 N_NBBSS ?? + 246 0xf6 N_NBSTS ?? + 248 0xf8 N_NBLCS ?? + + +File: stabs.info, Node: N_LENG, Prev: Gould, Up: Expanded Reference + +D.13 N_LENG +=========== + + -- .stabn: N_LENG + Second symbol entry containing a length-value for the preceding + entry. The value is the length. + + +File: stabs.info, Node: Questions, Next: Stab Sections, Prev: Expanded Reference, Up: Top + +Appendix E Questions and Anomalies +********************************** + + * For GNU C stabs defining local and global variables ('N_LSYM' and + 'N_GSYM'), the desc field is supposed to contain the source line + number on which the variable is defined. In reality the desc field + is always 0. (This behavior is defined in 'dbxout.c' and putting a + line number in desc is controlled by '#ifdef WINNING_GDB', which + defaults to false). GDB supposedly uses this information if you + say 'list VAR'. In reality, VAR can be a variable defined in the + program and GDB says 'function VAR not defined'. + + * In GNU C stabs, there seems to be no way to differentiate tag + types: structures, unions, and enums (symbol descriptor 'T') and + typedefs (symbol descriptor 't') defined at file scope from types + defined locally to a procedure or other more local scope. They all + use the 'N_LSYM' stab type. Types defined at procedure scope are + emitted after the 'N_RBRAC' of the preceding function and before + the code of the procedure in which they are defined. This is + exactly the same as types defined in the source file between the + two procedure bodies. GDB over-compensates by placing all types in + block #1, the block for symbols of file scope. This is true for + default, '-ansi' and '-traditional' compiler options. (Bugs + gcc/1063, gdb/1066.) + + * What ends the procedure scope? Is it the proc block's 'N_RBRAC' or + the next 'N_FUN'? (I believe it's the first.) + + +File: stabs.info, Node: Stab Sections, Next: GNU Free Documentation License, Prev: Questions, Up: Top + +Appendix F Using Stabs in Their Own Sections +******************************************** + +Many object file formats allow tools to create object files with custom +sections containing any arbitrary data. For any such object file +format, stabs can be embedded in special sections. This is how stabs +are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs +are used with COFF. + +* Menu: + +* Stab Section Basics:: How to embed stabs in sections +* ELF Linker Relocation:: Sun ELF hacks + + +File: stabs.info, Node: Stab Section Basics, Next: ELF Linker Relocation, Up: Stab Sections + +F.1 How to Embed Stabs in Sections +================================== + +The assembler creates two custom sections, a section named '.stab' which +contains an array of fixed length structures, one struct per stab, and a +section named '.stabstr' containing all the variable length strings that +are referenced by stabs in the '.stab' section. The byte order of the +stabs binary data depends on the object file format. For ELF, it +matches the byte order of the ELF file itself, as determined from the +'EI_DATA' field in the 'e_ident' member of the ELF header. For SOM, it +is always big-endian (is this true??? FIXME). For COFF, it matches the +byte order of the COFF headers. The meaning of the fields is the same +as for a.out (*note Symbol Table Format::), except that the 'n_strx' +field is relative to the strings for the current compilation unit (which +can be found using the synthetic N_UNDF stab described below), rather +than the entire string table. + + The first stab in the '.stab' section for each compilation unit is +synthetic, generated entirely by the assembler, with no corresponding +'.stab' directive as input to the assembler. This stab contains the +following fields: + +'n_strx' + Offset in the '.stabstr' section to the source filename. + +'n_type' + 'N_UNDF'. + +'n_other' + Unused field, always zero. This may eventually be used to hold + overflows from the count in the 'n_desc' field. + +'n_desc' + Count of upcoming symbols, i.e., the number of remaining stabs for + this source file. + +'n_value' + Size of the string table fragment associated with this source file, + in bytes. + + The '.stabstr' section always starts with a null byte (so that string +offsets of zero reference a null string), followed by random length +strings, each of which is null byte terminated. + + The ELF section header for the '.stab' section has its 'sh_link' +member set to the section number of the '.stabstr' section, and the +'.stabstr' section has its ELF section header 'sh_type' member set to +'SHT_STRTAB' to mark it as a string table. SOM and COFF have no way of +linking the sections together or marking them as string tables. + + For COFF, the '.stab' and '.stabstr' sections may be simply +concatenated by the linker. GDB then uses the 'n_desc' fields to figure +out the extent of the original sections. Similarly, the 'n_value' +fields of the header symbols are added together in order to get the +actual position of the strings in a desired '.stabstr' section. +Although this design obviates any need for the linker to relocate or +otherwise manipulate '.stab' and '.stabstr' sections, it also requires +some care to ensure that the offsets are calculated correctly. For +instance, if the linker were to pad in between the '.stabstr' sections +before concatenating, then the offsets to strings in the middle of the +executable's '.stabstr' section would be wrong. + + The GNU linker is able to optimize stabs information by merging +duplicate strings and removing duplicate header file information (*note +Include Files::). When some versions of the GNU linker optimize stabs +in sections, they remove the leading 'N_UNDF' symbol and arranges for +all the 'n_strx' fields to be relative to the start of the '.stabstr' +section. + + +File: stabs.info, Node: ELF Linker Relocation, Prev: Stab Section Basics, Up: Stab Sections + +F.2 Having the Linker Relocate Stabs in ELF +=========================================== + +This section describes some Sun hacks for Stabs in ELF; it does not +apply to COFF or SOM. While GDB no longer supports this hack for Sun +Stabs in ELF, this section is kept to document the issue. + + To keep linking fast, you don't want the linker to have to relocate +very many stabs. Making sure this is done for 'N_SLINE', 'N_RBRAC', and +'N_LBRAC' stabs is the most important thing (see the descriptions of +those stabs for more information). But Sun's stabs in ELF has taken +this further, to make all addresses in the 'n_value' field (functions +and static variables) relative to the source file. For the 'N_SO' +symbol itself, Sun simply omits the address. To find the address of +each section corresponding to a given source file, the compiler puts out +symbols giving the address of each section for a given source file. +Since these are ELF (not stab) symbols, the linker relocates them +correctly without having to touch the stabs section. They are named +'Bbss.bss' for the bss section, 'Ddata.data' for the data section, and +'Drodata.rodata' for the rodata section. For the text section, there is +no such symbol (but there should be, see below). For an example of how +these symbols work, *Note Stab Section Transformations::. GCC does not +provide these symbols; it instead relies on the stabs getting relocated. +Thus addresses which would normally be relative to 'Bbss.bss', etc., are +already relocated. The Sun linker provided with Solaris 2.2 and earlier +relocates stabs using normal ELF relocation information, as it would do +for any section. Sun has been threatening to kludge their linker to not +do this (to speed up linking), even though the correct way to avoid +having the linker do these relocations is to have the compiler no longer +output relocatable values. Last I heard they had been talked out of the +linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With +the Sun compiler this affects 'S' symbol descriptor stabs (*note +Statics::) and functions (*note Procedures::). In the latter case, to +adopt the clean solution (making the value of the stab relative to the +start of the compilation unit), it would be necessary to invent a +'Ttext.text' symbol, analogous to the 'Bbss.bss', etc., symbols. I +recommend this rather than using a zero value and getting the address +from the ELF symbols. + + Finding the correct 'Bbss.bss', etc., symbol is difficult, because +the linker simply concatenates the '.stab' sections from each '.o' file +without including any information about which part of a '.stab' section +comes from which '.o' file. The way GDB use to do this is to look for +an ELF 'STT_FILE' symbol which has the same name as the last component +of the file name from the 'N_SO' symbol in the stabs (for example, if +the file name is '../../gdb/main.c', it looks for an ELF 'STT_FILE' +symbol named 'main.c'). This loses if different files have the same +name (they could be in different directories, a library could have been +copied from one system to another, etc.). It would be much cleaner to +have the 'Bbss.bss' symbols in the stabs themselves. Having the linker +relocate them there is no more work than having the linker relocate ELF +symbols, and it solves the problem of having to associate the ELF and +stab symbols. However, no one has yet designed or implemented such a +scheme. + + +File: stabs.info, Node: GNU Free Documentation License, Next: Symbol Types Index, Prev: Stab Sections, Up: Top + +Appendix G GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: stabs.info, Node: Symbol Types Index, Prev: GNU Free Documentation License, Up: Top + +Symbol Types Index +****************** + +[index] +* Menu: + +* .bb: Block Structure. (line 25) +* .be: Block Structure. (line 25) +* C_BCOMM: Common Blocks. (line 10) +* C_BINCL: Include Files. (line 40) +* C_BLOCK: Block Structure. (line 25) +* C_BSTAT: Statics. (line 31) +* C_DECL, for types: Typedefs. (line 6) +* C_ECOML: Common Blocks. (line 17) +* C_ECOMM: Common Blocks. (line 10) +* C_EINCL: Include Files. (line 40) +* C_ENTRY: Alternate Entry Points. + (line 6) +* C_ESTAT: Statics. (line 31) +* C_FILE: Source Files. (line 53) +* C_FUN: Procedures. (line 17) +* C_GSYM: Global Variables. (line 6) +* C_LSYM: Stack Variables. (line 11) +* C_PSYM: Parameters. (line 12) +* C_RPSYM: Register Parameters. (line 15) +* C_RSYM: Register Variables. (line 6) +* C_STSYM: Statics. (line 31) +* N_BCOMM: Common Blocks. (line 10) +* N_BINCL: Include Files. (line 17) +* N_BROWS: N_BROWS. (line 6) +* N_BROWS <1>: N_BROWS. (line 7) +* N_BSLINE: Line Numbers. (line 12) +* N_CATCH: N_CATCH. (line 6) +* N_CATCH <1>: N_CATCH. (line 7) +* N_DEFD: N_DEFD. (line 6) +* N_DEFD <1>: N_DEFD. (line 7) +* N_DSLINE: Line Numbers. (line 12) +* N_ECOML: Common Blocks. (line 17) +* N_ECOMM: Common Blocks. (line 10) +* N_EHDECL: N_EHDECL. (line 6) +* N_EHDECL <1>: N_EHDECL. (line 7) +* N_EINCL: Include Files. (line 17) +* N_ENTRY: Alternate Entry Points. + (line 6) +* N_EXCL: Include Files. (line 17) +* N_FNAME: Procedures. (line 6) +* N_FUN, for functions: Procedures. (line 6) +* N_FUN, for variables: Statics. (line 12) +* N_GSYM: Global Variables. (line 6) +* N_GSYM, for functions (Sun acc): Procedures. (line 6) +* N_LBRAC: Block Structure. (line 6) +* N_LCSYM: Statics. (line 12) +* N_LENG: N_LENG. (line 6) +* N_LENG <1>: N_LENG. (line 7) +* N_LSYM, for parameter: Local Variable Parameters. + (line 35) +* N_LSYM, for stack variables: Stack Variables. (line 11) +* N_LSYM, for types: Typedefs. (line 6) +* N_M2C: N_M2C. (line 6) +* N_M2C <1>: N_M2C. (line 7) +* N_MAC_DEFINE: Macro define and undefine. + (line 11) +* N_MAC_UNDEF: Macro define and undefine. + (line 14) +* N_MAIN: Main Program. (line 6) +* N_MOD2: N_MOD2. (line 6) +* N_MOD2 <1>: N_MOD2. (line 7) +* N_NBBSS: Gould. (line 8) +* N_NBBSS <1>: Gould. (line 11) +* N_NBDATA: Gould. (line 7) +* N_NBDATA <1>: Gould. (line 11) +* N_NBLCS: Gould. (line 10) +* N_NBLCS <1>: Gould. (line 11) +* N_NBSTS: Gould. (line 9) +* N_NBSTS <1>: Gould. (line 11) +* N_NBTEXT: Gould. (line 6) +* N_NBTEXT <1>: Gould. (line 11) +* N_NOMAP: N_NOMAP. (line 6) +* N_NOMAP <1>: N_NOMAP. (line 7) +* N_NSYMS: N_NSYMS. (line 6) +* N_NSYMS <1>: N_NSYMS. (line 7) +* N_PC: N_PC. (line 6) +* N_PC <1>: N_PC. (line 7) +* N_PSYM: Parameters. (line 12) +* N_RBRAC: Block Structure. (line 6) +* N_ROSYM: Statics. (line 12) +* N_RSYM: Register Variables. (line 6) +* N_RSYM, for parameters: Register Parameters. (line 15) +* N_SCOPE: N_SCOPE. (line 6) +* N_SCOPE <1>: N_SCOPE. (line 7) +* N_SLINE: Line Numbers. (line 6) +* N_SO: Source Files. (line 6) +* N_SOL: Include Files. (line 11) +* N_SSYM: N_SSYM. (line 6) +* N_SSYM <1>: N_SSYM. (line 7) +* N_STSYM: Statics. (line 12) +* N_STSYM, for functions (Sun acc): Procedures. (line 6) + + + +Tag Table: +Node: Top1360 +Node: Overview2407 +Node: Flow3821 +Node: Stabs Format5347 +Node: String Field6909 +Node: C Example12338 +Node: Assembly Code12883 +Node: Program Structure14854 +Node: Main Program15580 +Node: Source Files16141 +Node: Include Files18583 +Node: Line Numbers21248 +Node: Procedures22782 +Node: Nested Procedures28673 +Node: Block Structure29849 +Node: Alternate Entry Points31253 +Node: Constants31986 +Node: Variables35097 +Node: Stack Variables35785 +Node: Global Variables37486 +Node: Register Variables38641 +Node: Common Blocks39463 +Node: Statics40716 +Node: Based Variables43295 +Node: Parameters44681 +Node: Register Parameters46292 +Node: Local Variable Parameters48552 +Node: Reference Parameters51467 +Node: Conformant Arrays52087 +Node: Types52805 +Node: Builtin Types53752 +Node: Traditional Builtin Types54898 +Node: Traditional Integer Types55299 +Node: Traditional Other Types57607 +Node: Builtin Type Descriptors58521 +Node: Negative Type Numbers62021 +Node: Miscellaneous Types68376 +Node: Cross-References70262 +Node: Subranges71937 +Node: Arrays73176 +Node: Strings76401 +Node: Enumerations77463 +Node: Structures79847 +Node: Typedefs82555 +Node: Unions83877 +Node: Function Types85458 +Node: Macro define and undefine87039 +Node: Symbol Tables88612 +Node: Symbol Table Format89064 +Node: Transformations On Symbol Tables90511 +Node: Transformations On Static Variables91865 +Node: Transformations On Global Variables92601 +Node: Stab Section Transformations93845 +Node: Cplusplus95228 +Node: Class Names95811 +Node: Nested Symbols96556 +Node: Basic Cplusplus Types97402 +Node: Simple Classes98962 +Node: Class Instance103255 +Node: Methods103972 +Node: Method Type Descriptor106191 +Node: Member Type Descriptor107391 +Node: Protections108183 +Node: Method Modifiers111273 +Node: Virtual Methods112901 +Node: Inheritance116701 +Node: Virtual Base Classes120397 +Node: Static Members122642 +Node: Stab Types123112 +Node: Non-Stab Symbol Types123736 +Node: Stab Symbol Types125119 +Node: Symbol Descriptors128902 +Node: Type Descriptors131681 +Node: Expanded Reference134893 +Node: N_PC136311 +Node: N_NSYMS136677 +Node: N_NOMAP136916 +Node: N_M2C137220 +Node: N_BROWS137651 +Node: N_DEFD137932 +Node: N_EHDECL138387 +Node: N_MOD2138636 +Node: N_CATCH138871 +Node: N_SSYM139363 +Node: N_SCOPE139646 +Node: Gould139834 +Node: N_LENG140817 +Node: Questions141043 +Node: Stab Sections142685 +Node: Stab Section Basics143295 +Node: ELF Linker Relocation146637 +Node: GNU Free Documentation License150156 +Node: Symbol Types Index175316 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/gdb/doc/stabs.texinfo 16.3-5ubuntu1/gdb/doc/stabs.texinfo --- 16.3-5/gdb/doc/stabs.texinfo 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/gdb/doc/stabs.texinfo 2025-04-20 17:22:05.000000000 +0000 @@ -1 +1,4130 @@ +\input texinfo +@setfilename stabs.info +@setchapternewpage odd +@settitle STABS +@c man begin INCLUDE +@include gdb-cfg.texi +@c man end + +@c @finalout + +@c This is a dir.info fragment to support semi-automated addition of +@c manuals to an info tree. +@dircategory Software development +@direntry +* Stabs: (stabs). The "stabs" debugging information format. +@end direntry + +@copying +Copyright @copyright{} 1992--2024 Free Software Foundation, Inc. +Contributed by Cygnus Support. Written by Julia Menapace, Jim Kingdon, +and David MacKenzie. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the section entitled ``GNU +Free Documentation License''. +@end copying + +@ifnottex +This document describes the stabs debugging symbol tables. + +@insertcopying +@end ifnottex + +@titlepage +@title The ``stabs'' debug format +@author Julia Menapace, Jim Kingdon, David MacKenzie +@author Cygnus Support +@page +@tex +\def\$#1${{#1}} % Kludge: collect RCS revision info without $...$ +\xdef\manvers{\$Revision$} % For use in headers, footers too +{\parskip=0pt +\hfill Cygnus Support\par +\hfill \manvers\par +\hfill \TeX{}info \texinfoversion\par +} +@end tex + +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@ifnottex +@node Top +@top The "stabs" representation of debugging information + +This document describes the stabs debugging format. + +@menu +* Overview:: Overview of stabs +* Program Structure:: Encoding of the structure of the program +* Constants:: Constants +* Variables:: +* Types:: Type definitions +* Macro define and undefine:: Representation of #define and #undef +* Symbol Tables:: Symbol information in symbol tables +* Cplusplus:: Stabs specific to C++ +* Stab Types:: Symbol types in a.out files +* Symbol Descriptors:: Table of symbol descriptors +* Type Descriptors:: Table of type descriptors +* Expanded Reference:: Reference information by stab type +* Questions:: Questions and anomalies +* Stab Sections:: In some object file formats, stabs are + in sections. +* GNU Free Documentation License:: The license for this documentation +* Symbol Types Index:: Index of symbolic stab symbol type names. +@end menu +@end ifnottex + +@contents + +@node Overview +@chapter Overview of Stabs + +@dfn{Stabs} refers to a format for information that describes a program +to a debugger. This format was apparently invented by +Peter Kessler at +the University of California at Berkeley, for the @code{pdx} Pascal +debugger; the format has spread widely since then. + +This document is one of the few published sources of documentation on +stabs. It is believed to be comprehensive for stabs used by C. The +lists of symbol descriptors (@pxref{Symbol Descriptors}) and type +descriptors (@pxref{Type Descriptors}) are believed to be completely +comprehensive. Stabs for COBOL-specific features and for variant +records (used by Pascal and Modula-2) are poorly documented here. + +@c FIXME: Need to document all OS9000 stuff in GDB; see all references +@c to os9k_stabs in stabsread.c. + +Other sources of information on stabs are @cite{Dbx and Dbxtool +Interfaces}, 2nd edition, by Sun, 1988, and @cite{AIX Version 3.2 Files +Reference}, Fourth Edition, September 1992, "dbx Stabstring Grammar" in +the a.out section, page 2-31. This document is believed to incorporate +the information from those two sources except where it explicitly directs +you to them for more information. + +@menu +* Flow:: Overview of debugging information flow +* Stabs Format:: Overview of stab format +* String Field:: The string field +* C Example:: A simple example in C source +* Assembly Code:: The simple example at the assembly level +@end menu + +@node Flow +@section Overview of Debugging Information Flow + +The GNU C compiler compiles C source in a @file{.c} file into assembly +language in a @file{.s} file, which the assembler translates into +a @file{.o} file, which the linker combines with other @file{.o} files and +libraries to produce an executable file. + +With the @samp{-g} option, GCC puts in the @file{.s} file additional +debugging information, which is slightly transformed by the assembler +and linker, and carried through into the final executable. This +debugging information describes features of the source file like line +numbers, the types and scopes of variables, and function names, +parameters, and scopes. + +For some object file formats, the debugging information is encapsulated +in assembler directives known collectively as @dfn{stab} (symbol table) +directives, which are interspersed with the generated code. Stabs are +the native format for debugging information in the a.out and XCOFF +object file formats. The GNU tools can also emit stabs in the COFF and +ECOFF object file formats. + +The assembler adds the information from stabs to the symbol information +it places by default in the symbol table and the string table of the +@file{.o} file it is building. The linker consolidates the @file{.o} +files into one executable file, with one symbol table and one string +table. Debuggers use the symbol and string tables in the executable as +a source of debugging information about the program. + +@node Stabs Format +@section Overview of Stab Format + +There are three overall formats for stab assembler directives, +differentiated by the first word of the stab. The name of the directive +describes which combination of four possible data fields follows. It is +either @code{.stabs} (string), @code{.stabn} (number), or @code{.stabd} +(dot). IBM's XCOFF assembler uses @code{.stabx} (and some other +directives such as @code{.file} and @code{.bi}) instead of +@code{.stabs}, @code{.stabn} or @code{.stabd}. + +The overall format of each class of stab is: + +@example +.stabs "@var{string}",@var{type},@var{other},@var{desc},@var{value} +.stabn @var{type},@var{other},@var{desc},@var{value} +.stabd @var{type},@var{other},@var{desc} +.stabx "@var{string}",@var{value},@var{type},@var{sdb-type} +@end example + +@c what is the correct term for "current file location"? My AIX +@c assembler manual calls it "the value of the current location counter". +For @code{.stabn} and @code{.stabd}, there is no @var{string} (the +@code{n_strx} field is zero; see @ref{Symbol Tables}). For +@code{.stabd}, the @var{value} field is implicit and has the value of +the current file location. For @code{.stabx}, the @var{sdb-type} field +is unused for stabs and can always be set to zero. The @var{other} +field is almost always unused and can be set to zero. + +The number in the @var{type} field gives some basic information about +which type of stab this is (or whether it @emph{is} a stab, as opposed +to an ordinary symbol). Each valid type number defines a different stab +type; further, the stab type defines the exact interpretation of, and +possible values for, any remaining @var{string}, @var{desc}, or +@var{value} fields present in the stab. @xref{Stab Types}, for a list +in numeric order of the valid @var{type} field values for stab directives. + +@node String Field +@section The String Field + +For most stabs the string field holds the meat of the +debugging information. The flexible nature of this field +is what makes stabs extensible. For some stab types the string field +contains only a name. For other stab types the contents can be a great +deal more complex. + +The overall format of the string field for most stab types is: + +@example +"@var{name}:@var{symbol-descriptor} @var{type-information}" +@end example + +@var{name} is the name of the symbol represented by the stab; it can +contain a pair of colons (@pxref{Nested Symbols}). @var{name} can be +omitted, which means the stab represents an unnamed object. For +example, @samp{:t10=*2} defines type 10 as a pointer to type 2, but does +not give the type a name. Omitting the @var{name} field is supported by +AIX dbx and GDB after about version 4.8, but not other debuggers. GCC +sometimes uses a single space as the name instead of omitting the name +altogether; apparently that is supported by most debuggers. + +The @var{symbol-descriptor} following the @samp{:} is an alphabetic +character that tells more specifically what kind of symbol the stab +represents. If the @var{symbol-descriptor} is omitted, but type +information follows, then the stab represents a local variable. For a +list of symbol descriptors, see @ref{Symbol Descriptors}. The @samp{c} +symbol descriptor is an exception in that it is not followed by type +information. @xref{Constants}. + +@var{type-information} is either a @var{type-number}, or +@samp{@var{type-number}=}. A @var{type-number} alone is a type +reference, referring directly to a type that has already been defined. + +The @samp{@var{type-number}=} form is a type definition, where the +number represents a new type which is about to be defined. The type +definition may refer to other types by number, and those type numbers +may be followed by @samp{=} and nested definitions. Also, the Lucid +compiler will repeat @samp{@var{type-number}=} more than once if it +wants to define several type numbers at once. + +In a type definition, if the character that follows the equals sign is +non-numeric then it is a @var{type-descriptor}, and tells what kind of +type is about to be defined. Any other values following the +@var{type-descriptor} vary, depending on the @var{type-descriptor}. +@xref{Type Descriptors}, for a list of @var{type-descriptor} values. If +a number follows the @samp{=} then the number is a @var{type-reference}. +For a full description of types, @ref{Types}. + +A @var{type-number} is often a single number. The GNU and Sun tools +additionally permit a @var{type-number} to be a pair +(@var{file-number},@var{filetype-number}) (the parentheses appear in the +string, and serve to distinguish the two cases). The @var{file-number} +is 0 for the base source file, 1 for the first included file, 2 for the +next, and so on. The @var{filetype-number} is a number starting with +1 which is incremented for each new type defined in the file. +(Separating the file number and the type number permits the +@code{N_BINCL} optimization to succeed more often; see @ref{Include +Files}). + +There is an AIX extension for type attributes. Following the @samp{=} +are any number of type attributes. Each one starts with @samp{@@} and +ends with @samp{;}. Debuggers, including AIX's dbx and GDB 4.10, skip +any type attributes they do not recognize. GDB 4.9 and other versions +of dbx may not do this. Because of a conflict with C@t{++} +(@pxref{Cplusplus}), new attributes should not be defined which begin +with a digit, @samp{(}, or @samp{-}; GDB may be unable to distinguish +those from the C@t{++} type descriptor @samp{@@}. The attributes are: + +@table @code +@item a@var{boundary} +@var{boundary} is an integer specifying the alignment. I assume it +applies to all variables of this type. + +@item p@var{integer} +Pointer class (for checking). Not sure what this means, or how +@var{integer} is interpreted. + +@item P +Indicate this is a packed type, meaning that structure fields or array +elements are placed more closely in memory, to save memory at the +expense of speed. + +@item s@var{size} +Size in bits of a variable of this type. This is fully supported by GDB +4.11 and later. + +@item S +Indicate that this type is a string instead of an array of characters, +or a bitstring instead of a set. It doesn't change the layout of the +data being represented, but does enable the debugger to know which type +it is. + +@item V +Indicate that this type is a vector instead of an array. The only +major difference between vectors and arrays is that vectors are +passed by value instead of by reference (vector coprocessor extension). + +@end table + +All of this can make the string field quite long. All versions of GDB, +and some versions of dbx, can handle arbitrarily long strings. But many +versions of dbx (or assemblers or linkers, I'm not sure which) +cretinously limit the strings to about 80 characters, so compilers which +must work with such systems need to split the @code{.stabs} directive +into several @code{.stabs} directives. Each stab duplicates every field +except the string field. The string field of every stab except the last +is marked as continued with a backslash at the end (in the assembly code +this may be written as a double backslash, depending on the assembler). +Removing the backslashes and concatenating the string fields of each +stab produces the original, long string. Just to be incompatible (or so +they don't have to worry about what the assembler does with +backslashes), AIX can use @samp{?} instead of backslash. + +@node C Example +@section A Simple Example in C Source + +To get the flavor of how stabs describe source information for a C +program, let's look at the simple program: + +@example +main() +@{ + printf("Hello world"); +@} +@end example + +When compiled with @samp{-g}, the program above yields the following +@file{.s} file. Line numbers have been added to make it easier to refer +to parts of the @file{.s} file in the description of the stabs that +follows. + +@node Assembly Code +@section The Simple Example at the Assembly Level + +This simple ``hello world'' example demonstrates several of the stab +types used to describe C language source files. + +@example +1 gcc2_compiled.: +2 .stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 +3 .stabs "hello.c",100,0,0,Ltext0 +4 .text +5 Ltext0: +6 .stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 +7 .stabs "char:t2=r2;0;127;",128,0,0,0 +8 .stabs "long int:t3=r1;-2147483648;2147483647;",128,0,0,0 +9 .stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 +10 .stabs "long unsigned int:t5=r1;0;-1;",128,0,0,0 +11 .stabs "short int:t6=r1;-32768;32767;",128,0,0,0 +12 .stabs "long long int:t7=r1;0;-1;",128,0,0,0 +13 .stabs "short unsigned int:t8=r1;0;65535;",128,0,0,0 +14 .stabs "long long unsigned int:t9=r1;0;-1;",128,0,0,0 +15 .stabs "signed char:t10=r1;-128;127;",128,0,0,0 +16 .stabs "unsigned char:t11=r1;0;255;",128,0,0,0 +17 .stabs "float:t12=r1;4;0;",128,0,0,0 +18 .stabs "double:t13=r1;8;0;",128,0,0,0 +19 .stabs "long double:t14=r1;8;0;",128,0,0,0 +20 .stabs "void:t15=15",128,0,0,0 +21 .align 4 +22 LC0: +23 .ascii "Hello, world!\12\0" +24 .align 4 +25 .global _main +26 .proc 1 +27 _main: +28 .stabn 68,0,4,LM1 +29 LM1: +30 !#PROLOGUE# 0 +31 save %sp,-136,%sp +32 !#PROLOGUE# 1 +33 call ___main,0 +34 nop +35 .stabn 68,0,5,LM2 +36 LM2: +37 LBB2: +38 sethi %hi(LC0),%o1 +39 or %o1,%lo(LC0),%o0 +40 call _printf,0 +41 nop +42 .stabn 68,0,6,LM3 +43 LM3: +44 LBE2: +45 .stabn 68,0,6,LM4 +46 LM4: +47 L1: +48 ret +49 restore +50 .stabs "main:F1",36,0,0,_main +51 .stabn 192,0,0,LBB2 +52 .stabn 224,0,0,LBE2 +@end example + +@node Program Structure +@chapter Encoding the Structure of the Program + +The elements of the program structure that stabs encode include the name +of the main function, the names of the source and include files, the +line numbers, procedure names and types, and the beginnings and ends of +blocks of code. + +@menu +* Main Program:: Indicate what the main program is +* Source Files:: The path and name of the source file +* Include Files:: Names of include files +* Line Numbers:: +* Procedures:: +* Nested Procedures:: +* Block Structure:: +* Alternate Entry Points:: Entering procedures except at the beginning. +@end menu + +@node Main Program +@section Main Program + +@findex N_MAIN +Most languages allow the main program to have any name. The +@code{N_MAIN} stab type tells the debugger the name that is used in this +program. Only the string field is significant; it is the name of +a function which is the main program. Most C compilers do not use this +stab (they expect the debugger to assume that the name is @code{main}), +but some C compilers emit an @code{N_MAIN} stab for the @code{main} +function. I'm not sure how XCOFF handles this. + +@node Source Files +@section Paths and Names of the Source Files + +@findex N_SO +Before any other stabs occur, there must be a stab specifying the source +file. This information is contained in a symbol of stab type +@code{N_SO}; the string field contains the name of the file. The +value of the symbol is the start address of the portion of the +text section corresponding to that file. + +Some compilers use the desc field to indicate the language of the +source file. Sun's compilers started this usage, and the first +constants are derived from their documentation. Languages added +by gcc/gdb start at 0x32 to avoid conflict with languages Sun may +add in the future. A desc field with a value 0 indicates that no +language has been specified via this mechanism. + +@table @asis +@item @code{N_SO_AS} (0x1) +Assembly language +@item @code{N_SO_C} (0x2) +K&R traditional C +@item @code{N_SO_ANSI_C} (0x3) +ANSI C +@item @code{N_SO_CC} (0x4) +C++ +@item @code{N_SO_FORTRAN} (0x5) +Fortran +@item @code{N_SO_PASCAL} (0x6) +Pascal +@item @code{N_SO_FORTRAN90} (0x7) +Fortran90 +@item @code{N_SO_OBJC} (0x32) +Objective-C +@item @code{N_SO_OBJCPLUS} (0x33) +Objective-C++ +@end table + +Some compilers (for example, GCC2 and SunOS4 @file{/bin/cc}) also +include the directory in which the source was compiled, in a second +@code{N_SO} symbol preceding the one containing the file name. This +symbol can be distinguished by the fact that it ends in a slash. Code +from the @code{cfront} C@t{++} compiler can have additional @code{N_SO} symbols for +nonexistent source files after the @code{N_SO} for the real source file; +these are believed to contain no useful information. + +For example: + +@example +.stabs "/cygint/s1/users/jcm/play/",100,0,0,Ltext0 # @r{100 is N_SO} +.stabs "hello.c",100,0,0,Ltext0 + .text +Ltext0: +@end example + +@findex C_FILE +Instead of @code{N_SO} symbols, XCOFF uses a @code{.file} assembler +directive which assembles to a @code{C_FILE} symbol; explaining this in +detail is outside the scope of this document. + +@c FIXME: Exactly when should the empty N_SO be used? Why? +If it is useful to indicate the end of a source file, this is done with +an @code{N_SO} symbol with an empty string for the name. The value is +the address of the end of the text section for the file. For some +systems, there is no indication of the end of a source file, and you +just need to figure it ended when you see an @code{N_SO} for a different +source file, or a symbol ending in @code{.o} (which at least some +linkers insert to mark the start of a new @code{.o} file). + +@node Include Files +@section Names of Include Files + +There are several schemes for dealing with include files: the +traditional @code{N_SOL} approach, Sun's @code{N_BINCL} approach, and the +XCOFF @code{C_BINCL} approach (which despite the similar name has little in +common with @code{N_BINCL}). + +@findex N_SOL +An @code{N_SOL} symbol specifies which include file subsequent symbols +refer to. The string field is the name of the file and the value is the +text address corresponding to the end of the previous include file and +the start of this one. To specify the main source file again, use an +@code{N_SOL} symbol with the name of the main source file. + +@findex N_BINCL +@findex N_EINCL +@findex N_EXCL +The @code{N_BINCL} approach works as follows. An @code{N_BINCL} symbol +specifies the start of an include file. In an object file, only the +string is significant; the linker puts data into some of the other +fields. The end of the include file is marked by an @code{N_EINCL} +symbol (which has no string field). In an object file, there is no +significant data in the @code{N_EINCL} symbol. @code{N_BINCL} and +@code{N_EINCL} can be nested. + +If the linker detects that two source files have identical stabs between +an @code{N_BINCL} and @code{N_EINCL} pair (as will generally be the case +for a header file), then it only puts out the stabs once. Each +additional occurrence is replaced by an @code{N_EXCL} symbol. I believe +the GNU linker and the Sun (both SunOS4 and Solaris) linker are the only +ones which supports this feature. + +A linker which supports this feature will set the value of a +@code{N_BINCL} symbol to the total of all the characters in the stabs +strings included in the header file, omitting any file numbers. The +value of an @code{N_EXCL} symbol is the same as the value of the +@code{N_BINCL} symbol it replaces. This information can be used to +match up @code{N_EXCL} and @code{N_BINCL} symbols which have the same +filename. The @code{N_EINCL} value, and the values of the other and +description fields for all three, appear to always be zero. + +@findex C_BINCL +@findex C_EINCL +For the start of an include file in XCOFF, use the @file{.bi} assembler +directive, which generates a @code{C_BINCL} symbol. A @file{.ei} +directive, which generates a @code{C_EINCL} symbol, denotes the end of +the include file. Both directives are followed by the name of the +source file in quotes, which becomes the string for the symbol. +The value of each symbol, produced automatically by the assembler +and linker, is the offset into the executable of the beginning +(inclusive, as you'd expect) or end (inclusive, as you would not expect) +of the portion of the COFF line table that corresponds to this include +file. @code{C_BINCL} and @code{C_EINCL} do not nest. + +@node Line Numbers +@section Line Numbers + +@findex N_SLINE +An @code{N_SLINE} symbol represents the start of a source line. The +desc field contains the line number and the value contains the code +address for the start of that source line. On most machines the address +is absolute; for stabs in sections (@pxref{Stab Sections}), it is +relative to the function in which the @code{N_SLINE} symbol occurs. + +@findex N_DSLINE +@findex N_BSLINE +GNU documents @code{N_DSLINE} and @code{N_BSLINE} symbols for line +numbers in the data or bss segments, respectively. They are identical +to @code{N_SLINE} but are relocated differently by the linker. They +were intended to be used to describe the source location of a variable +declaration, but I believe that GCC2 actually puts the line number in +the desc field of the stab for the variable itself. GDB has been +ignoring these symbols (unless they contain a string field) since +at least GDB 3.5. + +For single source lines that generate discontiguous code, such as flow +of control statements, there may be more than one line number entry for +the same source line. In this case there is a line number entry at the +start of each code range, each with the same line number. + +XCOFF does not use stabs for line numbers. Instead, it uses COFF line +numbers (which are outside the scope of this document). Standard COFF +line numbers cannot deal with include files, but in XCOFF this is fixed +with the @code{C_BINCL} method of marking include files (@pxref{Include +Files}). + +@node Procedures +@section Procedures + +@findex N_FUN, for functions +@findex N_FNAME +@findex N_STSYM, for functions (Sun acc) +@findex N_GSYM, for functions (Sun acc) +All of the following stabs normally use the @code{N_FUN} symbol type. +However, Sun's @code{acc} compiler on SunOS4 uses @code{N_GSYM} and +@code{N_STSYM}, which means that the value of the stab for the function +is useless and the debugger must get the address of the function from +the non-stab symbols instead. On systems where non-stab symbols have +leading underscores, the stabs will lack underscores and the debugger +needs to know about the leading underscore to match up the stab and the +non-stab symbol. BSD Fortran is said to use @code{N_FNAME} with the +same restriction; the value of the symbol is not useful (I'm not sure it +really does use this, because GDB doesn't handle this and no one has +complained). + +@findex C_FUN +A function is represented by an @samp{F} symbol descriptor for a global +(extern) function, and @samp{f} for a static (local) function. For +a.out, the value of the symbol is the address of the start of the +function; it is already relocated. For stabs in ELF, the SunPRO +compiler version 2.0.1 and GCC put out an address which gets relocated +by the linker. In a future release SunPRO is planning to put out zero, +in which case the address can be found from the ELF (non-stab) symbol. +Because looking things up in the ELF symbols would probably be slow, I'm +not sure how to find which symbol of that name is the right one, and +this doesn't provide any way to deal with nested functions, it would +probably be better to make the value of the stab an address relative to +the start of the file, or just absolute. See @ref{ELF Linker +Relocation} for more information on linker relocation of stabs in ELF +files. For XCOFF, the stab uses the @code{C_FUN} storage class and the +value of the stab is meaningless; the address of the function can be +found from the csect symbol (XTY_LD/XMC_PR). + +The type information of the stab represents the return type of the +function; thus @samp{foo:f5} means that foo is a function returning type +5. There is no need to try to get the line number of the start of the +function from the stab for the function; it is in the next +@code{N_SLINE} symbol. + +@c FIXME: verify whether the "I suspect" below is true or not. +Some compilers (such as Sun's Solaris compiler) support an extension for +specifying the types of the arguments. I suspect this extension is not +used for old (non-prototyped) function definitions in C. If the +extension is in use, the type information of the stab for the function +is followed by type information for each argument, with each argument +preceded by @samp{;}. An argument type of 0 means that additional +arguments are being passed, whose types and number may vary (@samp{...} +in ANSI C). GDB has tolerated this extension (parsed the syntax, if not +necessarily used the information) since at least version 4.8; I don't +know whether all versions of dbx tolerate it. The argument types given +here are not redundant with the symbols for the formal parameters +(@pxref{Parameters}); they are the types of the arguments as they are +passed, before any conversions might take place. For example, if a C +function which is declared without a prototype takes a @code{float} +argument, the value is passed as a @code{double} but then converted to a +@code{float}. Debuggers need to use the types given in the arguments +when printing values, but when calling the function they need to use the +types given in the symbol defining the function. + +If the return type and types of arguments of a function which is defined +in another source file are specified (i.e., a function prototype in ANSI +C), traditionally compilers emit no stab; the only way for the debugger +to find the information is if the source file where the function is +defined was also compiled with debugging symbols. As an extension the +Solaris compiler uses symbol descriptor @samp{P} followed by the return +type of the function, followed by the arguments, each preceded by +@samp{;}, as in a stab with symbol descriptor @samp{f} or @samp{F}. +This use of symbol descriptor @samp{P} can be distinguished from its use +for register parameters (@pxref{Register Parameters}) by the fact that it has +symbol type @code{N_FUN}. + +The AIX documentation also defines symbol descriptor @samp{J} as an +internal function. I assume this means a function nested within another +function. It also says symbol descriptor @samp{m} is a module in +Modula-2 or extended Pascal. + +Procedures (functions which do not return values) are represented as +functions returning the @code{void} type in C. I don't see why this couldn't +be used for all languages (inventing a @code{void} type for this purpose if +necessary), but the AIX documentation defines @samp{I}, @samp{P}, and +@samp{Q} for internal, global, and static procedures, respectively. +These symbol descriptors are unusual in that they are not followed by +type information. + +The following example shows a stab for a function @code{main} which +returns type number @code{1}. The @code{_main} specified for the value +is a reference to an assembler label which is used to fill in the start +address of the function. + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +@end example + +The stab representing a procedure is located immediately following the +code of the procedure. This stab is in turn directly followed by a +group of other stabs describing elements of the procedure. These other +stabs describe the procedure's parameters, its block local variables, and +its block structure. + +If functions can appear in different sections, then the debugger may not +be able to find the end of a function. Recent versions of GCC will mark +the end of a function with an @code{N_FUN} symbol with an empty string +for the name. The value is the address of the end of the current +function. Without such a symbol, there is no indication of the address +of the end of a function, and you must assume that it ended at the +starting address of the next function or at the end of the text section +for the program. + +@node Nested Procedures +@section Nested Procedures + +For any of the symbol descriptors representing procedures, after the +symbol descriptor and the type information is optionally a scope +specifier. This consists of a comma, the name of the procedure, another +comma, and the name of the enclosing procedure. The first name is local +to the scope specified, and seems to be redundant with the name of the +symbol (before the @samp{:}). This feature is used by GCC, and +presumably Pascal, Modula-2, etc., compilers, for nested functions. + +If procedures are nested more than one level deep, only the immediately +containing scope is specified. For example, this code: + +@example +int +foo (int x) +@{ + int bar (int y) + @{ + int baz (int z) + @{ + return x + y + z; + @} + return baz (x + 2 * y); + @} + return x + bar (3 * x); +@} +@end example + +@noindent +produces the stabs: + +@example +.stabs "baz:f1,baz,bar",36,0,0,_baz.15 # @r{36 is N_FUN} +.stabs "bar:f1,bar,foo",36,0,0,_bar.12 +.stabs "foo:F1",36,0,0,_foo +@end example + +@node Block Structure +@section Block Structure + +@findex N_LBRAC +@findex N_RBRAC +@c For GCC 2.5.8 or so stabs-in-coff, these are absolute instead of +@c function relative (as documented below). But GDB has never been able +@c to deal with that (it had wanted them to be relative to the file, but +@c I just fixed that (between GDB 4.12 and 4.13)), so it is function +@c relative just like ELF and SOM and the below documentation. +The program's block structure is represented by the @code{N_LBRAC} (left +brace) and the @code{N_RBRAC} (right brace) stab types. The variables +defined inside a block precede the @code{N_LBRAC} symbol for most +compilers, including GCC. Other compilers, such as the Convex, Acorn +RISC machine, and Sun @code{acc} compilers, put the variables after the +@code{N_LBRAC} symbol. The values of the @code{N_LBRAC} and +@code{N_RBRAC} symbols are the start and end addresses of the code of +the block, respectively. For most machines, they are relative to the +starting address of this source file. For the Gould NP1, they are +absolute. For stabs in sections (@pxref{Stab Sections}), they are +relative to the function in which they occur. + +The @code{N_LBRAC} and @code{N_RBRAC} stabs that describe the block +scope of a procedure are located after the @code{N_FUN} stab that +represents the procedure itself. + +Sun documents the desc field of @code{N_LBRAC} and +@code{N_RBRAC} symbols as containing the nesting level of the block. +However, dbx seems to not care, and GCC always sets desc to +zero. + +@findex .bb +@findex .be +@findex C_BLOCK +For XCOFF, block scope is indicated with @code{C_BLOCK} symbols. If the +name of the symbol is @samp{.bb}, then it is the beginning of the block; +if the name of the symbol is @samp{.be}; it is the end of the block. + +@node Alternate Entry Points +@section Alternate Entry Points + +@findex N_ENTRY +@findex C_ENTRY +Some languages, like Fortran, have the ability to enter procedures at +some place other than the beginning. One can declare an alternate entry +point. The @code{N_ENTRY} stab is for this; however, the Sun FORTRAN +compiler doesn't use it. According to AIX documentation, only the name +of a @code{C_ENTRY} stab is significant; the address of the alternate +entry point comes from the corresponding external symbol. A previous +revision of this document said that the value of an @code{N_ENTRY} stab +was the address of the alternate entry point, but I don't know the +source for that information. + +@node Constants +@chapter Constants + +The @samp{c} symbol descriptor indicates that this stab represents a +constant. This symbol descriptor is an exception to the general rule +that symbol descriptors are followed by type information. Instead, it +is followed by @samp{=} and one of the following: + +@table @code +@item b @var{value} +Boolean constant. @var{value} is a numeric value; I assume it is 0 for +false or 1 for true. + +@item c @var{value} +Character constant. @var{value} is the numeric value of the constant. + +@item e @var{type-information} , @var{value} +Constant whose value can be represented as integral. +@var{type-information} is the type of the constant, as it would appear +after a symbol descriptor (@pxref{String Field}). @var{value} is the +numeric value of the constant. GDB 4.9 does not actually get the right +value if @var{value} does not fit in a host @code{int}, but it does not +do anything violent, and future debuggers could be extended to accept +integers of any size (whether unsigned or not). This constant type is +usually documented as being only for enumeration constants, but GDB has +never imposed that restriction; I don't know about other debuggers. + +@item i @var{value} +Integer constant. @var{value} is the numeric value. The type is some +sort of generic integer type (for GDB, a host @code{int}); to specify +the type explicitly, use @samp{e} instead. + +@item r @var{value} +Real constant. @var{value} is the real value, which can be @samp{INF} +(optionally preceded by a sign) for infinity, @samp{QNAN} for a quiet +NaN (not-a-number), or @samp{SNAN} for a signalling NaN. If it is a +normal number the format is that accepted by the C library function +@code{atof}. + +@item s @var{string} +String constant. @var{string} is a string enclosed in either @samp{'} +(in which case @samp{'} characters within the string are represented as +@samp{\'} or @samp{"} (in which case @samp{"} characters within the +string are represented as @samp{\"}). + +@item S @var{type-information} , @var{elements} , @var{bits} , @var{pattern} +Set constant. @var{type-information} is the type of the constant, as it +would appear after a symbol descriptor (@pxref{String Field}). +@var{elements} is the number of elements in the set (does this means +how many bits of @var{pattern} are actually used, which would be +redundant with the type, or perhaps the number of bits set in +@var{pattern}? I don't get it), @var{bits} is the number of bits in the +constant (meaning it specifies the length of @var{pattern}, I think), +and @var{pattern} is a hexadecimal representation of the set. AIX +documentation refers to a limit of 32 bytes, but I see no reason why +this limit should exist. This form could probably be used for arbitrary +constants, not just sets; the only catch is that @var{pattern} should be +understood to be target, not host, byte order and format. +@end table + +The boolean, character, string, and set constants are not supported by +GDB 4.9, but it ignores them. GDB 4.8 and earlier gave an error +message and refused to read symbols from the file containing the +constants. + +The above information is followed by @samp{;}. + +@node Variables +@chapter Variables + +Different types of stabs describe the various ways that variables can be +allocated: on the stack, globally, in registers, in common blocks, +statically, or as arguments to a function. + +@menu +* Stack Variables:: Variables allocated on the stack. +* Global Variables:: Variables used by more than one source file. +* Register Variables:: Variables in registers. +* Common Blocks:: Variables statically allocated together. +* Statics:: Variables local to one source file. +* Based Variables:: Fortran pointer based variables. +* Parameters:: Variables for arguments to functions. +@end menu + +@node Stack Variables +@section Automatic Variables Allocated on the Stack + +If a variable's scope is local to a function and its lifetime is only as +long as that function executes (C calls such variables +@dfn{automatic}), it can be allocated in a register (@pxref{Register +Variables}) or on the stack. + +@findex N_LSYM, for stack variables +@findex C_LSYM +Each variable allocated on the stack has a stab with the symbol +descriptor omitted. Since type information should begin with a digit, +@samp{-}, or @samp{(}, only those characters precluded from being used +for symbol descriptors. However, the Acorn RISC machine (ARM) is said +to get this wrong: it puts out a mere type definition here, without the +preceding @samp{@var{type-number}=}. This is a bad idea; there is no +guarantee that type descriptors are distinct from symbol descriptors. +Stabs for stack variables use the @code{N_LSYM} stab type, or +@code{C_LSYM} for XCOFF. + +The value of the stab is the offset of the variable within the +local variables. On most machines this is an offset from the frame +pointer and is negative. The location of the stab specifies which block +it is defined in; see @ref{Block Structure}. + +For example, the following C code: + +@example +int +main () +@{ + int x; +@} +@end example + +produces the following stabs: + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +.stabs "x:1",128,0,0,-12 # @r{128 is N_LSYM} +.stabn 192,0,0,LBB2 # @r{192 is N_LBRAC} +.stabn 224,0,0,LBE2 # @r{224 is N_RBRAC} +@end example + +See @ref{Procedures} for more information on the @code{N_FUN} stab, and +@ref{Block Structure} for more information on the @code{N_LBRAC} and +@code{N_RBRAC} stabs. + +@node Global Variables +@section Global Variables + +@findex N_GSYM +@findex C_GSYM +@c FIXME: verify for sure that it really is C_GSYM on XCOFF +A variable whose scope is not specific to just one source file is +represented by the @samp{G} symbol descriptor. These stabs use the +@code{N_GSYM} stab type (C_GSYM for XCOFF). The type information for +the stab (@pxref{String Field}) gives the type of the variable. + +For example, the following source code: + +@example +char g_foo = 'c'; +@end example + +@noindent +yields the following assembly code: + +@example +.stabs "g_foo:G2",32,0,0,0 # @r{32 is N_GSYM} + .global _g_foo + .data +_g_foo: + .byte 99 +@end example + +The address of the variable represented by the @code{N_GSYM} is not +contained in the @code{N_GSYM} stab. The debugger gets this information +from the external symbol for the global variable. In the example above, +the @code{.global _g_foo} and @code{_g_foo:} lines tell the assembler to +produce an external symbol. + +Some compilers, like GCC, output @code{N_GSYM} stabs only once, where +the variable is defined. Other compilers, like SunOS4 /bin/cc, output a +@code{N_GSYM} stab for each compilation unit which references the +variable. + +@node Register Variables +@section Register Variables + +@findex N_RSYM +@findex C_RSYM +@c According to an old version of this manual, AIX uses C_RPSYM instead +@c of C_RSYM. I am skeptical; this should be verified. +Register variables have their own stab type, @code{N_RSYM} +(@code{C_RSYM} for XCOFF), and their own symbol descriptor, @samp{r}. +The stab's value is the number of the register where the variable data +will be stored. +@c .stabs "name:type",N_RSYM,0,RegSize,RegNumber (Sun doc) + +AIX defines a separate symbol descriptor @samp{d} for floating point +registers. This seems unnecessary; why not just just give floating +point registers different register numbers? I have not verified whether +the compiler actually uses @samp{d}. + +If the register is explicitly allocated to a global variable, but not +initialized, as in: + +@example +register int g_bar asm ("%g5"); +@end example + +@noindent +then the stab may be emitted at the end of the object file, with +the other bss symbols. + +@node Common Blocks +@section Common Blocks + +A common block is a statically allocated section of memory which can be +referred to by several source files. It may contain several variables. +I believe Fortran is the only language with this feature. + +@findex N_BCOMM +@findex N_ECOMM +@findex C_BCOMM +@findex C_ECOMM +A @code{N_BCOMM} stab begins a common block and an @code{N_ECOMM} stab +ends it. The only field that is significant in these two stabs is the +string, which names a normal (non-debugging) symbol that gives the +address of the common block. According to IBM documentation, only the +@code{N_BCOMM} has the name of the common block (even though their +compiler actually puts it both places). + +@findex N_ECOML +@findex C_ECOML +The stabs for the members of the common block are between the +@code{N_BCOMM} and the @code{N_ECOMM}; the value of each stab is the +offset within the common block of that variable. IBM uses the +@code{C_ECOML} stab type, and there is a corresponding @code{N_ECOML} +stab type, but Sun's Fortran compiler uses @code{N_GSYM} instead. The +variables within a common block use the @samp{V} symbol descriptor (I +believe this is true of all Fortran variables). Other stabs (at least +type declarations using @code{C_DECL}) can also be between the +@code{N_BCOMM} and the @code{N_ECOMM}. + +@node Statics +@section Static Variables + +Initialized static variables are represented by the @samp{S} and +@samp{V} symbol descriptors. @samp{S} means file scope static, and +@samp{V} means procedure scope static. One exception: in XCOFF, IBM's +xlc compiler always uses @samp{V}, and whether it is file scope or not +is distinguished by whether the stab is located within a function. + +@c This is probably not worth mentioning; it is only true on the sparc +@c for `double' variables which although declared const are actually in +@c the data segment (the text segment can't guarantee 8 byte alignment). +@c (although GCC +@c 2.4.5 has a bug in that it uses @code{N_FUN}, so neither dbx nor GDB can +@c find the variables) +@findex N_STSYM +@findex N_LCSYM +@findex N_FUN, for variables +@findex N_ROSYM +In a.out files, @code{N_STSYM} means the data section, @code{N_FUN} +means the text section, and @code{N_LCSYM} means the bss section. For +those systems with a read-only data section separate from the text +section (Solaris), @code{N_ROSYM} means the read-only data section. + +For example, the source lines: + +@example +static const int var_const = 5; +static int var_init = 2; +static int var_noinit; +@end example + +@noindent +yield the following stabs: + +@example +.stabs "var_const:S1",36,0,0,_var_const # @r{36 is N_FUN} +@dots{} +.stabs "var_init:S1",38,0,0,_var_init # @r{38 is N_STSYM} +@dots{} +.stabs "var_noinit:S1",40,0,0,_var_noinit # @r{40 is N_LCSYM} +@end example + +@findex C_STSYM +@findex C_BSTAT +@findex C_ESTAT +In XCOFF files, the stab type need not indicate the section; +@code{C_STSYM} can be used for all statics. Also, each static variable +is enclosed in a static block. A @code{C_BSTAT} (emitted with a +@samp{.bs} assembler directive) symbol begins the static block; its +value is the symbol number of the csect symbol whose value is the +address of the static block, its section is the section of the variables +in that static block, and its name is @samp{.bs}. A @code{C_ESTAT} +(emitted with a @samp{.es} assembler directive) symbol ends the static +block; its name is @samp{.es} and its value and section are ignored. + +In ECOFF files, the storage class is used to specify the section, so the +stab type need not indicate the section. + +In ELF files, for the SunPRO compiler version 2.0.1, symbol descriptor +@samp{S} means that the address is absolute (the linker relocates it) +and symbol descriptor @samp{V} means that the address is relative to the +start of the relevant section for that compilation unit. SunPRO has +plans to have the linker stop relocating stabs; I suspect that their the +debugger gets the address from the corresponding ELF (not stab) symbol. +I'm not sure how to find which symbol of that name is the right one. +The clean way to do all this would be to have the value of a symbol +descriptor @samp{S} symbol be an offset relative to the start of the +file, just like everything else, but that introduces obvious +compatibility problems. For more information on linker stab relocation, +@xref{ELF Linker Relocation}. + +@node Based Variables +@section Fortran Based Variables + +Fortran (at least, the Sun and SGI dialects of FORTRAN-77) has a feature +which allows allocating arrays with @code{malloc}, but which avoids +blurring the line between arrays and pointers the way that C does. In +stabs such a variable uses the @samp{b} symbol descriptor. + +For example, the Fortran declarations + +@example +real foo, foo10(10), foo10_5(10,5) +pointer (foop, foo) +pointer (foo10p, foo10) +pointer (foo105p, foo10_5) +@end example + +produce the stabs + +@example +foo:b6 +foo10:bar3;1;10;6 +foo10_5:bar3;1;5;ar3;1;10;6 +@end example + +In this example, @code{real} is type 6 and type 3 is an integral type +which is the type of the subscripts of the array (probably +@code{integer}). + +The @samp{b} symbol descriptor is like @samp{V} in that it denotes a +statically allocated symbol whose scope is local to a function; see +@xref{Statics}. The value of the symbol, instead of being the address +of the variable itself, is the address of a pointer to that variable. +So in the above example, the value of the @code{foo} stab is the address +of a pointer to a real, the value of the @code{foo10} stab is the +address of a pointer to a 10-element array of reals, and the value of +the @code{foo10_5} stab is the address of a pointer to a 5-element array +of 10-element arrays of reals. + +@node Parameters +@section Parameters + +Formal parameters to a function are represented by a stab (or sometimes +two; see below) for each parameter. The stabs are in the order in which +the debugger should print the parameters (i.e., the order in which the +parameters are declared in the source file). The exact form of the stab +depends on how the parameter is being passed. + +@findex N_PSYM +@findex C_PSYM +Parameters passed on the stack use the symbol descriptor @samp{p} and +the @code{N_PSYM} symbol type (or @code{C_PSYM} for XCOFF). The value +of the symbol is an offset used to locate the parameter on the stack; +its exact meaning is machine-dependent, but on most machines it is an +offset from the frame pointer. + +As a simple example, the code: + +@example +main (argc, argv) + int argc; + char **argv; +@end example + +produces the stabs: + +@example +.stabs "main:F1",36,0,0,_main # @r{36 is N_FUN} +.stabs "argc:p1",160,0,0,68 # @r{160 is N_PSYM} +.stabs "argv:p20=*21=*2",160,0,0,72 +@end example + +The type definition of @code{argv} is interesting because it contains +several type definitions. Type 21 is pointer to type 2 (char) and +@code{argv} (type 20) is pointer to type 21. + +@c FIXME: figure out what these mean and describe them coherently. +The following symbol descriptors are also said to go with @code{N_PSYM}. +The value of the symbol is said to be an offset from the argument +pointer (I'm not sure whether this is true or not). + +@example +pP (<>) +pF Fortran function parameter +X (function result variable) +@end example + +@menu +* Register Parameters:: +* Local Variable Parameters:: +* Reference Parameters:: +* Conformant Arrays:: +@end menu + +@node Register Parameters +@subsection Passing Parameters in Registers + +If the parameter is passed in a register, then traditionally there are +two symbols for each argument: + +@example +.stabs "arg:p1" . . . ; N_PSYM +.stabs "arg:r1" . . . ; N_RSYM +@end example + +Debuggers use the second one to find the value, and the first one to +know that it is an argument. + +@findex C_RPSYM +@findex N_RSYM, for parameters +Because that approach is kind of ugly, some compilers use symbol +descriptor @samp{P} or @samp{R} to indicate an argument which is in a +register. Symbol type @code{C_RPSYM} is used in XCOFF and @code{N_RSYM} +is used otherwise. The symbol's value is the register number. @samp{P} +and @samp{R} mean the same thing; the difference is that @samp{P} is a +GNU invention and @samp{R} is an IBM (XCOFF) invention. As of version +4.9, GDB should handle either one. + +There is at least one case where GCC uses a @samp{p} and @samp{r} pair +rather than @samp{P}; this is where the argument is passed in the +argument list and then loaded into a register. + +According to the AIX documentation, symbol descriptor @samp{D} is for a +parameter passed in a floating point register. This seems +unnecessary---why not just use @samp{R} with a register number which +indicates that it's a floating point register? I haven't verified +whether the system actually does what the documentation indicates. + +@c FIXME: On the hppa this is for any type > 8 bytes, I think, and not +@c for small structures (investigate). +On the sparc and hppa, for a @samp{P} symbol whose type is a structure +or union, the register contains the address of the structure. On the +sparc, this is also true of a @samp{p} and @samp{r} pair (using Sun +@code{cc}) or a @samp{p} symbol. However, if a (small) structure is +really in a register, @samp{r} is used. And, to top it all off, on the +hppa it might be a structure which was passed on the stack and loaded +into a register and for which there is a @samp{p} and @samp{r} pair! I +believe that symbol descriptor @samp{i} is supposed to deal with this +case (it is said to mean "value parameter by reference, indirect +access"; I don't know the source for this information), but I don't know +details or what compilers or debuggers use it, if any (not GDB or GCC). +It is not clear to me whether this case needs to be dealt with +differently than parameters passed by reference (@pxref{Reference Parameters}). + +@node Local Variable Parameters +@subsection Storing Parameters as Local Variables + +There is a case similar to an argument in a register, which is an +argument that is actually stored as a local variable. Sometimes this +happens when the argument was passed in a register and then the compiler +stores it as a local variable. If possible, the compiler should claim +that it's in a register, but this isn't always done. + +If a parameter is passed as one type and converted to a smaller type by +the prologue (for example, the parameter is declared as a @code{float}, +but the calling conventions specify that it is passed as a +@code{double}), then GCC2 (sometimes) uses a pair of symbols. The first +symbol uses symbol descriptor @samp{p} and the type which is passed. +The second symbol has the type and location which the parameter actually +has after the prologue. For example, suppose the following C code +appears with no prototypes involved: + +@example +void +subr (f) + float f; +@{ +@end example + +if @code{f} is passed as a double at stack offset 8, and the prologue +converts it to a float in register number 0, then the stabs look like: + +@example +.stabs "f:p13",160,0,3,8 # @r{160 is @code{N_PSYM}, here 13 is @code{double}} +.stabs "f:r12",64,0,3,0 # @r{64 is @code{N_RSYM}, here 12 is @code{float}} +@end example + +In both stabs 3 is the line number where @code{f} is declared +(@pxref{Line Numbers}). + +@findex N_LSYM, for parameter +GCC, at least on the 960, has another solution to the same problem. It +uses a single @samp{p} symbol descriptor for an argument which is stored +as a local variable but uses @code{N_LSYM} instead of @code{N_PSYM}. In +this case, the value of the symbol is an offset relative to the local +variables for that function, not relative to the arguments; on some +machines those are the same thing, but not on all. + +@c This is mostly just background info; the part that logically belongs +@c here is the last sentence. +On the VAX or on other machines in which the calling convention includes +the number of words of arguments actually passed, the debugger (GDB at +least) uses the parameter symbols to keep track of whether it needs to +print nameless arguments in addition to the formal parameters which it +has printed because each one has a stab. For example, in + +@example +extern int fprintf (FILE *stream, char *format, @dots{}); +@dots{} +fprintf (stdout, "%d\n", x); +@end example + +there are stabs for @code{stream} and @code{format}. On most machines, +the debugger can only print those two arguments (because it has no way +of knowing that additional arguments were passed), but on the VAX or +other machines with a calling convention which indicates the number of +words of arguments, the debugger can print all three arguments. To do +so, the parameter symbol (symbol descriptor @samp{p}) (not necessarily +@samp{r} or symbol descriptor omitted symbols) needs to contain the +actual type as passed (for example, @code{double} not @code{float} if it +is passed as a double and converted to a float). + +@node Reference Parameters +@subsection Passing Parameters by Reference + +If the parameter is passed by reference (e.g., Pascal @code{VAR} +parameters), then the symbol descriptor is @samp{v} if it is in the +argument list, or @samp{a} if it in a register. Other than the fact +that these contain the address of the parameter rather than the +parameter itself, they are identical to @samp{p} and @samp{R}, +respectively. I believe @samp{a} is an AIX invention; @samp{v} is +supported by all stabs-using systems as far as I know. + +@node Conformant Arrays +@subsection Passing Conformant Array Parameters + +@c Is this paragraph correct? It is based on piecing together patchy +@c information and some guesswork +Conformant arrays are a feature of Modula-2, and perhaps other +languages, in which the size of an array parameter is not known to the +called function until run-time. Such parameters have two stabs: a +@samp{x} for the array itself, and a @samp{C}, which represents the size +of the array. The value of the @samp{x} stab is the offset in the +argument list where the address of the array is stored (it this right? +it is a guess); the value of the @samp{C} stab is the offset in the +argument list where the size of the array (in elements? in bytes?) is +stored. + +@node Types +@chapter Defining Types + +The examples so far have described types as references to previously +defined types, or defined in terms of subranges of or pointers to +previously defined types. This chapter describes the other type +descriptors that may follow the @samp{=} in a type definition. + +@menu +* Builtin Types:: Integers, floating point, void, etc. +* Miscellaneous Types:: Pointers, sets, files, etc. +* Cross-References:: Referring to a type not yet defined. +* Subranges:: A type with a specific range. +* Arrays:: An aggregate type of same-typed elements. +* Strings:: Like an array but also has a length. +* Enumerations:: Like an integer but the values have names. +* Structures:: An aggregate type of different-typed elements. +* Typedefs:: Giving a type a name. +* Unions:: Different types sharing storage. +* Function Types:: +@end menu + +@node Builtin Types +@section Builtin Types + +Certain types are built in (@code{int}, @code{short}, @code{void}, +@code{float}, etc.); the debugger recognizes these types and knows how +to handle them. Thus, don't be surprised if some of the following ways +of specifying builtin types do not specify everything that a debugger +would need to know about the type---in some cases they merely specify +enough information to distinguish the type from other types. + +The traditional way to define builtin types is convoluted, so new ways +have been invented to describe them. Sun's @code{acc} uses special +builtin type descriptors (@samp{b} and @samp{R}), and IBM uses negative +type numbers. GDB accepts all three ways, as of version 4.8; dbx just +accepts the traditional builtin types and perhaps one of the other two +formats. The following sections describe each of these formats. + +@menu +* Traditional Builtin Types:: Put on your seat belts and prepare for kludgery +* Builtin Type Descriptors:: Builtin types with special type descriptors +* Negative Type Numbers:: Builtin types using negative type numbers +@end menu + +@node Traditional Builtin Types +@subsection Traditional Builtin Types + +This is the traditional, convoluted method for defining builtin types. +There are several classes of such type definitions: integer, floating +point, and @code{void}. + +@menu +* Traditional Integer Types:: +* Traditional Other Types:: +@end menu + +@node Traditional Integer Types +@subsubsection Traditional Integer Types + +Often types are defined as subranges of themselves. If the bounding values +fit within an @code{int}, then they are given normally. For example: + +@example +.stabs "int:t1=r1;-2147483648;2147483647;",128,0,0,0 # @r{128 is N_LSYM} +.stabs "char:t2=r2;0;127;",128,0,0,0 +@end example + +Builtin types can also be described as subranges of @code{int}: + +@example +.stabs "unsigned short:t6=r1;0;65535;",128,0,0,0 +@end example + +If the lower bound of a subrange is 0 and the upper bound is -1, +the type is an unsigned integral type whose bounds are too +big to describe in an @code{int}. Traditionally this is only used for +@code{unsigned int} and @code{unsigned long}: + +@example +.stabs "unsigned int:t4=r1;0;-1;",128,0,0,0 +@end example + +For larger types, GCC 2.4.5 puts out bounds in octal, with one or more +leading zeroes. In this case a negative bound consists of a number +which is a 1 bit (for the sign bit) followed by a 0 bit for each bit in +the number (except the sign bit), and a positive bound is one which is a +1 bit for each bit in the number (except possibly the sign bit). All +known versions of dbx and GDB version 4 accept this (at least in the +sense of not refusing to process the file), but GDB 3.5 refuses to read +the whole file containing such symbols. So GCC 2.3.3 did not output the +proper size for these types. As an example of octal bounds, the string +fields of the stabs for 64 bit integer types look like: + +@c .stabs directives, etc., omitted to make it fit on the page. +@example +long int:t3=r1;001000000000000000000000;000777777777777777777777; +long unsigned int:t5=r1;000000000000000000000000;001777777777777777777777; +@end example + +If the lower bound of a subrange is 0 and the upper bound is negative, +the type is an unsigned integral type whose size in bytes is the +absolute value of the upper bound. I believe this is a Convex +convention for @code{unsigned long long}. + +If the lower bound of a subrange is negative and the upper bound is 0, +the type is a signed integral type whose size in bytes is +the absolute value of the lower bound. I believe this is a Convex +convention for @code{long long}. To distinguish this from a legitimate +subrange, the type should be a subrange of itself. I'm not sure whether +this is the case for Convex. + +@node Traditional Other Types +@subsubsection Traditional Other Types + +If the upper bound of a subrange is 0 and the lower bound is positive, +the type is a floating point type, and the lower bound of the subrange +indicates the number of bytes in the type: + +@example +.stabs "float:t12=r1;4;0;",128,0,0,0 +.stabs "double:t13=r1;8;0;",128,0,0,0 +@end example + +However, GCC writes @code{long double} the same way it writes +@code{double}, so there is no way to distinguish. + +@example +.stabs "long double:t14=r1;8;0;",128,0,0,0 +@end example + +Complex types are defined the same way as floating-point types; there is +no way to distinguish a single-precision complex from a double-precision +floating-point type. + +The C @code{void} type is defined as itself: + +@example +.stabs "void:t15=15",128,0,0,0 +@end example + +I'm not sure how a boolean type is represented. + +@node Builtin Type Descriptors +@subsection Defining Builtin Types Using Builtin Type Descriptors + +This is the method used by Sun's @code{acc} for defining builtin types. +These are the type descriptors to define builtin types: + +@table @code +@c FIXME: clean up description of width and offset, once we figure out +@c what they mean +@item b @var{signed} @var{char-flag} @var{width} ; @var{offset} ; @var{nbits} ; +Define an integral type. @var{signed} is @samp{u} for unsigned or +@samp{s} for signed. @var{char-flag} is @samp{c} which indicates this +is a character type, or is omitted. I assume this is to distinguish an +integral type from a character type of the same size, for example it +might make sense to set it for the C type @code{wchar_t} so the debugger +can print such variables differently (Solaris does not do this). Sun +sets it on the C types @code{signed char} and @code{unsigned char} which +arguably is wrong. @var{width} and @var{offset} appear to be for small +objects stored in larger ones, for example a @code{short} in an +@code{int} register. @var{width} is normally the number of bytes in the +type. @var{offset} seems to always be zero. @var{nbits} is the number +of bits in the type. + +Note that type descriptor @samp{b} used for builtin types conflicts with +its use for Pascal space types (@pxref{Miscellaneous Types}); they can +be distinguished because the character following the type descriptor +will be a digit, @samp{(}, or @samp{-} for a Pascal space type, or +@samp{u} or @samp{s} for a builtin type. + +@item w +Documented by AIX to define a wide character type, but their compiler +actually uses negative type numbers (@pxref{Negative Type Numbers}). + +@item R @var{fp-type} ; @var{bytes} ; +Define a floating point type. @var{fp-type} has one of the following values: + +@table @code +@item 1 (NF_SINGLE) +IEEE 32-bit (single precision) floating point format. + +@item 2 (NF_DOUBLE) +IEEE 64-bit (double precision) floating point format. + +@item 3 (NF_COMPLEX) +@item 4 (NF_COMPLEX16) +@item 5 (NF_COMPLEX32) +@c "GDB source" really means @file{include/aout/stab_gnu.h}, but trying +@c to put that here got an overfull hbox. +These are for complex numbers. A comment in the GDB source describes +them as Fortran @code{complex}, @code{double complex}, and +@code{complex*16}, respectively, but what does that mean? (i.e., Single +precision? Double precision?). + +@item 6 (NF_LDOUBLE) +Long double. This should probably only be used for Sun format +@code{long double}, and new codes should be used for other floating +point formats (@code{NF_DOUBLE} can be used if a @code{long double} is +really just an IEEE double, of course). +@end table + +@var{bytes} is the number of bytes occupied by the type. This allows a +debugger to perform some operations with the type even if it doesn't +understand @var{fp-type}. + +@item g @var{type-information} ; @var{nbits} +Documented by AIX to define a floating type, but their compiler actually +uses negative type numbers (@pxref{Negative Type Numbers}). + +@item c @var{type-information} ; @var{nbits} +Documented by AIX to define a complex type, but their compiler actually +uses negative type numbers (@pxref{Negative Type Numbers}). +@end table + +The C @code{void} type is defined as a signed integral type 0 bits long: +@example +.stabs "void:t19=bs0;0;0",128,0,0,0 +@end example +The Solaris compiler seems to omit the trailing semicolon in this case. +Getting sloppy in this way is not a swift move because if a type is +embedded in a more complex expression it is necessary to be able to tell +where it ends. + +I'm not sure how a boolean type is represented. + +@node Negative Type Numbers +@subsection Negative Type Numbers + +This is the method used in XCOFF for defining builtin types. +Since the debugger knows about the builtin types anyway, the idea of +negative type numbers is simply to give a special type number which +indicates the builtin type. There is no stab defining these types. + +There are several subtle issues with negative type numbers. + +One is the size of the type. A builtin type (for example the C types +@code{int} or @code{long}) might have different sizes depending on +compiler options, the target architecture, the ABI, etc. This issue +doesn't come up for IBM tools since (so far) they just target the +RS/6000; the sizes indicated below for each size are what the IBM +RS/6000 tools use. To deal with differing sizes, either define separate +negative type numbers for each size (which works but requires changing +the debugger, and, unless you get both AIX dbx and GDB to accept the +change, introduces an incompatibility), or use a type attribute +(@pxref{String Field}) to define a new type with the appropriate size +(which merely requires a debugger which understands type attributes, +like AIX dbx or GDB). For example, + +@example +.stabs "boolean:t10=@@s8;-16",128,0,0,0 +@end example + +defines an 8-bit boolean type, and + +@example +.stabs "boolean:t10=@@s64;-16",128,0,0,0 +@end example + +defines a 64-bit boolean type. + +A similar issue is the format of the type. This comes up most often for +floating-point types, which could have various formats (particularly +extended doubles, which vary quite a bit even among IEEE systems). +Again, it is best to define a new negative type number for each +different format; changing the format based on the target system has +various problems. One such problem is that the Alpha has both VAX and +IEEE floating types. One can easily imagine one library using the VAX +types and another library in the same executable using the IEEE types. +Another example is that the interpretation of whether a boolean is true +or false can be based on the least significant bit, most significant +bit, whether it is zero, etc., and different compilers (or different +options to the same compiler) might provide different kinds of boolean. + +The last major issue is the names of the types. The name of a given +type depends @emph{only} on the negative type number given; these do not +vary depending on the language, the target system, or anything else. +One can always define separate type numbers---in the following list you +will see for example separate @code{int} and @code{integer*4} types +which are identical except for the name. But compatibility can be +maintained by not inventing new negative type numbers and instead just +defining a new type with a new name. For example: + +@example +.stabs "CARDINAL:t10=-8",128,0,0,0 +@end example + +Here is the list of negative type numbers. The phrase @dfn{integral +type} is used to mean twos-complement (I strongly suspect that all +machines which use stabs use twos-complement; most machines use +twos-complement these days). + +@table @code +@item -1 +@code{int}, 32 bit signed integral type. + +@item -2 +@code{char}, 8 bit type holding a character. Both GDB and dbx on AIX +treat this as signed. GCC uses this type whether @code{char} is signed +or not, which seems like a bad idea. The AIX compiler (@code{xlc}) seems to +avoid this type; it uses -5 instead for @code{char}. + +@item -3 +@code{short}, 16 bit signed integral type. + +@item -4 +@code{long}, 32 bit signed integral type. + +@item -5 +@code{unsigned char}, 8 bit unsigned integral type. + +@item -6 +@code{signed char}, 8 bit signed integral type. + +@item -7 +@code{unsigned short}, 16 bit unsigned integral type. + +@item -8 +@code{unsigned int}, 32 bit unsigned integral type. + +@item -9 +@code{unsigned}, 32 bit unsigned integral type. + +@item -10 +@code{unsigned long}, 32 bit unsigned integral type. + +@item -11 +@code{void}, type indicating the lack of a value. + +@item -12 +@code{float}, IEEE single precision. + +@item -13 +@code{double}, IEEE double precision. + +@item -14 +@code{long double}, IEEE double precision. The compiler claims the size +will increase in a future release, and for binary compatibility you have +to avoid using @code{long double}. I hope when they increase it they +use a new negative type number. + +@item -15 +@code{integer}. 32 bit signed integral type. + +@item -16 +@code{boolean}. 32 bit type. GDB and GCC assume that zero is false, +one is true, and other values have unspecified meaning. I hope this +agrees with how the IBM tools use the type. + +@item -17 +@code{short real}. IEEE single precision. + +@item -18 +@code{real}. IEEE double precision. + +@item -19 +@code{stringptr}. @xref{Strings}. + +@item -20 +@code{character}, 8 bit unsigned character type. + +@item -21 +@code{logical*1}, 8 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -22 +@code{logical*2}, 16 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -23 +@code{logical*4}, 32 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -24 +@code{logical}, 32 bit type. This Fortran type has a split +personality in that it is used for boolean variables, but can also be +used for unsigned integers. 0 is false, 1 is true, and other values are +non-boolean. + +@item -25 +@code{complex}. A complex type consisting of two IEEE single-precision +floating point values. + +@item -26 +@code{complex}. A complex type consisting of two IEEE double-precision +floating point values. + +@item -27 +@code{integer*1}, 8 bit signed integral type. + +@item -28 +@code{integer*2}, 16 bit signed integral type. + +@item -29 +@code{integer*4}, 32 bit signed integral type. + +@item -30 +@code{wchar}. Wide character, 16 bits wide, unsigned (what format? +Unicode?). + +@item -31 +@code{long long}, 64 bit signed integral type. + +@item -32 +@code{unsigned long long}, 64 bit unsigned integral type. + +@item -33 +@code{logical*8}, 64 bit unsigned integral type. + +@item -34 +@code{integer*8}, 64 bit signed integral type. +@end table + +@node Miscellaneous Types +@section Miscellaneous Types + +@table @code +@item b @var{type-information} ; @var{bytes} +Pascal space type. This is documented by IBM; what does it mean? + +This use of the @samp{b} type descriptor can be distinguished +from its use for builtin integral types (@pxref{Builtin Type +Descriptors}) because the character following the type descriptor is +always a digit, @samp{(}, or @samp{-}. + +@item B @var{type-information} +A volatile-qualified version of @var{type-information}. This is +a Sun extension. References and stores to a variable with a +volatile-qualified type must not be optimized or cached; they +must occur as the user specifies them. + +@item d @var{type-information} +File of type @var{type-information}. As far as I know this is only used +by Pascal. + +@item k @var{type-information} +A const-qualified version of @var{type-information}. This is a Sun +extension. A variable with a const-qualified type cannot be modified. + +@item M @var{type-information} ; @var{length} +Multiple instance type. The type seems to composed of @var{length} +repetitions of @var{type-information}, for example @code{character*3} is +represented by @samp{M-2;3}, where @samp{-2} is a reference to a +character type (@pxref{Negative Type Numbers}). I'm not sure how this +differs from an array. This appears to be a Fortran feature. +@var{length} is a bound, like those in range types; see @ref{Subranges}. + +@item S @var{type-information} +Pascal set type. @var{type-information} must be a small type such as an +enumeration or a subrange, and the type is a bitmask whose length is +specified by the number of elements in @var{type-information}. + +In CHILL, if it is a bitstring instead of a set, also use the @samp{S} +type attribute (@pxref{String Field}). + +@item * @var{type-information} +Pointer to @var{type-information}. +@end table + +@node Cross-References +@section Cross-References to Other Types + +A type can be used before it is defined; one common way to deal with +that situation is just to use a type reference to a type which has not +yet been defined. + +Another way is with the @samp{x} type descriptor, which is followed by +@samp{s} for a structure tag, @samp{u} for a union tag, or @samp{e} for +a enumerator tag, followed by the name of the tag, followed by @samp{:}. +If the name contains @samp{::} between a @samp{<} and @samp{>} pair (for +C@t{++} templates), such a @samp{::} does not end the name---only a single +@samp{:} ends the name; see @ref{Nested Symbols}. + +For example, the following C declarations: + +@example +struct foo; +struct foo *bar; +@end example + +@noindent +produce: + +@example +.stabs "bar:G16=*17=xsfoo:",32,0,0,0 +@end example + +Not all debuggers support the @samp{x} type descriptor, so on some +machines GCC does not use it. I believe that for the above example it +would just emit a reference to type 17 and never define it, but I +haven't verified that. + +Modula-2 imported types, at least on AIX, use the @samp{i} type +descriptor, which is followed by the name of the module from which the +type is imported, followed by @samp{:}, followed by the name of the +type. There is then optionally a comma followed by type information for +the type. This differs from merely naming the type (@pxref{Typedefs}) in +that it identifies the module; I don't understand whether the name of +the type given here is always just the same as the name we are giving +it, or whether this type descriptor is used with a nameless stab +(@pxref{String Field}), or what. The symbol ends with @samp{;}. + +@node Subranges +@section Subrange Types + +The @samp{r} type descriptor defines a type as a subrange of another +type. It is followed by type information for the type of which it is a +subrange, a semicolon, an integral lower bound, a semicolon, an +integral upper bound, and a semicolon. The AIX documentation does not +specify the trailing semicolon, in an effort to specify array indexes +more cleanly, but a subrange which is not an array index has always +included a trailing semicolon (@pxref{Arrays}). + +Instead of an integer, either bound can be one of the following: + +@table @code +@item A @var{offset} +The bound is passed by reference on the stack at offset @var{offset} +from the argument list. @xref{Parameters}, for more information on such +offsets. + +@item T @var{offset} +The bound is passed by value on the stack at offset @var{offset} from +the argument list. + +@item a @var{register-number} +The bound is passed by reference in register number +@var{register-number}. + +@item t @var{register-number} +The bound is passed by value in register number @var{register-number}. + +@item J +There is no bound. +@end table + +Subranges are also used for builtin types; see @ref{Traditional Builtin Types}. + +@node Arrays +@section Array Types + +Arrays use the @samp{a} type descriptor. Following the type descriptor +is the type of the index and the type of the array elements. If the +index type is a range type, it ends in a semicolon; otherwise +(for example, if it is a type reference), there does not +appear to be any way to tell where the types are separated. In an +effort to clean up this mess, IBM documents the two types as being +separated by a semicolon, and a range type as not ending in a semicolon +(but this is not right for range types which are not array indexes, +@pxref{Subranges}). I think probably the best solution is to specify +that a semicolon ends a range type, and that the index type and element +type of an array are separated by a semicolon, but that if the index +type is a range type, the extra semicolon can be omitted. GDB (at least +through version 4.9) doesn't support any kind of index type other than a +range anyway; I'm not sure about dbx. + +It is well established, and widely used, that the type of the index, +unlike most types found in the stabs, is merely a type definition, not +type information (@pxref{String Field}) (that is, it need not start with +@samp{@var{type-number}=} if it is defining a new type). According to a +comment in GDB, this is also true of the type of the array elements; it +gives @samp{ar1;1;10;ar1;1;10;4} as a legitimate way to express a two +dimensional array. According to AIX documentation, the element type +must be type information. GDB accepts either. + +The type of the index is often a range type, expressed as the type +descriptor @samp{r} and some parameters. It defines the size of the +array. In the example below, the range @samp{r1;0;2;} defines an index +type which is a subrange of type 1 (integer), with a lower bound of 0 +and an upper bound of 2. This defines the valid range of subscripts of +a three-element C array. + +For example, the definition: + +@example +char char_vec[3] = @{'a','b','c'@}; +@end example + +@noindent +produces the output: + +@example +.stabs "char_vec:G19=ar1;0;2;2",32,0,0,0 + .global _char_vec + .align 4 +_char_vec: + .byte 97 + .byte 98 + .byte 99 +@end example + +If an array is @dfn{packed}, the elements are spaced more +closely than normal, saving memory at the expense of speed. For +example, an array of 3-byte objects might, if unpacked, have each +element aligned on a 4-byte boundary, but if packed, have no padding. +One way to specify that something is packed is with type attributes +(@pxref{String Field}). In the case of arrays, another is to use the +@samp{P} type descriptor instead of @samp{a}. Other than specifying a +packed array, @samp{P} is identical to @samp{a}. + +@c FIXME-what is it? A pointer? +An open array is represented by the @samp{A} type descriptor followed by +type information specifying the type of the array elements. + +@c FIXME: what is the format of this type? A pointer to a vector of pointers? +An N-dimensional dynamic array is represented by + +@example +D @var{dimensions} ; @var{type-information} +@end example + +@c Does dimensions really have this meaning? The AIX documentation +@c doesn't say. +@var{dimensions} is the number of dimensions; @var{type-information} +specifies the type of the array elements. + +@c FIXME: what is the format of this type? A pointer to some offsets in +@c another array? +A subarray of an N-dimensional array is represented by + +@example +E @var{dimensions} ; @var{type-information} +@end example + +@c Does dimensions really have this meaning? The AIX documentation +@c doesn't say. +@var{dimensions} is the number of dimensions; @var{type-information} +specifies the type of the array elements. + +@node Strings +@section Strings + +Some languages, like C or the original Pascal, do not have string types, +they just have related things like arrays of characters. But most +Pascals and various other languages have string types, which are +indicated as follows: + +@table @code +@item n @var{type-information} ; @var{bytes} +@var{bytes} is the maximum length. I'm not sure what +@var{type-information} is; I suspect that it means that this is a string +of @var{type-information} (thus allowing a string of integers, a string +of wide characters, etc., as well as a string of characters). Not sure +what the format of this type is. This is an AIX feature. + +@item z @var{type-information} ; @var{bytes} +Just like @samp{n} except that this is a gstring, not an ordinary +string. I don't know the difference. + +@item N +Pascal Stringptr. What is this? This is an AIX feature. +@end table + +Languages, such as CHILL which have a string type which is basically +just an array of characters use the @samp{S} type attribute +(@pxref{String Field}). + +@node Enumerations +@section Enumerations + +Enumerations are defined with the @samp{e} type descriptor. + +@c FIXME: Where does this information properly go? Perhaps it is +@c redundant with something we already explain. +The source line below declares an enumeration type at file scope. +The type definition is located after the @code{N_RBRAC} that marks the end of +the previous procedure's block scope, and before the @code{N_FUN} that marks +the beginning of the next procedure's block scope. Therefore it does not +describe a block local symbol, but a file local one. + +The source line: + +@example +enum e_places @{first,second=3,last@}; +@end example + +@noindent +generates the following stab: + +@example +.stabs "e_places:T22=efirst:0,second:3,last:4,;",128,0,0,0 +@end example + +The symbol descriptor (@samp{T}) says that the stab describes a +structure, enumeration, or union tag. The type descriptor @samp{e}, +following the @samp{22=} of the type definition narrows it down to an +enumeration type. Following the @samp{e} is a list of the elements of +the enumeration. The format is @samp{@var{name}:@var{value},}. The +list of elements ends with @samp{;}. The fact that @var{value} is +specified as an integer can cause problems if the value is large. GCC +2.5.2 tries to output it in octal in that case with a leading zero, +which is probably a good thing, although GDB 4.11 supports octal only in +cases where decimal is perfectly good. Negative decimal values are +supported by both GDB and dbx. + +There is no standard way to specify the size of an enumeration type; it +is determined by the architecture (normally all enumerations types are +32 bits). Type attributes can be used to specify an enumeration type of +another size for debuggers which support them; see @ref{String Field}. + +Enumeration types are unusual in that they define symbols for the +enumeration values (@code{first}, @code{second}, and @code{third} in the +above example), and even though these symbols are visible in the file as +a whole (rather than being in a more local namespace like structure +member names), they are defined in the type definition for the +enumeration type rather than each having their own symbol. In order to +be fast, GDB will only get symbols from such types (in its initial scan +of the stabs) if the type is the first thing defined after a @samp{T} or +@samp{t} symbol descriptor (the above example fulfills this +requirement). If the type does not have a name, the compiler should +emit it in a nameless stab (@pxref{String Field}); GCC does this. + +@node Structures +@section Structures + +The encoding of structures in stabs can be shown with an example. + +The following source code declares a structure tag and defines an +instance of the structure in global scope. Then a @code{typedef} equates the +structure tag with a new type. Separate stabs are generated for the +structure tag, the structure @code{typedef}, and the structure instance. The +stabs for the tag and the @code{typedef} are emitted when the definitions are +encountered. Since the structure elements are not initialized, the +stab and code for the structure variable itself is located at the end +of the program in the bss section. + +@example +struct s_tag @{ + int s_int; + float s_float; + char s_char_vec[8]; + struct s_tag* s_next; +@} g_an_s; + +typedef struct s_tag s_typedef; +@end example + +The structure tag has an @code{N_LSYM} stab type because, like the +enumeration, the symbol has file scope. Like the enumeration, the +symbol descriptor is @samp{T}, for enumeration, structure, or tag type. +The type descriptor @samp{s} following the @samp{16=} of the type +definition narrows the symbol type to structure. + +Following the @samp{s} type descriptor is the number of bytes the +structure occupies, followed by a description of each structure element. +The structure element descriptions are of the form +@samp{@var{name}:@var{type}, @var{bit offset from the start of the +struct}, @var{number of bits in the element}}. + +@c FIXME: phony line break. Can probably be fixed by using an example +@c with fewer fields. +@example +# @r{128 is N_LSYM} +.stabs "s_tag:T16=s20s_int:1,0,32;s_float:12,32,32; + s_char_vec:17=ar1;0;7;2,64,64;s_next:18=*16,128,32;;",128,0,0,0 +@end example + +In this example, the first two structure elements are previously defined +types. For these, the type following the @samp{@var{name}:} part of the +element description is a simple type reference. The other two structure +elements are new types. In this case there is a type definition +embedded after the @samp{@var{name}:}. The type definition for the +array element looks just like a type definition for a stand-alone array. +The @code{s_next} field is a pointer to the same kind of structure that +the field is an element of. So the definition of structure type 16 +contains a type definition for an element which is a pointer to type 16. + +If a field is a static member (this is a C@t{++} feature in which a single +variable appears to be a field of every structure of a given type) it +still starts out with the field name, a colon, and the type, but then +instead of a comma, bit position, comma, and bit size, there is a colon +followed by the name of the variable which each such field refers to. + +If the structure has methods (a C@t{++} feature), they follow the non-method +fields; see @ref{Cplusplus}. + +@node Typedefs +@section Giving a Type a Name + +@findex N_LSYM, for types +@findex C_DECL, for types +To give a type a name, use the @samp{t} symbol descriptor. The type +is specified by the type information (@pxref{String Field}) for the stab. +For example, + +@example +.stabs "s_typedef:t16",128,0,0,0 # @r{128 is N_LSYM} +@end example + +specifies that @code{s_typedef} refers to type number 16. Such stabs +have symbol type @code{N_LSYM} (or @code{C_DECL} for XCOFF). (The Sun +documentation mentions using @code{N_GSYM} in some cases). + +If you are specifying the tag name for a structure, union, or +enumeration, use the @samp{T} symbol descriptor instead. I believe C is +the only language with this feature. + +If the type is an opaque type (I believe this is a Modula-2 feature), +AIX provides a type descriptor to specify it. The type descriptor is +@samp{o} and is followed by a name. I don't know what the name +means---is it always the same as the name of the type, or is this type +descriptor used with a nameless stab (@pxref{String Field})? There +optionally follows a comma followed by type information which defines +the type of this type. If omitted, a semicolon is used in place of the +comma and the type information, and the type is much like a generic +pointer type---it has a known size but little else about it is +specified. + +@node Unions +@section Unions + +@example +union u_tag @{ + int u_int; + float u_float; + char* u_char; +@} an_u; +@end example + +This code generates a stab for a union tag and a stab for a union +variable. Both use the @code{N_LSYM} stab type. If a union variable is +scoped locally to the procedure in which it is defined, its stab is +located immediately preceding the @code{N_LBRAC} for the procedure's block +start. + +The stab for the union tag, however, is located preceding the code for +the procedure in which it is defined. The stab type is @code{N_LSYM}. This +would seem to imply that the union type is file scope, like the struct +type @code{s_tag}. This is not true. The contents and position of the stab +for @code{u_type} do not convey any information about its procedure local +scope. + +@c FIXME: phony line break. Can probably be fixed by using an example +@c with fewer fields. +@smallexample +# @r{128 is N_LSYM} +.stabs "u_tag:T23=u4u_int:1,0,32;u_float:12,0,32;u_char:21,0,32;;", + 128,0,0,0 +@end smallexample + +The symbol descriptor @samp{T}, following the @samp{name:} means that +the stab describes an enumeration, structure, or union tag. The type +descriptor @samp{u}, following the @samp{23=} of the type definition, +narrows it down to a union type definition. Following the @samp{u} is +the number of bytes in the union. After that is a list of union element +descriptions. Their format is @samp{@var{name}:@var{type}, @var{bit +offset into the union}, @var{number of bytes for the element};}. + +The stab for the union variable is: + +@example +.stabs "an_u:23",128,0,0,-20 # @r{128 is N_LSYM} +@end example + +@samp{-20} specifies where the variable is stored (@pxref{Stack +Variables}). + +@node Function Types +@section Function Types + +Various types can be defined for function variables. These types are +not used in defining functions (@pxref{Procedures}); they are used for +things like pointers to functions. + +The simple, traditional, type is type descriptor @samp{f} is followed by +type information for the return type of the function, followed by a +semicolon. + +This does not deal with functions for which the number and types of the +parameters are part of the type, as in Modula-2 or ANSI C. AIX provides +extensions to specify these, using the @samp{f}, @samp{F}, @samp{p}, and +@samp{R} type descriptors. + +First comes the type descriptor. If it is @samp{f} or @samp{F}, this +type involves a function rather than a procedure, and the type +information for the return type of the function follows, followed by a +comma. Then comes the number of parameters to the function and a +semicolon. Then, for each parameter, there is the name of the parameter +followed by a colon (this is only present for type descriptors @samp{R} +and @samp{F} which represent Pascal function or procedure parameters), +type information for the parameter, a comma, 0 if passed by reference or +1 if passed by value, and a semicolon. The type definition ends with a +semicolon. + +For example, this variable definition: + +@example +int (*g_pf)(); +@end example + +@noindent +generates the following code: + +@example +.stabs "g_pf:G24=*25=f1",32,0,0,0 + .common _g_pf,4,"bss" +@end example + +The variable defines a new type, 24, which is a pointer to another new +type, 25, which is a function returning @code{int}. + +@node Macro define and undefine +@chapter Representation of #define and #undef + +This section describes the stabs support for macro define and undefine +information, supported on some systems. (e.g., with @option{-g3} +@option{-gstabs} when using GCC). + +A @code{#define @var{macro-name} @var{macro-body}} is represented with +an @code{N_MAC_DEFINE} stab with a string field of +@code{@var{macro-name} @var{macro-body}}. +@findex N_MAC_DEFINE + +An @code{#undef @var{macro-name}} is represented with an +@code{N_MAC_UNDEF} stabs with a string field of simply +@code{@var{macro-name}}. +@findex N_MAC_UNDEF + +For both @code{N_MAC_DEFINE} and @code{N_MAC_UNDEF}, the desc field is +the line number within the file where the corresponding @code{#define} +or @code{#undef} occurred. + +For example, the following C code: + +@example + #define NONE 42 + #define TWO(a, b) (a + (a) + 2 * b) + #define ONE(c) (c + 19) + + main(int argc, char *argv[]) + @{ + func(NONE, TWO(10, 11)); + func(NONE, ONE(23)); + + #undef ONE + #define ONE(c) (c + 23) + + func(NONE, ONE(-23)); + + return (0); + @} + + int global; + + func(int arg1, int arg2) + @{ + global = arg1 + arg2; + @} +@end example + +@noindent +produces the following stabs (as well as many others): + +@example + .stabs "NONE 42",54,0,1,0 + .stabs "TWO(a,b) (a + (a) + 2 * b)",54,0,2,0 + .stabs "ONE(c) (c + 19)",54,0,3,0 + .stabs "ONE",58,0,10,0 + .stabs "ONE(c) (c + 23)",54,0,11,0 +@end example + +@noindent +NOTE: In the above example, @code{54} is @code{N_MAC_DEFINE} and +@code{58} is @code{N_MAC_UNDEF}. + +@node Symbol Tables +@chapter Symbol Information in Symbol Tables + +This chapter describes the format of symbol table entries +and how stab assembler directives map to them. It also describes the +transformations that the assembler and linker make on data from stabs. + +@menu +* Symbol Table Format:: +* Transformations On Symbol Tables:: +@end menu + +@node Symbol Table Format +@section Symbol Table Format + +Each time the assembler encounters a stab directive, it puts +each field of the stab into a corresponding field in a symbol table +entry of its output file. If the stab contains a string field, the +symbol table entry for that stab points to a string table entry +containing the string data from the stab. Assembler labels become +relocatable addresses. Symbol table entries in a.out have the format: + +@c FIXME: should refer to external, not internal. +@example +struct internal_nlist @{ + unsigned long n_strx; /* index into string table of name */ + unsigned char n_type; /* type of symbol */ + unsigned char n_other; /* misc info (usually empty) */ + unsigned short n_desc; /* description field */ + bfd_vma n_value; /* value of symbol */ +@}; +@end example + +If the stab has a string, the @code{n_strx} field holds the offset in +bytes of the string within the string table. The string is terminated +by a NUL character. If the stab lacks a string (for example, it was +produced by a @code{.stabn} or @code{.stabd} directive), the +@code{n_strx} field is zero. + +Symbol table entries with @code{n_type} field values greater than 0x1f +originated as stabs generated by the compiler (with one random +exception). The other entries were placed in the symbol table of the +executable by the assembler or the linker. + +@node Transformations On Symbol Tables +@section Transformations on Symbol Tables + +The linker concatenates object files and does fixups of externally +defined symbols. + +You can see the transformations made on stab data by the assembler and +linker by examining the symbol table after each pass of the build. To +do this, use @samp{nm -ap}, which dumps the symbol table, including +debugging information, unsorted. For stab entries the columns are: +@var{value}, @var{other}, @var{desc}, @var{type}, @var{string}. For +assembler and linker symbols, the columns are: @var{value}, @var{type}, +@var{string}. + +The low 5 bits of the stab type tell the linker how to relocate the +value of the stab. Thus for stab types like @code{N_RSYM} and +@code{N_LSYM}, where the value is an offset or a register number, the +low 5 bits are @code{N_ABS}, which tells the linker not to relocate the +value. + +Where the value of a stab contains an assembly language label, +it is transformed by each build step. The assembler turns it into a +relocatable address and the linker turns it into an absolute address. + +@menu +* Transformations On Static Variables:: +* Transformations On Global Variables:: +* Stab Section Transformations:: For some object file formats, + things are a bit different. +@end menu + +@node Transformations On Static Variables +@subsection Transformations on Static Variables + +This source line defines a static variable at file scope: + +@example +static int s_g_repeat +@end example + +@noindent +The following stab describes the symbol: + +@example +.stabs "s_g_repeat:S1",38,0,0,_s_g_repeat +@end example + +@noindent +The assembler transforms the stab into this symbol table entry in the +@file{.o} file. The location is expressed as a data segment offset. + +@example +00000084 - 00 0000 STSYM s_g_repeat:S1 +@end example + +@noindent +In the symbol table entry from the executable, the linker has made the +relocatable address absolute. + +@example +0000e00c - 00 0000 STSYM s_g_repeat:S1 +@end example + +@node Transformations On Global Variables +@subsection Transformations on Global Variables + +Stabs for global variables do not contain location information. In +this case, the debugger finds location information in the assembler or +linker symbol table entry describing the variable. The source line: + +@example +char g_foo = 'c'; +@end example + +@noindent +generates the stab: + +@example +.stabs "g_foo:G2",32,0,0,0 +@end example + +The variable is represented by two symbol table entries in the object +file (see below). The first one originated as a stab. The second one +is an external symbol. The upper case @samp{D} signifies that the +@code{n_type} field of the symbol table contains 7, @code{N_DATA} with +local linkage. The stab's value is zero since the value is not used for +@code{N_GSYM} stabs. The value of the linker symbol is the relocatable +address corresponding to the variable. + +@example +00000000 - 00 0000 GSYM g_foo:G2 +00000080 D _g_foo +@end example + +@noindent +These entries as transformed by the linker. The linker symbol table +entry now holds an absolute address: + +@example +00000000 - 00 0000 GSYM g_foo:G2 +@dots{} +0000e008 D _g_foo +@end example + +@node Stab Section Transformations +@subsection Transformations of Stabs in separate sections + +For object file formats using stabs in separate sections (@pxref{Stab +Sections}), use @code{objdump --stabs} instead of @code{nm} to show the +stabs in an object or executable file. @code{objdump} is a GNU utility; +Sun does not provide any equivalent. + +The following example is for a stab whose value is an address is +relative to the compilation unit (@pxref{ELF Linker Relocation}). For +example, if the source line + +@example +static int ld = 5; +@end example + +appears within a function, then the assembly language output from the +compiler contains: + +@example +.Ddata.data: +@dots{} + .stabs "ld:V(0,3)",0x26,0,4,.L18-Ddata.data # @r{0x26 is N_STSYM} +@dots{} +.L18: + .align 4 + .word 0x5 +@end example + +Because the value is formed by subtracting one symbol from another, the +value is absolute, not relocatable, and so the object file contains + +@example +Symnum n_type n_othr n_desc n_value n_strx String +31 STSYM 0 4 00000004 680 ld:V(0,3) +@end example + +without any relocations, and the executable file also contains + +@example +Symnum n_type n_othr n_desc n_value n_strx String +31 STSYM 0 4 00000004 680 ld:V(0,3) +@end example + +@node Cplusplus +@chapter GNU C@t{++} Stabs + +@menu +* Class Names:: C++ class names are both tags and typedefs. +* Nested Symbols:: C++ symbol names can be within other types. +* Basic Cplusplus Types:: +* Simple Classes:: +* Class Instance:: +* Methods:: Method definition +* Method Type Descriptor:: The @samp{#} type descriptor +* Member Type Descriptor:: The @samp{@@} type descriptor +* Protections:: +* Method Modifiers:: +* Virtual Methods:: +* Inheritance:: +* Virtual Base Classes:: +* Static Members:: +@end menu + +@node Class Names +@section C@t{++} Class Names + +In C@t{++}, a class name which is declared with @code{class}, @code{struct}, +or @code{union}, is not only a tag, as in C, but also a type name. Thus +there should be stabs with both @samp{t} and @samp{T} symbol descriptors +(@pxref{Typedefs}). + +To save space, there is a special abbreviation for this case. If the +@samp{T} symbol descriptor is followed by @samp{t}, then the stab +defines both a type name and a tag. + +For example, the C@t{++} code + +@example +struct foo @{int x;@}; +@end example + +can be represented as either + +@example +.stabs "foo:T19=s4x:1,0,32;;",128,0,0,0 # @r{128 is N_LSYM} +.stabs "foo:t19",128,0,0,0 +@end example + +or + +@example +.stabs "foo:Tt19=s4x:1,0,32;;",128,0,0,0 +@end example + +@node Nested Symbols +@section Defining a Symbol Within Another Type + +In C@t{++}, a symbol (such as a type name) can be defined within another type. +@c FIXME: Needs example. + +In stabs, this is sometimes represented by making the name of a symbol +which contains @samp{::}. Such a pair of colons does not end the name +of the symbol, the way a single colon would (@pxref{String Field}). I'm +not sure how consistently used or well thought out this mechanism is. +So that a pair of colons in this position always has this meaning, +@samp{:} cannot be used as a symbol descriptor. + +For example, if the string for a stab is @samp{foo::bar::baz:t5=*6}, +then @code{foo::bar::baz} is the name of the symbol, @samp{t} is the +symbol descriptor, and @samp{5=*6} is the type information. + +@node Basic Cplusplus Types +@section Basic Types For C@t{++} + +<< the examples that follow are based on a01.C >> + + +C@t{++} adds two more builtin types to the set defined for C. These are +the unknown type and the vtable record type. The unknown type, type +16, is defined in terms of itself like the void type. + +The vtable record type, type 17, is defined as a structure type and +then as a structure tag. The structure has four fields: delta, index, +pfn, and delta2. pfn is the function pointer. + +<< In boilerplate $vtbl_ptr_type, what are the fields delta, +index, and delta2 used for? >> + +This basic type is present in all C@t{++} programs even if there are no +virtual methods defined. + +@display +.stabs "struct_name:sym_desc(type)type_def(17)=type_desc(struct)struct_bytes(8) + elem_name(delta):type_ref(short int),bit_offset(0),field_bits(16); + elem_name(index):type_ref(short int),bit_offset(16),field_bits(16); + elem_name(pfn):type_def(18)=type_desc(ptr to)type_ref(void), + bit_offset(32),field_bits(32); + elem_name(delta2):type_def(short int);bit_offset(32),field_bits(16);;" + N_LSYM, NIL, NIL +@end display + +@smallexample +.stabs "$vtbl_ptr_type:t17=s8 + delta:6,0,16;index:6,16,16;pfn:18=*15,32,32;delta2:6,32,16;;" + ,128,0,0,0 +@end smallexample + +@display +.stabs "name:sym_dec(struct tag)type_ref($vtbl_ptr_type)",N_LSYM,NIL,NIL,NIL +@end display + +@example +.stabs "$vtbl_ptr_type:T17",128,0,0,0 +@end example + +@node Simple Classes +@section Simple Class Definition + +The stabs describing C@t{++} language features are an extension of the +stabs describing C. Stabs representing C@t{++} class types elaborate +extensively on the stab format used to describe structure types in C. +Stabs representing class type variables look just like stabs +representing C language variables. + +Consider the following very simple class definition. + +@example +class baseA @{ +public: + int Adat; + int Ameth(int in, char other); +@}; +@end example + +The class @code{baseA} is represented by two stabs. The first stab describes +the class as a structure type. The second stab describes a structure +tag of the class type. Both stabs are of stab type @code{N_LSYM}. Since the +stab is not located between an @code{N_FUN} and an @code{N_LBRAC} stab this indicates +that the class is defined at file scope. If it were, then the @code{N_LSYM} +would signify a local variable. + +A stab describing a C@t{++} class type is similar in format to a stab +describing a C struct, with each class member shown as a field in the +structure. The part of the struct format describing fields is +expanded to include extra information relevant to C@t{++} class members. +In addition, if the class has multiple base classes or virtual +functions the struct format outside of the field parts is also +augmented. + +In this simple example the field part of the C@t{++} class stab +representing member data looks just like the field part of a C struct +stab. The section on protections describes how its format is +sometimes extended for member data. + +The field part of a C@t{++} class stab representing a member function +differs substantially from the field part of a C struct stab. It +still begins with @samp{name:} but then goes on to define a new type number +for the member function, describe its return type, its argument types, +its protection level, any qualifiers applied to the method definition, +and whether the method is virtual or not. If the method is virtual +then the method description goes on to give the vtable index of the +method, and the type number of the first base class defining the +method. + +When the field name is a method name it is followed by two colons rather +than one. This is followed by a new type definition for the method. +This is a number followed by an equal sign and the type of the method. +Normally this will be a type declared using the @samp{#} type +descriptor; see @ref{Method Type Descriptor}; static member functions +are declared using the @samp{f} type descriptor instead; see +@ref{Function Types}. + +The format of an overloaded operator method name differs from that of +other methods. It is @samp{op$::@var{operator-name}.} where +@var{operator-name} is the operator name such as @samp{+} or @samp{+=}. +The name ends with a period, and any characters except the period can +occur in the @var{operator-name} string. + +The next part of the method description represents the arguments to the +method, preceded by a colon and ending with a semi-colon. The types of +the arguments are expressed in the same way argument types are expressed +in C@t{++} name mangling. In this example an @code{int} and a @code{char} +map to @samp{ic}. + +This is followed by a number, a letter, and an asterisk or period, +followed by another semicolon. The number indicates the protections +that apply to the member function. Here the 2 means public. The +letter encodes any qualifier applied to the method definition. In +this case, @samp{A} means that it is a normal function definition. The dot +shows that the method is not virtual. The sections that follow +elaborate further on these fields and describe the additional +information present for virtual methods. + + +@display +.stabs "class_name:sym_desc(type)type_def(20)=type_desc(struct)struct_bytes(4) + field_name(Adat):type(int),bit_offset(0),field_bits(32); + + method_name(Ameth)::type_def(21)=type_desc(method)return_type(int); + :arg_types(int char); + protection(public)qualifier(normal)virtual(no);;" + N_LSYM,NIL,NIL,NIL +@end display + +@smallexample +.stabs "baseA:t20=s4Adat:1,0,32;Ameth::21=##1;:ic;2A.;;",128,0,0,0 + +.stabs "class_name:sym_desc(struct tag)",N_LSYM,NIL,NIL,NIL + +.stabs "baseA:T20",128,0,0,0 +@end smallexample + +@node Class Instance +@section Class Instance + +As shown above, describing even a simple C@t{++} class definition is +accomplished by massively extending the stab format used in C to +describe structure types. However, once the class is defined, C stabs +with no modifications can be used to describe class instances. The +following source: + +@example +main () @{ + baseA AbaseA; +@} +@end example + +@noindent +yields the following stab describing the class instance. It looks no +different from a standard C stab describing a local variable. + +@display +.stabs "name:type_ref(baseA)", N_LSYM, NIL, NIL, frame_ptr_offset +@end display + +@example +.stabs "AbaseA:20",128,0,0,-20 +@end example + +@node Methods +@section Method Definition + +The class definition shown above declares Ameth. The C@t{++} source below +defines Ameth: + +@example +int +baseA::Ameth(int in, char other) +@{ + return in; +@}; +@end example + + +This method definition yields three stabs following the code of the +method. One stab describes the method itself and following two describe +its parameters. Although there is only one formal argument all methods +have an implicit argument which is the @code{this} pointer. The @code{this} +pointer is a pointer to the object on which the method was called. Note +that the method name is mangled to encode the class name and argument +types. Name mangling is described in the @sc{arm} (@cite{The Annotated +C++ Reference Manual}, by Ellis and Stroustrup, @sc{isbn} +0-201-51459-1); @file{gpcompare.texi} in Cygnus GCC distributions +describes the differences between GNU mangling and @sc{arm} +mangling. +@c FIXME: Use @xref, especially if this is generally installed in the +@c info tree. +@c FIXME: This information should be in a net release, either of GCC or +@c GDB. But gpcompare.texi doesn't seem to be in the FSF GCC. + +@example +.stabs "name:symbol_descriptor(global function)return_type(int)", + N_FUN, NIL, NIL, code_addr_of_method_start + +.stabs "Ameth__5baseAic:F1",36,0,0,_Ameth__5baseAic +@end example + +Here is the stab for the @code{this} pointer implicit argument. The +name of the @code{this} pointer is always @code{this}. Type 19, the +@code{this} pointer is defined as a pointer to type 20, @code{baseA}, +but a stab defining @code{baseA} has not yet been emitted. Since the +compiler knows it will be emitted shortly, here it just outputs a cross +reference to the undefined symbol, by prefixing the symbol name with +@samp{xs}. + +@example +.stabs "name:sym_desc(register param)type_def(19)= + type_desc(ptr to)type_ref(baseA)= + type_desc(cross-reference to)baseA:",N_RSYM,NIL,NIL,register_number + +.stabs "this:P19=*20=xsbaseA:",64,0,0,8 +@end example + +The stab for the explicit integer argument looks just like a parameter +to a C function. The last field of the stab is the offset from the +argument pointer, which in most systems is the same as the frame +pointer. + +@example +.stabs "name:sym_desc(value parameter)type_ref(int)", + N_PSYM,NIL,NIL,offset_from_arg_ptr + +.stabs "in:p1",160,0,0,72 +@end example + +<< The examples that follow are based on A1.C >> + +@node Method Type Descriptor +@section The @samp{#} Type Descriptor + +This is used to describe a class method. This is a function which takes +an extra argument as its first argument, for the @code{this} pointer. + +If the @samp{#} is immediately followed by another @samp{#}, the second +one will be followed by the return type and a semicolon. The class and +argument types are not specified, and must be determined by demangling +the name of the method if it is available. + +Otherwise, the single @samp{#} is followed by the class type, a comma, +the return type, a comma, and zero or more parameter types separated by +commas. The list of arguments is terminated by a semicolon. In the +debugging output generated by gcc, a final argument type of @code{void} +indicates a method which does not take a variable number of arguments. +If the final argument type of @code{void} does not appear, the method +was declared with an ellipsis. + +Note that although such a type will normally be used to describe fields +in structures, unions, or classes, for at least some versions of the +compiler it can also be used in other contexts. + +@node Member Type Descriptor +@section The @samp{@@} Type Descriptor + +The @samp{@@} type descriptor is used for a +pointer-to-non-static-member-data type. It is followed +by type information for the class (or union), a comma, and type +information for the member data. + +The following C@t{++} source: + +@smallexample +typedef int A::*int_in_a; +@end smallexample + +generates the following stab: + +@smallexample +.stabs "int_in_a:t20=21=@@19,1",128,0,0,0 +@end smallexample + +Note that there is a conflict between this and type attributes +(@pxref{String Field}); both use type descriptor @samp{@@}. +Fortunately, the @samp{@@} type descriptor used in this C@t{++} sense always +will be followed by a digit, @samp{(}, or @samp{-}, and type attributes +never start with those things. + +@node Protections +@section Protections + +In the simple class definition shown above all member data and +functions were publicly accessible. The example that follows +contrasts public, protected and privately accessible fields and shows +how these protections are encoded in C@t{++} stabs. + +If the character following the @samp{@var{field-name}:} part of the +string is @samp{/}, then the next character is the visibility. @samp{0} +means private, @samp{1} means protected, and @samp{2} means public. +Debuggers should ignore visibility characters they do not recognize, and +assume a reasonable default (such as public) (GDB 4.11 does not, but +this should be fixed in the next GDB release). If no visibility is +specified the field is public. The visibility @samp{9} means that the +field has been optimized out and is public (there is no way to specify +an optimized out field with a private or protected visibility). +Visibility @samp{9} is not supported by GDB 4.11; this should be fixed +in the next GDB release. + +The following C@t{++} source: + +@example +class vis @{ +private: + int priv; +protected: + char prot; +public: + float pub; +@}; +@end example + +@noindent +generates the following stab: + +@example +# @r{128 is N_LSYM} +.stabs "vis:T19=s12priv:/01,0,32;prot:/12,32,8;pub:12,64,32;;",128,0,0,0 +@end example + +@samp{vis:T19=s12} indicates that type number 19 is a 12 byte structure +named @code{vis} The @code{priv} field has public visibility +(@samp{/0}), type int (@samp{1}), and offset and size @samp{,0,32;}. +The @code{prot} field has protected visibility (@samp{/1}), type char +(@samp{2}) and offset and size @samp{,32,8;}. The @code{pub} field has +type float (@samp{12}), and offset and size @samp{,64,32;}. + +Protections for member functions are signified by one digit embedded in +the field part of the stab describing the method. The digit is 0 if +private, 1 if protected and 2 if public. Consider the C@t{++} class +definition below: + +@example +class all_methods @{ +private: + int priv_meth(int in)@{return in;@}; +protected: + char protMeth(char in)@{return in;@}; +public: + float pubMeth(float in)@{return in;@}; +@}; +@end example + +It generates the following stab. The digit in question is to the left +of an @samp{A} in each case. Notice also that in this case two symbol +descriptors apply to the class name struct tag and struct type. + +@display +.stabs "class_name:sym_desc(struct tag&type)type_def(21)= + sym_desc(struct)struct_bytes(1) + meth_name::type_def(22)=sym_desc(method)returning(int); + :args(int);protection(private)modifier(normal)virtual(no); + meth_name::type_def(23)=sym_desc(method)returning(char); + :args(char);protection(protected)modifier(normal)virtual(no); + meth_name::type_def(24)=sym_desc(method)returning(float); + :args(float);protection(public)modifier(normal)virtual(no);;", + N_LSYM,NIL,NIL,NIL +@end display + +@smallexample +.stabs "all_methods:Tt21=s1priv_meth::22=##1;:i;0A.;protMeth::23=##2;:c;1A.; + pubMeth::24=##12;:f;2A.;;",128,0,0,0 +@end smallexample + +@node Method Modifiers +@section Method Modifiers (@code{const}, @code{volatile}, @code{const volatile}) + +<< based on a6.C >> + +In the class example described above all the methods have the normal +modifier. This method modifier information is located just after the +protection information for the method. This field has four possible +character values. Normal methods use @samp{A}, const methods use +@samp{B}, volatile methods use @samp{C}, and const volatile methods use +@samp{D}. Consider the class definition below: + +@example +class A @{ +public: + int ConstMeth (int arg) const @{ return arg; @}; + char VolatileMeth (char arg) volatile @{ return arg; @}; + float ConstVolMeth (float arg) const volatile @{return arg; @}; +@}; +@end example + +This class is described by the following stab: + +@display +.stabs "class(A):sym_desc(struct)type_def(20)=type_desc(struct)struct_bytes(1) + meth_name(ConstMeth)::type_def(21)sym_desc(method) + returning(int);:arg(int);protection(public)modifier(const)virtual(no); + meth_name(VolatileMeth)::type_def(22)=sym_desc(method) + returning(char);:arg(char);protection(public)modifier(volatile)virt(no) + meth_name(ConstVolMeth)::type_def(23)=sym_desc(method) + returning(float);:arg(float);protection(public)modifier(const volatile) + virtual(no);;", @dots{} +@end display + +@example +.stabs "A:T20=s1ConstMeth::21=##1;:i;2B.;VolatileMeth::22=##2;:c;2C.; + ConstVolMeth::23=##12;:f;2D.;;",128,0,0,0 +@end example + +@node Virtual Methods +@section Virtual Methods + +<< The following examples are based on a4.C >> + +The presence of virtual methods in a class definition adds additional +data to the class description. The extra data is appended to the +description of the virtual method and to the end of the class +description. Consider the class definition below: + +@example +class A @{ +public: + int Adat; + virtual int A_virt (int arg) @{ return arg; @}; +@}; +@end example + +This results in the stab below describing class A. It defines a new +type (20) which is an 8 byte structure. The first field of the class +struct is @samp{Adat}, an integer, starting at structure offset 0 and +occupying 32 bits. + +The second field in the class struct is not explicitly defined by the +C@t{++} class definition but is implied by the fact that the class +contains a virtual method. This field is the vtable pointer. The +name of the vtable pointer field starts with @samp{$vf} and continues with a +type reference to the class it is part of. In this example the type +reference for class A is 20 so the name of its vtable pointer field is +@samp{$vf20}, followed by the usual colon. + +Next there is a type definition for the vtable pointer type (21). +This is in turn defined as a pointer to another new type (22). + +Type 22 is the vtable itself, which is defined as an array, indexed by +a range of integers between 0 and 1, and whose elements are of type +17. Type 17 was the vtable record type defined by the boilerplate C@t{++} +type definitions, as shown earlier. + +The bit offset of the vtable pointer field is 32. The number of bits +in the field are not specified when the field is a vtable pointer. + +Next is the method definition for the virtual member function @code{A_virt}. +Its description starts out using the same format as the non-virtual +member functions described above, except instead of a dot after the +@samp{A} there is an asterisk, indicating that the function is virtual. +Since is is virtual some addition information is appended to the end +of the method description. + +The first number represents the vtable index of the method. This is a +32 bit unsigned number with the high bit set, followed by a +semi-colon. + +The second number is a type reference to the first base class in the +inheritance hierarchy defining the virtual member function. In this +case the class stab describes a base class so the virtual function is +not overriding any other definition of the method. Therefore the +reference is to the type number of the class that the stab is +describing (20). + +This is followed by three semi-colons. One marks the end of the +current sub-section, one marks the end of the method field, and the +third marks the end of the struct definition. + +For classes containing virtual functions the very last section of the +string part of the stab holds a type reference to the first base +class. This is preceded by @samp{~%} and followed by a final semi-colon. + +@display +.stabs "class_name(A):type_def(20)=sym_desc(struct)struct_bytes(8) + field_name(Adat):type_ref(int),bit_offset(0),field_bits(32); + field_name(A virt func ptr):type_def(21)=type_desc(ptr to)type_def(22)= + sym_desc(array)index_type_ref(range of int from 0 to 1); + elem_type_ref(vtbl elem type), + bit_offset(32); + meth_name(A_virt)::typedef(23)=sym_desc(method)returning(int); + :arg_type(int),protection(public)normal(yes)virtual(yes) + vtable_index(1);class_first_defining(A);;;~%first_base(A);", + N_LSYM,NIL,NIL,NIL +@end display + +@c FIXME: bogus line break. +@example +.stabs "A:t20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 +@end example + +@node Inheritance +@section Inheritance + +Stabs describing C@t{++} derived classes include additional sections that +describe the inheritance hierarchy of the class. A derived class stab +also encodes the number of base classes. For each base class it tells +if the base class is virtual or not, and if the inheritance is private +or public. It also gives the offset into the object of the portion of +the object corresponding to each base class. + +This additional information is embedded in the class stab following the +number of bytes in the struct. First the number of base classes +appears bracketed by an exclamation point and a comma. + +Then for each base type there repeats a series: a virtual character, a +visibility character, a number, a comma, another number, and a +semi-colon. + +The virtual character is @samp{1} if the base class is virtual and +@samp{0} if not. The visibility character is @samp{2} if the derivation +is public, @samp{1} if it is protected, and @samp{0} if it is private. +Debuggers should ignore virtual or visibility characters they do not +recognize, and assume a reasonable default (such as public and +non-virtual) (GDB 4.11 does not, but this should be fixed in the next +GDB release). + +The number following the virtual and visibility characters is the offset +from the start of the object to the part of the object pertaining to the +base class. + +After the comma, the second number is a type_descriptor for the base +type. Finally a semi-colon ends the series, which repeats for each +base class. + +The source below defines three base classes @code{A}, @code{B}, and +@code{C} and the derived class @code{D}. + + +@example +class A @{ +public: + int Adat; + virtual int A_virt (int arg) @{ return arg; @}; +@}; + +class B @{ +public: + int B_dat; + virtual int B_virt (int arg) @{return arg; @}; +@}; + +class C @{ +public: + int Cdat; + virtual int C_virt (int arg) @{return arg; @}; +@}; + +class D : A, virtual B, public C @{ +public: + int Ddat; + virtual int A_virt (int arg ) @{ return arg+1; @}; + virtual int B_virt (int arg) @{ return arg+2; @}; + virtual int C_virt (int arg) @{ return arg+3; @}; + virtual int D_virt (int arg) @{ return arg; @}; +@}; +@end example + +Class stabs similar to the ones described earlier are generated for +each base class. + +@c FIXME!!! the linebreaks in the following example probably make the +@c examples literally unusable, but I don't know any other way to get +@c them on the page. +@c One solution would be to put some of the type definitions into +@c separate stabs, even if that's not exactly what the compiler actually +@c emits. +@smallexample +.stabs "A:T20=s8Adat:1,0,32;$vf20:21=*22=ar1;0;1;17,32; + A_virt::23=##1;:i;2A*-2147483647;20;;;~%20;",128,0,0,0 + +.stabs "B:Tt25=s8Bdat:1,0,32;$vf25:21,32;B_virt::26=##1; + :i;2A*-2147483647;25;;;~%25;",128,0,0,0 + +.stabs "C:Tt28=s8Cdat:1,0,32;$vf28:21,32;C_virt::29=##1; + :i;2A*-2147483647;28;;;~%28;",128,0,0,0 +@end smallexample + +In the stab describing derived class @code{D} below, the information about +the derivation of this class is encoded as follows. + +@display +.stabs "derived_class_name:symbol_descriptors(struct tag&type)= + type_descriptor(struct)struct_bytes(32)!num_bases(3), + base_virtual(no)inheritance_public(no)base_offset(0), + base_class_type_ref(A); + base_virtual(yes)inheritance_public(no)base_offset(NIL), + base_class_type_ref(B); + base_virtual(no)inheritance_public(yes)base_offset(64), + base_class_type_ref(C); @dots{} +@end display + +@c FIXME! fake linebreaks. +@smallexample +.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat: + 1,160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt: + :32:i;2A*-2147483647;25;;C_virt::32:i;2A*-2147483647; + 28;;D_virt::32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 +@end smallexample + +@node Virtual Base Classes +@section Virtual Base Classes + +A derived class object consists of a concatenation in memory of the data +areas defined by each base class, starting with the leftmost and ending +with the rightmost in the list of base classes. The exception to this +rule is for virtual inheritance. In the example above, class @code{D} +inherits virtually from base class @code{B}. This means that an +instance of a @code{D} object will not contain its own @code{B} part but +merely a pointer to a @code{B} part, known as a virtual base pointer. + +In a derived class stab, the base offset part of the derivation +information, described above, shows how the base class parts are +ordered. The base offset for a virtual base class is always given as 0. +Notice that the base offset for @code{B} is given as 0 even though +@code{B} is not the first base class. The first base class @code{A} +starts at offset 0. + +The field information part of the stab for class @code{D} describes the field +which is the pointer to the virtual base class @code{B}. The vbase pointer +name is @samp{$vb} followed by a type reference to the virtual base class. +Since the type id for @code{B} in this example is 25, the vbase pointer name +is @samp{$vb25}. + +@c FIXME!! fake linebreaks below +@smallexample +.stabs "D:Tt31=s32!3,000,20;100,25;0264,28;$vb25:24,128;Ddat:1, + 160,32;A_virt::32=##1;:i;2A*-2147483647;20;;B_virt::32:i; + 2A*-2147483647;25;;C_virt::32:i;2A*-2147483647;28;;D_virt: + :32:i;2A*-2147483646;31;;;~%20;",128,0,0,0 +@end smallexample + +Following the name and a semicolon is a type reference describing the +type of the virtual base class pointer, in this case 24. Type 24 was +defined earlier as the type of the @code{B} class @code{this} pointer. The +@code{this} pointer for a class is a pointer to the class type. + +@example +.stabs "this:P24=*25=xsB:",64,0,0,8 +@end example + +Finally the field offset part of the vbase pointer field description +shows that the vbase pointer is the first field in the @code{D} object, +before any data fields defined by the class. The layout of a @code{D} +class object is a follows, @code{Adat} at 0, the vtable pointer for +@code{A} at 32, @code{Cdat} at 64, the vtable pointer for C at 96, the +virtual base pointer for @code{B} at 128, and @code{Ddat} at 160. + + +@node Static Members +@section Static Members + +The data area for a class is a concatenation of the space used by the +data members of the class. If the class has virtual methods, a vtable +pointer follows the class data. The field offset part of each field +description in the class stab shows this ordering. + +<< How is this reflected in stabs? See Cygnus bug #677 for some info. >> + +@node Stab Types +@appendix Table of Stab Types + +The following are all the possible values for the stab type field, for +a.out files, in numeric order. This does not apply to XCOFF, but +it does apply to stabs in sections (@pxref{Stab Sections}). Stabs in +ECOFF use these values but add 0x8f300 to distinguish them from non-stab +symbols. + +The symbolic names are defined in the file @file{include/aout/stabs.def}. + +@menu +* Non-Stab Symbol Types:: Types from 0 to 0x1f +* Stab Symbol Types:: Types from 0x20 to 0xff +@end menu + +@node Non-Stab Symbol Types +@appendixsec Non-Stab Symbol Types + +The following types are used by the linker and assembler, not by stab +directives. Since this document does not attempt to describe aspects of +object file format other than the debugging format, no details are +given. + +@c Try to get most of these to fit on a single line. +@iftex +@tableindent=1.5in +@end iftex + +@table @code +@item 0x0 N_UNDF +Undefined symbol + +@item 0x2 N_ABS +File scope absolute symbol + +@item 0x3 N_ABS | N_EXT +External absolute symbol + +@item 0x4 N_TEXT +File scope text symbol + +@item 0x5 N_TEXT | N_EXT +External text symbol + +@item 0x6 N_DATA +File scope data symbol + +@item 0x7 N_DATA | N_EXT +External data symbol + +@item 0x8 N_BSS +File scope BSS symbol + +@item 0x9 N_BSS | N_EXT +External BSS symbol + +@item 0x0c N_FN_SEQ +Same as @code{N_FN}, for Sequent compilers + +@item 0x0a N_INDR +Symbol is indirected to another symbol + +@item 0x12 N_COMM +Common---visible after shared library dynamic link + +@item 0x14 N_SETA +@itemx 0x15 N_SETA | N_EXT +Absolute set element + +@item 0x16 N_SETT +@itemx 0x17 N_SETT | N_EXT +Text segment set element + +@item 0x18 N_SETD +@itemx 0x19 N_SETD | N_EXT +Data segment set element + +@item 0x1a N_SETB +@itemx 0x1b N_SETB | N_EXT +BSS segment set element + +@item 0x1c N_SETV +@itemx 0x1d N_SETV | N_EXT +Pointer to set vector + +@item 0x1e N_WARNING +Print a warning message during linking + +@item 0x1f N_FN +File name of a @file{.o} file +@end table + +@node Stab Symbol Types +@appendixsec Stab Symbol Types + +The following symbol types indicate that this is a stab. This is the +full list of stab numbers, including stab types that are used in +languages other than C. + +@table @code +@item 0x20 N_GSYM +Global symbol; see @ref{Global Variables}. + +@item 0x22 N_FNAME +Function name (for BSD Fortran); see @ref{Procedures}. + +@item 0x24 N_FUN +Function name (@pxref{Procedures}) or text segment variable +(@pxref{Statics}). + +@item 0x26 N_STSYM +Data segment file-scope variable; see @ref{Statics}. + +@item 0x28 N_LCSYM +BSS segment file-scope variable; see @ref{Statics}. + +@item 0x2a N_MAIN +Name of main routine; see @ref{Main Program}. + +@item 0x2c N_ROSYM +Variable in @code{.rodata} section; see @ref{Statics}. + +@item 0x30 N_PC +Global symbol (for Pascal); see @ref{N_PC}. + +@item 0x32 N_NSYMS +Number of symbols (according to Ultrix V4.0); see @ref{N_NSYMS}. + +@item 0x34 N_NOMAP +No DST map; see @ref{N_NOMAP}. + +@item 0x36 N_MAC_DEFINE +Name and body of a @code{#define}d macro; see @ref{Macro define and undefine}. + +@c FIXME: describe this solaris feature in the body of the text (see +@c comments in include/aout/stab.def). +@item 0x38 N_OBJ +Object file (Solaris2). + +@item 0x3a N_MAC_UNDEF +Name of an @code{#undef}ed macro; see @ref{Macro define and undefine}. + +@c See include/aout/stab.def for (a little) more info. +@item 0x3c N_OPT +Debugger options (Solaris2). + +@item 0x40 N_RSYM +Register variable; see @ref{Register Variables}. + +@item 0x42 N_M2C +Modula-2 compilation unit; see @ref{N_M2C}. + +@item 0x44 N_SLINE +Line number in text segment; see @ref{Line Numbers}. + +@item 0x46 N_DSLINE +Line number in data segment; see @ref{Line Numbers}. + +@item 0x48 N_BSLINE +Line number in bss segment; see @ref{Line Numbers}. + +@item 0x48 N_BROWS +Sun source code browser, path to @file{.cb} file; see @ref{N_BROWS}. + +@item 0x4a N_DEFD +GNU Modula2 definition module dependency; see @ref{N_DEFD}. + +@item 0x4c N_FLINE +Function start/body/end line numbers (Solaris2). + +@item 0x50 N_EHDECL +GNU C@t{++} exception variable; see @ref{N_EHDECL}. + +@item 0x50 N_MOD2 +Modula2 info "for imc" (according to Ultrix V4.0); see @ref{N_MOD2}. + +@item 0x54 N_CATCH +GNU C@t{++} @code{catch} clause; see @ref{N_CATCH}. + +@item 0x60 N_SSYM +Structure of union element; see @ref{N_SSYM}. + +@item 0x62 N_ENDM +Last stab for module (Solaris2). + +@item 0x64 N_SO +Path and name of source file; see @ref{Source Files}. + +@item 0x80 N_LSYM +Stack variable (@pxref{Stack Variables}) or type (@pxref{Typedefs}). + +@item 0x82 N_BINCL +Beginning of an include file (Sun only); see @ref{Include Files}. + +@item 0x84 N_SOL +Name of include file; see @ref{Include Files}. + +@item 0xa0 N_PSYM +Parameter variable; see @ref{Parameters}. + +@item 0xa2 N_EINCL +End of an include file; see @ref{Include Files}. + +@item 0xa4 N_ENTRY +Alternate entry point; see @ref{Alternate Entry Points}. + +@item 0xc0 N_LBRAC +Beginning of a lexical block; see @ref{Block Structure}. + +@item 0xc2 N_EXCL +Place holder for a deleted include file; see @ref{Include Files}. + +@item 0xc4 N_SCOPE +Modula2 scope information (Sun linker); see @ref{N_SCOPE}. + +@item 0xe0 N_RBRAC +End of a lexical block; see @ref{Block Structure}. + +@item 0xe2 N_BCOMM +Begin named common block; see @ref{Common Blocks}. + +@item 0xe4 N_ECOMM +End named common block; see @ref{Common Blocks}. + +@item 0xe8 N_ECOML +Member of a common block; see @ref{Common Blocks}. + +@c FIXME: How does this really work? Move it to main body of document. +@item 0xea N_WITH +Pascal @code{with} statement: type,,0,0,offset (Solaris2). + +@item 0xf0 N_NBTEXT +Gould non-base registers; see @ref{Gould}. + +@item 0xf2 N_NBDATA +Gould non-base registers; see @ref{Gould}. + +@item 0xf4 N_NBBSS +Gould non-base registers; see @ref{Gould}. + +@item 0xf6 N_NBSTS +Gould non-base registers; see @ref{Gould}. + +@item 0xf8 N_NBLCS +Gould non-base registers; see @ref{Gould}. +@end table + +@c Restore the default table indent +@iftex +@tableindent=.8in +@end iftex + +@node Symbol Descriptors +@appendix Table of Symbol Descriptors + +The symbol descriptor is the character which follows the colon in many +stabs, and which tells what kind of stab it is. @xref{String Field}, +for more information about their use. + +@c Please keep this alphabetical +@table @code +@c In TeX, this looks great, digit is in italics. But makeinfo insists +@c on putting it in `', not realizing that @var should override @code. +@c I don't know of any way to make makeinfo do the right thing. Seems +@c like a makeinfo bug to me. +@item @var{digit} +@itemx ( +@itemx - +Variable on the stack; see @ref{Stack Variables}. + +@item : +C@t{++} nested symbol; see @xref{Nested Symbols}. + +@item a +Parameter passed by reference in register; see @ref{Reference Parameters}. + +@item b +Based variable; see @ref{Based Variables}. + +@item c +Constant; see @ref{Constants}. + +@item C +Conformant array bound (Pascal, maybe other languages); @ref{Conformant +Arrays}. Name of a caught exception (GNU C@t{++}). These can be +distinguished because the latter uses @code{N_CATCH} and the former uses +another symbol type. + +@item d +Floating point register variable; see @ref{Register Variables}. + +@item D +Parameter in floating point register; see @ref{Register Parameters}. + +@item f +File scope function; see @ref{Procedures}. + +@item F +Global function; see @ref{Procedures}. + +@item G +Global variable; see @ref{Global Variables}. + +@item i +@xref{Register Parameters}. + +@item I +Internal (nested) procedure; see @ref{Nested Procedures}. + +@item J +Internal (nested) function; see @ref{Nested Procedures}. + +@item L +Label name (documented by AIX, no further information known). + +@item m +Module; see @ref{Procedures}. + +@item p +Argument list parameter; see @ref{Parameters}. + +@item pP +@xref{Parameters}. + +@item pF +Fortran Function parameter; see @ref{Parameters}. + +@item P +Unfortunately, three separate meanings have been independently invented +for this symbol descriptor. At least the GNU and Sun uses can be +distinguished by the symbol type. Global Procedure (AIX) (symbol type +used unknown); see @ref{Procedures}. Register parameter (GNU) (symbol +type @code{N_PSYM}); see @ref{Parameters}. Prototype of function +referenced by this file (Sun @code{acc}) (symbol type @code{N_FUN}). + +@item Q +Static Procedure; see @ref{Procedures}. + +@item R +Register parameter; see @ref{Register Parameters}. + +@item r +Register variable; see @ref{Register Variables}. + +@item S +File scope variable; see @ref{Statics}. + +@item s +Local variable (OS9000). + +@item t +Type name; see @ref{Typedefs}. + +@item T +Enumeration, structure, or union tag; see @ref{Typedefs}. + +@item v +Parameter passed by reference; see @ref{Reference Parameters}. + +@item V +Procedure scope static variable; see @ref{Statics}. + +@item x +Conformant array; see @ref{Conformant Arrays}. + +@item X +Function return variable; see @ref{Parameters}. +@end table + +@node Type Descriptors +@appendix Table of Type Descriptors + +The type descriptor is the character which follows the type number and +an equals sign. It specifies what kind of type is being defined. +@xref{String Field}, for more information about their use. + +@table @code +@item @var{digit} +@itemx ( +Type reference; see @ref{String Field}. + +@item - +Reference to builtin type; see @ref{Negative Type Numbers}. + +@item # +Method (C@t{++}); see @ref{Method Type Descriptor}. + +@item * +Pointer; see @ref{Miscellaneous Types}. + +@item & +Reference (C@t{++}). + +@item @@ +Type Attributes (AIX); see @ref{String Field}. Member (class and variable) +type (GNU C@t{++}); see @ref{Member Type Descriptor}. + +@item a +Array; see @ref{Arrays}. + +@item A +Open array; see @ref{Arrays}. + +@item b +Pascal space type (AIX); see @ref{Miscellaneous Types}. Builtin integer +type (Sun); see @ref{Builtin Type Descriptors}. Const and volatile +qualified type (OS9000). + +@item B +Volatile-qualified type; see @ref{Miscellaneous Types}. + +@item c +Complex builtin type (AIX); see @ref{Builtin Type Descriptors}. +Const-qualified type (OS9000). + +@item C +COBOL Picture type. See AIX documentation for details. + +@item d +File type; see @ref{Miscellaneous Types}. + +@item D +N-dimensional dynamic array; see @ref{Arrays}. + +@item e +Enumeration type; see @ref{Enumerations}. + +@item E +N-dimensional subarray; see @ref{Arrays}. + +@item f +Function type; see @ref{Function Types}. + +@item F +Pascal function parameter; see @ref{Function Types} + +@item g +Builtin floating point type; see @ref{Builtin Type Descriptors}. + +@item G +COBOL Group. See AIX documentation for details. + +@item i +Imported type (AIX); see @ref{Cross-References}. Volatile-qualified +type (OS9000). + +@item k +Const-qualified type; see @ref{Miscellaneous Types}. + +@item K +COBOL File Descriptor. See AIX documentation for details. + +@item M +Multiple instance type; see @ref{Miscellaneous Types}. + +@item n +String type; see @ref{Strings}. + +@item N +Stringptr; see @ref{Strings}. + +@item o +Opaque type; see @ref{Typedefs}. + +@item p +Procedure; see @ref{Function Types}. + +@item P +Packed array; see @ref{Arrays}. + +@item r +Range type; see @ref{Subranges}. + +@item R +Builtin floating type; see @ref{Builtin Type Descriptors} (Sun). Pascal +subroutine parameter; see @ref{Function Types} (AIX). Detecting this +conflict is possible with careful parsing (hint: a Pascal subroutine +parameter type will always contain a comma, and a builtin type +descriptor never will). + +@item s +Structure type; see @ref{Structures}. + +@item S +Set type; see @ref{Miscellaneous Types}. + +@item u +Union; see @ref{Unions}. + +@item v +Variant record. This is a Pascal and Modula-2 feature which is like a +union within a struct in C. See AIX documentation for details. + +@item w +Wide character; see @ref{Builtin Type Descriptors}. + +@item x +Cross-reference; see @ref{Cross-References}. + +@item Y +Used by IBM's xlC C@t{++} compiler (for structures, I think). + +@item z +gstring; see @ref{Strings}. +@end table + +@node Expanded Reference +@appendix Expanded Reference by Stab Type + +@c FIXME: This appendix should go away; see N_PSYM or N_SO for an example. + +For a full list of stab types, and cross-references to where they are +described, see @ref{Stab Types}. This appendix just covers certain +stabs which are not yet described in the main body of this document; +eventually the information will all be in one place. + +Format of an entry: + +The first line is the symbol type (see @file{include/aout/stab.def}). + +The second line describes the language constructs the symbol type +represents. + +The third line is the stab format with the significant stab fields +named and the rest NIL. + +Subsequent lines expand upon the meaning and possible values for each +significant stab field. + +Finally, any further information. + +@menu +* N_PC:: Pascal global symbol +* N_NSYMS:: Number of symbols +* N_NOMAP:: No DST map +* N_M2C:: Modula-2 compilation unit +* N_BROWS:: Path to .cb file for Sun source code browser +* N_DEFD:: GNU Modula2 definition module dependency +* N_EHDECL:: GNU C++ exception variable +* N_MOD2:: Modula2 information "for imc" +* N_CATCH:: GNU C++ "catch" clause +* N_SSYM:: Structure or union element +* N_SCOPE:: Modula2 scope information (Sun only) +* Gould:: non-base register symbols used on Gould systems +* N_LENG:: Length of preceding entry +@end menu + +@node N_PC +@section N_PC + +@deffn @code{.stabs} N_PC +@findex N_PC +Global symbol (for Pascal). + +@example +"name" -> "symbol_name" <> +value -> supposedly the line number (stab.def is skeptical) +@end example + +@display +@file{stabdump.c} says: + +global pascal symbol: name,,0,subtype,line +<< subtype? >> +@end display +@end deffn + +@node N_NSYMS +@section N_NSYMS + +@deffn @code{.stabn} N_NSYMS +@findex N_NSYMS +Number of symbols (according to Ultrix V4.0). + +@display + 0, files,,funcs,lines (stab.def) +@end display +@end deffn + +@node N_NOMAP +@section N_NOMAP + +@deffn @code{.stabs} N_NOMAP +@findex N_NOMAP +No DST map for symbol (according to Ultrix V4.0). I think this means a +variable has been optimized out. + +@display + name, ,0,type,ignored (stab.def) +@end display +@end deffn + +@node N_M2C +@section N_M2C + +@deffn @code{.stabs} N_M2C +@findex N_M2C +Modula-2 compilation unit. + +@example +"string" -> "unit_name,unit_time_stamp[,code_time_stamp]" +desc -> unit_number +value -> 0 (main unit) + 1 (any other unit) +@end example + +See @cite{Dbx and Dbxtool Interfaces}, 2nd edition, by Sun, 1988, for +more information. + +@end deffn + +@node N_BROWS +@section N_BROWS + +@deffn @code{.stabs} N_BROWS +@findex N_BROWS +Sun source code browser, path to @file{.cb} file + +<> +"path to associated @file{.cb} file" + +Note: N_BROWS has the same value as N_BSLINE. +@end deffn + +@node N_DEFD +@section N_DEFD + +@deffn @code{.stabn} N_DEFD +@findex N_DEFD +GNU Modula2 definition module dependency. + +GNU Modula-2 definition module dependency. The value is the +modification time of the definition file. The other field is non-zero +if it is imported with the GNU M2 keyword @code{%INITIALIZE}. Perhaps +@code{N_M2C} can be used if there are enough empty fields? +@end deffn + +@node N_EHDECL +@section N_EHDECL + +@deffn @code{.stabs} N_EHDECL +@findex N_EHDECL +GNU C@t{++} exception variable <>. + +"@var{string} is variable name" + +Note: conflicts with @code{N_MOD2}. +@end deffn + +@node N_MOD2 +@section N_MOD2 + +@deffn @code{.stab?} N_MOD2 +@findex N_MOD2 +Modula2 info "for imc" (according to Ultrix V4.0) + +Note: conflicts with @code{N_EHDECL} <> +@end deffn + +@node N_CATCH +@section N_CATCH + +@deffn @code{.stabn} N_CATCH +@findex N_CATCH +GNU C@t{++} @code{catch} clause + +GNU C@t{++} @code{catch} clause. The value is its address. The desc field +is nonzero if this entry is immediately followed by a @code{CAUGHT} stab +saying what exception was caught. Multiple @code{CAUGHT} stabs means +that multiple exceptions can be caught here. If desc is 0, it means all +exceptions are caught here. +@end deffn + +@node N_SSYM +@section N_SSYM + +@deffn @code{.stabn} N_SSYM +@findex N_SSYM +Structure or union element. + +The value is the offset in the structure. + +<> +@end deffn + +@node N_SCOPE +@section N_SCOPE + +@deffn @code{.stab?} N_SCOPE +@findex N_SCOPE +Modula2 scope information (Sun linker) +<> +@end deffn + +@node Gould +@section Non-base registers on Gould systems + +@deffn @code{.stab?} N_NBTEXT +@deffnx @code{.stab?} N_NBDATA +@deffnx @code{.stab?} N_NBBSS +@deffnx @code{.stab?} N_NBSTS +@deffnx @code{.stab?} N_NBLCS +@findex N_NBTEXT +@findex N_NBDATA +@findex N_NBBSS +@findex N_NBSTS +@findex N_NBLCS +These are used on Gould systems for non-base registers syms. + +However, the following values are not the values used by Gould; they are +the values which GNU has been documenting for these values for a long +time, without actually checking what Gould uses. I include these values +only because perhaps some someone actually did something with the GNU +information (I hope not, why GNU knowingly assigned wrong values to +these in the header file is a complete mystery to me). + +@example +240 0xf0 N_NBTEXT ?? +242 0xf2 N_NBDATA ?? +244 0xf4 N_NBBSS ?? +246 0xf6 N_NBSTS ?? +248 0xf8 N_NBLCS ?? +@end example +@end deffn + +@node N_LENG +@section N_LENG + +@deffn @code{.stabn} N_LENG +@findex N_LENG +Second symbol entry containing a length-value for the preceding entry. +The value is the length. +@end deffn + +@node Questions +@appendix Questions and Anomalies + +@itemize @bullet +@item +@c I think this is changed in GCC 2.4.5 to put the line number there. +For GNU C stabs defining local and global variables (@code{N_LSYM} and +@code{N_GSYM}), the desc field is supposed to contain the source +line number on which the variable is defined. In reality the desc +field is always 0. (This behavior is defined in @file{dbxout.c} and +putting a line number in desc is controlled by @samp{#ifdef +WINNING_GDB}, which defaults to false). GDB supposedly uses this +information if you say @samp{list @var{var}}. In reality, @var{var} can +be a variable defined in the program and GDB says @samp{function +@var{var} not defined}. + +@item +In GNU C stabs, there seems to be no way to differentiate tag types: +structures, unions, and enums (symbol descriptor @samp{T}) and typedefs +(symbol descriptor @samp{t}) defined at file scope from types defined locally +to a procedure or other more local scope. They all use the @code{N_LSYM} +stab type. Types defined at procedure scope are emitted after the +@code{N_RBRAC} of the preceding function and before the code of the +procedure in which they are defined. This is exactly the same as +types defined in the source file between the two procedure bodies. +GDB over-compensates by placing all types in block #1, the block for +symbols of file scope. This is true for default, @samp{-ansi} and +@samp{-traditional} compiler options. (Bugs gcc/1063, gdb/1066.) + +@item +What ends the procedure scope? Is it the proc block's @code{N_RBRAC} or the +next @code{N_FUN}? (I believe it's the first.) +@end itemize + +@node Stab Sections +@appendix Using Stabs in Their Own Sections + +Many object file formats allow tools to create object files with custom +sections containing any arbitrary data. For any such object file +format, stabs can be embedded in special sections. This is how stabs +are used with ELF and SOM, and aside from ECOFF and XCOFF, is how stabs +are used with COFF. + +@menu +* Stab Section Basics:: How to embed stabs in sections +* ELF Linker Relocation:: Sun ELF hacks +@end menu + +@node Stab Section Basics +@appendixsec How to Embed Stabs in Sections + +The assembler creates two custom sections, a section named @code{.stab} +which contains an array of fixed length structures, one struct per stab, +and a section named @code{.stabstr} containing all the variable length +strings that are referenced by stabs in the @code{.stab} section. The +byte order of the stabs binary data depends on the object file format. +For ELF, it matches the byte order of the ELF file itself, as determined +from the @code{EI_DATA} field in the @code{e_ident} member of the ELF +header. For SOM, it is always big-endian (is this true??? FIXME). For +COFF, it matches the byte order of the COFF headers. The meaning of the +fields is the same as for a.out (@pxref{Symbol Table Format}), except +that the @code{n_strx} field is relative to the strings for the current +compilation unit (which can be found using the synthetic N_UNDF stab +described below), rather than the entire string table. + +The first stab in the @code{.stab} section for each compilation unit is +synthetic, generated entirely by the assembler, with no corresponding +@code{.stab} directive as input to the assembler. This stab contains +the following fields: + +@table @code +@item n_strx +Offset in the @code{.stabstr} section to the source filename. + +@item n_type +@code{N_UNDF}. + +@item n_other +Unused field, always zero. +This may eventually be used to hold overflows from the count in +the @code{n_desc} field. + +@item n_desc +Count of upcoming symbols, i.e., the number of remaining stabs for this +source file. + +@item n_value +Size of the string table fragment associated with this source file, in +bytes. +@end table + +The @code{.stabstr} section always starts with a null byte (so that string +offsets of zero reference a null string), followed by random length strings, +each of which is null byte terminated. + +The ELF section header for the @code{.stab} section has its +@code{sh_link} member set to the section number of the @code{.stabstr} +section, and the @code{.stabstr} section has its ELF section +header @code{sh_type} member set to @code{SHT_STRTAB} to mark it as a +string table. SOM and COFF have no way of linking the sections together +or marking them as string tables. + +For COFF, the @code{.stab} and @code{.stabstr} sections may be simply +concatenated by the linker. GDB then uses the @code{n_desc} fields to +figure out the extent of the original sections. Similarly, the +@code{n_value} fields of the header symbols are added together in order +to get the actual position of the strings in a desired @code{.stabstr} +section. Although this design obviates any need for the linker to +relocate or otherwise manipulate @code{.stab} and @code{.stabstr} +sections, it also requires some care to ensure that the offsets are +calculated correctly. For instance, if the linker were to pad in +between the @code{.stabstr} sections before concatenating, then the +offsets to strings in the middle of the executable's @code{.stabstr} +section would be wrong. + +The GNU linker is able to optimize stabs information by merging +duplicate strings and removing duplicate header file information +(@pxref{Include Files}). When some versions of the GNU linker optimize +stabs in sections, they remove the leading @code{N_UNDF} symbol and +arranges for all the @code{n_strx} fields to be relative to the start of +the @code{.stabstr} section. + +@node ELF Linker Relocation +@appendixsec Having the Linker Relocate Stabs in ELF + +This section describes some Sun hacks for Stabs in ELF; it does not +apply to COFF or SOM. While @value{GDBN} no longer supports this hack +for Sun Stabs in ELF, this section is kept to document the issue. + +To keep linking fast, you don't want the linker to have to relocate very +many stabs. Making sure this is done for @code{N_SLINE}, +@code{N_RBRAC}, and @code{N_LBRAC} stabs is the most important thing +(see the descriptions of those stabs for more information). But Sun's +stabs in ELF has taken this further, to make all addresses in the +@code{n_value} field (functions and static variables) relative to the +source file. For the @code{N_SO} symbol itself, Sun simply omits the +address. To find the address of each section corresponding to a given +source file, the compiler puts out symbols giving the address of each +section for a given source file. Since these are ELF (not stab) +symbols, the linker relocates them correctly without having to touch the +stabs section. They are named @code{Bbss.bss} for the bss section, +@code{Ddata.data} for the data section, and @code{Drodata.rodata} for +the rodata section. For the text section, there is no such symbol (but +there should be, see below). For an example of how these symbols work, +@xref{Stab Section Transformations}. GCC does not provide these symbols; +it instead relies on the stabs getting relocated. Thus addresses which +would normally be relative to @code{Bbss.bss}, etc., are already +relocated. The Sun linker provided with Solaris 2.2 and earlier +relocates stabs using normal ELF relocation information, as it would do +for any section. Sun has been threatening to kludge their linker to not +do this (to speed up linking), even though the correct way to avoid +having the linker do these relocations is to have the compiler no longer +output relocatable values. Last I heard they had been talked out of the +linker kludge. See Sun point patch 101052-01 and Sun bug 1142109. With +the Sun compiler this affects @samp{S} symbol descriptor stabs +(@pxref{Statics}) and functions (@pxref{Procedures}). In the latter +case, to adopt the clean solution (making the value of the stab relative +to the start of the compilation unit), it would be necessary to invent a +@code{Ttext.text} symbol, analogous to the @code{Bbss.bss}, etc., +symbols. I recommend this rather than using a zero value and getting +the address from the ELF symbols. + +Finding the correct @code{Bbss.bss}, etc., symbol is difficult, because +the linker simply concatenates the @code{.stab} sections from each +@file{.o} file without including any information about which part of a +@code{.stab} section comes from which @file{.o} file. The way GDB use to +do this is to look for an ELF @code{STT_FILE} symbol which has the same +name as the last component of the file name from the @code{N_SO} symbol +in the stabs (for example, if the file name is @file{../../gdb/main.c}, +it looks for an ELF @code{STT_FILE} symbol named @code{main.c}). This +loses if different files have the same name (they could be in different +directories, a library could have been copied from one system to +another, etc.). It would be much cleaner to have the @code{Bbss.bss} +symbols in the stabs themselves. Having the linker relocate them there +is no more work than having the linker relocate ELF symbols, and it +solves the problem of having to associate the ELF and stab symbols. +However, no one has yet designed or implemented such a scheme. + +@node GNU Free Documentation License +@appendix GNU Free Documentation License +@include fdl.texi + +@node Symbol Types Index +@unnumbered Symbol Types Index + +@printindex fn + +@bye diff -pruN 16.3-5/libctf/doc/ctf-spec.info 16.3-5ubuntu1/libctf/doc/ctf-spec.info --- 16.3-5/libctf/doc/ctf-spec.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/libctf/doc/ctf-spec.info 2025-04-20 17:25:30.000000000 +0000 @@ -0,0 +1,1755 @@ +This is ctf-spec.info, produced by makeinfo version 6.8 from +ctf-spec.texi. + +Copyright (C) 2021-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License, Version 3 or any +later version published by the Free Software Foundation. A copy of the +license is included in the section entitled "GNU General Public +License". + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* CTF: (ctf-spec). The CTF file format. +END-INFO-DIR-ENTRY + + +File: ctf-spec.info, Node: Top, Next: Overview, Up: (dir) + +The CTF file format +******************* + +This manual describes version 3 of the CTF file format, which is +intended to model the C type system in a fashion that C programs can +consume at runtime. + +* Menu: + +* Overview:: +* CTF archive:: +* CTF dictionaries:: +* Index:: + + +File: ctf-spec.info, Node: Overview, Next: CTF archive, Prev: Top, Up: Top + +Overview +******** + +The CTF file format compactly describes C types and the association +between function and data symbols and types: if embedded in ELF objects, +it can exploit the ELF string table to reduce duplication further. +There is no real concept of namespacing: only top-level types are +described, not types scoped to within single functions. + + CTF dictionaries can be "children" of other dictionaries, in a +one-level hierarchy: child dictionaries can refer to types in the +parent, but the opposite is not sensible (since if you refer to a child +type in the parent, the actual type you cited would vary depending on +what child was attached). This parent/child definition is recorded in +the child, but only as a recommendation: users of the API have to attach +parents to children explicitly, and can choose to attach a child to any +parent they like, or to none, though doing so might lead to unpleasant +consequences like dangling references to types. *Note Type indexes and +type IDs::. Type lookups in child dicts that are not associated with a +parent at all will fail with 'ECTF_NOPARENT' if a parent type was +needed. + + The associated API to generate, merge together, and query this file +format will be described in the accompanying 'libctf' manual once it is +written. There is no API to modify dictionaries once they've been +written out: CTF is a write-once file format. (However, it is always +possible to dynamically create a new child dictionary on the fly and +attach it to a pre-existing, read-only parent.) + + There are two major pieces to CTF: the "archive" and the +"dictionary". Some relatives and ancestors of CTF call dictionaries +"containers": the archive format is unique to this variant of CTF. (Much +of the source code still uses the old term.) + + The archive file format is a very simple mmappable archive used to +group multiple dictionaries together into groups: it is expected to +slowly go away and be replaced by other mechanisms, but right now it is +an important part of the file format, used to group dictionaries +containing types with conflicting definitions in different TUs with the +overarching dictionary used to store all other types. (Even when +archives go away, the 'libctf' API used to access them will remain, and +access the other mechanisms that replace it instead.) + + The CTF dictionary consists of a "preamble", which does not vary +between versions of the CTF file format, and a "header" and some number +of "sections", which can vary between versions. + + The rest of this specification describes the format of these +sections, first for the latest version of CTF, then for all earlier +versions supported by 'libctf': the earlier versions are defined in +terms of their differences from the next later one. We describe each +part of the format first by reproducing the C structure which defines +that part, then describing it at greater length in terms of file +offsets. + + The description of the file format ends with a description of +relevant limits that apply to it. These limits can vary between file +format versions. + + This document is quite young, so for now the C code in 'ctf.h' should +be presumed correct when this document conflicts with it. + + +File: ctf-spec.info, Node: CTF archive, Next: CTF dictionaries, Prev: Overview, Up: Top + +1 CTF archives +************** + +The CTF archive format maps names to CTF dictionaries. The names may +contain any character other than \0, but for now archives containing +slashes in the names may not extract correctly. It is possible to +insert multiple members with the same name, but these are quite hard to +access reliably (you have to iterate through all the members rather than +opening by name) so this is not recommended. + + CTF archives are not themselves compressed: the constituent +components, CTF dictionaries, can be compressed. (*Note CTF header::). + + CTF archives usually contain a collection of related dictionaries, +one parent and many children of that parent. CTF archives can have a +member with a "default name", '.ctf' (which can be represented as 'NULL' +in the API). If present, this member is usually the parent of all the +children, but it is possible for CTF producers to emit parents with +different names if they wish (usually for backward- compatibility +purposes). + + '.ctf' sections in ELF objects consist of a single CTF dictionary +rather than an archive of dictionaries if and only if the section +contains no types with identical names but conflicting definitions: if +two conflicting definitions exist, the deduplicator will place the type +most commonly referred to by other types in the parent and will place +the other type in a child named after the translation unit it is found +in, and will emit a CTF archive containing both dictionaries instead of +a raw dictionary. All types that refer to such conflicting types are +also placed in the per-translation-unit child. + + The definition of an archive in 'ctf.h' is as follows: + +struct ctf_archive +{ + uint64_t ctfa_magic; + uint64_t ctfa_model; + uint64_t ctfa_nfiles; + uint64_t ctfa_names; + uint64_t ctfa_ctfs; +}; + +typedef struct ctf_archive_modent +{ + uint64_t name_offset; + uint64_t ctf_offset; +} ctf_archive_modent_t; + + (Note one irregularity here: the 'ctf_archive_t' is not a typedef to +'struct ctf_archive', but a different typedef, private to 'libctf', so +that things that are not really archives can be made to appear as if +they were.) + + All the above items are always in little-endian byte order, +regardless of the machine endianness. + + The archive header has the following fields: + +Offset Name Description +------------------------------------------------------------------------------------------ +0x00 'uint64_t ctfa_magic' The magic number for archives, 'CTFA_MAGIC': + 0x8b47f2a4d7623eeb. + +0x08 'uint64_t ctfa_model' The data model for this archive: an arbitrary integer + that serves no purpose but to be handed back by the + libctf API. *Note Data models::. + +0x10 'uint64_t ctfa_nfiles' The number of CTF dictionaries in this archive. + +0x18 'uint64_t ctfa_names' Offset of the name table, in bytes from the start of + the archive. The name table is an array of 'struct + ctf_archive_modent_t[ctfa_nfiles]'. + +0x20 'uint64_t ctfa_ctfs' Offset of the CTF table. Each element starts with a + 'uint64_t' size, followed by a CTF dictionary. + + + The array pointed to by 'ctfa_names' is an array of entries of +'ctf_archive_modent': + +Offset Name Description +--------------------------------------------------------------------------------- +0x00 'uint64_t name_offset' Offset of this name, in bytes from the start + of the archive. + +0x08 'uint64_t ctf_offset' Offset of this CTF dictionary, in bytes from + the start of the archive. + + + The 'ctfa_names' array is sorted into ASCIIbetical order by name +(i.e. by the result of dereferencing the 'name_offset'). + + The archive file also contains a name table and a table of CTF +dictionaries: these are pointed to by the structures above. The name +table is a simple strtab which is not required to be sorted; the +dictionary array is described above in the entry for 'ctfa_ctfs'. + + The relative order of these various parts is not defined, except that +the header naturally always comes first. + + +File: ctf-spec.info, Node: CTF dictionaries, Next: Index, Prev: CTF archive, Up: Top + +2 CTF dictionaries +****************** + +CTF dictionaries consist of a header, starting with a premable, and a +number of sections. + +* Menu: + +* CTF Preamble:: +* CTF header:: +* The type section:: +* The symtypetab sections:: +* The variable section:: +* The label section:: +* The string section:: +* Data models:: +* Limits of CTF:: + + +File: ctf-spec.info, Node: CTF Preamble, Next: CTF header, Up: CTF dictionaries + +2.1 CTF Preamble +================ + +The preamble is the only part of the CTF dictionary whose format cannot +vary between versions. It is never compressed. It is correspondingly +simple: + +typedef struct ctf_preamble +{ + unsigned short ctp_magic; + unsigned char ctp_version; + unsigned char ctp_flags; +} ctf_preamble_t; + + '#define's are provided under the names 'cth_magic', 'cth_version' +and 'cth_flags' to make the fields of the 'ctf_preamble_t' appear to be +part of the 'ctf_header_t', so consuming programs rarely need to +consider the existence of the preamble as a separate structure. + +Offset Name Description +------------------------------------------------------------------------------- +0x00 'unsigned short ctp_magic' The magic number for CTF + dictionaries, 'CTF_MAGIC': 0xdff2. + +0x02 'unsigned char ctp_version' The version number of this CTF + dictionary. + +0x03 'ctp_flags' Flags for this CTF file. + *Note CTF file-wide flags::. + + Every element of a dictionary must be naturally aligned unless +otherwise specified. (This restriction will be lifted in later +versions.) + + CTF dictionaries are stored in the native endianness of the system +that generates them: the consumer (e.g., 'libctf') can detect whether to +endian-flip a CTF dictionary by inspecting the 'ctp_magic'. (If it +appears as 0xf2df, endian-flipping is needed.) + + The version of the CTF dictionary can be determined by inspecting +'ctp_version'. The following versions are currently valid, and 'libctf' +can read all of them: + +Version Number Description +------------------------------------------------------------------------------------------- +'CTF_VERSION_1' 1 First version, rare. Very similar to Solaris CTF. + +'CTF_VERSION_1_UPGRADED_3' 2 First version, upgraded to v3 or higher and + written out again. Name may change. Very rare. + +'CTF_VERSION_2' 3 Second version, with many range limits lifted. + +'CTF_VERSION_3' 4 Third and current version, documented here. + + This section documents 'CTF_VERSION_3'. + +* Menu: + +* CTF file-wide flags:: + + +File: ctf-spec.info, Node: CTF file-wide flags, Up: CTF Preamble + +2.1.1 CTF file-wide flags +------------------------- + +The preamble contains bitflags in its 'ctp_flags' field that describe +various file-wide properties. Some of the flags are valid only for +particular file-format versions, which means the flags can be used to +fix file-format bugs. Consumers that see unknown flags should +accordingly assume that the dictionary is not comprehensible, and refuse +to open them. + + The following flags are currently defined. Many are bug workarounds, +valid only in CTFv3, and will not be valid in any future versions: the +same values may be reused for other flags in v4+. + +Flag Versions Value Meaning +--------------------------------------------------------------------------------------- +'CTF_F_COMPRESS' All 0x1 Compressed with zlib +'CTF_F_NEWFUNCINFO' 3 only 0x2 "New-format" func info section. +'CTF_F_IDXSORTED' 3+ 0x4 The index section is in sorted order +'CTF_F_DYNSTR' 3 only 0x8 The external strtab is in '.dynstr' and the + symtab used is '.dynsym'. + *Note The string section:: + + 'CTF_F_NEWFUNCINFO' and 'CTF_F_IDXSORTED' relate to the function info +and data object sections. *Note The symtypetab sections::. + + Further flags (and further compression methods) wil be added in +future. + + +File: ctf-spec.info, Node: CTF header, Next: The type section, Prev: CTF Preamble, Up: CTF dictionaries + +2.2 CTF header +============== + +The CTF header is the first part of a CTF dictionary, including the +preamble. All parts of it other than the preamble (*note CTF +Preamble::) can vary between CTF file versions and are never compressed. +It contains things that apply to the dictionary as a whole, and a table +of the sections into which the rest of the dictionary is divided. The +sections tile the file: each section runs from the offset given until +the start of the next section. Only the last section cannot follow this +rule, so the header has a length for it instead. + + All section offsets, here and in the rest of the CTF file, are +relative to the _end_ of the header. (This is annoyingly different to +how offsets in CTF archives are handled.) + + This is the first structure to include offsets into the string table, +which are not straight references because CTF dictionaries can include +references into the ELF string table to save space, as well as into the +string table internal to the CTF dictionary. *Note The string section:: +for more on these. Offset 0 is always the null string. + +typedef struct ctf_header +{ + ctf_preamble_t cth_preamble; + uint32_t cth_parlabel; + uint32_t cth_parname; + uint32_t cth_cuname; + uint32_t cth_lbloff; + uint32_t cth_objtoff; + uint32_t cth_funcoff; + uint32_t cth_objtidxoff; + uint32_t cth_funcidxoff; + uint32_t cth_varoff; + uint32_t cth_typeoff; + uint32_t cth_stroff; + uint32_t cth_strlen; +} ctf_header_t; + + In detail: + +Offset Name Description +----------------------------------------------------------------------------------------------- +0x00 'ctf_preamble_t cth_preamble' The preamble (conceptually embedded in the header). + *Note CTF Preamble:: + +0x04 'uint32_t cth_parlabel' The parent label, if deduplication happened against + a specific label: a strtab offset. + *Note The label section::. Currently unused and + always 0, but may be used in future when semantics + are attached to the label section. + +0x08 'uint32_t cth_parname' The name of the parent dictionary deduplicated + against: a strtab offset. Interpretation is up to + the consumer (usually a CTF archive member name). + 0 (the null string) if this is not a child + dictionary. + +0x1c 'uint32_t cth_cuname' The name of the compilation unit, for consumers + like GDB that want to know the name of CUs + associated with single CUs: a strtab offset. 0 if + this dictionary describes types from many CUs. + +0x10 'uint32_t cth_lbloff' The offset of the label section, which tiles the + type space into named regions. + *Note The label section::. + +0x14 'uint32_t cth_objtoff' The offset of the data object symtypetab section, + which maps ELF data symbols to types. + *Note The symtypetab sections::. + +0x18 'uint32_t cth_funcoff' The offset of the function info symtypetab section, + which maps ELF function symbols to a return type + and arg types. *Note The symtypetab sections::. + +0x1c 'uint32_t cth_objtidxoff' The offset of the object index section, which maps + ELF object symbols to entries in the data object + section. *Note The symtypetab sections::. + +0x20 'uint32_t cth_funcidxoff' The offset of the function info index section, + which maps ELF function symbols to entries in the + function info section. + *Note The symtypetab sections::. + +0x24 'uint32_t cth_varoff' The offset of the variable section, which maps + string names to types. + *Note The variable section::. + +0x28 'uint32_t cth_typeoff' The offset of the type section, the core of CTF, + which describes types using variable-length array + elements. *Note The type section::. + +0x2c 'uint32_t cth_stroff' The offset of the string section. + *Note The string section::. + +0x30 'uint32_t cth_strlen' The length of the string section (not an offset!). + The CTF file ends at this point. + + + Everything from this point on (until the end of the file at +'cth_stroff' + 'cth_strlen') is compressed with zlib if 'CTF_F_COMPRESS' +is set in the preamble's 'ctp_flags'. + + +File: ctf-spec.info, Node: The type section, Next: The symtypetab sections, Prev: CTF header, Up: CTF dictionaries + +2.3 The type section +==================== + +This section is the most important section in CTF, describing all the +top-level types in the program. It consists of an array of type +structures, each of which describes a type of some "kind": each kind of +type has some amount of variable-length data associated with it (some +kinds have none). The amount of variable-length data associated with a +given type can be determined by inspecting the type, so the reading code +can walk through the types in sequence at opening time. + + Each type structure is one of a set of overlapping structures in a +discriminated union of sorts: the variable-length data for each type +immediately follows the type's type structure. Here's the largest of +the overlapping structures, which is only needed for huge types and so +is very rarely seen: + +typedef struct ctf_type +{ + uint32_t ctt_name; + uint32_t ctt_info; + __extension__ + union + { + uint32_t ctt_size; + uint32_t ctt_type; + }; + uint32_t ctt_lsizehi; + uint32_t ctt_lsizelo; +} ctf_type_t; + + Here's the much more common smaller form: + +typedef struct ctf_stype +{ + uint32_t ctt_name; + uint32_t ctt_info; + __extension__ + union + { + uint32_t ctt_size; + uint32_t ctt_type; + }; +} ctf_stype_t; + + If 'ctt_size' is the #define 'CTF_LSIZE_SENT', 0xffffffff, this type +is described by a 'ctf_type_t': otherwise, a 'ctf_stype_t'. + + Here's what the fields mean: + +Offset Name Description +----------------------------------------------------------------------------------------------------- +0x00 'uint32_t ctt_name' Strtab offset of the type name, if any (0 if none). + +0x04 'uint32_t ctt_info' The "info word", containing information on the kind + of this type, its variable-length data and whether + it is visible to name lookup. See + *Note The info word::. + +0x08 'uint32_t ctt_size' The size of this type, if this type is of a kind for + which a size needs to be recorded (constant-size + types don't need one). If this is 'CTF_LSIZE_SENT', + this type is a huge type described by 'ctf_type_t'. + +0x08 'uint32_t ctt_type' The type this type refers to, if this type is of a + kind which refers to other types (like a pointer). + All such types are fixed-size, and no types that are + variable-size refer to other types, so 'ctt_size' + and 'ctt_type' overlap. All type kinds that use + 'ctt_type' are described by 'ctf_stype_t', not + 'ctf_type_t'. *Note Type indexes and type IDs::. + +0x0c ('ctf_type_t' 'uint32_t ctt_lsizehi' The high 32 bits of the size of a very large type. +only) The 'CTF_TYPE_LSIZE' macro can be used to get a + 64-bit size out of this field and the next one. + 'CTF_SIZE_TO_LSIZE_HI' splits the 'ctt_lsizehi' out + of it again. + +0x10 ('ctf_type_t' 'uint32_t ctt_lsizelo' The low 32 bits of the size of a very large type. +only) 'CTF_SIZE_TO_LSIZE_LO' splits the 'ctt_lsizelo' out + of a 64-bit size. + + Two aspects of this need further explanation: the info word, and what +exactly a type ID is and how you determine it. (Information on the +various type-kind- dependent things, like whether 'ctt_size' or +'ctt_type' is used, is described in the section devoted to each kind.) + +* Menu: + +* The info word:: +* Type indexes and type IDs:: +* Type kinds:: +* Integer types:: +* Floating-point types:: +* Slices:: +* Pointers typedefs and cvr-quals:: +* Arrays:: +* Function pointers:: +* Enums:: +* Structs and unions:: +* Forward declarations:: + + +File: ctf-spec.info, Node: The info word, Next: Type indexes and type IDs, Up: The type section + +2.3.1 The info word, ctt_info +----------------------------- + +The info word is a bitfield split into three parts. From MSB to LSB: + +Bit offset Name Description +------------------------------------------------------------------------------------------ +26-31 'kind' Type kind: *note Type kinds::. + +25 'isroot' 1 if this type is visible to name lookup + +0-24 'vlen' Length of variable-length data for this type (some kinds only). + The variable-length data directly follows the 'ctf_type_t' or + 'ctf_stype_t'. This is a kind-dependent array length value, + not a length in bytes. Some kinds have no variable-length + data, or fixed-size variable-length data, and do not use this + value. + + The most mysterious of these is undoubtedly 'isroot'. This indicates +whether types with names (nonzero 'ctt_name') are visible to name +lookup: if zero, this type is considered a "non-root type" and you can't +look it up by name at all. Multiple types with the same name in the +same C namespace (struct, union, enum, other) can exist in a single +dictionary, but only one of them may have a nonzero value for 'isroot'. +'libctf' validates this at open time and refuses to open dictionaries +that violate this constraint. + + Historically, this feature was introduced for the encoding of +bitfields (*note Integer types::): for instance, int bitfields will all +be named 'int' with different widths or offsets, but only the full-width +one at offset zero is wanted when you look up the type named 'int'. +With the introduction of slices (*note Slices::) as a more general +bitfield encoding mechanism, this is less important, but we still use +non-root types to handle conflicts if the linker API is used to fuse +multiple translation units into one dictionary and those translation +units contain types with the same name and conflicting definitions. (We +do not discuss this further here, because the linker never does this: +only specialized type mergers do, like that used for the Linux kernel. +The libctf documentation will describe this in more detail.) + + The 'CTF_TYPE_INFO' macro can be used to compose an info word from a +'kind', 'isroot', and 'vlen'; 'CTF_V2_INFO_KIND', 'CTF_V2_INFO_ISROOT' +and 'CTF_V2_INFO_VLEN' pick it apart again. + + +File: ctf-spec.info, Node: Type indexes and type IDs, Next: Type kinds, Prev: The info word, Up: The type section + +2.3.2 Type indexes and type IDs +------------------------------- + +Types are referred to within the CTF file via "type IDs". A type ID is +a number from 0 to 2^32, from a space divided in half. Types 2^31-1 and +below are in the "parent range": these IDs are used for dictionaries +that have not had any other dictionary 'ctf_import'ed into it as a +parent. Both completely standalone dictionaries and parent dictionaries +with children hanging off them have types in this range. Types 2^31 and +above are in the "child range": only types in child dictionaries are in +this range. + + These IDs appear in 'ctf_type_t.ctt_type' (*note The type section::), +but the types themselves have no visible ID: quite intentionally, +because adding an ID uses space, and every ID is different so they don't +compress well. The IDs are implicit: at open time, the consumer walks +through the entire type section and counts the types in the type +section. The type section is an array of variable-length elements, so +each entry could be considered as having an index, starting from 1. We +count these indexes and associate each with its corresponding +'ctf_type_t' or 'ctf_stype_t'. + + Lookups of types with IDs in the parent space look in the parent +dictionary if this dictionary has one associated with it; lookups of +types with IDs in the child space error out if the dictionary does not +have a parent, and otherwise convert the ID into an index by shaving off +the top bit and look up the index in the child. + + These properties mean that the same dictionary can be used as a +parent of child dictionaries and can also be used directly with no +children at all, but a dictionary created as a child dictionary must +always be associated with a parent -- usually, the same parent -- +because its references to its own types have the high bit turned on and +this is only flipped off again if this is a child dictionary. (This is +not a problem, because if you _don't_ associate the child with a parent, +any references within it to its parent types will fail, and there are +almost certain to be many such references, or why is it a child at all?) + + This does mean that consumers should keep a close eye on the +distinction between type IDs and type indexes: if you mix them up, +everything will appear to work as long as you're only using parent +dictionaries or standalone dictionaries, but as soon as you start using +children, everything will fail horribly. + + Type index zero, and type ID zero, are used to indicate that this +type cannot be represented in CTF as currently constituted: they are +emitted by the compiler, but all type chains that terminate in the +unknown type are erased at link time (structure fields that use them +just vanish, etc). So you will probably never see a use of type zero +outside the symtypetab sections, where they serve as sentinels of sorts, +to indicate symbols with no associated type. + + The macros 'CTF_V2_TYPE_TO_INDEX' and 'CTF_V2_INDEX_TO_TYPE' may help +in translation between types and indexes: 'CTF_V2_TYPE_ISPARENT' and +'CTF_V2_TYPE_ISCHILD' can be used to tell whether a given ID is in the +parent or child range. + + It is quite possible and indeed common for type IDs to point forward +in the dictionary, as well as backward. + + +File: ctf-spec.info, Node: Type kinds, Next: Integer types, Prev: Type indexes and type IDs, Up: The type section + +2.3.3 Type kinds +---------------- + +Every type in CTF is of some "kind". Each kind is some variety of C +type: all structures are a single kind, as are all unions, all pointers, +all arrays, all integers regardless of their bitfield width, etc. The +kind of a type is given in the 'kind' field of the 'ctt_info' word +(*note The info word::). + + The space of type kinds is only a quarter full so far, so there is +plenty of room for expansion. It is likely that in future versions of +the file format, types with smaller kinds will be more efficiently +encoded than types with larger kinds, so their numerical value will +actually start to matter in future. (So these IDs will probably change +their numerical values in a later release of this format, to move more +frequently-used kinds like structures and cv-quals towards the top of +the space, and move rarely-used kinds like integers downwards. Yes, +integers are rare: how many kinds of 'int' are there in a program? +They're just very frequently _referenced_.) + + Here's the set of kinds so far. Each kind has a '#define' associated +with it, also given here. + +Kind Macro Purpose +---------------------------------------------------------------------------------------- +0 'CTF_K_UNKNOWN' Indicates a type that cannot be represented in CTF, or that + is being skipped. It is very similar to type ID 0, except + that you can have _multiple_, distinct types of kind + 'CTF_K_UNKNOWN'. + +1 'CTF_K_INTEGER' An integer type. *Note Integer types::. + +2 'CTF_K_FLOAT' A floating-point type. *Note Floating-point types::. + +3 'CTF_K_POINTER' A pointer. *Note Pointers typedefs and cvr-quals::. + +4 'CTF_K_ARRAY' An array. *Note Arrays::. + +5 'CTF_K_FUNCTION' A function pointer. *Note Function pointers::. + +6 'CTF_K_STRUCT' A structure. *Note Structs and unions::. + +7 'CTF_K_UNION' A union. *Note Structs and unions::. + +8 'CTF_K_ENUM' An enumerated type. *Note Enums::. + +9 'CTF_K_FORWARD' A forward. *Note Forward declarations::. + +10 'CTF_K_TYPEDEF' A typedef. *Note Pointers typedefs and cvr-quals::. + +11 'CTF_K_VOLATILE' A volatile-qualified type. + *Note Pointers typedefs and cvr-quals::. + +12 'CTF_K_CONST' A const-qualified type. + *Note Pointers typedefs and cvr-quals::. + +13 'CTF_K_RESTRICT' A restrict-qualified type. + *Note Pointers typedefs and cvr-quals::. + +14 'CTF_K_SLICE' A slice, a change of the bit-width or offset of some other + type. *Note Slices::. + + Now we cover all type kinds in turn. Some are more complicated than +others. + + +File: ctf-spec.info, Node: Integer types, Next: Floating-point types, Prev: Type kinds, Up: The type section + +2.3.4 Integer types +------------------- + +Integral types are all represented as types of kind 'CTF_K_INTEGER'. +These types fill out 'ctt_size' in the 'ctf_stype_t' with the size in +bytes of the integral type in question. They are always represented by +'ctf_stype_t', never 'ctf_type_t'. Their variable-length data is one +'uint32_t' in length: 'vlen' in the info word should be disregarded and +is always zero. + + The variable-length data for integers has multiple items packed into +it much like the info word does. + +Bit offset Name Description +----------------------------------------------------------------------------------- +24-31 Encoding The desired display representation of this integer. You + can extract this field with the 'CTF_INT_ENCODING' + macro. See below. + +16-23 Offset The offset of this integral type in bits from the start + of its enclosing structure field, adjusted for + endianness: *note Structs and unions::. You can extract + this field with the 'CTF_INT_OFFSET' macro. + +0-15 Bit-width The width of this integral type in bits. You can + extract this field with the 'CTF_INT_BITS' macro. + + If you choose, bitfields can be represented using the things above as +a sort of integral type with the 'isroot' bit flipped off and the offset +and bits values set in the vlen word: you can populate it with the +'CTF_INT_DATA' macro. (But it may be more convenient to represent them +using slices of a full-width integer: *note Slices::.) + + Integers that are bitfields usually have a 'ctt_size' rounded up to +the nearest power of two in bytes, for natural alignment (e.g. a 17-bit +integer would have a 'ctt_size' of 4). However, not all types are +naturally aligned on all architectures: packed structures may in theory +use integral bitfields with different 'ctt_size', though this is rarely +observed. + + The "encoding" for integers is a bit-field comprised of the values +below, which consumers can use to decide how to display values of this +type: + +Offset Name Description +-------------------------------------------------------------------------------------------------------- +0x01 'CTF_INT_SIGNED' If set, this is a signed int: if false, unsigned. + +0x02 'CTF_INT_CHAR' If set, this is a char type. It is platform-dependent whether unadorned + 'char' is signed or not: the 'CTF_CHAR' macro produces an integral type + suitable for the definition of 'char' on this platform. + +0x04 'CTF_INT_BOOL' If set, this is a boolean type. (It is theoretically possible to turn + this and 'CTF_INT_CHAR' on at the same time, but it is not clear what + this would mean.) + +0x08 'CTF_INT_VARARGS' If set, this is a varargs-promoted value in a K&R function definition. + This is not currently produced or consumed by anything that we know of: + it is set aside for future use. + + The GCC "'Complex int'" and fixed-point extensions are not yet +supported: references to such types will be emitted as type 0. + + +File: ctf-spec.info, Node: Floating-point types, Next: Slices, Prev: Integer types, Up: The type section + +2.3.5 Floating-point types +-------------------------- + +Floating-point types are all represented as types of kind 'CTF_K_FLOAT'. +Like integers, These types fill out 'ctt_size' in the 'ctf_stype_t' with +the size in bytes of the floating-point type in question. They are +always represented by 'ctf_stype_t', never 'ctf_type_t'. + + This part of CTF shows many rough edges in the more obscure corners +of floating-point handling, and is likely to change in format v4. + + The variable-length data for floats has multiple items packed into it +just like integers do: + +Bit offset Name Description +------------------------------------------------------------------------------------------- +24-31 Encoding The desired display representation of this float. You can + extract this field with the 'CTF_FP_ENCODING' macro. See below. + +16-23 Offset The offset of this floating-point type in bits from the start of + its enclosing structure field, adjusted for endianness: + *note Structs and unions::. You can extract this field with the + 'CTF_FP_OFFSET' macro. + +0-15 Bit-width The width of this floating-point type in bits. You can extract + this field with the 'CTF_FP_BITS' macro. + + The purpose of the floating-point offset and bit-width is somewhat +opaque, since there are no such things as floating-point bitfields in C: +the bit-width should be filled out with the full width of the type in +bits, and the offset should always be zero. It is likely that these +fields will go away in the future. As with integers, you can use +'CTF_FP_DATA' to assemble one of these vlen items from its component +parts. + + The "encoding" for floats is not a bitfield but a simple value +indicating the display representation. Many of these are unused, relate +to Solaris-specific compiler extensions, and will be recycled in future: +some are unused and will become used in future. + +Offset Name Description +---------------------------------------------------------------------------------------------- +1 'CTF_FP_SINGLE' This is a single-precision IEEE 754 'float'. +2 'CTF_FP_DOUBLE' This is a double-precision IEEE 754 'double'. +3 'CTF_FP_CPLX' This is a 'Complex float'. +4 'CTF_FP_DCPLX' This is a 'Complex double'. +5 'CTF_FP_LDCPLX' This is a 'Complex long double'. +6 'CTF_FP_LDOUBLE' This is a 'long double'. +7 'CTF_FP_INTRVL' This is a 'float' interval type, a Solaris-specific extension. + Unused: will be recycled. +8 'CTF_FP_DINTRVL' This is a 'double' interval type, a Solaris-specific + extension. Unused: will be recycled. +9 'CTF_FP_LDINTRVL' This is a 'long double' interval type, a Solaris-specific + extension. Unused: will be recycled. +10 'CTF_FP_IMAGRY' This is a the imaginary part of a 'Complex float'. Not + currently generated. May change. +11 'CTF_FP_DIMAGRY' This is a the imaginary part of a 'Complex double'. Not + currently generated. May change. +12 'CTF_FP_LDIMAGRY' This is a the imaginary part of a 'Complex long double'. Not + currently generated. May change. + + The use of the complex floating-point encodings is obscure: it is +possible that 'CTF_FP_CPLX' is meant to be used for only the real part +of complex types, and 'CTF_FP_IMAGRY' et al for the imaginary part - but +for now, we are emitting 'CTF_FP_CPLX' to cover the entire type, with no +way to get at its constituent parts. There appear to be no uses of +these encodings anywhere, so they are quite likely to change +incompatibly in future. + + +File: ctf-spec.info, Node: Slices, Next: Pointers typedefs and cvr-quals, Prev: Floating-point types, Up: The type section + +2.3.6 Slices +------------ + +Slices, with kind 'CTF_K_SLICE', are an unusual CTF construct: they do +not directly correspond to any C type, but are a way to model other +types in a more convenient fashion for CTF generators. + + A slice is like a pointer or other reference type in that they are +always represented by 'ctf_stype_t': but unlike pointers and other +reference types, they populate the 'ctt_size' field just like integral +types do, and come with an attached encoding and transform the encoding +of the underlying type. The underlying type is described in the +variable-length data, similarly to structure and union fields: see +below. Requests for the type size should also chase down to the +referenced type. + + Slices are always nameless: 'ctt_name' is always zero for them. + + (The 'libctf' API behaviour is unusual as well, and justifies the +existence of slices: 'ctf_type_kind' never returns 'CTF_K_SLICE' but +always the underlying type kind, so that consumers never need to know +about slices: they can tell if an apparent integer is actually a slice +if they need to by calling 'ctf_type_reference', which will uniquely +return the underlying integral type rather than erroring out with +'ECTF_NOTREF' if this is actually a slice. So slices act just like an +integer with an encoding, but more closely mirror DWARF and other +debugging information formats by allowing CTF file creators to represent +a bitfield as a slice of an underlying integral type.) + + The vlen in the info word for a slice should be ignored and is always +zero. The variable-length data for a slice is a single 'ctf_slice_t': + +typedef struct ctf_slice +{ + uint32_t cts_type; + unsigned short cts_offset; + unsigned short cts_bits; +} ctf_slice_t; + +Offset Name Description +---------------------------------------------------------------------------------------- +0x0 'uint32_t cts_type' The type this slice is a slice of. Must be an + integral type (or a floating-point type, but + this nonsensical option will go away in v4.) + +0x4 'unsigned short cts_offset' The offset of this integral type in bits from + the start of its enclosing structure field, + adjusted for endianness: + *note Structs and unions::. Identical + semantics to the 'CTF_INT_OFFSET' field: + *note Integer types::. This field is much too + long, because the maximum possible offset of + an integral type would easily fit in a char: + this field is bigger just for the sake of + alignment. This will change in v4. + +0x6 'unsigned short cts_bits' The bit-width of this integral type. + Identical semantics to the 'CTF_INT_BITS' + field: *note Integer types::. As above, this + field is really too large and will shrink in + v4. + + +File: ctf-spec.info, Node: Pointers typedefs and cvr-quals, Next: Arrays, Prev: Slices, Up: The type section + +2.3.7 Pointers, typedefs, and cvr-quals +--------------------------------------- + +Pointers, 'typedef's, and 'const', 'volatile' and 'restrict' qualifiers +are represented identically except for their type kind (though they may +be treated differently by consuming libraries like 'libctf', since +pointers affect assignment-compatibility in ways cvr-quals do not, and +they may have different alignment requirements, etc). + + All of these are represented by 'ctf_stype_t', have no variable data +at all, and populate 'ctt_type' with the type ID of the type they point +to. These types can stack: a 'CTF_K_RESTRICT' can point to a +'CTF_K_CONST' which can point to a 'CTF_K_POINTER' etc. + + They are all unnamed: 'ctt_name' is 0. + + The size of 'CTF_K_POINTER' is derived from the data model (*note +Data models::), i.e. in practice, from the target machine ABI, and is +not explicitly represented. The size of other kinds in this set should +be determined by chasing ctf_types as necessary until a +non-typedef/const/volatile/restrict is found, and using that. + + +File: ctf-spec.info, Node: Arrays, Next: Function pointers, Prev: Pointers typedefs and cvr-quals, Up: The type section + +2.3.8 Arrays +------------ + +Arrays are encoded as types of kind 'CTF_K_ARRAY' in a 'ctf_stype_t'. +Both size and kind for arrays are zero. The variable-length data is a +'ctf_array_t': 'vlen' in the info word should be disregarded and is +always zero. + +typedef struct ctf_array +{ + uint32_t cta_contents; + uint32_t cta_index; + uint32_t cta_nelems; +} ctf_array_t; + +Offset Name Description +---------------------------------------------------------------------------------------- +0x0 'uint32_t cta_contents' The type of the array elements: a type ID. + +0x4 'uint32_t cta_index' The type of the array index: a type ID of an + integral type. If this is a variable-length + array, the index type ID will be 0 (but the + actual index type of this array is probably + 'int'). Probably redundant and may be + dropped in v4. + +0x8 'uint32_t cta_nelems' The number of array elements. 0 for VLAs, + and also for the historical variety of VLA + which has explicit zero dimensions (which + will have a nonzero 'cta_index'.) + + The size of an array can be computed by simple multiplication of the +size of the 'cta_contents' type by the 'cta_nelems'. + + +File: ctf-spec.info, Node: Function pointers, Next: Enums, Prev: Arrays, Up: The type section + +2.3.9 Function pointers +----------------------- + +Function pointers are explicitly represented in the CTF type section by +a type of kind 'CTF_K_FUNCTION', always encoded with a 'ctf_stype_t'. +The 'ctt_type' is the function return type ID. The 'vlen' in the info +word is the number of arguments, each of which is a type ID, a +'uint32_t': if the last argument is 0, this is a varargs function and +the number of arguments is one less than indicated by the vlen. + + If the number of arguments is odd, a single 'uint32_t' of padding is +inserted to maintain alignment. + + +File: ctf-spec.info, Node: Enums, Next: Structs and unions, Prev: Function pointers, Up: The type section + +2.3.10 Enums +------------ + +Enumerated types are represented as types of kind 'CTF_K_ENUM' in a +'ctf_stype_t'. The 'ctt_size' is always the size of an int from the +data model (enum bitfields are implemented via slices). The 'vlen' is a +count of enumerations, each of which is represented by a 'ctf_enum_t' in +the vlen: + +typedef struct ctf_enum +{ + uint32_t cte_name; + int32_t cte_value; +} ctf_enum_t; + +Offset Name Description +------------------------------------------------------------------------ +0x0 'uint32_t cte_name' Strtab offset of the enumeration name. + Must not be 0. + +0x4 'int32_t cte_value' The enumeration value. + + + Enumeration values larger than 2^32 are not yet supported and are +omitted from the enumeration. (v4 will lift this restriction by +encoding the value differently.) + + Forward declarations of enums are not implemented with this kind: +*note Forward declarations::. + + Enumerated type names, as usual in C, go into their own namespace, +and do not conflict with non-enums, structs, or unions with the same +name. + + +File: ctf-spec.info, Node: Structs and unions, Next: Forward declarations, Prev: Enums, Up: The type section + +2.3.11 Structs and unions +------------------------- + +Structures and unions are represnted as types of kind 'CTF_K_STRUCT' and +'CTF_K_UNION': their representation is otherwise identical, and it is +perfectly allowed for "structs" to contain overlapping fields etc, so we +will treat them together for the rest of this section. + + They fill out 'ctt_size', and use 'ctf_type_t' in preference to +'ctf_stype_t' if the structure size is greater than 'CTF_MAX_SIZE' +(0xfffffffe). + + The vlen for structures and unions is a count of structure fields, +but the type used to represent a structure field (and thus the size of +the variable-length array element representing the type) depends on the +size of the structure: truly huge structures, greater than +'CTF_LSTRUCT_THRESH' bytes in length, use a different type. +('CTF_LSTRUCT_THRESH' is 536870912, so such structures are vanishingly +rare: in v4, this representation will change somewhat for greater +compactness. It's inherited from v1, where the limits were much lower.) + + Most structures can get away with using 'ctf_member_t': + +typedef struct ctf_member_v2 +{ + uint32_t ctm_name; + uint32_t ctm_offset; + uint32_t ctm_type; +} ctf_member_t; + + Huge structures that are represented by 'ctf_type_t' rather than +'ctf_stype_t' have to use 'ctf_lmember_t', which splits the offset as +'ctf_type_t' splits the size: + +typedef struct ctf_lmember_v2 +{ + uint32_t ctlm_name; + uint32_t ctlm_offsethi; + uint32_t ctlm_type; + uint32_t ctlm_offsetlo; +} ctf_lmember_t; + + Here's what the fields of 'ctf_member' mean: + +Offset Name Description +--------------------------------------------------------------------------------------------------------- +0x00 'uint32_t ctm_name' Strtab offset of the field name. + +0x04 'uint32_t ctm_offset' The offset of this field _in bits_. (Usually, for bitfields, this is + machine-word-aligned and the individual field has an offset in bits, + but the format allows for the offset to be encoded in bits here.) + +0x08 'uint32_t ctm_type' The type ID of the type of the field. + + Here's what the fields of the very similar 'ctf_lmember' mean: + +Offset Name Description +------------------------------------------------------------------------------------------------------------ +0x00 'uint32_t ctlm_name' Strtab offset of the field name. + +0x04 'uint32_t ctlm_offsethi' The high 32 bits of the offset of this field in bits. + +0x08 'uint32_t ctlm_type' The type ID of the type of the field. + +0x0c 'uint32_t ctlm_offsetlo' The low 32 bits of the offset of this field in bits. + + Macros 'CTF_LMEM_OFFSET', 'CTF_OFFSET_TO_LMEMHI' and +'CTF_OFFSET_TO_LMEMLO' serve to extract and install the values of the +'ctlm_offset' fields, much as with the split size fields in +'ctf_type_t'. + + Unnamed structure and union fields are simply implemented by +collapsing the unnamed field's members into the containing structure or +union: this does mean that a structure containing an unnamed union can +end up being a "structure" with multiple members at the same offset. (A +future format revision may collapse 'CTF_K_STRUCT' and 'CTF_K_UNION' +into the same kind and decide among them based on whether their members +do in fact overlap.) + + Structure and union type names, as usual in C, go into their own +namespace, just as enum type names do. + + Forward declarations of structures and unions are not implemented +with this kind: *note Forward declarations::. + + +File: ctf-spec.info, Node: Forward declarations, Prev: Structs and unions, Up: The type section + +2.3.12 Forward declarations +--------------------------- + +When the compiler encounters a forward declaration of a struct, union, +or enum, it emits a type of kind 'CTF_K_FORWARD'. If it later +encounters a non- forward declaration of the same thing, it marks the +forward as non-root-visible: before link time, therefore, +non-root-visible forwards indicate that a non-forward is coming. + + After link time, forwards are fused with their corresponding +non-forwards by the deduplicator where possible. They are kept if there +is no non-forward definition (maybe it's not visible from any TU at all) +or if 'multiple' conflicting structures with the same name might match +it. Otherwise, all other forwards are converted to structures, unions, +or enums as appropriate, even across TUs if only one structure could +correspond to the forward (after all, all types across all TUs land in +the same dictionary unless they conflict, so promoting forwards to their +concrete type seems most helpful). + + A forward has a rather strange representation: it is encoded with a +'ctf_stype_t' but the 'ctt_type' is populated not with a type (if it's a +forward, we don't have an underlying type yet: if we did, we'd have +promoted it and this wouldn't be a forward any more) but with the 'kind' +of the forward. This means that we can distinguish forwards to structs, +enums and unions reliably and ensure they land in the appropriate +namespace even before the actual struct, union or enum is found. + + +File: ctf-spec.info, Node: The symtypetab sections, Next: The variable section, Prev: The type section, Up: CTF dictionaries + +2.4 The symtypetab sections +=========================== + +These are two very simple sections with identical formats, used by +consumers to map from ELF function and data symbols directly to their +types. So they are usually populated only in CTF sections that are +embedded in ELF objects. + + Their format is very simple: an array of type IDs. Which symbol each +type ID corresponds to depends on whether the optional _index section_ +associated with this symtypetab section has any content. + + If the index section is nonempty, it is an array of 'uint32_t' string +table offsets, each giving the name of the symbol whose type is at the +same offset in the corresponding non-index section: users can look up +symbols in such a table by name. The index section and corresponding +symtypetab section is usually ASCIIbetically sorted (indicated by the +'CTF_F_IDXSORTED' flag in the header): if it's sorted, it can be +bsearched for a symbol name rather than having to use a slower linear +search. + + If the data object index section is empty, the entries in the data +object and function info sections are associated 1:1 with ELF symbols of +type 'STT_OBJECT' (for data object) or 'STT_FUNC' (for function info) +with a nonzero value: the linker shuffles the symtypetab sections to +correspond with the order of the symbols in the ELF file. Symbols with +no name, undefined symbols and symbols named "'_START_'" and "'_END_'" +are skipped and never appear in either section. Symbols that have no +corresponding type are represented by type ID 0. The section may have +fewer entries than the symbol table, in which case no later entries have +associated types. This format is more compact than an indexed form if +most entries have types (since there is no need to record any symbol +names), but if the producer and consumer disagree even slightly about +which symbols are omitted, the types of all further symbols will be +wrong! + + The compiler always emits indexed symtypetab tables, because there is +no symbol table yet. The linker will always have to read them all in +and always works through them from start to end, so there is no benefit +having the compiler sort them either. The linker (actually, 'libctf''s +linking machinery) will automatically sort unsorted indexed sections, +and convert indexed sections that contain a lot of pads into the more +compact, unindexed form. + + If child dicts are in use, only symbols that use types actually +mentioned in the child appear in the child's symtypetab: symbols that +use only types in the parent appear in the parent's symtypetab instead. +So the child's symtypetab will almost always be very sparse, and thus +will usually use the indexed form even in fully linked objects. (It is, +of course, impossible for symbols to exist that use types from multiple +child dicts at once, since it's impossible to declare a function in C +that uses types that are only visible in two different, disjoint +translation units.) + + +File: ctf-spec.info, Node: The variable section, Next: The label section, Prev: The symtypetab sections, Up: CTF dictionaries + +2.5 The variable section +======================== + +The variable section is a simple array mapping names (strtab entries) to +type IDs, intended to provide a replacement for the data object section +in dynamic situations in which there is no static ELF strtab but the +consumer instead hands back names. The section is sorted into +ASCIIbetical order by name for rapid lookup, like the CTF archive name +table. + + The section is an array of these structures: + +typedef struct ctf_varent +{ + uint32_t ctv_name; + uint32_t ctv_type; +} ctf_varent_t; + +Offset Name Description +----------------------------------------------------------- +0x00 'uint32_t ctv_name' Strtab offset of the name + +0x04 'uint32_t ctv_type' Type ID of this type + + There is no analogue of the function info section yet: v4 will +probably drop this section in favour of a way to put both indexed (thus, +named) and nonindexed symbols into the symtypetab sections at the same +time. + + +File: ctf-spec.info, Node: The label section, Next: The string section, Prev: The variable section, Up: CTF dictionaries + +2.6 The label section +===================== + +The label section is a currently-unused facility allowing the tiling of +the type space with names taken from the strtab. The section is an +array of these structures: + +typedef struct ctf_lblent +{ + uint32_t ctl_label; + uint32_t ctl_type; +} ctf_lblent_t; + +Offset Name Description +------------------------------------------------------------- +0x00 'uint32_t ctl_label' Strtab offset of the label + +0x04 'uint32_t ctl_type' Type ID of the last type + covered by this label + + Semantics will be attached to labels soon, probably in v4 (the plan +is to use them to allow multiple disjoint namespaces in a single CTF +file, removing many uses of CTF archives, in particular in the '.ctf' +section in ELF objects). + + +File: ctf-spec.info, Node: The string section, Next: Data models, Prev: The label section, Up: CTF dictionaries + +2.7 The string section +====================== + +This section is a simple ELF-format strtab, starting with a zero byte +(thus ensuring that the string with offset 0 is the null string, as +assumed elsewhere in this spec). The strtab is usually ASCIIbetically +sorted to somewhat improve compression efficiency. + + Where the strtab is unusual is the _references_ to it. CTF has two +string tables, the internal strtab and an external strtab associated +with the CTF dictionary at open time: usually, this is the ELF dynamic +strtab ('.dynstr') of a CTF dictionary embedded in an ELF file. We +distinguish between these strtabs by the most significant bit, bit 31, +of the 32-bit strtab references: if it is 0, the offset is in the +internal strtab: if 1, the offset is in the external strtab. + + There is a bug workaround in this area: in format v3 (the first +version to have working support for external strtabs), the external +strtab is '.strtab' unless the 'CTF_F_DYNSTR' flag is set on the +dictionary (*note CTF file-wide flags::). Format v4 will introduce a +header field that explicitly names the external strtab, making this flag +unnecessary. + + +File: ctf-spec.info, Node: Data models, Next: Limits of CTF, Prev: The string section, Up: CTF dictionaries + +2.8 Data models +=============== + +The data model is a simple integer which indicates the ABI in use on +this platform. Right now, it is very simple, distinguishing only +between 32- and 64-bit types: a model of 1 indicates ILP32, 2 indicats +LP64. The mapping from ABI integer to type sizes is hardwired into +'libctf': currently, we use this to hardwire the size of pointers, +function pointers, and enumerated types, + + This is a very kludgy corner of CTF and will probably be replaced +with explicit header fields to record this sort of thing in future. + + +File: ctf-spec.info, Node: Limits of CTF, Prev: Data models, Up: CTF dictionaries + +2.9 Limits of CTF +================= + +The following limits are imposed by various aspects of CTF version 3: + +'CTF_MAX_TYPE' + Maximum type identifier (maximum number of types accessible with + parent and child containers in use): 0xfffffffe +'CTF_MAX_PTYPE' + Maximum type identifier in a parent dictioanry: maximum number of + types in any one dictionary: 0x7fffffff +'CTF_MAX_NAME' + Maximum offset into a string table: 0x7fffffff +'CTF_MAX_VLEN' + Maximum number of members in a struct, union, or enum: maximum + number of function args: 0xffffff +'CTF_MAX_SIZE' + Maximum size of a 'ctf_stype_t' in bytes before we fall back to + 'ctf_type_t': 0xfffffffe bytes + + Other maxima without associated macros: + * Maximum value of an enumerated type: 2^32 + * Maximum size of an array element: 2^32 + + These maxima are generally considered to be too low, because C +programs can and do exceed them: they will be lifted in format v4. + + +File: ctf-spec.info, Node: Index, Prev: CTF dictionaries, Up: Top + +Index +***** + +[index] +* Menu: + +* alignment: CTF Preamble. (line 33) +* archive, CTF archive: CTF archive. (line 6) +* Arrays: Arrays. (line 6) +* bool: Integer types. (line 6) +* Bug workarounds, CTF_F_DYNSTR: The symtypetab sections. + (line 6) +* Bug workarounds, CTF_F_DYNSTR <1>: The string section. (line 19) +* char: Integer types. (line 6) +* Child range: Type indexes and type IDs. + (line 6) +* Complex, double: Floating-point types. (line 6) +* Complex, float: Floating-point types. (line 6) +* Complex, signed double: Floating-point types. (line 6) +* Complex, signed float: Floating-point types. (line 6) +* Complex, unsigned double: Floating-point types. (line 6) +* Complex, unsigned float: Floating-point types. (line 6) +* const: Pointers typedefs and cvr-quals. + (line 6) +* cta_contents: Arrays. (line 20) +* cta_index: Arrays. (line 22) +* cta_nelems: Arrays. (line 29) +* cte_name: Enums. (line 21) +* cte_value: Enums. (line 24) +* CTF header: CTF header. (line 6) +* CTF versions, versions: CTF Preamble. (line 46) +* ctfa_ctfs: CTF archive. (line 76) +* ctfa_magic: CTF archive. (line 63) +* CTFA_MAGIC: CTF archive. (line 64) +* ctfa_model: CTF archive. (line 66) +* ctfa_names: CTF archive. (line 72) +* ctfa_nfiles: CTF archive. (line 71) +* ctf_archive_modent_t: CTF archive. (line 83) +* ctf_archive_modent_t, ctf_offset: CTF archive. (line 88) +* ctf_archive_modent_t, name_offset: CTF archive. (line 86) +* ctf_array_t: Arrays. (line 18) +* ctf_array_t, cta_contents: Arrays. (line 20) +* ctf_array_t, cta_index: Arrays. (line 22) +* ctf_array_t, cta_nelems: Arrays. (line 29) +* CTF_CHAR: Integer types. (line 53) +* ctf_enum_t: Enums. (line 18) +* ctf_enum_t, cte_name: Enums. (line 21) +* ctf_enum_t, cte_value: Enums. (line 24) +* CTF_FP_BITS: Floating-point types. (line 28) +* CTF_FP_CPLX: Floating-point types. (line 47) +* CTF_FP_DCPLX: Floating-point types. (line 48) +* CTF_FP_DIMAGRY: Floating-point types. (line 60) +* CTF_FP_DINTRVL: Floating-point types. (line 54) +* CTF_FP_DOUBLE: Floating-point types. (line 46) +* CTF_FP_ENCODING: Floating-point types. (line 21) +* CTF_FP_IMAGRY: Floating-point types. (line 58) +* CTF_FP_INTRVL: Floating-point types. (line 52) +* CTF_FP_LDCPLX: Floating-point types. (line 49) +* CTF_FP_LDIMAGRY: Floating-point types. (line 62) +* CTF_FP_LDINTRVL: Floating-point types. (line 56) +* CTF_FP_LDOUBLE: Floating-point types. (line 50) +* CTF_FP_OFFSET: Floating-point types. (line 25) +* CTF_FP_SINGLE: Floating-point types. (line 45) +* CTF_F_COMPRESS: CTF file-wide flags. (line 17) +* CTF_F_DYNSTR: CTF file-wide flags. (line 21) +* CTF_F_DYNSTR <1>: The symtypetab sections. + (line 6) +* CTF_F_DYNSTR <2>: The string section. (line 19) +* CTF_F_IDXSORTED: CTF file-wide flags. (line 20) +* CTF_F_IDXSORTED <1>: The symtypetab sections. + (line 6) +* CTF_F_NEWFUNCINFO: CTF file-wide flags. (line 19) +* ctf_header_t: CTF header. (line 44) +* ctf_header_t, cth_cuname: CTF header. (line 61) +* ctf_header_t, cth_flags: CTF Preamble. (line 30) +* ctf_header_t, cth_funcidxoff: CTF header. (line 82) +* ctf_header_t, cth_funcoff: CTF header. (line 74) +* ctf_header_t, cth_lbloff: CTF header. (line 66) +* ctf_header_t, cth_magic: CTF Preamble. (line 24) +* ctf_header_t, cth_objtidxoff: CTF header. (line 78) +* ctf_header_t, cth_objtoff: CTF header. (line 70) +* ctf_header_t, cth_parlabel: CTF header. (line 49) +* ctf_header_t, cth_parname: CTF header. (line 55) +* ctf_header_t, cth_preamble: CTF header. (line 47) +* ctf_header_t, cth_strlen: CTF header. (line 98) +* ctf_header_t, cth_stroff: CTF header. (line 95) +* ctf_header_t, cth_typeoff: CTF header. (line 91) +* ctf_header_t, cth_varoff: CTF header. (line 87) +* ctf_header_t, cth_version: CTF Preamble. (line 28) +* ctf_id_t: Type indexes and type IDs. + (line 6) +* CTF_INT_BITS: Integer types. (line 28) +* CTF_INT_BOOL: Integer types. (line 57) +* CTF_INT_CHAR: Integer types. (line 53) +* CTF_INT_DATA: Integer types. (line 34) +* CTF_INT_DATA <1>: Floating-point types. (line 36) +* CTF_INT_ENCODING: Integer types. (line 20) +* CTF_INT_OFFSET: Integer types. (line 25) +* CTF_INT_SIGNED: Integer types. (line 49) +* CTF_K_CONST: Pointers typedefs and cvr-quals. + (line 6) +* CTF_K_ENUM: Enums. (line 6) +* CTF_K_FLOAT: Floating-point types. (line 6) +* CTF_K_FORWARD: Forward declarations. (line 6) +* CTF_K_INTEGER: Integer types. (line 6) +* CTF_K_POINTER: Pointers typedefs and cvr-quals. + (line 6) +* CTF_K_RESTRICT: Pointers typedefs and cvr-quals. + (line 6) +* CTF_K_SLICE: Slices. (line 6) +* CTF_K_STRUCT: Structs and unions. (line 6) +* CTF_K_TYPEDEF: Pointers typedefs and cvr-quals. + (line 6) +* CTF_K_UNION: Structs and unions. (line 6) +* CTF_K_UNKNOWN: Type kinds. (line 31) +* CTF_K_VOLATILE: Pointers typedefs and cvr-quals. + (line 6) +* ctf_lblent_t: The label section. (line 16) +* ctf_lblent_t, ctl_label: The label section. (line 19) +* ctf_lblent_t, ctl_type: The label section. (line 20) +* ctf_lmember_t: Structs and unions. (line 59) +* ctf_lmember_t, ctlm_name: Structs and unions. (line 61) +* ctf_lmember_t, ctlm_offsethi: Structs and unions. (line 64) +* ctf_lmember_t, ctlm_offsetlo: Structs and unions. (line 68) +* CTF_LSIZE_SENT: The type section. (line 49) +* CTF_LSTRUCT_THRESH: Structs and unions. (line 23) +* CTF_MAGIC: CTF Preamble. (line 25) +* CTF_MAX_LSIZE: Structs and unions. (line 13) +* ctf_member_t: Structs and unions. (line 47) +* ctf_member_t, ctlm_type: Structs and unions. (line 65) +* ctf_member_t, ctm_name: Structs and unions. (line 49) +* ctf_member_t, ctm_offset: Structs and unions. (line 52) +* ctf_member_t, ctm_type: Structs and unions. (line 55) +* ctf_offset: CTF archive. (line 88) +* ctf_preamble_t: CTF Preamble. (line 22) +* ctf_preamble_t, ctp_flags: CTF Preamble. (line 30) +* ctf_preamble_t, ctp_magic: CTF Preamble. (line 24) +* ctf_preamble_t, ctp_version: CTF Preamble. (line 28) +* CTF_SIZE_TO_LSIZE_HI: The type section. (line 79) +* CTF_SIZE_TO_LSIZE_LO: The type section. (line 83) +* ctf_slice_t: Slices. (line 42) +* ctf_slice_t, cts_bits: Slices. (line 59) +* ctf_slice_t, cts_offset: Slices. (line 49) +* ctf_slice_t, cts_type: Slices. (line 44) +* ctf_stype_t: The type section. (line 53) +* ctf_stype_t, ctt_info: The type section. (line 57) +* ctf_stype_t, ctt_size: The type section. (line 62) +* ctf_stype_t, ctt_type: The type section. (line 67) +* CTF_TYPE_INFO: The info word. (line 45) +* CTF_TYPE_LSIZE: The type section. (line 79) +* ctf_type_t: The type section. (line 53) +* ctf_type_t, ctt_info: The type section. (line 57) +* ctf_type_t, ctt_lsizehi: The type section. (line 76) +* ctf_type_t, ctt_lsizelo: The type section. (line 82) +* ctf_type_t, ctt_size: The type section. (line 62) +* CTF_V2_INDEX_TO_TYPE: Type indexes and type IDs. + (line 58) +* CTF_V2_INFO_ISROOT: The info word. (line 45) +* CTF_V2_INFO_KIND: The info word. (line 45) +* CTF_V2_INFO_VLEN: The info word. (line 45) +* CTF_V2_TYPE_ISCHILD: Type indexes and type IDs. + (line 58) +* CTF_V2_TYPE_ISPARENT: Type indexes and type IDs. + (line 58) +* CTF_V2_TYPE_TO_INDEX: Type indexes and type IDs. + (line 58) +* ctf_varent_t: The variable section. (line 21) +* ctf_varent_t, ctv_name: The variable section. (line 24) +* ctf_varent_t, ctv_type: The variable section. (line 26) +* CTF_VERSION_3: CTF Preamble. (line 46) +* cth_cuname: CTF header. (line 61) +* cth_flags: CTF Preamble. (line 30) +* cth_funcidxoff: CTF header. (line 82) +* cth_funcoff: CTF header. (line 74) +* cth_lbloff: CTF header. (line 66) +* cth_magic: CTF Preamble. (line 24) +* cth_objtidxoff: CTF header. (line 78) +* cth_objtoff: CTF header. (line 70) +* cth_parlabel: CTF header. (line 49) +* cth_parname: CTF header. (line 55) +* cth_preamble: CTF header. (line 47) +* cth_strlen: CTF header. (line 98) +* cth_stroff: CTF header. (line 95) +* cth_typeoff: CTF header. (line 91) +* cth_varoff: CTF header. (line 87) +* cth_version: CTF Preamble. (line 28) +* ctlm_name: Structs and unions. (line 61) +* ctlm_offsethi: Structs and unions. (line 64) +* ctlm_offsetlo: Structs and unions. (line 68) +* ctl_label: The label section. (line 19) +* ctl_type: The label section. (line 20) +* ctm_name: Structs and unions. (line 49) +* ctm_offset: Structs and unions. (line 52) +* ctm_type: Structs and unions. (line 55) +* ctm_type <1>: Structs and unions. (line 65) +* ctp_flags: CTF Preamble. (line 30) +* ctp_flags <1>: CTF Preamble. (line 58) +* ctp_magic: CTF Preamble. (line 24) +* ctp_version: CTF Preamble. (line 28) +* cts_bits: Slices. (line 59) +* cts_offset: Slices. (line 49) +* cts_type: Slices. (line 44) +* ctt_info: The type section. (line 57) +* ctt_lsizehi: The type section. (line 76) +* ctt_lsizelo: The type section. (line 82) +* ctt_name: The type section. (line 55) +* ctt_size: The type section. (line 62) +* ctt_type: The type section. (line 67) +* ctv_name: The variable section. (line 24) +* ctv_type: The variable section. (line 26) +* cvr-quals: Pointers typedefs and cvr-quals. + (line 6) +* Data models: Data models. (line 6) +* Data object index section: The symtypetab sections. + (line 6) +* Data object section: The symtypetab sections. + (line 6) +* dictionary, CTF dictionary: CTF dictionaries. (line 6) +* double: Floating-point types. (line 6) +* endianness: CTF Preamble. (line 37) +* enum: Enums. (line 6) +* enum <1>: Forward declarations. (line 6) +* Enums: Enums. (line 6) +* float: Floating-point types. (line 6) +* Floating-point types: Floating-point types. (line 6) +* Forwards: Forward declarations. (line 6) +* Function info index section: The symtypetab sections. + (line 6) +* Function info section: The symtypetab sections. + (line 6) +* Function pointers: Function pointers. (line 6) +* int: Integer types. (line 6) +* Integer types: Integer types. (line 6) +* Label section: The label section. (line 6) +* libctf, effect of slices: Slices. (line 30) +* Limits: Limits of CTF. (line 6) +* long: Integer types. (line 6) +* long long: Integer types. (line 6) +* name_offset: CTF archive. (line 86) +* Overview: Overview. (line 6) +* Parent range: Type indexes and type IDs. + (line 6) +* Pointers: Pointers typedefs and cvr-quals. + (line 6) +* Pointers, to functions: Function pointers. (line 6) +* restrict: Pointers typedefs and cvr-quals. + (line 6) +* Sections, data object: The symtypetab sections. + (line 6) +* Sections, data object index: The symtypetab sections. + (line 6) +* Sections, function info: The symtypetab sections. + (line 6) +* Sections, function info index: The symtypetab sections. + (line 6) +* Sections, header: CTF header. (line 6) +* Sections, label: The label section. (line 6) +* Sections, string: The string section. (line 6) +* Sections, symtypetab: The symtypetab sections. + (line 6) +* Sections, type: The type section. (line 6) +* Sections, variable: The variable section. (line 6) +* short: Integer types. (line 6) +* signed char: Integer types. (line 6) +* signed double: Floating-point types. (line 6) +* signed float: Floating-point types. (line 6) +* signed int: Integer types. (line 6) +* signed long: Integer types. (line 6) +* signed long long: Integer types. (line 6) +* signed short: Integer types. (line 6) +* Slices: Slices. (line 6) +* Slices, effect on ctf_type_kind: Slices. (line 30) +* Slices, effect on ctf_type_reference: Slices. (line 30) +* String section: The string section. (line 6) +* struct: Structs and unions. (line 6) +* struct <1>: Forward declarations. (line 6) +* struct ctf_archive: CTF archive. (line 61) +* struct ctf_archive, ctfa_ctfs: CTF archive. (line 76) +* struct ctf_archive, ctfa_magic: CTF archive. (line 63) +* struct ctf_archive, ctfa_model: CTF archive. (line 66) +* struct ctf_archive, ctfa_names: CTF archive. (line 72) +* struct ctf_archive, ctfa_nfiles: CTF archive. (line 71) +* struct ctf_archive_modent: CTF archive. (line 83) +* struct ctf_archive_modent, ctf_offset: CTF archive. (line 88) +* struct ctf_archive_modent, name_offset: CTF archive. (line 86) +* struct ctf_array: Arrays. (line 18) +* struct ctf_array, cta_contents: Arrays. (line 20) +* struct ctf_array, cta_index: Arrays. (line 22) +* struct ctf_array, cta_nelems: Arrays. (line 29) +* struct ctf_enum: Enums. (line 18) +* struct ctf_enum, cte_name: Enums. (line 21) +* struct ctf_enum, cte_value: Enums. (line 24) +* struct ctf_header: CTF header. (line 44) +* struct ctf_header, cth_cuname: CTF header. (line 61) +* struct ctf_header, cth_flags: CTF Preamble. (line 30) +* struct ctf_header, cth_funcidxoff: CTF header. (line 82) +* struct ctf_header, cth_funcoff: CTF header. (line 74) +* struct ctf_header, cth_lbloff: CTF header. (line 66) +* struct ctf_header, cth_magic: CTF Preamble. (line 24) +* struct ctf_header, cth_objtidxoff: CTF header. (line 78) +* struct ctf_header, cth_objtoff: CTF header. (line 70) +* struct ctf_header, cth_parlabel: CTF header. (line 49) +* struct ctf_header, cth_parname: CTF header. (line 55) +* struct ctf_header, cth_preamble: CTF header. (line 47) +* struct ctf_header, cth_strlen: CTF header. (line 98) +* struct ctf_header, cth_stroff: CTF header. (line 95) +* struct ctf_header, cth_typeoff: CTF header. (line 91) +* struct ctf_header, cth_varoff: CTF header. (line 87) +* struct ctf_header, cth_version: CTF Preamble. (line 28) +* struct ctf_lblent: The label section. (line 16) +* struct ctf_lblent, ctl_label: The label section. (line 19) +* struct ctf_lblent, ctl_type: The label section. (line 20) +* struct ctf_lmember_v2: Structs and unions. (line 59) +* struct ctf_lmember_v2, ctlm_name: Structs and unions. (line 61) +* struct ctf_lmember_v2, ctlm_offsethi: Structs and unions. (line 64) +* struct ctf_lmember_v2, ctlm_offsetlo: Structs and unions. (line 68) +* struct ctf_lmember_v2, ctlm_type: Structs and unions. (line 65) +* struct ctf_member_v2: Structs and unions. (line 47) +* struct ctf_member_v2, ctm_name: Structs and unions. (line 49) +* struct ctf_member_v2, ctm_offset: Structs and unions. (line 52) +* struct ctf_member_v2, ctm_type: Structs and unions. (line 55) +* struct ctf_preamble: CTF Preamble. (line 22) +* struct ctf_preamble, ctp_flags: CTF Preamble. (line 30) +* struct ctf_preamble, ctp_magic: CTF Preamble. (line 24) +* struct ctf_preamble, ctp_version: CTF Preamble. (line 28) +* struct ctf_slice: Slices. (line 42) +* struct ctf_slice, cts_bits: Slices. (line 59) +* struct ctf_slice, cts_offset: Slices. (line 49) +* struct ctf_slice, cts_type: Slices. (line 44) +* struct ctf_stype: The type section. (line 53) +* struct ctf_stype, ctt_info: The type section. (line 57) +* struct ctf_stype, ctt_size: The type section. (line 62) +* struct ctf_stype, ctt_type: The type section. (line 67) +* struct ctf_type: The type section. (line 53) +* struct ctf_type, ctt_info: The type section. (line 57) +* struct ctf_type, ctt_lsizehi: The type section. (line 76) +* struct ctf_type, ctt_lsizelo: The type section. (line 82) +* struct ctf_type, ctt_size: The type section. (line 62) +* struct ctf_varent: The variable section. (line 21) +* struct ctf_varent, ctv_name: The variable section. (line 24) +* struct ctf_varent, ctv_type: The variable section. (line 26) +* Structures: Structs and unions. (line 6) +* Symtypetab section: The symtypetab sections. + (line 6) +* Type IDs: Type indexes and type IDs. + (line 6) +* Type IDs, ranges: Type indexes and type IDs. + (line 6) +* Type indexes: Type indexes and type IDs. + (line 6) +* Type kinds: Type kinds. (line 6) +* Type section: The type section. (line 6) +* Type, IDs of: Type indexes and type IDs. + (line 6) +* Type, indexes of: Type indexes and type IDs. + (line 6) +* Type, kinds of: Type kinds. (line 6) +* typedef: Pointers typedefs and cvr-quals. + (line 6) +* Typedefs: Pointers typedefs and cvr-quals. + (line 6) +* Types, floating-point: Floating-point types. (line 6) +* Types, integer: Integer types. (line 6) +* Types, slices of integral: Slices. (line 6) +* union: Structs and unions. (line 6) +* union <1>: Forward declarations. (line 6) +* Unions: Structs and unions. (line 6) +* unsigned char: Integer types. (line 6) +* unsigned double: Floating-point types. (line 6) +* unsigned float: Floating-point types. (line 6) +* unsigned int: Integer types. (line 6) +* unsigned long: Integer types. (line 6) +* unsigned long long: Integer types. (line 6) +* unsigned short: Integer types. (line 6) +* Unused bits: Floating-point types. (line 52) +* Unused bits <1>: Floating-point types. (line 54) +* Unused bits <2>: Floating-point types. (line 56) +* Unused bits <3>: Floating-point types. (line 58) +* Unused bits <4>: Floating-point types. (line 60) +* Unused bits <5>: Floating-point types. (line 62) +* Variable section: The variable section. (line 6) +* volatile: Pointers typedefs and cvr-quals. + (line 6) + + + +Tag Table: +Node: Top548 +Node: Overview878 +Node: CTF archive4165 +Node: CTF dictionaries8791 +Node: CTF Preamble9208 +Node: CTF file-wide flags11818 +Node: CTF header13276 +Node: The type section19200 +Node: The info word23866 +Node: Type indexes and type IDs26396 +Node: Type kinds29764 +Node: Integer types33057 +Node: Floating-point types36605 +Node: Slices40630 +Node: Pointers typedefs and cvr-quals44134 +Node: Arrays45305 +Node: Function pointers47036 +Node: Enums47701 +Node: Structs and unions48983 +Node: Forward declarations52840 +Node: The symtypetab sections54419 +Node: The variable section57497 +Node: The label section58635 +Node: The string section59610 +Node: Data models60872 +Node: Limits of CTF61541 +Node: Index62586 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/libctf/doc/ctf-spec.texi 16.3-5ubuntu1/libctf/doc/ctf-spec.texi --- 16.3-5/libctf/doc/ctf-spec.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libctf/doc/ctf-spec.texi 2025-04-20 17:22:06.000000000 +0000 @@ -1 +1,1736 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename ctf-spec.info +@settitle The CTF File Format +@ifnottex +@xrefautomaticsectiontitle on +@end ifnottex +@synindex fn cp +@synindex tp cp +@synindex vr cp +@copying +Copyright @copyright{} 2021-2024 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License, Version 3 or any +later version published by the Free Software Foundation. A copy of the +license is included in the section entitled ``GNU General Public +License''. + +@end copying + +@dircategory Software development +@direntry +* CTF: (ctf-spec). The CTF file format. +@end direntry + +@titlepage +@title The CTF File Format +@subtitle Version 3 +@author Nick Alcock + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@contents + +@ifnottex +@node Top +@top The CTF file format + +This manual describes version 3 of the CTF file format, which is +intended to model the C type system in a fashion that C programs can +consume at runtime. +@end ifnottex + +@node Overview +@unnumbered Overview +@cindex Overview + +The CTF file format compactly describes C types and the association +between function and data symbols and types: if embedded in ELF objects, +it can exploit the ELF string table to reduce duplication further. +There is no real concept of namespacing: only top-level types are +described, not types scoped to within single functions. + +CTF dictionaries can be @dfn{children} of other dictionaries, in a +one-level hierarchy: child dictionaries can refer to types in the +parent, but the opposite is not sensible (since if you refer to a child +type in the parent, the actual type you cited would vary depending on +what child was attached). This parent/child definition is recorded in +the child, but only as a recommendation: users of the API have to attach +parents to children explicitly, and can choose to attach a child to any +parent they like, or to none, though doing so might lead to unpleasant +consequences like dangling references to types. @xref{Type indexes and +type IDs}. Type lookups in child dicts that are not associated with a +parent at all will fail with @code{ECTF_NOPARENT} if a parent type was +needed. + +The associated API to generate, merge together, and query this file +format will be described in the accompanying @code{libctf} manual once +it is written. There is no API to modify dictionaries once they've been +written out: CTF is a write-once file format. (However, it is always +possible to dynamically create a new child dictionary on the fly and +attach it to a pre-existing, read-only parent.) + +There are two major pieces to CTF: the @dfn{archive} and the +@dfn{dictionary}. Some relatives and ancestors of CTF call dictionaries +@dfn{containers}: the archive format is unique to this variant of CTF. +(Much of the source code still uses the old term.) + +The archive file format is a very simple mmappable archive used to group +multiple dictionaries together into groups: it is expected to slowly go +away and be replaced by other mechanisms, but right now it is an +important part of the file format, used to group dictionaries containing +types with conflicting definitions in different TUs with the overarching +dictionary used to store all other types. (Even when archives go away, +the @code{libctf} API used to access them will remain, and access the +other mechanisms that replace it instead.) + +The CTF dictionary consists of a @dfn{preamble}, which does not vary +between versions of the CTF file format, and a @dfn{header} and some +number of @dfn{sections}, which can vary between versions. + +The rest of this specification describes the format of these sections, +first for the latest version of CTF, then for all earlier versions +supported by @code{libctf}: the earlier versions are defined in terms of +their differences from the next later one. We describe each part of the +format first by reproducing the C structure which defines that part, +then describing it at greater length in terms of file offsets. + +The description of the file format ends with a description of relevant +limits that apply to it. These limits can vary between file format +versions. + +This document is quite young, so for now the C code in @file{ctf.h} +should be presumed correct when this document conflicts with it. + +@node CTF archive +@chapter CTF archives +@cindex archive, CTF archive + +The CTF archive format maps names to CTF dictionaries. The names may +contain any character other than \0, but for now archives containing +slashes in the names may not extract correctly. It is possible to +insert multiple members with the same name, but these are quite hard to +access reliably (you have to iterate through all the members rather than +opening by name) so this is not recommended. + +CTF archives are not themselves compressed: the constituent components, +CTF dictionaries, can be compressed. (@xref{CTF header}). + +CTF archives usually contain a collection of related dictionaries, one +parent and many children of that parent. CTF archives can have a member +with a @dfn{default name}, @code{.ctf} (which can be represented as +@code{NULL} in the API). If present, this member is usually the parent +of all the children, but it is possible for CTF producers to emit +parents with different names if they wish (usually for backward- +compatibility purposes). + +@code{.ctf} sections in ELF objects consist of a single CTF dictionary +rather than an archive of dictionaries if and only if the section +contains no types with identical names but conflicting definitions: if +two conflicting definitions exist, the deduplicator will place the type +most commonly referred to by other types in the parent and will place +the other type in a child named after the translation unit it is found +in, and will emit a CTF archive containing both dictionaries instead of +a raw dictionary. All types that refer to such conflicting types are +also placed in the per-translation-unit child. + +The definition of an archive in @file{ctf.h} is as follows: + +@verbatim +struct ctf_archive +{ + uint64_t ctfa_magic; + uint64_t ctfa_model; + uint64_t ctfa_nfiles; + uint64_t ctfa_names; + uint64_t ctfa_ctfs; +}; + +typedef struct ctf_archive_modent +{ + uint64_t name_offset; + uint64_t ctf_offset; +} ctf_archive_modent_t; +@end verbatim + +(Note one irregularity here: the @code{ctf_archive_t} is not a typedef +to @code{struct ctf_archive}, but a different typedef, private to +@code{libctf}, so that things that are not really archives can be made +to appear as if they were.) + +All the above items are always in little-endian byte order, regardless +of the machine endianness. + +The archive header has the following fields: + +@tindex struct ctf_archive +@multitable {Offset} {@code{uint64_t ctfa_nfiles}} {The data model for this archive: an arbitrary integer} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint64_t ctfa_magic} +@vindex ctfa_magic +@vindex struct ctf_archive, ctfa_magic +@tab The magic number for archives, @code{CTFA_MAGIC}: 0x8b47f2a4d7623eeb. +@tindex CTFA_MAGIC + +@item 0x08 +@tab @code{uint64_t ctfa_model} +@vindex ctfa_model +@vindex struct ctf_archive, ctfa_model +@tab The data model for this archive: an arbitrary integer that serves no +purpose but to be handed back by the libctf API. @xref{Data models}. + +@item 0x10 +@tab @code{uint64_t ctfa_nfiles} +@vindex ctfa_nfiles +@vindex struct ctf_archive, ctfa_nfiles +@tab The number of CTF dictionaries in this archive. + +@item 0x18 +@tab @code{uint64_t ctfa_names} +@vindex ctfa_names +@vindex struct ctf_archive, ctfa_names +@tab Offset of the name table, in bytes from the start of the archive. +The name table is an array of @code{struct ctf_archive_modent_t[ctfa_nfiles]}. + +@item 0x20 +@tab @code{uint64_t ctfa_ctfs} +@vindex ctfa_ctfs +@vindex struct ctf_archive, ctfa_ctfs +@tab Offset of the CTF table. Each element starts with a @code{uint64_t} size, +followed by a CTF dictionary. + +@end multitable + +The array pointed to by @code{ctfa_names} is an array of entries of +@code{ctf_archive_modent}: + +@tindex struct ctf_archive_modent +@tindex ctf_archive_modent_t +@multitable {Offset} {@code{uint64_t name_offset}} {Offset of this name, in bytes from the start} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint64_t name_offset} +@vindex name_offset +@vindex struct ctf_archive_modent, name_offset +@vindex ctf_archive_modent_t, name_offset +@tab Offset of this name, in bytes from the start of the archive. + +@item 0x08 +@tab @code{uint64_t ctf_offset} +@vindex ctf_offset +@vindex struct ctf_archive_modent, ctf_offset +@vindex ctf_archive_modent_t, ctf_offset +@tab Offset of this CTF dictionary, in bytes from the start of the archive. + +@end multitable + +The @code{ctfa_names} array is sorted into ASCIIbetical order by name +(i.e. by the result of dereferencing the @code{name_offset}). + +The archive file also contains a name table and a table of CTF +dictionaries: these are pointed to by the structures above. The name +table is a simple strtab which is not required to be sorted; the +dictionary array is described above in the entry for @code{ctfa_ctfs}. + +The relative order of these various parts is not defined, except that +the header naturally always comes first. + +@node CTF dictionaries +@chapter CTF dictionaries +@cindex dictionary, CTF dictionary + +CTF dictionaries consist of a header, starting with a premable, and a +number of sections. + +@node CTF Preamble +@section CTF Preamble + +The preamble is the only part of the CTF dictionary whose format cannot +vary between versions. It is never compressed. It is correspondingly +simple: + +@verbatim +typedef struct ctf_preamble +{ + unsigned short ctp_magic; + unsigned char ctp_version; + unsigned char ctp_flags; +} ctf_preamble_t; +@end verbatim + +@code{#define}s are provided under the names @code{cth_magic}, +@code{cth_version} and @code{cth_flags} to make the fields of the +@code{ctf_preamble_t} appear to be part of the @code{ctf_header_t}, so +consuming programs rarely need to consider the existence of the preamble +as a separate structure. + +@tindex struct ctf_preamble +@tindex ctf_preamble_t +@multitable {Offset} {@code{unsigned char ctp_version}} {The magic number for CTF dictionaries} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{unsigned short ctp_magic} +@vindex ctp_magic +@vindex cth_magic +@vindex ctf_preamble_t, ctp_magic +@vindex struct ctf_preamble, ctp_magic +@vindex ctf_header_t, cth_magic +@vindex struct ctf_header, cth_magic +@tab The magic number for CTF dictionaries, @code{CTF_MAGIC}: 0xdff2. +@tindex CTF_MAGIC + +@item 0x02 +@tab @code {unsigned char ctp_version} +@vindex ctp_version +@vindex cth_version +@vindex ctf_preamble_t, ctp_version +@vindex struct ctf_preamble, ctp_version +@vindex ctf_header_t, cth_version +@vindex struct ctf_header, cth_version +@tab The version number of this CTF dictionary. + +@item 0x03 +@tab @code{ctp_flags} +@vindex ctp_flags +@vindex cth_flags +@vindex ctf_preamble_t, ctp_flags +@vindex struct ctf_preamble, ctp_flags +@vindex ctf_header_t, cth_flags +@vindex struct ctf_header, cth_flags +@tab Flags for this CTF file. @xref{CTF file-wide flags}. +@end multitable + +@cindex alignment +Every element of a dictionary must be naturally aligned unless otherwise +specified. (This restriction will be lifted in later versions.) + +@cindex endianness +CTF dictionaries are stored in the native endianness of the system that +generates them: the consumer (e.g., @code{libctf}) can detect whether to +endian-flip a CTF dictionary by inspecting the @code{ctp_magic}. (If it +appears as 0xf2df, endian-flipping is needed.) + +The version of the CTF dictionary can be determined by inspecting +@code{ctp_version}. The following versions are currently valid, and +@code{libctf} can read all of them: + +@tindex CTF_VERSION_3 +@cindex CTF versions, versions +@multitable {@code{CTF_VERSION_1_UPGRADED_3}} {Number} {First version, rare. Very similar to Solaris CTF.} +@headitem Version @tab Number @tab Description +@item @code{CTF_VERSION_1} +@tab 1 @tab First version, rare. Very similar to Solaris CTF. + +@item @code{CTF_VERSION_1_UPGRADED_3} +@tab 2 @tab First version, upgraded to v3 or higher and written out again. +Name may change. Very rare. + +@item @code{CTF_VERSION_2} +@tab 3 @tab Second version, with many range limits lifted. + +@item @code{CTF_VERSION_3} +@tab 4 @tab Third and current version, documented here. +@end multitable + +This section documents @code{CTF_VERSION_3}. + +@vindex ctp_flags +@node CTF file-wide flags +@subsection CTF file-wide flags + +The preamble contains bitflags in its @code{ctp_flags} field that +describe various file-wide properties. Some of the flags are valid only +for particular file-format versions, which means the flags can be used +to fix file-format bugs. Consumers that see unknown flags should +accordingly assume that the dictionary is not comprehensible, and +refuse to open them. + +The following flags are currently defined. Many are bug workarounds, +valid only in CTFv3, and will not be valid in any future versions: the +same values may be reused for other flags in v4+. + +@multitable {@code{CTF_F_NEWFUNCINFO}} {Versions} {Value} {The external strtab is in @code{.dynstr} and the} +@headitem Flag @tab Versions @tab Value @tab Meaning +@tindex CTF_F_COMPRESS +@item @code{CTF_F_COMPRESS} @tab All @tab 0x1 @tab Compressed with zlib +@tindex CTF_F_NEWFUNCINFO +@item @code{CTF_F_NEWFUNCINFO} @tab 3 only @tab 0x2 +@tab ``New-format'' func info section. +@tindex CTF_F_IDXSORTED +@item @code{CTF_F_IDXSORTED} @tab 3+ @tab 0x4 @tab The index section is +in sorted order +@tindex CTF_F_DYNSTR +@item @code{CTF_F_DYNSTR} @tab 3 only @tab 0x8 @tab The external strtab is +in @code{.dynstr} and the symtab used is @code{.dynsym}. +@xref{The string section} +@end multitable + +@code{CTF_F_NEWFUNCINFO} and @code{CTF_F_IDXSORTED} relate to the +function info and data object sections. @xref{The symtypetab sections}. + +Further flags (and further compression methods) wil be added in future. + +@node CTF header +@section CTF header +@cindex CTF header +@cindex Sections, header + +The CTF header is the first part of a CTF dictionary, including the +preamble. All parts of it other than the preamble (@pxref{CTF Preamble}) +can vary between CTF file versions and are never compressed. It +contains things that apply to the dictionary as a whole, and a table of +the sections into which the rest of the dictionary is divided. The +sections tile the file: each section runs from the offset given until +the start of the next section. Only the last section cannot follow this +rule, so the header has a length for it instead. + +All section offsets, here and in the rest of the CTF file, are relative to the +@emph{end} of the header. (This is annoyingly different to how offsets in CTF +archives are handled.) + +This is the first structure to include offsets into the string table, which are +not straight references because CTF dictionaries can include references into the +ELF string table to save space, as well as into the string table internal to the +CTF dictionary. @xref{The string section} for more on these. Offset 0 is +always the null string. + +@verbatim +typedef struct ctf_header +{ + ctf_preamble_t cth_preamble; + uint32_t cth_parlabel; + uint32_t cth_parname; + uint32_t cth_cuname; + uint32_t cth_lbloff; + uint32_t cth_objtoff; + uint32_t cth_funcoff; + uint32_t cth_objtidxoff; + uint32_t cth_funcidxoff; + uint32_t cth_varoff; + uint32_t cth_typeoff; + uint32_t cth_stroff; + uint32_t cth_strlen; +} ctf_header_t; +@end verbatim + +In detail: + +@tindex struct ctf_header +@tindex ctf_header_t +@multitable {Offset} {@code{ctf_preamble_t cth_preamble}} {The parent label, if deduplication happened against} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{ctf_preamble_t cth_preamble} +@vindex cth_preamble +@vindex struct ctf_header, cth_preamble +@vindex ctf_header_t, cth_preamble +@tab The preamble (conceptually embedded in the header). @xref{CTF Preamble} + +@item 0x04 +@tab @code{uint32_t cth_parlabel} +@vindex cth_parlabel +@vindex struct ctf_header, cth_parlabel +@vindex ctf_header_t, cth_parlabel +@tab The parent label, if deduplication happened against a specific label: a +strtab offset. @xref{The label section}. Currently unused and always 0, but may +be used in future when semantics are attached to the label section. + +@item 0x08 +@tab @code{uint32_t cth_parname} +@vindex cth_parname +@vindex struct ctf_header, cth_parname +@vindex ctf_header_t, cth_parname +@tab The name of the parent dictionary deduplicated against: a strtab offset. +Interpretation is up to the consumer (usually a CTF archive member name). 0 +(the null string) if this is not a child dictionary. + +@item 0x1c +@tab @code{uint32_t cth_cuname} +@vindex cth_cuname +@vindex struct ctf_header, cth_cuname +@vindex ctf_header_t, cth_cuname +@tab The name of the compilation unit, for consumers like GDB that want to +know the name of CUs associated with single CUs: a strtab offset. 0 if this +dictionary describes types from many CUs. + +@item 0x10 +@tab @code{uint32_t cth_lbloff} +@vindex cth_lbloff +@vindex struct ctf_header, cth_lbloff +@vindex ctf_header_t, cth_lbloff +@tab The offset of the label section, which tiles the type space into +named regions. @xref{The label section}. + +@item 0x14 +@tab @code{uint32_t cth_objtoff} +@vindex cth_objtoff +@vindex struct ctf_header, cth_objtoff +@vindex ctf_header_t, cth_objtoff +@tab The offset of the data object symtypetab section, which maps ELF data symbols to +types. @xref{The symtypetab sections}. + +@item 0x18 +@tab @code{uint32_t cth_funcoff} +@vindex cth_funcoff +@vindex struct ctf_header, cth_funcoff +@vindex ctf_header_t, cth_funcoff +@tab The offset of the function info symtypetab section, which maps ELF function +symbols to a return type and arg types. @xref{The symtypetab sections}. + +@item 0x1c +@tab @code{uint32_t cth_objtidxoff} +@vindex cth_objtidxoff +@vindex struct ctf_header, cth_objtidxoff +@vindex ctf_header_t, cth_objtidxoff +@tab The offset of the object index section, which maps ELF object symbols to +entries in the data object section. @xref{The symtypetab sections}. + +@item 0x20 +@tab @code{uint32_t cth_funcidxoff} +@vindex cth_funcidxoff +@vindex struct ctf_header, cth_funcidxoff +@vindex ctf_header_t, cth_funcidxoff +@tab The offset of the function info index section, which maps ELF function +symbols to entries in the function info section. @xref{The symtypetab sections}. + +@item 0x24 +@tab @code{uint32_t cth_varoff} +@vindex cth_varoff +@vindex struct ctf_header, cth_varoff +@vindex ctf_header_t, cth_varoff +@tab The offset of the variable section, which maps string names to types. +@xref{The variable section}. + +@item 0x28 +@tab @code{uint32_t cth_typeoff} +@vindex cth_typeoff +@vindex struct ctf_header, cth_typeoff +@vindex ctf_header_t, cth_typeoff +@tab The offset of the type section, the core of CTF, which describes types + using variable-length array elements. @xref{The type section}. + +@item 0x2c +@tab @code{uint32_t cth_stroff} +@vindex cth_stroff +@vindex struct ctf_header, cth_stroff +@vindex ctf_header_t, cth_stroff +@tab The offset of the string section. @xref{The string section}. + +@item 0x30 +@tab @code{uint32_t cth_strlen} +@vindex cth_strlen +@vindex struct ctf_header, cth_strlen +@vindex ctf_header_t, cth_strlen +@tab The length of the string section (not an offset!). The CTF file ends +at this point. + +@end multitable + +Everything from this point on (until the end of the file at @code{cth_stroff} + +@code{cth_strlen}) is compressed with zlib if @code{CTF_F_COMPRESS} is set in +the preamble's @code{ctp_flags}. + +@node The type section +@section The type section +@cindex Type section +@cindex Sections, type + +This section is the most important section in CTF, describing all the top-level +types in the program. It consists of an array of type structures, each of which +describes a type of some @dfn{kind}: each kind of type has some amount of +variable-length data associated with it (some kinds have none). The amount of +variable-length data associated with a given type can be determined by +inspecting the type, so the reading code can walk through the types in sequence +at opening time. + +Each type structure is one of a set of overlapping structures in a discriminated +union of sorts: the variable-length data for each type immediately follows the +type's type structure. Here's the largest of the overlapping structures, which +is only needed for huge types and so is very rarely seen: + +@verbatim +typedef struct ctf_type +{ + uint32_t ctt_name; + uint32_t ctt_info; + __extension__ + union + { + uint32_t ctt_size; + uint32_t ctt_type; + }; + uint32_t ctt_lsizehi; + uint32_t ctt_lsizelo; +} ctf_type_t; +@end verbatim + +Here's the much more common smaller form: + +@verbatim +typedef struct ctf_stype +{ + uint32_t ctt_name; + uint32_t ctt_info; + __extension__ + union + { + uint32_t ctt_size; + uint32_t ctt_type; + }; +} ctf_stype_t; +@end verbatim + +If @code{ctt_size} is the #define @code{CTF_LSIZE_SENT}, 0xffffffff, this type +is described by a @code{ctf_type_t}: otherwise, a @code{ctf_stype_t}. +@tindex CTF_LSIZE_SENT + +Here's what the fields mean: + +@tindex struct ctf_type +@tindex struct ctf_stype +@tindex ctf_type_t +@tindex ctf_stype_t +@multitable {0x1c (@code{ctf_type_t}} {@code{uint32_t ctt_lsizehi}} {The size of this type, if this type is of a kind for} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint32_t ctt_name} +@vindex ctt_name +@tab Strtab offset of the type name, if any (0 if none). + +@item 0x04 +@tab @code{uint32_t ctt_info} +@vindex ctt_info +@vindex struct ctf_type, ctt_info +@vindex ctf_type_t, ctt_info +@vindex struct ctf_stype, ctt_info +@vindex ctf_stype_t, ctt_info +@tab The @dfn{info word}, containing information on the kind of this type, its +variable-length data and whether it is visible to name lookup. See @xref{The +info word}. + +@item 0x08 +@tab @code{uint32_t ctt_size} +@vindex ctt_size +@vindex struct ctf_type, ctt_size +@vindex ctf_type_t, ctt_size +@vindex struct ctf_stype, ctt_size +@vindex ctf_stype_t, ctt_size +@tab The size of this type, if this type is of a kind for which a size needs +to be recorded (constant-size types don't need one). If this is +@code{CTF_LSIZE_SENT}, this type is a huge type described by @code{ctf_type_t}. + +@item 0x08 +@tab @code{uint32_t ctt_type} +@vindex ctt_type +@vindex struct ctf_stype, ctt_type +@vindex ctf_stype_t, ctt_type +@tab The type this type refers to, if this type is of a kind which refers to +other types (like a pointer). All such types are fixed-size, and no types that +are variable-size refer to other types, so @code{ctt_size} and @code{ctt_type} +overlap. All type kinds that use @code{ctt_type} are described by +@code{ctf_stype_t}, not @code{ctf_type_t}. @xref{Type indexes and type IDs}. + +@item 0x0c (@code{ctf_type_t} only) +@tab @code{uint32_t ctt_lsizehi} +@vindex ctt_lsizehi +@vindex struct ctf_type, ctt_lsizehi +@vindex ctf_type_t, ctt_lsizehi +@tab The high 32 bits of the size of a very large type. The @code{CTF_TYPE_LSIZE} macro +can be used to get a 64-bit size out of this field and the next one. +@code{CTF_SIZE_TO_LSIZE_HI} splits the @code{ctt_lsizehi} out of it again. +@findex CTF_TYPE_LSIZE +@findex CTF_SIZE_TO_LSIZE_HI + +@item 0x10 (@code{ctf_type_t} only) +@tab @code{uint32_t ctt_lsizelo} +@vindex ctt_lsizelo +@vindex struct ctf_type, ctt_lsizelo +@vindex ctf_type_t, ctt_lsizelo +@tab The low 32 bits of the size of a very large type. +@code{CTF_SIZE_TO_LSIZE_LO} splits the @code{ctt_lsizelo} out of a 64-bit size. +@findex CTF_SIZE_TO_LSIZE_LO +@end multitable + +Two aspects of this need further explanation: the info word, and what exactly a +type ID is and how you determine it. (Information on the various type-kind- +dependent things, like whether @code{ctt_size} or @code{ctt_type} is used, +is described in the section devoted to each kind.) + +@node The info word +@subsection The info word, ctt_info + +The info word is a bitfield split into three parts. From MSB to LSB: + +@multitable {Bit offset} {@code{isroot}} {Length of variable-length data for this type (some kinds only).} +@headitem Bit offset @tab Name @tab Description +@item 26--31 +@tab @code{kind} +@tab Type kind: @pxref{Type kinds}. + +@item 25 +@tab @code{isroot} +@tab 1 if this type is visible to name lookup + +@item 0--24 +@tab @code{vlen} +@tab Length of variable-length data for this type (some kinds only). +The variable-length data directly follows the @code{ctf_type_t} or +@code{ctf_stype_t}. This is a kind-dependent array length value, +not a length in bytes. Some kinds have no variable-length data, or +fixed-size variable-length data, and do not use this value. +@end multitable + +The most mysterious of these is undoubtedly @code{isroot}. This indicates +whether types with names (nonzero @code{ctt_name}) are visible to name lookup: +if zero, this type is considered a @dfn{non-root type} and you can't look it up +by name at all. Multiple types with the same name in the same C namespace +(struct, union, enum, other) can exist in a single dictionary, but only one of +them may have a nonzero value for @code{isroot}. @code{libctf} validates this +at open time and refuses to open dictionaries that violate this constraint. + +Historically, this feature was introduced for the encoding of bitfields +(@pxref{Integer types}): for instance, int bitfields will all be named +@code{int} with different widths or offsets, but only the full-width one at +offset zero is wanted when you look up the type named @code{int}. With the +introduction of slices (@pxref{Slices}) as a more general bitfield encoding +mechanism, this is less important, but we still use non-root types to handle +conflicts if the linker API is used to fuse multiple translation units into one +dictionary and those translation units contain types with the same name and +conflicting definitions. (We do not discuss this further here, because the +linker never does this: only specialized type mergers do, like that used for the +Linux kernel. The libctf documentation will describe this in more detail.) +@c XXX update when libctf docs are written. + +The @code{CTF_TYPE_INFO} macro can be used to compose an info word from +a @code{kind}, @code{isroot}, and @code{vlen}; @code{CTF_V2_INFO_KIND}, +@code{CTF_V2_INFO_ISROOT} and @code{CTF_V2_INFO_VLEN} pick it apart again. +@findex CTF_TYPE_INFO +@findex CTF_V2_INFO_KIND +@findex CTF_V2_INFO_ISROOT +@findex CTF_V2_INFO_VLEN + +@node Type indexes and type IDs +@subsection Type indexes and type IDs +@cindex Type indexes +@cindex Type IDs +@cindex Type, IDs of +@cindex Type, indexes of +@cindex ctf_id_t + +@cindex Parent range +@cindex Child range +@cindex Type IDs, ranges +Types are referred to within the CTF file via @dfn{type IDs}. A type ID is a +number from 0 to @math{2^32}, from a space divided in half. Types @math{2^31-1} +and below are in the @dfn{parent range}: these IDs are used for dictionaries +that have not had any other dictionary @code{ctf_import}ed into it as a parent. +Both completely standalone dictionaries and parent dictionaries with children +hanging off them have types in this range. Types @math{2^31} and above are in +the @dfn{child range}: only types in child dictionaries are in this range. + +These IDs appear in @code{ctf_type_t.ctt_type} (@pxref{The type section}), but +the types themselves have no visible ID: quite intentionally, because adding an +ID uses space, and every ID is different so they don't compress well. The IDs +are implicit: at open time, the consumer walks through the entire type section +and counts the types in the type section. The type section is an array of +variable-length elements, so each entry could be considered as having an index, +starting from 1. We count these indexes and associate each with its +corresponding @code{ctf_type_t} or @code{ctf_stype_t}. + +Lookups of types with IDs in the parent space look in the parent dictionary if +this dictionary has one associated with it; lookups of types with IDs in the +child space error out if the dictionary does not have a parent, and otherwise +convert the ID into an index by shaving off the top bit and look up the index +in the child. + +These properties mean that the same dictionary can be used as a parent of child +dictionaries and can also be used directly with no children at all, but a +dictionary created as a child dictionary must always be associated with a parent +--- usually, the same parent --- because its references to its own types have +the high bit turned on and this is only flipped off again if this is a child +dictionary. (This is not a problem, because if you @emph{don't} associate the +child with a parent, any references within it to its parent types will fail, and +there are almost certain to be many such references, or why is it a child at +all?) + +This does mean that consumers should keep a close eye on the distinction between +type IDs and type indexes: if you mix them up, everything will appear to work as +long as you're only using parent dictionaries or standalone dictionaries, but as +soon as you start using children, everything will fail horribly. + +Type index zero, and type ID zero, are used to indicate that this type cannot be +represented in CTF as currently constituted: they are emitted by the compiler, +but all type chains that terminate in the unknown type are erased at link time +(structure fields that use them just vanish, etc). So you will probably never +see a use of type zero outside the symtypetab sections, where they serve as +sentinels of sorts, to indicate symbols with no associated type. + +The macros @code{CTF_V2_TYPE_TO_INDEX} and @code{CTF_V2_INDEX_TO_TYPE} may help +in translation between types and indexes: @code{CTF_V2_TYPE_ISPARENT} and +@code{CTF_V2_TYPE_ISCHILD} can be used to tell whether a given ID is in the +parent or child range. +@findex CTF_V2_TYPE_TO_INDEX +@findex CTF_V2_INDEX_TO_TYPE +@findex CTF_V2_TYPE_ISPARENT +@findex CTF_V2_TYPE_ISCHILD + +It is quite possible and indeed common for type IDs to point forward in the +dictionary, as well as backward. + +@node Type kinds +@subsection Type kinds +@cindex Type kinds +@cindex Type, kinds of + +Every type in CTF is of some @dfn{kind}. Each kind is some variety of C type: +all structures are a single kind, as are all unions, all pointers, all arrays, +all integers regardless of their bitfield width, etc. The kind of a type is +given in the @code{kind} field of the @code{ctt_info} word (@pxref{The info +word}). + +The space of type kinds is only a quarter full so far, so there is plenty of +room for expansion. It is likely that in future versions of the file format, +types with smaller kinds will be more efficiently encoded than types with larger +kinds, so their numerical value will actually start to matter in future. (So +these IDs will probably change their numerical values in a later release of this +format, to move more frequently-used kinds like structures and cv-quals towards +the top of the space, and move rarely-used kinds like integers downwards. Yes, +integers are rare: how many kinds of @code{int} are there in a program? They're +just very frequently @emph{referenced}.) + +Here's the set of kinds so far. Each kind has a @code{#define} associated with +it, also given here. + +@multitable {Kind} {@code{CTF_K_VOLATILE}} {Indicates a type that cannot be represented in CTF, or that} {@xref{Pointers typedefs and cvr-quals}} +@headitem Kind @tab Macro @tab Purpose +@item 0 +@tab @code{CTF_K_UNKNOWN} +@tab Indicates a type that cannot be represented in CTF, or that is being skipped. +It is very similar to type ID 0, except that you can have @emph{multiple}, distinct types +of kind @code{CTF_K_UNKNOWN}. +@tindex CTF_K_UNKNOWN + +@item 1 +@tab @code{CTF_K_INTEGER} +@tab An integer type. @xref{Integer types}. + +@item 2 +@tab @code{CTF_K_FLOAT} +@tab A floating-point type. @xref{Floating-point types}. + +@item 3 +@tab @code{CTF_K_POINTER} +@tab A pointer. @xref{Pointers typedefs and cvr-quals}. + +@item 4 +@tab @code{CTF_K_ARRAY} +@tab An array. @xref{Arrays}. + +@item 5 +@tab @code{CTF_K_FUNCTION} +@tab A function pointer. @xref{Function pointers}. + +@item 6 +@tab @code{CTF_K_STRUCT} +@tab A structure. @xref{Structs and unions}. + +@item 7 +@tab @code{CTF_K_UNION} +@tab A union. @xref{Structs and unions}. + +@item 8 +@tab @code{CTF_K_ENUM} +@tab An enumerated type. @xref{Enums}. + +@item 9 +@tab @code{CTF_K_FORWARD} +@tab A forward. @xref{Forward declarations}. + +@item 10 +@tab @code{CTF_K_TYPEDEF} +@tab A typedef. @xref{Pointers typedefs and cvr-quals}. + +@item 11 +@tab @code{CTF_K_VOLATILE} +@tab A volatile-qualified type. @xref{Pointers typedefs and cvr-quals}. + +@item 12 +@tab @code{CTF_K_CONST} +@tab A const-qualified type. @xref{Pointers typedefs and cvr-quals}. + +@item 13 +@tab @code{CTF_K_RESTRICT} +@tab A restrict-qualified type. @xref{Pointers typedefs and cvr-quals}. + +@item 14 +@tab @code{CTF_K_SLICE} +@tab A slice, a change of the bit-width or offset of some other type. @xref{Slices}. +@end multitable + +Now we cover all type kinds in turn. Some are more complicated than others. + +@node Integer types +@subsection Integer types +@cindex Integer types +@cindex Types, integer +@tindex int +@tindex long +@tindex long long +@tindex short +@tindex char +@tindex bool +@tindex unsigned int +@tindex unsigned long +@tindex unsigned long long +@tindex unsigned short +@tindex unsigned char +@tindex signed int +@tindex signed long +@tindex signed long long +@tindex signed short +@tindex signed char +@cindex CTF_K_INTEGER + +Integral types are all represented as types of kind @code{CTF_K_INTEGER}. These +types fill out @code{ctt_size} in the @code{ctf_stype_t} with the size in bytes +of the integral type in question. They are always represented by +@code{ctf_stype_t}, never @code{ctf_type_t}. Their variable-length data is one +@code{uint32_t} in length: @code{vlen} in the info word should be disregarded +and is always zero. + +The variable-length data for integers has multiple items packed into it much +like the info word does. + +@multitable {Bit offset} {Encoding} {The integer encoding and desired display representation.} +@headitem Bit offset @tab Name @tab Description +@item 24--31 +@tab Encoding +@tab The desired display representation of this integer. You can extract this +field with the @code{CTF_INT_ENCODING} macro. See below. +@findex CTF_INT_ENCODING + +@item 16--23 +@tab Offset +@tab The offset of this integral type in bits from the start of its enclosing +structure field, adjusted for endianness: @pxref{Structs and unions}. You can +extract this field with the @code{CTF_INT_OFFSET} macro. +@findex CTF_INT_OFFSET + +@item 0--15 +@tab Bit-width +@tab The width of this integral type in bits. You can extract this field with +the @code{CTF_INT_BITS} macro. +@findex CTF_INT_BITS +@end multitable + +If you choose, bitfields can be represented using the things above as a sort of +integral type with the @code{isroot} bit flipped off and the offset and bits +values set in the vlen word: you can populate it with the @code{CTF_INT_DATA} +macro. (But it may be more convenient to represent them using slices of a +full-width integer: @pxref{Slices}.) +@findex CTF_INT_DATA + +Integers that are bitfields usually have a @code{ctt_size} rounded up to the +nearest power of two in bytes, for natural alignment (e.g. a 17-bit integer +would have a @code{ctt_size} of 4). However, not all types are naturally +aligned on all architectures: packed structures may in theory use integral +bitfields with different @code{ctt_size}, though this is rarely observed. + +The @dfn{encoding} for integers is a bit-field comprised of the values below, +which consumers can use to decide how to display values of this type: + +@multitable {Offset} {@code{CTF_INT_VARARGS}} {If set, this is a char type. It is platform-dependent whether unadorned} +@headitem Offset @tab Name @tab Description +@item 0x01 +@tab @code{CTF_INT_SIGNED} +@tab If set, this is a signed int: if false, unsigned. +@tindex CTF_INT_SIGNED + +@item 0x02 +@tab @code{CTF_INT_CHAR} +@tab If set, this is a char type. It is platform-dependent whether unadorned +@code{char} is signed or not: the @code{CTF_CHAR} macro produces an integral +type suitable for the definition of @code{char} on this platform. +@tindex CTF_INT_CHAR +@findex CTF_CHAR + +@item 0x04 +@tab @code{CTF_INT_BOOL} +@tab If set, this is a boolean type. (It is theoretically possible to turn this +and @code{CTF_INT_CHAR} on at the same time, but it is not clear what this would +mean.) +@tindex CTF_INT_BOOL + +@item 0x08 +@tab @code{CTF_INT_VARARGS} +@tab If set, this is a varargs-promoted value in a K&R function definition. +This is not currently produced or consumed by anything that we know of: it is set +aside for future use. +@end multitable + +The GCC ``@code{Complex int}'' and fixed-point extensions are not yet supported: +references to such types will be emitted as type 0. + +@node Floating-point types +@subsection Floating-point types +@cindex Floating-point types +@cindex Types, floating-point +@tindex float +@tindex double +@tindex signed float +@tindex signed double +@tindex unsigned float +@tindex unsigned double +@tindex Complex, float +@tindex Complex, double +@tindex Complex, signed float +@tindex Complex, signed double +@tindex Complex, unsigned float +@tindex Complex, unsigned double +@cindex CTF_K_FLOAT + +Floating-point types are all represented as types of kind @code{CTF_K_FLOAT}. +Like integers, These types fill out @code{ctt_size} in the @code{ctf_stype_t} +with the size in bytes of the floating-point type in question. They are always +represented by @code{ctf_stype_t}, never @code{ctf_type_t}. + +This part of CTF shows many rough edges in the more obscure corners of +floating-point handling, and is likely to change in format v4. + +The variable-length data for floats has multiple items packed into it just like +integers do: + +@multitable {Bit offset} {Encoding} {The floating-;point encoding and desired display representation.} +@headitem Bit offset @tab Name @tab Description +@item 24--31 +@tab Encoding +@tab The desired display representation of this float. You can extract this +field with the @code{CTF_FP_ENCODING} macro. See below. +@findex CTF_FP_ENCODING + +@item 16--23 +@tab Offset +@tab The offset of this floating-point type in bits from the start of its enclosing +structure field, adjusted for endianness: @pxref{Structs and unions}. You can +extract this field with the @code{CTF_FP_OFFSET} macro. +@findex CTF_FP_OFFSET + +@item 0--15 +@tab Bit-width +@tab The width of this floating-point type in bits. You can extract this field with +the @code{CTF_FP_BITS} macro. +@findex CTF_FP_BITS +@end multitable + +The purpose of the floating-point offset and bit-width is somewhat opaque, since +there are no such things as floating-point bitfields in C: the bit-width should +be filled out with the full width of the type in bits, and the offset should +always be zero. It is likely that these fields will go away in the future. As +with integers, you can use @code{CTF_FP_DATA} to assemble one of these vlen +items from its component parts. +@findex CTF_INT_DATA + +The @dfn{encoding} for floats is not a bitfield but a simple value indicating +the display representation. Many of these are unused, relate to +Solaris-specific compiler extensions, and will be recycled in future: some are +unused and will become used in future. + +@multitable {Offset} {@code{CTF_FP_LDIMAGRY}} {This is a @code{float} interval type, a Solaris-specific extension.} +@headitem Offset @tab Name @tab Description +@item 1 +@tab @code{CTF_FP_SINGLE} +@tab This is a single-precision IEEE 754 @code{float}. +@tindex CTF_FP_SINGLE +@item 2 +@tab @code{CTF_FP_DOUBLE} +@tab This is a double-precision IEEE 754 @code{double}. +@tindex CTF_FP_DOUBLE +@item 3 +@tab @code{CTF_FP_CPLX} +@tab This is a @code{Complex float}. +@tindex CTF_FP_CPLX +@item 4 +@tab @code{CTF_FP_DCPLX} +@tab This is a @code{Complex double}. +@tindex CTF_FP_DCPLX +@item 5 +@tab @code{CTF_FP_LDCPLX} +@tab This is a @code{Complex long double}. +@tindex CTF_FP_LDCPLX +@item 6 +@tab @code{CTF_FP_LDOUBLE} +@tab This is a @code{long double}. +@tindex CTF_FP_LDOUBLE +@item 7 +@tab @code{CTF_FP_INTRVL} +@tab This is a @code{float} interval type, a Solaris-specific extension. +Unused: will be recycled. +@tindex CTF_FP_INTRVL +@cindex Unused bits +@item 8 +@tab @code{CTF_FP_DINTRVL} +@tab This is a @code{double} interval type, a Solaris-specific extension. +Unused: will be recycled. +@tindex CTF_FP_DINTRVL +@cindex Unused bits +@item 9 +@tab @code{CTF_FP_LDINTRVL} +@tab This is a @code{long double} interval type, a Solaris-specific extension. +Unused: will be recycled. +@tindex CTF_FP_LDINTRVL +@cindex Unused bits +@item 10 +@tab @code{CTF_FP_IMAGRY} +@tab This is a the imaginary part of a @code{Complex float}. Not currently +generated. May change. +@tindex CTF_FP_IMAGRY +@cindex Unused bits +@item 11 +@tab @code{CTF_FP_DIMAGRY} +@tab This is a the imaginary part of a @code{Complex double}. Not currently +generated. May change. +@tindex CTF_FP_DIMAGRY +@cindex Unused bits +@item 12 +@tab @code{CTF_FP_LDIMAGRY} +@tab This is a the imaginary part of a @code{Complex long double}. Not currently +generated. May change. +@tindex CTF_FP_LDIMAGRY +@cindex Unused bits +@end multitable + +The use of the complex floating-point encodings is obscure: it is possible that +@code{CTF_FP_CPLX} is meant to be used for only the real part of complex types, +and @code{CTF_FP_IMAGRY} et al for the imaginary part -- but for now, we are +emitting @code{CTF_FP_CPLX} to cover the entire type, with no way to get at its +constituent parts. There appear to be no uses of these encodings anywhere, so +they are quite likely to change incompatibly in future. + +@node Slices +@subsection Slices +@cindex Slices +@cindex Types, slices of integral +@tindex CTF_K_SLICE + +Slices, with kind @code{CTF_K_SLICE}, are an unusual CTF construct: they do not +directly correspond to any C type, but are a way to model other types in a more +convenient fashion for CTF generators. + +A slice is like a pointer or other reference type in that they are always +represented by @code{ctf_stype_t}: but unlike pointers and other reference +types, they populate the @code{ctt_size} field just like integral types do, and +come with an attached encoding and transform the encoding of the underlying +type. The underlying type is described in the variable-length data, similarly +to structure and union fields: see below. Requests for the type size should +also chase down to the referenced type. + +Slices are always nameless: @code{ctt_name} is always zero for them. + +(The @code{libctf} API behaviour is unusual as well, and justifies the existence +of slices: @code{ctf_type_kind} never returns @code{CTF_K_SLICE} but always the +underlying type kind, so that consumers never need to know about slices: they +can tell if an apparent integer is actually a slice if they need to by calling +@code{ctf_type_reference}, which will uniquely return the underlying integral +type rather than erroring out with @code{ECTF_NOTREF} if this is actually a +slice. So slices act just like an integer with an encoding, but more closely +mirror DWARF and other debugging information formats by allowing CTF file +creators to represent a bitfield as a slice of an underlying integral type.) +@findex Slices, effect on ctf_type_kind +@findex Slices, effect on ctf_type_reference +@findex libctf, effect of slices + +The vlen in the info word for a slice should be ignored and is always zero. The +variable-length data for a slice is a single @code{ctf_slice_t}: + +@verbatim +typedef struct ctf_slice +{ + uint32_t cts_type; + unsigned short cts_offset; + unsigned short cts_bits; +} ctf_slice_t; +@end verbatim + +@tindex struct ctf_slice +@tindex ctf_slice_t +@multitable {Offset} {@code{unsigned short cts_offset}} {The type this slice is a slice of. Must be an} +@headitem Offset @tab Name @tab Description +@item 0x0 +@tab @code{uint32_t cts_type} +@vindex cts_type +@vindex struct ctf_slice, cts_type +@vindex ctf_slice_t, cts_type +@tab The type this slice is a slice of. Must be an integral type (or a +floating-point type, but this nonsensical option will go away in v4.) + +@item 0x4 +@tab @code{unsigned short cts_offset} +@vindex cts_offset +@vindex struct ctf_slice, cts_offset +@vindex ctf_slice_t, cts_offset +@tab The offset of this integral type in bits from the start of its enclosing +structure field, adjusted for endianness: @pxref{Structs and unions}. Identical +semantics to the @code{CTF_INT_OFFSET} field: @pxref{Integer types}. This field +is much too long, because the maximum possible offset of an integral type would +easily fit in a char: this field is bigger just for the sake of alignment. This +will change in v4. + +@item 0x6 +@tab @code{unsigned short cts_bits} +@vindex cts_bits +@vindex struct ctf_slice, cts_bits +@vindex ctf_slice_t, cts_bits +@tab The bit-width of this integral type. Identical semantics to the +@code{CTF_INT_BITS} field: @pxref{Integer types}. As above, this field is +really too large and will shrink in v4. +@end multitable + +@node Pointers typedefs and cvr-quals +@subsection Pointers, typedefs, and cvr-quals +@cindex Pointers +@cindex Typedefs +@cindex cvr-quals +@tindex typedef +@tindex const +@tindex volatile +@tindex restrict +@tindex CTF_K_POINTER +@tindex CTF_K_TYPEDEF +@tindex CTF_K_CONST +@tindex CTF_K_VOLATILE +@tindex CTF_K_RESTRICT + +Pointers, @code{typedef}s, and @code{const}, @code{volatile} and @code{restrict} +qualifiers are represented identically except for their type kind (though they +may be treated differently by consuming libraries like @code{libctf}, since +pointers affect assignment-compatibility in ways cvr-quals do not, and they may +have different alignment requirements, etc). + +All of these are represented by @code{ctf_stype_t}, have no variable data at +all, and populate @code{ctt_type} with the type ID of the type they point +to. These types can stack: a @code{CTF_K_RESTRICT} can point to a +@code{CTF_K_CONST} which can point to a @code{CTF_K_POINTER} etc. + +They are all unnamed: @code{ctt_name} is 0. + +The size of @code{CTF_K_POINTER} is derived from the data model (@pxref{Data +models}), i.e. in practice, from the target machine ABI, and is not explicitly +represented. The size of other kinds in this set should be determined by +chasing ctf_types as necessary until a non-typedef/const/volatile/restrict is +found, and using that. + +@node Arrays +@subsection Arrays +@cindex Arrays + +Arrays are encoded as types of kind @code{CTF_K_ARRAY} in a @code{ctf_stype_t}. +Both size and kind for arrays are zero. The variable-length data is a +@code{ctf_array_t}: @code{vlen} in the info word should be disregarded and is +always zero. + +@verbatim +typedef struct ctf_array +{ + uint32_t cta_contents; + uint32_t cta_index; + uint32_t cta_nelems; +} ctf_array_t; +@end verbatim + +@tindex struct ctf_array +@tindex ctf_array_t +@multitable {Offset} {@code{unsigned short cta_contents}} {The type of the array index: a type ID of an} +@headitem Offset @tab Name @tab Description +@item 0x0 +@tab @code{uint32_t cta_contents} +@vindex cta_contents +@vindex struct ctf_array, cta_contents +@vindex ctf_array_t, cta_contents +@tab The type of the array elements: a type ID. + +@item 0x4 +@tab @code{uint32_t cta_index} +@vindex cta_index +@vindex struct ctf_array, cta_index +@vindex ctf_array_t, cta_index +@tab The type of the array index: a type ID of an integral type. +If this is a variable-length array, the index type ID will be 0 +(but the actual index type of this array is probably @code{int}). +Probably redundant and may be dropped in v4. + +@item 0x8 +@tab @code{uint32_t cta_nelems} +@vindex cta_nelems +@vindex struct ctf_array, cta_nelems +@vindex ctf_array_t, cta_nelems +@tab The number of array elements. 0 for VLAs, and also for +the historical variety of VLA which has explicit zero dimensions (which will +have a nonzero @code{cta_index}.) +@end multitable + +The size of an array can be computed by simple multiplication of the size of the +@code{cta_contents} type by the @code{cta_nelems}. + +@node Function pointers +@subsection Function pointers +@cindex Function pointers +@cindex Pointers, to functions + +Function pointers are explicitly represented in the CTF type section by a type +of kind @code{CTF_K_FUNCTION}, always encoded with a @code{ctf_stype_t}. The +@code{ctt_type} is the function return type ID. The @code{vlen} in the info +word is the number of arguments, each of which is a type ID, a @code{uint32_t}: +if the last argument is 0, this is a varargs function and the number of +arguments is one less than indicated by the vlen. + +If the number of arguments is odd, a single @code{uint32_t} of padding is +inserted to maintain alignment. + +@node Enums +@subsection Enums +@cindex Enums +@tindex enum +@tindex CTF_K_ENUM + +Enumerated types are represented as types of kind @code{CTF_K_ENUM} in a +@code{ctf_stype_t}. The @code{ctt_size} is always the size of an int from the +data model (enum bitfields are implemented via slices). The @code{vlen} is a +count of enumerations, each of which is represented by a @code{ctf_enum_t} in +the vlen: + +@verbatim +typedef struct ctf_enum +{ + uint32_t cte_name; + int32_t cte_value; +} ctf_enum_t; +@end verbatim + +@tindex struct ctf_enum +@tindex ctf_enum_t +@multitable {Offset} {@code{int32_t cte_value}} {Strtab offset of the enumeration name.} +@headitem Offset @tab Name @tab Description +@item 0x0 +@tab @code{uint32_t cte_name} +@vindex cte_name +@vindex struct ctf_enum, cte_name +@vindex ctf_enum_t, cte_name +@tab Strtab offset of the enumeration name. Must not be 0. + +@item 0x4 +@tab @code{int32_t cte_value} +@vindex cte_value +@vindex struct ctf_enum, cte_value +@vindex ctf_enum_t, cte_value +@tab The enumeration value. + +@end multitable + +Enumeration values larger than @math{2^32} are not yet supported and are omitted +from the enumeration. (v4 will lift this restriction by encoding the value +differently.) + +Forward declarations of enums are not implemented with this kind: @pxref{Forward +declarations}. + +Enumerated type names, as usual in C, go into their own namespace, and do not +conflict with non-enums, structs, or unions with the same name. + +@node Structs and unions +@subsection Structs and unions +@cindex Structures +@cindex Unions +@tindex struct +@tindex union +@tindex CTF_K_STRUCT +@tindex CTF_K_UNION + +Structures and unions are represnted as types of kind @code{CTF_K_STRUCT} and +@code{CTF_K_UNION}: their representation is otherwise identical, and it is +perfectly allowed for ``structs'' to contain overlapping fields etc, so we will +treat them together for the rest of this section. + +They fill out @code{ctt_size}, and use @code{ctf_type_t} in preference to +@code{ctf_stype_t} if the structure size is greater than @code{CTF_MAX_SIZE} +(0xfffffffe). +@tindex CTF_MAX_LSIZE + +The vlen for structures and unions is a count of structure fields, but the type +used to represent a structure field (and thus the size of the variable-length +array element representing the type) depends on the size of the structure: truly +huge structures, greater than @code{CTF_LSTRUCT_THRESH} bytes in length, use a +different type. (@code{CTF_LSTRUCT_THRESH} is 536870912, so such structures are +vanishingly rare: in v4, this representation will change somewhat for greater +compactness. It's inherited from v1, where the limits were much lower.) +@tindex CTF_LSTRUCT_THRESH + +Most structures can get away with using @code{ctf_member_t}: + +@verbatim +typedef struct ctf_member_v2 +{ + uint32_t ctm_name; + uint32_t ctm_offset; + uint32_t ctm_type; +} ctf_member_t; +@end verbatim + +Huge structures that are represented by @code{ctf_type_t} rather than +@code{ctf_stype_t} have to use @code{ctf_lmember_t}, which splits the offset as +@code{ctf_type_t} splits the size: + +@verbatim +typedef struct ctf_lmember_v2 +{ + uint32_t ctlm_name; + uint32_t ctlm_offsethi; + uint32_t ctlm_type; + uint32_t ctlm_offsetlo; +} ctf_lmember_t; +@end verbatim + +Here's what the fields of @code{ctf_member} mean: + +@tindex struct ctf_member_v2 +@tindex ctf_member_t +@multitable {Offset} {@code{uint32_t ctm_offset}} {The offset of this field @emph{in bits}. (Usually, for bitfields, this is} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint32_t ctm_name} +@vindex ctm_name +@vindex struct ctf_member_v2, ctm_name +@vindex ctf_member_t, ctm_name +@tab Strtab offset of the field name. + +@item 0x04 +@tab @code{uint32_t ctm_offset} +@vindex ctm_offset +@vindex struct ctf_member_v2, ctm_offset +@vindex ctf_member_t, ctm_offset +@tab The offset of this field @emph{in bits}. (Usually, for bitfields, this is +machine-word-aligned and the individual field has an offset in bits, but +the format allows for the offset to be encoded in bits here.) + +@item 0x08 +@tab @code{uint32_t ctm_type} +@vindex ctm_type +@vindex struct ctf_member_v2, ctm_type +@vindex ctf_member_t, ctm_type +@tab The type ID of the type of the field. +@end multitable + +Here's what the fields of the very similar @code{ctf_lmember} mean: + +@tindex struct ctf_lmember_v2 +@tindex ctf_lmember_t +@multitable {Offset} {@code{uint32_t ctlm_offsethi}} {The offset of this field @emph{in bits}. (Usually, for bitfields, this is} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint32_t ctlm_name} +@vindex ctlm_name +@vindex struct ctf_lmember_v2, ctlm_name +@vindex ctf_lmember_t, ctlm_name +@tab Strtab offset of the field name. + +@item 0x04 +@tab @code{uint32_t ctlm_offsethi} +@vindex ctlm_offsethi +@vindex struct ctf_lmember_v2, ctlm_offsethi +@vindex ctf_lmember_t, ctlm_offsethi +@tab The high 32 bits of the offset of this field in bits. + +@item 0x08 +@tab @code{uint32_t ctlm_type} +@vindex ctm_type +@vindex struct ctf_lmember_v2, ctlm_type +@vindex ctf_member_t, ctlm_type +@tab The type ID of the type of the field. + +@item 0x0c +@tab @code{uint32_t ctlm_offsetlo} +@vindex ctlm_offsetlo +@vindex struct ctf_lmember_v2, ctlm_offsetlo +@vindex ctf_lmember_t, ctlm_offsetlo +@tab The low 32 bits of the offset of this field in bits. +@end multitable + +Macros @code{CTF_LMEM_OFFSET}, @code{CTF_OFFSET_TO_LMEMHI} and +@code{CTF_OFFSET_TO_LMEMLO} serve to extract and install the values of the +@code{ctlm_offset} fields, much as with the split size fields in +@code{ctf_type_t}. + +Unnamed structure and union fields are simply implemented by collapsing the +unnamed field's members into the containing structure or union: this does mean +that a structure containing an unnamed union can end up being a ``structure'' +with multiple members at the same offset. (A future format revision may +collapse @code{CTF_K_STRUCT} and @code{CTF_K_UNION} into the same kind and +decide among them based on whether their members do in fact overlap.) + +Structure and union type names, as usual in C, go into their own namespace, +just as enum type names do. + +Forward declarations of structures and unions are not implemented with this +kind: @pxref{Forward declarations}. + +@node Forward declarations +@subsection Forward declarations +@cindex Forwards +@tindex enum +@tindex struct +@tindex union +@tindex CTF_K_FORWARD + +When the compiler encounters a forward declaration of a struct, union, or enum, +it emits a type of kind @code{CTF_K_FORWARD}. If it later encounters a non- +forward declaration of the same thing, it marks the forward as non-root-visible: +before link time, therefore, non-root-visible forwards indicate that a +non-forward is coming. + +After link time, forwards are fused with their corresponding non-forwards by the +deduplicator where possible. They are kept if there is no non-forward +definition (maybe it's not visible from any TU at all) or if @code{multiple} +conflicting structures with the same name might match it. Otherwise, all other +forwards are converted to structures, unions, or enums as appropriate, even +across TUs if only one structure could correspond to the forward (after all, +all types across all TUs land in the same dictionary unless they conflict, +so promoting forwards to their concrete type seems most helpful). + +A forward has a rather strange representation: it is encoded with a +@code{ctf_stype_t} but the @code{ctt_type} is populated not with a type (if it's +a forward, we don't have an underlying type yet: if we did, we'd have promoted +it and this wouldn't be a forward any more) but with the @code{kind} of the +forward. This means that we can distinguish forwards to structs, enums and +unions reliably and ensure they land in the appropriate namespace even before +the actual struct, union or enum is found. + +@node The symtypetab sections +@section The symtypetab sections +@cindex Symtypetab section +@cindex Sections, symtypetab +@cindex Function info section +@cindex Sections, function info +@cindex Data object section +@cindex Sections, data object +@cindex Function info index section +@cindex Sections, function info index +@cindex Data object index section +@cindex Sections, data object index +@tindex CTF_F_IDXSORTED +@tindex CTF_F_DYNSTR +@cindex Bug workarounds, CTF_F_DYNSTR + +These are two very simple sections with identical formats, used by consumers to +map from ELF function and data symbols directly to their types. So they are +usually populated only in CTF sections that are embedded in ELF objects. + +Their format is very simple: an array of type IDs. Which symbol each type ID +corresponds to depends on whether the optional @emph{index section} associated +with this symtypetab section has any content. + +If the index section is nonempty, it is an array of @code{uint32_t} string table +offsets, each giving the name of the symbol whose type is at the same offset in +the corresponding non-index section: users can look up symbols in such a table +by name. The index section and corresponding symtypetab section is usually +ASCIIbetically sorted (indicated by the @code{CTF_F_IDXSORTED} flag in the +header): if it's sorted, it can be bsearched for a symbol name rather than +having to use a slower linear search. + +If the data object index section is empty, the entries in the data object and +function info sections are associated 1:1 with ELF symbols of type +@code{STT_OBJECT} (for data object) or @code{STT_FUNC} (for function info) with +a nonzero value: the linker shuffles the symtypetab sections to correspond with +the order of the symbols in the ELF file. Symbols with no name, undefined +symbols and symbols named ``@code{_START_}'' and ``@code{_END_}'' are skipped +and never appear in either section. Symbols that have no corresponding type are +represented by type ID 0. The section may have fewer entries than the symbol +table, in which case no later entries have associated types. This format is +more compact than an indexed form if most entries have types (since there is no +need to record any symbol names), but if the producer and consumer disagree even +slightly about which symbols are omitted, the types of all further symbols will +be wrong! + +The compiler always emits indexed symtypetab tables, because there is no symbol +table yet. The linker will always have to read them all in and always works +through them from start to end, so there is no benefit having the compiler sort +them either. The linker (actually, @code{libctf}'s linking machinery) will +automatically sort unsorted indexed sections, and convert indexed sections that +contain a lot of pads into the more compact, unindexed form. + +If child dicts are in use, only symbols that use types actually mentioned in the +child appear in the child's symtypetab: symbols that use only types in the +parent appear in the parent's symtypetab instead. So the child's symtypetab will +almost always be very sparse, and thus will usually use the indexed form even in +fully linked objects. (It is, of course, impossible for symbols to exist that +use types from multiple child dicts at once, since it's impossible to declare a +function in C that uses types that are only visible in two different, disjoint +translation units.) + +@node The variable section +@section The variable section +@cindex Variable section +@cindex Sections, variable + +The variable section is a simple array mapping names (strtab entries) to type +IDs, intended to provide a replacement for the data object section in dynamic +situations in which there is no static ELF strtab but the consumer instead hands +back names. The section is sorted into ASCIIbetical order by name for rapid +lookup, like the CTF archive name table. + +The section is an array of these structures: + +@verbatim +typedef struct ctf_varent +{ + uint32_t ctv_name; + uint32_t ctv_type; +} ctf_varent_t; +@end verbatim + +@tindex struct ctf_varent +@tindex ctf_varent_t +@multitable {Offset} {@code{uint32_t ctv_name}} {Strtab offset of the name} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint32_t ctv_name} +@vindex ctv_name +@vindex struct ctf_varent, ctv_name +@vindex ctf_varent_t, ctv_name +@tab Strtab offset of the name + +@item 0x04 +@tab @code{uint32_t ctv_type} +@vindex ctv_type +@vindex struct ctf_varent, ctv_type +@vindex ctf_varent_t, ctv_type +@tab Type ID of this type +@end multitable + +There is no analogue of the function info section yet: v4 will probably drop +this section in favour of a way to put both indexed (thus, named) and nonindexed +symbols into the symtypetab sections at the same time. + +@node The label section +@section The label section +@cindex Label section +@cindex Sections, label + +The label section is a currently-unused facility allowing the tiling of the type +space with names taken from the strtab. The section is an array of these +structures: + +@verbatim +typedef struct ctf_lblent +{ + uint32_t ctl_label; + uint32_t ctl_type; +} ctf_lblent_t; +@end verbatim + +@tindex struct ctf_lblent +@tindex ctf_lblent_t +@multitable {Offset} {@code{uint32_t ctl_label}} {Strtab offset of the label} +@headitem Offset @tab Name @tab Description +@item 0x00 +@tab @code{uint32_t ctl_label} +@vindex ctl_label +@vindex struct ctf_lblent, ctl_label +@vindex ctf_lblent_t, ctl_label +@tab Strtab offset of the label + +@item 0x04 +@tab @code{uint32_t ctl_type} +@vindex ctl_type +@vindex struct ctf_lblent, ctl_type +@vindex ctf_lblent_t, ctl_type +@tab Type ID of the last type covered by this label +@end multitable + +Semantics will be attached to labels soon, probably in v4 (the plan is to use +them to allow multiple disjoint namespaces in a single CTF file, removing many +uses of CTF archives, in particular in the @code{.ctf} section in ELF objects). + +@node The string section +@section The string section +@cindex String section +@cindex Sections, string + +This section is a simple ELF-format strtab, starting with a zero byte (thus +ensuring that the string with offset 0 is the null string, as assumed elsewhere +in this spec). The strtab is usually ASCIIbetically sorted to somewhat improve +compression efficiency. + +Where the strtab is unusual is the @emph{references} to it. CTF has two +string tables, the internal strtab and an external strtab associated +with the CTF dictionary at open time: usually, this is the ELF dynamic +strtab (@code{.dynstr}) of a CTF dictionary embedded in an ELF file. We +distinguish between these strtabs by the most significant bit, bit 31, +of the 32-bit strtab references: if it is 0, the offset is in the +internal strtab: if 1, the offset is in the external strtab. + +@tindex CTF_F_DYNSTR +@cindex Bug workarounds, CTF_F_DYNSTR +There is a bug workaround in this area: in format v3 (the first version +to have working support for external strtabs), the external strtab is +@code{.strtab} unless the @code{CTF_F_DYNSTR} flag is set on the +dictionary (@pxref{CTF file-wide flags}). Format v4 will introduce a +header field that explicitly names the external strtab, making this flag +unnecessary. + +@node Data models +@section Data models +@cindex Data models + +The data model is a simple integer which indicates the ABI in use on this +platform. Right now, it is very simple, distinguishing only between 32- and +64-bit types: a model of 1 indicates ILP32, 2 indicats LP64. The mapping from +ABI integer to type sizes is hardwired into @code{libctf}: currently, we use +this to hardwire the size of pointers, function pointers, and enumerated types, + +This is a very kludgy corner of CTF and will probably be replaced with explicit +header fields to record this sort of thing in future. + +@node Limits of CTF +@section Limits of CTF +@cindex Limits + +The following limits are imposed by various aspects of CTF version 3: + +@table @code +@item CTF_MAX_TYPE +Maximum type identifier (maximum number of types accessible with parent and +child containers in use): 0xfffffffe +@item CTF_MAX_PTYPE +Maximum type identifier in a parent dictioanry: maximum number of types in any +one dictionary: 0x7fffffff +@item CTF_MAX_NAME +Maximum offset into a string table: 0x7fffffff +@item CTF_MAX_VLEN +Maximum number of members in a struct, union, or enum: maximum number of +function args: 0xffffff +@item CTF_MAX_SIZE +Maximum size of a @code{ctf_stype_t} in bytes before we fall back to +@code{ctf_type_t}: 0xfffffffe bytes +@end table + +Other maxima without associated macros: +@itemize +@item +Maximum value of an enumerated type: 2^32 +@item +Maximum size of an array element: 2^32 +@end itemize + +These maxima are generally considered to be too low, because C programs can and +do exceed them: they will be lifted in format v4. + +@node Index +@unnumbered Index + +@printindex cp + +@bye diff -pruN 16.3-5/libiberty/at-file.texi 16.3-5ubuntu1/libiberty/at-file.texi --- 16.3-5/libiberty/at-file.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libiberty/at-file.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,15 @@ +@c This file is designed to be included in manuals that use +@c expandargv. +@item @@@var{file} +Read command-line options from @var{file}. The options read are +inserted in place of the original @@@var{file} option. If @var{file} +does not exist, or cannot be read, then the option will be treated +literally, and not removed. + +Options in @var{file} are separated by whitespace. A whitespace +character may be included in an option by surrounding the entire +option in either single or double quotes. Any character (including a +backslash) may be included by prefixing the character to be included +with a backslash. The @var{file} may itself contain additional +@@@var{file} options; any such options will be processed recursively. diff -pruN 16.3-5/libiberty/copying-lib.texi 16.3-5ubuntu1/libiberty/copying-lib.texi --- 16.3-5/libiberty/copying-lib.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libiberty/copying-lib.texi 2025-04-20 17:22:06.000000000 +0000 @@ -1 +1,560 @@ +@node Library Copying +@appendixsec GNU LESSER GENERAL PUBLIC LICENSE +@cindex LGPL, Lesser General Public License +@center Version 2.1, February 1999 + +@display +Copyright @copyright{} 1991-2024 Free Software Foundation, Inc. +51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. + +[This is the first released version of the Lesser GPL. It also counts +as the successor of the GNU Library Public License, version 2, hence the +version number 2.1.] +@end display + +@appendixsubsec Preamble + + The licenses for most software are designed to take away your +freedom to share and change it. By contrast, the GNU General Public +Licenses are intended to guarantee your freedom to share and change +free software---to make sure the software is free for all its users. + + This license, the Lesser General Public License, applies to some +specially designated software---typically libraries---of the Free +Software Foundation and other authors who decide to use it. You can use +it too, but we suggest you first think carefully about whether this +license or the ordinary General Public License is the better strategy to +use in any particular case, based on the explanations below. + + When we speak of free software, we are referring to freedom of use, +not price. Our General Public Licenses are designed to make sure that +you have the freedom to distribute copies of free software (and charge +for this service if you wish); that you receive source code or can get +it if you want it; that you can change the software and use pieces of it +in new free programs; and that you are informed that you can do these +things. + + To protect your rights, we need to make restrictions that forbid +distributors to deny you these rights or to ask you to surrender these +rights. These restrictions translate to certain responsibilities for +you if you distribute copies of the library or if you modify it. + + For example, if you distribute copies of the library, whether gratis +or for a fee, you must give the recipients all the rights that we gave +you. You must make sure that they, too, receive or can get the source +code. If you link other code with the library, you must provide +complete object files to the recipients, so that they can relink them +with the library after making changes to the library and recompiling +it. And you must show them these terms so they know their rights. + + We protect your rights with a two-step method: (1) we copyright the +library, and (2) we offer you this license, which gives you legal +permission to copy, distribute and/or modify the library. + + To protect each distributor, we want to make it very clear that +there is no warranty for the free library. Also, if the library is +modified by someone else and passed on, the recipients should know +that what they have is not the original version, so that the original +author's reputation will not be affected by problems that might be +introduced by others. + + Finally, software patents pose a constant threat to the existence of +any free program. We wish to make sure that a company cannot +effectively restrict the users of a free program by obtaining a +restrictive license from a patent holder. Therefore, we insist that +any patent license obtained for a version of the library must be +consistent with the full freedom of use specified in this license. + + Most GNU software, including some libraries, is covered by the +ordinary GNU General Public License. This license, the GNU Lesser +General Public License, applies to certain designated libraries, and +is quite different from the ordinary General Public License. We use +this license for certain libraries in order to permit linking those +libraries into non-free programs. + + When a program is linked with a library, whether statically or using +a shared library, the combination of the two is legally speaking a +combined work, a derivative of the original library. The ordinary +General Public License therefore permits such linking only if the +entire combination fits its criteria of freedom. The Lesser General +Public License permits more lax criteria for linking other code with +the library. + + We call this license the @dfn{Lesser} General Public License because it +does @emph{Less} to protect the user's freedom than the ordinary General +Public License. It also provides other free software developers Less +of an advantage over competing non-free programs. These disadvantages +are the reason we use the ordinary General Public License for many +libraries. However, the Lesser license provides advantages in certain +special circumstances. + + For example, on rare occasions, there may be a special need to +encourage the widest possible use of a certain library, so that it becomes +a de-facto standard. To achieve this, non-free programs must be +allowed to use the library. A more frequent case is that a free +library does the same job as widely used non-free libraries. In this +case, there is little to gain by limiting the free library to free +software only, so we use the Lesser General Public License. + + In other cases, permission to use a particular library in non-free +programs enables a greater number of people to use a large body of +free software. For example, permission to use the GNU C Library in +non-free programs enables many more people to use the whole GNU +operating system, as well as its variant, the GNU/Linux operating +system. + + Although the Lesser General Public License is Less protective of the +users' freedom, it does ensure that the user of a program that is +linked with the Library has the freedom and the wherewithal to run +that program using a modified version of the Library. + + The precise terms and conditions for copying, distribution and +modification follow. Pay close attention to the difference between a +``work based on the library'' and a ``work that uses the library''. The +former contains code derived from the library, whereas the latter must +be combined with the library in order to run. + +@iftex +@appendixsubsec TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end iftex +@ifinfo +@center GNU LESSER GENERAL PUBLIC LICENSE +@center TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION +@end ifinfo + +@enumerate 0 +@item +This License Agreement applies to any software library or other program +which contains a notice placed by the copyright holder or other +authorized party saying it may be distributed under the terms of this +Lesser General Public License (also called ``this License''). Each +licensee is addressed as ``you''. + + A ``library'' means a collection of software functions and/or data +prepared so as to be conveniently linked with application programs +(which use some of those functions and data) to form executables. + + The ``Library'', below, refers to any such software library or work +which has been distributed under these terms. A ``work based on the +Library'' means either the Library or any derivative work under +copyright law: that is to say, a work containing the Library or a +portion of it, either verbatim or with modifications and/or translated +straightforwardly into another language. (Hereinafter, translation is +included without limitation in the term ``modification''.) + + ``Source code'' for a work means the preferred form of the work for +making modifications to it. For a library, complete source code means +all the source code for all modules it contains, plus any associated +interface definition files, plus the scripts used to control compilation +and installation of the library. + + Activities other than copying, distribution and modification are not +covered by this License; they are outside its scope. The act of +running a program using the Library is not restricted, and output from +such a program is covered only if its contents constitute a work based +on the Library (independent of the use of the Library in a tool for +writing it). Whether that is true depends on what the Library does +and what the program that uses the Library does. + +@item +You may copy and distribute verbatim copies of the Library's +complete source code as you receive it, in any medium, provided that +you conspicuously and appropriately publish on each copy an +appropriate copyright notice and disclaimer of warranty; keep intact +all the notices that refer to this License and to the absence of any +warranty; and distribute a copy of this License along with the +Library. + + You may charge a fee for the physical act of transferring a copy, +and you may at your option offer warranty protection in exchange for a +fee. + +@item +You may modify your copy or copies of the Library or any portion +of it, thus forming a work based on the Library, and copy and +distribute such modifications or work under the terms of Section 1 +above, provided that you also meet all of these conditions: + +@enumerate a +@item +The modified work must itself be a software library. + +@item +You must cause the files modified to carry prominent notices +stating that you changed the files and the date of any change. + +@item +You must cause the whole of the work to be licensed at no +charge to all third parties under the terms of this License. + +@item +If a facility in the modified Library refers to a function or a +table of data to be supplied by an application program that uses +the facility, other than as an argument passed when the facility +is invoked, then you must make a good faith effort to ensure that, +in the event an application does not supply such function or +table, the facility still operates, and performs whatever part of +its purpose remains meaningful. + +(For example, a function in a library to compute square roots has +a purpose that is entirely well-defined independent of the +application. Therefore, Subsection 2d requires that any +application-supplied function or table used by this function must +be optional: if the application does not supply it, the square +root function must still compute square roots.) +@end enumerate + +These requirements apply to the modified work as a whole. If +identifiable sections of that work are not derived from the Library, +and can be reasonably considered independent and separate works in +themselves, then this License, and its terms, do not apply to those +sections when you distribute them as separate works. But when you +distribute the same sections as part of a whole which is a work based +on the Library, the distribution of the whole must be on the terms of +this License, whose permissions for other licensees extend to the +entire whole, and thus to each and every part regardless of who wrote +it. + +Thus, it is not the intent of this section to claim rights or contest +your rights to work written entirely by you; rather, the intent is to +exercise the right to control the distribution of derivative or +collective works based on the Library. + +In addition, mere aggregation of another work not based on the Library +with the Library (or with a work based on the Library) on a volume of +a storage or distribution medium does not bring the other work under +the scope of this License. + +@item +You may opt to apply the terms of the ordinary GNU General Public +License instead of this License to a given copy of the Library. To do +this, you must alter all the notices that refer to this License, so +that they refer to the ordinary GNU General Public License, version 2, +instead of to this License. (If a newer version than version 2 of the +ordinary GNU General Public License has appeared, then you can specify +that version instead if you wish.) Do not make any other change in +these notices. + + Once this change is made in a given copy, it is irreversible for +that copy, so the ordinary GNU General Public License applies to all +subsequent copies and derivative works made from that copy. + + This option is useful when you wish to copy part of the code of +the Library into a program that is not a library. + +@item +You may copy and distribute the Library (or a portion or +derivative of it, under Section 2) in object code or executable form +under the terms of Sections 1 and 2 above provided that you accompany +it with the complete corresponding machine-readable source code, which +must be distributed under the terms of Sections 1 and 2 above on a +medium customarily used for software interchange. + + If distribution of object code is made by offering access to copy +from a designated place, then offering equivalent access to copy the +source code from the same place satisfies the requirement to +distribute the source code, even though third parties are not +compelled to copy the source along with the object code. + +@item +A program that contains no derivative of any portion of the +Library, but is designed to work with the Library by being compiled or +linked with it, is called a ``work that uses the Library''. Such a +work, in isolation, is not a derivative work of the Library, and +therefore falls outside the scope of this License. + + However, linking a ``work that uses the Library'' with the Library +creates an executable that is a derivative of the Library (because it +contains portions of the Library), rather than a ``work that uses the +library''. The executable is therefore covered by this License. +Section 6 states terms for distribution of such executables. + + When a ``work that uses the Library'' uses material from a header file +that is part of the Library, the object code for the work may be a +derivative work of the Library even though the source code is not. +Whether this is true is especially significant if the work can be +linked without the Library, or if the work is itself a library. The +threshold for this to be true is not precisely defined by law. + + If such an object file uses only numerical parameters, data +structure layouts and accessors, and small macros and small inline +functions (ten lines or less in length), then the use of the object +file is unrestricted, regardless of whether it is legally a derivative +work. (Executables containing this object code plus portions of the +Library will still fall under Section 6.) + + Otherwise, if the work is a derivative of the Library, you may +distribute the object code for the work under the terms of Section 6. +Any executables containing that work also fall under Section 6, +whether or not they are linked directly with the Library itself. + +@item +As an exception to the Sections above, you may also combine or +link a ``work that uses the Library'' with the Library to produce a +work containing portions of the Library, and distribute that work +under terms of your choice, provided that the terms permit +modification of the work for the customer's own use and reverse +engineering for debugging such modifications. + + You must give prominent notice with each copy of the work that the +Library is used in it and that the Library and its use are covered by +this License. You must supply a copy of this License. If the work +during execution displays copyright notices, you must include the +copyright notice for the Library among them, as well as a reference +directing the user to the copy of this License. Also, you must do one +of these things: + +@enumerate a +@item +Accompany the work with the complete corresponding +machine-readable source code for the Library including whatever +changes were used in the work (which must be distributed under +Sections 1 and 2 above); and, if the work is an executable linked +with the Library, with the complete machine-readable ``work that +uses the Library'', as object code and/or source code, so that the +user can modify the Library and then relink to produce a modified +executable containing the modified Library. (It is understood +that the user who changes the contents of definitions files in the +Library will not necessarily be able to recompile the application +to use the modified definitions.) + +@item +Use a suitable shared library mechanism for linking with the Library. A +suitable mechanism is one that (1) uses at run time a copy of the +library already present on the user's computer system, rather than +copying library functions into the executable, and (2) will operate +properly with a modified version of the library, if the user installs +one, as long as the modified version is interface-compatible with the +version that the work was made with. + +@item +Accompany the work with a written offer, valid for at +least three years, to give the same user the materials +specified in Subsection 6a, above, for a charge no more +than the cost of performing this distribution. + +@item +If distribution of the work is made by offering access to copy +from a designated place, offer equivalent access to copy the above +specified materials from the same place. + +@item +Verify that the user has already received a copy of these +materials or that you have already sent this user a copy. +@end enumerate + + For an executable, the required form of the ``work that uses the +Library'' must include any data and utility programs needed for +reproducing the executable from it. However, as a special exception, +the materials to be distributed need not include anything that is +normally distributed (in either source or binary form) with the major +components (compiler, kernel, and so on) of the operating system on +which the executable runs, unless that component itself accompanies the +executable. + + It may happen that this requirement contradicts the license +restrictions of other proprietary libraries that do not normally +accompany the operating system. Such a contradiction means you cannot +use both them and the Library together in an executable that you +distribute. + +@item +You may place library facilities that are a work based on the +Library side-by-side in a single library together with other library +facilities not covered by this License, and distribute such a combined +library, provided that the separate distribution of the work based on +the Library and of the other library facilities is otherwise +permitted, and provided that you do these two things: + +@enumerate a +@item +Accompany the combined library with a copy of the same work +based on the Library, uncombined with any other library +facilities. This must be distributed under the terms of the +Sections above. + +@item +Give prominent notice with the combined library of the fact +that part of it is a work based on the Library, and explaining +where to find the accompanying uncombined form of the same work. +@end enumerate + +@item +You may not copy, modify, sublicense, link with, or distribute +the Library except as expressly provided under this License. Any +attempt otherwise to copy, modify, sublicense, link with, or +distribute the Library is void, and will automatically terminate your +rights under this License. However, parties who have received copies, +or rights, from you under this License will not have their licenses +terminated so long as such parties remain in full compliance. + +@item +You are not required to accept this License, since you have not +signed it. However, nothing else grants you permission to modify or +distribute the Library or its derivative works. These actions are +prohibited by law if you do not accept this License. Therefore, by +modifying or distributing the Library (or any work based on the +Library), you indicate your acceptance of this License to do so, and +all its terms and conditions for copying, distributing or modifying +the Library or works based on it. + +@item +Each time you redistribute the Library (or any work based on the +Library), the recipient automatically receives a license from the +original licensor to copy, distribute, link with or modify the Library +subject to these terms and conditions. You may not impose any further +restrictions on the recipients' exercise of the rights granted herein. +You are not responsible for enforcing compliance by third parties with +this License. + +@item +If, as a consequence of a court judgment or allegation of patent +infringement or for any other reason (not limited to patent issues), +conditions are imposed on you (whether by court order, agreement or +otherwise) that contradict the conditions of this License, they do not +excuse you from the conditions of this License. If you cannot +distribute so as to satisfy simultaneously your obligations under this +License and any other pertinent obligations, then as a consequence you +may not distribute the Library at all. For example, if a patent +license would not permit royalty-free redistribution of the Library by +all those who receive copies directly or indirectly through you, then +the only way you could satisfy both it and this License would be to +refrain entirely from distribution of the Library. + +If any portion of this section is held invalid or unenforceable under any +particular circumstance, the balance of the section is intended to apply, +and the section as a whole is intended to apply in other circumstances. + +It is not the purpose of this section to induce you to infringe any +patents or other property right claims or to contest validity of any +such claims; this section has the sole purpose of protecting the +integrity of the free software distribution system which is +implemented by public license practices. Many people have made +generous contributions to the wide range of software distributed +through that system in reliance on consistent application of that +system; it is up to the author/donor to decide if he or she is willing +to distribute software through any other system and a licensee cannot +impose that choice. + +This section is intended to make thoroughly clear what is believed to +be a consequence of the rest of this License. + +@item +If the distribution and/or use of the Library is restricted in +certain countries either by patents or by copyrighted interfaces, the +original copyright holder who places the Library under this License may add +an explicit geographical distribution limitation excluding those countries, +so that distribution is permitted only in or among countries not thus +excluded. In such case, this License incorporates the limitation as if +written in the body of this License. + +@item +The Free Software Foundation may publish revised and/or new +versions of the Lesser General Public License from time to time. +Such new versions will be similar in spirit to the present version, +but may differ in detail to address new problems or concerns. + +Each version is given a distinguishing version number. If the Library +specifies a version number of this License which applies to it and +``any later version'', you have the option of following the terms and +conditions either of that version or of any later version published by +the Free Software Foundation. If the Library does not specify a +license version number, you may choose any version ever published by +the Free Software Foundation. + +@item +If you wish to incorporate parts of the Library into other free +programs whose distribution conditions are incompatible with these, +write to the author to ask for permission. For software which is +copyrighted by the Free Software Foundation, write to the Free +Software Foundation; we sometimes make exceptions for this. Our +decision will be guided by the two goals of preserving the free status +of all derivatives of our free software and of promoting the sharing +and reuse of software generally. + +@center NO WARRANTY + +@item +BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO +WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. +EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR +OTHER PARTIES PROVIDE THE LIBRARY ``AS IS'' WITHOUT WARRANTY OF ANY +KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE +LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME +THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. + +@item +IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN +WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY +AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU +FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR +CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE +LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING +RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A +FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF +SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH +DAMAGES. +@end enumerate + +@iftex +@heading END OF TERMS AND CONDITIONS +@end iftex +@ifinfo +@center END OF TERMS AND CONDITIONS +@end ifinfo + +@page +@appendixsubsec How to Apply These Terms to Your New Libraries + + If you develop a new library, and you want it to be of the greatest +possible use to the public, we recommend making it free software that +everyone can redistribute and change. You can do so by permitting +redistribution under these terms (or, alternatively, under the terms of the +ordinary General Public License). + + To apply these terms, attach the following notices to the library. It is +safest to attach them to the start of each source file to most effectively +convey the exclusion of warranty; and each file should have at least the +``copyright'' line and a pointer to where the full notice is found. + +@smallexample +@var{one line to give the library's name and an idea of what it does.} +Copyright (C) @var{year} @var{name of author} + +This library is free software; you can redistribute it and/or modify it +under the terms of the GNU Lesser General Public License as published by +the Free Software Foundation; either version 2.1 of the License, or (at +your option) any later version. + +This library is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +Lesser General Public License for more details. + +You should have received a copy of the GNU Lesser General Public +License along with this library; if not, write to the Free Software +Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, +USA. +@end smallexample + +Also add information on how to contact you by electronic and paper mail. + +You should also get your employer (if you work as a programmer) or your +school, if any, to sign a ``copyright disclaimer'' for the library, if +necessary. Here is a sample; alter the names: + +@smallexample +Yoyodyne, Inc., hereby disclaims all copyright interest in the library +`Frob' (a library for tweaking knobs) written by James Random Hacker. + +@var{signature of Ty Coon}, 1 April 1990 +Ty Coon, President of Vice +@end smallexample + +That's all there is to it! diff -pruN 16.3-5/libiberty/functions.texi 16.3-5ubuntu1/libiberty/functions.texi --- 16.3-5/libiberty/functions.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libiberty/functions.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,2063 @@ +@c Automatically generated from *.c and others (the comments before +@c each entry tell you which file and where in that file). DO NOT EDIT! +@c Edit the *.c files, configure with --enable-maintainer-mode, +@c run 'make stamp-functions' and gather-docs will build a new copy. + +@c alloca.c:26 +@deftypefn Replacement void* alloca (size_t @var{size}) + +This function allocates memory which will be automatically reclaimed +after the procedure exits. The @libib{} implementation does not free +the memory immediately but will do so eventually during subsequent +calls to this function. Memory is allocated using @code{xmalloc} under +normal circumstances. + +The header file @file{alloca-conf.h} can be used in conjunction with the +GNU Autoconf test @code{AC_FUNC_ALLOCA} to test for and properly make +available this function. The @code{AC_FUNC_ALLOCA} test requires that +client code use a block of preprocessor code to be safe (see the Autoconf +manual for more); this header incorporates that logic and more, including +the possibility of a GCC built-in function. + +@end deftypefn + +@c asprintf.c:32 +@deftypefn Extension int asprintf (char **@var{resptr}, const char *@var{format}, ...) + +Like @code{sprintf}, but instead of passing a pointer to a buffer, you +pass a pointer to a pointer. This function will compute the size of +the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{sprintf} would return. If memory could +not be allocated, minus one is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + +@c atexit.c:6 +@deftypefn Supplemental int atexit (void (*@var{f})()) + +Causes function @var{f} to be called at exit. Returns 0. + +@end deftypefn + +@c basename.c:6 +@deftypefn Supplemental char* basename (const char *@var{name}) + +Returns a pointer to the last component of pathname @var{name}. +Behavior is undefined if the pathname ends in a directory separator. + +@end deftypefn + +@c bcmp.c:6 +@deftypefn Supplemental int bcmp (char *@var{x}, char *@var{y}, int @var{count}) + +Compares the first @var{count} bytes of two areas of memory. Returns +zero if they are the same, nonzero otherwise. Returns zero if +@var{count} is zero. A nonzero result only indicates a difference, +it does not indicate any sorting order (say, by having a positive +result mean @var{x} sorts before @var{y}). + +@end deftypefn + +@c bcopy.c:3 +@deftypefn Supplemental void bcopy (char *@var{in}, char *@var{out}, int @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. The use of @code{bcopy} is deprecated in new programs. + +@end deftypefn + +@c bsearch.c:33 +@deftypefn Supplemental void* bsearch (const void *@var{key}, @ + const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ + int (*@var{compar})(const void *, const void *)) + +Performs a search over an array of @var{nmemb} elements pointed to by +@var{base} for a member that matches the object pointed to by @var{key}. +The size of each member is specified by @var{size}. The array contents +should be sorted in ascending order according to the @var{compar} +comparison function. This routine should take two arguments pointing to +the @var{key} and to an array member, in that order, and should return an +integer less than, equal to, or greater than zero if the @var{key} object +is respectively less than, matching, or greater than the array member. + +@end deftypefn + +@c bsearch_r.c:33 +@deftypefn Supplemental void* bsearch_r (const void *@var{key}, @ + const void *@var{base}, size_t @var{nmemb}, size_t @var{size}, @ + int (*@var{compar})(const void *, const void *, void *), void *@var{arg}) + +Performs a search over an array of @var{nmemb} elements pointed to by +@var{base} for a member that matches the object pointed to by @var{key}. +The size of each member is specified by @var{size}. The array contents +should be sorted in ascending order according to the @var{compar} +comparison function. This routine should take three arguments: the first +two point to the @var{key} and to an array member, and the last is passed +down unchanged from @code{bsearch_r}'s last argument. It should return an +integer less than, equal to, or greater than zero if the @var{key} object +is respectively less than, matching, or greater than the array member. + +@end deftypefn + +@c argv.c:138 +@deftypefn Extension char** buildargv (char *@var{sp}) + +Given a pointer to a string, parse the string extracting fields +separated by whitespace and optionally enclosed within either single +or double quotes (which are stripped off), and build a vector of +pointers to copies of the string for each field. The input string +remains unchanged. The last element of the vector is followed by a +@code{NULL} element. + +All of the memory for the pointer array and copies of the string +is obtained from @code{xmalloc}. All of the memory can be returned to the +system with the single function call @code{freeargv}, which takes the +returned result of @code{buildargv}, as it's argument. + +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if @var{sp} is @code{NULL} or if there is insufficient +memory to complete building the argument vector. + +If the input is a null string (as opposed to a @code{NULL} pointer), +then buildarg returns an argument vector that has one arg, a null +string. + +@end deftypefn + +@c bzero.c:6 +@deftypefn Supplemental void bzero (char *@var{mem}, int @var{count}) + +Zeros @var{count} bytes starting at @var{mem}. Use of this function +is deprecated in favor of @code{memset}. + +@end deftypefn + +@c calloc.c:6 +@deftypefn Supplemental void* calloc (size_t @var{nelem}, size_t @var{elsize}) + +Uses @code{malloc} to allocate storage for @var{nelem} objects of +@var{elsize} bytes each, then zeros the memory. + +@end deftypefn + +@c filename_cmp.c:201 +@deftypefn Extension int canonical_filename_eq (const char *@var{a}, const char *@var{b}) + +Return non-zero if file names @var{a} and @var{b} are equivalent. +This function compares the canonical versions of the filenames as returned by +@code{lrealpath()}, so that so that different file names pointing to the same +underlying file are treated as being identical. + +@end deftypefn + +@c choose-temp.c:45 +@deftypefn Extension char* choose_temp_base (void) + +Return a prefix for temporary file names or @code{NULL} if unable to +find one. The current directory is chosen if all else fails so the +program is exited if a temporary directory can't be found (@code{mktemp} +fails). The buffer for the result is obtained with @code{xmalloc}. + +This function is provided for backwards compatibility only. Its use is +not recommended. + +@end deftypefn + +@c make-temp-file.c:95 +@deftypefn Replacement const char* choose_tmpdir () + +Returns a pointer to a directory path suitable for creating temporary +files in. + +@end deftypefn + +@c clock.c:27 +@deftypefn Supplemental long clock (void) + +Returns an approximation of the CPU time used by the process as a +@code{clock_t}; divide this number by @samp{CLOCKS_PER_SEC} to get the +number of seconds used. + +@end deftypefn + +@c concat.c:24 +@deftypefn Extension char* concat (const char *@var{s1}, const char *@var{s2}, @ + @dots{}, @code{NULL}) + +Concatenate zero or more of strings and return the result in freshly +@code{xmalloc}ed memory. The argument list is terminated by the first +@code{NULL} pointer encountered. Pointers to empty strings are ignored. + +@end deftypefn + +@c argv.c:495 +@deftypefn Extension int countargv (char * const *@var{argv}) + +Return the number of elements in @var{argv}. +Returns zero if @var{argv} is NULL. + +@end deftypefn + +@c crc32.c:140 +@deftypefn Extension {unsigned int} crc32 (const unsigned char *@var{buf}, @ + int @var{len}, unsigned int @var{init}) + +Compute the 32-bit CRC of @var{buf} which has length @var{len}. The +starting value is @var{init}; this may be used to compute the CRC of +data split across multiple buffers by passing the return value of each +call as the @var{init} parameter of the next. + +This is used by the @command{gdb} remote protocol for the @samp{qCRC} +command. In order to get the same results as gdb for a block of data, +you must pass the first CRC parameter as @code{0xffffffff}. + +This CRC can be specified as: + + Width : 32 + Poly : 0x04c11db7 + Init : parameter, typically 0xffffffff + RefIn : false + RefOut : false + XorOut : 0 + +This differs from the "standard" CRC-32 algorithm in that the values +are not reflected, and there is no final XOR value. These differences +make it easy to compose the values of multiple blocks. + +@end deftypefn + +@c argv.c:59 +@deftypefn Extension char** dupargv (char * const *@var{vector}) + +Duplicate an argument vector. Simply scans through @var{vector}, +duplicating each argument until the terminating @code{NULL} is found. +Returns a pointer to the argument vector if successful. Returns +@code{NULL} if there is insufficient memory to complete building the +argument vector. + +@end deftypefn + +@c strerror.c:572 +@deftypefn Extension int errno_max (void) + +Returns the maximum @code{errno} value for which a corresponding +symbolic name or message is available. Note that in the case where we +use the @code{sys_errlist} supplied by the system, it is possible for +there to be more symbolic names than messages, or vice versa. In +fact, the manual page for @code{perror(3C)} explicitly warns that one +should check the size of the table (@code{sys_nerr}) before indexing +it, since new error codes may be added to the system before they are +added to the table. Thus @code{sys_nerr} might be smaller than value +implied by the largest @code{errno} value defined in @code{}. + +We return the maximum value that can be used to obtain a meaningful +symbolic name or message. + +@end deftypefn + +@c argv.c:352 +@deftypefn Extension void expandargv (int *@var{argcp}, char ***@var{argvp}) + +The @var{argcp} and @code{argvp} arguments are pointers to the usual +@code{argc} and @code{argv} arguments to @code{main}. This function +looks for arguments that begin with the character @samp{@@}. Any such +arguments are interpreted as ``response files''. The contents of the +response file are interpreted as additional command line options. In +particular, the file is separated into whitespace-separated strings; +each such string is taken as a command-line option. The new options +are inserted in place of the option naming the response file, and +@code{*argcp} and @code{*argvp} will be updated. If the value of +@code{*argvp} is modified by this function, then the new value has +been dynamically allocated and can be deallocated by the caller with +@code{freeargv}. However, most callers will simply call +@code{expandargv} near the beginning of @code{main} and allow the +operating system to free the memory when the program exits. + +@end deftypefn + +@c fdmatch.c:23 +@deftypefn Extension int fdmatch (int @var{fd1}, int @var{fd2}) + +Check to see if two open file descriptors refer to the same file. +This is useful, for example, when we have an open file descriptor for +an unnamed file, and the name of a file that we believe to correspond +to that fd. This can happen when we are exec'd with an already open +file (@code{stdout} for example) or from the SVR4 @file{/proc} calls +that return open file descriptors for mapped address spaces. All we +have to do is open the file by name and check the two file descriptors +for a match, which is done by comparing major and minor device numbers +and inode numbers. + +@end deftypefn + +@c fopen_unlocked.c:49 +@deftypefn Extension {FILE *} fdopen_unlocked (int @var{fildes}, @ + const char * @var{mode}) + +Opens and returns a @code{FILE} pointer via @code{fdopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c ffs.c:3 +@deftypefn Supplemental int ffs (int @var{valu}) + +Find the first (least significant) bit set in @var{valu}. Bits are +numbered from right to left, starting with bit 1 (corresponding to the +value 1). If @var{valu} is zero, zero is returned. + +@end deftypefn + +@c filename_cmp.c:37 +@deftypefn Extension int filename_cmp (const char *@var{s1}, const char *@var{s2}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent. +If not equivalent, the returned value is similar to what @code{strcmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + +@c filename_cmp.c:183 +@deftypefn Extension int filename_eq (const void *@var{s1}, const void *@var{s2}) + +Return non-zero if file names @var{s1} and @var{s2} are equivalent. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:152 +@deftypefn Extension hashval_t filename_hash (const void *@var{s}) + +Return the hash value for file name @var{s} that will be compared +using filename_cmp. +This function is for use with hashtab.c hash tables. + +@end deftypefn + +@c filename_cmp.c:94 +@deftypefn Extension int filename_ncmp (const char *@var{s1}, const char *@var{s2}, size_t @var{n}) + +Return zero if the two file names @var{s1} and @var{s2} are equivalent +in range @var{n}. +If not equivalent, the returned value is similar to what @code{strncmp} +would return. In other words, it returns a negative value if @var{s1} +is less than @var{s2}, or a positive value if @var{s2} is greater than +@var{s2}. + +This function does not normalize file names. As a result, this function +will treat filenames that are spelled differently as different even in +the case when the two filenames point to the same underlying file. +However, it does handle the fact that on DOS-like file systems, forward +and backward slashes are equal. + +@end deftypefn + +@c fnmatch.txh:1 +@deftypefn Replacement int fnmatch (const char *@var{pattern}, @ + const char *@var{string}, int @var{flags}) + +Matches @var{string} against @var{pattern}, returning zero if it +matches, @code{FNM_NOMATCH} if not. @var{pattern} may contain the +wildcards @code{?} to match any one character, @code{*} to match any +zero or more characters, or a set of alternate characters in square +brackets, like @samp{[a-gt8]}, which match one character (@code{a} +through @code{g}, or @code{t}, or @code{8}, in this example) if that one +character is in the set. A set may be inverted (i.e., match anything +except what's in the set) by giving @code{^} or @code{!} as the first +character in the set. To include those characters in the set, list them +as anything other than the first character of the set. To include a +dash in the set, list it last in the set. A backslash character makes +the following character not special, so for example you could match +against a literal asterisk with @samp{\*}. To match a literal +backslash, use @samp{\\}. + +@code{flags} controls various aspects of the matching process, and is a +boolean OR of zero or more of the following values (defined in +@code{}): + +@table @code + +@item FNM_PATHNAME +@itemx FNM_FILE_NAME +@var{string} is assumed to be a path name. No wildcard will ever match +@code{/}. + +@item FNM_NOESCAPE +Do not interpret backslashes as quoting the following special character. + +@item FNM_PERIOD +A leading period (at the beginning of @var{string}, or if +@code{FNM_PATHNAME} after a slash) is not matched by @code{*} or +@code{?} but must be matched explicitly. + +@item FNM_LEADING_DIR +Means that @var{string} also matches @var{pattern} if some initial part +of @var{string} matches, and is followed by @code{/} and zero or more +characters. For example, @samp{foo*} would match either @samp{foobar} +or @samp{foobar/grill}. + +@item FNM_CASEFOLD +Ignores case when performing the comparison. + +@end table + +@end deftypefn + +@c fopen_unlocked.c:39 +@deftypefn Extension {FILE *} fopen_unlocked (const char *@var{path}, @ + const char * @var{mode}) + +Opens and returns a @code{FILE} pointer via @code{fopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c argv.c:93 +@deftypefn Extension void freeargv (char **@var{vector}) + +Free an argument vector that was built using @code{buildargv}. Simply +scans through @var{vector}, freeing the memory for each argument until +the terminating @code{NULL} is found, and then frees @var{vector} +itself. + +@end deftypefn + +@c fopen_unlocked.c:59 +@deftypefn Extension {FILE *} freopen_unlocked (const char * @var{path}, @ + const char * @var{mode}, FILE * @var{stream}) + +Opens and returns a @code{FILE} pointer via @code{freopen}. If the +operating system supports it, ensure that the stream is setup to avoid +any multi-threaded locking. Otherwise return the @code{FILE} pointer +unchanged. + +@end deftypefn + +@c getruntime.c:86 +@deftypefn Replacement long get_run_time (void) + +Returns the time used so far, in microseconds. If possible, this is +the time used by this process, else it is the elapsed time since the +process started. + +@end deftypefn + +@c getcwd.c:6 +@deftypefn Supplemental char* getcwd (char *@var{pathname}, int @var{len}) + +Copy the absolute pathname for the current working directory into +@var{pathname}, which is assumed to point to a buffer of at least +@var{len} bytes, and return a pointer to the buffer. If the current +directory's path doesn't fit in @var{len} characters, the result is +@code{NULL} and @code{errno} is set. If @var{pathname} is a null pointer, +@code{getcwd} will obtain @var{len} bytes of space using +@code{malloc}. + +@end deftypefn + +@c getpagesize.c:5 +@deftypefn Supplemental int getpagesize (void) + +Returns the number of bytes in a page of memory. This is the +granularity of many of the system memory management routines. No +guarantee is made as to whether or not it is the same as the basic +memory management hardware page size. + +@end deftypefn + +@c getpwd.c:5 +@deftypefn Supplemental char* getpwd (void) + +Returns the current working directory. This implementation caches the +result on the assumption that the process will not call @code{chdir} +between calls to @code{getpwd}. + +@end deftypefn + +@c gettimeofday.c:12 +@deftypefn Supplemental int gettimeofday (struct timeval *@var{tp}, void *@var{tz}) + +Writes the current time to @var{tp}. This implementation requires +that @var{tz} be NULL. Returns 0 on success, -1 on failure. + +@end deftypefn + +@c hex.c:33 +@deftypefn Extension void hex_init (void) + +Initializes the array mapping the current character set to +corresponding hex values. This function must be called before any +call to @code{hex_p} or @code{hex_value}. If you fail to call it, a +default ASCII-based table will normally be used on ASCII systems. + +@end deftypefn + +@c hex.c:42 +@deftypefn Extension int hex_p (int @var{c}) + +Evaluates to non-zero if the given character is a valid hex character, +or zero if it is not. Note that the value you pass will be cast to +@code{unsigned char} within the macro. + +@end deftypefn + +@c hex.c:50 +@deftypefn Extension {unsigned int} hex_value (int @var{c}) + +Returns the numeric equivalent of the given character when interpreted +as a hexadecimal digit. The result is undefined if you pass an +invalid hex digit. Note that the value you pass will be cast to +@code{unsigned char} within the macro. + +The @code{hex_value} macro returns @code{unsigned int}, rather than +signed @code{int}, to make it easier to use in parsing addresses from +hex dump files: a signed @code{int} would be sign-extended when +converted to a wider unsigned type --- like @code{bfd_vma}, on some +systems. + +@end deftypefn + +@c safe-ctype.c:24 +@defvr Extension HOST_CHARSET +This macro indicates the basic character set and encoding used by the +host: more precisely, the encoding used for character constants in +preprocessor @samp{#if} statements (the C "execution character set"). +It is defined by @file{safe-ctype.h}, and will be an integer constant +with one of the following values: + +@ftable @code +@item HOST_CHARSET_UNKNOWN +The host character set is unknown - that is, not one of the next two +possibilities. + +@item HOST_CHARSET_ASCII +The host character set is ASCII. + +@item HOST_CHARSET_EBCDIC +The host character set is some variant of EBCDIC. (Only one of the +nineteen EBCDIC varying characters is tested; exercise caution.) +@end ftable +@end defvr + +@c hashtab.c:327 +@deftypefn Supplemental htab_t htab_create_typed_alloc (size_t @var{size}, @ +htab_hash @var{hash_f}, htab_eq @var{eq_f}, htab_del @var{del_f}, @ +htab_alloc @var{alloc_tab_f}, htab_alloc @var{alloc_f}, @ +htab_free @var{free_f}) + +This function creates a hash table that uses two different allocators +@var{alloc_tab_f} and @var{alloc_f} to use for allocating the table itself +and its entries respectively. This is useful when variables of different +types need to be allocated with different allocators. + +The created hash table is slightly larger than @var{size} and it is +initially empty (all the hash table entries are @code{HTAB_EMPTY_ENTRY}). +The function returns the created hash table, or @code{NULL} if memory +allocation fails. + +@end deftypefn + +@c index.c:5 +@deftypefn Supplemental char* index (char *@var{s}, int @var{c}) + +Returns a pointer to the first occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. The use of @code{index} is +deprecated in new programs in favor of @code{strchr}. + +@end deftypefn + +@c insque.c:6 +@deftypefn Supplemental void insque (struct qelem *@var{elem}, @ + struct qelem *@var{pred}) +@deftypefnx Supplemental void remque (struct qelem *@var{elem}) + +Routines to manipulate queues built from doubly linked lists. The +@code{insque} routine inserts @var{elem} in the queue immediately +after @var{pred}. The @code{remque} routine removes @var{elem} from +its containing queue. These routines expect to be passed pointers to +structures which have as their first members a forward pointer and a +back pointer, like this prototype (although no prototype is provided): + +@example +struct qelem @{ + struct qelem *q_forw; + struct qelem *q_back; + char q_data[]; +@}; +@end example + +@end deftypefn + +@c safe-ctype.c:45 +@deffn Extension ISALPHA (@var{c}) +@deffnx Extension ISALNUM (@var{c}) +@deffnx Extension ISBLANK (@var{c}) +@deffnx Extension ISCNTRL (@var{c}) +@deffnx Extension ISDIGIT (@var{c}) +@deffnx Extension ISGRAPH (@var{c}) +@deffnx Extension ISLOWER (@var{c}) +@deffnx Extension ISPRINT (@var{c}) +@deffnx Extension ISPUNCT (@var{c}) +@deffnx Extension ISSPACE (@var{c}) +@deffnx Extension ISUPPER (@var{c}) +@deffnx Extension ISXDIGIT (@var{c}) + +These twelve macros are defined by @file{safe-ctype.h}. Each has the +same meaning as the corresponding macro (with name in lowercase) +defined by the standard header @file{ctype.h}. For example, +@code{ISALPHA} returns true for alphabetic characters and false for +others. However, there are two differences between these macros and +those provided by @file{ctype.h}: + +@itemize @bullet +@item These macros are guaranteed to have well-defined behavior for all +values representable by @code{signed char} and @code{unsigned char}, and +for @code{EOF}. + +@item These macros ignore the current locale; they are true for these +fixed sets of characters: +@multitable {@code{XDIGIT}} {yada yada yada yada yada yada yada yada} +@item @code{ALPHA} @tab @kbd{A-Za-z} +@item @code{ALNUM} @tab @kbd{A-Za-z0-9} +@item @code{BLANK} @tab @kbd{space tab} +@item @code{CNTRL} @tab @code{!PRINT} +@item @code{DIGIT} @tab @kbd{0-9} +@item @code{GRAPH} @tab @code{ALNUM || PUNCT} +@item @code{LOWER} @tab @kbd{a-z} +@item @code{PRINT} @tab @code{GRAPH ||} @kbd{space} +@item @code{PUNCT} @tab @kbd{`~!@@#$%^&*()_-=+[@{]@}\|;:'",<.>/?} +@item @code{SPACE} @tab @kbd{space tab \n \r \f \v} +@item @code{UPPER} @tab @kbd{A-Z} +@item @code{XDIGIT} @tab @kbd{0-9A-Fa-f} +@end multitable + +Note that, if the host character set is ASCII or a superset thereof, +all these macros will return false for all values of @code{char} outside +the range of 7-bit ASCII. In particular, both ISPRINT and ISCNTRL return +false for characters with numeric values from 128 to 255. +@end itemize +@end deffn + +@c safe-ctype.c:94 +@deffn Extension ISIDNUM (@var{c}) +@deffnx Extension ISIDST (@var{c}) +@deffnx Extension IS_VSPACE (@var{c}) +@deffnx Extension IS_NVSPACE (@var{c}) +@deffnx Extension IS_SPACE_OR_NUL (@var{c}) +@deffnx Extension IS_ISOBASIC (@var{c}) +These six macros are defined by @file{safe-ctype.h} and provide +additional character classes which are useful when doing lexical +analysis of C or similar languages. They are true for the following +sets of characters: + +@multitable {@code{SPACE_OR_NUL}} {yada yada yada yada yada yada yada yada} +@item @code{IDNUM} @tab @kbd{A-Za-z0-9_} +@item @code{IDST} @tab @kbd{A-Za-z_} +@item @code{VSPACE} @tab @kbd{\r \n} +@item @code{NVSPACE} @tab @kbd{space tab \f \v \0} +@item @code{SPACE_OR_NUL} @tab @code{VSPACE || NVSPACE} +@item @code{ISOBASIC} @tab @code{VSPACE || NVSPACE || PRINT} +@end multitable +@end deffn + +@c lbasename.c:23 +@deftypefn Replacement {const char*} lbasename (const char *@var{name}) + +Given a pointer to a string containing a typical pathname +(@samp{/usr/src/cmd/ls/ls.c} for example), returns a pointer to the +last component of the pathname (@samp{ls.c} in this case). The +returned pointer is guaranteed to lie within the original +string. This latter fact is not true of many vendor C +libraries, which return special strings or modify the passed +strings for particular input. + +In particular, the empty string returns the same empty string, +and a path ending in @code{/} returns the empty string after it. + +@end deftypefn + +@c lrealpath.c:25 +@deftypefn Replacement {const char*} lrealpath (const char *@var{name}) + +Given a pointer to a string containing a pathname, returns a canonical +version of the filename. Symlinks will be resolved, and ``.'' and ``..'' +components will be simplified. The returned value will be allocated using +@code{malloc}, or @code{NULL} will be returned on a memory allocation error. + +@end deftypefn + +@c make-relative-prefix.c:23 +@deftypefn Extension {const char*} make_relative_prefix (const char *@var{progname}, @ + const char *@var{bin_prefix}, const char *@var{prefix}) + +Given three paths @var{progname}, @var{bin_prefix}, @var{prefix}, +return the path that is in the same position relative to +@var{progname}'s directory as @var{prefix} is relative to +@var{bin_prefix}. That is, a string starting with the directory +portion of @var{progname}, followed by a relative pathname of the +difference between @var{bin_prefix} and @var{prefix}. + +If @var{progname} does not contain any directory separators, +@code{make_relative_prefix} will search @env{PATH} to find a program +named @var{progname}. Also, if @var{progname} is a symbolic link, +the symbolic link will be resolved. + +For example, if @var{bin_prefix} is @code{/alpha/beta/gamma/gcc/delta}, +@var{prefix} is @code{/alpha/beta/gamma/omega/}, and @var{progname} is +@code{/red/green/blue/gcc}, then this function will return +@code{/red/green/blue/../../omega/}. + +The return value is normally allocated via @code{malloc}. If no +relative prefix can be found, return @code{NULL}. + +@end deftypefn + +@c make-temp-file.c:173 +@deftypefn Replacement char* make_temp_file (const char *@var{suffix}) + +Return a temporary file name (as a string) or @code{NULL} if unable to +create one. @var{suffix} is a suffix to append to the file name. The +string is @code{malloc}ed, and the temporary file has been created. + +@end deftypefn + +@c memchr.c:3 +@deftypefn Supplemental void* memchr (const void *@var{s}, int @var{c}, @ + size_t @var{n}) + +This function searches memory starting at @code{*@var{s}} for the +character @var{c}. The search only ends with the first occurrence of +@var{c}, or after @var{length} characters; in particular, a null +character does not terminate the search. If the character @var{c} is +found within @var{length} characters of @code{*@var{s}}, a pointer +to the character is returned. If @var{c} is not found, then @code{NULL} is +returned. + +@end deftypefn + +@c memcmp.c:6 +@deftypefn Supplemental int memcmp (const void *@var{x}, const void *@var{y}, @ + size_t @var{count}) + +Compares the first @var{count} bytes of two areas of memory. Returns +zero if they are the same, a value less than zero if @var{x} is +lexically less than @var{y}, or a value greater than zero if @var{x} +is lexically greater than @var{y}. Note that lexical order is determined +as if comparing unsigned char arrays. + +@end deftypefn + +@c memcpy.c:6 +@deftypefn Supplemental void* memcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. Returns a pointer to @var{out}. + +@end deftypefn + +@c memmem.c:20 +@deftypefn Supplemental void* memmem (const void *@var{haystack}, @ + size_t @var{haystack_len} const void *@var{needle}, size_t @var{needle_len}) + +Returns a pointer to the first occurrence of @var{needle} (length +@var{needle_len}) in @var{haystack} (length @var{haystack_len}). +Returns @code{NULL} if not found. + +@end deftypefn + +@c memmove.c:6 +@deftypefn Supplemental void* memmove (void *@var{from}, const void *@var{to}, @ + size_t @var{count}) + +Copies @var{count} bytes from memory area @var{from} to memory area +@var{to}, returning a pointer to @var{to}. + +@end deftypefn + +@c mempcpy.c:23 +@deftypefn Supplemental void* mempcpy (void *@var{out}, const void *@var{in}, @ + size_t @var{length}) + +Copies @var{length} bytes from memory region @var{in} to region +@var{out}. Returns a pointer to @var{out} + @var{length}. + +@end deftypefn + +@c memset.c:6 +@deftypefn Supplemental void* memset (void *@var{s}, int @var{c}, @ + size_t @var{count}) + +Sets the first @var{count} bytes of @var{s} to the constant byte +@var{c}, returning a pointer to @var{s}. + +@end deftypefn + +@c mkstemps.c:60 +@deftypefn Replacement int mkstemps (char *@var{pattern}, int @var{suffix_len}) + +Generate a unique temporary file name from @var{pattern}. +@var{pattern} has the form: + +@example + @var{path}/ccXXXXXX@var{suffix} +@end example + +@var{suffix_len} tells us how long @var{suffix} is (it can be zero +length). The last six characters of @var{pattern} before @var{suffix} +must be @samp{XXXXXX}; they are replaced with a string that makes the +filename unique. Returns a file descriptor open on the file for +reading and writing. + +@end deftypefn + +@c pexecute.txh:278 +@deftypefn Extension void pex_free (struct pex_obj @var{obj}) + +Clean up and free all data associated with @var{obj}. If you have not +yet called @code{pex_get_times} or @code{pex_get_status}, this will +try to kill the subprocesses. + +@end deftypefn + +@c pexecute.txh:251 +@deftypefn Extension int pex_get_status (struct pex_obj *@var{obj}, @ + int @var{count}, int *@var{vector}) + +Returns the exit status of all programs run using @var{obj}. +@var{count} is the number of results expected. The results will be +placed into @var{vector}. The results are in the order of the calls +to @code{pex_run}. Returns 0 on error, 1 on success. + +@end deftypefn + +@c pexecute.txh:261 +@deftypefn Extension int pex_get_times (struct pex_obj *@var{obj}, @ + int @var{count}, struct pex_time *@var{vector}) + +Returns the process execution times of all programs run using +@var{obj}. @var{count} is the number of results expected. The +results will be placed into @var{vector}. The results are in the +order of the calls to @code{pex_run}. Returns 0 on error, 1 on +success. + +@code{struct pex_time} has the following fields of the type +@code{unsigned long}: @code{user_seconds}, +@code{user_microseconds}, @code{system_seconds}, +@code{system_microseconds}. On systems which do not support reporting +process times, all the fields will be set to @code{0}. + +@end deftypefn + +@c pexecute.txh:2 +@deftypefn Extension {struct pex_obj *} pex_init (int @var{flags}, @ + const char *@var{pname}, const char *@var{tempbase}) + +Prepare to execute one or more programs, with standard output of each +program fed to standard input of the next. This is a system +independent interface to execute a pipeline. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_RECORD_TIMES +@item PEX_RECORD_TIMES +Record subprocess times if possible. + +@vindex PEX_USE_PIPES +@item PEX_USE_PIPES +Use pipes for communication between processes, if possible. + +@vindex PEX_SAVE_TEMPS +@item PEX_SAVE_TEMPS +Don't delete temporary files used for communication between +processes. + +@end table + +@var{pname} is the name of program to be executed, used in error +messages. @var{tempbase} is a base name to use for any required +temporary files; it may be @code{NULL} to use a randomly chosen name. + +@end deftypefn + +@c pexecute.txh:161 +@deftypefn Extension {FILE *} pex_input_file (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{in_name}) + +Return a stream for a temporary file to pass to the first program in +the pipeline as input. + +The name of the input file is chosen according to the same rules +@code{pex_run} uses to choose output file names, based on +@var{in_name}, @var{obj} and the @code{PEX_SUFFIX} bit in @var{flags}. + +Don't call @code{fclose} on the returned stream; the first call to +@code{pex_run} closes it automatically. + +If @var{flags} includes @code{PEX_BINARY_OUTPUT}, open the stream in +binary mode; otherwise, open it in the default mode. Including +@code{PEX_BINARY_OUTPUT} in @var{flags} has no effect on Unix. +@end deftypefn + +@c pexecute.txh:179 +@deftypefn Extension {FILE *} pex_input_pipe (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Return a stream @var{fp} for a pipe connected to the standard input of +the first program in the pipeline; @var{fp} is opened for writing. +You must have passed @code{PEX_USE_PIPES} to the @code{pex_init} call +that returned @var{obj}. + +You must close @var{fp} using @code{fclose} yourself when you have +finished writing data to the pipeline. + +The file descriptor underlying @var{fp} is marked not to be inherited +by child processes. + +On systems that do not support pipes, this function returns +@code{NULL}, and sets @code{errno} to @code{EINVAL}. If you would +like to write code that is portable to all systems the @code{pex} +functions support, consider using @code{pex_input_file} instead. + +There are two opportunities for deadlock using +@code{pex_input_pipe}: + +@itemize @bullet +@item +Most systems' pipes can buffer only a fixed amount of data; a process +that writes to a full pipe blocks. Thus, if you write to @file{fp} +before starting the first process, you run the risk of blocking when +there is no child process yet to read the data and allow you to +continue. @code{pex_input_pipe} makes no promises about the +size of the pipe's buffer, so if you need to write any data at all +before starting the first process in the pipeline, consider using +@code{pex_input_file} instead. + +@item +Using @code{pex_input_pipe} and @code{pex_read_output} together +may also cause deadlock. If the output pipe fills up, so that each +program in the pipeline is waiting for the next to read more data, and +you fill the input pipe by writing more data to @var{fp}, then there +is no way to make progress: the only process that could read data from +the output pipe is you, but you are blocked on the input pipe. + +@end itemize + +@end deftypefn + +@c pexecute.txh:286 +@deftypefn Extension {const char *} pex_one (int @var{flags}, @ + const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{pname}, const char *@var{outname}, const char *@var{errname}, @ + int *@var{status}, int *@var{err}) + +An interface to permit the easy execution of a +single program. The return value and most of the parameters are as +for a call to @code{pex_run}. @var{flags} is restricted to a +combination of @code{PEX_SEARCH}, @code{PEX_STDERR_TO_STDOUT}, and +@code{PEX_BINARY_OUTPUT}. @var{outname} is interpreted as if +@code{PEX_LAST} were set. On a successful return, @code{*@var{status}} will +be set to the exit status of the program. + +@end deftypefn + +@c pexecute.txh:237 +@deftypefn Extension {FILE *} pex_read_err (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Returns a @code{FILE} pointer which may be used to read the standard +error of the last program in the pipeline. When this is used, +@code{PEX_LAST} should not be used in a call to @code{pex_run}. After +this is called, @code{pex_run} may no longer be called with the same +@var{obj}. @var{binary} should be non-zero if the file should be +opened in binary mode. Don't call @code{fclose} on the returned file; +it will be closed by @code{pex_free}. + +@end deftypefn + +@c pexecute.txh:224 +@deftypefn Extension {FILE *} pex_read_output (struct pex_obj *@var{obj}, @ + int @var{binary}) + +Returns a @code{FILE} pointer which may be used to read the standard +output of the last program in the pipeline. When this is used, +@code{PEX_LAST} should not be used in a call to @code{pex_run}. After +this is called, @code{pex_run} may no longer be called with the same +@var{obj}. @var{binary} should be non-zero if the file should be +opened in binary mode. Don't call @code{fclose} on the returned file; +it will be closed by @code{pex_free}. + +@end deftypefn + +@c pexecute.txh:34 +@deftypefn Extension {const char *} pex_run (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + const char *@var{outname}, const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline. On success this returns +@code{NULL}. On failure it returns an error message, a statically +allocated string. + +@var{obj} is returned by a previous call to @code{pex_init}. + +@var{flags} is a bitwise combination of the following: + +@table @code + +@vindex PEX_LAST +@item PEX_LAST +This must be set on the last program in the pipeline. In particular, +it should be set when executing a single program. The standard output +of the program will be sent to @var{outname}, or, if @var{outname} is +@code{NULL}, to the standard output of the calling program. Do @emph{not} +set this bit if you want to call @code{pex_read_output} +(described below). After a call to @code{pex_run} with this bit set, +@var{pex_run} may no longer be called with the same @var{obj}. + +@vindex PEX_SEARCH +@item PEX_SEARCH +Search for the program using the user's executable search path. + +@vindex PEX_SUFFIX +@item PEX_SUFFIX +@var{outname} is a suffix. See the description of @var{outname}, +below. + +@vindex PEX_STDERR_TO_STDOUT +@item PEX_STDERR_TO_STDOUT +Send the program's standard error to standard output, if possible. + +@vindex PEX_BINARY_INPUT +@vindex PEX_BINARY_OUTPUT +@vindex PEX_BINARY_ERROR +@item PEX_BINARY_INPUT +@itemx PEX_BINARY_OUTPUT +@itemx PEX_BINARY_ERROR +The standard input (output or error) of the program should be read (written) in +binary mode rather than text mode. These flags are ignored on systems +which do not distinguish binary mode and text mode, such as Unix. For +proper behavior these flags should match appropriately---a call to +@code{pex_run} using @code{PEX_BINARY_OUTPUT} should be followed by a +call using @code{PEX_BINARY_INPUT}. + +@vindex PEX_STDERR_TO_PIPE +@item PEX_STDERR_TO_PIPE +Send the program's standard error to a pipe, if possible. This flag +cannot be specified together with @code{PEX_STDERR_TO_STDOUT}. This +flag can be specified only on the last program in pipeline. + +@end table + +@var{executable} is the program to execute. @var{argv} is the set of +arguments to pass to the program; normally @code{@var{argv}[0]} will +be a copy of @var{executable}. + +@var{outname} is used to set the name of the file to use for standard +output. There are two cases in which no output file will be used: + +@enumerate +@item +if @code{PEX_LAST} is not set in @var{flags}, and @code{PEX_USE_PIPES} +was set in the call to @code{pex_init}, and the system supports pipes + +@item +if @code{PEX_LAST} is set in @var{flags}, and @var{outname} is +@code{NULL} +@end enumerate + +@noindent +Otherwise the code will use a file to hold standard +output. If @code{PEX_LAST} is not set, this file is considered to be +a temporary file, and it will be removed when no longer needed, unless +@code{PEX_SAVE_TEMPS} was set in the call to @code{pex_init}. + +There are two cases to consider when setting the name of the file to +hold standard output. + +@enumerate +@item +@code{PEX_SUFFIX} is set in @var{flags}. In this case +@var{outname} may not be @code{NULL}. If the @var{tempbase} parameter +to @code{pex_init} was not @code{NULL}, then the output file name is +the concatenation of @var{tempbase} and @var{outname}. If +@var{tempbase} was @code{NULL}, then the output file name is a random +file name ending in @var{outname}. + +@item +@code{PEX_SUFFIX} was not set in @var{flags}. In this +case, if @var{outname} is not @code{NULL}, it is used as the output +file name. If @var{outname} is @code{NULL}, and @var{tempbase} was +not NULL, the output file name is randomly chosen using +@var{tempbase}. Otherwise the output file name is chosen completely +at random. +@end enumerate + +@var{errname} is the file name to use for standard error output. If +it is @code{NULL}, standard error is the same as the caller's. +Otherwise, standard error is written to the named file. + +On an error return, the code sets @code{*@var{err}} to an @code{errno} +value, or to 0 if there is no relevant @code{errno}. + +@end deftypefn + +@c pexecute.txh:145 +@deftypefn Extension {const char *} pex_run_in_environment (struct pex_obj *@var{obj}, @ + int @var{flags}, const char *@var{executable}, char * const *@var{argv}, @ + char * const *@var{env}, int @var{env_size}, const char *@var{outname}, @ + const char *@var{errname}, int *@var{err}) + +Execute one program in a pipeline, permitting the environment for the +program to be specified. Behaviour and parameters not listed below are +as for @code{pex_run}. + +@var{env} is the environment for the child process, specified as an array of +character pointers. Each element of the array should point to a string of the +form @code{VAR=VALUE}, with the exception of the last element that must be +@code{NULL}. + +@end deftypefn + +@c pexecute.txh:301 +@deftypefn Extension int pexecute (const char *@var{program}, @ + char * const *@var{argv}, const char *@var{this_pname}, @ + const char *@var{temp_base}, char **@var{errmsg_fmt}, @ + char **@var{errmsg_arg}, int @var{flags}) + +This is the old interface to execute one or more programs. It is +still supported for compatibility purposes, but is no longer +documented. + +@end deftypefn + +@c strsignal.c:541 +@deftypefn Supplemental void psignal (int @var{signo}, char *@var{message}) + +Print @var{message} to the standard error, followed by a colon, +followed by the description of the signal specified by @var{signo}, +followed by a newline. + +@end deftypefn + +@c putenv.c:21 +@deftypefn Supplemental int putenv (const char *@var{string}) + +Uses @code{setenv} or @code{unsetenv} to put @var{string} into +the environment or remove it. If @var{string} is of the form +@samp{name=value} the string is added; if no @samp{=} is present the +name is unset/removed. + +@end deftypefn + +@c pexecute.txh:312 +@deftypefn Extension int pwait (int @var{pid}, int *@var{status}, int @var{flags}) + +Another part of the old execution interface. + +@end deftypefn + +@c random.c:39 +@deftypefn Supplement {long int} random (void) +@deftypefnx Supplement void srandom (unsigned int @var{seed}) +@deftypefnx Supplement void* initstate (unsigned int @var{seed}, @ + void *@var{arg_state}, unsigned long @var{n}) +@deftypefnx Supplement void* setstate (void *@var{arg_state}) + +Random number functions. @code{random} returns a random number in the +range 0 to @code{LONG_MAX}. @code{srandom} initializes the random +number generator to some starting point determined by @var{seed} +(else, the values returned by @code{random} are always the same for each +run of the program). @code{initstate} and @code{setstate} allow fine-grained +control over the state of the random number generator. + +@end deftypefn + +@c concat.c:160 +@deftypefn Extension char* reconcat (char *@var{optr}, const char *@var{s1}, @ + @dots{}, @code{NULL}) + +Same as @code{concat}, except that if @var{optr} is not @code{NULL} it +is freed after the string is created. This is intended to be useful +when you're extending an existing string or building up a string in a +loop: + +@example + str = reconcat (str, "pre-", str, NULL); +@end example + +@end deftypefn + +@c rename.c:6 +@deftypefn Supplemental int rename (const char *@var{old}, const char *@var{new}) + +Renames a file from @var{old} to @var{new}. If @var{new} already +exists, it is removed. + +@end deftypefn + +@c rindex.c:5 +@deftypefn Supplemental char* rindex (const char *@var{s}, int @var{c}) + +Returns a pointer to the last occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. The use of @code{rindex} is +deprecated in new programs in favor of @code{strrchr}. + +@end deftypefn + +@c setenv.c:22 +@deftypefn Supplemental int setenv (const char *@var{name}, @ + const char *@var{value}, int @var{overwrite}) +@deftypefnx Supplemental void unsetenv (const char *@var{name}) + +@code{setenv} adds @var{name} to the environment with value +@var{value}. If the name was already present in the environment, +the new value will be stored only if @var{overwrite} is nonzero. +The companion @code{unsetenv} function removes @var{name} from the +environment. This implementation is not safe for multithreaded code. + +@end deftypefn + +@c setproctitle.c:31 +@deftypefn Supplemental void setproctitle (const char *@var{fmt}, ...) + +Set the title of a process to @var{fmt}. va args not supported for now, +but defined for compatibility with BSD. + +@end deftypefn + +@c strsignal.c:348 +@deftypefn Extension int signo_max (void) + +Returns the maximum signal value for which a corresponding symbolic +name or message is available. Note that in the case where we use the +@code{sys_siglist} supplied by the system, it is possible for there to +be more symbolic names than messages, or vice versa. In fact, the +manual page for @code{psignal(3b)} explicitly warns that one should +check the size of the table (@code{NSIG}) before indexing it, since +new signal codes may be added to the system before they are added to +the table. Thus @code{NSIG} might be smaller than value implied by +the largest signo value defined in @code{}. + +We return the maximum value that can be used to obtain a meaningful +symbolic name or message. + +@end deftypefn + +@c sigsetmask.c:8 +@deftypefn Supplemental int sigsetmask (int @var{set}) + +Sets the signal mask to the one provided in @var{set} and returns +the old mask (which, for libiberty's implementation, will always +be the value @code{1}). + +@end deftypefn + +@c simple-object.txh:96 +@deftypefn Extension {const char *} simple_object_attributes_compare @ + (simple_object_attributes *@var{attrs1}, simple_object_attributes *@var{attrs2}, @ + int *@var{err}) + +Compare @var{attrs1} and @var{attrs2}. If they could be linked +together without error, return @code{NULL}. Otherwise, return an +error message and set @code{*@var{err}} to an errno value or @code{0} +if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:81 +@deftypefn Extension {simple_object_attributes *} simple_object_fetch_attributes @ + (simple_object_read *@var{simple_object}, const char **@var{errmsg}, int *@var{err}) + +Fetch the attributes of @var{simple_object}. The attributes are +internal information such as the format of the object file, or the +architecture it was compiled for. This information will persist until +@code{simple_object_attributes_release} is called, even if +@var{simple_object} itself is released. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:49 +@deftypefn Extension {int} simple_object_find_section @ + (simple_object_read *@var{simple_object} off_t *@var{offset}, @ + off_t *@var{length}, const char **@var{errmsg}, int *@var{err}) + +Look for the section @var{name} in @var{simple_object}. This returns +information for the first section with that name. + +If found, return 1 and set @code{*@var{offset}} to the offset in the +file of the section contents and set @code{*@var{length}} to the +length of the section contents. The value in @code{*@var{offset}} +will be relative to the offset passed to +@code{simple_object_open_read}. + +If the section is not found, and no error occurs, +@code{simple_object_find_section} returns @code{0} and set +@code{*@var{errmsg}} to @code{NULL}. + +If an error occurs, @code{simple_object_find_section} returns +@code{0}, sets @code{*@var{errmsg}} to an error message, and sets +@code{*@var{err}} to an errno value or @code{0} if there is no +relevant errno. + +@end deftypefn + +@c simple-object.txh:27 +@deftypefn Extension {const char *} simple_object_find_sections @ + (simple_object_read *@var{simple_object}, int (*@var{pfn}) (void *@var{data}, @ + const char *@var{name}, off_t @var{offset}, off_t @var{length}), @ + void *@var{data}, int *@var{err}) + +This function calls @var{pfn} for each section in @var{simple_object}. +It calls @var{pfn} with the section name, the offset within the file +of the section contents, and the length of the section contents. The +offset within the file is relative to the offset passed to +@code{simple_object_open_read}. The @var{data} argument to this +function is passed along to @var{pfn}. + +If @var{pfn} returns @code{0}, the loop over the sections stops and +@code{simple_object_find_sections} returns. If @var{pfn} returns some +other value, the loop continues. + +On success @code{simple_object_find_sections} returns. On error it +returns an error string, and sets @code{*@var{err}} to an errno value +or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:2 +@deftypefn Extension {simple_object_read *} simple_object_open_read @ + (int @var{descriptor}, off_t @var{offset}, const char *{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Opens an object file for reading. Creates and returns an +@code{simple_object_read} pointer which may be passed to other +functions to extract data from the object file. + +@var{descriptor} holds a file descriptor which permits reading. + +@var{offset} is the offset into the file; this will be @code{0} in the +normal case, but may be a different value when reading an object file +in an archive file. + +@var{segment_name} is only used with the Mach-O file format used on +Darwin aka Mac OS X. It is required on that platform, and means to +only look at sections within the segment with that name. The +parameter is ignored on other systems. + +If an error occurs, this functions returns @code{NULL} and sets +@code{*@var{errmsg}} to an error string and sets @code{*@var{err}} to +an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:107 +@deftypefn Extension {void} simple_object_release_attributes @ + (simple_object_attributes *@var{attrs}) + +Release all resources associated with @var{attrs}. + +@end deftypefn + +@c simple-object.txh:73 +@deftypefn Extension {void} simple_object_release_read @ + (simple_object_read *@var{simple_object}) + +Release all resources associated with @var{simple_object}. This does +not close the file descriptor. + +@end deftypefn + +@c simple-object.txh:184 +@deftypefn Extension {void} simple_object_release_write @ + (simple_object_write *@var{simple_object}) + +Release all resources associated with @var{simple_object}. + +@end deftypefn + +@c simple-object.txh:114 +@deftypefn Extension {simple_object_write *} simple_object_start_write @ + (simple_object_attributes @var{attrs}, const char *@var{segment_name}, @ + const char **@var{errmsg}, int *@var{err}) + +Start creating a new object file using the object file format +described in @var{attrs}. You must fetch attribute information from +an existing object file before you can create a new one. There is +currently no support for creating an object file de novo. + +@var{segment_name} is only used with Mach-O as found on Darwin aka Mac +OS X. The parameter is required on that target. It means that all +sections are created within the named segment. It is ignored for +other object file formats. + +On error @code{simple_object_start_write} returns @code{NULL}, sets +@code{*@var{ERRMSG}} to an error message, and sets @code{*@var{err}} +to an errno value or @code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:153 +@deftypefn Extension {const char *} simple_object_write_add_data @ + (simple_object_write *@var{simple_object}, @ + simple_object_write_section *@var{section}, const void *@var{buffer}, @ + size_t @var{size}, int @var{copy}, int *@var{err}) + +Add data @var{buffer}/@var{size} to @var{section} in +@var{simple_object}. If @var{copy} is non-zero, the data will be +copied into memory if necessary. If @var{copy} is zero, @var{buffer} +must persist until @code{simple_object_write_to_file} is called. is +released. + +On success this returns @code{NULL}. On error this returns an error +message, and sets @code{*@var{err}} to an errno value or 0 if there is +no relevant erro. + +@end deftypefn + +@c simple-object.txh:134 +@deftypefn Extension {simple_object_write_section *} simple_object_write_create_section @ + (simple_object_write *@var{simple_object}, const char *@var{name}, @ + unsigned int @var{align}, const char **@var{errmsg}, int *@var{err}) + +Add a section to @var{simple_object}. @var{name} is the name of the +new section. @var{align} is the required alignment expressed as the +number of required low-order 0 bits (e.g., 2 for alignment to a 32-bit +boundary). + +The section is created as containing data, readable, not writable, not +executable, not loaded at runtime. The section is not written to the +file until @code{simple_object_write_to_file} is called. + +On error this returns @code{NULL}, sets @code{*@var{errmsg}} to an +error message, and sets @code{*@var{err}} to an errno value or +@code{0} if there is no relevant errno. + +@end deftypefn + +@c simple-object.txh:170 +@deftypefn Extension {const char *} simple_object_write_to_file @ + (simple_object_write *@var{simple_object}, int @var{descriptor}, int *@var{err}) + +Write the complete object file to @var{descriptor}, an open file +descriptor. This writes out all the data accumulated by calls to +@code{simple_object_write_create_section} and +@var{simple_object_write_add_data}. + +This returns @code{NULL} on success. On error this returns an error +message and sets @code{*@var{err}} to an errno value or @code{0} if +there is no relevant errno. + +@end deftypefn + +@c snprintf.c:28 +@deftypefn Supplemental int snprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, ...) + +This function is similar to @code{sprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. +On error the return value is -1, otherwise it returns the number of +bytes, not including the terminating null byte, that would have been +written had @var{n} been sufficiently large, regardless of the actual +value of @var{n}. Note some pre-C99 system libraries do not implement +this correctly so users cannot generally rely on the return value if +the system version of this function is used. + +@end deftypefn + +@c spaces.c:22 +@deftypefn Extension char* spaces (int @var{count}) + +Returns a pointer to a memory region filled with the specified +number of spaces and null terminated. The returned pointer is +valid until at least the next call. + +@end deftypefn + +@c splay-tree.c:305 +@deftypefn Supplemental splay_tree splay_tree_new_with_typed_alloc @ +(splay_tree_compare_fn @var{compare_fn}, @ +splay_tree_delete_key_fn @var{delete_key_fn}, @ +splay_tree_delete_value_fn @var{delete_value_fn}, @ +splay_tree_allocate_fn @var{tree_allocate_fn}, @ +splay_tree_allocate_fn @var{node_allocate_fn}, @ +splay_tree_deallocate_fn @var{deallocate_fn}, @ +void * @var{allocate_data}) + +This function creates a splay tree that uses two different allocators +@var{tree_allocate_fn} and @var{node_allocate_fn} to use for allocating the +tree itself and its nodes respectively. This is useful when variables of +different types need to be allocated with different allocators. + +The splay tree will use @var{compare_fn} to compare nodes, +@var{delete_key_fn} to deallocate keys, and @var{delete_value_fn} to +deallocate values. Keys and values will be deallocated when the +tree is deleted using splay_tree_delete or when a node is removed +using splay_tree_remove. splay_tree_insert will release the previously +inserted key and value using @var{delete_key_fn} and @var{delete_value_fn} +if the inserted key is already found in the tree. + +@end deftypefn + +@c stack-limit.c:28 +@deftypefn Extension void stack_limit_increase (unsigned long @var{pref}) + +Attempt to increase stack size limit to @var{pref} bytes if possible. + +@end deftypefn + +@c stpcpy.c:23 +@deftypefn Supplemental char* stpcpy (char *@var{dst}, const char *@var{src}) + +Copies the string @var{src} into @var{dst}. Returns a pointer to +@var{dst} + strlen(@var{src}). + +@end deftypefn + +@c stpncpy.c:23 +@deftypefn Supplemental char* stpncpy (char *@var{dst}, const char *@var{src}, @ + size_t @var{len}) + +Copies the string @var{src} into @var{dst}, copying exactly @var{len} +and padding with zeros if necessary. If @var{len} < strlen(@var{src}) +then return @var{dst} + @var{len}, otherwise returns @var{dst} + +strlen(@var{src}). + +@end deftypefn + +@c strcasecmp.c:15 +@deftypefn Supplemental int strcasecmp (const char *@var{s1}, const char *@var{s2}) + +A case-insensitive @code{strcmp}. + +@end deftypefn + +@c strchr.c:6 +@deftypefn Supplemental char* strchr (const char *@var{s}, int @var{c}) + +Returns a pointer to the first occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the +null character, the results are undefined. + +@end deftypefn + +@c strdup.c:3 +@deftypefn Supplemental char* strdup (const char *@var{s}) + +Returns a pointer to a copy of @var{s} in memory obtained from +@code{malloc}, or @code{NULL} if insufficient memory was available. + +@end deftypefn + +@c strerror.c:675 +@deftypefn Replacement {const char*} strerrno (int @var{errnum}) + +Given an error number returned from a system call (typically returned +in @code{errno}), returns a pointer to a string containing the +symbolic name of that error number, as found in @code{}. + +If the supplied error number is within the valid range of indices for +symbolic names, but no name is available for the particular error +number, then returns the string @samp{Error @var{num}}, where @var{num} +is the error number. + +If the supplied error number is not within the range of valid +indices, then returns @code{NULL}. + +The contents of the location pointed to are only guaranteed to be +valid until the next call to @code{strerrno}. + +@end deftypefn + +@c strerror.c:608 +@deftypefn Supplemental char* strerror (int @var{errnoval}) + +Maps an @code{errno} number to an error message string, the contents +of which are implementation defined. On systems which have the +external variables @code{sys_nerr} and @code{sys_errlist}, these +strings will be the same as the ones used by @code{perror}. + +If the supplied error number is within the valid range of indices for +the @code{sys_errlist}, but no message is available for the particular +error number, then returns the string @samp{Error @var{num}}, where +@var{num} is the error number. + +If the supplied error number is not a valid index into +@code{sys_errlist}, returns @code{NULL}. + +The returned string is only guaranteed to be valid only until the +next call to @code{strerror}. + +@end deftypefn + +@c strncasecmp.c:15 +@deftypefn Supplemental int strncasecmp (const char *@var{s1}, const char *@var{s2}) + +A case-insensitive @code{strncmp}. + +@end deftypefn + +@c strncmp.c:6 +@deftypefn Supplemental int strncmp (const char *@var{s1}, @ + const char *@var{s2}, size_t @var{n}) + +Compares the first @var{n} bytes of two strings, returning a value as +@code{strcmp}. + +@end deftypefn + +@c strndup.c:23 +@deftypefn Extension char* strndup (const char *@var{s}, size_t @var{n}) + +Returns a pointer to a copy of @var{s} with at most @var{n} characters +in memory obtained from @code{malloc}, or @code{NULL} if insufficient +memory was available. The result is always NUL terminated. + +@end deftypefn + +@c strnlen.c:6 +@deftypefn Supplemental size_t strnlen (const char *@var{s}, size_t @var{maxlen}) + +Returns the length of @var{s}, as with @code{strlen}, but never looks +past the first @var{maxlen} characters in the string. If there is no +'\0' character in the first @var{maxlen} characters, returns +@var{maxlen}. + +@end deftypefn + +@c strrchr.c:6 +@deftypefn Supplemental char* strrchr (const char *@var{s}, int @var{c}) + +Returns a pointer to the last occurrence of the character @var{c} in +the string @var{s}, or @code{NULL} if not found. If @var{c} is itself the +null character, the results are undefined. + +@end deftypefn + +@c strsignal.c:383 +@deftypefn Supplemental {const char *} strsignal (int @var{signo}) + +Maps an signal number to an signal message string, the contents of +which are implementation defined. On systems which have the external +variable @code{sys_siglist}, these strings will be the same as the +ones used by @code{psignal()}. + +If the supplied signal number is within the valid range of indices for +the @code{sys_siglist}, but no message is available for the particular +signal number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not a valid index into +@code{sys_siglist}, returns @code{NULL}. + +The returned string is only guaranteed to be valid only until the next +call to @code{strsignal}. + +@end deftypefn + +@c strsignal.c:448 +@deftypefn Extension {const char*} strsigno (int @var{signo}) + +Given an signal number, returns a pointer to a string containing the +symbolic name of that signal number, as found in @code{}. + +If the supplied signal number is within the valid range of indices for +symbolic names, but no name is available for the particular signal +number, then returns the string @samp{Signal @var{num}}, where +@var{num} is the signal number. + +If the supplied signal number is not within the range of valid +indices, then returns @code{NULL}. + +The contents of the location pointed to are only guaranteed to be +valid until the next call to @code{strsigno}. + +@end deftypefn + +@c strstr.c:6 +@deftypefn Supplemental char* strstr (const char *@var{string}, const char *@var{sub}) + +This function searches for the substring @var{sub} in the string +@var{string}, not including the terminating null characters. A pointer +to the first occurrence of @var{sub} is returned, or @code{NULL} if the +substring is absent. If @var{sub} points to a string with zero +length, the function returns @var{string}. + +@end deftypefn + +@c strtod.c:27 +@deftypefn Supplemental double strtod (const char *@var{string}, @ + char **@var{endptr}) + +This ISO C function converts the initial portion of @var{string} to a +@code{double}. If @var{endptr} is not @code{NULL}, a pointer to the +character after the last character used in the conversion is stored in +the location referenced by @var{endptr}. If no conversion is +performed, zero is returned and the value of @var{string} is stored in +the location referenced by @var{endptr}. + +@end deftypefn + +@c strerror.c:734 +@deftypefn Extension int strtoerrno (const char *@var{name}) + +Given the symbolic name of a error number (e.g., @code{EACCES}), map it +to an errno value. If no translation is found, returns 0. + +@end deftypefn + +@c strtol.c:33 +@deftypefn Supplemental {long int} strtol (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long int} strtoul (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) + +The @code{strtol} function converts the string in @var{string} to a +long integer value according to the given @var{base}, which must be +between 2 and 36 inclusive, or be the special value 0. If @var{base} +is 0, @code{strtol} will look for the prefixes @code{0} and @code{0x} +to indicate bases 8 and 16, respectively, else default to base 10. +When the base is 16 (either explicitly or implicitly), a prefix of +@code{0x} is allowed. The handling of @var{endptr} is as that of +@code{strtod} above. The @code{strtoul} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strtoll.c:33 +@deftypefn Supplemental {long long int} strtoll (const char *@var{string}, @ + char **@var{endptr}, int @var{base}) +@deftypefnx Supplemental {unsigned long long int} strtoull (@ + const char *@var{string}, char **@var{endptr}, int @var{base}) + +The @code{strtoll} function converts the string in @var{string} to a +long long integer value according to the given @var{base}, which must be +between 2 and 36 inclusive, or be the special value 0. If @var{base} +is 0, @code{strtoll} will look for the prefixes @code{0} and @code{0x} +to indicate bases 8 and 16, respectively, else default to base 10. +When the base is 16 (either explicitly or implicitly), a prefix of +@code{0x} is allowed. The handling of @var{endptr} is as that of +@code{strtod} above. The @code{strtoull} function is the same, except +that the converted value is unsigned. + +@end deftypefn + +@c strsignal.c:502 +@deftypefn Extension int strtosigno (const char *@var{name}) + +Given the symbolic name of a signal, map it to a signal number. If no +translation is found, returns 0. + +@end deftypefn + +@c strverscmp.c:25 +@deftypefun int strverscmp (const char *@var{s1}, const char *@var{s2}) +The @code{strverscmp} function compares the string @var{s1} against +@var{s2}, considering them as holding indices/version numbers. Return +value follows the same conventions as found in the @code{strverscmp} +function. In fact, if @var{s1} and @var{s2} contain no digits, +@code{strverscmp} behaves like @code{strcmp}. + +Basically, we compare strings normally (character by character), until +we find a digit in each string - then we enter a special comparison +mode, where each sequence of digits is taken as a whole. If we reach the +end of these two parts without noticing a difference, we return to the +standard comparison mode. There are two types of numeric parts: +"integral" and "fractional" (those begin with a '0'). The types +of the numeric parts affect the way we sort them: + +@itemize @bullet +@item +integral/integral: we compare values as you would expect. + +@item +fractional/integral: the fractional part is less than the integral one. +Again, no surprise. + +@item +fractional/fractional: the things become a bit more complex. +If the common prefix contains only leading zeroes, the longest part is less +than the other one; else the comparison behaves normally. +@end itemize + +@smallexample +strverscmp ("no digit", "no digit") + @result{} 0 // @r{same behavior as strcmp.} +strverscmp ("item#99", "item#100") + @result{} <0 // @r{same prefix, but 99 < 100.} +strverscmp ("alpha1", "alpha001") + @result{} >0 // @r{fractional part inferior to integral one.} +strverscmp ("part1_f012", "part1_f01") + @result{} >0 // @r{two fractional parts.} +strverscmp ("foo.009", "foo.0") + @result{} <0 // @r{idem, but with leading zeroes only.} +@end smallexample + +This function is especially useful when dealing with filename sorting, +because filenames frequently hold indices/version numbers. +@end deftypefun + +@c timeval-utils.c:43 +@deftypefn Extension void timeval_add (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Adds @var{a} to @var{b} and stores the result in @var{result}. + +@end deftypefn + +@c timeval-utils.c:67 +@deftypefn Extension void timeval_sub (struct timeval *@var{a}, @ + struct timeval *@var{b}, struct timeval *@var{result}) + +Subtracts @var{b} from @var{a} and stores the result in @var{result}. + +@end deftypefn + +@c tmpnam.c:3 +@deftypefn Supplemental char* tmpnam (char *@var{s}) + +This function attempts to create a name for a temporary file, which +will be a valid file name yet not exist when @code{tmpnam} checks for +it. @var{s} must point to a buffer of at least @code{L_tmpnam} bytes, +or be @code{NULL}. Use of this function creates a security risk, and it must +not be used in new projects. Use @code{mkstemp} instead. + +@end deftypefn + +@c unlink-if-ordinary.c:27 +@deftypefn Supplemental int unlink_if_ordinary (const char*) + +Unlinks the named file, unless it is special (e.g. a device file). +Returns 0 when the file was unlinked, a negative value (and errno set) when +there was an error deleting the file, and a positive value if no attempt +was made to unlink the file because it is special. + +@end deftypefn + +@c fopen_unlocked.c:31 +@deftypefn Extension void unlock_std_streams (void) + +If the OS supports it, ensure that the standard I/O streams, +@code{stdin}, @code{stdout} and @code{stderr} are setup to avoid any +multi-threaded locking. Otherwise do nothing. + +@end deftypefn + +@c fopen_unlocked.c:23 +@deftypefn Extension void unlock_stream (FILE * @var{stream}) + +If the OS supports it, ensure that the supplied stream is setup to +avoid any multi-threaded locking. Otherwise leave the @code{FILE} +pointer unchanged. If the @var{stream} is @code{NULL} do nothing. + +@end deftypefn + +@c vasprintf.c:47 +@deftypefn Extension int vasprintf (char **@var{resptr}, @ + const char *@var{format}, va_list @var{args}) + +Like @code{vsprintf}, but instead of passing a pointer to a buffer, +you pass a pointer to a pointer. This function will compute the size +of the buffer needed, allocate memory with @code{malloc}, and store a +pointer to the allocated memory in @code{*@var{resptr}}. The value +returned is the same as @code{vsprintf} would return. If memory could +not be allocated, minus one is returned and @code{NULL} is stored in +@code{*@var{resptr}}. + +@end deftypefn + +@c vfork.c:6 +@deftypefn Supplemental int vfork (void) + +Emulates @code{vfork} by calling @code{fork} and returning its value. + +@end deftypefn + +@c vprintf.c:3 +@deftypefn Supplemental int vprintf (const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vfprintf (FILE *@var{stream}, @ + const char *@var{format}, va_list @var{ap}) +@deftypefnx Supplemental int vsprintf (char *@var{str}, @ + const char *@var{format}, va_list @var{ap}) + +These functions are the same as @code{printf}, @code{fprintf}, and +@code{sprintf}, respectively, except that they are called with a +@code{va_list} instead of a variable number of arguments. Note that +they do not call @code{va_end}; this is the application's +responsibility. In @libib{} they are implemented in terms of the +nonstandard but common function @code{_doprnt}. + +@end deftypefn + +@c vsnprintf.c:28 +@deftypefn Supplemental int vsnprintf (char *@var{buf}, size_t @var{n}, @ + const char *@var{format}, va_list @var{ap}) + +This function is similar to @code{vsprintf}, but it will write to +@var{buf} at most @code{@var{n}-1} bytes of text, followed by a +terminating null byte, for a total of @var{n} bytes. On error the +return value is -1, otherwise it returns the number of characters that +would have been printed had @var{n} been sufficiently large, +regardless of the actual value of @var{n}. Note some pre-C99 system +libraries do not implement this correctly so users cannot generally +rely on the return value if the system version of this function is +used. + +@end deftypefn + +@c waitpid.c:3 +@deftypefn Supplemental int waitpid (int @var{pid}, int *@var{status}, int) + +This is a wrapper around the @code{wait} function. Any ``special'' +values of @var{pid} depend on your implementation of @code{wait}, as +does the return value. The third argument is unused in @libib{}. + +@end deftypefn + +@c argv.c:289 +@deftypefn Extension int writeargv (char * const *@var{argv}, FILE *@var{file}) + +Write each member of ARGV, handling all necessary quoting, to the file +named by FILE, separated by whitespace. Return 0 on success, non-zero +if an error occurred while writing to FILE. + +@end deftypefn + +@c xasprintf.c:31 +@deftypefn Replacement char* xasprintf (const char *@var{format}, ...) + +Print to allocated string without fail. If @code{xasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn + +@c xatexit.c:11 +@deftypefun int xatexit (void (*@var{fn}) (void)) + +Behaves as the standard @code{atexit} function, but with no limit on +the number of registered functions. Returns 0 on success, or @minus{}1 on +failure. If you use @code{xatexit} to register functions, you must use +@code{xexit} to terminate your program. + +@end deftypefun + +@c xmalloc.c:38 +@deftypefn Replacement void* xcalloc (size_t @var{nelem}, size_t @var{elsize}) + +Allocate memory without fail, and set it to zero. This routine functions +like @code{calloc}, but will behave the same as @code{xmalloc} if memory +cannot be found. + +@end deftypefn + +@c xexit.c:22 +@deftypefn Replacement void xexit (int @var{code}) + +Terminates the program. If any functions have been registered with +the @code{xatexit} replacement function, they will be called first. +Termination is handled via the system's normal @code{exit} call. + +@end deftypefn + +@c xmalloc.c:22 +@deftypefn Replacement void* xmalloc (size_t) + +Allocate memory without fail. If @code{malloc} fails, this will print +a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, +if any) and then call @code{xexit}. Note that it is therefore safe for +a program to contain @code{#define malloc xmalloc} in its source. + +@end deftypefn + +@c xmalloc.c:53 +@deftypefn Replacement void xmalloc_failed (size_t) + +This function is not meant to be called by client code, and is listed +here for completeness only. If any of the allocation routines fail, this +function will be called to print an error message and terminate execution. + +@end deftypefn + +@c xmalloc.c:46 +@deftypefn Replacement void xmalloc_set_program_name (const char *@var{name}) + +You can use this to set the name of the program used by +@code{xmalloc_failed} when printing a failure message. + +@end deftypefn + +@c xmemdup.c:7 +@deftypefn Replacement void* xmemdup (void *@var{input}, @ + size_t @var{copy_size}, size_t @var{alloc_size}) + +Duplicates a region of memory without fail. First, @var{alloc_size} bytes +are allocated, then @var{copy_size} bytes from @var{input} are copied into +it, and the new memory is returned. If fewer bytes are copied than were +allocated, the remaining memory is zeroed. + +@end deftypefn + +@c xmalloc.c:32 +@deftypefn Replacement void* xrealloc (void *@var{ptr}, size_t @var{size}) +Reallocate memory without fail. This routine functions like @code{realloc}, +but will behave the same as @code{xmalloc} if memory cannot be found. + +@end deftypefn + +@c xstrdup.c:7 +@deftypefn Replacement char* xstrdup (const char *@var{s}) + +Duplicates a character string without fail, using @code{xmalloc} to +obtain memory. + +@end deftypefn + +@c xstrerror.c:7 +@deftypefn Replacement char* xstrerror (int @var{errnum}) + +Behaves exactly like the standard @code{strerror} function, but +will never return a @code{NULL} pointer. + +@end deftypefn + +@c xstrndup.c:23 +@deftypefn Replacement char* xstrndup (const char *@var{s}, size_t @var{n}) + +Returns a pointer to a copy of @var{s} with at most @var{n} characters +without fail, using @code{xmalloc} to obtain memory. The result is +always NUL terminated. + +@end deftypefn + +@c xvasprintf.c:38 +@deftypefn Replacement char* xvasprintf (const char *@var{format}, va_list @var{args}) + +Print to allocated string without fail. If @code{xvasprintf} fails, +this will print a message to @code{stderr} (using the name set by +@code{xmalloc_set_program_name}, if any) and then call @code{xexit}. + +@end deftypefn + diff -pruN 16.3-5/libiberty/libiberty.texi 16.3-5ubuntu1/libiberty/libiberty.texi --- 16.3-5/libiberty/libiberty.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libiberty/libiberty.texi 2025-04-20 17:22:06.000000000 +0000 @@ -1 +1,313 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename libiberty.info +@settitle @sc{gnu} libiberty +@c %**end of header + +@syncodeindex fn cp +@syncodeindex vr cp +@syncodeindex pg cp + +@finalout +@c %**end of header + +@dircategory GNU libraries +@direntry +* Libiberty: (libiberty). Library of utility functions which + are missing or broken on some systems. +@end direntry + +@macro libib +@code{libiberty} +@end macro + +@ifinfo +This manual describes the GNU @libib library of utility subroutines. + +Copyright @copyright{} 2001-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled ``GNU Free Documentation License''. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries a copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +@end ifinfo + + +@titlepage +@title @sc{gnu} libiberty +@author Phil Edwards et al. +@page + + +@vskip 0pt plus 1filll +Copyright @copyright{} 2001-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, with no Front-Cover Texts, and with no + Back-Cover Texts. A copy of the license is included in the + section entitled ``GNU Free Documentation License''. + +@end titlepage +@contents +@page + +@ifnottex +@node Top,Using,, +@top Introduction + +The @libib{} library is a collection of subroutines used by various +GNU programs. It is available under the Library General Public +License; for more information, see @ref{Library Copying}. + +@end ifnottex + +@menu +* Using:: How to use libiberty in your code. + +* Overview:: Overview of available function groups. + +* Functions:: Available functions, macros, and global variables. + +* Licenses:: The various licenses under which libiberty sources are + distributed. + +* Index:: Index of functions and categories. +@end menu + +@node Using +@chapter Using +@cindex using libiberty +@cindex libiberty usage +@cindex how to use + +@c THIS SECTION IS CRAP AND NEEDS REWRITING BADLY. + +To date, @libib{} is generally not installed on its own. It has evolved +over years but does not have its own version number nor release schedule. + +Possibly the easiest way to use @libib{} in your projects is to drop the +@libib{} code into your project's sources, and to build the library along +with your own sources; the library would then be linked in at the end. This +prevents any possible version mismatches with other copies of libiberty +elsewhere on the system. + +Passing @option{--enable-install-libiberty} to the @command{configure} +script when building @libib{} causes the header files and archive library +to be installed when @kbd{make install} is run. This option also takes +an (optional) argument to specify the installation location, in the same +manner as @option{--prefix}. + +For your own projects, an approach which offers stability and flexibility +is to include @libib{} with your code, but allow the end user to optionally +choose to use a previously-installed version instead. In this way the +user may choose (for example) to install @libib{} as part of GCC, and use +that version for all software built with that compiler. (This approach +has proven useful with software using the GNU @code{readline} library.) + +Making use of @libib{} code usually requires that you include one or more +header files from the @libib{} distribution. (They will be named as +necessary in the function descriptions.) At link time, you will need to +add @option{-liberty} to your link command invocation. + + +@node Overview +@chapter Overview + +Functions contained in @libib{} can be divided into three general categories. + + +@menu +* Supplemental Functions:: Providing functions which don't exist + on older operating systems. + +* Replacement Functions:: These functions are sometimes buggy or + unpredictable on some operating systems. + +* Extensions:: Functions which provide useful extensions + or safety wrappers around existing code. +@end menu + +@node Supplemental Functions +@section Supplemental Functions +@cindex supplemental functions +@cindex functions, supplemental +@cindex functions, missing + +Certain operating systems do not provide functions which have since +become standardized, or at least common. For example, the Single +Unix Specification Version 2 requires that the @code{basename} +function be provided, but an OS which predates that specification +might not have this function. This should not prevent well-written +code from running on such a system. + +Similarly, some functions exist only among a particular ``flavor'' +or ``family'' of operating systems. As an example, the @code{bzero} +function is often not present on systems outside the BSD-derived +family of systems. + +Many such functions are provided in @libib{}. They are quickly +listed here with little description, as systems which lack them +become less and less common. Each function @var{foo} is implemented +in @file{@var{foo}.c} but not declared in any @libib{} header file; more +comments and caveats for each function's implementation are often +available in the source file. Generally, the function can simply +be declared as @code{extern}. + + + +@node Replacement Functions +@section Replacement Functions +@cindex replacement functions +@cindex functions, replacement + +Some functions have extremely limited implementations on different +platforms. Other functions are tedious to use correctly; for example, +proper use of @code{malloc} calls for the return value to be checked and +appropriate action taken if memory has been exhausted. A group of +``replacement functions'' is available in @libib{} to address these issues +for some of the most commonly used subroutines. + +All of these functions are declared in the @file{libiberty.h} header +file. Many of the implementations will use preprocessor macros set by +GNU Autoconf, if you decide to make use of that program. Some of these +functions may call one another. + + +@menu +* Memory Allocation:: Testing and handling failed memory + requests automatically. +* Exit Handlers:: Calling routines on program exit. +* Error Reporting:: Mapping errno and signal numbers to + more useful string formats. +@end menu + +@node Memory Allocation +@subsection Memory Allocation +@cindex memory allocation + +The functions beginning with the letter @samp{x} are wrappers around +standard functions; the functions provided by the system environment +are called and their results checked before the results are passed back +to client code. If the standard functions fail, these wrappers will +terminate the program. Thus, these versions can be used with impunity. + + +@node Exit Handlers +@subsection Exit Handlers +@cindex exit handlers + +The existence and implementation of the @code{atexit} routine varies +amongst the flavors of Unix. @libib{} provides an unvarying dependable +implementation via @code{xatexit} and @code{xexit}. + + +@node Error Reporting +@subsection Error Reporting +@cindex error reporting + +These are a set of routines to facilitate programming with the system +@code{errno} interface. The @libib{} source file @file{strerror.c} +contains a good deal of documentation for these functions. + +@c signal stuff + + +@node Extensions +@section Extensions +@cindex extensions +@cindex functions, extension + +@libib{} includes additional functionality above and beyond standard +functions, which has proven generically useful in GNU programs, such as +obstacks and regex. These functions are often copied from other +projects as they gain popularity, and are included here to provide a +central location from which to use, maintain, and distribute them. + +@menu +* Obstacks:: Stacks of arbitrary objects. +@end menu + +@c This is generated from the glibc manual using contrib/make-obstacks-texi.pl +@include obstacks.texi + +@node Functions +@chapter Function, Variable, and Macro Listing. +@include functions.texi + +@node Licenses +@appendix Licenses + +@menu + +* Library Copying:: The GNU Library General Public License +* BSD:: Regents of the University of California + +@end menu + +@c This takes care of Library Copying. It is the copying-lib.texi from the +@c GNU web site, with its @node line altered to make makeinfo shut up. +@include copying-lib.texi + +@page +@node BSD +@appendixsec BSD + +Copyright @copyright{} 1990 Regents of the University of California. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions +are met: + +@enumerate + +@item +Redistributions of source code must retain the above copyright +notice, this list of conditions and the following disclaimer. + +@item +Redistributions in binary form must reproduce the above copyright +notice, this list of conditions and the following disclaimer in the +documentation and/or other materials provided with the distribution. + +@item +[rescinded 22 July 1999] + +@item +Neither the name of the University nor the names of its contributors +may be used to endorse or promote products derived from this software +without specific prior written permission. + +@end enumerate + +THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +SUCH DAMAGE. + +@node Index +@unnumbered Index + +@printindex cp + +@bye diff -pruN 16.3-5/libiberty/obstacks.texi 16.3-5ubuntu1/libiberty/obstacks.texi --- 16.3-5/libiberty/obstacks.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libiberty/obstacks.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,774 @@ +@node Obstacks +@subsection Obstacks +@cindex obstacks + +An @dfn{obstack} is a pool of memory containing a stack of objects. You +can create any number of separate obstacks, and then allocate objects in +specified obstacks. Within each obstack, the last object allocated must +always be the first one freed, but distinct obstacks are independent of +each other. + +Aside from this one constraint of order of freeing, obstacks are totally +general: an obstack can contain any number of objects of any size. They +are implemented with macros, so allocation is usually very fast as long as +the objects are usually small. And the only space overhead per object is +the padding needed to start each object on a suitable boundary. + +@menu +* Creating Obstacks:: How to declare an obstack in your program. +* Preparing for Obstacks:: Preparations needed before you can + use obstacks. +* Allocation in an Obstack:: Allocating objects in an obstack. +* Freeing Obstack Objects:: Freeing objects in an obstack. +* Obstack Functions:: The obstack functions are really macros. +* Growing Objects:: Making an object bigger by stages. +* Extra Fast Growing:: Extra-high-efficiency (though more + complicated) growing objects. +* Status of an Obstack:: Inquiries about the status of an obstack. +* Obstacks Data Alignment:: Controlling alignment of objects in obstacks. +* Obstack Chunks:: How obstacks obtain and release chunks; + efficiency considerations. +* Summary of Obstacks:: +@end menu + +@node Creating Obstacks +@subsubsection Creating Obstacks + +The utilities for manipulating obstacks are declared in the header +file @file{obstack.h}. +@pindex obstack.h + +@comment obstack.h +@comment GNU +@deftp {Data Type} {struct obstack} +An obstack is represented by a data structure of type @code{struct +obstack}. This structure has a small fixed size; it records the status +of the obstack and how to find the space in which objects are allocated. +It does not contain any of the objects themselves. You should not try +to access the contents of the structure directly; use only the macros +described in this chapter. +@end deftp + +You can declare variables of type @code{struct obstack} and use them as +obstacks, or you can allocate obstacks dynamically like any other kind +of object. Dynamic allocation of obstacks allows your program to have a +variable number of different stacks. (You can even allocate an +obstack structure in another obstack, but this is rarely useful.) + +All the macros that work with obstacks require you to specify which +obstack to use. You do this with a pointer of type @code{struct obstack +*}. In the following, we often say ``an obstack'' when strictly +speaking the object at hand is such a pointer. + +The objects in the obstack are packed into large blocks called +@dfn{chunks}. The @code{struct obstack} structure points to a chain of +the chunks currently in use. + +The obstack library obtains a new chunk whenever you allocate an object +that won't fit in the previous chunk. Since the obstack library manages +chunks automatically, you don't need to pay much attention to them, but +you do need to supply a function which the obstack library should use to +get a chunk. Usually you supply a function which uses @code{malloc} +directly or indirectly. You must also supply a function to free a chunk. +These matters are described in the following section. + +@node Preparing for Obstacks +@subsubsection Preparing for Using Obstacks + +Each source file in which you plan to use obstacks +must include the header file @file{obstack.h}, like this: + +@smallexample +#include +@end smallexample + +@findex obstack_chunk_alloc +@findex obstack_chunk_free +Also, if the source file uses the macro @code{obstack_init}, it must +declare or define two macros that will be called by the +obstack library. One, @code{obstack_chunk_alloc}, is used to allocate +the chunks of memory into which objects are packed. The other, +@code{obstack_chunk_free}, is used to return chunks when the objects in +them are freed. These macros should appear before any use of obstacks +in the source file. + +Usually these are defined to use @code{malloc} via the intermediary +@code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with +the following pair of macro definitions: + +@smallexample +#define obstack_chunk_alloc xmalloc +#define obstack_chunk_free free +@end smallexample + +@noindent +Though the memory you get using obstacks really comes from @code{malloc}, +using obstacks is faster because @code{malloc} is called less often, for +larger blocks of memory. @xref{Obstack Chunks}, for full details. + +At run time, before the program can use a @code{struct obstack} object +as an obstack, it must initialize the obstack by calling +@code{obstack_init} or one of its variants, @code{obstack_begin}, +@code{obstack_specify_allocation}, or +@code{obstack_specify_allocation_with_arg}. + +@comment obstack.h +@comment GNU +@deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) +Initialize obstack @var{obstack-ptr} for allocation of objects. This +macro calls the obstack's @code{obstack_chunk_alloc} function. If +allocation of memory fails, the function pointed to by +@code{obstack_alloc_failed_handler} is called. The @code{obstack_init} +macro always returns 1 (Compatibility notice: Former versions of +obstack returned 0 if allocation failed). +@end deftypefun + +Here are two examples of how to allocate the space for an obstack and +initialize it. First, an obstack that is a static variable: + +@smallexample +static struct obstack myobstack; +@dots{} +obstack_init (&myobstack); +@end smallexample + +@noindent +Second, an obstack that is itself dynamically allocated: + +@smallexample +struct obstack *myobstack_ptr + = (struct obstack *) xmalloc (sizeof (struct obstack)); + +obstack_init (myobstack_ptr); +@end smallexample + +@comment obstack.h +@comment GNU +@deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) +Like @code{obstack_init}, but specify chunks to be at least +@var{chunk_size} bytes in size. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) +Like @code{obstack_init}, specifying chunk size, chunk +alignment, and memory allocation functions. A @var{chunk_size} or +@var{alignment} of zero results in the default size or alignment +respectively being used. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) +Like @code{obstack_specify_allocation}, but specifying memory +allocation functions that take an extra first argument, @var{arg}. +@end deftypefun + +@comment obstack.h +@comment GNU +@defvar obstack_alloc_failed_handler +The value of this variable is a pointer to a function that +@code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate +memory. The default action is to print a message and abort. +You should supply a function that either calls @code{exit} +(@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) +or @code{longjmp} and doesn't return. + +@smallexample +void my_obstack_alloc_failed (void) +@dots{} +obstack_alloc_failed_handler = &my_obstack_alloc_failed; +@end smallexample + +@end defvar + +@node Allocation in an Obstack +@subsubsection Allocation in an Obstack +@cindex allocation (obstacks) + +The most direct way to allocate an object in an obstack is with +@code{obstack_alloc}, which is invoked almost like @code{malloc}. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) +This allocates an uninitialized block of @var{size} bytes in an obstack +and returns its address. Here @var{obstack-ptr} specifies which obstack +to allocate the block in; it is the address of the @code{struct obstack} +object which represents the obstack. Each obstack macro +requires you to specify an @var{obstack-ptr} as the first argument. + +This macro calls the obstack's @code{obstack_chunk_alloc} function if +it needs to allocate a new chunk of memory; it calls +@code{obstack_alloc_failed_handler} if allocation of memory by +@code{obstack_chunk_alloc} failed. +@end deftypefun + +For example, here is a function that allocates a copy of a string @var{str} +in a specific obstack, which is in the variable @code{string_obstack}: + +@smallexample +struct obstack string_obstack; + +char * +copystring (char *string) +@{ + size_t len = strlen (string) + 1; + char *s = (char *) obstack_alloc (&string_obstack, len); + memcpy (s, string, len); + return s; +@} +@end smallexample + +To allocate a block with specified contents, use the macro @code{obstack_copy}. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +This allocates a block and initializes it by copying @var{size} +bytes of data starting at @var{address}. It calls +@code{obstack_alloc_failed_handler} if allocation of memory by +@code{obstack_chunk_alloc} failed. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Like @code{obstack_copy}, but appends an extra byte containing a null +character. This extra byte is not counted in the argument @var{size}. +@end deftypefun + +The @code{obstack_copy0} macro is convenient for copying a sequence +of characters into an obstack as a null-terminated string. Here is an +example of its use: + +@smallexample +char * +obstack_savestring (char *addr, size_t size) +@{ + return obstack_copy0 (&myobstack, addr, size); +@} +@end smallexample + +@noindent +Contrast this with the previous example of @code{savestring} using +@code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). + +@node Freeing Obstack Objects +@subsubsection Freeing Objects in an Obstack +@cindex freeing (obstacks) + +To free an object allocated in an obstack, use the macro +@code{obstack_free}. Since the obstack is a stack of objects, freeing +one object automatically frees all other objects allocated more recently +in the same obstack. + +@comment obstack.h +@comment GNU +@deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +If @var{object} is a null pointer, everything allocated in the obstack +is freed. Otherwise, @var{object} must be the address of an object +allocated in the obstack. Then @var{object} is freed, along with +everything allocated in @var{obstack} since @var{object}. +@end deftypefun + +Note that if @var{object} is a null pointer, the result is an +uninitialized obstack. To free all memory in an obstack but leave it +valid for further allocation, call @code{obstack_free} with the address +of the first object allocated on the obstack: + +@smallexample +obstack_free (obstack_ptr, first_object_allocated_ptr); +@end smallexample + +Recall that the objects in an obstack are grouped into chunks. When all +the objects in a chunk become free, the obstack library automatically +frees the chunk (@pxref{Preparing for Obstacks}). Then other +obstacks, or non-obstack allocation, can reuse the space of the chunk. + +@node Obstack Functions +@subsubsection Obstack Functions and Macros +@cindex macros + +The interfaces for using obstacks are shown here as functions to +specify the return type and argument types, but they are really +defined as macros. This means that the arguments don't actually have +types, but they generally behave as if they have the types shown. +You can call these macros like functions, but you cannot use them in +any other way (for example, you cannot take their address). + +Calling the macros requires a special precaution: namely, the first +operand (the obstack pointer) may not contain any side effects, because +it may be computed more than once. For example, if you write this: + +@smallexample +obstack_alloc (get_obstack (), 4); +@end smallexample + +@noindent +you will find that @code{get_obstack} may be called several times. +If you use @code{*obstack_list_ptr++} as the obstack pointer argument, +you will get very strange results since the incrementation may occur +several times. + +If you use the GNU C compiler, this precaution is not necessary, because +various language extensions in GNU C permit defining the macros so as to +compute each argument only once. + +Note that arguments other than the first will only be evaluated once, +even when not using GNU C. + +@code{obstack.h} does declare a number of functions, +@code{_obstack_begin}, @code{_obstack_begin_1}, +@code{_obstack_newchunk}, @code{_obstack_free}, and +@code{_obstack_memory_used}. You should not call these directly. + +@node Growing Objects +@subsubsection Growing Objects +@cindex growing objects (in obstacks) +@cindex changing the size of a block (obstacks) + +Because memory in obstack chunks is used sequentially, it is possible to +build up an object step by step, adding one or more bytes at a time to the +end of the object. With this technique, you do not need to know how much +data you will put in the object until you come to the end of it. We call +this the technique of @dfn{growing objects}. The special macros +for adding data to the growing object are described in this section. + +You don't need to do anything special when you start to grow an object. +Using one of the macros to add data to the object automatically +starts it. However, it is necessary to say explicitly when the object is +finished. This is done with @code{obstack_finish}. + +The actual address of the object thus built up is not known until the +object is finished. Until then, it always remains possible that you will +add so much data that the object must be copied into a new chunk. + +While the obstack is in use for a growing object, you cannot use it for +ordinary allocation of another object. If you try to do so, the space +already added to the growing object will become part of the other object. + +@comment obstack.h +@comment GNU +@deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) +The most basic macro for adding to a growing object is +@code{obstack_blank}, which adds space without initializing it. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) +To add a block of initialized space, use @code{obstack_grow}, which is +the growing-object analogue of @code{obstack_copy}. It adds @var{size} +bytes of data to the growing object, copying the contents from +@var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) +This is the growing-object analogue of @code{obstack_copy0}. It adds +@var{size} bytes copied from @var{data}, followed by an additional null +character. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) +To add one character at a time, use @code{obstack_1grow}. +It adds a single byte containing @var{c} to the growing object. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) +Adding the value of a pointer one can use +@code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes +containing the value of @var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) +A single value of type @code{int} can be added by using +@code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to +the growing object and initializes them with the value of @var{data}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) +When you are finished growing the object, use +@code{obstack_finish} to close it off and return its final address. + +Once you have finished the object, the obstack is available for ordinary +allocation or for growing another object. +@end deftypefun + +When you build an object by growing it, you will probably need to know +afterward how long it became. You need not keep track of this as you grow +the object, because you can find out the length from the obstack +with @code{obstack_object_size}, before finishing the object. + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +This macro returns the current size of the growing object, in bytes. +Remember to call @code{obstack_object_size} @emph{before} finishing the object. +After it is finished, @code{obstack_object_size} will return zero. +@end deftypefun + +If you have started growing an object and wish to cancel it, you should +finish it and then free it, like this: + +@smallexample +obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); +@end smallexample + +@noindent +This has no effect if no object was growing. + +@node Extra Fast Growing +@subsubsection Extra Fast Growing Objects +@cindex efficiency and obstacks + +The usual macros for growing objects incur overhead for checking +whether there is room for the new growth in the current chunk. If you +are frequently constructing objects in small steps of growth, this +overhead can be significant. + +You can reduce the overhead by using special ``fast growth'' +macros that grow the object without checking. In order to have a +robust program, you must do the checking yourself. If you do this checking +in the simplest way each time you are about to add data to the object, you +have not saved anything, because that is what the ordinary growth +macros do. But if you can arrange to check less often, or check +more efficiently, then you make the program faster. + +@code{obstack_room} returns the amount of room available +in the current chunk. + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr}) +This returns the number of bytes that can be added safely to the current +growing object (or to an object about to be started) in obstack +@var{obstack} using the fast growth macros. +@end deftypefun + +While you know there is room, you can use these fast growth macros +for adding data to a growing object: + +@comment obstack.h +@comment GNU +@deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) +@code{obstack_1grow_fast} adds one byte containing the +character @var{c} to the growing object in obstack @var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) +@code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} +bytes containing the value of @var{data} to the growing object in +obstack @var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) +@code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes +containing the value of @var{data} to the growing object in obstack +@var{obstack-ptr}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) +@code{obstack_blank_fast} adds @var{size} bytes to the +growing object in obstack @var{obstack-ptr} without initializing them. +@end deftypefun + +When you check for space using @code{obstack_room} and there is not +enough room for what you want to add, the fast growth macros +are not safe. In this case, simply use the corresponding ordinary +growth macro instead. Very soon this will copy the object to a +new chunk; then there will be lots of room available again. + +So, each time you use an ordinary growth macro, check afterward for +sufficient space using @code{obstack_room}. Once the object is copied +to a new chunk, there will be plenty of space again, so the program will +start using the fast growth macros again. + +Here is an example: + +@smallexample +@group +void +add_string (struct obstack *obstack, const char *ptr, size_t len) +@{ + while (len > 0) + @{ + size_t room = obstack_room (obstack); + if (room == 0) + @{ + /* @r{Not enough room. Add one character slowly,} + @r{which may copy to a new chunk and make room.} */ + obstack_1grow (obstack, *ptr++); + len--; + @} + else + @{ + if (room > len) + room = len; + /* @r{Add fast as much as we have room for.} */ + len -= room; + while (room-- > 0) + obstack_1grow_fast (obstack, *ptr++); + @} + @} +@} +@end group +@end smallexample + +@cindex shrinking objects +You can use @code{obstack_blank_fast} with a ``negative'' size +argument to make the current object smaller. Just don't try to shrink +it beyond zero length---there's no telling what will happen if you do +that. Earlier versions of obstacks allowed you to use +@code{obstack_blank} to shrink objects. This will no longer work. + +@node Status of an Obstack +@subsubsection Status of an Obstack +@cindex obstack status +@cindex status of obstack + +Here are macros that provide information on the current status of +allocation in an obstack. You can use them to learn about an object while +still growing it. + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) +This macro returns the tentative address of the beginning of the +currently growing object in @var{obstack-ptr}. If you finish the object +immediately, it will have that address. If you make it larger first, it +may outgrow the current chunk---then its address will change! + +If no object is growing, this value says where the next object you +allocate will start (once again assuming it fits in the current +chunk). +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) +This macro returns the address of the first free byte in the current +chunk of obstack @var{obstack-ptr}. This is the end of the currently +growing object. If no object is growing, @code{obstack_next_free} +returns the same value as @code{obstack_base}. +@end deftypefun + +@comment obstack.h +@comment GNU +@deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +This macro returns the size in bytes of the currently growing object. +This is equivalent to + +@smallexample +((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}))) +@end smallexample +@end deftypefun + +@node Obstacks Data Alignment +@subsubsection Alignment of Data in Obstacks +@cindex alignment (in obstacks) + +Each obstack has an @dfn{alignment boundary}; each object allocated in +the obstack automatically starts on an address that is a multiple of the +specified boundary. By default, this boundary is aligned so that +the object can hold any type of data. + +To access an obstack's alignment boundary, use the macro +@code{obstack_alignment_mask}. + +@comment obstack.h +@comment GNU +@deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +The value is a bit mask; a bit that is 1 indicates that the corresponding +bit in the address of an object should be 0. The mask value should be one +less than a power of 2; the effect is that all object addresses are +multiples of that power of 2. The default value of the mask is a value +that allows aligned objects to hold any type of data: for example, if +its value is 3, any type of data can be stored at locations whose +addresses are multiples of 4. A mask value of 0 means an object can start +on any multiple of 1 (that is, no alignment is required). + +The expansion of the macro @code{obstack_alignment_mask} is an lvalue, +so you can alter the mask by assignment. For example, this statement: + +@smallexample +obstack_alignment_mask (obstack_ptr) = 0; +@end smallexample + +@noindent +has the effect of turning off alignment processing in the specified obstack. +@end deftypefn + +Note that a change in alignment mask does not take effect until +@emph{after} the next time an object is allocated or finished in the +obstack. If you are not growing an object, you can make the new +alignment mask take effect immediately by calling @code{obstack_finish}. +This will finish a zero-length object and then do proper alignment for +the next object. + +@node Obstack Chunks +@subsubsection Obstack Chunks +@cindex efficiency of chunks +@cindex chunks + +Obstacks work by allocating space for themselves in large chunks, and +then parceling out space in the chunks to satisfy your requests. Chunks +are normally 4096 bytes long unless you specify a different chunk size. +The chunk size includes 8 bytes of overhead that are not actually used +for storing objects. Regardless of the specified size, longer chunks +will be allocated when necessary for long objects. + +The obstack library allocates chunks by calling the function +@code{obstack_chunk_alloc}, which you must define. When a chunk is no +longer needed because you have freed all the objects in it, the obstack +library frees the chunk by calling @code{obstack_chunk_free}, which you +must also define. + +These two must be defined (as macros) or declared (as functions) in each +source file that uses @code{obstack_init} (@pxref{Creating Obstacks}). +Most often they are defined as macros like this: + +@smallexample +#define obstack_chunk_alloc malloc +#define obstack_chunk_free free +@end smallexample + +Note that these are simple macros (no arguments). Macro definitions with +arguments will not work! It is necessary that @code{obstack_chunk_alloc} +or @code{obstack_chunk_free}, alone, expand into a function name if it is +not itself a function name. + +If you allocate chunks with @code{malloc}, the chunk size should be a +power of 2. The default chunk size, 4096, was chosen because it is long +enough to satisfy many typical requests on the obstack yet short enough +not to waste too much memory in the portion of the last chunk not yet used. + +@comment obstack.h +@comment GNU +@deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) +This returns the chunk size of the given obstack. +@end deftypefn + +Since this macro expands to an lvalue, you can specify a new chunk size by +assigning it a new value. Doing so does not affect the chunks already +allocated, but will change the size of chunks allocated for that particular +obstack in the future. It is unlikely to be useful to make the chunk size +smaller, but making it larger might improve efficiency if you are +allocating many objects whose size is comparable to the chunk size. Here +is how to do so cleanly: + +@smallexample +if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) + obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; +@end smallexample + +@node Summary of Obstacks +@subsubsection Summary of Obstack Macros + +Here is a summary of all the macros associated with obstacks. Each +takes the address of an obstack (@code{struct obstack *}) as its first +argument. + +@table @code +@item int obstack_init (struct obstack *@var{obstack-ptr}) +Initialize use of an obstack. @xref{Creating Obstacks}. + +@item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) +Initialize use of an obstack, with an initial chunk of +@var{chunk_size} bytes. + +@item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) +Initialize use of an obstack, specifying intial chunk size, chunk +alignment, and memory allocation functions. + +@item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) +Like @code{obstack_specify_allocation}, but specifying memory +allocation functions that take an extra first argument, @var{arg}. + +@item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Allocate an object of @var{size} uninitialized bytes. +@xref{Allocation in an Obstack}. + +@item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Allocate an object of @var{size} bytes, with contents copied from +@var{address}. @xref{Allocation in an Obstack}. + +@item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Allocate an object of @var{size}+1 bytes, with @var{size} of them copied +from @var{address}, followed by a null character at the end. +@xref{Allocation in an Obstack}. + +@item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) +Free @var{object} (and everything allocated in the specified obstack +more recently than @var{object}). @xref{Freeing Obstack Objects}. + +@item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Add @var{size} uninitialized bytes to a growing object. +@xref{Growing Objects}. + +@item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Add @var{size} bytes, copied from @var{address}, to a growing object. +@xref{Growing Objects}. + +@item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) +Add @var{size} bytes, copied from @var{address}, to a growing object, +and then add another byte containing a null character. @xref{Growing +Objects}. + +@item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) +Add one byte containing @var{data-char} to a growing object. +@xref{Growing Objects}. + +@item void *obstack_finish (struct obstack *@var{obstack-ptr}) +Finalize the object that is growing and return its permanent address. +@xref{Growing Objects}. + +@item size_t obstack_object_size (struct obstack *@var{obstack-ptr}) +Get the current size of the currently growing object. @xref{Growing +Objects}. + +@item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) +Add @var{size} uninitialized bytes to a growing object without checking +that there is enough room. @xref{Extra Fast Growing}. + +@item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) +Add one byte containing @var{data-char} to a growing object without +checking that there is enough room. @xref{Extra Fast Growing}. + +@item size_t obstack_room (struct obstack *@var{obstack-ptr}) +Get the amount of room now available for growing the current object. +@xref{Extra Fast Growing}. + +@item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) +The mask used for aligning the beginning of an object. This is an +lvalue. @xref{Obstacks Data Alignment}. + +@item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) +The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. + +@item void *obstack_base (struct obstack *@var{obstack-ptr}) +Tentative starting address of the currently growing object. +@xref{Status of an Obstack}. + +@item void *obstack_next_free (struct obstack *@var{obstack-ptr}) +Address just after the end of the currently growing object. +@xref{Status of an Obstack}. +@end table diff -pruN 16.3-5/libsframe/doc/sframe-spec.info 16.3-5ubuntu1/libsframe/doc/sframe-spec.info --- 16.3-5/libsframe/doc/sframe-spec.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/libsframe/doc/sframe-spec.info 2025-04-20 17:24:57.000000000 +0000 @@ -0,0 +1,915 @@ +This is sframe-spec.info, produced by makeinfo version 6.8 from +sframe-spec.texi. + +Copyright (C) 2021-2024 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License, Version 3 or any +later version published by the Free Software Foundation. A copy of the +license is included in the section entitled "GNU General Public +License". + +INFO-DIR-SECTION Software development +START-INFO-DIR-ENTRY +* SFrame: (sframe-spec). The Simple Frame format. +END-INFO-DIR-ENTRY + + +File: sframe-spec.info, Node: Top, Next: Introduction, Up: (dir) + +The SFrame format +***************** + +This manual describes version 2 of the SFrame file format. SFrame +stands for Simple Frame. The SFrame format keeps track of the minimal +necessary information needed for generating stack traces: + + - Canonical Frame Address (CFA). + - Frame Pointer (FP). + - Return Address (RA). + + The reason for existence of the SFrame format is to provide a simple, +fast and low-overhead mechanism to generate stack traces. + +* Menu: + +* Introduction:: +* SFrame Section:: +* ABI/arch-specific Definition:: + +Appendices +* Generating Stack Traces using SFrame:: + +* Index:: + + +File: sframe-spec.info, Node: Introduction, Next: SFrame Section, Prev: Top, Up: Top + +1 Introduction +************** + +* Menu: + +* Overview:: +* Changes from Version 1 to Version 2:: + + +File: sframe-spec.info, Node: Overview, Next: Changes from Version 1 to Version 2, Up: Introduction + +1.1 Overview +============ + +The SFrame stack trace information is provided in a loaded section, +known as the '.sframe' section. When available, the '.sframe' section +appears in a new segment of its own, PT_GNU_SFRAME. + + The SFrame format is currently supported only for select ABIs, +namely, AMD64 and AAPCS64. + + A portion of the SFrame format follows an unaligned on-disk +representation. Some data structures, however, (namely the SFrame +header and the SFrame function descriptor entry) have elements at their +natural boundaries. All data structures are packed, unless otherwise +stated. + + The contents of the SFrame section are stored in the target +endianness, i.e., in the endianness of the system on which the section +is targeted to be used. An SFrame section reader may use the magic +number in the SFrame header to identify the endianness of the SFrame +section. + + Addresses in this specification are expressed in bytes. + + The rest of this specification describes the current version of the +format, 'SFRAME_VERSION_2', in detail. Additional sections outline the +major changes made to each previously published version of the SFrame +stack trace format. + + The associated API to decode, probe and encode the SFrame section, +provided via 'libsframe', is not accompanied here at this time. This +will be added later. + + This document is intended to be in sync with the C code in +'sframe.h'. Please report discrepancies between the two, if any. + + +File: sframe-spec.info, Node: Changes from Version 1 to Version 2, Prev: Overview, Up: Introduction + +1.2 Changes from Version 1 to Version 2 +======================================= + +The following is a list of the changes made to the SFrame stack trace +format since Version 1 was published. + + * Add an unsigned 8-bit integral field to the SFrame function + descriptor entry to encode the size of the repetitive code blocks. + Such code blocks, e.g, pltN entries, use an SFrame function + descriptor entry of type SFRAME_FDE_TYPE_PCMASK. + * Add an unsigned 16-bit integral field to the SFrame function + descriptor entry to serve as padding. This helps ensure natural + alignment for the members of the data structure. + * The above two imply that each SFrame function descriptor entry has + a fixed size of 20 bytes instead of its size of 17 bytes in SFrame + format version 1. + + SFrame version 1 is now obsolete and should not be used. + + +File: sframe-spec.info, Node: SFrame Section, Next: ABI/arch-specific Definition, Prev: Introduction, Up: Top + +2 SFrame Section +**************** + +The SFrame section consists of an SFrame header, starting with a +preamble, and two other sub-sections, namely the SFrame function +descriptor entry (SFrame FDE) sub-section, and the SFrame frame row +entry (SFrame FRE) sub-section. + +* Menu: + +* SFrame Preamble:: +* SFrame Header:: +* SFrame Function Descriptor Entries:: +* SFrame Frame Row Entries:: + + +File: sframe-spec.info, Node: SFrame Preamble, Next: SFrame Header, Up: SFrame Section + +2.1 SFrame Preamble +=================== + +The preamble is a 32-bit packed structure; the only part of the SFrame +section whose format cannot vary between versions. + + typedef struct sframe_preamble + { + uint16_t sfp_magic; + uint8_t sfp_version; + uint8_t sfp_flags; + } ATTRIBUTE_PACKED sframe_preamble; + + Every element of the SFrame preamble is naturally aligned. + + All values are stored in the endianness of the target system for +which the SFrame section is intended. Further details: + +Offset Type Name Description +------------------------------------------------------------------------------------- +0x00 'uint16_t' 'sfp_magic' The magic number for SFrame section: 0xdee2. + Defined as a macro 'SFRAME_MAGIC'. + +0x02 'uint8_t' 'sfp_version' The version number of this SFrame section. + *Note SFrame Version::, for the set of valid + values. Current version is + 'SFRAME_VERSION_2'. + +0x03 'uint8_t' 'sfp_flags' Flags (section-wide) for this SFrame + section. *Note SFrame Flags::, for the set + of valid values. + +* Menu: + +* SFrame Magic Number and Endianness:: +* SFrame Version:: +* SFrame Flags:: + + +File: sframe-spec.info, Node: SFrame Magic Number and Endianness, Next: SFrame Version, Up: SFrame Preamble + +2.1.1 SFrame Magic Number and Endianness +---------------------------------------- + +SFrame sections are stored in the target endianness of the system that +consumes them. A consumer library reading or writing SFrame sections +should detect foreign-endianness by inspecting the SFrame magic number +in the 'sfp_magic' field in the SFrame header. It may then provide +means to endian-flip the SFrame section as necessary. + + +File: sframe-spec.info, Node: SFrame Version, Next: SFrame Flags, Prev: SFrame Magic Number and Endianness, Up: SFrame Preamble + +2.1.2 SFrame Version +-------------------- + +The version of the SFrame format can be determined by inspecting +'sfp_version'. The following versions are currently valid: + +Version Name Number Description +------------------------------------------------------------------ +'SFRAME_VERSION_1' 1 First version, obsolete. +'SFRAME_VERSION_2' 2 Current version, under development. + + This document describes 'SFRAME_VERSION_2'. + + +File: sframe-spec.info, Node: SFrame Flags, Prev: SFrame Version, Up: SFrame Preamble + +2.1.3 SFrame Flags +------------------ + +The preamble contains bitflags in its 'sfp_flags' field that describe +various section-wide properties. + + The following flags are currently defined. + +Flag Versions Value Meaning +---------------------------------------------------------------------------- +'SFRAME_F_FDE_SORTED' All 0x1 Function Descriptor Entries + are sorted on PC. +'SFRAME_F_FRAME_POINTER' All 0x2 All functions in the object + file preserve frame + pointer. + + The purpose of SFRAME_F_FRAME_POINTER flag is to facilitate stack +tracers to reliably fallback on the frame pointer based stack tracing +method, if SFrame information is not present for some function in the +SFrame section. + + Further flags may be added in future. + + +File: sframe-spec.info, Node: SFrame Header, Next: SFrame Function Descriptor Entries, Prev: SFrame Preamble, Up: SFrame Section + +2.2 SFrame Header +================= + +The SFrame header is the first part of an SFrame section. It begins +with the SFrame preamble. All parts of it other than the preamble +(*note SFrame Preamble::) can vary between SFrame file versions. It +contains things that apply to the section as a whole, and offsets to the +various other sub-sections defined in the format. As with the rest of +the SFrame section, all values are stored in the endianness of the +target system. + + The two sub-sections tile the SFrame section: each section runs from +the offset given until the start of the next section. An explicit +length is given for the last sub-section, the SFrame Frame Row Entry +(SFrame FRE) sub-section. + + typedef struct sframe_header + { + sframe_preamble sfh_preamble; + uint8_t sfh_abi_arch; + int8_t sfh_cfa_fixed_fp_offset; + int8_t sfh_cfa_fixed_ra_offset; + uint8_t sfh_auxhdr_len; + uint32_t sfh_num_fdes; + uint32_t sfh_num_fres; + uint32_t sfh_fre_len; + uint32_t sfh_fdeoff; + uint32_t sfh_freoff; + } ATTRIBUTE_PACKED sframe_header; + + Every element of the SFrame header is naturally aligned. + + The sub-section offsets, namely 'sfh_fdeoff' and 'sfh_freoff', in the +SFrame header are relative to the _end_ of the SFrame header; they are +each an offset in bytes into the SFrame section where the SFrame FDE +sub-section and the SFrame FRE sub-section respectively start. + + The SFrame section contains 'sfh_num_fdes' number of fixed-length +array elements in the SFrame FDE sub-section. Each array element is of +type SFrame function descriptor entry; each providing a high-level +function description for the purpose of stack tracing. More details in +a subsequent section. *Note SFrame Function Descriptor Entries::. + + Next, the SFrame FRE sub-section, starting at offset 'sfh_fre_off', +describes the stack trace information for each function, using a total +of 'sfh_num_fres' number of variable-length array elements. Each array +element is of type SFrame frame row entry. *Note SFrame Frame Row +Entries::. + + SFrame header allows specifying explicitly the fixed offsets from +CFA, if any, from which FP or RA may be recovered. For example, in +AMD64, the stack offset of the return address is 'CFA - 8'. Since these +offsets are expected to be in close vicinity to the CFA in most ABIs, +'sfh_cfa_fixed_fp_offset' and 'sfh_cfa_fixed_ra_offset' are limited to +signed 8-bit integers. + + The SFrame format has made some provisions for supporting more +ABIs/architectures in the future. One of them is the concept of the +auxiliary SFrame header. Bytes in the auxiliary SFrame header may be +used to convey further ABI-specific information. The 'sframe_header' +structure provides an unsigned 8-bit integral field to denote the size +(in bytes) of an auxiliary SFrame header. The auxiliary SFrame header +follows right after the 'sframe_header' structure. As for the +calculation of the sub-section offsets, namely 'sfh_fdeoff' and +'sfh_freoff', the _end_ of SFrame header must be the end of the +auxiliary SFrame header, if the latter is present. + + Putting it all together: + +Offset Type Name Description +------------------------------------------------------------------------------------- +0x00 'sframe_ 'sfh_preamble' The SFrame preamble. + preamble' *Note SFrame Preamble::. + +0x04 'uint8_t' 'sfh_abi_arch' The ABI/arch identifier. + *Note SFrame ABI/arch Identifier::. + +0x05 'int8_t' 'sfh_cfa_fixed_fp_offset' The CFA fixed FP offset, if any. + +0x06 'int8_t' 'sfh_cfa_fixed_ra_offset' The CFA fixed RA offset, if any. + +0x07 'uint8_t' 'sfh_auxhdr_len' Size in bytes of the auxiliary + header that follows the + 'sframe_header' structure. + +0x08 'uint32_t' 'sfh_num_fdes' The number of SFrame FDEs in the + section. + +0x0c 'uint32_t' 'sfh_num_fres' The number of SFrame FREs in the + section. + +0x10 'uint32_t' 'sfh_fre_len' The length in bytes of the + SFrame FRE sub-section. + +0x14 'uint32_t' 'sfh_fdeoff' The offset in bytes to the + SFrame FDE sub-section. + +0x18 'uint32_t' 'sfh_freoff' The offset in bytes to the + SFrame FRE sub-section. + + +* Menu: + +* SFrame ABI/arch Identifier:: + + +File: sframe-spec.info, Node: SFrame ABI/arch Identifier, Up: SFrame Header + +2.2.1 SFrame ABI/arch Identifier +-------------------------------- + +SFrame header identifies the ABI/arch of the target system for which the +executable and hence, the stack trace information contained in the +SFrame section, is intended. There are currently three identifiable +ABI/arch values in the format. + +ABI/arch Identifier Value Description + +--------------------------------------------------------------------- +'SFRAME_ABI_AARCH64_ENDIAN_BIG' 1 AARCH64 big-endian + +'SFRAME_ABI_AARCH64_ENDIAN_LITTLE' 2 AARCH64 little-endian + +'SFRAME_ABI_AMD64_ENDIAN_LITTLE' 3 AMD64 little-endian + + + The presence of an explicit identification of ABI/arch in SFrame may +allow stack trace generators to make certain ABI/arch-specific +decisions. + + +File: sframe-spec.info, Node: SFrame Function Descriptor Entries, Next: SFrame Frame Row Entries, Prev: SFrame Header, Up: SFrame Section + +2.3 SFrame FDE +============== + +The SFrame function descriptor entry sub-section is an array of the +fixed-length SFrame function descriptor entries (SFrame FDEs). Each +SFrame FDE is a packed structure which contains information to describe +a function's stack trace information at a high-level. + + The array of SFrame FDEs is sorted on the 'sfde_func_start_address' +if the SFrame section header flag 'sfp_flags' has 'SFRAME_F_FDE_SORTED' +set. Typically (as is the case with GNU ld) a linked object or +executable will have the 'SFRAME_F_FDE_SORTED' set. This makes the job +of a stack tracer easier as it may then employ binary search schemes to +look for the pertinent SFrame FDE. + + typedef struct sframe_func_desc_entry + { + int32_t sfde_func_start_address; + uint32_t sfde_func_size; + uint32_t sfde_func_start_fre_off; + uint32_t sfde_func_num_fres; + uint8_t sfde_func_info; + uint8_t sfde_func_rep_size; + uint16_t sfde_func_padding2; + } ATTRIBUTE_PACKED sframe_func_desc_entry; + + Every element of the SFrame function descriptor entry is naturally +aligned. + + 'sfde_func_start_fre_off' is the offset to the first SFrame FRE for +the function. This offset is relative to the _end of the SFrame FDE_ +sub-section (unlike the sub-section offsets in the SFrame header, which +are relative to the _end_ of the SFrame header). + + 'sfde_func_info' is the SFrame FDE "info word", containing +information on the FRE type and the FDE type for the function *Note The +SFrame FDE Info Word::. + + Apart from the 'sfde_func_padding2', the SFrame FDE has some +currently unused bits in the SFrame FDE info word, *Note The SFrame FDE +Info Word::, that may be used for the purpose of extending the SFrame +file format specification for future ABIs. + + Following table describes each component of the SFrame FDE structure: + +Offset Type Name Description +---------------------------------------------------------------------------------------------- +0x00 'int32_t' 'sfde_func_start_address' Signed 32-bit integral field denoting the + virtual memory address of the described + function. + +0x04 'uint32_t' 'sfde_func_size' Unsigned 32-bit integral field specifying + the size of the function in bytes. + +0x08 'uint32_t' 'sfde_func_start_fre_off' Unsigned 32-bit integral field specifying + the offset in bytes of the function's + first SFrame FRE in the SFrame section. + +0x0c 'uint32_t' 'sfde_func_num_fres' Unsigned 32-bit integral field specifying + the total number of SFrame FREs used for + the function. + +0x10 'uint8_t' 'sfde_func_info' Unsigned 8-bit integral field specifying + the SFrame FDE info word. + *Note The SFrame FDE Info Word::. + +0x11 'uint8_t' 'sfde_func_rep_size' Unsigned 8-bit integral field specifying + the size of the repetitive code block for + which an SFrame FDE of type + SFRAME_FDE_TYPE_PCMASK is used. For + example, in AMD64, the size of a pltN + entry is 16 bytes. + +0x12 'uint16_t' 'sfde_func_padding2' Padding of 2 bytes. Currently unused + bytes. + + +* Menu: + +* The SFrame FDE Info Word:: +* The SFrame FDE Types:: +* The SFrame FRE Types:: + + +File: sframe-spec.info, Node: The SFrame FDE Info Word, Next: The SFrame FDE Types, Up: SFrame Function Descriptor Entries + +2.3.1 The SFrame FDE Info Word +------------------------------ + +The info word is a bitfield split into three parts. From MSB to LSB: + +Bit offset Name Description +---------------------------------------------------------------------------------------- +7-6 'unused' Unused bits. + +5 'pauth_key' (For AARCH64) Specify which key is used for signing the + return addresses in the SFrame FDE. Two possible values: + SFRAME_AARCH64_PAUTH_KEY_A (0), or + SFRAME_AARCH64_PAUTH_KEY_B (1). + Ununsed in AMD64. + +4 'fdetype' Specify the SFrame FDE type. Two possible values: + SFRAME_FDE_TYPE_PCMASK (1), or + SFRAME_FDE_TYPE_PCINC (0). + *Note The SFrame FDE Types::. + +0-3 'fretype' Choice of three SFrame FRE types. + *Note The SFrame FRE Types::. + + +File: sframe-spec.info, Node: The SFrame FDE Types, Next: The SFrame FRE Types, Prev: The SFrame FDE Info Word, Up: SFrame Function Descriptor Entries + +2.3.2 The SFrame FDE Types +-------------------------- + +The SFrame format defines two types of FDE entries. The choice of which +SFrame FDE type to use is made based on the instruction patterns in the +relevant program stub. + + An SFrame FDE of type 'SFRAME_FDE_TYPE_PCINC' is an indication that +the PCs in the FREs should be treated as increments in bytes. This is +used fo the the bulk of the executable code of a program, which contains +instructions with no specific pattern. + + In contrast, an SFrame FDE of type 'SFRAME_FDE_TYPE_PCMASK' is an +indication that the PCs in the FREs should be treated as masks. This +type is useful for the cases where a small pattern of instructions in a +program stub is used repeatedly for a specific functionality. Typical +usecases are pltN entries and trampolines. + +Name of SFrame FDE Value Description +type +--------------------------------------------------------------------------- +SFRAME_FDE_TYPE_PCINC 0 Stacktracers perform a + (PC >= FRE_START_ADDR) to look up a + matching FRE. + +SFRAME_FDE_TYPE_PCMASK 1 Stacktracers perform a + (PC % REP_BLOCK_SIZE + >= FRE_START_ADDR) to look up a + matching FRE. REP_BLOCK_SIZE is the + size in bytes of the repeating block of + program instructions and is encoded via + 'sfde_func_rep_size' in the SFrame FDE. + + + +File: sframe-spec.info, Node: The SFrame FRE Types, Prev: The SFrame FDE Types, Up: SFrame Function Descriptor Entries + +2.3.3 The SFrame FRE Types +-------------------------- + +A real world application can have functions of size big and small. +SFrame format defines three types of SFrame FRE entries to effeciently +encode the stack trace information for such a variety of function sizes. +These representations vary in the number of bits needed to encode the +start address offset in the SFrame FRE. + + The following constants are defined and used to identify the SFrame +FRE types: + +Name Value Description + +------------------------------------------------------------------------------- +'SFRAME_FRE_TYPE_ADDR1' 0 The start address offset (in bytes) of the + SFrame FRE is an unsigned 8-bit value. + +'SFRAME_FRE_TYPE_ADDR2' 1 The start address offset (in bytes) of the + SFrame FRE is an unsigned 16-bit value. + +'SFRAME_FRE_TYPE_ADDR4' 2 The start address offset (in bytes) of the + SFrame FRE is an unsigned 32-bit value. + + A single function must use the same type of SFrame FRE throughout. +The identifier to reflect the chosen SFrame FRE type is stored in the +'fretype' bits in the SFrame FDE info word, *Note The SFrame FDE Info +Word::. + + +File: sframe-spec.info, Node: SFrame Frame Row Entries, Prev: SFrame Function Descriptor Entries, Up: SFrame Section + +2.4 SFrame FRE +============== + +The SFrame frame row entry sub-section contains the core of the stack +trace information. An SFrame frame row entry (FRE) is a self-sufficient +record containing SFrame stack trace information for a range of +contiguous (instruction) addresses, starting at the specified offset +from the start of the function. + + Each SFrame FRE encodes the stack offsets to recover the CFA, FP and +RA (where applicable) for the respective instruction addresses. To +encode this information, each SFrame FRE is followed by S*N bytes, +where: + + - 'S' is the size of a stack offset for the FRE, and + - 'N' is the number of stack offsets in the FRE + + The entities 'S', 'N' are encoded in the SFrame FRE info word, via +the 'fre_offset_size' and the 'fre_offset_count' respectively. More +information about the precise encoding and range of values for 'S' and +'N' is provided later in the *Note The SFrame FRE Info Word::. + + It is important to underline here that although the canonical +interpretation of these bytes is as stack offsets (to recover CFA, FP +and RA), these bytes _may_ be used by future ABIs/architectures to +convey other information on a per SFrame FRE basis. + + In summary, SFrame file format, by design, supports a variable number +of stack offsets at the tail end of each SFrame FRE. To keep the SFrame +file format specification flexible yet extensible, the interpretation of +the stack offsets is ABI/arch-specific. The precise interpretation of +the FRE stack offsets in the currently supported ABIs/architectures is +covered in the ABI/arch-specific definition of the SFrame file format, +*Note ABI/arch-specific Definition::. + + Next, the definitions of the three SFrame FRE types are as follows: + + typedef struct sframe_frame_row_entry_addr1 + { + uint8_t sfre_start_address; + sframe_fre_info sfre_info; + } ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; + + typedef struct sframe_frame_row_entry_addr2 + { + uint16_t sfre_start_address; + sframe_fre_info sfre_info; + } ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; + + typedef struct sframe_frame_row_entry_addr4 + { + uint32_t sfre_start_address; + sframe_fre_info sfre_info; + } ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; + + For ensuring compactness, SFrame frame row entries are stored +unaligned on disk. Appropriate mechanisms need to be employed, as +necessary, by the serializing and deserializing entities, if unaligned +accesses need to be avoided. + + 'sfre_start_address' is an unsigned 8-bit/16-bit/32-bit integral +field identifies the start address of the range of program counters, for +which the SFrame FRE applies. The value encoded in the +'sfre_start_address' field is the offset in bytes of the start address +of the SFrame FRE, from the start address of the function. + + Further SFrame FRE types may be added in future. + +* Menu: + +* The SFrame FRE Info Word:: + + +File: sframe-spec.info, Node: The SFrame FRE Info Word, Up: SFrame Frame Row Entries + +2.4.1 The SFrame FRE Info Word +------------------------------ + +The SFrame FRE info word is a bitfield split into four parts. From MSB +to LSB: + +Bit offset Name Description +------------------------------------------------------------------------------------- +7 'fre_mangled_ra_p' Indicate whether the return address is + mangled with any authorization bits (signed + RA). + +5-6 'fre_offset_size' Size of stack offsets in bytes. Valid values + are: + SFRAME_FRE_OFFSET_1B, + SFRAME_FRE_OFFSET_2B, and + SFRAME_FRE_OFFSET_4B. + +1-4 'fre_offset_count' A max value of 15 is allowed. Typically, a + value of upto 3 is sufficient for most ABIs + to track all three of CFA, FP and RA. + +0 'fre_cfa_base_reg_id' Distinguish between SP or FP based CFA + recovery. + + +Name Value Description + +-------------------------------------------------------------------------------- +'SFRAME_FRE_OFFSET_1B' 0 All stack offsets following the fixed-length + FRE structure are 1 byte long. + +'SFRAME_FRE_OFFSET_2B' 1 All stack offsets following the fixed-length + FRE structure are 2 bytes long. + +'SFRAME_FRE_OFFSET_4B' 2 All stack offsets following the fixed-length + FRE structure are 4 bytes long. + + + +File: sframe-spec.info, Node: ABI/arch-specific Definition, Next: Generating Stack Traces using SFrame, Prev: SFrame Section, Up: Top + +3 ABI/arch-specific Definition +****************************** + +This section covers the ABI/arch-specific definition of the SFrame file +format. + + Currently, the only part of the SFrame file format definition that is +ABI/arch-specific is the interpretation of the variable number of bytes +at the tail end of each SFrame FRE. Currently, these bytes are only used +for representing stack offsets (for all the currently supported ABIs). +It is recommended to peruse this section along with *Note SFrame Frame +Row Entries:: for clarity of context. + + Future ABIs must specify the algorithm for identifying the +appropriate SFrame FRE stack offsets in this chapter. This should +inevitably include the blueprint for interpreting the variable number of +bytes at the tail end of the SFrame FRE for the specific ABI/arch. Any +further provisions, e.g., using the auxiliary SFrame header, etc., if +used, must also be outlined here. + +* Menu: + +* AMD64:: +* AArch64:: + + +File: sframe-spec.info, Node: AMD64, Next: AArch64, Up: ABI/arch-specific Definition + +3.1 AMD64 +========= + +Irrespective of the ABI, the first stack offset is always used to locate +the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. The +identification of the 'BASE_REG' is done by using the +'fre_cfa_base_reg_id' field in the SFrame FRE info word. + + In AMD64, the return address (RA) is always saved on stack when a +function call is executed. Further, AMD64 ABI mandates that the RA be +saved at a 'fixed offset' from the CFA when entering a new function. +This means that the RA does not need to be tracked per SFrame FRE. The +fixed offset is encoded in the SFrame file format in the field +'sfh_cfa_fixed_ra_offset' in the SFrame header. *Note SFrame Header::. + + Hence, the second stack offset (in the SFrame FRE), when present, +will be used to locate the FP, by interpreting it as: FP = CFA + +offset2. + + Hence, in summary: + +Offset ID Interpretation in AMD64 +----------------------------------------------- +1 CFA = 'BASE_REG' + offset1 +2 FP = CFA + offset2 + + +File: sframe-spec.info, Node: AArch64, Prev: AMD64, Up: ABI/arch-specific Definition + +3.2 AArch64 +=========== + +Irrespective of the ABI, the first stack offset is always used to locate +the CFA, by interpreting it as: CFA = 'BASE_REG' + offset1. The +identification of the 'BASE_REG' is done by using the +'fre_cfa_base_reg_id' field in the SFrame FRE info word. + + In AARCH64, the AAPCS64 standard specifies that the Frame Record +saves both FP and LR (a.k.a the RA). However, the standard does not +mandate the precise location in the function where the frame record is +created, if at all. Hence the need to track RA in the SFrame stack +trace format. As RA is being tracked in this ABI, the second stack +offset is always used to locate the RA, by interpreting it as: RA = CFA ++ offset2. The third stack offset will be used to locate the FP, by +interpreting it as: FP = CFA + offset3. + + Given the nature of things, the number of stack offsets seen on +AARCH64 per SFrame FRE is either 1 or 3. + + Hence, in summary: + +Offset ID Interpretation in AArch64 +--------------------------------------------- +1 CFA = 'BASE_REG' + offset1 +2 RA = CFA + offset2 +3 FP = CFA + offset3 + + +File: sframe-spec.info, Node: Generating Stack Traces using SFrame, Next: Index, Prev: ABI/arch-specific Definition, Up: Top + +Appendix A Generating Stack Traces using SFrame +*********************************************** + +Using some C-like pseudocode, this section highlights how SFrame +provides a simple, fast and low-overhead mechanism to generate stack +traces. Needless to say that for generating accurate and useful stack +traces, several other aspects will need attention: finding and decoding +bits of SFrame section(s) in the program binary, symbolization of +addresses, to name a few. + + In the current context, a 'frame' is the abstract construct that +encapsulates the following information: + - program counter (PC), + - stack pointer (SP), and + - frame pointer (FP) + + With that said, establishing the first 'frame' should be trivial: + + // frame 0 + frame->pc = current_IP; + frame->sp = get_reg_value (REG_SP); + frame->fp = get_reg_value (REG_FP); + + where 'REG_SP' and 'REG_FP' are are ABI-designated stack pointer and +frame pointer registers respectively. + + Next, given frame N, generating stack trace needs us to get frame +N+1. This can be done as follows: + + // Get the PC, SP, and FP for frame N. + pc = frame->pc; + sp = frame->sp; + fp = frame->fp; + // Populate frame N+1. + int err = get_next_frame (&next_frame, pc, sp, fp); + + where given the values of the program counter, stack pointer and +frame pointer from frame N, 'get_next_frame' populates the provided +'next_frame' object and returns the error code, if any. In the +following pseudocode for 'get_next_frame', the 'sframe_*' functions +fetch information from the SFrame section. + + fre = sframe_find_fre (pc); + if (fre) + // Whether the base register for CFA tracking is REG_FP. + base_reg_val = sframe_fre_base_reg_fp_p (fre) ? fp : sp; + // Get the CFA stack offset from the FRE. + cfa_offset = sframe_fre_get_cfa_offset (fre); + // Get the fixed RA offset or FRE stack offset as applicable. + ra_offset = sframe_fre_get_ra_offset (fre); + // Get the fixed FP offset or FRE stack offset as applicable. + fp_offset = sframe_fre_get_fp_offset (fre); + + cfa = base_reg_val + cfa_offset; + next_frame->sp = cfa; + + ra_stack_loc = cfa + ra_offset; + // Get the address stored in the stack location. + next_frame->pc = read_value (ra_stack_loc); + + if (fp_offset is VALID) + fp_stack_loc = cfa + fp_offset; + // Get the value stored in the stack location. + next_frame->fp = read_value (fp_stack_loc); + else + // Continue to use the value of fp as it has not + // been clobbered by the current frame yet. + next_frame->fp = fp; + else + ret = ERR_NO_SFRAME_FRE; + + +File: sframe-spec.info, Node: Index, Prev: Generating Stack Traces using SFrame, Up: Top + +Index +***** + +[index] +* Menu: + +* ABI/arch-specific Definition: ABI/arch-specific Definition. + (line 6) +* Changes from Version 1 to Version 2: Changes from Version 1 to Version 2. + (line 6) +* endianness: SFrame Magic Number and Endianness. + (line 6) +* Introduction: Introduction. (line 6) +* Overview: Overview. (line 6) +* Provisions for future ABIs: SFrame Header. (line 59) +* Provisions for future ABIs <1>: SFrame Function Descriptor Entries. + (line 41) +* Provisions for future ABIs <2>: SFrame Frame Row Entries. + (line 25) +* SFrame ABI/arch Identifier: SFrame ABI/arch Identifier. + (line 6) +* SFrame FDE: SFrame Function Descriptor Entries. + (line 6) +* SFrame Flags: SFrame Flags. (line 6) +* SFrame FRE: SFrame Frame Row Entries. + (line 6) +* SFrame header: SFrame Header. (line 6) +* SFrame magic number: SFrame Magic Number and Endianness. + (line 6) +* SFrame preamble: SFrame Preamble. (line 6) +* SFrame Section: SFrame Section. (line 6) +* SFrame versions: SFrame Version. (line 9) +* SFRAME_ABI_AARCH64_ENDIAN_BIG: SFrame ABI/arch Identifier. + (line 13) +* SFRAME_ABI_AARCH64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. + (line 16) +* SFRAME_ABI_AMD64_ENDIAN_LITTLE: SFrame ABI/arch Identifier. + (line 18) +* SFRAME_FDE_TYPE_PCINC: The SFrame FDE Types. (line 6) +* SFRAME_FDE_TYPE_PCMASK: The SFrame FDE Types. (line 6) +* SFRAME_FRE_OFFSET_1B: The SFrame FRE Info Word. + (line 31) +* SFRAME_FRE_OFFSET_2B: The SFrame FRE Info Word. + (line 35) +* SFRAME_FRE_OFFSET_4B: The SFrame FRE Info Word. + (line 38) +* SFRAME_FRE_TYPE_ADDR1: The SFrame FRE Types. (line 17) +* SFRAME_FRE_TYPE_ADDR2: The SFrame FRE Types. (line 21) +* SFRAME_FRE_TYPE_ADDR4: The SFrame FRE Types. (line 24) +* SFRAME_F_FDE_SORTED: SFrame Flags. (line 11) +* SFRAME_F_FRAME_POINTER: SFrame Flags. (line 14) +* SFRAME_MAGIC: SFrame Preamble. (line 24) +* SFRAME_VERSION_1: SFrame Version. (line 9) +* The SFrame FDE Info Word: SFrame Function Descriptor Entries. + (line 85) +* The SFrame FRE Info Word: SFrame Frame Row Entries. + (line 74) + + + +Tag Table: +Node: Top564 +Node: Introduction1232 +Node: Overview1418 +Node: Changes from Version 1 to Version 22984 +Node: SFrame Section3955 +Node: SFrame Preamble4454 +Node: SFrame Magic Number and Endianness6021 +Node: SFrame Version6553 +Node: SFrame Flags7130 +Node: SFrame Header8145 +Node: SFrame ABI/arch Identifier13571 +Node: SFrame Function Descriptor Entries14599 +Node: The SFrame FDE Info Word19043 +Node: The SFrame FDE Types20257 +Node: The SFrame FRE Types22079 +Node: SFrame Frame Row Entries23567 +Node: The SFrame FRE Info Word26619 +Node: ABI/arch-specific Definition28697 +Node: AMD6429792 +Node: AArch6430892 +Node: Generating Stack Traces using SFrame32101 +Node: Index35122 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/libsframe/doc/sframe-spec.texi 16.3-5ubuntu1/libsframe/doc/sframe-spec.texi --- 16.3-5/libsframe/doc/sframe-spec.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/libsframe/doc/sframe-spec.texi 2025-04-20 17:22:06.000000000 +0000 @@ -1 +1,916 @@ +\input texinfo @c -*- Texinfo -*- +@setfilename sframe-spec.info +@settitle The SFrame Format +@copying +Copyright @copyright{} 2021-2024 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU General Public License, Version 3 or any +later version published by the Free Software Foundation. A copy of the +license is included in the section entitled ``GNU General Public +License''. + +@end copying + +@dircategory Software development +@direntry +* SFrame: (sframe-spec). The Simple Frame format. +@end direntry + +@titlepage +@title The SFrame Format +@subtitle Version 2 +@author Indu Bhagat + +@page +@vskip 0pt plus 1filll +@insertcopying +@end titlepage +@contents + +@ifnottex +@node Top +@top The SFrame format + +This manual describes version 2 of the SFrame file format. SFrame stands for +Simple Frame. The SFrame format keeps track of the minimal necessary +information needed for generating stack traces: + +@itemize @minus +@item +Canonical Frame Address (CFA). +@item +Frame Pointer (FP). +@item +Return Address (RA). +@end itemize + +The reason for existence of the SFrame format is to provide a simple, fast and +low-overhead mechanism to generate stack traces. + +@menu +* Introduction:: +* SFrame Section:: +* ABI/arch-specific Definition:: + +Appendices +* Generating Stack Traces using SFrame:: + +* Index:: +@end menu + +@end ifnottex + +@node Introduction +@chapter Introduction +@cindex Introduction + +@menu +* Overview:: +* Changes from Version 1 to Version 2:: +@end menu + +@node Overview +@section Overview +@cindex Overview + +The SFrame stack trace information is provided in a loaded section, known as the +@code{.sframe} section. When available, the @code{.sframe} section appears in +a new segment of its own, PT_GNU_SFRAME. + +The SFrame format is currently supported only for select ABIs, namely, AMD64 +and AAPCS64. + +A portion of the SFrame format follows an unaligned on-disk representation. +Some data structures, however, (namely the SFrame header and the SFrame +function descriptor entry) have elements at their natural boundaries. All data +structures are packed, unless otherwise stated. + +The contents of the SFrame section are stored in the target endianness, i.e., +in the endianness of the system on which the section is targeted to be used. +An SFrame section reader may use the magic number in the SFrame header to +identify the endianness of the SFrame section. + +Addresses in this specification are expressed in bytes. + +The rest of this specification describes the current version of the format, +@code{SFRAME_VERSION_2}, in detail. Additional sections outline the major +changes made to each previously published version of the SFrame stack trace +format. + +The associated API to decode, probe and encode the SFrame section, provided via +@code{libsframe}, is not accompanied here at this time. This will be added +later. + +This document is intended to be in sync with the C code in @file{sframe.h}. +Please report discrepancies between the two, if any. + +@node Changes from Version 1 to Version 2 +@section Changes from Version 1 to Version 2 +@cindex Changes from Version 1 to Version 2 + +The following is a list of the changes made to the SFrame stack trace format +since Version 1 was published. + +@itemize @bullet +@item +Add an unsigned 8-bit integral field to the SFrame function descriptor entry to +encode the size of the repetitive code blocks. Such code blocks, e.g, pltN +entries, use an SFrame function descriptor entry of type +SFRAME_FDE_TYPE_PCMASK. +@item +Add an unsigned 16-bit integral field to the SFrame function descriptor entry +to serve as padding. This helps ensure natural alignment for the members of +the data structure. +@item +The above two imply that each SFrame function descriptor entry has a fixed size +of 20 bytes instead of its size of 17 bytes in SFrame format version 1. +@end itemize + +SFrame version 1 is now obsolete and should not be used. + +@node SFrame Section +@chapter SFrame Section +@cindex SFrame Section + +The SFrame section consists of an SFrame header, starting with a preamble, and +two other sub-sections, namely the SFrame function descriptor entry (SFrame +FDE) sub-section, and the SFrame frame row entry (SFrame FRE) sub-section. + +@menu +* SFrame Preamble:: +* SFrame Header:: +* SFrame Function Descriptor Entries:: +* SFrame Frame Row Entries:: +@end menu + +@node SFrame Preamble +@section SFrame Preamble +@cindex SFrame preamble + +The preamble is a 32-bit packed structure; the only part of the SFrame section +whose format cannot vary between versions. + +@example +typedef struct sframe_preamble +@{ + uint16_t sfp_magic; + uint8_t sfp_version; + uint8_t sfp_flags; +@} ATTRIBUTE_PACKED sframe_preamble; +@end example + +Every element of the SFrame preamble is naturally aligned. + +All values are stored in the endianness of the target system for which the +SFrame section is intended. Further details: + +@multitable {Offset} {@code{uint16_t}} {@code{sfp_version}} {The magic number for SFrame section: 0xdee2.} +@headitem Offset @tab Type @tab Name @tab Description +@item 0x00 +@tab @code{uint16_t} +@tab @code{sfp_magic} +@tab The magic number for SFrame section: 0xdee2. Defined as a macro @code{SFRAME_MAGIC}. +@tindex SFRAME_MAGIC + +@item 0x02 +@tab @code{uint8_t} +@tab @code{sfp_version} +@tab The version number of this SFrame section. @xref{SFrame Version}, for the +set of valid values. Current version is +@code{SFRAME_VERSION_2}. + +@item 0x03 +@tab @code{uint8_t} +@tab @code{sfp_flags} +@tab Flags (section-wide) for this SFrame section. @xref{SFrame Flags}, for the +set of valid values. +@end multitable + +@menu +* SFrame Magic Number and Endianness:: +* SFrame Version:: +* SFrame Flags:: +@end menu + +@node SFrame Magic Number and Endianness +@subsection SFrame Magic Number and Endianness + +@cindex endianness +@cindex SFrame magic number +SFrame sections are stored in the target endianness of the system that consumes +them. A consumer library reading or writing SFrame sections should detect +foreign-endianness by inspecting the SFrame magic number in the +@code{sfp_magic} field in the SFrame header. It may then provide means to +endian-flip the SFrame section as necessary. + +@node SFrame Version +@subsection SFrame Version + +The version of the SFrame format can be determined by inspecting +@code{sfp_version}. The following versions are currently valid: + +@tindex SFRAME_VERSION_1 +@cindex SFrame versions +@multitable {SFRAME_VERSION_2} {Number} {Current version, under development.} +@headitem Version Name @tab Number @tab Description +@item @code{SFRAME_VERSION_1} +@tab 1 @tab First version, obsolete. +@item @code{SFRAME_VERSION_2} +@tab 2 @tab Current version, under development. +@end multitable + +This document describes @code{SFRAME_VERSION_2}. + +@node SFrame Flags +@subsection SFrame Flags +@cindex SFrame Flags + +The preamble contains bitflags in its @code{sfp_flags} field that +describe various section-wide properties. + +The following flags are currently defined. + +@multitable {@code{SFRAME_F_FRAME_POINTER}} {Versions} {Value} {Function Descriptor Entries} +@headitem Flag @tab Versions @tab Value @tab Meaning +@tindex SFRAME_F_FDE_SORTED +@item @code{SFRAME_F_FDE_SORTED} @tab All @tab 0x1 @tab Function Descriptor +Entries are sorted on PC. +@tindex SFRAME_F_FRAME_POINTER +@item @code{SFRAME_F_FRAME_POINTER} @tab All @tab 0x2 +@tab All functions in the object file preserve frame pointer. +@end multitable + +The purpose of SFRAME_F_FRAME_POINTER flag is to facilitate stack tracers to +reliably fallback on the frame pointer based stack tracing method, if SFrame +information is not present for some function in the SFrame section. + +Further flags may be added in future. + +@node SFrame Header +@section SFrame Header +@cindex SFrame header + +The SFrame header is the first part of an SFrame section. It begins with the +SFrame preamble. All parts of it other than the preamble +(@pxref{SFrame Preamble}) can vary between SFrame file versions. It contains +things that apply to the section as a whole, and offsets to the various other +sub-sections defined in the format. As with the rest of the SFrame section, +all values are stored in the endianness of the target system. + +The two sub-sections tile the SFrame section: each section runs from the offset +given until the start of the next section. An explicit length is given for the +last sub-section, the SFrame Frame Row Entry (SFrame FRE) sub-section. + +@example +typedef struct sframe_header +@{ + sframe_preamble sfh_preamble; + uint8_t sfh_abi_arch; + int8_t sfh_cfa_fixed_fp_offset; + int8_t sfh_cfa_fixed_ra_offset; + uint8_t sfh_auxhdr_len; + uint32_t sfh_num_fdes; + uint32_t sfh_num_fres; + uint32_t sfh_fre_len; + uint32_t sfh_fdeoff; + uint32_t sfh_freoff; +@} ATTRIBUTE_PACKED sframe_header; +@end example + +Every element of the SFrame header is naturally aligned. + +The sub-section offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, in the +SFrame header are relative to the @emph{end} of the SFrame header; they are +each an offset in bytes into the SFrame section where the SFrame FDE +sub-section and the SFrame FRE sub-section respectively start. + +The SFrame section contains @code{sfh_num_fdes} number of fixed-length array +elements in the SFrame FDE sub-section. Each array element is of type SFrame +function descriptor entry; each providing a high-level function description for +the purpose of stack tracing. More details in a subsequent section. +@xref{SFrame Function Descriptor Entries}. + +Next, the SFrame FRE sub-section, starting at offset @code{sfh_fre_off}, +describes the stack trace information for each function, using a total of +@code{sfh_num_fres} number of variable-length array elements. Each array +element is of type SFrame frame row entry. +@xref{SFrame Frame Row Entries}. + +SFrame header allows specifying explicitly the fixed offsets from CFA, if any, +from which FP or RA may be recovered. For example, in AMD64, the stack offset +of the return address is @code{CFA - 8}. Since these offsets are expected to +be in close vicinity to the CFA in most ABIs, @code{sfh_cfa_fixed_fp_offset} +and @code{sfh_cfa_fixed_ra_offset} are limited to signed 8-bit integers. + +@cindex Provisions for future ABIs +The SFrame format has made some provisions for supporting more +ABIs/architectures in the future. One of them is the concept of the auxiliary +SFrame header. Bytes in the auxiliary SFrame header may be used to convey +further ABI-specific information. The @code{sframe_header} structure provides +an unsigned 8-bit integral field to denote the size (in bytes) of an auxiliary +SFrame header. The auxiliary SFrame header follows right after the +@code{sframe_header} structure. As for the calculation of the sub-section +offsets, namely @code{sfh_fdeoff} and @code{sfh_freoff}, the @emph{end} of +SFrame header must be the end of the auxiliary SFrame header, if the latter is +present. + +Putting it all together: + +@multitable {Offset} {@code{uint32_t}} {@code{sfh_cfa_fixed_fp_offset}} {The number of SFrame FREs in the} +@headitem Offset @tab Type @tab Name @tab Description +@item 0x00 +@tab @code{sframe_ @* preamble} +@tab @code{sfh_preamble} +@tab The SFrame preamble. @xref{SFrame Preamble}. + +@item 0x04 +@tab @code{uint8_t} +@tab @code{sfh_abi_arch} +@tab The ABI/arch identifier. @xref{SFrame ABI/arch Identifier}. + +@item 0x05 +@tab @code{int8_t} +@tab @code{sfh_cfa_fixed_fp_offset} +@tab The CFA fixed FP offset, if any. + +@item 0x06 +@tab @code{int8_t} +@tab @code{sfh_cfa_fixed_ra_offset} +@tab The CFA fixed RA offset, if any. + +@item 0x07 +@tab @code{uint8_t} +@tab @code{sfh_auxhdr_len} +@tab Size in bytes of the auxiliary header that follows the +@code{sframe_header} structure. + +@item 0x08 +@tab @code{uint32_t} +@tab @code{sfh_num_fdes} +@tab The number of SFrame FDEs in the section. + +@item 0x0c +@tab @code{uint32_t} +@tab @code{sfh_num_fres} +@tab The number of SFrame FREs in the section. + +@item 0x10 +@tab @code{uint32_t} +@tab @code{sfh_fre_len} +@tab The length in bytes of the SFrame FRE sub-section. + +@item 0x14 +@tab @code{uint32_t} +@tab @code{sfh_fdeoff} +@tab The offset in bytes to the SFrame FDE sub-section. + +@item 0x18 +@tab @code{uint32_t} +@tab @code{sfh_freoff} +@tab The offset in bytes to the SFrame FRE sub-section. + +@end multitable + +@menu +* SFrame ABI/arch Identifier:: +@end menu + +@node SFrame ABI/arch Identifier +@subsection SFrame ABI/arch Identifier +@cindex SFrame ABI/arch Identifier + +SFrame header identifies the ABI/arch of the target system for which the +executable and hence, the stack trace information contained in the SFrame +section, is intended. There are currently three identifiable ABI/arch values +in the format. + +@multitable {SFRAME_ABI_AARCH64_ENDIAN_LITTLE} {Value} {@code{AARCH64 little-endian}} +@headitem ABI/arch Identifier @tab Value @tab Description + +@tindex SFRAME_ABI_AARCH64_ENDIAN_BIG +@item @code{SFRAME_ABI_AARCH64_ENDIAN_BIG} +@tab 1 @tab AARCH64 big-endian + +@tindex SFRAME_ABI_AARCH64_ENDIAN_LITTLE +@item @code{SFRAME_ABI_AARCH64_ENDIAN_LITTLE} +@tab 2 @tab AARCH64 little-endian + +@tindex SFRAME_ABI_AMD64_ENDIAN_LITTLE +@item @code{SFRAME_ABI_AMD64_ENDIAN_LITTLE} +@tab 3 @tab AMD64 little-endian + +@end multitable + +The presence of an explicit identification of ABI/arch in SFrame may allow +stack trace generators to make certain ABI/arch-specific decisions. + +@node SFrame Function Descriptor Entries +@section SFrame FDE +@cindex SFrame FDE + +The SFrame function descriptor entry sub-section is an array of the +fixed-length SFrame function descriptor entries (SFrame FDEs). Each SFrame FDE +is a packed structure which contains information to describe a function's stack +trace information at a high-level. + +The array of SFrame FDEs is sorted on the @code{sfde_func_start_address} if +the SFrame section header flag @code{sfp_flags} has @code{SFRAME_F_FDE_SORTED} +set. Typically (as is the case with GNU ld) a linked object or executable +will have the @code{SFRAME_F_FDE_SORTED} set. This makes the job of a stack +tracer easier as it may then employ binary search schemes to look for the +pertinent SFrame FDE. + +@example +typedef struct sframe_func_desc_entry +@{ + int32_t sfde_func_start_address; + uint32_t sfde_func_size; + uint32_t sfde_func_start_fre_off; + uint32_t sfde_func_num_fres; + uint8_t sfde_func_info; + uint8_t sfde_func_rep_size; + uint16_t sfde_func_padding2; +@} ATTRIBUTE_PACKED sframe_func_desc_entry; +@end example + +Every element of the SFrame function descriptor entry is naturally aligned. + +@code{sfde_func_start_fre_off} is the offset to the first SFrame FRE for the +function. This offset is relative to the @emph{end of the SFrame FDE} +sub-section (unlike the sub-section offsets in the SFrame header, which are +relative to the @emph{end} of the SFrame header). + +@code{sfde_func_info} is the SFrame FDE "info word", containing information on +the FRE type and the FDE type for the function @xref{The SFrame FDE Info Word}. + +@cindex Provisions for future ABIs +Apart from the @code{sfde_func_padding2}, the SFrame FDE has some currently +unused bits in the SFrame FDE info word, @xref{The SFrame FDE Info Word}, that +may be used for the purpose of extending the SFrame file format specification +for future ABIs. + +Following table describes each component of the SFrame FDE structure: + +@multitable {Offset} {@code{uint32_t}} {@code{sfde_func_start_fre_off}} {Signed 32-bit integral field denoting the} +@headitem Offset @tab Type @tab Name @tab Description +@item 0x00 +@tab @code{int32_t} +@tab @code{sfde_func_start_address} +@tab Signed 32-bit integral field denoting the virtual memory address of the +described function. + +@item 0x04 +@tab @code{uint32_t} +@tab @code{sfde_func_size} +@tab Unsigned 32-bit integral field specifying the size of the function in +bytes. + +@item 0x08 +@tab @code{uint32_t} +@tab @code{sfde_func_start_fre_off} +@tab Unsigned 32-bit integral field specifying the offset in bytes of the +function's first SFrame FRE in the SFrame section. + +@item 0x0c +@tab @code{uint32_t} +@tab @code{sfde_func_num_fres} +@tab Unsigned 32-bit integral field specifying the total number of SFrame FREs +used for the function. + +@item 0x10 +@tab @code{uint8_t} +@tab @code{sfde_func_info} +@tab Unsigned 8-bit integral field specifying the SFrame FDE info word. +@xref{The SFrame FDE Info Word}. + +@item 0x11 +@tab @code{uint8_t} +@tab @code{sfde_func_rep_size} +@tab Unsigned 8-bit integral field specifying the size of the repetitive code +block for which an SFrame FDE of type SFRAME_FDE_TYPE_PCMASK is used. For +example, in AMD64, the size of a pltN entry is 16 bytes. + +@item 0x12 +@tab @code{uint16_t} +@tab @code{sfde_func_padding2} +@tab Padding of 2 bytes. Currently unused bytes. + +@end multitable + +@menu +* The SFrame FDE Info Word:: +* The SFrame FDE Types:: +* The SFrame FRE Types:: +@end menu + +@cindex The SFrame FDE Info Word +@node The SFrame FDE Info Word +@subsection The SFrame FDE Info Word + +The info word is a bitfield split into three parts. From MSB to LSB: + +@multitable {Bit offset} {@code{pauth_key}} {Specify which key is used for signing the return addresses} +@headitem Bit offset @tab Name @tab Description +@item 7--6 +@tab @code{unused} +@tab Unused bits. + +@item 5 +@tab @code{pauth_key} +@tab (For AARCH64) Specify which key is used for signing the return addresses +in the SFrame FDE. Two possible values: @* +SFRAME_AARCH64_PAUTH_KEY_A (0), or @* +SFRAME_AARCH64_PAUTH_KEY_B (1). @* +Ununsed in AMD64. + +@item 4 +@tab @code{fdetype} +@tab Specify the SFrame FDE type. Two possible values: @* +SFRAME_FDE_TYPE_PCMASK (1), or @* +SFRAME_FDE_TYPE_PCINC (0). @* +@xref{The SFrame FDE Types}. + +@item 0--3 +@tab @code{fretype} +@tab Choice of three SFrame FRE types. @xref{The SFrame FRE Types}. +@end multitable + +@node The SFrame FDE Types +@subsection The SFrame FDE Types +@tindex SFRAME_FDE_TYPE_PCMASK +@tindex SFRAME_FDE_TYPE_PCINC + +The SFrame format defines two types of FDE entries. The choice of which SFrame +FDE type to use is made based on the instruction patterns in the relevant +program stub. + +An SFrame FDE of type @code{SFRAME_FDE_TYPE_PCINC} is an indication that the PCs in the +FREs should be treated as increments in bytes. This is used fo the the bulk of +the executable code of a program, which contains instructions with no specific +pattern. + +In contrast, an SFrame FDE of type @code{SFRAME_FDE_TYPE_PCMASK} is an +indication that the PCs in the FREs should be treated as masks. This type is +useful for the cases where a small pattern of instructions in a program stub is +used repeatedly for a specific functionality. Typical usecases are pltN +entries and trampolines. + +@multitable {SFRAME_FDE_TYPE_PCMASK} {Value} {Unwinders perform a Unwinders perform a} +@headitem Name of SFrame FDE type @tab Value @tab Description + +@item SFRAME_FDE_TYPE_PCINC +@tab 0 @tab Stacktracers perform a @* +(PC >= FRE_START_ADDR) to look up a matching FRE. + +@item SFRAME_FDE_TYPE_PCMASK +@tab 1 @tab Stacktracers perform a @* +(PC % REP_BLOCK_SIZE @* + >= FRE_START_ADDR) +to look up a matching FRE. REP_BLOCK_SIZE is the size in bytes of the +repeating block of program instructions and is encoded via +@code{sfde_func_rep_size} in the SFrame FDE. + +@end multitable + +@node The SFrame FRE Types +@subsection The SFrame FRE Types + +A real world application can have functions of size big and small. SFrame +format defines three types of SFrame FRE entries to effeciently encode the +stack trace information for such a variety of function sizes. These +representations vary in the number of bits needed to encode the start address +offset in the SFrame FRE. + +The following constants are defined and used to identify the SFrame FRE types: + +@multitable {SFRAME_FRE_TYPE_ADDR1} {@code{Value}} {The start address offset (in bytes) of the} +@headitem Name @tab Value @tab Description + +@tindex SFRAME_FRE_TYPE_ADDR1 +@item @code{SFRAME_FRE_TYPE_ADDR1} +@tab 0 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +8-bit value. + +@tindex SFRAME_FRE_TYPE_ADDR2 +@item @code{SFRAME_FRE_TYPE_ADDR2} +@tab 1 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +16-bit value. + +@tindex SFRAME_FRE_TYPE_ADDR4 +@item @code{SFRAME_FRE_TYPE_ADDR4} +@tab 2 +@tab The start address offset (in bytes) of the SFrame FRE is an unsigned +32-bit value. +@end multitable + +A single function must use the same type of SFrame FRE throughout. The +identifier to reflect the chosen SFrame FRE type is stored in the +@code{fretype} bits in the SFrame FDE info word, +@xref{The SFrame FDE Info Word}. + +@node SFrame Frame Row Entries +@section SFrame FRE +@cindex SFrame FRE + +The SFrame frame row entry sub-section contains the core of the stack trace +information. An SFrame frame row entry (FRE) is a self-sufficient record +containing SFrame stack trace information for a range of contiguous +(instruction) addresses, starting at the specified offset from the start of the +function. + +Each SFrame FRE encodes the stack offsets to recover the CFA, FP and RA (where +applicable) for the respective instruction addresses. To encode this +information, each SFrame FRE is followed by S*N bytes, where: + +@itemize @minus +@item +@code{S} is the size of a stack offset for the FRE, and +@item +@code{N} is the number of stack offsets in the FRE +@end itemize + +The entities @code{S}, @code{N} are encoded in the SFrame FRE info word, via +the @code{fre_offset_size} and the @code{fre_offset_count} respectively. More +information about the precise encoding and range of values for @code{S} and +@code{N} is provided later in the @xref{The SFrame FRE Info Word}. + +@cindex Provisions for future ABIs +It is important to underline here that although the canonical interpretation +of these bytes is as stack offsets (to recover CFA, FP and RA), these bytes +@emph{may} be used by future ABIs/architectures to convey other information on +a per SFrame FRE basis. + +In summary, SFrame file format, by design, supports a variable number of stack +offsets at the tail end of each SFrame FRE. To keep the SFrame file +format specification flexible yet extensible, the interpretation of the stack +offsets is ABI/arch-specific. The precise interpretation of the FRE stack +offsets in the currently supported ABIs/architectures is covered in the +ABI/arch-specific definition of the SFrame file format, +@xref{ABI/arch-specific Definition}. + +Next, the definitions of the three SFrame FRE types are as follows: + +@example +typedef struct sframe_frame_row_entry_addr1 +@{ + uint8_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr1; +@end example + +@example +typedef struct sframe_frame_row_entry_addr2 +@{ + uint16_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr2; +@end example + +@example +typedef struct sframe_frame_row_entry_addr4 +@{ + uint32_t sfre_start_address; + sframe_fre_info sfre_info; +@} ATTRIBUTE_PACKED sframe_frame_row_entry_addr4; +@end example + +For ensuring compactness, SFrame frame row entries are stored unaligned on +disk. Appropriate mechanisms need to be employed, as necessary, by the +serializing and deserializing entities, if unaligned accesses need to be +avoided. + +@code{sfre_start_address} is an unsigned 8-bit/16-bit/32-bit integral field +identifies the start address of the range of program counters, for which the +SFrame FRE applies. The value encoded in the @code{sfre_start_address} field +is the offset in bytes of the start address of the SFrame FRE, from the start +address of the function. + +Further SFrame FRE types may be added in future. + +@menu +* The SFrame FRE Info Word:: +@end menu + +@cindex The SFrame FRE Info Word +@node The SFrame FRE Info Word +@subsection The SFrame FRE Info Word + +The SFrame FRE info word is a bitfield split into four parts. From MSB to LSB: + +@multitable {Bit offset} {@code{fre_cfa_base_reg_id}} {Size of stack offsets in bytes. Valid values} +@headitem Bit offset @tab Name @tab Description +@item 7 +@tab @code{fre_mangled_ra_p} +@tab Indicate whether the return address is mangled with any authorization bits (signed RA). + +@item 5-6 +@tab @code{fre_offset_size} +@tab Size of stack offsets in bytes. Valid values are: @* +SFRAME_FRE_OFFSET_1B, @* +SFRAME_FRE_OFFSET_2B, and @* +SFRAME_FRE_OFFSET_4B. + +@item 1-4 +@tab @code{fre_offset_count} +@tab A max value of 15 is allowed. Typically, a value of upto 3 is sufficient +for most ABIs to track all three of CFA, FP and RA. + +@item 0 +@tab @code{fre_cfa_base_reg_id} +@tab Distinguish between SP or FP based CFA recovery. + +@end multitable + +@multitable {SFRAME_FRE_OFFSET_4B} {@code{Value}} {All stack offsets following the fixed-length} +@headitem Name @tab Value @tab Description + +@tindex SFRAME_FRE_OFFSET_1B +@item @code{SFRAME_FRE_OFFSET_1B} +@tab 0 +@tab All stack offsets following the fixed-length FRE structure are 1 byte +long. + +@tindex SFRAME_FRE_OFFSET_2B +@item @code{SFRAME_FRE_OFFSET_2B} +@tab 1 +@tab All stack offsets following the fixed-length FRE structure are 2 bytes +long. + +@tindex SFRAME_FRE_OFFSET_4B +@item @code{SFRAME_FRE_OFFSET_4B} +@tab 2 +@tab All stack offsets following the fixed-length FRE structure are 4 bytes +long. + +@end multitable + +@node ABI/arch-specific Definition +@chapter ABI/arch-specific Definition +@cindex ABI/arch-specific Definition + +This section covers the ABI/arch-specific definition of the SFrame file format. + +Currently, the only part of the SFrame file format definition that is +ABI/arch-specific is the interpretation of the variable number of bytes at the +tail end of each SFrame FRE. Currently, these bytes are only used for +representing stack offsets (for all the currently supported ABIs). It is +recommended to peruse this section along with @xref{SFrame Frame Row Entries} +for clarity of context. + +Future ABIs must specify the algorithm for identifying the appropriate SFrame +FRE stack offsets in this chapter. This should inevitably include the +blueprint for interpreting the variable number of bytes at the tail end of the +SFrame FRE for the specific ABI/arch. Any further provisions, e.g., using the +auxiliary SFrame header, etc., if used, must also be outlined here. + +@menu +* AMD64:: +* AArch64:: +@end menu + +@node AMD64 +@section AMD64 + +Irrespective of the ABI, the first stack offset is always used to locate the +CFA, by interpreting it as: CFA = @code{BASE_REG} + offset1. The +identification of the @code{BASE_REG} is done by using the +@code{fre_cfa_base_reg_id} field in the SFrame FRE info word. + +In AMD64, the return address (RA) is always saved on stack when a function +call is executed. Further, AMD64 ABI mandates that the RA be saved at a +@code{fixed offset} from the CFA when entering a new function. This means +that the RA does not need to be tracked per SFrame FRE. The fixed offset is +encoded in the SFrame file format in the field @code{sfh_cfa_fixed_ra_offset} +in the SFrame header. @xref{SFrame Header}. + +Hence, the second stack offset (in the SFrame FRE), when present, will be used +to locate the FP, by interpreting it as: FP = CFA + offset2. + +Hence, in summary: + +@multitable {Offset ID} {Interpretation in AMD64 in AMD64} +@headitem Offset ID @tab Interpretation in AMD64 +@item 1 @tab CFA = @code{BASE_REG} + offset1 +@item 2 @tab FP = CFA + offset2 +@end multitable + +@node AArch64 +@section AArch64 + +Irrespective of the ABI, the first stack offset is always used to locate the +CFA, by interpreting it as: CFA = @code{BASE_REG} + offset1. The +identification of the @code{BASE_REG} is done by using the +@code{fre_cfa_base_reg_id} field in the SFrame FRE info word. + +In AARCH64, the AAPCS64 standard specifies that the Frame Record saves both FP +and LR (a.k.a the RA). However, the standard does not mandate the precise +location in the function where the frame record is created, if at all. Hence +the need to track RA in the SFrame stack trace format. As RA is being tracked +in this ABI, the second stack offset is always used to locate the RA, by +interpreting it as: RA = CFA + offset2. The third stack offset will be used to +locate the FP, by interpreting it as: FP = CFA + offset3. + +Given the nature of things, the number of stack offsets seen on AARCH64 per +SFrame FRE is either 1 or 3. + +Hence, in summary: + +@multitable {Offset ID} {Interpretation in AArch64 in X} +@headitem Offset ID @tab Interpretation in AArch64 +@item 1 @tab CFA = @code{BASE_REG} + offset1 +@item 2 @tab RA = CFA + offset2 +@item 3 @tab FP = CFA + offset3 +@end multitable + +@node Generating Stack Traces using SFrame +@appendix Generating Stack Traces using SFrame + +Using some C-like pseudocode, this section highlights how SFrame provides a +simple, fast and low-overhead mechanism to generate stack traces. Needless to +say that for generating accurate and useful stack traces, several other aspects +will need attention: finding and decoding bits of SFrame section(s) in the +program binary, symbolization of addresses, to name a few. + +In the current context, a @code{frame} is the abstract construct that +encapsulates the following information: +@itemize @minus +@item +program counter (PC), +@item +stack pointer (SP), and +@item +frame pointer (FP) +@end itemize + +With that said, establishing the first @code{frame} should be trivial: + +@example + // frame 0 + frame->pc = current_IP; + frame->sp = get_reg_value (REG_SP); + frame->fp = get_reg_value (REG_FP); +@end example + +where @code{REG_SP} and @code{REG_FP} are are ABI-designated stack pointer and +frame pointer registers respectively. + +Next, given frame N, generating stack trace needs us to get frame N+1. This +can be done as follows: + +@example + // Get the PC, SP, and FP for frame N. + pc = frame->pc; + sp = frame->sp; + fp = frame->fp; + // Populate frame N+1. + int err = get_next_frame (&next_frame, pc, sp, fp); +@end example + +where given the values of the program counter, stack pointer and frame pointer +from frame N, @code{get_next_frame} populates the provided @code{next_frame} +object and returns the error code, if any. In the following pseudocode for +@code{get_next_frame}, the @code{sframe_*} functions fetch information from the +SFrame section. + +@example + fre = sframe_find_fre (pc); + if (fre) + // Whether the base register for CFA tracking is REG_FP. + base_reg_val = sframe_fre_base_reg_fp_p (fre) ? fp : sp; + // Get the CFA stack offset from the FRE. + cfa_offset = sframe_fre_get_cfa_offset (fre); + // Get the fixed RA offset or FRE stack offset as applicable. + ra_offset = sframe_fre_get_ra_offset (fre); + // Get the fixed FP offset or FRE stack offset as applicable. + fp_offset = sframe_fre_get_fp_offset (fre); + + cfa = base_reg_val + cfa_offset; + next_frame->sp = cfa; + + ra_stack_loc = cfa + ra_offset; + // Get the address stored in the stack location. + next_frame->pc = read_value (ra_stack_loc); + + if (fp_offset is VALID) + fp_stack_loc = cfa + fp_offset; + // Get the value stored in the stack location. + next_frame->fp = read_value (fp_stack_loc); + else + // Continue to use the value of fp as it has not + // been clobbered by the current frame yet. + next_frame->fp = fp; + else + ret = ERR_NO_SFRAME_FRE; +@end example + +@node Index +@unnumbered Index + +@syncodeindex tp cp +@printindex cp + +@bye diff -pruN 16.3-5/readline/readline/doc/fdl.texi 16.3-5ubuntu1/readline/readline/doc/fdl.texi --- 16.3-5/readline/readline/doc/fdl.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/fdl.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,506 @@ +@c The GNU Free Documentation License. +@center Version 1.3, 3 November 2008 + +@c This file is intended to be included within another document, +@c hence no sectioning command or @node. + +@display +Copyright @copyright{} 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. +@uref{http://fsf.org/} + +Everyone is permitted to copy and distribute verbatim copies +of this license document, but changing it is not allowed. +@end display + +@enumerate 0 +@item +PREAMBLE + +The purpose of this License is to make a manual, textbook, or other +functional and useful document @dfn{free} in the sense of freedom: to +assure everyone the effective freedom to copy and redistribute it, +with or without modifying it, either commercially or noncommercially. +Secondarily, this License preserves for the author and publisher a way +to get credit for their work, while not being considered responsible +for modifications made by others. + +This License is a kind of ``copyleft'', which means that derivative +works of the document must themselves be free in the same sense. It +complements the GNU General Public License, which is a copyleft +license designed for free software. + +We have designed this License in order to use it for manuals for free +software, because free software needs free documentation: a free +program should come with manuals providing the same freedoms that the +software does. But this License is not limited to software manuals; +it can be used for any textual work, regardless of subject matter or +whether it is published as a printed book. We recommend this License +principally for works whose purpose is instruction or reference. + +@item +APPLICABILITY AND DEFINITIONS + +This License applies to any manual or other work, in any medium, that +contains a notice placed by the copyright holder saying it can be +distributed under the terms of this License. Such a notice grants a +world-wide, royalty-free license, unlimited in duration, to use that +work under the conditions stated herein. The ``Document'', below, +refers to any such manual or work. Any member of the public is a +licensee, and is addressed as ``you''. You accept the license if you +copy, modify or distribute the work in a way requiring permission +under copyright law. + +A ``Modified Version'' of the Document means any work containing the +Document or a portion of it, either copied verbatim, or with +modifications and/or translated into another language. + +A ``Secondary Section'' is a named appendix or a front-matter section +of the Document that deals exclusively with the relationship of the +publishers or authors of the Document to the Document's overall +subject (or to related matters) and contains nothing that could fall +directly within that overall subject. (Thus, if the Document is in +part a textbook of mathematics, a Secondary Section may not explain +any mathematics.) The relationship could be a matter of historical +connection with the subject or with related matters, or of legal, +commercial, philosophical, ethical or political position regarding +them. + +The ``Invariant Sections'' are certain Secondary Sections whose titles +are designated, as being those of Invariant Sections, in the notice +that says that the Document is released under this License. If a +section does not fit the above definition of Secondary then it is not +allowed to be designated as Invariant. The Document may contain zero +Invariant Sections. If the Document does not identify any Invariant +Sections then there are none. + +The ``Cover Texts'' are certain short passages of text that are listed, +as Front-Cover Texts or Back-Cover Texts, in the notice that says that +the Document is released under this License. A Front-Cover Text may +be at most 5 words, and a Back-Cover Text may be at most 25 words. + +A ``Transparent'' copy of the Document means a machine-readable copy, +represented in a format whose specification is available to the +general public, that is suitable for revising the document +straightforwardly with generic text editors or (for images composed of +pixels) generic paint programs or (for drawings) some widely available +drawing editor, and that is suitable for input to text formatters or +for automatic translation to a variety of formats suitable for input +to text formatters. A copy made in an otherwise Transparent file +format whose markup, or absence of markup, has been arranged to thwart +or discourage subsequent modification by readers is not Transparent. +An image format is not Transparent if used for any substantial amount +of text. A copy that is not ``Transparent'' is called ``Opaque''. + +Examples of suitable formats for Transparent copies include plain +@sc{ascii} without markup, Texinfo input format, La@TeX{} input +format, @acronym{SGML} or @acronym{XML} using a publicly available +@acronym{DTD}, and standard-conforming simple @acronym{HTML}, +PostScript or @acronym{PDF} designed for human modification. Examples +of transparent image formats include @acronym{PNG}, @acronym{XCF} and +@acronym{JPG}. Opaque formats include proprietary formats that can be +read and edited only by proprietary word processors, @acronym{SGML} or +@acronym{XML} for which the @acronym{DTD} and/or processing tools are +not generally available, and the machine-generated @acronym{HTML}, +PostScript or @acronym{PDF} produced by some word processors for +output purposes only. + +The ``Title Page'' means, for a printed book, the title page itself, +plus such following pages as are needed to hold, legibly, the material +this License requires to appear in the title page. For works in +formats which do not have any title page as such, ``Title Page'' means +the text near the most prominent appearance of the work's title, +preceding the beginning of the body of the text. + +The ``publisher'' means any person or entity that distributes copies +of the Document to the public. + +A section ``Entitled XYZ'' means a named subunit of the Document whose +title either is precisely XYZ or contains XYZ in parentheses following +text that translates XYZ in another language. (Here XYZ stands for a +specific section name mentioned below, such as ``Acknowledgements'', +``Dedications'', ``Endorsements'', or ``History''.) To ``Preserve the Title'' +of such a section when you modify the Document means that it remains a +section ``Entitled XYZ'' according to this definition. + +The Document may include Warranty Disclaimers next to the notice which +states that this License applies to the Document. These Warranty +Disclaimers are considered to be included by reference in this +License, but only as regards disclaiming warranties: any other +implication that these Warranty Disclaimers may have is void and has +no effect on the meaning of this License. + +@item +VERBATIM COPYING + +You may copy and distribute the Document in any medium, either +commercially or noncommercially, provided that this License, the +copyright notices, and the license notice saying this License applies +to the Document are reproduced in all copies, and that you add no other +conditions whatsoever to those of this License. You may not use +technical measures to obstruct or control the reading or further +copying of the copies you make or distribute. However, you may accept +compensation in exchange for copies. If you distribute a large enough +number of copies you must also follow the conditions in section 3. + +You may also lend copies, under the same conditions stated above, and +you may publicly display copies. + +@item +COPYING IN QUANTITY + +If you publish printed copies (or copies in media that commonly have +printed covers) of the Document, numbering more than 100, and the +Document's license notice requires Cover Texts, you must enclose the +copies in covers that carry, clearly and legibly, all these Cover +Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on +the back cover. Both covers must also clearly and legibly identify +you as the publisher of these copies. The front cover must present +the full title with all words of the title equally prominent and +visible. You may add other material on the covers in addition. +Copying with changes limited to the covers, as long as they preserve +the title of the Document and satisfy these conditions, can be treated +as verbatim copying in other respects. + +If the required texts for either cover are too voluminous to fit +legibly, you should put the first ones listed (as many as fit +reasonably) on the actual cover, and continue the rest onto adjacent +pages. + +If you publish or distribute Opaque copies of the Document numbering +more than 100, you must either include a machine-readable Transparent +copy along with each Opaque copy, or state in or with each Opaque copy +a computer-network location from which the general network-using +public has access to download using public-standard network protocols +a complete Transparent copy of the Document, free of added material. +If you use the latter option, you must take reasonably prudent steps, +when you begin distribution of Opaque copies in quantity, to ensure +that this Transparent copy will remain thus accessible at the stated +location until at least one year after the last time you distribute an +Opaque copy (directly or through your agents or retailers) of that +edition to the public. + +It is requested, but not required, that you contact the authors of the +Document well before redistributing any large number of copies, to give +them a chance to provide you with an updated version of the Document. + +@item +MODIFICATIONS + +You may copy and distribute a Modified Version of the Document under +the conditions of sections 2 and 3 above, provided that you release +the Modified Version under precisely this License, with the Modified +Version filling the role of the Document, thus licensing distribution +and modification of the Modified Version to whoever possesses a copy +of it. In addition, you must do these things in the Modified Version: + +@enumerate A +@item +Use in the Title Page (and on the covers, if any) a title distinct +from that of the Document, and from those of previous versions +(which should, if there were any, be listed in the History section +of the Document). You may use the same title as a previous version +if the original publisher of that version gives permission. + +@item +List on the Title Page, as authors, one or more persons or entities +responsible for authorship of the modifications in the Modified +Version, together with at least five of the principal authors of the +Document (all of its principal authors, if it has fewer than five), +unless they release you from this requirement. + +@item +State on the Title page the name of the publisher of the +Modified Version, as the publisher. + +@item +Preserve all the copyright notices of the Document. + +@item +Add an appropriate copyright notice for your modifications +adjacent to the other copyright notices. + +@item +Include, immediately after the copyright notices, a license notice +giving the public permission to use the Modified Version under the +terms of this License, in the form shown in the Addendum below. + +@item +Preserve in that license notice the full lists of Invariant Sections +and required Cover Texts given in the Document's license notice. + +@item +Include an unaltered copy of this License. + +@item +Preserve the section Entitled ``History'', Preserve its Title, and add +to it an item stating at least the title, year, new authors, and +publisher of the Modified Version as given on the Title Page. If +there is no section Entitled ``History'' in the Document, create one +stating the title, year, authors, and publisher of the Document as +given on its Title Page, then add an item describing the Modified +Version as stated in the previous sentence. + +@item +Preserve the network location, if any, given in the Document for +public access to a Transparent copy of the Document, and likewise +the network locations given in the Document for previous versions +it was based on. These may be placed in the ``History'' section. +You may omit a network location for a work that was published at +least four years before the Document itself, or if the original +publisher of the version it refers to gives permission. + +@item +For any section Entitled ``Acknowledgements'' or ``Dedications'', Preserve +the Title of the section, and preserve in the section all the +substance and tone of each of the contributor acknowledgements and/or +dedications given therein. + +@item +Preserve all the Invariant Sections of the Document, +unaltered in their text and in their titles. Section numbers +or the equivalent are not considered part of the section titles. + +@item +Delete any section Entitled ``Endorsements''. Such a section +may not be included in the Modified Version. + +@item +Do not retitle any existing section to be Entitled ``Endorsements'' or +to conflict in title with any Invariant Section. + +@item +Preserve any Warranty Disclaimers. +@end enumerate + +If the Modified Version includes new front-matter sections or +appendices that qualify as Secondary Sections and contain no material +copied from the Document, you may at your option designate some or all +of these sections as invariant. To do this, add their titles to the +list of Invariant Sections in the Modified Version's license notice. +These titles must be distinct from any other section titles. + +You may add a section Entitled ``Endorsements'', provided it contains +nothing but endorsements of your Modified Version by various +parties---for example, statements of peer review or that the text has +been approved by an organization as the authoritative definition of a +standard. + +You may add a passage of up to five words as a Front-Cover Text, and a +passage of up to 25 words as a Back-Cover Text, to the end of the list +of Cover Texts in the Modified Version. Only one passage of +Front-Cover Text and one of Back-Cover Text may be added by (or +through arrangements made by) any one entity. If the Document already +includes a cover text for the same cover, previously added by you or +by arrangement made by the same entity you are acting on behalf of, +you may not add another; but you may replace the old one, on explicit +permission from the previous publisher that added the old one. + +The author(s) and publisher(s) of the Document do not by this License +give permission to use their names for publicity for or to assert or +imply endorsement of any Modified Version. + +@item +COMBINING DOCUMENTS + +You may combine the Document with other documents released under this +License, under the terms defined in section 4 above for modified +versions, provided that you include in the combination all of the +Invariant Sections of all of the original documents, unmodified, and +list them all as Invariant Sections of your combined work in its +license notice, and that you preserve all their Warranty Disclaimers. + +The combined work need only contain one copy of this License, and +multiple identical Invariant Sections may be replaced with a single +copy. If there are multiple Invariant Sections with the same name but +different contents, make the title of each such section unique by +adding at the end of it, in parentheses, the name of the original +author or publisher of that section if known, or else a unique number. +Make the same adjustment to the section titles in the list of +Invariant Sections in the license notice of the combined work. + +In the combination, you must combine any sections Entitled ``History'' +in the various original documents, forming one section Entitled +``History''; likewise combine any sections Entitled ``Acknowledgements'', +and any sections Entitled ``Dedications''. You must delete all +sections Entitled ``Endorsements.'' + +@item +COLLECTIONS OF DOCUMENTS + +You may make a collection consisting of the Document and other documents +released under this License, and replace the individual copies of this +License in the various documents with a single copy that is included in +the collection, provided that you follow the rules of this License for +verbatim copying of each of the documents in all other respects. + +You may extract a single document from such a collection, and distribute +it individually under this License, provided you insert a copy of this +License into the extracted document, and follow this License in all +other respects regarding verbatim copying of that document. + +@item +AGGREGATION WITH INDEPENDENT WORKS + +A compilation of the Document or its derivatives with other separate +and independent documents or works, in or on a volume of a storage or +distribution medium, is called an ``aggregate'' if the copyright +resulting from the compilation is not used to limit the legal rights +of the compilation's users beyond what the individual works permit. +When the Document is included in an aggregate, this License does not +apply to the other works in the aggregate which are not themselves +derivative works of the Document. + +If the Cover Text requirement of section 3 is applicable to these +copies of the Document, then if the Document is less than one half of +the entire aggregate, the Document's Cover Texts may be placed on +covers that bracket the Document within the aggregate, or the +electronic equivalent of covers if the Document is in electronic form. +Otherwise they must appear on printed covers that bracket the whole +aggregate. + +@item +TRANSLATION + +Translation is considered a kind of modification, so you may +distribute translations of the Document under the terms of section 4. +Replacing Invariant Sections with translations requires special +permission from their copyright holders, but you may include +translations of some or all Invariant Sections in addition to the +original versions of these Invariant Sections. You may include a +translation of this License, and all the license notices in the +Document, and any Warranty Disclaimers, provided that you also include +the original English version of this License and the original versions +of those notices and disclaimers. In case of a disagreement between +the translation and the original version of this License or a notice +or disclaimer, the original version will prevail. + +If a section in the Document is Entitled ``Acknowledgements'', +``Dedications'', or ``History'', the requirement (section 4) to Preserve +its Title (section 1) will typically require changing the actual +title. + +@item +TERMINATION + +You may not copy, modify, sublicense, or distribute the Document +except as expressly provided under this License. Any attempt +otherwise to copy, modify, sublicense, or distribute it is void, and +will automatically terminate your rights under this License. + +However, if you cease all violation of this License, then your license +from a particular copyright holder is reinstated (a) provisionally, +unless and until the copyright holder explicitly and finally +terminates your license, and (b) permanently, if the copyright holder +fails to notify you of the violation by some reasonable means prior to +60 days after the cessation. + +Moreover, your license from a particular copyright holder is +reinstated permanently if the copyright holder notifies you of the +violation by some reasonable means, this is the first time you have +received notice of violation of this License (for any work) from that +copyright holder, and you cure the violation prior to 30 days after +your receipt of the notice. + +Termination of your rights under this section does not terminate the +licenses of parties who have received copies or rights from you under +this License. If your rights have been terminated and not permanently +reinstated, receipt of a copy of some or all of the same material does +not give you any rights to use it. + +@item +FUTURE REVISIONS OF THIS LICENSE + +The Free Software Foundation may publish new, revised versions +of the GNU Free Documentation License from time to time. Such new +versions will be similar in spirit to the present version, but may +differ in detail to address new problems or concerns. See +@uref{http://www.gnu.org/copyleft/}. + +Each version of the License is given a distinguishing version number. +If the Document specifies that a particular numbered version of this +License ``or any later version'' applies to it, you have the option of +following the terms and conditions either of that specified version or +of any later version that has been published (not as a draft) by the +Free Software Foundation. If the Document does not specify a version +number of this License, you may choose any version ever published (not +as a draft) by the Free Software Foundation. If the Document +specifies that a proxy can decide which future versions of this +License can be used, that proxy's public statement of acceptance of a +version permanently authorizes you to choose that version for the +Document. + +@item +RELICENSING + +``Massive Multiauthor Collaboration Site'' (or ``MMC Site'') means any +World Wide Web server that publishes copyrightable works and also +provides prominent facilities for anybody to edit those works. A +public wiki that anybody can edit is an example of such a server. A +``Massive Multiauthor Collaboration'' (or ``MMC'') contained in the +site means any set of copyrightable works thus published on the MMC +site. + +``CC-BY-SA'' means the Creative Commons Attribution-Share Alike 3.0 +license published by Creative Commons Corporation, a not-for-profit +corporation with a principal place of business in San Francisco, +California, as well as future copyleft versions of that license +published by that same organization. + +``Incorporate'' means to publish or republish a Document, in whole or +in part, as part of another Document. + +An MMC is ``eligible for relicensing'' if it is licensed under this +License, and if all works that were first published under this License +somewhere other than this MMC, and subsequently incorporated in whole +or in part into the MMC, (1) had no cover texts or invariant sections, +and (2) were thus incorporated prior to November 1, 2008. + +The operator of an MMC Site may republish an MMC contained in the site +under CC-BY-SA on the same site at any time before August 1, 2009, +provided the MMC is eligible for relicensing. + +@end enumerate + +@page +@heading ADDENDUM: How to use this License for your documents + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and +license notices just after the title page: + +@smallexample +@group + Copyright (C) @var{year} @var{your name}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. +@end group +@end smallexample + +If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, +replace the ``with@dots{}Texts.'' line with this: + +@smallexample +@group + with the Invariant Sections being @var{list their titles}, with + the Front-Cover Texts being @var{list}, and with the Back-Cover Texts + being @var{list}. +@end group +@end smallexample + +If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + +If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of +free software license, such as the GNU General Public License, +to permit their use in free software. + +@c Local Variables: +@c ispell-local-pdict: "ispell-dict" +@c End: diff -pruN 16.3-5/readline/readline/doc/history.info 16.3-5ubuntu1/readline/readline/doc/history.info --- 16.3-5/readline/readline/doc/history.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/history.info 2025-04-20 17:25:31.000000000 +0000 @@ -0,0 +1,1426 @@ +This is history.info, produced by makeinfo version 6.8 from +history.texi. + +This document describes the GNU History library (version 8.2, 19 +September 2022), a programming tool that provides a consistent user +interface for recalling lines of previously typed input. + + Copyright (C) 1988-2022 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + +INFO-DIR-SECTION Libraries +START-INFO-DIR-ENTRY +* History: (history). The GNU history library API. +END-INFO-DIR-ENTRY + + +File: history.info, Node: Top, Next: Using History Interactively, Up: (dir) + +GNU History Library +******************* + +This document describes the GNU History library, a programming tool that +provides a consistent user interface for recalling lines of previously +typed input. + +* Menu: + +* Using History Interactively:: GNU History User's Manual. +* Programming with GNU History:: GNU History Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. + + +File: history.info, Node: Using History Interactively, Next: Programming with GNU History, Prev: Top, Up: Top + +1 Using History Interactively +***************************** + +This chapter describes how to use the GNU History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the GNU History Library in your own programs, *note +(history)Programming with GNU History::. + +* Menu: + +* History Interaction:: What it feels like using History as a user. + + +File: history.info, Node: History Interaction, Up: Using History Interactively + +1.1 History Expansion +===================== + +The History library provides a history expansion feature that is similar +to the history expansion provided by 'csh'. This section describes the +syntax used to manipulate the history information. + + History expansions introduce words from the history list into the +input stream, making it easy to repeat commands, insert the arguments to +a previous command into the current input line, or fix errors in +previous commands quickly. + + History expansion takes place in two parts. The first is to +determine which line from the history list should be used during +substitution. The second is to select portions of that line for +inclusion into the current one. The line selected from the history is +called the "event", and the portions of that line that are acted upon +are called "words". Various "modifiers" are available to manipulate the +selected words. The line is broken into words in the same fashion that +Bash does, so that several words surrounded by quotes are considered one +word. History expansions are introduced by the appearance of the +history expansion character, which is '!' by default. + + History expansion implements shell-like quoting conventions: a +backslash can be used to remove the special handling for the next +character; single quotes enclose verbatim sequences of characters, and +can be used to inhibit history expansion; and characters enclosed within +double quotes may be subject to history expansion, since backslash can +escape the history expansion character, but single quotes may not, since +they are not treated specially within double quotes. + +* Menu: + +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. + + +File: history.info, Node: Event Designators, Next: Word Designators, Up: History Interaction + +1.1.1 Event Designators +----------------------- + +An event designator is a reference to a command line entry in the +history list. Unless the reference is absolute, events are relative to +the current position in the history list. + +'!' + Start a history substitution, except when followed by a space, tab, + the end of the line, or '='. + +'!N' + Refer to command line N. + +'!-N' + Refer to the command N lines back. + +'!!' + Refer to the previous command. This is a synonym for '!-1'. + +'!STRING' + Refer to the most recent command preceding the current position in + the history list starting with STRING. + +'!?STRING[?]' + Refer to the most recent command preceding the current position in + the history list containing STRING. The trailing '?' may be + omitted if the STRING is followed immediately by a newline. If + STRING is missing, the string from the most recent search is used; + it is an error if there is no previous search string. + +'^STRING1^STRING2^' + Quick Substitution. Repeat the last command, replacing STRING1 + with STRING2. Equivalent to '!!:s^STRING1^STRING2^'. + +'!#' + The entire command line typed so far. + + +File: history.info, Node: Word Designators, Next: Modifiers, Prev: Event Designators, Up: History Interaction + +1.1.2 Word Designators +---------------------- + +Word designators are used to select desired words from the event. A ':' +separates the event specification from the word designator. It may be +omitted if the word designator begins with a '^', '$', '*', '-', or '%'. +Words are numbered from the beginning of the line, with the first word +being denoted by 0 (zero). Words are inserted into the current line +separated by single spaces. + + For example, + +'!!' + designates the preceding command. When you type this, the + preceding command is repeated in toto. + +'!!:$' + designates the last argument of the preceding command. This may be + shortened to '!$'. + +'!fi:2' + designates the second argument of the most recent command starting + with the letters 'fi'. + + Here are the word designators: + +'0 (zero)' + The '0'th word. For many applications, this is the command word. + +'N' + The Nth word. + +'^' + The first argument; that is, word 1. + +'$' + The last argument. + +'%' + The first word matched by the most recent '?STRING?' search, if the + search string begins with a character that is part of a word. + +'X-Y' + A range of words; '-Y' abbreviates '0-Y'. + +'*' + All of the words, except the '0'th. This is a synonym for '1-$'. + It is not an error to use '*' if there is just one word in the + event; the empty string is returned in that case. + +'X*' + Abbreviates 'X-$' + +'X-' + Abbreviates 'X-$' like 'X*', but omits the last word. If 'x' is + missing, it defaults to 0. + + If a word designator is supplied without an event specification, the +previous command is used as the event. + + +File: history.info, Node: Modifiers, Prev: Word Designators, Up: History Interaction + +1.1.3 Modifiers +--------------- + +After the optional word designator, you can add a sequence of one or +more of the following modifiers, each preceded by a ':'. These modify, +or edit, the word or words selected from the history event. + +'h' + Remove a trailing pathname component, leaving only the head. + +'t' + Remove all leading pathname components, leaving the tail. + +'r' + Remove a trailing suffix of the form '.SUFFIX', leaving the + basename. + +'e' + Remove all but the trailing suffix. + +'p' + Print the new command but do not execute it. + +'s/OLD/NEW/' + Substitute NEW for the first occurrence of OLD in the event line. + Any character may be used as the delimiter in place of '/'. The + delimiter may be quoted in OLD and NEW with a single backslash. If + '&' appears in NEW, it is replaced by OLD. A single backslash will + quote the '&'. If OLD is null, it is set to the last OLD + substituted, or, if no previous history substitutions took place, + the last STRING in a !?STRING'[?]' search. If NEW is null, each + matching OLD is deleted. The final delimiter is optional if it is + the last character on the input line. + +'&' + Repeat the previous substitution. + +'g' +'a' + Cause changes to be applied over the entire event line. Used in + conjunction with 's', as in 'gs/OLD/NEW/', or with '&'. + +'G' + Apply the following 's' or '&' modifier once to each word in the + event. + + +File: history.info, Node: Programming with GNU History, Next: GNU Free Documentation License, Prev: Using History Interactively, Up: Top + +2 Programming with GNU History +****************************** + +This chapter describes how to interface programs that you write with the +GNU History Library. It should be considered a technical guide. For +information on the interactive use of GNU History, *note Using History +Interactively::. + +* Menu: + +* Introduction to History:: What is the GNU History library for? +* History Storage:: How information is stored. +* History Functions:: Functions that you can use. +* History Variables:: Variables that control behaviour. +* History Programming Example:: Example of using the GNU History Library. + + +File: history.info, Node: Introduction to History, Next: History Storage, Up: Programming with GNU History + +2.1 Introduction to History +=========================== + +Many programs read input from the user a line at a time. The GNU +History library is able to keep track of those lines, associate +arbitrary data with each line, and utilize information from previous +lines in composing new ones. + + A programmer using the History library has available functions for +remembering lines on a history list, associating arbitrary data with a +line, removing lines from the list, searching through the list for a +line containing an arbitrary text string, and referencing any line in +the list directly. In addition, a history "expansion" function is +available which provides for a consistent user interface across +different programs. + + The user using programs written with the History library has the +benefit of a consistent user interface with a set of well-known commands +for manipulating the text of previous lines and using that text in new +commands. The basic history manipulation commands are similar to the +history substitution provided by 'csh'. + + The programmer can also use the Readline library, which includes some +history manipulation by default, and has the added advantage of command +line editing. + + Before declaring any functions using any functionality the History +library provides in other code, an application writer should include the +file '' in any file that uses the History library's +features. It supplies extern declarations for all of the library's +public functions and variables, and declares all of the public data +structures. + + +File: history.info, Node: History Storage, Next: History Functions, Prev: Introduction to History, Up: Programming with GNU History + +2.2 History Storage +=================== + +The history list is an array of history entries. A history entry is +declared as follows: + + typedef void *histdata_t; + + typedef struct _hist_entry { + char *line; + char *timestamp; + histdata_t data; + } HIST_ENTRY; + + The history list itself might therefore be declared as + + HIST_ENTRY **the_history_list; + + The state of the History library is encapsulated into a single +structure: + + /* + * A structure used to pass around the current state of the history. + */ + typedef struct _hist_state { + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; + } HISTORY_STATE; + + If the flags member includes 'HS_STIFLED', the history has been +stifled. + + +File: history.info, Node: History Functions, Next: History Variables, Prev: History Storage, Up: Programming with GNU History + +2.3 History Functions +===================== + +This section describes the calling sequence for the various functions +exported by the GNU History library. + +* Menu: + +* Initializing History and State Management:: Functions to call when you + want to use history in a + program. +* History List Management:: Functions used to manage the list + of history entries. +* Information About the History List:: Functions returning information about + the history list. +* Moving Around the History List:: Functions used to change the position + in the history list. +* Searching the History List:: Functions to search the history list + for entries containing a string. +* Managing the History File:: Functions that read and write a file + containing the history list. +* History Expansion:: Functions to perform csh-like history + expansion. + + +File: history.info, Node: Initializing History and State Management, Next: History List Management, Up: History Functions + +2.3.1 Initializing History and State Management +----------------------------------------------- + +This section describes functions used to initialize and manage the state +of the History library when you want to use the history functions in +your program. + + -- Function: void using_history (void) + Begin a session in which the history functions might be used. This + initializes the interactive variables. + + -- Function: HISTORY_STATE * history_get_history_state (void) + Return a structure describing the current state of the input + history. + + -- Function: void history_set_history_state (HISTORY_STATE *state) + Set the state of the history list according to STATE. + + +File: history.info, Node: History List Management, Next: Information About the History List, Prev: Initializing History and State Management, Up: History Functions + +2.3.2 History List Management +----------------------------- + +These functions manage individual entries on the history list, or set +parameters managing the list itself. + + -- Function: void add_history (const char *string) + Place STRING at the end of the history list. The associated data + field (if any) is set to 'NULL'. If the maximum number of history + entries has been set using 'stifle_history()', and the new number + of history entries would exceed that maximum, the oldest history + entry is removed. + + -- Function: void add_history_time (const char *string) + Change the time stamp associated with the most recent history entry + to STRING. + + -- Function: HIST_ENTRY * remove_history (int which) + Remove history entry at offset WHICH from the history. The removed + element is returned so you can free the line, data, and containing + structure. + + -- Function: histdata_t free_history_entry (HIST_ENTRY *histent) + Free the history entry HISTENT and any history library private data + associated with it. Returns the application-specific data so the + caller can dispose of it. + + -- Function: HIST_ENTRY * replace_history_entry (int which, const char + *line, histdata_t data) + Make the history entry at offset WHICH have LINE and DATA. This + returns the old entry so the caller can dispose of any + application-specific data. In the case of an invalid WHICH, a + 'NULL' pointer is returned. + + -- Function: void clear_history (void) + Clear the history list by deleting all the entries. + + -- Function: void stifle_history (int max) + Stifle the history list, remembering only the last MAX entries. + The history list will contain only MAX entries at a time. + + -- Function: int unstifle_history (void) + Stop stifling the history. This returns the previously-set maximum + number of history entries (as set by 'stifle_history()'). The + value is positive if the history was stifled, negative if it + wasn't. + + -- Function: int history_is_stifled (void) + Returns non-zero if the history is stifled, zero if it is not. + + +File: history.info, Node: Information About the History List, Next: Moving Around the History List, Prev: History List Management, Up: History Functions + +2.3.3 Information About the History List +---------------------------------------- + +These functions return information about the entire history list or +individual list entries. + + -- Function: HIST_ENTRY ** history_list (void) + Return a 'NULL' terminated array of 'HIST_ENTRY *' which is the + current input history. Element 0 of this list is the beginning of + time. If there is no history, return 'NULL'. + + -- Function: int where_history (void) + Returns the offset of the current history element. + + -- Function: HIST_ENTRY * current_history (void) + Return the history entry at the current position, as determined by + 'where_history()'. If there is no entry there, return a 'NULL' + pointer. + + -- Function: HIST_ENTRY * history_get (int offset) + Return the history entry at position OFFSET. The range of valid + values of OFFSET starts at 'history_base' and ends at + HISTORY_LENGTH - 1 (*note History Variables::). If there is no + entry there, or if OFFSET is outside the valid range, return a + 'NULL' pointer. + + -- Function: time_t history_get_time (HIST_ENTRY *entry) + Return the time stamp associated with the history entry ENTRY. If + the timestamp is missing or invalid, return 0. + + -- Function: int history_total_bytes (void) + Return the number of bytes that the primary history entries are + using. This function returns the sum of the lengths of all the + lines in the history. + + +File: history.info, Node: Moving Around the History List, Next: Searching the History List, Prev: Information About the History List, Up: History Functions + +2.3.4 Moving Around the History List +------------------------------------ + +These functions allow the current index into the history list to be set +or changed. + + -- Function: int history_set_pos (int pos) + Set the current history offset to POS, an absolute index into the + list. Returns 1 on success, 0 if POS is less than zero or greater + than the number of history entries. + + -- Function: HIST_ENTRY * previous_history (void) + Back up the current history offset to the previous history entry, + and return a pointer to that entry. If there is no previous entry, + return a 'NULL' pointer. + + -- Function: HIST_ENTRY * next_history (void) + If the current history offset refers to a valid history entry, + increment the current history offset. If the possibly-incremented + history offset refers to a valid history entry, return a pointer to + that entry; otherwise, return a 'BNULL' pointer. + + +File: history.info, Node: Searching the History List, Next: Managing the History File, Prev: Moving Around the History List, Up: History Functions + +2.3.5 Searching the History List +-------------------------------- + +These functions allow searching of the history list for entries +containing a specific string. Searching may be performed both forward +and backward from the current history position. The search may be +"anchored", meaning that the string must match at the beginning of the +history entry. + + -- Function: int history_search (const char *string, int direction) + Search the history for STRING, starting at the current history + offset. If DIRECTION is less than 0, then the search is through + previous entries, otherwise through subsequent entries. If STRING + is found, then the current history index is set to that history + entry, and the value returned is the offset in the line of the + entry where STRING was found. Otherwise, nothing is changed, and a + -1 is returned. + + -- Function: int history_search_prefix (const char *string, int + direction) + Search the history for STRING, starting at the current history + offset. The search is anchored: matching lines must begin with + STRING. If DIRECTION is less than 0, then the search is through + previous entries, otherwise through subsequent entries. If STRING + is found, then the current history index is set to that entry, and + the return value is 0. Otherwise, nothing is changed, and a -1 is + returned. + + -- Function: int history_search_pos (const char *string, int direction, + int pos) + Search for STRING in the history list, starting at POS, an absolute + index into the list. If DIRECTION is negative, the search proceeds + backward from POS, otherwise forward. Returns the absolute index + of the history element where STRING was found, or -1 otherwise. + + +File: history.info, Node: Managing the History File, Next: History Expansion, Prev: Searching the History List, Up: History Functions + +2.3.6 Managing the History File +------------------------------- + +The History library can read the history from and write it to a file. +This section documents the functions for managing a history file. + + -- Function: int read_history (const char *filename) + Add the contents of FILENAME to the history list, a line at a time. + If FILENAME is 'NULL', then read from '~/.history'. Returns 0 if + successful, or 'errno' if not. + + -- Function: int read_history_range (const char *filename, int from, + int to) + Read a range of lines from FILENAME, adding them to the history + list. Start reading at line FROM and end at TO. If FROM is zero, + start at the beginning. If TO is less than FROM, then read until + the end of the file. If FILENAME is 'NULL', then read from + '~/.history'. Returns 0 if successful, or 'errno' if not. + + -- Function: int write_history (const char *filename) + Write the current history to FILENAME, overwriting FILENAME if + necessary. If FILENAME is 'NULL', then write the history list to + '~/.history'. Returns 0 on success, or 'errno' on a read or write + error. + + -- Function: int append_history (int nelements, const char *filename) + Append the last NELEMENTS of the history list to FILENAME. If + FILENAME is 'NULL', then append to '~/.history'. Returns 0 on + success, or 'errno' on a read or write error. + + -- Function: int history_truncate_file (const char *filename, int + nlines) + Truncate the history file FILENAME, leaving only the last NLINES + lines. If FILENAME is 'NULL', then '~/.history' is truncated. + Returns 0 on success, or 'errno' on failure. + + +File: history.info, Node: History Expansion, Prev: Managing the History File, Up: History Functions + +2.3.7 History Expansion +----------------------- + +These functions implement history expansion. + + -- Function: int history_expand (char *string, char **output) + Expand STRING, placing the result into OUTPUT, a pointer to a + string (*note History Interaction::). Returns: + '0' + If no expansions took place (or, if the only change in the + text was the removal of escape characters preceding the + history expansion character); + '1' + if expansions did take place; + '-1' + if there was an error in expansion; + '2' + if the returned line should be displayed, but not executed, as + with the ':p' modifier (*note Modifiers::). + + If an error occurred in expansion, then OUTPUT contains a + descriptive error message. + + -- Function: char * get_history_event (const char *string, int *cindex, + int qchar) + Returns the text of the history event beginning at STRING + + *CINDEX. *CINDEX is modified to point to after the event + specifier. At function entry, CINDEX points to the index into + STRING where the history event specification begins. QCHAR is a + character that is allowed to end the event specification in + addition to the "normal" terminating characters. + + -- Function: char ** history_tokenize (const char *string) + Return an array of tokens parsed out of STRING, much as the shell + might. The tokens are split on the characters in the + HISTORY_WORD_DELIMITERS variable, and shell quoting conventions are + obeyed as described below. + + -- Function: char * history_arg_extract (int first, int last, const + char *string) + Extract a string segment consisting of the FIRST through LAST + arguments present in STRING. Arguments are split using + 'history_tokenize'. + + +File: history.info, Node: History Variables, Next: History Programming Example, Prev: History Functions, Up: Programming with GNU History + +2.4 History Variables +===================== + +This section describes the externally-visible variables exported by the +GNU History Library. + + -- Variable: int history_base + The logical offset of the first entry in the history list. + + -- Variable: int history_length + The number of entries currently stored in the history list. + + -- Variable: int history_max_entries + The maximum number of history entries. This must be changed using + 'stifle_history()'. + + -- Variable: int history_write_timestamps + If non-zero, timestamps are written to the history file, so they + can be preserved between sessions. The default value is 0, meaning + that timestamps are not saved. + + The current timestamp format uses the value of HISTORY_COMMENT_CHAR + to delimit timestamp entries in the history file. If that variable + does not have a value (the default), timestamps will not be + written. + + -- Variable: char history_expansion_char + The character that introduces a history event. The default is '!'. + Setting this to 0 inhibits history expansion. + + -- Variable: char history_subst_char + The character that invokes word substitution if found at the start + of a line. The default is '^'. + + -- Variable: char history_comment_char + During tokenization, if this character is seen as the first + character of a word, then it and all subsequent characters up to a + newline are ignored, suppressing history expansion for the + remainder of the line. This is disabled by default. + + -- Variable: char * history_word_delimiters + The characters that separate tokens for 'history_tokenize()'. The + default value is '" \t\n()<>;&|"'. + + -- Variable: char * history_search_delimiter_chars + The list of additional characters which can delimit a history + search string, in addition to space, TAB, ':' and '?' in the case + of a substring search. The default is empty. + + -- Variable: char * history_no_expand_chars + The list of characters which inhibit history expansion if found + immediately following HISTORY_EXPANSION_CHAR. The default is + space, tab, newline, carriage return, and '='. + + -- Variable: int history_quotes_inhibit_expansion + If non-zero, the history expansion code implements shell-like + quoting: single-quoted words are not scanned for the history + expansion character or the history comment character, and + double-quoted words may have history expansion performed, since + single quotes are not special within double quotes. The default + value is 0. + + -- Variable: int history_quoting_state + An application may set this variable to indicate that the current + line being expanded is subject to existing quoting. If set to ''', + the history expansion function will assume that the line is + single-quoted and inhibit expansion until it reads an unquoted + closing single quote; if set to '"', history expansion will assume + the line is double quoted until it reads an unquoted closing double + quote. If set to zero, the default, the history expansion function + will assume the line is not quoted and treat quote characters + within the line as described above. This is only effective if + HISTORY_QUOTES_INHIBIT_EXPANSION is set. + + -- Variable: rl_linebuf_func_t * history_inhibit_expansion_function + This should be set to the address of a function that takes two + arguments: a 'char *' (STRING) and an 'int' index into that string + (I). It should return a non-zero value if the history expansion + starting at STRING[I] should not be performed; zero if the + expansion should be done. It is intended for use by applications + like Bash that use the history expansion character for additional + purposes. By default, this variable is set to 'NULL'. + + +File: history.info, Node: History Programming Example, Prev: History Variables, Up: Programming with GNU History + +2.5 History Programming Example +=============================== + +The following program demonstrates simple use of the GNU History +Library. + + #include + #include + + main (argc, argv) + int argc; + char **argv; + { + char line[1024], *t; + int len, done = 0; + + line[0] = 0; + + using_history (); + while (!done) + { + printf ("history$ "); + fflush (stdout); + t = fgets (line, sizeof (line) - 1, stdin); + if (t && *t) + { + len = strlen (t); + if (t[len - 1] == '\n') + t[len - 1] = '\0'; + } + + if (!t) + strcpy (line, "quit"); + + if (line[0]) + { + char *expansion; + int result; + + result = history_expand (line, &expansion); + if (result) + fprintf (stderr, "%s\n", expansion); + + if (result < 0 || result == 2) + { + free (expansion); + continue; + } + + add_history (expansion); + strncpy (line, expansion, sizeof (line) - 1); + free (expansion); + } + + if (strcmp (line, "quit") == 0) + done = 1; + else if (strcmp (line, "save") == 0) + write_history ("history_file"); + else if (strcmp (line, "read") == 0) + read_history ("history_file"); + else if (strcmp (line, "list") == 0) + { + register HIST_ENTRY **the_list; + register int i; + + the_list = history_list (); + if (the_list) + for (i = 0; the_list[i]; i++) + printf ("%d: %s\n", i + history_base, the_list[i]->line); + } + else if (strncmp (line, "delete", 6) == 0) + { + int which; + if ((sscanf (line + 6, "%d", &which)) == 1) + { + HIST_ENTRY *entry = remove_history (which); + if (!entry) + fprintf (stderr, "No such entry %d\n", which); + else + { + free (entry->line); + free (entry); + } + } + else + { + fprintf (stderr, "non-numeric arg given to `delete'\n"); + } + } + } + } + + +File: history.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU History, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: history.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top + +Appendix B Concept Index +************************ + +[index] +* Menu: + +* anchored search: Searching the History List. + (line 10) +* event designators: Event Designators. (line 6) +* history events: Event Designators. (line 8) +* history expansion: History Interaction. (line 6) +* History Searching: Searching the History List. + (line 6) + + +File: history.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top + +Appendix C Function and Variable Index +************************************** + +[index] +* Menu: + +* add_history: History List Management. + (line 9) +* add_history_time: History List Management. + (line 16) +* append_history: Managing the History File. + (line 28) +* clear_history: History List Management. + (line 37) +* current_history: Information About the History List. + (line 17) +* free_history_entry: History List Management. + (line 25) +* get_history_event: History Expansion. (line 26) +* history_arg_extract: History Expansion. (line 41) +* history_base: History Variables. (line 9) +* history_comment_char: History Variables. (line 37) +* history_expand: History Expansion. (line 8) +* history_expansion_char: History Variables. (line 29) +* history_get: Information About the History List. + (line 22) +* history_get_history_state: Initializing History and State Management. + (line 14) +* history_get_time: Information About the History List. + (line 29) +* history_inhibit_expansion_function: History Variables. (line 77) +* history_is_stifled: History List Management. + (line 50) +* history_length: History Variables. (line 12) +* history_list: Information About the History List. + (line 9) +* history_max_entries: History Variables. (line 15) +* history_no_expand_chars: History Variables. (line 52) +* history_quotes_inhibit_expansion: History Variables. (line 57) +* history_quoting_state: History Variables. (line 65) +* history_search: Searching the History List. + (line 12) +* history_search_delimiter_chars: History Variables. (line 47) +* history_search_pos: Searching the History List. + (line 31) +* history_search_prefix: Searching the History List. + (line 21) +* history_set_history_state: Initializing History and State Management. + (line 18) +* history_set_pos: Moving Around the History List. + (line 9) +* history_subst_char: History Variables. (line 33) +* history_tokenize: History Expansion. (line 35) +* history_total_bytes: Information About the History List. + (line 33) +* history_truncate_file: Managing the History File. + (line 33) +* history_word_delimiters: History Variables. (line 43) +* history_write_timestamps: History Variables. (line 19) +* next_history: Moving Around the History List. + (line 19) +* previous_history: Moving Around the History List. + (line 14) +* read_history: Managing the History File. + (line 9) +* read_history_range: Managing the History File. + (line 14) +* remove_history: History List Management. + (line 20) +* replace_history_entry: History List Management. + (line 30) +* stifle_history: History List Management. + (line 40) +* unstifle_history: History List Management. + (line 44) +* using_history: Initializing History and State Management. + (line 10) +* where_history: Information About the History List. + (line 14) +* write_history: Managing the History File. + (line 22) + + + +Tag Table: +Node: Top850 +Node: Using History Interactively1495 +Node: History Interaction2012 +Node: Event Designators3910 +Node: Word Designators5184 +Node: Modifiers6944 +Node: Programming with GNU History8486 +Node: Introduction to History9230 +Node: History Storage10908 +Node: History Functions12043 +Node: Initializing History and State Management13032 +Node: History List Management13844 +Node: Information About the History List16138 +Node: Moving Around the History List17752 +Node: Searching the History List18845 +Node: Managing the History File20770 +Node: History Expansion22590 +Node: History Variables24519 +Node: History Programming Example28499 +Node: GNU Free Documentation License31176 +Node: Concept Index56348 +Node: Function and Variable Index57053 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/readline/readline/doc/history.texi 16.3-5ubuntu1/readline/readline/doc/history.texi --- 16.3-5/readline/readline/doc/history.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/history.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,85 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header (This is for running Texinfo on a region.) +@setfilename history.info +@settitle GNU History Library +@include version.texi +@c %**end of header (This is for running Texinfo on a region.) + +@copying +This document describes the GNU History library +(version @value{VERSION}, @value{UPDATED}), +a programming tool that provides a consistent user interface for +recalling lines of previously typed input. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* History: (history). The GNU history library API. +@end direntry + +@titlepage +@title GNU History Library +@subtitle Edition @value{EDITION}, for @code{History Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page + +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU History Library + +This document describes the GNU History library, a programming tool that +provides a consistent user interface for recalling lines of previously +typed input. + +@menu +* Using History Interactively:: GNU History User's Manual. +* Programming with GNU History:: GNU History Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. +@end menu +@end ifnottex + +@syncodeindex fn vr + +@include hsuser.texi +@include hstech.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@node Concept Index +@appendix Concept Index +@printindex cp + +@node Function and Variable Index +@appendix Function and Variable Index +@printindex vr + +@bye diff -pruN 16.3-5/readline/readline/doc/hstech.texi 16.3-5ubuntu1/readline/readline/doc/hstech.texi --- 16.3-5/readline/readline/doc/hstech.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/hstech.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,602 @@ +@ignore +This file documents the user interface to the GNU History library. +Copyright (C) 1988-2022 Free Software Foundation, Inc. +Authored by Brian Fox and Chet Ramey. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Programming with GNU History +@chapter Programming with GNU History + +This chapter describes how to interface programs that you write +with the @sc{gnu} History Library. +It should be considered a technical guide. +For information on the interactive use of @sc{gnu} History, @pxref{Using +History Interactively}. + +@menu +* Introduction to History:: What is the GNU History library for? +* History Storage:: How information is stored. +* History Functions:: Functions that you can use. +* History Variables:: Variables that control behaviour. +* History Programming Example:: Example of using the GNU History Library. +@end menu + +@node Introduction to History +@section Introduction to History + +Many programs read input from the user a line at a time. The @sc{gnu} +History library is able to keep track of those lines, associate arbitrary +data with each line, and utilize information from previous lines in +composing new ones. + +A programmer using the History library has available functions +for remembering lines on a history list, associating arbitrary data +with a line, removing lines from the list, searching through the list +for a line containing an arbitrary text string, and referencing any line +in the list directly. In addition, a history @dfn{expansion} function +is available which provides for a consistent user interface across +different programs. + +The user using programs written with the History library has the +benefit of a consistent user interface with a set of well-known +commands for manipulating the text of previous lines and using that text +in new commands. The basic history manipulation commands are similar to +the history substitution provided by @code{csh}. + +The programmer can also use the Readline library, which +includes some history manipulation by default, and has the added +advantage of command line editing. + +Before declaring any functions using any functionality the History +library provides in other code, an application writer should include +the file @code{} in any file that uses the +History library's features. It supplies extern declarations for all +of the library's public functions and variables, and declares all of +the public data structures. + +@node History Storage +@section History Storage + +The history list is an array of history entries. A history entry is +declared as follows: + +@example +typedef void *histdata_t; + +typedef struct _hist_entry @{ + char *line; + char *timestamp; + histdata_t data; +@} HIST_ENTRY; +@end example + +The history list itself might therefore be declared as + +@example +HIST_ENTRY **the_history_list; +@end example + +The state of the History library is encapsulated into a single structure: + +@example +/* + * A structure used to pass around the current state of the history. + */ +typedef struct _hist_state @{ + HIST_ENTRY **entries; /* Pointer to the entries themselves. */ + int offset; /* The location pointer within this array. */ + int length; /* Number of elements within this array. */ + int size; /* Number of slots allocated to this array. */ + int flags; +@} HISTORY_STATE; +@end example + +If the flags member includes @code{HS_STIFLED}, the history has been +stifled. + +@node History Functions +@section History Functions + +This section describes the calling sequence for the various functions +exported by the @sc{gnu} History library. + +@menu +* Initializing History and State Management:: Functions to call when you + want to use history in a + program. +* History List Management:: Functions used to manage the list + of history entries. +* Information About the History List:: Functions returning information about + the history list. +* Moving Around the History List:: Functions used to change the position + in the history list. +* Searching the History List:: Functions to search the history list + for entries containing a string. +* Managing the History File:: Functions that read and write a file + containing the history list. +* History Expansion:: Functions to perform csh-like history + expansion. +@end menu + +@node Initializing History and State Management +@subsection Initializing History and State Management + +This section describes functions used to initialize and manage +the state of the History library when you want to use the history +functions in your program. + +@deftypefun void using_history (void) +Begin a session in which the history functions might be used. This +initializes the interactive variables. +@end deftypefun + +@deftypefun {HISTORY_STATE *} history_get_history_state (void) +Return a structure describing the current state of the input history. +@end deftypefun + +@deftypefun void history_set_history_state (HISTORY_STATE *state) +Set the state of the history list according to @var{state}. +@end deftypefun + +@node History List Management +@subsection History List Management + +These functions manage individual entries on the history list, or set +parameters managing the list itself. + +@deftypefun void add_history (const char *string) +Place @var{string} at the end of the history list. The associated data +field (if any) is set to @code{NULL}. +If the maximum number of history entries has been set using +@code{stifle_history()}, and the new number of history entries would exceed +that maximum, the oldest history entry is removed. +@end deftypefun + +@deftypefun void add_history_time (const char *string) +Change the time stamp associated with the most recent history entry to +@var{string}. +@end deftypefun + +@deftypefun {HIST_ENTRY *} remove_history (int which) +Remove history entry at offset @var{which} from the history. The +removed element is returned so you can free the line, data, +and containing structure. +@end deftypefun + +@deftypefun {histdata_t} free_history_entry (HIST_ENTRY *histent) +Free the history entry @var{histent} and any history library private +data associated with it. Returns the application-specific data +so the caller can dispose of it. +@end deftypefun + +@deftypefun {HIST_ENTRY *} replace_history_entry (int which, const char *line, histdata_t data) +Make the history entry at offset @var{which} have @var{line} and @var{data}. +This returns the old entry so the caller can dispose of any +application-specific data. In the case +of an invalid @var{which}, a @code{NULL} pointer is returned. +@end deftypefun + +@deftypefun void clear_history (void) +Clear the history list by deleting all the entries. +@end deftypefun + +@deftypefun void stifle_history (int max) +Stifle the history list, remembering only the last @var{max} entries. +The history list will contain only @var{max} entries at a time. +@end deftypefun + +@deftypefun int unstifle_history (void) +Stop stifling the history. This returns the previously-set +maximum number of history entries (as set by @code{stifle_history()}). +The value is positive if the history was +stifled, negative if it wasn't. +@end deftypefun + +@deftypefun int history_is_stifled (void) +Returns non-zero if the history is stifled, zero if it is not. +@end deftypefun + +@node Information About the History List +@subsection Information About the History List + +These functions return information about the entire history list or +individual list entries. + +@deftypefun {HIST_ENTRY **} history_list (void) +Return a @code{NULL} terminated array of @code{HIST_ENTRY *} which is the +current input history. Element 0 of this list is the beginning of time. +If there is no history, return @code{NULL}. +@end deftypefun + +@deftypefun int where_history (void) +Returns the offset of the current history element. +@end deftypefun + +@deftypefun {HIST_ENTRY *} current_history (void) +Return the history entry at the current position, as determined by +@code{where_history()}. If there is no entry there, return a @code{NULL} +pointer. +@end deftypefun + +@deftypefun {HIST_ENTRY *} history_get (int offset) +Return the history entry at position @var{offset}. +The range of valid +values of @var{offset} starts at @code{history_base} and ends at +@var{history_length} - 1 (@pxref{History Variables}). +If there is no entry there, or if @var{offset} is outside the valid +range, return a @code{NULL} pointer. +@end deftypefun + +@deftypefun time_t history_get_time (HIST_ENTRY *entry) +Return the time stamp associated with the history entry @var{entry}. +If the timestamp is missing or invalid, return 0. +@end deftypefun + +@deftypefun int history_total_bytes (void) +Return the number of bytes that the primary history entries are using. +This function returns the sum of the lengths of all the lines in the +history. +@end deftypefun + +@node Moving Around the History List +@subsection Moving Around the History List + +These functions allow the current index into the history list to be +set or changed. + +@deftypefun int history_set_pos (int pos) +Set the current history offset to @var{pos}, an absolute index +into the list. +Returns 1 on success, 0 if @var{pos} is less than zero or greater +than the number of history entries. +@end deftypefun + +@deftypefun {HIST_ENTRY *} previous_history (void) +Back up the current history offset to the previous history entry, and +return a pointer to that entry. If there is no previous entry, return +a @code{NULL} pointer. +@end deftypefun + +@deftypefun {HIST_ENTRY *} next_history (void) +If the current history offset refers to a valid history entry, +increment the current history offset. +If the possibly-incremented history offset refers to a valid history +entry, return a pointer to that entry; +otherwise, return a @code{BNULL} pointer. +@end deftypefun + +@node Searching the History List +@subsection Searching the History List +@cindex History Searching + +These functions allow searching of the history list for entries containing +a specific string. Searching may be performed both forward and backward +from the current history position. The search may be @dfn{anchored}, +meaning that the string must match at the beginning of the history entry. +@cindex anchored search + +@deftypefun int history_search (const char *string, int direction) +Search the history for @var{string}, starting at the current history offset. +If @var{direction} is less than 0, then the search is through +previous entries, otherwise through subsequent entries. +If @var{string} is found, then +the current history index is set to that history entry, and the value +returned is the offset in the line of the entry where +@var{string} was found. Otherwise, nothing is changed, and a -1 is +returned. +@end deftypefun + +@deftypefun int history_search_prefix (const char *string, int direction) +Search the history for @var{string}, starting at the current history +offset. The search is anchored: matching lines must begin with +@var{string}. If @var{direction} is less than 0, then the search is +through previous entries, otherwise through subsequent entries. +If @var{string} is found, then the +current history index is set to that entry, and the return value is 0. +Otherwise, nothing is changed, and a -1 is returned. +@end deftypefun + +@deftypefun int history_search_pos (const char *string, int direction, int pos) +Search for @var{string} in the history list, starting at @var{pos}, an +absolute index into the list. If @var{direction} is negative, the search +proceeds backward from @var{pos}, otherwise forward. Returns the absolute +index of the history element where @var{string} was found, or -1 otherwise. +@end deftypefun + +@node Managing the History File +@subsection Managing the History File + +The History library can read the history from and write it to a file. +This section documents the functions for managing a history file. + +@deftypefun int read_history (const char *filename) +Add the contents of @var{filename} to the history list, a line at a time. +If @var{filename} is @code{NULL}, then read from @file{~/.history}. +Returns 0 if successful, or @code{errno} if not. +@end deftypefun + +@deftypefun int read_history_range (const char *filename, int from, int to) +Read a range of lines from @var{filename}, adding them to the history list. +Start reading at line @var{from} and end at @var{to}. +If @var{from} is zero, start at the beginning. If @var{to} is less than +@var{from}, then read until the end of the file. If @var{filename} is +@code{NULL}, then read from @file{~/.history}. Returns 0 if successful, +or @code{errno} if not. +@end deftypefun + +@deftypefun int write_history (const char *filename) +Write the current history to @var{filename}, overwriting @var{filename} +if necessary. +If @var{filename} is @code{NULL}, then write the history list to +@file{~/.history}. +Returns 0 on success, or @code{errno} on a read or write error. +@end deftypefun + +@deftypefun int append_history (int nelements, const char *filename) +Append the last @var{nelements} of the history list to @var{filename}. +If @var{filename} is @code{NULL}, then append to @file{~/.history}. +Returns 0 on success, or @code{errno} on a read or write error. +@end deftypefun + +@deftypefun int history_truncate_file (const char *filename, int nlines) +Truncate the history file @var{filename}, leaving only the last +@var{nlines} lines. +If @var{filename} is @code{NULL}, then @file{~/.history} is truncated. +Returns 0 on success, or @code{errno} on failure. +@end deftypefun + +@node History Expansion +@subsection History Expansion + +These functions implement history expansion. + +@deftypefun int history_expand (char *string, char **output) +Expand @var{string}, placing the result into @var{output}, a pointer +to a string (@pxref{History Interaction}). Returns: +@table @code +@item 0 +If no expansions took place (or, if the only change in +the text was the removal of escape characters preceding the history expansion +character); +@item 1 +if expansions did take place; +@item -1 +if there was an error in expansion; +@item 2 +if the returned line should be displayed, but not executed, +as with the @code{:p} modifier (@pxref{Modifiers}). +@end table + +If an error occurred in expansion, then @var{output} contains a descriptive +error message. +@end deftypefun + +@deftypefun {char *} get_history_event (const char *string, int *cindex, int qchar) +Returns the text of the history event beginning at @var{string} + +@var{*cindex}. @var{*cindex} is modified to point to after the event +specifier. At function entry, @var{cindex} points to the index into +@var{string} where the history event specification begins. @var{qchar} +is a character that is allowed to end the event specification in addition +to the ``normal'' terminating characters. +@end deftypefun + +@deftypefun {char **} history_tokenize (const char *string) +Return an array of tokens parsed out of @var{string}, much as the +shell might. The tokens are split on the characters in the +@var{history_word_delimiters} variable, +and shell quoting conventions are obeyed as described below. +@end deftypefun + +@deftypefun {char *} history_arg_extract (int first, int last, const char *string) +Extract a string segment consisting of the @var{first} through @var{last} +arguments present in @var{string}. Arguments are split using +@code{history_tokenize}. +@end deftypefun + +@node History Variables +@section History Variables + +This section describes the externally-visible variables exported by +the @sc{gnu} History Library. + +@deftypevar int history_base +The logical offset of the first entry in the history list. +@end deftypevar + +@deftypevar int history_length +The number of entries currently stored in the history list. +@end deftypevar + +@deftypevar int history_max_entries +The maximum number of history entries. This must be changed using +@code{stifle_history()}. +@end deftypevar + +@deftypevar int history_write_timestamps +If non-zero, timestamps are written to the history file, so they can be +preserved between sessions. The default value is 0, meaning that +timestamps are not saved. + +The current timestamp format uses the value of @var{history_comment_char} +to delimit timestamp entries in the history file. If that variable does +not have a value (the default), timestamps will not be written. +@end deftypevar + +@deftypevar char history_expansion_char +The character that introduces a history event. The default is @samp{!}. +Setting this to 0 inhibits history expansion. +@end deftypevar + +@deftypevar char history_subst_char +The character that invokes word substitution if found at the start of +a line. The default is @samp{^}. +@end deftypevar + +@deftypevar char history_comment_char +During tokenization, if this character is seen as the first character +of a word, then it and all subsequent characters up to a newline are +ignored, suppressing history expansion for the remainder of the line. +This is disabled by default. +@end deftypevar + +@deftypevar {char *} history_word_delimiters +The characters that separate tokens for @code{history_tokenize()}. +The default value is @code{" \t\n()<>;&|"}. +@end deftypevar + +@deftypevar {char *} history_search_delimiter_chars +The list of additional characters which can delimit a history search +string, in addition to space, TAB, @samp{:} and @samp{?} in the case of +a substring search. The default is empty. +@end deftypevar + +@deftypevar {char *} history_no_expand_chars +The list of characters which inhibit history expansion if found immediately +following @var{history_expansion_char}. The default is space, tab, newline, +carriage return, and @samp{=}. +@end deftypevar + +@deftypevar int history_quotes_inhibit_expansion +If non-zero, the history expansion code implements shell-like quoting: +single-quoted words are not scanned for the history expansion +character or the history comment character, and double-quoted words may +have history expansion performed, since single quotes are not special +within double quotes. +The default value is 0. +@end deftypevar + +@deftypevar int history_quoting_state +An application may set this variable to indicate that the current line +being expanded is subject to existing quoting. If set to @samp{'}, the +history expansion function will assume that the line is single-quoted and +inhibit expansion until it reads an unquoted closing single quote; if set +to @samp{"}, history expansion will assume the line is double quoted until +it reads an unquoted closing double quote. If set to zero, the default, +the history expansion function will assume the line is not quoted and +treat quote characters within the line as described above. +This is only effective if @var{history_quotes_inhibit_expansion} is set. +@end deftypevar + +@deftypevar {rl_linebuf_func_t *} history_inhibit_expansion_function +This should be set to the address of a function that takes two arguments: +a @code{char *} (@var{string}) +and an @code{int} index into that string (@var{i}). +It should return a non-zero value if the history expansion starting at +@var{string[i]} should not be performed; zero if the expansion should +be done. +It is intended for use by applications like Bash that use the history +expansion character for additional purposes. +By default, this variable is set to @code{NULL}. +@end deftypevar + +@node History Programming Example +@section History Programming Example + +The following program demonstrates simple use of the @sc{gnu} History Library. + +@smallexample +#include +#include + +main (argc, argv) + int argc; + char **argv; +@{ + char line[1024], *t; + int len, done = 0; + + line[0] = 0; + + using_history (); + while (!done) + @{ + printf ("history$ "); + fflush (stdout); + t = fgets (line, sizeof (line) - 1, stdin); + if (t && *t) + @{ + len = strlen (t); + if (t[len - 1] == '\n') + t[len - 1] = '\0'; + @} + + if (!t) + strcpy (line, "quit"); + + if (line[0]) + @{ + char *expansion; + int result; + + result = history_expand (line, &expansion); + if (result) + fprintf (stderr, "%s\n", expansion); + + if (result < 0 || result == 2) + @{ + free (expansion); + continue; + @} + + add_history (expansion); + strncpy (line, expansion, sizeof (line) - 1); + free (expansion); + @} + + if (strcmp (line, "quit") == 0) + done = 1; + else if (strcmp (line, "save") == 0) + write_history ("history_file"); + else if (strcmp (line, "read") == 0) + read_history ("history_file"); + else if (strcmp (line, "list") == 0) + @{ + register HIST_ENTRY **the_list; + register int i; + + the_list = history_list (); + if (the_list) + for (i = 0; the_list[i]; i++) + printf ("%d: %s\n", i + history_base, the_list[i]->line); + @} + else if (strncmp (line, "delete", 6) == 0) + @{ + int which; + if ((sscanf (line + 6, "%d", &which)) == 1) + @{ + HIST_ENTRY *entry = remove_history (which); + if (!entry) + fprintf (stderr, "No such entry %d\n", which); + else + @{ + free (entry->line); + free (entry); + @} + @} + else + @{ + fprintf (stderr, "non-numeric arg given to `delete'\n"); + @} + @} + @} +@} +@end smallexample diff -pruN 16.3-5/readline/readline/doc/hsuser.texi 16.3-5ubuntu1/readline/readline/doc/hsuser.texi --- 16.3-5/readline/readline/doc/hsuser.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/hsuser.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,535 @@ +@ignore +This file documents the user interface to the GNU History library. +Copyright (C) 1988--2022 Free Software Foundation, Inc. +Authored by Brian Fox and Chet Ramey. + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@node Using History Interactively +@chapter Using History Interactively + +@c GDB bundling modification: +@c @ifclear BashFeatures +@c @defcodeindex bt +@c @end ifclear + +@ifset BashFeatures +This chapter describes how to use the @sc{gnu} History Library +interactively, from a user's standpoint. +It should be considered a user's guide. +For information on using the @sc{gnu} History Library in other programs, +see the @sc{gnu} Readline Library Manual. +@end ifset +@ifclear BashFeatures +This chapter describes how to use the @sc{gnu} History Library interactively, +from a user's standpoint. It should be considered a user's guide. For +information on using the @sc{gnu} History Library in your own programs, +@c GDB bundling modification: +@pxref{Programming with GNU History, , , history, GNU History Library}. +@end ifclear + +@ifset BashFeatures +@menu +* Bash History Facilities:: How Bash lets you manipulate your command + history. +* Bash History Builtins:: The Bash builtin commands that manipulate + the command history. +* History Interaction:: What it feels like using History as a user. +@end menu +@end ifset +@ifclear BashFeatures +@menu +* History Interaction:: What it feels like using History as a user. +@end menu +@end ifclear + +@ifset BashFeatures +@node Bash History Facilities +@section Bash History Facilities +@cindex command history +@cindex history list + +When the @option{-o history} option to the @code{set} builtin +is enabled (@pxref{The Set Builtin}), +the shell provides access to the @dfn{command history}, +the list of commands previously typed. +The value of the @env{HISTSIZE} shell variable is used as the +number of commands to save in a history list. +The text of the last @env{$HISTSIZE} +commands (default 500) is saved. +The shell stores each command in the history list prior to +parameter and variable expansion +but after history expansion is performed, subject to the +values of the shell variables +@env{HISTIGNORE} and @env{HISTCONTROL}. + +When the shell starts up, the history is initialized from the +file named by the @env{HISTFILE} variable (default @file{~/.bash_history}). +The file named by the value of @env{HISTFILE} is truncated, if +necessary, to contain no more than the number of lines specified by +the value of the @env{HISTFILESIZE} variable. +When a shell with history enabled exits, the last +@env{$HISTSIZE} lines are copied from the history list to the file +named by @env{$HISTFILE}. +If the @code{histappend} shell option is set (@pxref{Bash Builtins}), +the lines are appended to the history file, +otherwise the history file is overwritten. +If @env{HISTFILE} +is unset, or if the history file is unwritable, the history is not saved. +After saving the history, the history file is truncated +to contain no more than @env{$HISTFILESIZE} lines. +If @env{HISTFILESIZE} is unset, or set to null, a non-numeric value, or +a numeric value less than zero, the history file is not truncated. + +If the @env{HISTTIMEFORMAT} is set, the time stamp information +associated with each history entry is written to the history file, +marked with the history comment character. +When the history file is read, lines beginning with the history +comment character followed immediately by a digit are interpreted +as timestamps for the following history entry. + +The builtin command @code{fc} may be used to list or edit and re-execute +a portion of the history list. +The @code{history} builtin may be used to display or modify the history +list and manipulate the history file. +When using command-line editing, search commands +are available in each editing mode that provide access to the +history list (@pxref{Commands For History}). + +The shell allows control over which commands are saved on the history +list. The @env{HISTCONTROL} and @env{HISTIGNORE} +variables may be set to cause the shell to save only a subset of the +commands entered. +The @code{cmdhist} +shell option, if enabled, causes the shell to attempt to save each +line of a multi-line command in the same history entry, adding +semicolons where necessary to preserve syntactic correctness. +The @code{lithist} +shell option causes the shell to save the command with embedded newlines +instead of semicolons. +The @code{shopt} builtin is used to set these options. +@xref{The Shopt Builtin}, for a description of @code{shopt}. + +@node Bash History Builtins +@section Bash History Builtins +@cindex history builtins + +Bash provides two builtin commands which manipulate the +history list and history file. + +@table @code + +@item fc +@btindex fc +@example +@code{fc [-e @var{ename}] [-lnr] [@var{first}] [@var{last}]} +@code{fc -s [@var{pat}=@var{rep}] [@var{command}]} +@end example + +The first form selects a range of commands from @var{first} to +@var{last} from the history list and displays or edits and re-executes +them. +Both @var{first} and +@var{last} may be specified as a string (to locate the most recent +command beginning with that string) or as a number (an index into the +history list, where a negative number is used as an offset from the +current command number). + +When listing, a @var{first} or @var{last} of 0 is equivalent to -1 +and -0 is equivalent to the current command (usually the @code{fc} +command); +otherwise 0 is equivalent to -1 and -0 is invalid. + +If @var{last} is not specified, it is set to +@var{first}. If @var{first} is not specified, it is set to the previous +command for editing and @minus{}16 for listing. If the @option{-l} flag is +given, the commands are listed on standard output. The @option{-n} flag +suppresses the command numbers when listing. The @option{-r} flag +reverses the order of the listing. Otherwise, the editor given by +@var{ename} is invoked on a file containing those commands. If +@var{ename} is not given, the value of the following variable expansion +is used: @code{$@{FCEDIT:-$@{EDITOR:-vi@}@}}. This says to use the +value of the @env{FCEDIT} variable if set, or the value of the +@env{EDITOR} variable if that is set, or @code{vi} if neither is set. +When editing is complete, the edited commands are echoed and executed. + +In the second form, @var{command} is re-executed after each instance +of @var{pat} in the selected command is replaced by @var{rep}. +@var{command} is interpreted the same as @var{first} above. + +A useful alias to use with the @code{fc} command is @code{r='fc -s'}, so +that typing @samp{r cc} runs the last command beginning with @code{cc} +and typing @samp{r} re-executes the last command (@pxref{Aliases}). + +@item history +@btindex history +@example +history [@var{n}] +history -c +history -d @var{offset} +history -d @var{start}-@var{end} +history [-anrw] [@var{filename}] +history -ps @var{arg} +@end example + +With no options, display the history list with line numbers. +Lines prefixed with a @samp{*} have been modified. +An argument of @var{n} lists only the last @var{n} lines. +If the shell variable @env{HISTTIMEFORMAT} is set and not null, +it is used as a format string for @var{strftime} to display +the time stamp associated with each displayed history entry. +No intervening blank is printed between the formatted time stamp +and the history line. + +Options, if supplied, have the following meanings: + +@table @code +@item -c +Clear the history list. This may be combined +with the other options to replace the history list completely. + +@item -d @var{offset} +Delete the history entry at position @var{offset}. +If @var{offset} is positive, it should be specified as it appears when +the history is displayed. +If @var{offset} is negative, it is interpreted as relative to one greater +than the last history position, so negative indices count back from the +end of the history, and an index of @samp{-1} refers to the current +@code{history -d} command. + +@item -d @var{start}-@var{end} +Delete the range of history entries between positions @var{start} and +@var{end}, inclusive. +Positive and negative values for @var{start} and @var{end} +are interpreted as described above. + +@item -a +Append the new history lines to the history file. +These are history lines entered since the beginning of the current +Bash session, but not already appended to the history file. + +@item -n +Append the history lines not already read from the history file +to the current history list. These are lines appended to the history +file since the beginning of the current Bash session. + +@item -r +Read the history file and append its contents to +the history list. + +@item -w +Write out the current history list to the history file. + +@item -p +Perform history substitution on the @var{arg}s and display the result +on the standard output, without storing the results in the history list. + +@item -s +The @var{arg}s are added to the end of +the history list as a single entry. + +@end table + +If a @var{filename} argument is supplied +when any of the @option{-w}, @option{-r}, @option{-a}, or @option{-n} options +is used, Bash uses @var{filename} as the history file. +If not, then the value of the @env{HISTFILE} variable is used. + +The return value is 0 unless an invalid option is encountered, an +error occurs while reading or writing the history file, an invalid +@var{offset} or range is supplied as an argument to @option{-d}, or the +history expansion supplied as an argument to @option{-p} fails. + +@end table +@end ifset + +@node History Interaction +@section History Expansion +@cindex history expansion + +The History library provides a history expansion feature that is similar +to the history expansion provided by @code{csh}. This section +describes the syntax used to manipulate the history information. + +History expansions introduce words from the history list into +the input stream, making it easy to repeat commands, insert the +arguments to a previous command into the current input line, or +fix errors in previous commands quickly. + +@ifset BashFeatures +History expansion is performed immediately after a complete line +is read, before the shell breaks it into words, and is performed +on each line individually. Bash attempts to inform the history +expansion functions about quoting still in effect from previous lines. +@end ifset + +History expansion takes place in two parts. The first is to determine +which line from the history list should be used during substitution. +The second is to select portions of that line for inclusion into the +current one. The line selected from the history is called the +@dfn{event}, and the portions of that line that are acted upon are +called @dfn{words}. Various @dfn{modifiers} are available to manipulate +the selected words. The line is broken into words in the same fashion +that Bash does, so that several words +surrounded by quotes are considered one word. +History expansions are introduced by the appearance of the +history expansion character, which is @samp{!} by default. + +History expansion implements shell-like quoting conventions: +a backslash can be used to remove the special handling for the next character; +single quotes enclose verbatim sequences of characters, and can be used to +inhibit history expansion; +and characters enclosed within double quotes may be subject to history +expansion, since backslash can escape the history expansion character, +but single quotes may not, since they are not treated specially within +double quotes. + +@ifset BashFeatures +When using the shell, only @samp{\} and @samp{'} may be used to escape the +history expansion character, but the history expansion character is +also treated as quoted if it immediately precedes the closing double quote +in a double-quoted string. +@end ifset + +@ifset BashFeatures +Several shell options settable with the @code{shopt} +builtin (@pxref{The Shopt Builtin}) may be used to tailor +the behavior of history expansion. If the +@code{histverify} shell option is enabled, and Readline +is being used, history substitutions are not immediately passed to +the shell parser. +Instead, the expanded line is reloaded into the Readline +editing buffer for further modification. +If Readline is being used, and the @code{histreedit} +shell option is enabled, a failed history expansion will be +reloaded into the Readline editing buffer for correction. +The @option{-p} option to the @code{history} builtin command +may be used to see what a history expansion will do before using it. +The @option{-s} option to the @code{history} builtin may be used to +add commands to the end of the history list without actually executing +them, so that they are available for subsequent recall. +This is most useful in conjunction with Readline. + +The shell allows control of the various characters used by the +history expansion mechanism with the @code{histchars} variable, +as explained above (@pxref{Bash Variables}). The shell uses +the history comment character to mark history timestamps when +writing the history file. +@end ifset + +@menu +* Event Designators:: How to specify which history line to use. +* Word Designators:: Specifying which words are of interest. +* Modifiers:: Modifying the results of substitution. +@end menu + +@node Event Designators +@subsection Event Designators +@cindex event designators + +An event designator is a reference to a command line entry in the +history list. +Unless the reference is absolute, events are relative to the current +position in the history list. +@cindex history events + +@table @asis + +@item @code{!} +@ifset BashFeatures +Start a history substitution, except when followed by a space, tab, +the end of the line, @samp{=} or @samp{(} (when the +@code{extglob} shell option is enabled using the @code{shopt} builtin). +@end ifset +@ifclear BashFeatures +Start a history substitution, except when followed by a space, tab, +the end of the line, or @samp{=}. +@end ifclear + +@item @code{!@var{n}} +Refer to command line @var{n}. + +@item @code{!-@var{n}} +Refer to the command @var{n} lines back. + +@item @code{!!} +Refer to the previous command. This is a synonym for @samp{!-1}. + +@item @code{!@var{string}} +Refer to the most recent command +preceding the current position in the history list +starting with @var{string}. + +@item @code{!?@var{string}[?]} +Refer to the most recent command +preceding the current position in the history list +containing @var{string}. +The trailing +@samp{?} may be omitted if the @var{string} is followed immediately by +a newline. +If @var{string} is missing, the string from the most recent search is used; +it is an error if there is no previous search string. + +@item @code{^@var{string1}^@var{string2}^} +Quick Substitution. Repeat the last command, replacing @var{string1} +with @var{string2}. Equivalent to +@code{!!:s^@var{string1}^@var{string2}^}. + +@item @code{!#} +The entire command line typed so far. + +@end table + +@node Word Designators +@subsection Word Designators + +Word designators are used to select desired words from the event. +A @samp{:} separates the event specification from the word designator. It +may be omitted if the word designator begins with a @samp{^}, @samp{$}, +@samp{*}, @samp{-}, or @samp{%}. Words are numbered from the beginning +of the line, with the first word being denoted by 0 (zero). Words are +inserted into the current line separated by single spaces. + +@need 0.75 +For example, + +@table @code +@item !! +designates the preceding command. When you type this, the preceding +command is repeated in toto. + +@item !!:$ +designates the last argument of the preceding command. This may be +shortened to @code{!$}. + +@item !fi:2 +designates the second argument of the most recent command starting with +the letters @code{fi}. +@end table + +@need 0.75 +Here are the word designators: + +@table @code + +@item 0 (zero) +The @code{0}th word. For many applications, this is the command word. + +@item @var{n} +The @var{n}th word. + +@item ^ +The first argument; that is, word 1. + +@item $ +The last argument. + +@item % +The first word matched by the most recent @samp{?@var{string}?} search, +if the search string begins with a character that is part of a word. + +@item @var{x}-@var{y} +A range of words; @samp{-@var{y}} abbreviates @samp{0-@var{y}}. + +@item * +All of the words, except the @code{0}th. This is a synonym for @samp{1-$}. +It is not an error to use @samp{*} if there is just one word in the event; +the empty string is returned in that case. + +@item @var{x}* +Abbreviates @samp{@var{x}-$} + +@item @var{x}- +Abbreviates @samp{@var{x}-$} like @samp{@var{x}*}, but omits the last word. +If @samp{x} is missing, it defaults to 0. + +@end table + +If a word designator is supplied without an event specification, the +previous command is used as the event. + +@node Modifiers +@subsection Modifiers + +After the optional word designator, you can add a sequence of one or more +of the following modifiers, each preceded by a @samp{:}. +These modify, or edit, the word or words selected from the history event. + +@table @code + +@item h +Remove a trailing pathname component, leaving only the head. + +@item t +Remove all leading pathname components, leaving the tail. + +@item r +Remove a trailing suffix of the form @samp{.@var{suffix}}, leaving +the basename. + +@item e +Remove all but the trailing suffix. + +@item p +Print the new command but do not execute it. + +@ifset BashFeatures +@item q +Quote the substituted words, escaping further substitutions. + +@item x +Quote the substituted words as with @samp{q}, +but break into words at spaces, tabs, and newlines. +The @samp{q} and @samp{x} modifiers are mutually exclusive; the last one +supplied is used. +@end ifset + +@item s/@var{old}/@var{new}/ +Substitute @var{new} for the first occurrence of @var{old} in the +event line. +Any character may be used as the delimiter in place of @samp{/}. +The delimiter may be quoted in @var{old} and @var{new} +with a single backslash. If @samp{&} appears in @var{new}, +it is replaced by @var{old}. A single backslash will quote +the @samp{&}. +If @var{old} is null, it is set to the last @var{old} +substituted, or, if no previous history substitutions took place, +the last @var{string} +in a !?@var{string}@code{[?]} +search. +If @var{new} is null, each matching @var{old} is deleted. +The final delimiter is optional if it is the last +character on the input line. + +@item & +Repeat the previous substitution. + +@item g +@itemx a +Cause changes to be applied over the entire event line. Used in +conjunction with @samp{s}, as in @code{gs/@var{old}/@var{new}/}, +or with @samp{&}. + +@item G +Apply the following @samp{s} or @samp{&} modifier once to each word +in the event. + +@end table diff -pruN 16.3-5/readline/readline/doc/readline.info 16.3-5ubuntu1/readline/readline/doc/readline.info --- 16.3-5/readline/readline/doc/readline.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/readline.info 2025-04-20 17:25:30.000000000 +0000 @@ -0,0 +1,5320 @@ +This is readline.info, produced by makeinfo version 6.8 from rlman.texi. + +This manual describes the GNU Readline Library (version 8.2, 19 +September 2022), a library which aids in the consistency of user +interface across discrete programs which provide a command line +interface. + + Copyright (C) 1988-2022 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + +INFO-DIR-SECTION Libraries +START-INFO-DIR-ENTRY +* Readline: (readline). The GNU readline library API. +END-INFO-DIR-ENTRY + + +File: readline.info, Node: Top, Next: Command Line Editing, Up: (dir) + +GNU Readline Library +******************** + +This document describes the GNU Readline Library, a utility which aids +in the consistency of user interface across discrete programs which +provide a command line interface. The Readline home page is +. + +* Menu: + +* Command Line Editing:: GNU Readline User's Manual. +* Programming with GNU Readline:: GNU Readline Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. + + +File: readline.info, Node: Command Line Editing, Next: Programming with GNU Readline, Prev: Top, Up: Top + +1 Command Line Editing +********************** + +This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: readline.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +1.1 Introduction to Line Editing +================================ + +The following paragraphs describe the notation used to represent +keystrokes. + + The text 'C-k' is read as 'Control-K' and describes the character +produced when the key is pressed while the Control key is depressed. + + The text 'M-k' is read as 'Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed. The Meta key is labeled on many keyboards. On +keyboards with two keys labeled (usually to either side of the +space bar), the on the left side is generally set to work as a +Meta key. The key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or key, or another key working as a +Meta key, the identical keystroke can be generated by typing +_first_, and then typing . Either process is known as "metafying" +the key. + + The text 'M-C-k' is read as 'Meta-Control-k' and describes the +character produced by "metafying" 'C-k'. + + In addition, several keys have their own names. Specifically, , +, , , , and all stand for themselves when seen +in this text, or in an init file (*note Readline Init File::). If your +keyboard lacks a key, typing will produce the desired +character. The key may be labeled or on some +keyboards. + + +File: readline.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +1.2 Readline Interaction +======================== + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press . You do not have to be at the end of +the line to press ; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: readline.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +1.2.1 Readline Bare Essentials +------------------------------ + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error until +you have typed several other characters. In that case, you can type +'C-b' to move the cursor to the left, and then correct your mistake. +Afterwards, you can move the cursor to the right with 'C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are 'pushed over' to make room for +the text that you have inserted. Likewise, when you delete text behind +the cursor, characters to the right of the cursor are 'pulled back' to +fill in the blank space created by the removal of the text. A list of +the bare essentials for editing the text of an input line follows. + +'C-b' + Move back one character. +'C-f' + Move forward one character. + or + Delete the character to the left of the cursor. +'C-d' + Delete the character underneath the cursor. +Printing characters + Insert the character into the line at the cursor. +'C-_' or 'C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the key might be set to +delete the character to the left of the cursor and the key set to +delete the character underneath the cursor, like 'C-d', rather than the +character to the left of the cursor.) + + +File: readline.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +1.2.2 Readline Movement Commands +-------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many other +commands have been added in addition to 'C-b', 'C-f', 'C-d', and . +Here are some commands for moving more rapidly about the line. + +'C-a' + Move to the start of the line. +'C-e' + Move to the end of the line. +'M-f' + Move forward a word, where a word is composed of letters and + digits. +'M-b' + Move backward a word. +'C-l' + Clear the screen, reprinting the current line at the top. + + Notice how 'C-f' moves forward a character, while 'M-f' moves forward +a word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: readline.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +1.2.3 Readline Killing Commands +------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into the +line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) + + If the description for a command says that it 'kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". Any +number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +'C-k' + Kill the text from the current cursor position to the end of the + line. + +'M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by 'M-f'. + +'M-' + Kill from the cursor to the start of the current word, or, if + between words, to the start of the previous word. Word boundaries + are the same as those used by 'M-b'. + +'C-w' + Kill from the cursor to the previous whitespace. This is different + than 'M-' because the word boundaries differ. + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +'C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +'M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'C-y' or 'M-y'. + + +File: readline.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +1.2.4 Readline Arguments +------------------------ + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type 'M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first 'digit' typed is a minus +sign ('-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give the +'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will +delete the next ten characters on the input line. + + +File: readline.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +1.2.5 Searching for Commands in the History +------------------------------------------- + +Readline provides commands for searching through the command history for +lines containing a specified string. There are two search modes: +"incremental" and "non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters as +needed to find the desired history entry. To search backward in the +history for a particular string, type 'C-r'. Typing 'C-s' searches +forward through the history. The characters present in the value of the +'isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the and +'C-J' characters will terminate an incremental search. 'C-g' will abort +an incremental search and restore the original line. When the search is +terminated, the history entry containing the search string becomes the +current line. + + To find other matching entries in the history list, type 'C-r' or +'C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. Any +other key sequence bound to a Readline command will terminate the search +and execute that command. For instance, a will terminate the +search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two 'C-r's +are typed without any intervening characters defining a new search +string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: readline.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +1.3 Readline Init File +====================== + +Although the Readline library comes with a set of Emacs-like keybindings +installed by default, it is possible to use a different set of +keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in their home +directory. The name of this file is taken from the value of the +environment variable 'INPUTRC'. If that variable is unset, the default +is '~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is '/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the 'C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: readline.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +1.3.1 Readline Init File Syntax +------------------------------- + +There are only a few basic constructs allowed in the Readline init file. +Blank lines are ignored. Lines beginning with a '#' are comments. +Lines beginning with a '$' indicate conditional constructs (*note +Conditional Init Constructs::). Other lines denote variable settings +and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the 'set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like key + binding to use 'vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. Any + other value results in the variable being set to off. + + A great deal of run-time behavior is changeable with the following + variables. + + 'active-region-start-color' + A string variable that controls the text color and background + when displaying the text in the active region (see the + description of 'enable-active-region' below). This string + must not take up any physical character positions on the + display, so it should consist only of terminal escape + sequences. It is output to the terminal before displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that puts the terminal in standout mode, + as obtained from the terminal's terminfo description. A + sample value might be '\e[01;33m'. + + 'active-region-end-color' + A string variable that "undoes" the effects of + 'active-region-start-color' and restores "normal" terminal + display appearance after displaying text in the active region. + This string must not take up any physical character positions + on the display, so it should consist only of terminal escape + sequences. It is output to the terminal after displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that restores the terminal from standout + mode, as obtained from the terminal's terminfo description. A + sample value might be '\e[0m'. + + 'bell-style' + Controls what happens when Readline wants to ring the terminal + bell. If set to 'none', Readline never rings the bell. If + set to 'visible', Readline uses a visible bell if one is + available. If set to 'audible' (the default), Readline + attempts to ring the terminal's bell. + + 'bind-tty-special-chars' + If set to 'on' (the default), Readline attempts to bind the + control characters treated specially by the kernel's terminal + driver to their Readline equivalents. + + 'blink-matching-paren' + If set to 'on', Readline attempts to briefly move the cursor + to an opening parenthesis when a closing parenthesis is + inserted. The default is 'off'. + + 'colored-completion-prefix' + If set to 'on', when listing completions, Readline displays + the common prefix of the set of possible completions using a + different color. The color definitions are taken from the + value of the 'LS_COLORS' environment variable. If there is a + color definition in 'LS_COLORS' for the custom suffix + 'readline-colored-completion-prefix', Readline uses this color + for the common prefix instead of its default. The default is + 'off'. + + 'colored-stats' + If set to 'on', Readline displays possible completions using + different colors to indicate their file type. The color + definitions are taken from the value of the 'LS_COLORS' + environment variable. The default is 'off'. + + 'comment-begin' + The string to insert at the beginning of the line when the + 'insert-comment' command is executed. The default value is + '"#"'. + + 'completion-display-width' + The number of screen columns used to display possible matches + when performing completion. The value is ignored if it is + less than 0 or greater than the terminal screen width. A + value of 0 will cause matches to be displayed one per line. + The default value is -1. + + 'completion-ignore-case' + If set to 'on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is 'off'. + + 'completion-map-case' + If set to 'on', and COMPLETION-IGNORE-CASE is enabled, + Readline treats hyphens ('-') and underscores ('_') as + equivalent when performing case-insensitive filename matching + and completion. The default value is 'off'. + + 'completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + 'completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than or equal to this value, Readline will ask whether or not + the user wishes to view them; otherwise, they are simply + listed. This variable must be set to an integer value greater + than or equal to zero. A zero value means Readline should + never ask; negative values are treated as zero. The default + limit is '100'. + + 'convert-meta' + If set to 'on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an character, converting them + to a meta-prefixed key sequence. The default value is 'on', + but will be set to 'off' if the locale is one that contains + eight-bit characters. This variable is dependent on the + 'LC_CTYPE' locale category, and may change if the locale is + changed. + + 'disable-completion' + If set to 'On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to 'self-insert'. The default is 'off'. + + 'echo-control-characters' + When set to 'on', on operating systems that indicate they + support it, Readline echoes a character corresponding to a + signal generated from the keyboard. The default is 'on'. + + 'editing-mode' + The 'editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either 'emacs' or 'vi'. + + 'emacs-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when emacs editing mode is active. The value is + expanded like a key binding, so the standard set of meta- and + control prefixes and backslash escape sequences is available. + Use the '\1' and '\2' escapes to begin and end sequences of + non-printing characters, which can be used to embed a terminal + control sequence into the mode string. The default is '@'. + + 'enable-active-region' + The "point" is the current cursor position, and "mark" refers + to a saved cursor position (*note Commands For Moving::). The + text between the point and mark is referred to as the + "region". When this variable is set to 'On', Readline allows + certain commands to designate the region as "active". When + the region is active, Readline highlights the text in the + region using the value of the 'active-region-start-color', + which defaults to the string that enables the terminal's + standout mode. The active region shows the text inserted by + bracketed-paste and any matching text found by incremental and + non-incremental history searches. The default is 'On'. + + 'enable-bracketed-paste' + When set to 'On', Readline configures the terminal to insert + each paste into the editing buffer as a single string of + characters, instead of treating each character as if it had + been read from the keyboard. This is called putting the + terminal into "bracketed paste mode"; it prevents Readline + from executing any editing commands bound to key sequences + appearing in the pasted text. The default is 'On'. + + 'enable-keypad' + When set to 'on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is 'off'. + + 'enable-meta-key' + When set to 'on', Readline will try to enable any meta + modifier key the terminal claims to support when it is called. + On many terminals, the meta key is used to send eight-bit + characters. The default is 'on'. + + 'expand-tilde' + If set to 'on', tilde expansion is performed when Readline + attempts word completion. The default is 'off'. + + 'history-preserve-point' + If set to 'on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with 'previous-history' or + 'next-history'. The default is 'off'. + + 'history-size' + Set the maximum number of history entries saved in the history + list. If set to zero, any existing history entries are + deleted and no new entries are saved. If set to a value less + than zero, the number of history entries is not limited. By + default, the number of history entries is not limited. If an + attempt is made to set HISTORY-SIZE to a non-numeric value, + the maximum number of history entries will be set to 500. + + 'horizontal-scroll-mode' + This variable can be set to either 'on' or 'off'. Setting it + to 'on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. This variable is automatically set to 'on' + for terminals of height 1. By default, this variable is set + to 'off'. + + 'input-meta' + If set to 'on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is 'off', but Readline will set it to 'on' if + the locale contains eight-bit characters. The name + 'meta-flag' is a synonym for this variable. This variable is + dependent on the 'LC_CTYPE' locale category, and may change if + the locale is changed. + + 'isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters and 'C-J' will terminate + an incremental search. + + 'keymap' + Sets Readline's idea of the current keymap for key binding + commands. Built-in 'keymap' names are 'emacs', + 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', + 'vi-command', and 'vi-insert'. 'vi' is equivalent to + 'vi-command' ('vi-move' is also a synonym); 'emacs' is + equivalent to 'emacs-standard'. Applications may add + additional names. The default value is 'emacs'. The value of + the 'editing-mode' variable also affects the default keymap. + + 'keyseq-timeout' + Specifies the duration Readline will wait for a character when + reading an ambiguous key sequence (one that can form a + complete key sequence using the input read so far, or can take + additional input to complete a longer key sequence). If no + input is received within the timeout, Readline will use the + shorter but complete key sequence. Readline uses this value + to determine whether or not input is available on the current + input source ('rl_instream' by default). The value is + specified in milliseconds, so a value of 1000 means that + Readline will wait one second for additional input. If this + variable is set to a value less than or equal to zero, or to a + non-numeric value, Readline will wait until another key is + pressed to decide which key sequence to complete. The default + value is '500'. + + 'mark-directories' + If set to 'on', completed directory names have a slash + appended. The default is 'on'. + + 'mark-modified-lines' + This variable, when set to 'on', causes Readline to display an + asterisk ('*') at the start of history lines which have been + modified. This variable is 'off' by default. + + 'mark-symlinked-directories' + If set to 'on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + 'mark-directories'). The default is 'off'. + + 'match-hidden-files' + This variable, when set to 'on', causes Readline to match + files whose names begin with a '.' (hidden files) when + performing filename completion. If set to 'off', the leading + '.' must be supplied by the user in the filename to be + completed. This variable is 'on' by default. + + 'menu-complete-display-prefix' + If set to 'on', menu completion displays the common prefix of + the list of possible completions (which may be empty) before + cycling through the list. The default is 'off'. + + 'output-meta' + If set to 'on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is 'off', but Readline will set it to + 'on' if the locale contains eight-bit characters. This + variable is dependent on the 'LC_CTYPE' locale category, and + may change if the locale is changed. + + 'page-completions' + If set to 'on', Readline uses an internal 'more'-like pager to + display a screenful of possible completions at a time. This + variable is 'on' by default. + + 'print-completions-horizontally' + If set to 'on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is 'off'. + + 'revert-all-at-newline' + If set to 'on', Readline will undo all changes to history + lines before returning when 'accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to 'readline()'. The default is + 'off'. + + 'show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to 'on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is 'off'. + + 'show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + 'on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is 'off'. + + 'show-mode-in-prompt' + If set to 'on', add a string to the beginning of the prompt + indicating the editing mode: emacs, vi command, or vi + insertion. The mode strings are user-settable (e.g., + EMACS-MODE-STRING). The default value is 'off'. + + 'skip-completed-text' + If set to 'on', this alters the default completion behavior + when inserting a single match into the line. It's only active + when performing completion in the middle of a word. If + enabled, Readline does not insert characters from the + completion that match characters after point in the word being + completed, so portions of the word following the cursor are + not duplicated. For instance, if this is enabled, attempting + completion when the cursor is after the 'e' in 'Makefile' will + result in 'Makefile' rather than 'Makefilefile', assuming + there is a single possible completion. The default value is + 'off'. + + 'vi-cmd-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in command mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(cmd)'. + + 'vi-ins-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in insertion mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(ins)'. + + 'visible-stats' + If set to 'on', a character denoting a file's type is appended + to the filename when listing possible completions. The + default is 'off'. + +Key Bindings + The syntax for controlling key bindings in the init file is simple. + First you need to find the name of the command that you want to + change. The following sections contain tables of the command name, + the default keybinding, if any, and a short description of what the + command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, Readline allows keys to be bound to a + string that is inserted when the key is pressed (a MACRO). + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the example above, 'C-u' is bound to the function + 'universal-argument', 'M-DEL' is bound to the function + 'backward-kill-word', and 'C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + '> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, 'C-u' is again bound to the function + 'universal-argument' (just as it was in the first example), + ''C-x' 'C-r'' is bound to the function 're-read-init-file', + and ' <[> <1> <1> <~>' is bound to insert the text + 'Function Key 1'. + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + '\C-' + control prefix + '\M-' + meta prefix + '\e' + an escape character + '\\' + backslash + '\"' + <">, a double quotation mark + '\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + '\a' + alert (bell) + '\b' + backspace + '\d' + delete + '\f' + form feed + '\n' + newline + '\r' + carriage return + '\t' + horizontal tab + '\v' + vertical tab + '\NNN' + the eight-bit character whose value is the octal value NNN + (one to three digits) + '\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including '"' and '''. For example, + the following binding will make ''C-x' \' insert a single '\' into + the line: + "\C-x\\": "\\" + + +File: readline.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +1.3.2 Conditional Init Constructs +--------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings and +variable settings to be performed as the result of tests. There are +four parser directives used. + +'$if' + The '$if' construct allows bindings to be made based on the editing + mode, the terminal being used, or the application using Readline. + The text of the test, after any comparison operator, extends to the + end of the line; unless otherwise noted, no characters are required + to isolate it. + + 'mode' + The 'mode=' form of the '$if' directive is used to test + whether Readline is in 'emacs' or 'vi' mode. This may be used + in conjunction with the 'set keymap' command, for instance, to + set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps + only if Readline is starting out in 'emacs' mode. + + 'term' + The 'term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + '=' is tested against both the full name of the terminal and + the portion of the terminal name before the first '-'. This + allows 'sun' to match both 'sun' and 'sun-cmd', for instance. + + 'version' + The 'version' test may be used to perform comparisons against + specific Readline versions. The 'version' expands to the + current Readline version. The set of comparison operators + includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The + version number supplied on the right side of the operator + consists of a major version number, an optional decimal point, + and an optional minor version (e.g., '7.1'). If the minor + version is omitted, it is assumed to be '0'. The operator may + be separated from the string 'version' and from the version + number argument by whitespace. The following example sets a + variable if the Readline version being used is 7.0 or newer: + $if version >= 7.0 + set show-mode-in-prompt on + $endif + + 'application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + + 'variable' + The VARIABLE construct provides simple equality tests for + Readline variables and values. The permitted comparison + operators are '=', '==', and '!='. The variable name must be + separated from the comparison operator by whitespace; the + operator may be separated from the value on the right hand + side by whitespace. Both string and boolean variables may be + tested. Boolean variables must be tested against the values + ON and OFF. The following example is equivalent to the + 'mode=emacs' test described above: + $if editing-mode == emacs + set show-mode-in-prompt on + $endif + +'$endif' + This command, as seen in the previous example, terminates an '$if' + command. + +'$else' + Commands in this branch of the '$if' directive are executed if the + test fails. + +'$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from '/etc/inputrc': + $include /etc/inputrc + + +File: readline.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +1.3.3 Sample Init File +---------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any system-wide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are 150 or more possible completions for a word, + # ask whether or not the user wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: readline.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +1.4 Bindable Readline Commands +============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + +This section describes Readline commands that may be bound to key +sequences. Command names without an accompanying key sequence are +unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the 'set-mark' +command. The text between the point and mark is referred to as the +"region". + + +File: readline.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +1.4.1 Commands For Moving +------------------------- + +'beginning-of-line (C-a)' + Move to the start of the current line. + +'end-of-line (C-e)' + Move to the end of the line. + +'forward-char (C-f)' + Move forward a character. + +'backward-char (C-b)' + Move back a character. + +'forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +'backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +'previous-screen-line ()' + Attempt to move point to the same physical screen column on the + previous physical screen line. This will not have the desired + effect if the current Readline line does not take up more than one + physical line or if point is not greater than the length of the + prompt plus the screen width. + +'next-screen-line ()' + Attempt to move point to the same physical screen column on the + next physical screen line. This will not have the desired effect + if the current Readline line does not take up more than one + physical line or if the length of the current Readline line is not + greater than the length of the prompt plus the screen width. + +'clear-display (M-C-l)' + Clear the screen and, if possible, the terminal's scrollback + buffer, then redraw the current line, leaving the current line at + the top of the screen. + +'clear-screen (C-l)' + Clear the screen, then redraw the current line, leaving the current + line at the top of the screen. + +'redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: readline.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +1.4.2 Commands For Manipulating The History +------------------------------------------- + +'accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, it may be added to the history list for future recall + with 'add_history()'. If this line is a modified history line, the + history line is restored to its original state. + +'previous-history (C-p)' + Move 'back' through the history list, fetching the previous + command. + +'next-history (C-n)' + Move 'forward' through the history list, fetching the next command. + +'beginning-of-history (M-<)' + Move to the first line in the history. + +'end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +'reverse-search-history (C-r)' + Search backward starting at the current line and moving 'up' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'forward-search-history (C-s)' + Search forward starting at the current line and moving 'down' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving 'up' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving 'down' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the '!N' + history expansion had been specified. + +'yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With a numeric argument, behave exactly + like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back + through the history list, inserting the last word (or the word + specified by the argument to the first call) of each line in turn. + Any numeric argument supplied to these successive calls determines + the direction to move through the history. A negative argument + switches the direction through the history (back or forward). The + history expansion facilities are used to extract the last argument, + as if the '!$' history expansion had been specified. + +'operate-and-get-next (C-o)' + Accept the current line for return to the calling application as if + a newline had been entered, and fetch the next line relative to the + current line from the history for editing. A numeric argument, if + supplied, specifies the history entry to use instead of the current + line. + +'fetch-history ()' + With a numeric argument, fetch that entry from the history list and + make it the current line. Without an argument, move back to the + first entry in the history list. + + +File: readline.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +1.4.3 Commands For Changing Text +-------------------------------- + +'end-of-file (usually C-d)' + The character indicating end-of-file as set, for example, by + 'stty'. If this character is read when there are no characters on + the line, and point is at the beginning of the line, Readline + interprets it as the end of input and returns EOF. + +'delete-char (C-d)' + Delete the character at point. If this function is bound to the + same character as the tty EOF character, as 'C-d' commonly is, see + above for the effects. + +'backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +'forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +'quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like 'C-q', for example. + +'tab-insert (M-)' + Insert a tab character. + +'self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +'bracketed-paste-begin ()' + This function is intended to be bound to the "bracketed paste" + escape sequence sent by some terminals, and such a binding is + assigned by default. It allows Readline to insert the pasted text + as a single unit without treating each character as if it had been + read from the keyboard. The characters are inserted as if each one + was bound to 'self-insert' instead of executing any editing + commands. + + Bracketed paste sets the region (the characters between point and + the mark) to the inserted text. It uses the concept of an _active + mark_: when the mark is active, Readline redisplay uses the + terminal's standout mode to denote the region. + +'transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +'transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +'upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +'downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +'capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +'overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + 'emacs' mode; 'vi' mode does overwrite differently. Each call to + 'readline()' starts in insert mode. + + In overwrite mode, characters bound to 'self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to 'backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + +File: readline.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +1.4.4 Killing And Yanking +------------------------- + +'kill-line (C-k)' + Kill the text from point to the end of the line. With a negative + numeric argument, kill backward from the cursor to the beginning of + the current line. + +'backward-kill-line (C-x Rubout)' + Kill backward from the cursor to the beginning of the current line. + With a negative numeric argument, kill forward from the cursor to + the end of the current line. + +'unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +'kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +'kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as 'forward-word'. + +'backward-kill-word (M-)' + Kill the word behind point. Word boundaries are the same as + 'backward-word'. + +'shell-transpose-words (M-C-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. Word + boundaries are the same as 'shell-forward-word' and + 'shell-backward-word'. + +'unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +'unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +'delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +'kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +'copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +'copy-backward-word ()' + Copy the word before point to the kill buffer. The word boundaries + are the same as 'backward-word'. By default, this command is + unbound. + +'copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as 'forward-word'. By default, this + command is unbound. + +'yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +'yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'yank' or 'yank-pop'. + + +File: readline.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +1.4.5 Specifying Numeric Arguments +---------------------------------- + +'digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. 'M--' starts a negative argument. + +'universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is followed + by digits, executing 'universal-argument' again ends the numeric + argument, but is otherwise ignored. As a special case, if this + command is immediately followed by a character that is neither a + digit nor minus sign, the argument count for the next command is + multiplied by four. The argument count is initially one, so + executing this function the first time makes the argument count + four, a second time makes the argument count sixteen, and so on. + By default, this is not bound to a key. + + +File: readline.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +1.4.6 Letting Readline Type For You +----------------------------------- + +'complete ()' + Attempt to perform completion on the text before point. The actual + completion performed is application-specific. The default is + filename completion. + +'possible-completions (M-?)' + List the possible completions of the text before point. When + displaying completions, Readline sets the number of columns used + for display to the value of 'completion-display-width', the value + of the environment variable 'COLUMNS', or the screen width, in that + order. + +'insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by 'possible-completions'. + +'menu-complete ()' + Similar to 'complete', but replaces the word to be completed with a + single match from the list of possible completions. Repeated + execution of 'menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + 'bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to , but is unbound by + default. + +'menu-complete-backward ()' + Identical to 'menu-complete', but moves backward through the list + of possible completions, as if 'menu-complete' had been given a + negative argument. + +'delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like 'delete-char'). If at the end of the line, + behaves identically to 'possible-completions'. This command is + unbound by default. + + +File: readline.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +1.4.7 Keyboard Macros +--------------------- + +'start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +'end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +'call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + +'print-last-kbd-macro ()' + Print the last keyboard macro defined in a format suitable for the + INPUTRC file. + + +File: readline.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +1.4.8 Some Miscellaneous Commands +--------------------------------- + +'re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +'abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of 'bell-style'). + +'do-lowercase-version (M-A, M-B, M-X, ...)' + If the metafied character X is upper case, run the command that is + bound to the corresponding metafied lower case character. The + behavior is undefined if X is already lower case. + +'prefix-meta ()' + Metafy the next character typed. This is for keyboards without a + meta key. Typing ' f' is equivalent to typing 'M-f'. + +'undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +'revert-line (M-r)' + Undo all changes made to this line. This is like executing the + 'undo' command enough times to get back to the beginning. + +'tilde-expand (M-~)' + Perform tilde expansion on the current word. + +'set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +'exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +'character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative argument searches for previous + occurrences. + +'character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative argument searches for subsequent + occurrences. + +'skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will have + no effect unless explicitly bound to a Readline command, instead of + inserting stray characters into the editing buffer. This is + unbound by default, but usually bound to ESC-[. + +'insert-comment (M-#)' + Without a numeric argument, the value of the 'comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if the + characters at the beginning of the line do not match the value of + 'comment-begin', the value is inserted, otherwise the characters in + 'comment-begin' are deleted from the beginning of the line. In + either case, the line is accepted as if a newline had been typed. + +'dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +'dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'emacs-editing-mode (C-e)' + When in 'vi' command mode, this causes a switch to 'emacs' editing + mode. + +'vi-editing-mode (M-C-j)' + When in 'emacs' editing mode, this causes a switch to 'vi' editing + mode. + + +File: readline.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +1.5 Readline vi Mode +==================== + +While the Readline library does not have a full set of 'vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline 'vi' mode behaves as specified in the POSIX standard. + + In order to switch interactively between 'emacs' and 'vi' editing +modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' +mode and to vi-editing-mode in 'emacs' mode). The Readline default is +'emacs' mode. + + When you enter a line in 'vi' mode, you are already placed in +'insertion' mode, as if you had typed an 'i'. Pressing switches +you into 'command' mode, where you can edit the text of the line with +the standard 'vi' movement keys, move to previous history lines with 'k' +and subsequent lines with 'j', and so forth. + + This document describes the GNU Readline Library, a utility for +aiding in the consistency of user interface across discrete programs +that need to provide a command line interface. + + Copyright (C) 1988-2022 Free Software Foundation, Inc. + + Permission is granted to make and distribute verbatim copies of this +manual provided the copyright notice and this permission notice pare +preserved on all copies. + + Permission is granted to copy and distribute modified versions of +this manual under the conditions for verbatim copying, provided that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + + Permission is granted to copy and distribute translations of this +manual into another language, under the above conditions for modified +versions, except that this permission notice may be stated in a +translation approved by the Foundation. + + +File: readline.info, Node: Programming with GNU Readline, Next: GNU Free Documentation License, Prev: Command Line Editing, Up: Top + +2 Programming with GNU Readline +******************************* + +This chapter describes the interface between the GNU Readline Library +and other programs. If you are a programmer, and you wish to include +the features found in GNU Readline such as completion, line editing, and +interactive history manipulation in your own programs, this section is +for you. + +* Menu: + +* Basic Behavior:: Using the default behavior of Readline. +* Custom Functions:: Adding your own functions to Readline. +* Readline Variables:: Variables accessible to custom + functions. +* Readline Convenience Functions:: Functions which Readline supplies to + aid in writing your own custom + functions. +* Readline Signal Handling:: How Readline behaves when it receives signals. +* Custom Completers:: Supplanting or supplementing Readline's + completion functions. + + +File: readline.info, Node: Basic Behavior, Next: Custom Functions, Up: Programming with GNU Readline + +2.1 Basic Behavior +================== + +Many programs provide a command line interface, such as 'mail', 'ftp', +and 'sh'. For such programs, the default behaviour of Readline is +sufficient. This section describes how to use Readline in the simplest +way possible, perhaps to replace calls in your code to 'gets()' or +'fgets()'. + + The function 'readline()' prints a prompt PROMPT and then reads and +returns a single line of text from the user. If PROMPT is 'NULL' or the +empty string, no prompt is displayed. The line 'readline' returns is +allocated with 'malloc()'; the caller should 'free()' the line when it +has finished with it. The declaration for 'readline' in ANSI C is + + char *readline (const char *PROMPT); + +So, one might say + char *line = readline ("Enter a line: "); +in order to read a line of text from the user. The line returned has +the final newline removed, so only the text remains. + + If 'readline' encounters an 'EOF' while reading the line, and the +line is empty at that point, then '(char *)NULL' is returned. +Otherwise, the line is ended just as if a newline had been typed. + + Readline performs some expansion on the PROMPT before it is displayed +on the screen. See the description of 'rl_expand_prompt' (*note +Redisplay::) for additional details, especially if PROMPT will contain +characters that do not consume physical screen space when displayed. + + If you want the user to be able to get at the line later, (with +for example), you must call 'add_history()' to save the line away in a +"history" list of such lines. + + add_history (line); + +For full details on the GNU History Library, see the associated manual. + + It is preferable to avoid saving empty lines on the history list, +since users rarely have a burning need to reuse a blank line. Here is a +function which usefully replaces the standard 'gets()' library function, +and has the advantage of no static buffer to overflow: + + /* A static variable for holding the line. */ + static char *line_read = (char *)NULL; + + /* Read a string, and return a pointer to it. + Returns NULL on EOF. */ + char * + rl_gets () + { + /* If the buffer has already been allocated, + return the memory to the free pool. */ + if (line_read) + { + free (line_read); + line_read = (char *)NULL; + } + + /* Get a line from the user. */ + line_read = readline (""); + + /* If the line has any text in it, + save it on the history. */ + if (line_read && *line_read) + add_history (line_read); + + return (line_read); + } + + This function gives the user the default behaviour of +completion: completion on file names. If you do not want Readline to +complete on filenames, you can change the binding of the key with +'rl_bind_key()'. + + int rl_bind_key (int KEY, rl_command_func_t *FUNCTION); + + 'rl_bind_key()' takes two arguments: KEY is the character that you +want to bind, and FUNCTION is the address of the function to call when +KEY is pressed. Binding to 'rl_insert()' makes insert +itself. 'rl_bind_key()' returns non-zero if KEY is not a valid ASCII +character code (between 0 and 255). + + Thus, to disable the default behavior, the following suffices: + rl_bind_key ('\t', rl_insert); + + This code should be executed once at the start of your program; you +might write a function called 'initialize_readline()' which performs +this and other desired initializations, such as installing custom +completers (*note Custom Completers::). + + +File: readline.info, Node: Custom Functions, Next: Readline Variables, Prev: Basic Behavior, Up: Programming with GNU Readline + +2.2 Custom Functions +==================== + +Readline provides many functions for manipulating the text of the line, +but it isn't possible to anticipate the needs of all programs. This +section describes the various functions and variables defined within the +Readline library which allow a user program to add customized +functionality to Readline. + + Before declaring any functions that customize Readline's behavior, or +using any functionality Readline provides in other code, an application +writer should include the file '' in any file that +uses Readline's features. Since some of the definitions in 'readline.h' +use the 'stdio' library, the file '' should be included before +'readline.h'. + + 'readline.h' defines a C preprocessor variable that should be treated +as an integer, 'RL_READLINE_VERSION', which may be used to conditionally +compile application code depending on the installed Readline version. +The value is a hexadecimal encoding of the major and minor version +numbers of the library, of the form 0xMMMM. MM is the two-digit major +version number; MM is the two-digit minor version number. For Readline +4.2, for example, the value of 'RL_READLINE_VERSION' would be '0x0402'. + +* Menu: + +* Readline Typedefs:: C declarations to make code readable. +* Function Writing:: Variables and calling conventions. + + +File: readline.info, Node: Readline Typedefs, Next: Function Writing, Up: Custom Functions + +2.2.1 Readline Typedefs +----------------------- + +For readability, we declare a number of new object types, all pointers +to functions. + + The reason for declaring these new types is to make it easier to +write code describing pointers to C functions with appropriately +prototyped arguments and return values. + + For instance, say we want to declare a variable FUNC as a pointer to +a function which takes two 'int' arguments and returns an 'int' (this is +the type of all of the Readline bindable functions). Instead of the +classic C declaration + + 'int (*func)();' + +or the ANSI-C style declaration + + 'int (*func)(int, int);' + +we may write + + 'rl_command_func_t *func;' + + The full list of function pointer types available is + +'typedef int rl_command_func_t (int, int);' + +'typedef char *rl_compentry_func_t (const char *, int);' + +'typedef char **rl_completion_func_t (const char *, int, int);' + +'typedef char *rl_quote_func_t (char *, int, char *);' + +'typedef char *rl_dequote_func_t (char *, int);' + +'typedef int rl_compignore_func_t (char **);' + +'typedef void rl_compdisp_func_t (char **, int, int);' + +'typedef int rl_hook_func_t (void);' + +'typedef int rl_getc_func_t (FILE *);' + +'typedef int rl_linebuf_func_t (char *, int);' + +'typedef int rl_intfunc_t (int);' +'#define rl_ivoidfunc_t rl_hook_func_t' +'typedef int rl_icpfunc_t (char *);' +'typedef int rl_icppfunc_t (char **);' + +'typedef void rl_voidfunc_t (void);' +'typedef void rl_vintfunc_t (int);' +'typedef void rl_vcpfunc_t (char *);' +'typedef void rl_vcppfunc_t (char **);' + + +File: readline.info, Node: Function Writing, Prev: Readline Typedefs, Up: Custom Functions + +2.2.2 Writing a New Function +---------------------------- + +In order to write new functions for Readline, you need to know the +calling conventions for keyboard-invoked functions, and the names of the +variables that describe the current state of the line read so far. + + The calling sequence for a command 'foo' looks like + + int foo (int count, int key) + +where COUNT is the numeric argument (or 1 if defaulted) and KEY is the +key that invoked this function. + + It is completely up to the function as to what should be done with +the numeric argument. Some functions use it as a repeat count, some as +a flag, and others to choose alternate behavior (refreshing the current +line as opposed to refreshing the screen, for example). Some choose to +ignore it. In general, if a function uses the numeric argument as a +repeat count, it should be able to do something useful with both +negative and positive arguments. At the very least, it should be aware +that it can be passed a negative argument. + + A command function should return 0 if its action completes +successfully, and a value greater than zero if some error occurs. This +is the convention obeyed by all of the builtin Readline bindable command +functions. + + +File: readline.info, Node: Readline Variables, Next: Readline Convenience Functions, Prev: Custom Functions, Up: Programming with GNU Readline + +2.3 Readline Variables +====================== + +These variables are available to function writers. + + -- Variable: char * rl_line_buffer + This is the line gathered so far. You are welcome to modify the + contents of the line, but see *note Allowing Undoing::. The + function 'rl_extend_line_buffer' is available to increase the + memory allocated to 'rl_line_buffer'. + + -- Variable: int rl_point + The offset of the current cursor position in 'rl_line_buffer' (the + _point_). + + -- Variable: int rl_end + The number of characters present in 'rl_line_buffer'. When + 'rl_point' is at the end of the line, 'rl_point' and 'rl_end' are + equal. + + -- Variable: int rl_mark + The MARK (saved position) in the current line. If set, the mark + and point define a _region_. + + -- Variable: int rl_done + Setting this to a non-zero value causes Readline to return the + current line immediately. Readline will set this variable when it + has read a key sequence bound to 'accept-line' and is about to + return the line to the caller. + + -- Variable: int rl_eof_found + Readline will set this variable when it has read an EOF character + (e.g., the stty 'EOF' character) on an empty line or encountered a + read error and is about to return a NULL line to the caller. + + -- Variable: int rl_num_chars_to_read + Setting this to a positive value before calling 'readline()' causes + Readline to return after accepting that many characters, rather + than reading up to a character bound to 'accept-line'. + + -- Variable: int rl_pending_input + Setting this to a value makes it the next keystroke read. This is + a way to stuff a single character into the input stream. + + -- Variable: int rl_dispatching + Set to a non-zero value if a function is being called from a key + binding; zero otherwise. Application functions can test this to + discover whether they were called directly or by Readline's + dispatching mechanism. + + -- Variable: int rl_erase_empty_line + Setting this to a non-zero value causes Readline to completely + erase the current line, including any prompt, any time a newline is + typed as the only character on an otherwise-empty line. The cursor + is moved to the beginning of the newly-blank line. + + -- Variable: char * rl_prompt + The prompt Readline uses. This is set from the argument to + 'readline()', and should not be assigned to directly. The + 'rl_set_prompt()' function (*note Redisplay::) may be used to + modify the prompt string after calling 'readline()'. + + -- Variable: char * rl_display_prompt + The string displayed as the prompt. This is usually identical to + RL_PROMPT, but may be changed temporarily by functions that use the + prompt string as a message area, such as incremental search. + + -- Variable: int rl_already_prompted + If an application wishes to display the prompt itself, rather than + have Readline do it the first time 'readline()' is called, it + should set this variable to a non-zero value after displaying the + prompt. The prompt must also be passed as the argument to + 'readline()' so the redisplay functions can update the display + properly. The calling application is responsible for managing the + value; Readline never sets it. + + -- Variable: const char * rl_library_version + The version number of this revision of the library. + + -- Variable: int rl_readline_version + An integer encoding the current version of the library. The + encoding is of the form 0xMMMM, where MM is the two-digit major + version number, and MM is the two-digit minor version number. For + example, for Readline-4.2, 'rl_readline_version' would have the + value 0x0402. + + -- Variable: int rl_gnu_readline_p + Always set to 1, denoting that this is GNU Readline rather than + some emulation. + + -- Variable: const char * rl_terminal_name + The terminal type, used for initialization. If not set by the + application, Readline sets this to the value of the 'TERM' + environment variable the first time it is called. + + -- Variable: const char * rl_readline_name + This variable is set to a unique name by each application using + Readline. The value allows conditional parsing of the inputrc file + (*note Conditional Init Constructs::). + + -- Variable: FILE * rl_instream + The stdio stream from which Readline reads input. If 'NULL', + Readline defaults to STDIN. + + -- Variable: FILE * rl_outstream + The stdio stream to which Readline performs output. If 'NULL', + Readline defaults to STDOUT. + + -- Variable: int rl_prefer_env_winsize + If non-zero, Readline gives values found in the 'LINES' and + 'COLUMNS' environment variables greater precedence than values + fetched from the kernel when computing the screen dimensions. + + -- Variable: rl_command_func_t * rl_last_func + The address of the last command function Readline executed. May be + used to test whether or not a function is being executed twice in + succession, for example. + + -- Variable: rl_hook_func_t * rl_startup_hook + If non-zero, this is the address of a function to call just before + 'readline' prints the first prompt. + + -- Variable: rl_hook_func_t * rl_pre_input_hook + If non-zero, this is the address of a function to call after the + first prompt has been printed and just before 'readline' starts + reading input characters. + + -- Variable: rl_hook_func_t * rl_event_hook + If non-zero, this is the address of a function to call periodically + when Readline is waiting for terminal input. By default, this will + be called at most ten times a second if there is no keyboard input. + + -- Variable: rl_getc_func_t * rl_getc_function + If non-zero, Readline will call indirectly through this pointer to + get a character from the input stream. By default, it is set to + 'rl_getc', the default Readline character input function (*note + Character Input::). In general, an application that sets + RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK as + well. + + -- Variable: rl_hook_func_t * rl_signal_event_hook + If non-zero, this is the address of a function to call if a read + system call is interrupted when Readline is reading terminal input. + + -- Variable: rl_hook_func_t * rl_timeout_event_hook + If non-zero, this is the address of a function to call if Readline + times out while reading input. + + -- Variable: rl_hook_func_t * rl_input_available_hook + If non-zero, Readline will use this function's return value when it + needs to determine whether or not there is available input on the + current input source. The default hook checks 'rl_instream'; if an + application is using a different input source, it should set the + hook appropriately. Readline queries for available input when + implementing intra-key-sequence timeouts during input and + incremental searches. This may use an application-specific timeout + before returning a value; Readline uses the value passed to + 'rl_set_keyboard_input_timeout()' or the value of the user-settable + KEYSEQ-TIMEOUT variable. This is designed for use by applications + using Readline's callback interface (*note Alternate Interface::), + which may not use the traditional 'read(2)' and file descriptor + interface, or other applications using a different input mechanism. + If an application uses an input mechanism or hook that can + potentially exceed the value of KEYSEQ-TIMEOUT, it should increase + the timeout or set this hook appropriately even when not using the + callback interface. In general, an application that sets + RL_GETC_FUNCTION should consider setting RL_INPUT_AVAILABLE_HOOK as + well. + + -- Variable: rl_voidfunc_t * rl_redisplay_function + If non-zero, Readline will call indirectly through this pointer to + update the display with the current contents of the editing buffer. + By default, it is set to 'rl_redisplay', the default Readline + redisplay function (*note Redisplay::). + + -- Variable: rl_vintfunc_t * rl_prep_term_function + If non-zero, Readline will call indirectly through this pointer to + initialize the terminal. The function takes a single argument, an + 'int' flag that says whether or not to use eight-bit characters. + By default, this is set to 'rl_prep_terminal' (*note Terminal + Management::). + + -- Variable: rl_voidfunc_t * rl_deprep_term_function + If non-zero, Readline will call indirectly through this pointer to + reset the terminal. This function should undo the effects of + 'rl_prep_term_function'. By default, this is set to + 'rl_deprep_terminal' (*note Terminal Management::). + + -- Variable: Keymap rl_executing_keymap + This variable is set to the keymap (*note Keymaps::) in which the + currently executing Readline function was found. + + -- Variable: Keymap rl_binding_keymap + This variable is set to the keymap (*note Keymaps::) in which the + last key binding occurred. + + -- Variable: char * rl_executing_macro + This variable is set to the text of any currently-executing macro. + + -- Variable: int rl_executing_key + The key that caused the dispatch to the currently-executing + Readline function. + + -- Variable: char * rl_executing_keyseq + The full key sequence that caused the dispatch to the + currently-executing Readline function. + + -- Variable: int rl_key_sequence_length + The number of characters in RL_EXECUTING_KEYSEQ. + + -- Variable: int rl_readline_state + A variable with bit values that encapsulate the current Readline + state. A bit is set with the 'RL_SETSTATE' macro, and unset with + the 'RL_UNSETSTATE' macro. Use the 'RL_ISSTATE' macro to test + whether a particular state bit is set. Current state bits include: + + 'RL_STATE_NONE' + Readline has not yet been called, nor has it begun to + initialize. + 'RL_STATE_INITIALIZING' + Readline is initializing its internal data structures. + 'RL_STATE_INITIALIZED' + Readline has completed its initialization. + 'RL_STATE_TERMPREPPED' + Readline has modified the terminal modes to do its own input + and redisplay. + 'RL_STATE_READCMD' + Readline is reading a command from the keyboard. + 'RL_STATE_METANEXT' + Readline is reading more input after reading the meta-prefix + character. + 'RL_STATE_DISPATCHING' + Readline is dispatching to a command. + 'RL_STATE_MOREINPUT' + Readline is reading more input while executing an editing + command. + 'RL_STATE_ISEARCH' + Readline is performing an incremental history search. + 'RL_STATE_NSEARCH' + Readline is performing a non-incremental history search. + 'RL_STATE_SEARCH' + Readline is searching backward or forward through the history + for a string. + 'RL_STATE_NUMERICARG' + Readline is reading a numeric argument. + 'RL_STATE_MACROINPUT' + Readline is currently getting its input from a + previously-defined keyboard macro. + 'RL_STATE_MACRODEF' + Readline is currently reading characters defining a keyboard + macro. + 'RL_STATE_OVERWRITE' + Readline is in overwrite mode. + 'RL_STATE_COMPLETING' + Readline is performing word completion. + 'RL_STATE_SIGHANDLER' + Readline is currently executing the readline signal handler. + 'RL_STATE_UNDOING' + Readline is performing an undo. + 'RL_STATE_INPUTPENDING' + Readline has input pending due to a call to + 'rl_execute_next()'. + 'RL_STATE_TTYCSAVED' + Readline has saved the values of the terminal's special + characters. + 'RL_STATE_CALLBACK' + Readline is currently using the alternate (callback) interface + (*note Alternate Interface::). + 'RL_STATE_VIMOTION' + Readline is reading the argument to a vi-mode "motion" + command. + 'RL_STATE_MULTIKEY' + Readline is reading a multiple-keystroke command. + 'RL_STATE_VICMDONCE' + Readline has entered vi command (movement) mode at least one + time during the current call to 'readline()'. + 'RL_STATE_DONE' + Readline has read a key sequence bound to 'accept-line' and is + about to return the line to the caller. + 'RL_STATE_TIMEOUT' + Readline has timed out (it did not receive a line or specified + number of characters before the timeout duration specified by + 'rl_set_timeout' elapsed) and is returning that status to the + caller. + 'RL_STATE_EOF' + Readline has read an EOF character (e.g., the stty 'EOF' + character) or encountered a read error and is about to return + a NULL line to the caller. + + -- Variable: int rl_explicit_arg + Set to a non-zero value if an explicit numeric argument was + specified by the user. Only valid in a bindable command function. + + -- Variable: int rl_numeric_arg + Set to the value of any numeric argument explicitly specified by + the user before executing the current Readline function. Only + valid in a bindable command function. + + -- Variable: int rl_editing_mode + Set to a value denoting Readline's current editing mode. A value + of 1 means Readline is currently in emacs mode; 0 means that vi + mode is active. + + +File: readline.info, Node: Readline Convenience Functions, Next: Readline Signal Handling, Prev: Readline Variables, Up: Programming with GNU Readline + +2.4 Readline Convenience Functions +================================== + +* Menu: + +* Function Naming:: How to give a function you write a name. +* Keymaps:: Making keymaps. +* Binding Keys:: Changing Keymaps. +* Associating Function Names and Bindings:: Translate function names to + key sequences. +* Allowing Undoing:: How to make your functions undoable. +* Redisplay:: Functions to control line display. +* Modifying Text:: Functions to modify 'rl_line_buffer'. +* Character Input:: Functions to read keyboard input. +* Terminal Management:: Functions to manage terminal settings. +* Utility Functions:: Generally useful functions and hooks. +* Miscellaneous Functions:: Functions that don't fall into any category. +* Alternate Interface:: Using Readline in a 'callback' fashion. +* A Readline Example:: An example Readline function. +* Alternate Interface Example:: An example program using the alternate interface. + + +File: readline.info, Node: Function Naming, Next: Keymaps, Up: Readline Convenience Functions + +2.4.1 Naming a Function +----------------------- + +The user can dynamically change the bindings of keys while using +Readline. This is done by representing the function with a descriptive +name. The user is able to type the descriptive name when referring to +the function. Thus, in an init file, one might find + + Meta-Rubout: backward-kill-word + + This binds the keystroke to the function +_descriptively_ named 'backward-kill-word'. You, as the programmer, +should bind the functions you write to descriptive names as well. +Readline provides a function for doing that: + + -- Function: int rl_add_defun (const char *name, rl_command_func_t + *function, int key) + Add NAME to the list of named functions. Make FUNCTION be the + function that gets called. If KEY is not -1, then bind it to + FUNCTION using 'rl_bind_key()'. + + Using this function alone is sufficient for most applications. It is +the recommended way to add a few functions to the default functions that +Readline has built in. If you need to do something other than adding a +function to Readline, you may need to use the underlying functions +described below. + + +File: readline.info, Node: Keymaps, Next: Binding Keys, Prev: Function Naming, Up: Readline Convenience Functions + +2.4.2 Selecting a Keymap +------------------------ + +Key bindings take place on a "keymap". The keymap is the association +between the keys that the user types and the functions that get run. +You can make your own keymaps, copy existing keymaps, and tell Readline +which keymap to use. + + -- Function: Keymap rl_make_bare_keymap (void) + Returns a new, empty keymap. The space for the keymap is allocated + with 'malloc()'; the caller should free it by calling + 'rl_free_keymap()' when done. + + -- Function: Keymap rl_copy_keymap (Keymap map) + Return a new keymap which is a copy of MAP. + + -- Function: Keymap rl_make_keymap (void) + Return a new keymap with the printing characters bound to + rl_insert, the lowercase Meta characters bound to run their + equivalents, and the Meta digits bound to produce numeric + arguments. + + -- Function: void rl_discard_keymap (Keymap keymap) + Free the storage associated with the data in KEYMAP. The caller + should free KEYMAP. + + -- Function: void rl_free_keymap (Keymap keymap) + Free all storage associated with KEYMAP. This calls + 'rl_discard_keymap' to free subordindate keymaps and macros. + + -- Function: int rl_empty_keymap (Keymap keymap) + Return non-zero if there are no keys bound to functions in KEYMAP; + zero if there are any keys bound. + + Readline has several internal keymaps. These functions allow you to +change which keymap is active. + + -- Function: Keymap rl_get_keymap (void) + Returns the currently active keymap. + + -- Function: void rl_set_keymap (Keymap keymap) + Makes KEYMAP the currently active keymap. + + -- Function: Keymap rl_get_keymap_by_name (const char *name) + Return the keymap matching NAME. NAME is one which would be + supplied in a 'set keymap' inputrc line (*note Readline Init + File::). + + -- Function: char * rl_get_keymap_name (Keymap keymap) + Return the name matching KEYMAP. NAME is one which would be + supplied in a 'set keymap' inputrc line (*note Readline Init + File::). + + -- Function: int rl_set_keymap_name (const char *name, Keymap keymap) + Set the name of KEYMAP. This name will then be "registered" and + available for use in a 'set keymap' inputrc directive *note + Readline Init File::). The NAME may not be one of Readline's + builtin keymap names; you may not add a different name for one of + Readline's builtin keymaps. You may replace the name associated + with a given keymap by calling this function more than once with + the same KEYMAP argument. You may associate a registered NAME with + a new keymap by calling this function more than once with the same + NAME argument. There is no way to remove a named keymap once the + name has been registered. Readline will make a copy of NAME. The + return value is greater than zero unless NAME is one of Readline's + builtin keymap names or KEYMAP is one of Readline's builtin + keymaps. + + +File: readline.info, Node: Binding Keys, Next: Associating Function Names and Bindings, Prev: Keymaps, Up: Readline Convenience Functions + +2.4.3 Binding Keys +------------------ + +Key sequences are associate with functions through the keymap. Readline +has several internal keymaps: 'emacs_standard_keymap', +'emacs_meta_keymap', 'emacs_ctlx_keymap', 'vi_movement_keymap', and +'vi_insertion_keymap'. 'emacs_standard_keymap' is the default, and the +examples in this manual assume that. + + Since 'readline()' installs a set of default key bindings the first +time it is called, there is always the danger that a custom binding +installed before the first call to 'readline()' will be overridden. An +alternate mechanism is to install custom key bindings in an +initialization function assigned to the 'rl_startup_hook' variable +(*note Readline Variables::). + + These functions manage key bindings. + + -- Function: int rl_bind_key (int key, rl_command_func_t *function) + Binds KEY to FUNCTION in the currently active keymap. Returns + non-zero in the case of an invalid KEY. + + -- Function: int rl_bind_key_in_map (int key, rl_command_func_t + *function, Keymap map) + Bind KEY to FUNCTION in MAP. Returns non-zero in the case of an + invalid KEY. + + -- Function: int rl_bind_key_if_unbound (int key, rl_command_func_t + *function) + Binds KEY to FUNCTION if it is not already bound in the currently + active keymap. Returns non-zero in the case of an invalid KEY or + if KEY is already bound. + + -- Function: int rl_bind_key_if_unbound_in_map (int key, + rl_command_func_t *function, Keymap map) + Binds KEY to FUNCTION if it is not already bound in MAP. Returns + non-zero in the case of an invalid KEY or if KEY is already bound. + + -- Function: int rl_unbind_key (int key) + Bind KEY to the null function in the currently active keymap. + Returns non-zero in case of error. + + -- Function: int rl_unbind_key_in_map (int key, Keymap map) + Bind KEY to the null function in MAP. Returns non-zero in case of + error. + + -- Function: int rl_unbind_function_in_map (rl_command_func_t + *function, Keymap map) + Unbind all keys that execute FUNCTION in MAP. + + -- Function: int rl_unbind_command_in_map (const char *command, Keymap + map) + Unbind all keys that are bound to COMMAND in MAP. + + -- Function: int rl_bind_keyseq (const char *keyseq, rl_command_func_t + *function) + Bind the key sequence represented by the string KEYSEQ to the + function FUNCTION, beginning in the current keymap. This makes new + keymaps as necessary. The return value is non-zero if KEYSEQ is + invalid. + + -- Function: int rl_bind_keyseq_in_map (const char *keyseq, + rl_command_func_t *function, Keymap map) + Bind the key sequence represented by the string KEYSEQ to the + function FUNCTION. This makes new keymaps as necessary. Initial + bindings are performed in MAP. The return value is non-zero if + KEYSEQ is invalid. + + -- Function: int rl_set_key (const char *keyseq, rl_command_func_t + *function, Keymap map) + Equivalent to 'rl_bind_keyseq_in_map'. + + -- Function: int rl_bind_keyseq_if_unbound (const char *keyseq, + rl_command_func_t *function) + Binds KEYSEQ to FUNCTION if it is not already bound in the + currently active keymap. Returns non-zero in the case of an + invalid KEYSEQ or if KEYSEQ is already bound. + + -- Function: int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, + rl_command_func_t *function, Keymap map) + Binds KEYSEQ to FUNCTION if it is not already bound in MAP. + Returns non-zero in the case of an invalid KEYSEQ or if KEYSEQ is + already bound. + + -- Function: int rl_generic_bind (int type, const char *keyseq, char + *data, Keymap map) + Bind the key sequence represented by the string KEYSEQ to the + arbitrary pointer DATA. TYPE says what kind of data is pointed to + by DATA; this can be a function ('ISFUNC'), a macro ('ISMACR'), or + a keymap ('ISKMAP'). This makes new keymaps as necessary. The + initial keymap in which to do bindings is MAP. + + -- Function: int rl_parse_and_bind (char *line) + Parse LINE as if it had been read from the 'inputrc' file and + perform any key bindings and variable assignments found (*note + Readline Init File::). + + -- Function: int rl_read_init_file (const char *filename) + Read keybindings and variable assignments from FILENAME (*note + Readline Init File::). + + +File: readline.info, Node: Associating Function Names and Bindings, Next: Allowing Undoing, Prev: Binding Keys, Up: Readline Convenience Functions + +2.4.4 Associating Function Names and Bindings +--------------------------------------------- + +These functions allow you to find out what keys invoke named functions +and the functions invoked by a particular key sequence. You may also +associate a new function name with an arbitrary function. + + -- Function: rl_command_func_t * rl_named_function (const char *name) + Return the function with name NAME. + + -- Function: rl_command_func_t * rl_function_of_keyseq (const char + *keyseq, Keymap map, int *type) + Return the function invoked by KEYSEQ in keymap MAP. If MAP is + 'NULL', the current keymap is used. If TYPE is not 'NULL', the + type of the object is returned in the 'int' variable it points to + (one of 'ISFUNC', 'ISKMAP', or 'ISMACR'). It takes a "translated" + key sequence and should not be used if the key sequence can include + NUL. + + -- Function: rl_command_func_t * rl_function_of_keyseq_len (const char + *keyseq, size_t len, Keymap map, int *type) + Return the function invoked by KEYSEQ of length LEN in keymap MAP. + Equivalent to 'rl_function_of_keyseq' with the addition of the LEN + parameter. It takes a "translated" key sequence and should be used + if the key sequence can include NUL. + + -- Function: int rl_trim_arg_from_keyseq (const char *keyseq, size_t + len, Keymap map) + If there is a numeric argument at the beginning of KEYSEQ, possibly + including digits, return the index of the first character in KEYSEQ + following the numeric argument. This can be used to skip over the + numeric argument (which is available as 'rl_numeric_arg' while + traversing the key sequence that invoked the current command. + + -- Function: char ** rl_invoking_keyseqs (rl_command_func_t *function) + Return an array of strings representing the key sequences used to + invoke FUNCTION in the current keymap. + + -- Function: char ** rl_invoking_keyseqs_in_map (rl_command_func_t + *function, Keymap map) + Return an array of strings representing the key sequences used to + invoke FUNCTION in the keymap MAP. + + -- Function: void rl_function_dumper (int readable) + Print the Readline function names and the key sequences currently + bound to them to 'rl_outstream'. If READABLE is non-zero, the list + is formatted in such a way that it can be made part of an 'inputrc' + file and re-read. + + -- Function: void rl_list_funmap_names (void) + Print the names of all bindable Readline functions to + 'rl_outstream'. + + -- Function: const char ** rl_funmap_names (void) + Return a NULL terminated array of known function names. The array + is sorted. The array itself is allocated, but not the strings + inside. You should free the array, but not the pointers, using + 'free' or 'rl_free' when you are done. + + -- Function: int rl_add_funmap_entry (const char *name, + rl_command_func_t *function) + Add NAME to the list of bindable Readline command names, and make + FUNCTION the function to be called when NAME is invoked. + + +File: readline.info, Node: Allowing Undoing, Next: Redisplay, Prev: Associating Function Names and Bindings, Up: Readline Convenience Functions + +2.4.5 Allowing Undoing +---------------------- + +Supporting the undo command is a painless thing, and makes your +functions much more useful. It is certainly easy to try something if +you know you can undo it. + + If your function simply inserts text once, or deletes text once, and +uses 'rl_insert_text()' or 'rl_delete_text()' to do it, then undoing is +already done for you automatically. + + If you do multiple insertions or multiple deletions, or any +combination of these operations, you should group them together into one +operation. This is done with 'rl_begin_undo_group()' and +'rl_end_undo_group()'. + + The types of events that can be undone are: + + enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END }; + + Notice that 'UNDO_DELETE' means to insert some text, and +'UNDO_INSERT' means to delete some text. That is, the undo code tells +what to undo, not how to undo it. 'UNDO_BEGIN' and 'UNDO_END' are tags +added by 'rl_begin_undo_group()' and 'rl_end_undo_group()'. + + -- Function: int rl_begin_undo_group (void) + Begins saving undo information in a group construct. The undo + information usually comes from calls to 'rl_insert_text()' and + 'rl_delete_text()', but could be the result of calls to + 'rl_add_undo()'. + + -- Function: int rl_end_undo_group (void) + Closes the current undo group started with 'rl_begin_undo_group + ()'. There should be one call to 'rl_end_undo_group()' for each + call to 'rl_begin_undo_group()'. + + -- Function: void rl_add_undo (enum undo_code what, int start, int end, + char *text) + Remember how to undo an event (according to WHAT). The affected + text runs from START to END, and encompasses TEXT. + + -- Function: void rl_free_undo_list (void) + Free the existing undo list. + + -- Function: int rl_do_undo (void) + Undo the first thing on the undo list. Returns '0' if there was + nothing to undo, non-zero if something was undone. + + Finally, if you neither insert nor delete text, but directly modify +the existing text (e.g., change its case), call 'rl_modifying()' once, +just before you modify the text. You must supply the indices of the +text range that you are going to modify. + + -- Function: int rl_modifying (int start, int end) + Tell Readline to save the text between START and END as a single + undo unit. It is assumed that you will subsequently modify that + text. + + +File: readline.info, Node: Redisplay, Next: Modifying Text, Prev: Allowing Undoing, Up: Readline Convenience Functions + +2.4.6 Redisplay +--------------- + + -- Function: void rl_redisplay (void) + Change what's displayed on the screen to reflect the current + contents of 'rl_line_buffer'. + + -- Function: int rl_forced_update_display (void) + Force the line to be updated and redisplayed, whether or not + Readline thinks the screen display is correct. + + -- Function: int rl_on_new_line (void) + Tell the update functions that we have moved onto a new (empty) + line, usually after outputting a newline. + + -- Function: int rl_on_new_line_with_prompt (void) + Tell the update functions that we have moved onto a new line, with + RL_PROMPT already displayed. This could be used by applications + that want to output the prompt string themselves, but still need + Readline to know the prompt string length for redisplay. It should + be used after setting RL_ALREADY_PROMPTED. + + -- Function: int rl_clear_visible_line (void) + Clear the screen lines corresponding to the current line's + contents. + + -- Function: int rl_reset_line_state (void) + Reset the display state to a clean state and redisplay the current + line starting on a new line. + + -- Function: int rl_crlf (void) + Move the cursor to the start of the next screen line. + + -- Function: int rl_show_char (int c) + Display character C on 'rl_outstream'. If Readline has not been + set to display meta characters directly, this will convert meta + characters to a meta-prefixed key sequence. This is intended for + use by applications which wish to do their own redisplay. + + -- Function: int rl_message (const char *, ...) + The arguments are a format string as would be supplied to 'printf', + possibly containing conversion specifications such as '%d', and any + additional arguments necessary to satisfy the conversion + specifications. The resulting string is displayed in the "echo + area". The echo area is also used to display numeric arguments and + search strings. You should call 'rl_save_prompt' to save the + prompt information before calling this function. + + -- Function: int rl_clear_message (void) + Clear the message in the echo area. If the prompt was saved with a + call to 'rl_save_prompt' before the last call to 'rl_message', call + 'rl_restore_prompt' before calling this function. + + -- Function: void rl_save_prompt (void) + Save the local Readline prompt display state in preparation for + displaying a new message in the message area with 'rl_message()'. + + -- Function: void rl_restore_prompt (void) + Restore the local Readline prompt display state saved by the most + recent call to 'rl_save_prompt'. if 'rl_save_prompt' was called to + save the prompt before a call to 'rl_message', this function should + be called before the corresponding call to 'rl_clear_message'. + + -- Function: int rl_expand_prompt (char *prompt) + Expand any special character sequences in PROMPT and set up the + local Readline prompt redisplay variables. This function is called + by 'readline()'. It may also be called to expand the primary + prompt if the 'rl_on_new_line_with_prompt()' function or + 'rl_already_prompted' variable is used. It returns the number of + visible characters on the last line of the (possibly multi-line) + prompt. Applications may indicate that the prompt contains + characters that take up no physical screen space when displayed by + bracketing a sequence of such characters with the special markers + 'RL_PROMPT_START_IGNORE' and 'RL_PROMPT_END_IGNORE' (declared in + 'readline.h' as '\001' and '\002', respectively). This may be used + to embed terminal-specific escape sequences in prompts. + + -- Function: int rl_set_prompt (const char *prompt) + Make Readline use PROMPT for subsequent redisplay. This calls + 'rl_expand_prompt()' to expand the prompt and sets 'rl_prompt' to + the result. + + +File: readline.info, Node: Modifying Text, Next: Character Input, Prev: Redisplay, Up: Readline Convenience Functions + +2.4.7 Modifying Text +-------------------- + + -- Function: int rl_insert_text (const char *text) + Insert TEXT into the line at the current cursor position. Returns + the number of characters inserted. + + -- Function: int rl_delete_text (int start, int end) + Delete the text between START and END in the current line. Returns + the number of characters deleted. + + -- Function: char * rl_copy_text (int start, int end) + Return a copy of the text between START and END in the current + line. + + -- Function: int rl_kill_text (int start, int end) + Copy the text between START and END in the current line to the kill + ring, appending or prepending to the last kill if the last command + was a kill command. The text is deleted. If START is less than + END, the text is appended, otherwise prepended. If the last + command was not a kill, a new kill ring slot is used. + + -- Function: int rl_push_macro_input (char *macro) + Cause MACRO to be inserted into the line, as if it had been invoked + by a key bound to a macro. Not especially useful; use + 'rl_insert_text()' instead. + + +File: readline.info, Node: Character Input, Next: Terminal Management, Prev: Modifying Text, Up: Readline Convenience Functions + +2.4.8 Character Input +--------------------- + + -- Function: int rl_read_key (void) + Return the next character available from Readline's current input + stream. This handles input inserted into the input stream via + RL_PENDING_INPUT (*note Readline Variables::) and + 'rl_stuff_char()', macros, and characters read from the keyboard. + While waiting for input, this function will call any function + assigned to the 'rl_event_hook' variable. + + -- Function: int rl_getc (FILE *stream) + Return the next character available from STREAM, which is assumed + to be the keyboard. + + -- Function: int rl_stuff_char (int c) + Insert C into the Readline input stream. It will be "read" before + Readline attempts to read characters from the terminal with + 'rl_read_key()'. Up to 512 characters may be pushed back. + 'rl_stuff_char' returns 1 if the character was successfully + inserted; 0 otherwise. + + -- Function: int rl_execute_next (int c) + Make C be the next command to be executed when 'rl_read_key()' is + called. This sets RL_PENDING_INPUT. + + -- Function: int rl_clear_pending_input (void) + Unset RL_PENDING_INPUT, effectively negating the effect of any + previous call to 'rl_execute_next()'. This works only if the + pending input has not already been read with 'rl_read_key()'. + + -- Function: int rl_set_keyboard_input_timeout (int u) + While waiting for keyboard input in 'rl_read_key()', Readline will + wait for U microseconds for input before calling any function + assigned to 'rl_event_hook'. U must be greater than or equal to + zero (a zero-length timeout is equivalent to a poll). The default + waiting period is one-tenth of a second. Returns the old timeout + value. + + -- Function: int rl_set_timeout (unsigned int secs, unsigned int usecs) + Set a timeout for subsequent calls to 'readline()'. If Readline + does not read a complete line, or the number of characters + specified by 'rl_num_chars_to_read', before the duration specified + by SECS (in seconds) and USECS (microseconds), it returns and sets + 'RL_STATE_TIMEOUT' in 'rl_readline_state'. Passing 0 for 'secs' + and 'usecs' cancels any previously set timeout; the convenience + macro 'rl_clear_timeout()' is shorthand for this. Returns 0 if the + timeout is set successfully. + + -- Function: int rl_timeout_remaining (unsigned int *secs, unsigned int + *usecs) + Return the number of seconds and microseconds remaining in the + current timeout duration in *SECS and *USECS, respectively. Both + *SECS and *USECS must be non-NULL to return any values. The return + value is -1 on error or when there is no timeout set, 0 when the + timeout has expired (leaving *SECS and *USECS unchanged), and 1 if + the timeout has not expired. If either of SECS and USECS is + 'NULL', the return value indicates whether the timeout has expired. + + +File: readline.info, Node: Terminal Management, Next: Utility Functions, Prev: Character Input, Up: Readline Convenience Functions + +2.4.9 Terminal Management +------------------------- + + -- Function: void rl_prep_terminal (int meta_flag) + Modify the terminal settings for Readline's use, so 'readline()' + can read a single character at a time from the keyboard. The + META_FLAG argument should be non-zero if Readline should read + eight-bit input. + + -- Function: void rl_deprep_terminal (void) + Undo the effects of 'rl_prep_terminal()', leaving the terminal in + the state in which it was before the most recent call to + 'rl_prep_terminal()'. + + -- Function: void rl_tty_set_default_bindings (Keymap kmap) + Read the operating system's terminal editing characters (as would + be displayed by 'stty') to their Readline equivalents. The + bindings are performed in KMAP. + + -- Function: void rl_tty_unset_default_bindings (Keymap kmap) + Reset the bindings manipulated by 'rl_tty_set_default_bindings' so + that the terminal editing characters are bound to 'rl_insert'. The + bindings are performed in KMAP. + + -- Function: int rl_tty_set_echoing (int value) + Set Readline's idea of whether or not it is echoing output to its + output stream (RL_OUTSTREAM). If VALUE is 0, Readline does not + display output to RL_OUTSTREAM; any other value enables output. + The initial value is set when Readline initializes the terminal + settings. This function returns the previous value. + + -- Function: int rl_reset_terminal (const char *terminal_name) + Reinitialize Readline's idea of the terminal settings using + TERMINAL_NAME as the terminal type (e.g., 'vt100'). If + TERMINAL_NAME is 'NULL', the value of the 'TERM' environment + variable is used. + + +File: readline.info, Node: Utility Functions, Next: Miscellaneous Functions, Prev: Terminal Management, Up: Readline Convenience Functions + +2.4.10 Utility Functions +------------------------ + + -- Function: int rl_save_state (struct readline_state *sp) + Save a snapshot of Readline's internal state to SP. The contents + of the READLINE_STATE structure are documented in 'readline.h'. + The caller is responsible for allocating the structure. + + -- Function: int rl_restore_state (struct readline_state *sp) + Restore Readline's internal state to that stored in SP, which must + have been saved by a call to 'rl_save_state'. The contents of the + READLINE_STATE structure are documented in 'readline.h'. The + caller is responsible for freeing the structure. + + -- Function: void rl_free (void *mem) + Deallocate the memory pointed to by MEM. MEM must have been + allocated by 'malloc'. + + -- Function: void rl_replace_line (const char *text, int clear_undo) + Replace the contents of 'rl_line_buffer' with TEXT. The point and + mark are preserved, if possible. If CLEAR_UNDO is non-zero, the + undo list associated with the current line is cleared. + + -- Function: void rl_extend_line_buffer (int len) + Ensure that 'rl_line_buffer' has enough space to hold LEN + characters, possibly reallocating it if necessary. + + -- Function: int rl_initialize (void) + Initialize or re-initialize Readline's internal state. It's not + strictly necessary to call this; 'readline()' calls it before + reading any input. + + -- Function: int rl_ding (void) + Ring the terminal bell, obeying the setting of 'bell-style'. + + -- Function: int rl_alphabetic (int c) + Return 1 if C is an alphabetic character. + + -- Function: void rl_display_match_list (char **matches, int len, int + max) + A convenience function for displaying a list of strings in columnar + format on Readline's output stream. 'matches' is the list of + strings, in argv format, such as a list of completion matches. + 'len' is the number of strings in 'matches', and 'max' is the + length of the longest string in 'matches'. This function uses the + setting of 'print-completions-horizontally' to select how the + matches are displayed (*note Readline Init File Syntax::). When + displaying completions, this function sets the number of columns + used for display to the value of 'completion-display-width', the + value of the environment variable 'COLUMNS', or the screen width, + in that order. + + The following are implemented as macros, defined in 'chardefs.h'. +Applications should refrain from using them. + + -- Function: int _rl_uppercase_p (int c) + Return 1 if C is an uppercase alphabetic character. + + -- Function: int _rl_lowercase_p (int c) + Return 1 if C is a lowercase alphabetic character. + + -- Function: int _rl_digit_p (int c) + Return 1 if C is a numeric character. + + -- Function: int _rl_to_upper (int c) + If C is a lowercase alphabetic character, return the corresponding + uppercase character. + + -- Function: int _rl_to_lower (int c) + If C is an uppercase alphabetic character, return the corresponding + lowercase character. + + -- Function: int _rl_digit_value (int c) + If C is a number, return the value it represents. + + +File: readline.info, Node: Miscellaneous Functions, Next: Alternate Interface, Prev: Utility Functions, Up: Readline Convenience Functions + +2.4.11 Miscellaneous Functions +------------------------------ + + -- Function: int rl_macro_bind (const char *keyseq, const char *macro, + Keymap map) + Bind the key sequence KEYSEQ to invoke the macro MACRO. The + binding is performed in MAP. When KEYSEQ is invoked, the MACRO + will be inserted into the line. This function is deprecated; use + 'rl_generic_bind()' instead. + + -- Function: void rl_macro_dumper (int readable) + Print the key sequences bound to macros and their values, using the + current keymap, to 'rl_outstream'. If READABLE is non-zero, the + list is formatted in such a way that it can be made part of an + 'inputrc' file and re-read. + + -- Function: int rl_variable_bind (const char *variable, const char + *value) + Make the Readline variable VARIABLE have VALUE. This behaves as if + the Readline command 'set VARIABLE VALUE' had been executed in an + 'inputrc' file (*note Readline Init File Syntax::). + + -- Function: char * rl_variable_value (const char *variable) + Return a string representing the value of the Readline variable + VARIABLE. For boolean variables, this string is either 'on' or + 'off'. + + -- Function: void rl_variable_dumper (int readable) + Print the Readline variable names and their current values to + 'rl_outstream'. If READABLE is non-zero, the list is formatted in + such a way that it can be made part of an 'inputrc' file and + re-read. + + -- Function: int rl_set_paren_blink_timeout (int u) + Set the time interval (in microseconds) that Readline waits when + showing a balancing character when 'blink-matching-paren' has been + enabled. + + -- Function: char * rl_get_termcap (const char *cap) + Retrieve the string value of the termcap capability CAP. Readline + fetches the termcap entry for the current terminal name and uses + those capabilities to move around the screen line and perform other + terminal-specific operations, like erasing a line. Readline does + not use all of a terminal's capabilities, and this function will + return values for only those capabilities Readline uses. + + -- Function: void rl_clear_history (void) + Clear the history list by deleting all of the entries, in the same + manner as the History library's 'clear_history()' function. This + differs from 'clear_history' because it frees private data Readline + saves in the history list. + + -- Function: void rl_activate_mark (void) + Enable an _active_ mark. When this is enabled, the text between + point and mark (the REGION) is displayed in the terminal's standout + mode (a FACE). This is called by various Readline functions that + set the mark and insert text, and is available for applications to + call. + + -- Function: void rl_deactivate_mark (void) + Turn off the active mark. + + -- Function: void rl_keep_mark_active (void) + Indicate that the mark should remain active when the current + Readline function completes and after redisplay occurs. In most + cases, the mark remains active for only the duration of a single + bindable Readline function. + + -- Function: int rl_mark_active_p (void) + Return a non-zero value if the mark is currently active; zero + otherwise. + + +File: readline.info, Node: Alternate Interface, Next: A Readline Example, Prev: Miscellaneous Functions, Up: Readline Convenience Functions + +2.4.12 Alternate Interface +-------------------------- + +An alternate interface is available to plain 'readline()'. Some +applications need to interleave keyboard I/O with file, device, or +window system I/O, typically by using a main loop to 'select()' on +various file descriptors. To accommodate this need, Readline can also +be invoked as a 'callback' function from an event loop. There are +functions available to make this easy. + + -- Function: void rl_callback_handler_install (const char *prompt, + rl_vcpfunc_t *lhandler) + Set up the terminal for Readline I/O and display the initial + expanded value of PROMPT. Save the value of LHANDLER to use as a + handler function to call when a complete line of input has been + entered. The handler function receives the text of the line as an + argument. As with 'readline()', the handler function should 'free' + the line when it it finished with it. + + -- Function: void rl_callback_read_char (void) + Whenever an application determines that keyboard input is + available, it should call 'rl_callback_read_char()', which will + read the next character from the current input source. If that + character completes the line, 'rl_callback_read_char' will invoke + the LHANDLER function installed by 'rl_callback_handler_install' to + process the line. Before calling the LHANDLER function, the + terminal settings are reset to the values they had before calling + 'rl_callback_handler_install'. If the LHANDLER function returns, + and the line handler remains installed, the terminal settings are + modified for Readline's use again. 'EOF' is indicated by calling + LHANDLER with a 'NULL' line. + + -- Function: void rl_callback_sigcleanup (void) + Clean up any internal state the callback interface uses to maintain + state between calls to rl_callback_read_char (e.g., the state of + any active incremental searches). This is intended to be used by + applications that wish to perform their own signal handling; + Readline's internal signal handler calls this when appropriate. + + -- Function: void rl_callback_handler_remove (void) + Restore the terminal to its initial state and remove the line + handler. You may call this function from within a callback as well + as independently. If the LHANDLER installed by + 'rl_callback_handler_install' does not exit the program, either + this function or the function referred to by the value of + 'rl_deprep_term_function' should be called before the program exits + to reset the terminal settings. + + +File: readline.info, Node: A Readline Example, Next: Alternate Interface Example, Prev: Alternate Interface, Up: Readline Convenience Functions + +2.4.13 A Readline Example +------------------------- + +Here is a function which changes lowercase characters to their uppercase +equivalents, and uppercase characters to lowercase. If this function +was bound to 'M-c', then typing 'M-c' would change the case of the +character under point. Typing 'M-1 0 M-c' would change the case of the +following 10 characters, leaving the cursor on the last character +changed. + + /* Invert the case of the COUNT following characters. */ + int + invert_case_line (count, key) + int count, key; + { + register int start, end, i; + + start = rl_point; + + if (rl_point >= rl_end) + return (0); + + if (count < 0) + { + direction = -1; + count = -count; + } + else + direction = 1; + + /* Find the end of the range to modify. */ + end = start + (count * direction); + + /* Force it to be within range. */ + if (end > rl_end) + end = rl_end; + else if (end < 0) + end = 0; + + if (start == end) + return (0); + + if (start > end) + { + int temp = start; + start = end; + end = temp; + } + + /* Tell readline that we are modifying the line, + so it will save the undo information. */ + rl_modifying (start, end); + + for (i = start; i != end; i++) + { + if (_rl_uppercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); + else if (_rl_lowercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); + } + /* Move point to on top of the last character changed. */ + rl_point = (direction == 1) ? end - 1 : start; + return (0); + } + + +File: readline.info, Node: Alternate Interface Example, Prev: A Readline Example, Up: Readline Convenience Functions + +2.4.14 Alternate Interface Example +---------------------------------- + +Here is a complete program that illustrates Readline's alternate +interface. It reads lines from the terminal and displays them, +providing the standard history and TAB completion functions. It +understands the EOF character or "exit" to exit the program. + + /* Standard include files. stdio.h is required. */ + #include + #include + #include + #include + + /* Used for select(2) */ + #include + #include + + #include + + #include + + /* Standard readline include files. */ + #include + #include + + static void cb_linehandler (char *); + static void sighandler (int); + + int running; + int sigwinch_received; + const char *prompt = "rltest$ "; + + /* Handle SIGWINCH and window size changes when readline is not active and + reading a character. */ + static void + sighandler (int sig) + { + sigwinch_received = 1; + } + + /* Callback function called for each line when accept-line executed, EOF + seen, or EOF character read. This sets a flag and returns; it could + also call exit(3). */ + static void + cb_linehandler (char *line) + { + /* Can use ^D (stty eof) or `exit' to exit. */ + if (line == NULL || strcmp (line, "exit") == 0) + { + if (line == 0) + printf ("\n"); + printf ("exit\n"); + /* This function needs to be called to reset the terminal settings, + and calling it from the line handler keeps one extra prompt from + being displayed. */ + rl_callback_handler_remove (); + + running = 0; + } + else + { + if (*line) + add_history (line); + printf ("input line: %s\n", line); + free (line); + } + } + + int + main (int c, char **v) + { + fd_set fds; + int r; + + /* Set the default locale values according to environment variables. */ + setlocale (LC_ALL, ""); + + /* Handle window size changes when readline is not active and reading + characters. */ + signal (SIGWINCH, sighandler); + + /* Install the line handler. */ + rl_callback_handler_install (prompt, cb_linehandler); + + /* Enter a simple event loop. This waits until something is available + to read on readline's input stream (defaults to standard input) and + calls the builtin character read callback to read it. It does not + have to modify the user's terminal settings. */ + running = 1; + while (running) + { + FD_ZERO (&fds); + FD_SET (fileno (rl_instream), &fds); + + r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); + if (r < 0 && errno != EINTR) + { + perror ("rltest: select"); + rl_callback_handler_remove (); + break; + } + if (sigwinch_received) + { + rl_resize_terminal (); + sigwinch_received = 0; + } + if (r < 0) + continue; + + if (FD_ISSET (fileno (rl_instream), &fds)) + rl_callback_read_char (); + } + + printf ("rltest: Event loop has exited\n"); + return 0; + } + + +File: readline.info, Node: Readline Signal Handling, Next: Custom Completers, Prev: Readline Convenience Functions, Up: Programming with GNU Readline + +2.5 Readline Signal Handling +============================ + +Signals are asynchronous events sent to a process by the Unix kernel, +sometimes on behalf of another process. They are intended to indicate +exceptional events, like a user pressing the terminal's interrupt key, +or a network connection being broken. There is a class of signals that +can be sent to the process currently reading input from the keyboard. +Since Readline changes the terminal attributes when it is called, it +needs to perform special processing when such a signal is received in +order to restore the terminal to a sane state, or provide application +writers with functions to do so manually. + + Readline contains an internal signal handler that is installed for a +number of signals ('SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGALRM', +'SIGTSTP', 'SIGTTIN', and 'SIGTTOU'). When one of these signals is +received, the signal handler will reset the terminal attributes to those +that were in effect before 'readline()' was called, reset the signal +handling to what it was before 'readline()' was called, and resend the +signal to the calling application. If and when the calling +application's signal handler returns, Readline will reinitialize the +terminal and continue to accept input. When a 'SIGINT' is received, the +Readline signal handler performs some additional work, which will cause +any partially-entered line to be aborted (see the description of +'rl_free_line_state()' below). + + There is an additional Readline signal handler, for 'SIGWINCH', which +the kernel sends to a process whenever the terminal's size changes (for +example, if a user resizes an 'xterm'). The Readline 'SIGWINCH' handler +updates Readline's internal screen size information, and then calls any +'SIGWINCH' signal handler the calling application has installed. +Readline calls the application's 'SIGWINCH' signal handler without +resetting the terminal to its original state. If the application's +signal handler does more than update its idea of the terminal size and +return (for example, a 'longjmp' back to a main processing loop), it +_must_ call 'rl_cleanup_after_signal()' (described below), to restore +the terminal state. + + When an application is using the callback interface (*note Alternate +Interface::), Readline installs signal handlers only for the duration of +the call to 'rl_callback_read_char'. Applications using the callback +interface should be prepared to clean up Readline's state if they wish +to handle the signal before the line handler completes and restores the +terminal state. + + If an application using the callback interface wishes to have +Readline install its signal handlers at the time the application calls +'rl_callback_handler_install' and remove them only when a complete line +of input has been read, it should set the +'rl_persistent_signal_handlers' variable to a non-zero value. This +allows an application to defer all of the handling of the signals +Readline catches to Readline. Applications should use this variable +with care; it can result in Readline catching signals and not acting on +them (or allowing the application to react to them) until the +application calls 'rl_callback_read_char'. This can result in an +application becoming less responsive to keyboard signals like SIGINT. If +an application does not want or need to perform any signal handling, or +does not need to do any processing between calls to +'rl_callback_read_char', setting this variable may be desirable. + + Readline provides two variables that allow application writers to +control whether or not it will catch certain signals and act on them +when they are received. It is important that applications change the +values of these variables only when calling 'readline()', not in a +signal handler, so Readline's internal signal state is not corrupted. + + -- Variable: int rl_catch_signals + If this variable is non-zero, Readline will install signal handlers + for 'SIGINT', 'SIGQUIT', 'SIGTERM', 'SIGHUP', 'SIGALRM', 'SIGTSTP', + 'SIGTTIN', and 'SIGTTOU'. + + The default value of 'rl_catch_signals' is 1. + + -- Variable: int rl_catch_sigwinch + If this variable is set to a non-zero value, Readline will install + a signal handler for 'SIGWINCH'. + + The default value of 'rl_catch_sigwinch' is 1. + + -- Variable: int rl_persistent_signal_handlers + If an application using the callback interface wishes Readline's + signal handlers to be installed and active during the set of calls + to 'rl_callback_read_char' that constitutes an entire single line, + it should set this variable to a non-zero value. + + The default value of 'rl_persistent_signal_handlers' is 0. + + -- Variable: int rl_change_environment + If this variable is set to a non-zero value, and Readline is + handling 'SIGWINCH', Readline will modify the LINES and COLUMNS + environment variables upon receipt of a 'SIGWINCH' + + The default value of 'rl_change_environment' is 1. + + If an application does not wish to have Readline catch any signals, +or to handle signals other than those Readline catches ('SIGHUP', for +example), Readline provides convenience functions to do the necessary +terminal and internal state cleanup upon receipt of a signal. + + -- Function: int rl_pending_signal (void) + Return the signal number of the most recent signal Readline + received but has not yet handled, or 0 if there is no pending + signal. + + -- Function: void rl_cleanup_after_signal (void) + This function will reset the state of the terminal to what it was + before 'readline()' was called, and remove the Readline signal + handlers for all signals, depending on the values of + 'rl_catch_signals' and 'rl_catch_sigwinch'. + + -- Function: void rl_free_line_state (void) + This will free any partial state associated with the current input + line (undo information, any partial history entry, any + partially-entered keyboard macro, and any partially-entered numeric + argument). This should be called before + 'rl_cleanup_after_signal()'. The Readline signal handler for + 'SIGINT' calls this to abort the current input line. + + -- Function: void rl_reset_after_signal (void) + This will reinitialize the terminal and reinstall any Readline + signal handlers, depending on the values of 'rl_catch_signals' and + 'rl_catch_sigwinch'. + + If an application wants to force Readline to handle any signals that +have arrived while it has been executing, 'rl_check_signals()' will call +Readline's internal signal handler if there are any pending signals. +This is primarily intended for those applications that use a custom +'rl_getc_function' (*note Readline Variables::) and wish to handle +signals received while waiting for input. + + -- Function: void rl_check_signals (void) + If there are any pending signals, call Readline's internal signal + handling functions to process them. 'rl_pending_signal()' can be + used independently to determine whether or not there are any + pending signals. + + If an application does not wish Readline to catch 'SIGWINCH', it may +call 'rl_resize_terminal()' or 'rl_set_screen_size()' to force Readline +to update its idea of the terminal size when it receives a 'SIGWINCH'. + + -- Function: void rl_echo_signal_char (int sig) + If an application wishes to install its own signal handlers, but + still have Readline display characters that generate signals, + calling this function with SIG set to 'SIGINT', 'SIGQUIT', or + 'SIGTSTP' will display the character generating that signal. + + -- Function: void rl_resize_terminal (void) + Update Readline's internal screen size by reading values from the + kernel. + + -- Function: void rl_set_screen_size (int rows, int cols) + Set Readline's idea of the terminal size to ROWS rows and COLS + columns. If either ROWS or COLUMNS is less than or equal to 0, + Readline's idea of that terminal dimension is unchanged. This is + intended to tell Readline the physical dimensions of the terminal, + and is used internally to calculate the maximum number of + characters that may appear on a single line and on the screen. + + If an application does not want to install a 'SIGWINCH' handler, but +is still interested in the screen dimensions, it may query Readline's +idea of the screen size. + + -- Function: void rl_get_screen_size (int *rows, int *cols) + Return Readline's idea of the terminal's size in the variables + pointed to by the arguments. + + -- Function: void rl_reset_screen_size (void) + Cause Readline to reobtain the screen size and recalculate its + dimensions. + + The following functions install and remove Readline's signal +handlers. + + -- Function: int rl_set_signals (void) + Install Readline's signal handler for 'SIGINT', 'SIGQUIT', + 'SIGTERM', 'SIGHUP', 'SIGALRM', 'SIGTSTP', 'SIGTTIN', 'SIGTTOU', + and 'SIGWINCH', depending on the values of 'rl_catch_signals' and + 'rl_catch_sigwinch'. + + -- Function: int rl_clear_signals (void) + Remove all of the Readline signal handlers installed by + 'rl_set_signals()'. + + +File: readline.info, Node: Custom Completers, Prev: Readline Signal Handling, Up: Programming with GNU Readline + +2.6 Custom Completers +===================== + +Typically, a program that reads commands from the user has a way of +disambiguating commands and data. If your program is one of these, then +it can provide completion for commands, data, or both. The following +sections describe how your program and Readline cooperate to provide +this service. + +* Menu: + +* How Completing Works:: The logic used to do completion. +* Completion Functions:: Functions provided by Readline. +* Completion Variables:: Variables which control completion. +* A Short Completion Example:: An example of writing completer subroutines. + + +File: readline.info, Node: How Completing Works, Next: Completion Functions, Up: Custom Completers + +2.6.1 How Completing Works +-------------------------- + +In order to complete some text, the full list of possible completions +must be available. That is, it is not possible to accurately expand a +partial word without knowing all of the possible words which make sense +in that context. The Readline library provides the user interface to +completion, and two of the most common completion functions: filename +and username. For completing other types of text, you must write your +own completion function. This section describes exactly what such +functions must do, and provides an example. + + There are three major functions used to perform completion: + + 1. The user-interface function 'rl_complete()'. This function is + called with the same arguments as other bindable Readline + functions: COUNT and INVOKING_KEY. It isolates the word to be + completed and calls 'rl_completion_matches()' to generate a list of + possible completions. It then either lists the possible + completions, inserts the possible completions, or actually performs + the completion, depending on which behavior is desired. + + 2. The internal function 'rl_completion_matches()' uses an + application-supplied "generator" function to generate the list of + possible matches, and then returns the array of these matches. The + caller should place the address of its generator function in + 'rl_completion_entry_function'. + + 3. The generator function is called repeatedly from + 'rl_completion_matches()', returning a string each time. The + arguments to the generator function are TEXT and STATE. TEXT is + the partial word to be completed. STATE is zero the first time the + function is called, allowing the generator to perform any necessary + initialization, and a positive non-zero integer for each subsequent + call. The generator function returns '(char *)NULL' to inform + 'rl_completion_matches()' that there are no more possibilities + left. Usually the generator function computes the list of possible + completions when STATE is zero, and returns them one at a time on + subsequent calls. Each string the generator function returns as a + match must be allocated with 'malloc()'; Readline frees the strings + when it has finished with them. Such a generator function is + referred to as an "application-specific completion function". + + -- Function: int rl_complete (int ignore, int invoking_key) + Complete the word at or before point. You have supplied the + function that does the initial simple matching selection algorithm + (see 'rl_completion_matches()'). The default is to do filename + completion. + + -- Variable: rl_compentry_func_t * rl_completion_entry_function + This is a pointer to the generator function for + 'rl_completion_matches()'. If the value of + 'rl_completion_entry_function' is 'NULL' then the default filename + generator function, 'rl_filename_completion_function()', is used. + An "application-specific completion function" is a function whose + address is assigned to 'rl_completion_entry_function' and whose + return values are used to generate possible completions. + + +File: readline.info, Node: Completion Functions, Next: Completion Variables, Prev: How Completing Works, Up: Custom Completers + +2.6.2 Completion Functions +-------------------------- + +Here is the complete list of callable completion functions present in +Readline. + + -- Function: int rl_complete_internal (int what_to_do) + Complete the word at or before point. WHAT_TO_DO says what to do + with the completion. A value of '?' means list the possible + completions. 'TAB' means do standard completion. '*' means insert + all of the possible completions. '!' means to display all of the + possible completions, if there is more than one, as well as + performing partial completion. '@' is similar to '!', but possible + completions are not listed if the possible completions share a + common prefix. + + -- Function: int rl_complete (int ignore, int invoking_key) + Complete the word at or before point. You have supplied the + function that does the initial simple matching selection algorithm + (see 'rl_completion_matches()' and 'rl_completion_entry_function'). + The default is to do filename completion. This calls + 'rl_complete_internal()' with an argument depending on + INVOKING_KEY. + + -- Function: int rl_possible_completions (int count, int invoking_key) + List the possible completions. See description of 'rl_complete + ()'. This calls 'rl_complete_internal()' with an argument of '?'. + + -- Function: int rl_insert_completions (int count, int invoking_key) + Insert the list of possible completions into the line, deleting the + partially-completed word. See description of 'rl_complete()'. + This calls 'rl_complete_internal()' with an argument of '*'. + + -- Function: int rl_completion_mode (rl_command_func_t *cfunc) + Returns the appropriate value to pass to 'rl_complete_internal()' + depending on whether CFUNC was called twice in succession and the + values of the 'show-all-if-ambiguous' and 'show-all-if-unmodified' + variables. Application-specific completion functions may use this + function to present the same interface as 'rl_complete()'. + + -- Function: char ** rl_completion_matches (const char *text, + rl_compentry_func_t *entry_func) + Returns an array of strings which is a list of completions for + TEXT. If there are no completions, returns 'NULL'. The first + entry in the returned array is the substitution for TEXT. The + remaining entries are the possible completions. The array is + terminated with a 'NULL' pointer. + + ENTRY_FUNC is a function of two args, and returns a 'char *'. The + first argument is TEXT. The second is a state argument; it is zero + on the first call, and non-zero on subsequent calls. ENTRY_FUNC + returns a 'NULL' pointer to the caller when there are no more + matches. + + -- Function: char * rl_filename_completion_function (const char *text, + int state) + A generator function for filename completion in the general case. + TEXT is a partial filename. The Bash source is a useful reference + for writing application-specific completion functions (the Bash + completion functions call this and other Readline functions). + + -- Function: char * rl_username_completion_function (const char *text, + int state) + A completion generator for usernames. TEXT contains a partial + username preceded by a random character (usually '~'). As with all + completion generators, STATE is zero on the first call and non-zero + for subsequent calls. + + +File: readline.info, Node: Completion Variables, Next: A Short Completion Example, Prev: Completion Functions, Up: Custom Completers + +2.6.3 Completion Variables +-------------------------- + + -- Variable: rl_compentry_func_t * rl_completion_entry_function + A pointer to the generator function for 'rl_completion_matches()'. + 'NULL' means to use 'rl_filename_completion_function()', the + default filename completer. + + -- Variable: rl_completion_func_t * rl_attempted_completion_function + A pointer to an alternative function to create matches. The + function is called with TEXT, START, and END. START and END are + indices in 'rl_line_buffer' defining the boundaries of TEXT, which + is a character string. If this function exists and returns 'NULL', + or if this variable is set to 'NULL', then 'rl_complete()' will + call the value of 'rl_completion_entry_function' to generate + matches, otherwise the array of strings returned will be used. If + this function sets the 'rl_attempted_completion_over' variable to a + non-zero value, Readline will not perform its default completion + even if this function returns no matches. + + -- Variable: rl_quote_func_t * rl_filename_quoting_function + A pointer to a function that will quote a filename in an + application-specific fashion. This is called if filename + completion is being attempted and one of the characters in + 'rl_filename_quote_characters' appears in a completed filename. + The function is called with TEXT, MATCH_TYPE, and QUOTE_POINTER. + The TEXT is the filename to be quoted. The MATCH_TYPE is either + 'SINGLE_MATCH', if there is only one completion match, or + 'MULT_MATCH'. Some functions use this to decide whether or not to + insert a closing quote character. The QUOTE_POINTER is a pointer + to any opening quote character the user typed. Some functions + choose to reset this character. + + -- Variable: rl_dequote_func_t * rl_filename_dequoting_function + A pointer to a function that will remove application-specific + quoting characters from a filename before completion is attempted, + so those characters do not interfere with matching the text against + names in the filesystem. It is called with TEXT, the text of the + word to be dequoted, and QUOTE_CHAR, which is the quoting character + that delimits the filename (usually ''' or '"'). If QUOTE_CHAR is + zero, the filename was not in an embedded string. + + -- Variable: rl_linebuf_func_t * rl_char_is_quoted_p + A pointer to a function to call that determines whether or not a + specific character in the line buffer is quoted, according to + whatever quoting mechanism the program calling Readline uses. The + function is called with two arguments: TEXT, the text of the line, + and INDEX, the index of the character in the line. It is used to + decide whether a character found in + 'rl_completer_word_break_characters' should be used to break words + for the completer. + + -- Variable: rl_compignore_func_t * rl_ignore_some_completions_function + This function, if defined, is called by the completer when real + filename completion is done, after all the matching names have been + generated. It is passed a 'NULL' terminated array of matches. The + first element ('matches[0]') is the maximal substring common to all + matches. This function can re-arrange the list of matches as + required, but each element deleted from the array must be freed. + + -- Variable: rl_icppfunc_t * rl_directory_completion_hook + This function, if defined, is allowed to modify the directory + portion of filenames Readline completes. It could be used to + expand symbolic links or shell variables in pathnames. It is + called with the address of a string (the current directory name) as + an argument, and may modify that string. If the string is replaced + with a new string, the old value should be freed. Any modified + directory name should have a trailing slash. The modified value + will be used as part of the completion, replacing the directory + portion of the pathname the user typed. At the least, even if no + other expansion is performed, this function should remove any quote + characters from the directory name, because its result will be + passed directly to 'opendir()'. + + The directory completion hook returns an integer that should be + non-zero if the function modifies its directory argument. The + function should not modify the directory argument if it returns 0. + + -- Variable: rl_icppfunc_t * rl_directory_rewrite_hook; + If non-zero, this is the address of a function to call when + completing a directory name. This function takes the address of + the directory name to be modified as an argument. Unlike + 'rl_directory_completion_hook', it only modifies the directory name + used in 'opendir', not what is displayed when the possible + completions are printed or inserted. It is called before + rl_directory_completion_hook. At the least, even if no other + expansion is performed, this function should remove any quote + characters from the directory name, because its result will be + passed directly to 'opendir()'. + + The directory rewrite hook returns an integer that should be + non-zero if the function modifies its directory argument. The + function should not modify the directory argument if it returns 0. + + -- Variable: rl_icppfunc_t * rl_filename_stat_hook + If non-zero, this is the address of a function for the completer to + call before deciding which character to append to a completed name. + This function modifies its filename name argument, and the modified + value is passed to 'stat()' to determine the file's type and + characteristics. This function does not need to remove quote + characters from the filename. + + The stat hook returns an integer that should be non-zero if the + function modifies its directory argument. The function should not + modify the directory argument if it returns 0. + + -- Variable: rl_dequote_func_t * rl_filename_rewrite_hook + If non-zero, this is the address of a function called when reading + directory entries from the filesystem for completion and comparing + them to the partial word to be completed. The function should + perform any necessary application or system-specific conversion on + the filename, such as converting between character sets or + converting from a filesystem format to a character input format. + The function takes two arguments: FNAME, the filename to be + converted, and FNLEN, its length in bytes. It must either return + its first argument (if no conversion takes place) or the converted + filename in newly-allocated memory. The converted form is used to + compare against the word to be completed, and, if it matches, is + added to the list of matches. Readline will free the allocated + string. + + -- Variable: rl_compdisp_func_t * rl_completion_display_matches_hook + If non-zero, then this is the address of a function to call when + completing a word would normally display the list of possible + matches. This function is called in lieu of Readline displaying + the list. It takes three arguments: ('char **'MATCHES, 'int' + NUM_MATCHES, 'int' MAX_LENGTH) where MATCHES is the array of + matching strings, NUM_MATCHES is the number of strings in that + array, and MAX_LENGTH is the length of the longest string in that + array. Readline provides a convenience function, + 'rl_display_match_list', that takes care of doing the display to + Readline's output stream. You may call that function from this + hook. + + -- Variable: const char * rl_basic_word_break_characters + The basic list of characters that signal a break between words for + the completer routine. The default value of this variable is the + characters which break words for completion in Bash: '" + \t\n\"\\'`@$><=;|&{("'. + + -- Variable: const char * rl_basic_quote_characters + A list of quote characters which can cause a word break. + + -- Variable: const char * rl_completer_word_break_characters + The list of characters that signal a break between words for + 'rl_complete_internal()'. The default list is the value of + 'rl_basic_word_break_characters'. + + -- Variable: rl_cpvfunc_t * rl_completion_word_break_hook + If non-zero, this is the address of a function to call when + Readline is deciding where to separate words for word completion. + It should return a character string like + 'rl_completer_word_break_characters' to be used to perform the + current completion. The function may choose to set + 'rl_completer_word_break_characters' itself. If the function + returns 'NULL', 'rl_completer_word_break_characters' is used. + + -- Variable: const char * rl_completer_quote_characters + A list of characters which can be used to quote a substring of the + line. Completion occurs on the entire substring, and within the + substring 'rl_completer_word_break_characters' are treated as any + other character, unless they also appear within this list. + + -- Variable: const char * rl_filename_quote_characters + A list of characters that cause a filename to be quoted by the + completer when they appear in a completed filename. The default is + the null string. + + -- Variable: const char * rl_special_prefixes + The list of characters that are word break characters, but should + be left in TEXT when it is passed to the completion function. + Programs can use this to help determine what kind of completing to + do. For instance, Bash sets this variable to "$@" so that it can + complete shell variables and hostnames. + + -- Variable: int rl_completion_query_items + Up to this many items will be displayed in response to a + possible-completions call. After that, Readline asks the user for + confirmation before displaying them. The default value is 100. A + negative value indicates that Readline should never ask for + confirmation. + + -- Variable: int rl_completion_append_character + When a single completion alternative matches at the end of the + command line, this character is appended to the inserted completion + text. The default is a space character (' '). Setting this to the + null character ('\0') prevents anything being appended + automatically. This can be changed in application-specific + completion functions to provide the "most sensible word separator + character" according to an application-specific command line syntax + specification. It is set to the default before any + application-specific completion function is called, and may only be + changed within such a function. + + -- Variable: int rl_completion_suppress_append + If non-zero, RL_COMPLETION_APPEND_CHARACTER is not appended to + matches at the end of the command line, as described above. It is + set to 0 before any application-specific completion function is + called, and may only be changed within such a function. + + -- Variable: int rl_completion_quote_character + When Readline is completing quoted text, as delimited by one of the + characters in RL_COMPLETER_QUOTE_CHARACTERS, it sets this variable + to the quoting character found. This is set before any + application-specific completion function is called. + + -- Variable: int rl_completion_suppress_quote + If non-zero, Readline does not append a matching quote character + when performing completion on a quoted string. It is set to 0 + before any application-specific completion function is called, and + may only be changed within such a function. + + -- Variable: int rl_completion_found_quote + When Readline is completing quoted text, it sets this variable to a + non-zero value if the word being completed contains or is delimited + by any quoting characters, including backslashes. This is set + before any application-specific completion function is called. + + -- Variable: int rl_completion_mark_symlink_dirs + If non-zero, a slash will be appended to completed filenames that + are symbolic links to directory names, subject to the value of the + user-settable MARK-DIRECTORIES variable. This variable exists so + that application-specific completion functions can override the + user's global preference (set via the MARK-SYMLINKED-DIRECTORIES + Readline variable) if appropriate. This variable is set to the + user's preference before any application-specific completion + function is called, so unless that function modifies the value, the + user's preferences are honored. + + -- Variable: int rl_ignore_completion_duplicates + If non-zero, then duplicates in the matches are removed. The + default is 1. + + -- Variable: int rl_filename_completion_desired + Non-zero means that the results of the matches are to be treated as + filenames. This is _always_ zero when completion is attempted, and + can only be changed within an application-specific completion + function. If it is set to a non-zero value by such a function, + directory names have a slash appended and Readline attempts to + quote completed filenames if they contain any characters in + 'rl_filename_quote_characters' and 'rl_filename_quoting_desired' is + set to a non-zero value. + + -- Variable: int rl_filename_quoting_desired + Non-zero means that the results of the matches are to be quoted + using double quotes (or an application-specific quoting mechanism) + if the completed filename contains any characters in + 'rl_filename_quote_chars'. This is _always_ non-zero when + completion is attempted, and can only be changed within an + application-specific completion function. The quoting is effected + via a call to the function pointed to by + 'rl_filename_quoting_function'. + + -- Variable: int rl_attempted_completion_over + If an application-specific completion function assigned to + 'rl_attempted_completion_function' sets this variable to a non-zero + value, Readline will not perform its default filename completion + even if the application's completion function returns no matches. + It should be set only by an application's completion function. + + -- Variable: int rl_sort_completion_matches + If an application sets this variable to 0, Readline will not sort + the list of completions (which implies that it cannot remove any + duplicate completions). The default value is 1, which means that + Readline will sort the completions and, depending on the value of + 'rl_ignore_completion_duplicates', will attempt to remove duplicate + matches. + + -- Variable: int rl_completion_type + Set to a character describing the type of completion Readline is + currently attempting; see the description of + 'rl_complete_internal()' (*note Completion Functions::) for the + list of characters. This is set to the appropriate value before + any application-specific completion function is called, allowing + such functions to present the same interface as 'rl_complete()'. + + -- Variable: int rl_completion_invoking_key + Set to the final character in the key sequence that invoked one of + the completion functions that call 'rl_complete_internal()'. This + is set to the appropriate value before any application-specific + completion function is called. + + -- Variable: int rl_inhibit_completion + If this variable is non-zero, completion is inhibited. The + completion character will be inserted as any other bound to + 'self-insert'. + + +File: readline.info, Node: A Short Completion Example, Prev: Completion Variables, Up: Custom Completers + +2.6.4 A Short Completion Example +-------------------------------- + +Here is a small application demonstrating the use of the GNU Readline +library. It is called 'fileman', and the source code resides in +'examples/fileman.c'. This sample application provides completion of +command names, line editing features, and access to the history list. + + /* fileman.c -- A tiny application which demonstrates how to use the + GNU Readline library. This application interactively allows users + to manipulate files and their modes. */ + + #ifdef HAVE_CONFIG_H + # include + #endif + + #include + #ifdef HAVE_SYS_FILE_H + # include + #endif + #include + + #ifdef HAVE_UNISTD_H + # include + #endif + + #include + #include + #include + #include + + #if defined (HAVE_STRING_H) + # include + #else /* !HAVE_STRING_H */ + # include + #endif /* !HAVE_STRING_H */ + + #ifdef HAVE_STDLIB_H + # include + #endif + + #include + + #include + #include + + extern char *xmalloc PARAMS((size_t)); + + /* The names of functions that actually do the manipulation. */ + int com_list PARAMS((char *)); + int com_view PARAMS((char *)); + int com_rename PARAMS((char *)); + int com_stat PARAMS((char *)); + int com_pwd PARAMS((char *)); + int com_delete PARAMS((char *)); + int com_help PARAMS((char *)); + int com_cd PARAMS((char *)); + int com_quit PARAMS((char *)); + + /* A structure which contains information on the commands this program + can understand. */ + + typedef struct { + char *name; /* User printable name of the function. */ + rl_icpfunc_t *func; /* Function to call to do the job. */ + char *doc; /* Documentation for this function. */ + } COMMAND; + + COMMAND commands[] = { + { "cd", com_cd, "Change to directory DIR" }, + { "delete", com_delete, "Delete FILE" }, + { "help", com_help, "Display this text" }, + { "?", com_help, "Synonym for `help'" }, + { "list", com_list, "List files in DIR" }, + { "ls", com_list, "Synonym for `list'" }, + { "pwd", com_pwd, "Print the current working directory" }, + { "quit", com_quit, "Quit using Fileman" }, + { "rename", com_rename, "Rename FILE to NEWNAME" }, + { "stat", com_stat, "Print out statistics on FILE" }, + { "view", com_view, "View the contents of FILE" }, + { (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL } + }; + + /* Forward declarations. */ + char *stripwhite (); + COMMAND *find_command (); + + /* The name of this program, as taken from argv[0]. */ + char *progname; + + /* When non-zero, this global means the user is done using this program. */ + int done; + + char * + dupstr (s) + char *s; + { + char *r; + + r = xmalloc (strlen (s) + 1); + strcpy (r, s); + return (r); + } + + main (argc, argv) + int argc; + char **argv; + { + char *line, *s; + + setlocale (LC_ALL, ""); + + progname = argv[0]; + + initialize_readline (); /* Bind our completer. */ + + /* Loop reading and executing lines until the user quits. */ + for ( ; done == 0; ) + { + line = readline ("FileMan: "); + + if (!line) + break; + + /* Remove leading and trailing whitespace from the line. + Then, if there is anything left, add it to the history list + and execute it. */ + s = stripwhite (line); + + if (*s) + { + add_history (s); + execute_line (s); + } + + free (line); + } + exit (0); + } + + /* Execute a command line. */ + int + execute_line (line) + char *line; + { + register int i; + COMMAND *command; + char *word; + + /* Isolate the command word. */ + i = 0; + while (line[i] && whitespace (line[i])) + i++; + word = line + i; + + while (line[i] && !whitespace (line[i])) + i++; + + if (line[i]) + line[i++] = '\0'; + + command = find_command (word); + + if (!command) + { + fprintf (stderr, "%s: No such command for FileMan.\n", word); + return (-1); + } + + /* Get argument to command, if any. */ + while (whitespace (line[i])) + i++; + + word = line + i; + + /* Call the function. */ + return ((*(command->func)) (word)); + } + + /* Look up NAME as the name of a command, and return a pointer to that + command. Return a NULL pointer if NAME isn't a command name. */ + COMMAND * + find_command (name) + char *name; + { + register int i; + + for (i = 0; commands[i].name; i++) + if (strcmp (name, commands[i].name) == 0) + return (&commands[i]); + + return ((COMMAND *)NULL); + } + + /* Strip whitespace from the start and end of STRING. Return a pointer + into STRING. */ + char * + stripwhite (string) + char *string; + { + register char *s, *t; + + for (s = string; whitespace (*s); s++) + ; + + if (*s == 0) + return (s); + + t = s + strlen (s) - 1; + while (t > s && whitespace (*t)) + t--; + *++t = '\0'; + + return s; + } + + /* **************************************************************** */ + /* */ + /* Interface to Readline Completion */ + /* */ + /* **************************************************************** */ + + char *command_generator PARAMS((const char *, int)); + char **fileman_completion PARAMS((const char *, int, int)); + + /* Tell the GNU Readline library how to complete. We want to try to complete + on command names if this is the first word in the line, or on filenames + if not. */ + initialize_readline () + { + /* Allow conditional parsing of the ~/.inputrc file. */ + rl_readline_name = "FileMan"; + + /* Tell the completer that we want a crack first. */ + rl_attempted_completion_function = fileman_completion; + } + + /* Attempt to complete on the contents of TEXT. START and END bound the + region of rl_line_buffer that contains the word to complete. TEXT is + the word to complete. We can use the entire contents of rl_line_buffer + in case we want to do some simple parsing. Return the array of matches, + or NULL if there aren't any. */ + char ** + fileman_completion (text, start, end) + const char *text; + int start, end; + { + char **matches; + + matches = (char **)NULL; + + /* If this word is at the start of the line, then it is a command + to complete. Otherwise it is the name of a file in the current + directory. */ + if (start == 0) + matches = rl_completion_matches (text, command_generator); + + return (matches); + } + + /* Generator function for command completion. STATE lets us know whether + to start from scratch; without any state (i.e. STATE == 0), then we + start at the top of the list. */ + char * + command_generator (text, state) + const char *text; + int state; + { + static int list_index, len; + char *name; + + /* If this is a new word to complete, initialize now. This includes + saving the length of TEXT for efficiency, and initializing the index + variable to 0. */ + if (!state) + { + list_index = 0; + len = strlen (text); + } + + /* Return the next name which partially matches from the command list. */ + while (name = commands[list_index].name) + { + list_index++; + + if (strncmp (name, text, len) == 0) + return (dupstr(name)); + } + + /* If no names matched, then return NULL. */ + return ((char *)NULL); + } + + /* **************************************************************** */ + /* */ + /* FileMan Commands */ + /* */ + /* **************************************************************** */ + + /* String to pass to system (). This is for the LIST, VIEW and RENAME + commands. */ + static char syscom[1024]; + + /* List the file(s) named in arg. */ + com_list (arg) + char *arg; + { + if (!arg) + arg = ""; + + sprintf (syscom, "ls -FClg %s", arg); + return (system (syscom)); + } + + com_view (arg) + char *arg; + { + if (!valid_argument ("view", arg)) + return 1; + + #if defined (__MSDOS__) + /* more.com doesn't grok slashes in pathnames */ + sprintf (syscom, "less %s", arg); + #else + sprintf (syscom, "more %s", arg); + #endif + return (system (syscom)); + } + + com_rename (arg) + char *arg; + { + too_dangerous ("rename"); + return (1); + } + + com_stat (arg) + char *arg; + { + struct stat finfo; + + if (!valid_argument ("stat", arg)) + return (1); + + if (stat (arg, &finfo) == -1) + { + perror (arg); + return (1); + } + + printf ("Statistics for `%s':\n", arg); + + printf ("%s has %d link%s, and is %d byte%s in length.\n", + arg, + finfo.st_nlink, + (finfo.st_nlink == 1) ? "" : "s", + finfo.st_size, + (finfo.st_size == 1) ? "" : "s"); + printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); + printf (" Last access at: %s", ctime (&finfo.st_atime)); + printf (" Last modified at: %s", ctime (&finfo.st_mtime)); + return (0); + } + + com_delete (arg) + char *arg; + { + too_dangerous ("delete"); + return (1); + } + + /* Print out help for ARG, or for all of the commands if ARG is + not present. */ + com_help (arg) + char *arg; + { + register int i; + int printed = 0; + + for (i = 0; commands[i].name; i++) + { + if (!*arg || (strcmp (arg, commands[i].name) == 0)) + { + printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); + printed++; + } + } + + if (!printed) + { + printf ("No commands match `%s'. Possibilities are:\n", arg); + + for (i = 0; commands[i].name; i++) + { + /* Print in six columns. */ + if (printed == 6) + { + printed = 0; + printf ("\n"); + } + + printf ("%s\t", commands[i].name); + printed++; + } + + if (printed) + printf ("\n"); + } + return (0); + } + + /* Change to the directory ARG. */ + com_cd (arg) + char *arg; + { + if (chdir (arg) == -1) + { + perror (arg); + return 1; + } + + com_pwd (""); + return (0); + } + + /* Print out the current working directory. */ + com_pwd (ignore) + char *ignore; + { + char dir[1024], *s; + + s = getcwd (dir, sizeof(dir) - 1); + if (s == 0) + { + printf ("Error getting pwd: %s\n", dir); + return 1; + } + + printf ("Current directory is %s\n", dir); + return 0; + } + + /* The user wishes to quit using this program. Just set DONE non-zero. */ + com_quit (arg) + char *arg; + { + done = 1; + return (0); + } + + /* Function which tells you that you can't do this. */ + too_dangerous (caller) + char *caller; + { + fprintf (stderr, + "%s: Too dangerous for me to distribute. Write it yourself.\n", + caller); + } + + /* Return non-zero if ARG is a valid argument for CALLER, else print + an error message and return zero. */ + int + valid_argument (caller, arg) + char *caller, *arg; + { + if (!arg || !*arg) + { + fprintf (stderr, "%s: Argument required.\n", caller); + return (0); + } + + return (1); + } + + +File: readline.info, Node: GNU Free Documentation License, Next: Concept Index, Prev: Programming with GNU Readline, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + +File: readline.info, Node: Concept Index, Next: Function and Variable Index, Prev: GNU Free Documentation License, Up: Top + +Concept Index +************* + +[index] +* Menu: + +* application-specific completion functions: Custom Completers. + (line 6) +* command editing: Readline Bare Essentials. + (line 6) +* editing command lines: Readline Bare Essentials. + (line 6) +* initialization file, readline: Readline Init File. (line 6) +* interaction, readline: Readline Interaction. (line 6) +* kill ring: Readline Killing Commands. + (line 18) +* killing text: Readline Killing Commands. + (line 6) +* notation, readline: Readline Bare Essentials. + (line 6) +* readline, function: Basic Behavior. (line 12) +* variables, readline: Readline Init File Syntax. + (line 34) +* yanking text: Readline Killing Commands. + (line 6) + + +File: readline.info, Node: Function and Variable Index, Prev: Concept Index, Up: Top + +Function and Variable Index +*************************** + +[index] +* Menu: + +* _rl_digit_p: Utility Functions. (line 64) +* _rl_digit_value: Utility Functions. (line 75) +* _rl_lowercase_p: Utility Functions. (line 61) +* _rl_to_lower: Utility Functions. (line 71) +* _rl_to_upper: Utility Functions. (line 67) +* _rl_uppercase_p: Utility Functions. (line 58) +* abort (C-g): Miscellaneous Commands. + (line 10) +* accept-line (Newline or Return): Commands For History. + (line 6) +* active-region-end-color: Readline Init File Syntax. + (line 48) +* active-region-start-color: Readline Init File Syntax. + (line 35) +* backward-char (C-b): Commands For Moving. (line 15) +* backward-delete-char (Rubout): Commands For Text. (line 17) +* backward-kill-line (C-x Rubout): Commands For Killing. + (line 11) +* backward-kill-word (M-): Commands For Killing. + (line 28) +* backward-word (M-b): Commands For Moving. (line 22) +* beginning-of-history (M-<): Commands For History. + (line 19) +* beginning-of-line (C-a): Commands For Moving. (line 6) +* bell-style: Readline Init File Syntax. + (line 61) +* bind-tty-special-chars: Readline Init File Syntax. + (line 68) +* blink-matching-paren: Readline Init File Syntax. + (line 73) +* bracketed-paste-begin (): Commands For Text. (line 36) +* call-last-kbd-macro (C-x e): Keyboard Macros. (line 13) +* capitalize-word (M-c): Commands For Text. (line 69) +* character-search (C-]): Miscellaneous Commands. + (line 42) +* character-search-backward (M-C-]): Miscellaneous Commands. + (line 47) +* clear-display (M-C-l): Commands For Moving. (line 40) +* clear-screen (C-l): Commands For Moving. (line 45) +* colored-completion-prefix: Readline Init File Syntax. + (line 78) +* colored-stats: Readline Init File Syntax. + (line 88) +* comment-begin: Readline Init File Syntax. + (line 94) +* complete (): Commands For Completion. + (line 6) +* completion-display-width: Readline Init File Syntax. + (line 99) +* completion-ignore-case: Readline Init File Syntax. + (line 106) +* completion-map-case: Readline Init File Syntax. + (line 111) +* completion-prefix-display-length: Readline Init File Syntax. + (line 117) +* completion-query-items: Readline Init File Syntax. + (line 124) +* convert-meta: Readline Init File Syntax. + (line 135) +* copy-backward-word (): Commands For Killing. + (line 60) +* copy-forward-word (): Commands For Killing. + (line 65) +* copy-region-as-kill (): Commands For Killing. + (line 56) +* delete-char (C-d): Commands For Text. (line 12) +* delete-char-or-list (): Commands For Completion. + (line 39) +* delete-horizontal-space (): Commands For Killing. + (line 48) +* digit-argument (M-0, M-1, ... M--): Numeric Arguments. (line 6) +* disable-completion: Readline Init File Syntax. + (line 145) +* do-lowercase-version (M-A, M-B, M-X, ...): Miscellaneous Commands. + (line 14) +* downcase-word (M-l): Commands For Text. (line 65) +* dump-functions (): Miscellaneous Commands. + (line 70) +* dump-macros (): Miscellaneous Commands. + (line 82) +* dump-variables (): Miscellaneous Commands. + (line 76) +* echo-control-characters: Readline Init File Syntax. + (line 150) +* editing-mode: Readline Init File Syntax. + (line 155) +* emacs-editing-mode (C-e): Miscellaneous Commands. + (line 88) +* emacs-mode-string: Readline Init File Syntax. + (line 161) +* enable-active-region: Readline Init File Syntax. + (line 171) +* enable-bracketed-paste: Readline Init File Syntax. + (line 184) +* enable-keypad: Readline Init File Syntax. + (line 193) +* end-kbd-macro (C-x )): Keyboard Macros. (line 9) +* end-of-file (usually C-d): Commands For Text. (line 6) +* end-of-history (M->): Commands For History. + (line 22) +* end-of-line (C-e): Commands For Moving. (line 9) +* exchange-point-and-mark (C-x C-x): Miscellaneous Commands. + (line 37) +* expand-tilde: Readline Init File Syntax. + (line 204) +* fetch-history (): Commands For History. + (line 102) +* forward-backward-delete-char (): Commands For Text. (line 21) +* forward-char (C-f): Commands For Moving. (line 12) +* forward-search-history (C-s): Commands For History. + (line 32) +* forward-word (M-f): Commands For Moving. (line 18) +* history-preserve-point: Readline Init File Syntax. + (line 208) +* history-search-backward (): Commands For History. + (line 56) +* history-search-forward (): Commands For History. + (line 50) +* history-size: Readline Init File Syntax. + (line 214) +* history-substring-search-backward (): Commands For History. + (line 68) +* history-substring-search-forward (): Commands For History. + (line 62) +* horizontal-scroll-mode: Readline Init File Syntax. + (line 223) +* input-meta: Readline Init File Syntax. + (line 232) +* insert-comment (M-#): Miscellaneous Commands. + (line 61) +* insert-completions (M-*): Commands For Completion. + (line 18) +* isearch-terminators: Readline Init File Syntax. + (line 242) +* keymap: Readline Init File Syntax. + (line 249) +* kill-line (C-k): Commands For Killing. + (line 6) +* kill-region (): Commands For Killing. + (line 52) +* kill-whole-line (): Commands For Killing. + (line 19) +* kill-word (M-d): Commands For Killing. + (line 23) +* mark-modified-lines: Readline Init File Syntax. + (line 279) +* mark-symlinked-directories: Readline Init File Syntax. + (line 284) +* match-hidden-files: Readline Init File Syntax. + (line 289) +* menu-complete (): Commands For Completion. + (line 22) +* menu-complete-backward (): Commands For Completion. + (line 34) +* menu-complete-display-prefix: Readline Init File Syntax. + (line 296) +* meta-flag: Readline Init File Syntax. + (line 232) +* next-history (C-n): Commands For History. + (line 16) +* next-screen-line (): Commands For Moving. (line 33) +* non-incremental-forward-search-history (M-n): Commands For History. + (line 44) +* non-incremental-reverse-search-history (M-p): Commands For History. + (line 38) +* operate-and-get-next (C-o): Commands For History. + (line 95) +* output-meta: Readline Init File Syntax. + (line 301) +* overwrite-mode (): Commands For Text. (line 73) +* page-completions: Readline Init File Syntax. + (line 309) +* possible-completions (M-?): Commands For Completion. + (line 11) +* prefix-meta (): Miscellaneous Commands. + (line 19) +* previous-history (C-p): Commands For History. + (line 12) +* previous-screen-line (): Commands For Moving. (line 26) +* print-last-kbd-macro (): Keyboard Macros. (line 17) +* quoted-insert (C-q or C-v): Commands For Text. (line 26) +* re-read-init-file (C-x C-r): Miscellaneous Commands. + (line 6) +* readline: Basic Behavior. (line 12) +* redraw-current-line (): Commands For Moving. (line 49) +* reverse-search-history (C-r): Commands For History. + (line 26) +* revert-all-at-newline: Readline Init File Syntax. + (line 319) +* revert-line (M-r): Miscellaneous Commands. + (line 26) +* rl_activate_mark: Miscellaneous Functions. + (line 55) +* rl_add_defun: Function Naming. (line 18) +* rl_add_funmap_entry: Associating Function Names and Bindings. + (line 62) +* rl_add_undo: Allowing Undoing. (line 39) +* rl_alphabetic: Utility Functions. (line 38) +* rl_already_prompted: Readline Variables. (line 70) +* rl_attempted_completion_function: Completion Variables. + (line 11) +* rl_attempted_completion_over: Completion Variables. + (line 256) +* rl_basic_quote_characters: Completion Variables. + (line 143) +* rl_basic_word_break_characters: Completion Variables. + (line 137) +* rl_begin_undo_group: Allowing Undoing. (line 28) +* rl_binding_keymap: Readline Variables. (line 195) +* rl_bind_key: Binding Keys. (line 21) +* rl_bind_keyseq: Binding Keys. (line 57) +* rl_bind_keyseq_if_unbound: Binding Keys. (line 75) +* rl_bind_keyseq_if_unbound_in_map: Binding Keys. (line 81) +* rl_bind_keyseq_in_map: Binding Keys. (line 64) +* rl_bind_key_if_unbound: Binding Keys. (line 30) +* rl_bind_key_if_unbound_in_map: Binding Keys. (line 36) +* rl_bind_key_in_map: Binding Keys. (line 25) +* rl_callback_handler_install: Alternate Interface. (line 13) +* rl_callback_handler_remove: Alternate Interface. (line 42) +* rl_callback_read_char: Alternate Interface. (line 22) +* rl_callback_sigcleanup: Alternate Interface. (line 35) +* rl_catch_signals: Readline Signal Handling. + (line 69) +* rl_catch_sigwinch: Readline Signal Handling. + (line 76) +* rl_change_environment: Readline Signal Handling. + (line 90) +* rl_char_is_quoted_p: Completion Variables. + (line 45) +* rl_check_signals: Readline Signal Handling. + (line 133) +* rl_cleanup_after_signal: Readline Signal Handling. + (line 107) +* rl_clear_history: Miscellaneous Functions. + (line 49) +* rl_clear_message: Redisplay. (line 51) +* rl_clear_pending_input: Character Input. (line 29) +* rl_clear_signals: Readline Signal Handling. + (line 182) +* rl_clear_visible_line: Redisplay. (line 25) +* rl_complete: How Completing Works. + (line 46) +* rl_complete <1>: Completion Functions. + (line 19) +* rl_completer_quote_characters: Completion Variables. + (line 160) +* rl_completer_word_break_characters: Completion Variables. + (line 146) +* rl_complete_internal: Completion Functions. + (line 9) +* rl_completion_append_character: Completion Variables. + (line 185) +* rl_completion_display_matches_hook: Completion Variables. + (line 124) +* rl_completion_entry_function: How Completing Works. + (line 52) +* rl_completion_entry_function <1>: Completion Variables. + (line 6) +* rl_completion_found_quote: Completion Variables. + (line 215) +* rl_completion_invoking_key: Completion Variables. + (line 279) +* rl_completion_mark_symlink_dirs: Completion Variables. + (line 221) +* rl_completion_matches: Completion Functions. + (line 43) +* rl_completion_mode: Completion Functions. + (line 36) +* rl_completion_query_items: Completion Variables. + (line 178) +* rl_completion_quote_character: Completion Variables. + (line 203) +* rl_completion_suppress_append: Completion Variables. + (line 197) +* rl_completion_suppress_quote: Completion Variables. + (line 209) +* rl_completion_type: Completion Variables. + (line 271) +* rl_completion_word_break_hook: Completion Variables. + (line 151) +* rl_copy_keymap: Keymaps. (line 16) +* rl_copy_text: Modifying Text. (line 14) +* rl_crlf: Redisplay. (line 33) +* rl_deactivate_mark: Miscellaneous Functions. + (line 62) +* rl_delete_text: Modifying Text. (line 10) +* rl_deprep_terminal: Terminal Management. (line 12) +* rl_deprep_term_function: Readline Variables. (line 185) +* rl_ding: Utility Functions. (line 35) +* rl_directory_completion_hook: Completion Variables. + (line 63) +* rl_directory_rewrite_hook;: Completion Variables. + (line 81) +* rl_discard_keymap: Keymaps. (line 25) +* rl_dispatching: Readline Variables. (line 47) +* rl_display_match_list: Utility Functions. (line 41) +* rl_display_prompt: Readline Variables. (line 65) +* rl_done: Readline Variables. (line 27) +* rl_do_undo: Allowing Undoing. (line 47) +* rl_echo_signal_char: Readline Signal Handling. + (line 143) +* rl_editing_mode: Readline Variables. (line 301) +* rl_empty_keymap: Keymaps. (line 33) +* rl_end: Readline Variables. (line 18) +* rl_end_undo_group: Allowing Undoing. (line 34) +* rl_eof_found: Readline Variables. (line 33) +* rl_erase_empty_line: Readline Variables. (line 53) +* rl_event_hook: Readline Variables. (line 130) +* rl_execute_next: Character Input. (line 25) +* rl_executing_key: Readline Variables. (line 202) +* rl_executing_keymap: Readline Variables. (line 191) +* rl_executing_keyseq: Readline Variables. (line 206) +* rl_executing_macro: Readline Variables. (line 199) +* rl_expand_prompt: Redisplay. (line 66) +* rl_explicit_arg: Readline Variables. (line 292) +* rl_extend_line_buffer: Utility Functions. (line 26) +* rl_filename_completion_desired: Completion Variables. + (line 236) +* rl_filename_completion_function: Completion Functions. + (line 57) +* rl_filename_dequoting_function: Completion Variables. + (line 36) +* rl_filename_quote_characters: Completion Variables. + (line 166) +* rl_filename_quoting_desired: Completion Variables. + (line 246) +* rl_filename_quoting_function: Completion Variables. + (line 23) +* rl_filename_rewrite_hook: Completion Variables. + (line 109) +* rl_filename_stat_hook: Completion Variables. + (line 97) +* rl_forced_update_display: Redisplay. (line 10) +* rl_free: Utility Functions. (line 17) +* rl_free_keymap: Keymaps. (line 29) +* rl_free_line_state: Readline Signal Handling. + (line 113) +* rl_free_undo_list: Allowing Undoing. (line 44) +* rl_function_dumper: Associating Function Names and Bindings. + (line 46) +* rl_function_of_keyseq: Associating Function Names and Bindings. + (line 13) +* rl_function_of_keyseq_len: Associating Function Names and Bindings. + (line 22) +* rl_funmap_names: Associating Function Names and Bindings. + (line 56) +* rl_generic_bind: Binding Keys. (line 87) +* rl_getc: Character Input. (line 14) +* rl_getc_function: Readline Variables. (line 135) +* rl_get_keymap: Keymaps. (line 40) +* rl_get_keymap_by_name: Keymaps. (line 46) +* rl_get_keymap_name: Keymaps. (line 51) +* rl_get_screen_size: Readline Signal Handling. + (line 165) +* rl_get_termcap: Miscellaneous Functions. + (line 41) +* rl_gnu_readline_p: Readline Variables. (line 89) +* rl_ignore_completion_duplicates: Completion Variables. + (line 232) +* rl_ignore_some_completions_function: Completion Variables. + (line 55) +* rl_inhibit_completion: Completion Variables. + (line 285) +* rl_initialize: Utility Functions. (line 30) +* rl_input_available_hook: Readline Variables. (line 151) +* rl_insert_completions: Completion Functions. + (line 31) +* rl_insert_text: Modifying Text. (line 6) +* rl_instream: Readline Variables. (line 103) +* rl_invoking_keyseqs: Associating Function Names and Bindings. + (line 37) +* rl_invoking_keyseqs_in_map: Associating Function Names and Bindings. + (line 41) +* rl_keep_mark_active: Miscellaneous Functions. + (line 65) +* rl_key_sequence_length: Readline Variables. (line 210) +* rl_kill_text: Modifying Text. (line 18) +* rl_last_func: Readline Variables. (line 116) +* rl_library_version: Readline Variables. (line 79) +* rl_line_buffer: Readline Variables. (line 8) +* rl_list_funmap_names: Associating Function Names and Bindings. + (line 52) +* rl_macro_bind: Miscellaneous Functions. + (line 6) +* rl_macro_dumper: Miscellaneous Functions. + (line 13) +* rl_make_bare_keymap: Keymaps. (line 11) +* rl_make_keymap: Keymaps. (line 19) +* rl_mark: Readline Variables. (line 23) +* rl_mark_active_p: Miscellaneous Functions. + (line 71) +* rl_message: Redisplay. (line 42) +* rl_modifying: Allowing Undoing. (line 56) +* rl_named_function: Associating Function Names and Bindings. + (line 10) +* rl_numeric_arg: Readline Variables. (line 296) +* rl_num_chars_to_read: Readline Variables. (line 38) +* rl_on_new_line: Redisplay. (line 14) +* rl_on_new_line_with_prompt: Redisplay. (line 18) +* rl_outstream: Readline Variables. (line 107) +* rl_parse_and_bind: Binding Keys. (line 95) +* rl_pending_input: Readline Variables. (line 43) +* rl_pending_signal: Readline Signal Handling. + (line 102) +* rl_persistent_signal_handlers: Readline Signal Handling. + (line 82) +* rl_point: Readline Variables. (line 14) +* rl_possible_completions: Completion Functions. + (line 27) +* rl_prefer_env_winsize: Readline Variables. (line 111) +* rl_prep_terminal: Terminal Management. (line 6) +* rl_prep_term_function: Readline Variables. (line 178) +* rl_pre_input_hook: Readline Variables. (line 125) +* rl_prompt: Readline Variables. (line 59) +* rl_push_macro_input: Modifying Text. (line 25) +* rl_readline_name: Readline Variables. (line 98) +* rl_readline_state: Readline Variables. (line 213) +* rl_readline_version: Readline Variables. (line 82) +* rl_read_init_file: Binding Keys. (line 100) +* rl_read_key: Character Input. (line 6) +* rl_redisplay: Redisplay. (line 6) +* rl_redisplay_function: Readline Variables. (line 172) +* rl_replace_line: Utility Functions. (line 21) +* rl_reset_after_signal: Readline Signal Handling. + (line 121) +* rl_reset_line_state: Redisplay. (line 29) +* rl_reset_screen_size: Readline Signal Handling. + (line 169) +* rl_reset_terminal: Terminal Management. (line 34) +* rl_resize_terminal: Readline Signal Handling. + (line 149) +* rl_restore_prompt: Redisplay. (line 60) +* rl_restore_state: Utility Functions. (line 11) +* rl_save_prompt: Redisplay. (line 56) +* rl_save_state: Utility Functions. (line 6) +* rl_set_key: Binding Keys. (line 71) +* rl_set_keyboard_input_timeout: Character Input. (line 34) +* rl_set_keymap: Keymaps. (line 43) +* rl_set_keymap_name: Keymaps. (line 56) +* rl_set_paren_blink_timeout: Miscellaneous Functions. + (line 36) +* rl_set_prompt: Redisplay. (line 80) +* rl_set_screen_size: Readline Signal Handling. + (line 153) +* rl_set_signals: Readline Signal Handling. + (line 176) +* rl_set_timeout: Character Input. (line 42) +* rl_show_char: Redisplay. (line 36) +* rl_signal_event_hook: Readline Variables. (line 143) +* rl_sort_completion_matches: Completion Variables. + (line 263) +* rl_special_prefixes: Completion Variables. + (line 171) +* rl_startup_hook: Readline Variables. (line 121) +* rl_stuff_char: Character Input. (line 18) +* rl_terminal_name: Readline Variables. (line 93) +* rl_timeout_event_hook: Readline Variables. (line 147) +* rl_timeout_remaining: Character Input. (line 52) +* rl_trim_arg_from_keyseq: Associating Function Names and Bindings. + (line 29) +* rl_tty_set_default_bindings: Terminal Management. (line 17) +* rl_tty_set_echoing: Terminal Management. (line 27) +* rl_tty_unset_default_bindings: Terminal Management. (line 22) +* rl_unbind_command_in_map: Binding Keys. (line 53) +* rl_unbind_function_in_map: Binding Keys. (line 49) +* rl_unbind_key: Binding Keys. (line 41) +* rl_unbind_key_in_map: Binding Keys. (line 45) +* rl_username_completion_function: Completion Functions. + (line 64) +* rl_variable_bind: Miscellaneous Functions. + (line 19) +* rl_variable_dumper: Miscellaneous Functions. + (line 30) +* rl_variable_value: Miscellaneous Functions. + (line 25) +* self-insert (a, b, A, 1, !, ...): Commands For Text. (line 33) +* set-mark (C-@): Miscellaneous Commands. + (line 33) +* shell-transpose-words (M-C-t): Commands For Killing. + (line 32) +* show-all-if-ambiguous: Readline Init File Syntax. + (line 326) +* show-all-if-unmodified: Readline Init File Syntax. + (line 332) +* show-mode-in-prompt: Readline Init File Syntax. + (line 341) +* skip-completed-text: Readline Init File Syntax. + (line 347) +* skip-csi-sequence (): Miscellaneous Commands. + (line 52) +* start-kbd-macro (C-x (): Keyboard Macros. (line 6) +* tab-insert (M-): Commands For Text. (line 30) +* tilde-expand (M-~): Miscellaneous Commands. + (line 30) +* transpose-chars (C-t): Commands For Text. (line 50) +* transpose-words (M-t): Commands For Text. (line 56) +* undo (C-_ or C-x C-u): Miscellaneous Commands. + (line 23) +* universal-argument (): Numeric Arguments. (line 10) +* unix-filename-rubout (): Commands For Killing. + (line 43) +* unix-line-discard (C-u): Commands For Killing. + (line 16) +* unix-word-rubout (C-w): Commands For Killing. + (line 39) +* upcase-word (M-u): Commands For Text. (line 61) +* vi-cmd-mode-string: Readline Init File Syntax. + (line 360) +* vi-editing-mode (M-C-j): Miscellaneous Commands. + (line 92) +* vi-ins-mode-string: Readline Init File Syntax. + (line 371) +* visible-stats: Readline Init File Syntax. + (line 382) +* yank (C-y): Commands For Killing. + (line 70) +* yank-last-arg (M-. or M-_): Commands For History. + (line 83) +* yank-nth-arg (M-C-y): Commands For History. + (line 74) +* yank-pop (M-y): Commands For Killing. + (line 73) + + + +Tag Table: +Node: Top866 +Node: Command Line Editing1591 +Node: Introduction and Notation2243 +Node: Readline Interaction3867 +Node: Readline Bare Essentials5059 +Node: Readline Movement Commands6849 +Node: Readline Killing Commands7810 +Node: Readline Arguments9732 +Node: Searching10777 +Node: Readline Init File12930 +Node: Readline Init File Syntax14086 +Node: Conditional Init Constructs37389 +Node: Sample Init File41586 +Node: Bindable Readline Commands44711 +Node: Commands For Moving45766 +Node: Commands For History47525 +Node: Commands For Text52489 +Node: Commands For Killing56192 +Node: Numeric Arguments58906 +Node: Commands For Completion60046 +Node: Keyboard Macros62015 +Node: Miscellaneous Commands62704 +Node: Readline vi Mode66632 +Node: Programming with GNU Readline68449 +Node: Basic Behavior69435 +Node: Custom Functions73118 +Node: Readline Typedefs74601 +Node: Function Writing76235 +Node: Readline Variables77549 +Node: Readline Convenience Functions91224 +Node: Function Naming92296 +Node: Keymaps93558 +Node: Binding Keys96637 +Node: Associating Function Names and Bindings101185 +Node: Allowing Undoing104415 +Node: Redisplay106965 +Node: Modifying Text111024 +Node: Character Input112271 +Node: Terminal Management115352 +Node: Utility Functions117175 +Node: Miscellaneous Functions120503 +Node: Alternate Interface123922 +Node: A Readline Example126664 +Node: Alternate Interface Example128603 +Node: Readline Signal Handling132135 +Node: Custom Completers141388 +Node: How Completing Works142108 +Node: Completion Functions145415 +Node: Completion Variables148989 +Node: A Short Completion Example164795 +Node: GNU Free Documentation License177632 +Node: Concept Index202806 +Node: Function and Variable Index204327 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/readline/readline/doc/rlman.texi 16.3-5ubuntu1/readline/readline/doc/rlman.texi --- 16.3-5/readline/readline/doc/rlman.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/rlman.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,84 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename readline.info +@settitle GNU Readline Library +@include version.texi +@comment %**end of header (This is for running Texinfo on a region.) +@synindex vr fn + +@copying +This manual describes the GNU Readline Library +(version @value{VERSION}, @value{UPDATED}), a library which aids in the +consistency of user interface across discrete programs which provide +a command line interface. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* Readline: (readline). The GNU readline library API. +@end direntry + +@titlepage +@title GNU Readline Library +@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Readline Library + +This document describes the GNU Readline Library, a utility which aids +in the consistency of user interface across discrete programs which +provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. + +@menu +* Command Line Editing:: GNU Readline User's Manual. +* Programming with GNU Readline:: GNU Readline Programmer's Manual. +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of concepts described in this manual. +* Function and Variable Index:: Index of externally visible functions + and variables. +@end menu +@end ifnottex + +@include rluser.texi +@include rltech.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@node Concept Index +@unnumbered Concept Index +@printindex cp + +@node Function and Variable Index +@unnumbered Function and Variable Index +@printindex fn + +@bye diff -pruN 16.3-5/readline/readline/doc/rltech.texi 16.3-5ubuntu1/readline/readline/doc/rltech.texi --- 16.3-5/readline/readline/doc/rltech.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/rltech.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,2815 @@ +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rltech.info +@comment %**end of header (This is for running Texinfo on a region.) +@ifinfo +This document describes the GNU Readline Library, a utility for aiding +in the consistency of user interface across discrete programs that need +to provide a command line interface. + +Copyright (C) 1988--2022 Free Software Foundation, Inc. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +pare preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). +@end ignore + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Foundation. +@end ifinfo + +@node Programming with GNU Readline +@chapter Programming with GNU Readline + +This chapter describes the interface between the @sc{gnu} Readline Library and +other programs. If you are a programmer, and you wish to include the +features found in @sc{gnu} Readline +such as completion, line editing, and interactive history manipulation +in your own programs, this section is for you. + +@menu +* Basic Behavior:: Using the default behavior of Readline. +* Custom Functions:: Adding your own functions to Readline. +* Readline Variables:: Variables accessible to custom + functions. +* Readline Convenience Functions:: Functions which Readline supplies to + aid in writing your own custom + functions. +* Readline Signal Handling:: How Readline behaves when it receives signals. +* Custom Completers:: Supplanting or supplementing Readline's + completion functions. +@end menu + +@node Basic Behavior +@section Basic Behavior + +Many programs provide a command line interface, such as @code{mail}, +@code{ftp}, and @code{sh}. For such programs, the default behaviour of +Readline is sufficient. This section describes how to use Readline in +the simplest way possible, perhaps to replace calls in your code to +@code{gets()} or @code{fgets()}. + +@findex readline +@cindex readline, function + +The function @code{readline()} prints a prompt @var{prompt} +and then reads and returns a single line of text from the user. +If @var{prompt} is @code{NULL} or the empty string, no prompt is displayed. +The line @code{readline} returns is allocated with @code{malloc()}; +the caller should @code{free()} the line when it has finished with it. +The declaration for @code{readline} in ANSI C is + +@example +@code{char *readline (const char *@var{prompt});} +@end example + +@noindent +So, one might say +@example +@code{char *line = readline ("Enter a line: ");} +@end example +@noindent +in order to read a line of text from the user. +The line returned has the final newline removed, so only the +text remains. + +If @code{readline} encounters an @code{EOF} while reading the line, and the +line is empty at that point, then @code{(char *)NULL} is returned. +Otherwise, the line is ended just as if a newline had been typed. + +Readline performs some expansion on the @var{prompt} before it is +displayed on the screen. See the description of @code{rl_expand_prompt} +(@pxref{Redisplay}) for additional details, especially if @var{prompt} +will contain characters that do not consume physical screen space when +displayed. + +If you want the user to be able to get at the line later, (with +@key{C-p} for example), you must call @code{add_history()} to save the +line away in a @dfn{history} list of such lines. + +@example +@code{add_history (line)}; +@end example + +@noindent +For full details on the GNU History Library, see the associated manual. + +It is preferable to avoid saving empty lines on the history list, since +users rarely have a burning need to reuse a blank line. Here is +a function which usefully replaces the standard @code{gets()} library +function, and has the advantage of no static buffer to overflow: + +@example +/* A static variable for holding the line. */ +static char *line_read = (char *)NULL; + +/* Read a string, and return a pointer to it. + Returns NULL on EOF. */ +char * +rl_gets () +@{ + /* If the buffer has already been allocated, + return the memory to the free pool. */ + if (line_read) + @{ + free (line_read); + line_read = (char *)NULL; + @} + + /* Get a line from the user. */ + line_read = readline (""); + + /* If the line has any text in it, + save it on the history. */ + if (line_read && *line_read) + add_history (line_read); + + return (line_read); +@} +@end example + +This function gives the user the default behaviour of @key{TAB} +completion: completion on file names. If you do not want Readline to +complete on filenames, you can change the binding of the @key{TAB} key +with @code{rl_bind_key()}. + +@example +@code{int rl_bind_key (int @var{key}, rl_command_func_t *@var{function});} +@end example + +@code{rl_bind_key()} takes two arguments: @var{key} is the character that +you want to bind, and @var{function} is the address of the function to +call when @var{key} is pressed. Binding @key{TAB} to @code{rl_insert()} +makes @key{TAB} insert itself. +@code{rl_bind_key()} returns non-zero if @var{key} is not a valid +ASCII character code (between 0 and 255). + +Thus, to disable the default @key{TAB} behavior, the following suffices: +@example +@code{rl_bind_key ('\t', rl_insert);} +@end example + +This code should be executed once at the start of your program; you +might write a function called @code{initialize_readline()} which +performs this and other desired initializations, such as installing +custom completers (@pxref{Custom Completers}). + +@node Custom Functions +@section Custom Functions + +Readline provides many functions for manipulating the text of +the line, but it isn't possible to anticipate the needs of all +programs. This section describes the various functions and variables +defined within the Readline library which allow a user program to add +customized functionality to Readline. + +Before declaring any functions that customize Readline's behavior, or +using any functionality Readline provides in other code, an +application writer should include the file @code{} +in any file that uses Readline's features. Since some of the definitions +in @code{readline.h} use the @code{stdio} library, the file +@code{} should be included before @code{readline.h}. + +@code{readline.h} defines a C preprocessor variable that should +be treated as an integer, @code{RL_READLINE_VERSION}, which may +be used to conditionally compile application code depending on +the installed Readline version. The value is a hexadecimal +encoding of the major and minor version numbers of the library, +of the form 0x@var{MMmm}. @var{MM} is the two-digit major +version number; @var{mm} is the two-digit minor version number. +For Readline 4.2, for example, the value of +@code{RL_READLINE_VERSION} would be @code{0x0402}. + +@menu +* Readline Typedefs:: C declarations to make code readable. +* Function Writing:: Variables and calling conventions. +@end menu + +@node Readline Typedefs +@subsection Readline Typedefs + +For readability, we declare a number of new object types, all pointers +to functions. + +The reason for declaring these new types is to make it easier to write +code describing pointers to C functions with appropriately prototyped +arguments and return values. + +For instance, say we want to declare a variable @var{func} as a pointer +to a function which takes two @code{int} arguments and returns an +@code{int} (this is the type of all of the Readline bindable functions). +Instead of the classic C declaration + +@code{int (*func)();} + +@noindent +or the ANSI-C style declaration + +@code{int (*func)(int, int);} + +@noindent +we may write + +@code{rl_command_func_t *func;} + +The full list of function pointer types available is + +@table @code +@item typedef int rl_command_func_t (int, int); + +@item typedef char *rl_compentry_func_t (const char *, int); + +@item typedef char **rl_completion_func_t (const char *, int, int); + +@item typedef char *rl_quote_func_t (char *, int, char *); + +@item typedef char *rl_dequote_func_t (char *, int); + +@item typedef int rl_compignore_func_t (char **); + +@item typedef void rl_compdisp_func_t (char **, int, int); + +@item typedef int rl_hook_func_t (void); + +@item typedef int rl_getc_func_t (FILE *); + +@item typedef int rl_linebuf_func_t (char *, int); + +@item typedef int rl_intfunc_t (int); +@item #define rl_ivoidfunc_t rl_hook_func_t +@item typedef int rl_icpfunc_t (char *); +@item typedef int rl_icppfunc_t (char **); + +@item typedef void rl_voidfunc_t (void); +@item typedef void rl_vintfunc_t (int); +@item typedef void rl_vcpfunc_t (char *); +@item typedef void rl_vcppfunc_t (char **); + +@end table + +@node Function Writing +@subsection Writing a New Function + +In order to write new functions for Readline, you need to know the +calling conventions for keyboard-invoked functions, and the names of the +variables that describe the current state of the line read so far. + +The calling sequence for a command @code{foo} looks like + +@example +@code{int foo (int count, int key)} +@end example + +@noindent +where @var{count} is the numeric argument (or 1 if defaulted) and +@var{key} is the key that invoked this function. + +It is completely up to the function as to what should be done with the +numeric argument. Some functions use it as a repeat count, some +as a flag, and others to choose alternate behavior (refreshing the current +line as opposed to refreshing the screen, for example). Some choose to +ignore it. In general, if a +function uses the numeric argument as a repeat count, it should be able +to do something useful with both negative and positive arguments. +At the very least, it should be aware that it can be passed a +negative argument. + +A command function should return 0 if its action completes successfully, +and a value greater than zero if some error occurs. +This is the convention obeyed by all of the builtin Readline bindable +command functions. + +@node Readline Variables +@section Readline Variables + +These variables are available to function writers. + +@deftypevar {char *} rl_line_buffer +This is the line gathered so far. You are welcome to modify the +contents of the line, but see @ref{Allowing Undoing}. The +function @code{rl_extend_line_buffer} is available to increase +the memory allocated to @code{rl_line_buffer}. +@end deftypevar + +@deftypevar int rl_point +The offset of the current cursor position in @code{rl_line_buffer} +(the @emph{point}). +@end deftypevar + +@deftypevar int rl_end +The number of characters present in @code{rl_line_buffer}. When +@code{rl_point} is at the end of the line, @code{rl_point} and +@code{rl_end} are equal. +@end deftypevar + +@deftypevar int rl_mark +The @var{mark} (saved position) in the current line. If set, the mark +and point define a @emph{region}. +@end deftypevar + +@deftypevar int rl_done +Setting this to a non-zero value causes Readline to return the current +line immediately. +Readline will set this variable when it has read a key sequence bound +to @code{accept-line} and is about to return the line to the caller. +@end deftypevar + +@deftypevar int rl_eof_found +Readline will set this variable when it has read an EOF character (e.g., the +stty @samp{EOF} character) on an empty line or encountered a read error and +is about to return a NULL line to the caller. +@end deftypevar + +@deftypevar int rl_num_chars_to_read +Setting this to a positive value before calling @code{readline()} causes +Readline to return after accepting that many characters, rather +than reading up to a character bound to @code{accept-line}. +@end deftypevar + +@deftypevar int rl_pending_input +Setting this to a value makes it the next keystroke read. This is a +way to stuff a single character into the input stream. +@end deftypevar + +@deftypevar int rl_dispatching +Set to a non-zero value if a function is being called from a key binding; +zero otherwise. Application functions can test this to discover whether +they were called directly or by Readline's dispatching mechanism. +@end deftypevar + +@deftypevar int rl_erase_empty_line +Setting this to a non-zero value causes Readline to completely erase +the current line, including any prompt, any time a newline is typed as +the only character on an otherwise-empty line. The cursor is moved to +the beginning of the newly-blank line. +@end deftypevar + +@deftypevar {char *} rl_prompt +The prompt Readline uses. This is set from the argument to +@code{readline()}, and should not be assigned to directly. +The @code{rl_set_prompt()} function (@pxref{Redisplay}) may +be used to modify the prompt string after calling @code{readline()}. +@end deftypevar + +@deftypevar {char *} rl_display_prompt +The string displayed as the prompt. This is usually identical to +@var{rl_prompt}, but may be changed temporarily by functions that +use the prompt string as a message area, such as incremental search. +@end deftypevar + +@deftypevar int rl_already_prompted +If an application wishes to display the prompt itself, rather than have +Readline do it the first time @code{readline()} is called, it should set +this variable to a non-zero value after displaying the prompt. +The prompt must also be passed as the argument to @code{readline()} so +the redisplay functions can update the display properly. +The calling application is responsible for managing the value; Readline +never sets it. +@end deftypevar + +@deftypevar {const char *} rl_library_version +The version number of this revision of the library. +@end deftypevar + +@deftypevar int rl_readline_version +An integer encoding the current version of the library. The encoding is +of the form 0x@var{MMmm}, where @var{MM} is the two-digit major version +number, and @var{mm} is the two-digit minor version number. +For example, for Readline-4.2, @code{rl_readline_version} would have the +value 0x0402. +@end deftypevar + +@deftypevar {int} rl_gnu_readline_p +Always set to 1, denoting that this is @sc{gnu} Readline rather than some +emulation. +@end deftypevar + +@deftypevar {const char *} rl_terminal_name +The terminal type, used for initialization. If not set by the application, +Readline sets this to the value of the @env{TERM} environment variable +the first time it is called. +@end deftypevar + +@deftypevar {const char *} rl_readline_name +This variable is set to a unique name by each application using Readline. +The value allows conditional parsing of the inputrc file +(@pxref{Conditional Init Constructs}). +@end deftypevar + +@deftypevar {FILE *} rl_instream +The stdio stream from which Readline reads input. +If @code{NULL}, Readline defaults to @var{stdin}. +@end deftypevar + +@deftypevar {FILE *} rl_outstream +The stdio stream to which Readline performs output. +If @code{NULL}, Readline defaults to @var{stdout}. +@end deftypevar + +@deftypevar int rl_prefer_env_winsize +If non-zero, Readline gives values found in the @env{LINES} and +@env{COLUMNS} environment variables greater precedence than values fetched +from the kernel when computing the screen dimensions. +@end deftypevar + +@deftypevar {rl_command_func_t *} rl_last_func +The address of the last command function Readline executed. May be used to +test whether or not a function is being executed twice in succession, for +example. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_startup_hook +If non-zero, this is the address of a function to call just +before @code{readline} prints the first prompt. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_pre_input_hook +If non-zero, this is the address of a function to call after +the first prompt has been printed and just before @code{readline} +starts reading input characters. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_event_hook +If non-zero, this is the address of a function to call periodically +when Readline is waiting for terminal input. +By default, this will be called at most ten times a second if there +is no keyboard input. +@end deftypevar + +@deftypevar {rl_getc_func_t *} rl_getc_function +If non-zero, Readline will call indirectly through this pointer +to get a character from the input stream. By default, it is set to +@code{rl_getc}, the default Readline character input function +(@pxref{Character Input}). +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_signal_event_hook +If non-zero, this is the address of a function to call if a read system +call is interrupted when Readline is reading terminal input. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_timeout_event_hook +If non-zero, this is the address of a function to call if Readline times +out while reading input. +@end deftypevar + +@deftypevar {rl_hook_func_t *} rl_input_available_hook +If non-zero, Readline will use this function's return value when it needs +to determine whether or not there is available input on the current input +source. +The default hook checks @code{rl_instream}; if an application is using a +different input source, it should set the hook appropriately. +Readline queries for available input when implementing intra-key-sequence +timeouts during input and incremental searches. +This may use an application-specific timeout before returning a value; +Readline uses the value passed to @code{rl_set_keyboard_input_timeout()} +or the value of the user-settable @var{keyseq-timeout} variable. +This is designed for use by applications using Readline's callback interface +(@pxref{Alternate Interface}), which may not use the traditional +@code{read(2)} and file descriptor interface, or other applications using +a different input mechanism. +If an application uses an input mechanism or hook that can potentially exceed +the value of @var{keyseq-timeout}, it should increase the timeout or set +this hook appropriately even when not using the callback interface. +In general, an application that sets @var{rl_getc_function} should consider +setting @var{rl_input_available_hook} as well. +@end deftypevar + +@deftypevar {rl_voidfunc_t *} rl_redisplay_function +If non-zero, Readline will call indirectly through this pointer +to update the display with the current contents of the editing buffer. +By default, it is set to @code{rl_redisplay}, the default Readline +redisplay function (@pxref{Redisplay}). +@end deftypevar + +@deftypevar {rl_vintfunc_t *} rl_prep_term_function +If non-zero, Readline will call indirectly through this pointer +to initialize the terminal. The function takes a single argument, an +@code{int} flag that says whether or not to use eight-bit characters. +By default, this is set to @code{rl_prep_terminal} +(@pxref{Terminal Management}). +@end deftypevar + +@deftypevar {rl_voidfunc_t *} rl_deprep_term_function +If non-zero, Readline will call indirectly through this pointer +to reset the terminal. This function should undo the effects of +@code{rl_prep_term_function}. +By default, this is set to @code{rl_deprep_terminal} +(@pxref{Terminal Management}). +@end deftypevar + +@deftypevar {Keymap} rl_executing_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +currently executing Readline function was found. +@end deftypevar + +@deftypevar {Keymap} rl_binding_keymap +This variable is set to the keymap (@pxref{Keymaps}) in which the +last key binding occurred. +@end deftypevar + +@deftypevar {char *} rl_executing_macro +This variable is set to the text of any currently-executing macro. +@end deftypevar + +@deftypevar int rl_executing_key +The key that caused the dispatch to the currently-executing Readline function. +@end deftypevar + +@deftypevar {char *} rl_executing_keyseq +The full key sequence that caused the dispatch to the currently-executing +Readline function. +@end deftypevar + +@deftypevar int rl_key_sequence_length +The number of characters in @var{rl_executing_keyseq}. +@end deftypevar + +@deftypevar {int} rl_readline_state +A variable with bit values that encapsulate the current Readline state. +A bit is set with the @code{RL_SETSTATE} macro, and unset with the +@code{RL_UNSETSTATE} macro. Use the @code{RL_ISSTATE} macro to test +whether a particular state bit is set. Current state bits include: + +@table @code +@item RL_STATE_NONE +Readline has not yet been called, nor has it begun to initialize. +@item RL_STATE_INITIALIZING +Readline is initializing its internal data structures. +@item RL_STATE_INITIALIZED +Readline has completed its initialization. +@item RL_STATE_TERMPREPPED +Readline has modified the terminal modes to do its own input and redisplay. +@item RL_STATE_READCMD +Readline is reading a command from the keyboard. +@item RL_STATE_METANEXT +Readline is reading more input after reading the meta-prefix character. +@item RL_STATE_DISPATCHING +Readline is dispatching to a command. +@item RL_STATE_MOREINPUT +Readline is reading more input while executing an editing command. +@item RL_STATE_ISEARCH +Readline is performing an incremental history search. +@item RL_STATE_NSEARCH +Readline is performing a non-incremental history search. +@item RL_STATE_SEARCH +Readline is searching backward or forward through the history for a string. +@item RL_STATE_NUMERICARG +Readline is reading a numeric argument. +@item RL_STATE_MACROINPUT +Readline is currently getting its input from a previously-defined keyboard +macro. +@item RL_STATE_MACRODEF +Readline is currently reading characters defining a keyboard macro. +@item RL_STATE_OVERWRITE +Readline is in overwrite mode. +@item RL_STATE_COMPLETING +Readline is performing word completion. +@item RL_STATE_SIGHANDLER +Readline is currently executing the readline signal handler. +@item RL_STATE_UNDOING +Readline is performing an undo. +@item RL_STATE_INPUTPENDING +Readline has input pending due to a call to @code{rl_execute_next()}. +@item RL_STATE_TTYCSAVED +Readline has saved the values of the terminal's special characters. +@item RL_STATE_CALLBACK +Readline is currently using the alternate (callback) interface +(@pxref{Alternate Interface}). +@item RL_STATE_VIMOTION +Readline is reading the argument to a vi-mode "motion" command. +@item RL_STATE_MULTIKEY +Readline is reading a multiple-keystroke command. +@item RL_STATE_VICMDONCE +Readline has entered vi command (movement) mode at least one time during +the current call to @code{readline()}. +@item RL_STATE_DONE +Readline has read a key sequence bound to @code{accept-line} +and is about to return the line to the caller. +@item RL_STATE_TIMEOUT +Readline has timed out (it did not receive a line or specified number of +characters before the timeout duration specified by @code{rl_set_timeout} +elapsed) and is returning that status to the caller. +@item RL_STATE_EOF +Readline has read an EOF character (e.g., the stty @samp{EOF} character) +or encountered a read error and is about to return a NULL line to the caller. +@end table + +@end deftypevar + +@deftypevar {int} rl_explicit_arg +Set to a non-zero value if an explicit numeric argument was specified by +the user. Only valid in a bindable command function. +@end deftypevar + +@deftypevar {int} rl_numeric_arg +Set to the value of any numeric argument explicitly specified by the user +before executing the current Readline function. Only valid in a bindable +command function. +@end deftypevar + +@deftypevar {int} rl_editing_mode +Set to a value denoting Readline's current editing mode. A value of +@var{1} means Readline is currently in emacs mode; @var{0} +means that vi mode is active. +@end deftypevar + + +@node Readline Convenience Functions +@section Readline Convenience Functions + +@menu +* Function Naming:: How to give a function you write a name. +* Keymaps:: Making keymaps. +* Binding Keys:: Changing Keymaps. +* Associating Function Names and Bindings:: Translate function names to + key sequences. +* Allowing Undoing:: How to make your functions undoable. +* Redisplay:: Functions to control line display. +* Modifying Text:: Functions to modify @code{rl_line_buffer}. +* Character Input:: Functions to read keyboard input. +* Terminal Management:: Functions to manage terminal settings. +* Utility Functions:: Generally useful functions and hooks. +* Miscellaneous Functions:: Functions that don't fall into any category. +* Alternate Interface:: Using Readline in a `callback' fashion. +* A Readline Example:: An example Readline function. +* Alternate Interface Example:: An example program using the alternate interface. +@end menu + +@node Function Naming +@subsection Naming a Function + +The user can dynamically change the bindings of keys while using +Readline. This is done by representing the function with a descriptive +name. The user is able to type the descriptive name when referring to +the function. Thus, in an init file, one might find + +@example +Meta-Rubout: backward-kill-word +@end example + +This binds the keystroke @key{Meta-Rubout} to the function +@emph{descriptively} named @code{backward-kill-word}. You, as the +programmer, should bind the functions you write to descriptive names as +well. Readline provides a function for doing that: + +@deftypefun int rl_add_defun (const char *name, rl_command_func_t *function, int key) +Add @var{name} to the list of named functions. Make @var{function} be +the function that gets called. If @var{key} is not -1, then bind it to +@var{function} using @code{rl_bind_key()}. +@end deftypefun + +Using this function alone is sufficient for most applications. +It is the recommended way to add a few functions to the default +functions that Readline has built in. +If you need to do something other than adding a function to Readline, +you may need to use the underlying functions described below. + +@node Keymaps +@subsection Selecting a Keymap + +Key bindings take place on a @dfn{keymap}. The keymap is the +association between the keys that the user types and the functions that +get run. You can make your own keymaps, copy existing keymaps, and tell +Readline which keymap to use. + +@deftypefun Keymap rl_make_bare_keymap (void) +Returns a new, empty keymap. The space for the keymap is allocated with +@code{malloc()}; the caller should free it by calling +@code{rl_free_keymap()} when done. +@end deftypefun + +@deftypefun Keymap rl_copy_keymap (Keymap map) +Return a new keymap which is a copy of @var{map}. +@end deftypefun + +@deftypefun Keymap rl_make_keymap (void) +Return a new keymap with the printing characters bound to rl_insert, +the lowercase Meta characters bound to run their equivalents, and +the Meta digits bound to produce numeric arguments. +@end deftypefun + +@deftypefun void rl_discard_keymap (Keymap keymap) +Free the storage associated with the data in @var{keymap}. +The caller should free @var{keymap}. +@end deftypefun + +@deftypefun void rl_free_keymap (Keymap keymap) +Free all storage associated with @var{keymap}. This calls +@code{rl_discard_keymap} to free subordindate keymaps and macros. +@end deftypefun + +@deftypefun int rl_empty_keymap (Keymap keymap) +Return non-zero if there are no keys bound to functions in @var{keymap}; +zero if there are any keys bound. +@end deftypefun + +Readline has several internal keymaps. These functions allow you to +change which keymap is active. + +@deftypefun Keymap rl_get_keymap (void) +Returns the currently active keymap. +@end deftypefun + +@deftypefun void rl_set_keymap (Keymap keymap) +Makes @var{keymap} the currently active keymap. +@end deftypefun + +@deftypefun Keymap rl_get_keymap_by_name (const char *name) +Return the keymap matching @var{name}. @var{name} is one which would +be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). +@end deftypefun + +@deftypefun {char *} rl_get_keymap_name (Keymap keymap) +Return the name matching @var{keymap}. @var{name} is one which would +be supplied in a @code{set keymap} inputrc line (@pxref{Readline Init File}). +@end deftypefun + +@deftypefun int rl_set_keymap_name (const char *name, Keymap keymap) +Set the name of @var{keymap}. This name will then be "registered" and +available for use in a @code{set keymap} inputrc directive +@pxref{Readline Init File}). +The @var{name} may not be one of Readline's builtin keymap names; +you may not add a different name for one of Readline's builtin keymaps. +You may replace the name associated with a given keymap by calling this +function more than once with the same @var{keymap} argument. +You may associate a registered @var{name} with a new keymap by calling this +function more than once with the same @var{name} argument. +There is no way to remove a named keymap once the name has been +registered. +Readline will make a copy of @var{name}. +The return value is greater than zero unless @var{name} is one of +Readline's builtin keymap names or @var{keymap} is one of Readline's +builtin keymaps. +@end deftypefun + +@node Binding Keys +@subsection Binding Keys + +Key sequences are associate with functions through the keymap. +Readline has several internal keymaps: @code{emacs_standard_keymap}, +@code{emacs_meta_keymap}, @code{emacs_ctlx_keymap}, +@code{vi_movement_keymap}, and @code{vi_insertion_keymap}. +@code{emacs_standard_keymap} is the default, and the examples in +this manual assume that. + +Since @code{readline()} installs a set of default key bindings the first +time it is called, there is always the danger that a custom binding +installed before the first call to @code{readline()} will be overridden. +An alternate mechanism is to install custom key bindings in an +initialization function assigned to the @code{rl_startup_hook} variable +(@pxref{Readline Variables}). + +These functions manage key bindings. + +@deftypefun int rl_bind_key (int key, rl_command_func_t *function) +Binds @var{key} to @var{function} in the currently active keymap. +Returns non-zero in the case of an invalid @var{key}. +@end deftypefun + +@deftypefun int rl_bind_key_in_map (int key, rl_command_func_t *function, Keymap map) +Bind @var{key} to @var{function} in @var{map}. +Returns non-zero in the case of an invalid @var{key}. +@end deftypefun + +@deftypefun int rl_bind_key_if_unbound (int key, rl_command_func_t *function) +Binds @var{key} to @var{function} if it is not already bound in the +currently active keymap. +Returns non-zero in the case of an invalid @var{key} or if @var{key} is +already bound. +@end deftypefun + +@deftypefun int rl_bind_key_if_unbound_in_map (int key, rl_command_func_t *function, Keymap map) +Binds @var{key} to @var{function} if it is not already bound in @var{map}. +Returns non-zero in the case of an invalid @var{key} or if @var{key} is +already bound. +@end deftypefun + +@deftypefun int rl_unbind_key (int key) +Bind @var{key} to the null function in the currently active keymap. +Returns non-zero in case of error. +@end deftypefun + +@deftypefun int rl_unbind_key_in_map (int key, Keymap map) +Bind @var{key} to the null function in @var{map}. +Returns non-zero in case of error. +@end deftypefun + +@deftypefun int rl_unbind_function_in_map (rl_command_func_t *function, Keymap map) +Unbind all keys that execute @var{function} in @var{map}. +@end deftypefun + +@deftypefun int rl_unbind_command_in_map (const char *command, Keymap map) +Unbind all keys that are bound to @var{command} in @var{map}. +@end deftypefun + +@deftypefun int rl_bind_keyseq (const char *keyseq, rl_command_func_t *function) +Bind the key sequence represented by the string @var{keyseq} to the function +@var{function}, beginning in the current keymap. +This makes new keymaps as necessary. +The return value is non-zero if @var{keyseq} is invalid. +@end deftypefun + +@deftypefun int rl_bind_keyseq_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) +Bind the key sequence represented by the string @var{keyseq} to the function +@var{function}. This makes new keymaps as necessary. +Initial bindings are performed in @var{map}. +The return value is non-zero if @var{keyseq} is invalid. +@end deftypefun + +@deftypefun int rl_set_key (const char *keyseq, rl_command_func_t *function, Keymap map) +Equivalent to @code{rl_bind_keyseq_in_map}. +@end deftypefun + +@deftypefun int rl_bind_keyseq_if_unbound (const char *keyseq, rl_command_func_t *function) +Binds @var{keyseq} to @var{function} if it is not already bound in the +currently active keymap. +Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is +already bound. +@end deftypefun + +@deftypefun int rl_bind_keyseq_if_unbound_in_map (const char *keyseq, rl_command_func_t *function, Keymap map) +Binds @var{keyseq} to @var{function} if it is not already bound in @var{map}. +Returns non-zero in the case of an invalid @var{keyseq} or if @var{keyseq} is +already bound. +@end deftypefun + +@deftypefun int rl_generic_bind (int type, const char *keyseq, char *data, Keymap map) +Bind the key sequence represented by the string @var{keyseq} to the arbitrary +pointer @var{data}. @var{type} says what kind of data is pointed to by +@var{data}; this can be a function (@code{ISFUNC}), a macro +(@code{ISMACR}), or a keymap (@code{ISKMAP}). This makes new keymaps as +necessary. The initial keymap in which to do bindings is @var{map}. +@end deftypefun + +@deftypefun int rl_parse_and_bind (char *line) +Parse @var{line} as if it had been read from the @code{inputrc} file and +perform any key bindings and variable assignments found +(@pxref{Readline Init File}). +@end deftypefun + +@deftypefun int rl_read_init_file (const char *filename) +Read keybindings and variable assignments from @var{filename} +(@pxref{Readline Init File}). +@end deftypefun + +@node Associating Function Names and Bindings +@subsection Associating Function Names and Bindings + +These functions allow you to find out what keys invoke named functions +and the functions invoked by a particular key sequence. You may also +associate a new function name with an arbitrary function. + +@deftypefun {rl_command_func_t *} rl_named_function (const char *name) +Return the function with name @var{name}. +@end deftypefun + +@deftypefun {rl_command_func_t *} rl_function_of_keyseq (const char *keyseq, Keymap map, int *type) +Return the function invoked by @var{keyseq} in keymap @var{map}. +If @var{map} is @code{NULL}, the current keymap is used. If @var{type} is +not @code{NULL}, the type of the object is returned in the @code{int} variable +it points to (one of @code{ISFUNC}, @code{ISKMAP}, or @code{ISMACR}). +It takes a "translated" key sequence and should not be used if the key sequence +can include NUL. +@end deftypefun + +@deftypefun {rl_command_func_t *} rl_function_of_keyseq_len (const char *keyseq, size_t len, Keymap map, int *type) +Return the function invoked by @var{keyseq} of length @var{len} +in keymap @var{map}. Equivalent to @code{rl_function_of_keyseq} with the +addition of the @var{len} parameter. +It takes a "translated" key sequence and should be used if the key sequence +can include NUL. +@end deftypefun + +@deftypefun {int} rl_trim_arg_from_keyseq (const char *keyseq, size_t len, Keymap map) +If there is a numeric argument at the beginning of @var{keyseq}, possibly +including digits, return the index of the first character in @var{keyseq} +following the numeric argument. +This can be used to skip over the numeric argument (which is available as +@code{rl_numeric_arg} while traversing the key sequence that invoked the +current command. +@end deftypefun + +@deftypefun {char **} rl_invoking_keyseqs (rl_command_func_t *function) +Return an array of strings representing the key sequences used to +invoke @var{function} in the current keymap. +@end deftypefun + +@deftypefun {char **} rl_invoking_keyseqs_in_map (rl_command_func_t *function, Keymap map) +Return an array of strings representing the key sequences used to +invoke @var{function} in the keymap @var{map}. +@end deftypefun + +@deftypefun void rl_function_dumper (int readable) +Print the Readline function names and the key sequences currently +bound to them to @code{rl_outstream}. If @var{readable} is non-zero, +the list is formatted in such a way that it can be made part of an +@code{inputrc} file and re-read. +@end deftypefun + +@deftypefun void rl_list_funmap_names (void) +Print the names of all bindable Readline functions to @code{rl_outstream}. +@end deftypefun + +@deftypefun {const char **} rl_funmap_names (void) +Return a NULL terminated array of known function names. The array is +sorted. The array itself is allocated, but not the strings inside. You +should free the array, but not the pointers, using @code{free} or +@code{rl_free} when you are done. +@end deftypefun + +@deftypefun int rl_add_funmap_entry (const char *name, rl_command_func_t *function) +Add @var{name} to the list of bindable Readline command names, and make +@var{function} the function to be called when @var{name} is invoked. +@end deftypefun + +@node Allowing Undoing +@subsection Allowing Undoing + +Supporting the undo command is a painless thing, and makes your +functions much more useful. It is certainly easy to try +something if you know you can undo it. + +If your function simply inserts text once, or deletes text once, and +uses @code{rl_insert_text()} or @code{rl_delete_text()} to do it, then +undoing is already done for you automatically. + +If you do multiple insertions or multiple deletions, or any combination +of these operations, you should group them together into one operation. +This is done with @code{rl_begin_undo_group()} and +@code{rl_end_undo_group()}. + +The types of events that can be undone are: + +@smallexample +enum undo_code @{ UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END @}; +@end smallexample + +Notice that @code{UNDO_DELETE} means to insert some text, and +@code{UNDO_INSERT} means to delete some text. That is, the undo code +tells what to undo, not how to undo it. @code{UNDO_BEGIN} and +@code{UNDO_END} are tags added by @code{rl_begin_undo_group()} and +@code{rl_end_undo_group()}. + +@deftypefun int rl_begin_undo_group (void) +Begins saving undo information in a group construct. The undo +information usually comes from calls to @code{rl_insert_text()} and +@code{rl_delete_text()}, but could be the result of calls to +@code{rl_add_undo()}. +@end deftypefun + +@deftypefun int rl_end_undo_group (void) +Closes the current undo group started with @code{rl_begin_undo_group +()}. There should be one call to @code{rl_end_undo_group()} +for each call to @code{rl_begin_undo_group()}. +@end deftypefun + +@deftypefun void rl_add_undo (enum undo_code what, int start, int end, char *text) +Remember how to undo an event (according to @var{what}). The affected +text runs from @var{start} to @var{end}, and encompasses @var{text}. +@end deftypefun + +@deftypefun void rl_free_undo_list (void) +Free the existing undo list. +@end deftypefun + +@deftypefun int rl_do_undo (void) +Undo the first thing on the undo list. Returns @code{0} if there was +nothing to undo, non-zero if something was undone. +@end deftypefun + +Finally, if you neither insert nor delete text, but directly modify the +existing text (e.g., change its case), call @code{rl_modifying()} +once, just before you modify the text. You must supply the indices of +the text range that you are going to modify. + +@deftypefun int rl_modifying (int start, int end) +Tell Readline to save the text between @var{start} and @var{end} as a +single undo unit. It is assumed that you will subsequently modify +that text. +@end deftypefun + +@node Redisplay +@subsection Redisplay + +@deftypefun void rl_redisplay (void) +Change what's displayed on the screen to reflect the current contents +of @code{rl_line_buffer}. +@end deftypefun + +@deftypefun int rl_forced_update_display (void) +Force the line to be updated and redisplayed, whether or not +Readline thinks the screen display is correct. +@end deftypefun + +@deftypefun int rl_on_new_line (void) +Tell the update functions that we have moved onto a new (empty) line, +usually after outputting a newline. +@end deftypefun + +@deftypefun int rl_on_new_line_with_prompt (void) +Tell the update functions that we have moved onto a new line, with +@var{rl_prompt} already displayed. +This could be used by applications that want to output the prompt string +themselves, but still need Readline to know the prompt string length for +redisplay. +It should be used after setting @var{rl_already_prompted}. +@end deftypefun + +@deftypefun int rl_clear_visible_line (void) +Clear the screen lines corresponding to the current line's contents. +@end deftypefun + +@deftypefun int rl_reset_line_state (void) +Reset the display state to a clean state and redisplay the current line +starting on a new line. +@end deftypefun + +@deftypefun int rl_crlf (void) +Move the cursor to the start of the next screen line. +@end deftypefun + +@deftypefun int rl_show_char (int c) +Display character @var{c} on @code{rl_outstream}. +If Readline has not been set to display meta characters directly, this +will convert meta characters to a meta-prefixed key sequence. +This is intended for use by applications which wish to do their own +redisplay. +@end deftypefun + +@deftypefun int rl_message (const char *, @dots{}) +The arguments are a format string as would be supplied to @code{printf}, +possibly containing conversion specifications such as @samp{%d}, and +any additional arguments necessary to satisfy the conversion specifications. +The resulting string is displayed in the @dfn{echo area}. The echo area +is also used to display numeric arguments and search strings. +You should call @code{rl_save_prompt} to save the prompt information +before calling this function. +@end deftypefun + +@deftypefun int rl_clear_message (void) +Clear the message in the echo area. If the prompt was saved with a call to +@code{rl_save_prompt} before the last call to @code{rl_message}, +call @code{rl_restore_prompt} before calling this function. +@end deftypefun + +@deftypefun void rl_save_prompt (void) +Save the local Readline prompt display state in preparation for +displaying a new message in the message area with @code{rl_message()}. +@end deftypefun + +@deftypefun void rl_restore_prompt (void) +Restore the local Readline prompt display state saved by the most +recent call to @code{rl_save_prompt}. +if @code{rl_save_prompt} was called to save the prompt before a call +to @code{rl_message}, this function should be called before the +corresponding call to @code{rl_clear_message}. +@end deftypefun + +@deftypefun int rl_expand_prompt (char *prompt) +Expand any special character sequences in @var{prompt} and set up the +local Readline prompt redisplay variables. +This function is called by @code{readline()}. It may also be called to +expand the primary prompt if the @code{rl_on_new_line_with_prompt()} +function or @code{rl_already_prompted} variable is used. +It returns the number of visible characters on the last line of the +(possibly multi-line) prompt. +Applications may indicate that the prompt contains characters that take +up no physical screen space when displayed by bracketing a sequence of +such characters with the special markers @code{RL_PROMPT_START_IGNORE} +and @code{RL_PROMPT_END_IGNORE} (declared in @file{readline.h} as +@samp{\001} and @samp{\002}, respectively). +This may be used to embed terminal-specific escape sequences in prompts. +@end deftypefun + +@deftypefun int rl_set_prompt (const char *prompt) +Make Readline use @var{prompt} for subsequent redisplay. This calls +@code{rl_expand_prompt()} to expand the prompt and sets @code{rl_prompt} +to the result. +@end deftypefun + +@node Modifying Text +@subsection Modifying Text + +@deftypefun int rl_insert_text (const char *text) +Insert @var{text} into the line at the current cursor position. +Returns the number of characters inserted. +@end deftypefun + +@deftypefun int rl_delete_text (int start, int end) +Delete the text between @var{start} and @var{end} in the current line. +Returns the number of characters deleted. +@end deftypefun + +@deftypefun {char *} rl_copy_text (int start, int end) +Return a copy of the text between @var{start} and @var{end} in +the current line. +@end deftypefun + +@deftypefun int rl_kill_text (int start, int end) +Copy the text between @var{start} and @var{end} in the current line +to the kill ring, appending or prepending to the last kill if the +last command was a kill command. The text is deleted. +If @var{start} is less than @var{end}, +the text is appended, otherwise prepended. If the last command was +not a kill, a new kill ring slot is used. +@end deftypefun + +@deftypefun int rl_push_macro_input (char *macro) +Cause @var{macro} to be inserted into the line, as if it had been invoked +by a key bound to a macro. Not especially useful; use +@code{rl_insert_text()} instead. +@end deftypefun + +@node Character Input +@subsection Character Input + +@deftypefun int rl_read_key (void) +Return the next character available from Readline's current input stream. +This handles input inserted into +the input stream via @var{rl_pending_input} (@pxref{Readline Variables}) +and @code{rl_stuff_char()}, macros, and characters read from the keyboard. +While waiting for input, this function will call any function assigned to +the @code{rl_event_hook} variable. +@end deftypefun + +@deftypefun int rl_getc (FILE *stream) +Return the next character available from @var{stream}, which is assumed to +be the keyboard. +@end deftypefun + +@deftypefun int rl_stuff_char (int c) +Insert @var{c} into the Readline input stream. It will be "read" +before Readline attempts to read characters from the terminal with +@code{rl_read_key()}. Up to 512 characters may be pushed back. +@code{rl_stuff_char} returns 1 if the character was successfully inserted; +0 otherwise. +@end deftypefun + +@deftypefun int rl_execute_next (int c) +Make @var{c} be the next command to be executed when @code{rl_read_key()} +is called. This sets @var{rl_pending_input}. +@end deftypefun + +@deftypefun int rl_clear_pending_input (void) +Unset @var{rl_pending_input}, effectively negating the effect of any +previous call to @code{rl_execute_next()}. This works only if the +pending input has not already been read with @code{rl_read_key()}. +@end deftypefun + +@deftypefun int rl_set_keyboard_input_timeout (int u) +While waiting for keyboard input in @code{rl_read_key()}, Readline will +wait for @var{u} microseconds for input before calling any function +assigned to @code{rl_event_hook}. @var{u} must be greater than or equal +to zero (a zero-length timeout is equivalent to a poll). +The default waiting period is one-tenth of a second. +Returns the old timeout value. +@end deftypefun + +@deftypefun int rl_set_timeout (unsigned int secs, unsigned int usecs) +Set a timeout for subsequent calls to @code{readline()}. If Readline does +not read a complete line, or the number of characters specified by +@code{rl_num_chars_to_read}, before the duration specified by @var{secs} +(in seconds) and @var{usecs} (microseconds), it returns and sets +@code{RL_STATE_TIMEOUT} in @code{rl_readline_state}. +Passing 0 for @code{secs} and @code{usecs} cancels any previously set +timeout; the convenience macro @code{rl_clear_timeout()} is shorthand +for this. +Returns 0 if the timeout is set successfully. +@end deftypefun + +@deftypefun int rl_timeout_remaining (unsigned int *secs, unsigned int *usecs) +Return the number of seconds and microseconds remaining in the current +timeout duration in @var{*secs} and @var{*usecs}, respectively. +Both @var{*secs} and @var{*usecs} must be non-NULL to return any values. +The return value is -1 on error or when there is no timeout set, +0 when the timeout has expired (leaving @var{*secs} and @var{*usecs} +unchanged), +and 1 if the timeout has not expired. +If either of @var{secs} and @var{usecs} is @code{NULL}, +the return value indicates whether the timeout has expired. +@end deftypefun + +@node Terminal Management +@subsection Terminal Management + +@deftypefun void rl_prep_terminal (int meta_flag) +Modify the terminal settings for Readline's use, so @code{readline()} +can read a single character at a time from the keyboard. +The @var{meta_flag} argument should be non-zero if Readline should +read eight-bit input. +@end deftypefun + +@deftypefun void rl_deprep_terminal (void) +Undo the effects of @code{rl_prep_terminal()}, leaving the terminal in +the state in which it was before the most recent call to +@code{rl_prep_terminal()}. +@end deftypefun + +@deftypefun void rl_tty_set_default_bindings (Keymap kmap) +Read the operating system's terminal editing characters (as would be +displayed by @code{stty}) to their Readline equivalents. +The bindings are performed in @var{kmap}. +@end deftypefun + +@deftypefun void rl_tty_unset_default_bindings (Keymap kmap) +Reset the bindings manipulated by @code{rl_tty_set_default_bindings} so +that the terminal editing characters are bound to @code{rl_insert}. +The bindings are performed in @var{kmap}. +@end deftypefun + +@deftypefun int rl_tty_set_echoing (int value) +Set Readline's idea of whether or not it is echoing output to its output +stream (@var{rl_outstream}). If @var{value} is 0, Readline does not display +output to @var{rl_outstream}; any other value enables output. The initial +value is set when Readline initializes the terminal settings. +This function returns the previous value. +@end deftypefun + +@deftypefun int rl_reset_terminal (const char *terminal_name) +Reinitialize Readline's idea of the terminal settings using +@var{terminal_name} as the terminal type (e.g., @code{vt100}). +If @var{terminal_name} is @code{NULL}, the value of the @code{TERM} +environment variable is used. +@end deftypefun + +@node Utility Functions +@subsection Utility Functions + +@deftypefun int rl_save_state (struct readline_state *sp) +Save a snapshot of Readline's internal state to @var{sp}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for allocating the structure. +@end deftypefun + +@deftypefun int rl_restore_state (struct readline_state *sp) +Restore Readline's internal state to that stored in @var{sp}, which must +have been saved by a call to @code{rl_save_state}. +The contents of the @var{readline_state} structure are documented +in @file{readline.h}. +The caller is responsible for freeing the structure. +@end deftypefun + +@deftypefun void rl_free (void *mem) +Deallocate the memory pointed to by @var{mem}. @var{mem} must have been +allocated by @code{malloc}. +@end deftypefun + +@deftypefun void rl_replace_line (const char *text, int clear_undo) +Replace the contents of @code{rl_line_buffer} with @var{text}. +The point and mark are preserved, if possible. +If @var{clear_undo} is non-zero, the undo list associated with the +current line is cleared. +@end deftypefun + +@deftypefun void rl_extend_line_buffer (int len) +Ensure that @code{rl_line_buffer} has enough space to hold @var{len} +characters, possibly reallocating it if necessary. +@end deftypefun + +@deftypefun int rl_initialize (void) +Initialize or re-initialize Readline's internal state. +It's not strictly necessary to call this; @code{readline()} calls it before +reading any input. +@end deftypefun + +@deftypefun int rl_ding (void) +Ring the terminal bell, obeying the setting of @code{bell-style}. +@end deftypefun + +@deftypefun int rl_alphabetic (int c) +Return 1 if @var{c} is an alphabetic character. +@end deftypefun + +@deftypefun void rl_display_match_list (char **matches, int len, int max) +A convenience function for displaying a list of strings in +columnar format on Readline's output stream. @code{matches} is the list +of strings, in argv format, such as a list of completion matches. +@code{len} is the number of strings in @code{matches}, and @code{max} +is the length of the longest string in @code{matches}. This function uses +the setting of @code{print-completions-horizontally} to select how the +matches are displayed (@pxref{Readline Init File Syntax}). +When displaying completions, this function sets the number of columns used +for display to the value of @code{completion-display-width}, the value of +the environment variable @env{COLUMNS}, or the screen width, in that order. +@end deftypefun + +The following are implemented as macros, defined in @code{chardefs.h}. +Applications should refrain from using them. + +@deftypefun int _rl_uppercase_p (int c) +Return 1 if @var{c} is an uppercase alphabetic character. +@end deftypefun + +@deftypefun int _rl_lowercase_p (int c) +Return 1 if @var{c} is a lowercase alphabetic character. +@end deftypefun + +@deftypefun int _rl_digit_p (int c) +Return 1 if @var{c} is a numeric character. +@end deftypefun + +@deftypefun int _rl_to_upper (int c) +If @var{c} is a lowercase alphabetic character, return the corresponding +uppercase character. +@end deftypefun + +@deftypefun int _rl_to_lower (int c) +If @var{c} is an uppercase alphabetic character, return the corresponding +lowercase character. +@end deftypefun + +@deftypefun int _rl_digit_value (int c) +If @var{c} is a number, return the value it represents. +@end deftypefun + +@node Miscellaneous Functions +@subsection Miscellaneous Functions + +@deftypefun int rl_macro_bind (const char *keyseq, const char *macro, Keymap map) +Bind the key sequence @var{keyseq} to invoke the macro @var{macro}. +The binding is performed in @var{map}. When @var{keyseq} is invoked, the +@var{macro} will be inserted into the line. This function is deprecated; +use @code{rl_generic_bind()} instead. +@end deftypefun + +@deftypefun void rl_macro_dumper (int readable) +Print the key sequences bound to macros and their values, using +the current keymap, to @code{rl_outstream}. +If @var{readable} is non-zero, the list is formatted in such a way +that it can be made part of an @code{inputrc} file and re-read. +@end deftypefun + +@deftypefun int rl_variable_bind (const char *variable, const char *value) +Make the Readline variable @var{variable} have @var{value}. +This behaves as if the Readline command +@samp{set @var{variable} @var{value}} had been executed in an @code{inputrc} +file (@pxref{Readline Init File Syntax}). +@end deftypefun + +@deftypefun {char *} rl_variable_value (const char *variable) +Return a string representing the value of the Readline variable @var{variable}. +For boolean variables, this string is either @samp{on} or @samp{off}. +@end deftypefun + +@deftypefun void rl_variable_dumper (int readable) +Print the Readline variable names and their current values +to @code{rl_outstream}. +If @var{readable} is non-zero, the list is formatted in such a way +that it can be made part of an @code{inputrc} file and re-read. +@end deftypefun + +@deftypefun int rl_set_paren_blink_timeout (int u) +Set the time interval (in microseconds) that Readline waits when showing +a balancing character when @code{blink-matching-paren} has been enabled. +@end deftypefun + +@deftypefun {char *} rl_get_termcap (const char *cap) +Retrieve the string value of the termcap capability @var{cap}. +Readline fetches the termcap entry for the current terminal name and +uses those capabilities to move around the screen line and perform other +terminal-specific operations, like erasing a line. Readline does not +use all of a terminal's capabilities, and this function will return +values for only those capabilities Readline uses. +@end deftypefun + +@deftypefun {void} rl_clear_history (void) +Clear the history list by deleting all of the entries, in the same manner +as the History library's @code{clear_history()} function. +This differs from @code{clear_history} because it frees private data +Readline saves in the history list. +@end deftypefun + +@deftypefun {void} rl_activate_mark (void) +Enable an @emph{active} mark. +When this is enabled, the text between point and mark (the @var{region}) is +displayed in the terminal's standout mode (a @var{face}). +This is called by various Readline functions that set the mark and insert +text, and is available for applications to call. +@end deftypefun + +@deftypefun {void} rl_deactivate_mark (void) +Turn off the active mark. +@end deftypefun + +@deftypefun {void} rl_keep_mark_active (void) +Indicate that the mark should remain active when the current Readline +function completes and after redisplay occurs. +In most cases, the mark remains active for only the duration of a single +bindable Readline function. +@end deftypefun + +@deftypefun {int} rl_mark_active_p (void) +Return a non-zero value if the mark is currently active; zero otherwise. +@end deftypefun + +@node Alternate Interface +@subsection Alternate Interface + +An alternate interface is available to plain @code{readline()}. Some +applications need to interleave keyboard I/O with file, device, or +window system I/O, typically by using a main loop to @code{select()} +on various file descriptors. To accommodate this need, Readline can +also be invoked as a `callback' function from an event loop. There +are functions available to make this easy. + +@deftypefun void rl_callback_handler_install (const char *prompt, rl_vcpfunc_t *lhandler) +Set up the terminal for Readline I/O and display the initial +expanded value of @var{prompt}. Save the value of @var{lhandler} to +use as a handler function to call when a complete line of input has been +entered. +The handler function receives the text of the line as an argument. +As with @code{readline()}, the handler function should @code{free} the +line when it it finished with it. +@end deftypefun + +@deftypefun void rl_callback_read_char (void) +Whenever an application determines that keyboard input is available, it +should call @code{rl_callback_read_char()}, which will read the next +character from the current input source. +If that character completes the line, @code{rl_callback_read_char} will +invoke the @var{lhandler} function installed by +@code{rl_callback_handler_install} to process the line. +Before calling the @var{lhandler} function, the terminal settings are +reset to the values they had before calling +@code{rl_callback_handler_install}. +If the @var{lhandler} function returns, +and the line handler remains installed, +the terminal settings are modified for Readline's use again. +@code{EOF} is indicated by calling @var{lhandler} with a +@code{NULL} line. +@end deftypefun + +@deftypefun void rl_callback_sigcleanup (void) +Clean up any internal state the callback interface uses to maintain state +between calls to rl_callback_read_char (e.g., the state of any active +incremental searches). This is intended to be used by applications that +wish to perform their own signal handling; Readline's internal signal handler +calls this when appropriate. +@end deftypefun + +@deftypefun void rl_callback_handler_remove (void) +Restore the terminal to its initial state and remove the line handler. +You may call this function from within a callback as well as independently. +If the @var{lhandler} installed by @code{rl_callback_handler_install} +does not exit the program, either this function or the function referred +to by the value of @code{rl_deprep_term_function} should be called before +the program exits to reset the terminal settings. +@end deftypefun + +@node A Readline Example +@subsection A Readline Example + +Here is a function which changes lowercase characters to their uppercase +equivalents, and uppercase characters to lowercase. If +this function was bound to @samp{M-c}, then typing @samp{M-c} would +change the case of the character under point. Typing @samp{M-1 0 M-c} +would change the case of the following 10 characters, leaving the cursor on +the last character changed. + +@example +/* Invert the case of the COUNT following characters. */ +int +invert_case_line (count, key) + int count, key; +@{ + register int start, end, i; + + start = rl_point; + + if (rl_point >= rl_end) + return (0); + + if (count < 0) + @{ + direction = -1; + count = -count; + @} + else + direction = 1; + + /* Find the end of the range to modify. */ + end = start + (count * direction); + + /* Force it to be within range. */ + if (end > rl_end) + end = rl_end; + else if (end < 0) + end = 0; + + if (start == end) + return (0); + + if (start > end) + @{ + int temp = start; + start = end; + end = temp; + @} + + /* Tell readline that we are modifying the line, + so it will save the undo information. */ + rl_modifying (start, end); + + for (i = start; i != end; i++) + @{ + if (_rl_uppercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_lower (rl_line_buffer[i]); + else if (_rl_lowercase_p (rl_line_buffer[i])) + rl_line_buffer[i] = _rl_to_upper (rl_line_buffer[i]); + @} + /* Move point to on top of the last character changed. */ + rl_point = (direction == 1) ? end - 1 : start; + return (0); +@} +@end example + +@node Alternate Interface Example +@subsection Alternate Interface Example + +Here is a complete program that illustrates Readline's alternate interface. +It reads lines from the terminal and displays them, providing the +standard history and TAB completion functions. +It understands the EOF character or "exit" to exit the program. + +@example +/* Standard include files. stdio.h is required. */ +#include +#include +#include +#include + +/* Used for select(2) */ +#include +#include + +#include + +#include + +/* Standard readline include files. */ +#include +#include + +static void cb_linehandler (char *); +static void sighandler (int); + +int running; +int sigwinch_received; +const char *prompt = "rltest$ "; + +/* Handle SIGWINCH and window size changes when readline is not active and + reading a character. */ +static void +sighandler (int sig) +@{ + sigwinch_received = 1; +@} + +/* Callback function called for each line when accept-line executed, EOF + seen, or EOF character read. This sets a flag and returns; it could + also call exit(3). */ +static void +cb_linehandler (char *line) +@{ + /* Can use ^D (stty eof) or `exit' to exit. */ + if (line == NULL || strcmp (line, "exit") == 0) + @{ + if (line == 0) + printf ("\n"); + printf ("exit\n"); + /* This function needs to be called to reset the terminal settings, + and calling it from the line handler keeps one extra prompt from + being displayed. */ + rl_callback_handler_remove (); + + running = 0; + @} + else + @{ + if (*line) + add_history (line); + printf ("input line: %s\n", line); + free (line); + @} +@} + +int +main (int c, char **v) +@{ + fd_set fds; + int r; + + /* Set the default locale values according to environment variables. */ + setlocale (LC_ALL, ""); + + /* Handle window size changes when readline is not active and reading + characters. */ + signal (SIGWINCH, sighandler); + + /* Install the line handler. */ + rl_callback_handler_install (prompt, cb_linehandler); + + /* Enter a simple event loop. This waits until something is available + to read on readline's input stream (defaults to standard input) and + calls the builtin character read callback to read it. It does not + have to modify the user's terminal settings. */ + running = 1; + while (running) + @{ + FD_ZERO (&fds); + FD_SET (fileno (rl_instream), &fds); + + r = select (FD_SETSIZE, &fds, NULL, NULL, NULL); + if (r < 0 && errno != EINTR) + @{ + perror ("rltest: select"); + rl_callback_handler_remove (); + break; + @} + if (sigwinch_received) + @{ + rl_resize_terminal (); + sigwinch_received = 0; + @} + if (r < 0) + continue; + + if (FD_ISSET (fileno (rl_instream), &fds)) + rl_callback_read_char (); + @} + + printf ("rltest: Event loop has exited\n"); + return 0; +@} +@end example + +@node Readline Signal Handling +@section Readline Signal Handling + +Signals are asynchronous events sent to a process by the Unix kernel, +sometimes on behalf of another process. They are intended to indicate +exceptional events, like a user pressing the terminal's interrupt key, +or a network connection being broken. There is a class of signals that can +be sent to the process currently reading input from the keyboard. Since +Readline changes the terminal attributes when it is called, it needs to +perform special processing when such a signal is received in order to +restore the terminal to a sane state, or provide application writers with +functions to do so manually. + +Readline contains an internal signal handler that is installed for a +number of signals (@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, +@code{SIGHUP}, +@code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}). +When one of these signals is received, the signal handler +will reset the terminal attributes to those that were in effect before +@code{readline()} was called, reset the signal handling to what it was +before @code{readline()} was called, and resend the signal to the calling +application. +If and when the calling application's signal handler returns, Readline +will reinitialize the terminal and continue to accept input. +When a @code{SIGINT} is received, the Readline signal handler performs +some additional work, which will cause any partially-entered line to be +aborted (see the description of @code{rl_free_line_state()} below). + +There is an additional Readline signal handler, for @code{SIGWINCH}, which +the kernel sends to a process whenever the terminal's size changes (for +example, if a user resizes an @code{xterm}). The Readline @code{SIGWINCH} +handler updates Readline's internal screen size information, and then calls +any @code{SIGWINCH} signal handler the calling application has installed. +Readline calls the application's @code{SIGWINCH} signal handler without +resetting the terminal to its original state. If the application's signal +handler does more than update its idea of the terminal size and return (for +example, a @code{longjmp} back to a main processing loop), it @emph{must} +call @code{rl_cleanup_after_signal()} (described below), to restore the +terminal state. + +When an application is using the callback interface +(@pxref{Alternate Interface}), Readline installs signal handlers only for +the duration of the call to @code{rl_callback_read_char}. Applications +using the callback interface should be prepared to clean up Readline's +state if they wish to handle the signal before the line handler completes +and restores the terminal state. + +If an application using the callback interface wishes to have Readline +install its signal handlers at the time the application calls +@code{rl_callback_handler_install} and remove them only when a complete +line of input has been read, it should set the +@code{rl_persistent_signal_handlers} variable to a non-zero value. +This allows an application to defer all of the handling of the signals +Readline catches to Readline. +Applications should use this variable with care; it can result in Readline +catching signals and not acting on them (or allowing the application to react +to them) until the application calls @code{rl_callback_read_char}. This +can result in an application becoming less responsive to keyboard signals +like SIGINT. +If an application does not want or need to perform any signal handling, or +does not need to do any processing between calls to @code{rl_callback_read_char}, +setting this variable may be desirable. + +Readline provides two variables that allow application writers to +control whether or not it will catch certain signals and act on them +when they are received. It is important that applications change the +values of these variables only when calling @code{readline()}, not in +a signal handler, so Readline's internal signal state is not corrupted. + +@deftypevar int rl_catch_signals +If this variable is non-zero, Readline will install signal handlers for +@code{SIGINT}, @code{SIGQUIT}, @code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, +@code{SIGTSTP}, @code{SIGTTIN}, and @code{SIGTTOU}. + +The default value of @code{rl_catch_signals} is 1. +@end deftypevar + +@deftypevar int rl_catch_sigwinch +If this variable is set to a non-zero value, +Readline will install a signal handler for @code{SIGWINCH}. + +The default value of @code{rl_catch_sigwinch} is 1. +@end deftypevar + +@deftypevar int rl_persistent_signal_handlers +If an application using the callback interface wishes Readline's signal +handlers to be installed and active during the set of calls to +@code{rl_callback_read_char} that constitutes an entire single line, +it should set this variable to a non-zero value. + +The default value of @code{rl_persistent_signal_handlers} is 0. +@end deftypevar + +@deftypevar int rl_change_environment +If this variable is set to a non-zero value, +and Readline is handling @code{SIGWINCH}, Readline will modify the +@var{LINES} and @var{COLUMNS} environment variables upon receipt of a +@code{SIGWINCH} + +The default value of @code{rl_change_environment} is 1. +@end deftypevar + +If an application does not wish to have Readline catch any signals, or +to handle signals other than those Readline catches (@code{SIGHUP}, +for example), +Readline provides convenience functions to do the necessary terminal +and internal state cleanup upon receipt of a signal. + +@deftypefun int rl_pending_signal (void) +Return the signal number of the most recent signal Readline received but +has not yet handled, or 0 if there is no pending signal. +@end deftypefun + +@deftypefun void rl_cleanup_after_signal (void) +This function will reset the state of the terminal to what it was before +@code{readline()} was called, and remove the Readline signal handlers for +all signals, depending on the values of @code{rl_catch_signals} and +@code{rl_catch_sigwinch}. +@end deftypefun + +@deftypefun void rl_free_line_state (void) +This will free any partial state associated with the current input line +(undo information, any partial history entry, any partially-entered +keyboard macro, and any partially-entered numeric argument). This +should be called before @code{rl_cleanup_after_signal()}. The +Readline signal handler for @code{SIGINT} calls this to abort the +current input line. +@end deftypefun + +@deftypefun void rl_reset_after_signal (void) +This will reinitialize the terminal and reinstall any Readline signal +handlers, depending on the values of @code{rl_catch_signals} and +@code{rl_catch_sigwinch}. +@end deftypefun + +If an application wants to force Readline to handle any signals that +have arrived while it has been executing, @code{rl_check_signals()} +will call Readline's internal signal handler if there are any pending +signals. This is primarily intended for those applications that use +a custom @code{rl_getc_function} (@pxref{Readline Variables}) and wish +to handle signals received while waiting for input. + +@deftypefun void rl_check_signals (void) +If there are any pending signals, call Readline's internal signal handling +functions to process them. @code{rl_pending_signal()} can be used independently +to determine whether or not there are any pending signals. +@end deftypefun + +If an application does not wish Readline to catch @code{SIGWINCH}, it may +call @code{rl_resize_terminal()} or @code{rl_set_screen_size()} to force +Readline to update its idea of the terminal size when it receives +a @code{SIGWINCH}. + +@deftypefun void rl_echo_signal_char (int sig) +If an application wishes to install its own signal handlers, but still +have Readline display characters that generate signals, calling this +function with @var{sig} set to @code{SIGINT}, @code{SIGQUIT}, or +@code{SIGTSTP} will display the character generating that signal. +@end deftypefun + +@deftypefun void rl_resize_terminal (void) +Update Readline's internal screen size by reading values from the kernel. +@end deftypefun + +@deftypefun void rl_set_screen_size (int rows, int cols) +Set Readline's idea of the terminal size to @var{rows} rows and +@var{cols} columns. If either @var{rows} or @var{columns} is less than +or equal to 0, Readline's idea of that terminal dimension is unchanged. +This is intended to tell Readline the physical dimensions of the terminal, +and is used internally to calculate the maximum number of characters that +may appear on a single line and on the screen. +@end deftypefun + +If an application does not want to install a @code{SIGWINCH} handler, but +is still interested in the screen dimensions, it may query Readline's idea +of the screen size. + +@deftypefun void rl_get_screen_size (int *rows, int *cols) +Return Readline's idea of the terminal's size in the +variables pointed to by the arguments. +@end deftypefun + +@deftypefun void rl_reset_screen_size (void) +Cause Readline to reobtain the screen size and recalculate its dimensions. +@end deftypefun + +The following functions install and remove Readline's signal handlers. + +@deftypefun int rl_set_signals (void) +Install Readline's signal handler for @code{SIGINT}, @code{SIGQUIT}, +@code{SIGTERM}, @code{SIGHUP}, @code{SIGALRM}, @code{SIGTSTP}, @code{SIGTTIN}, +@code{SIGTTOU}, and @code{SIGWINCH}, depending on the values of +@code{rl_catch_signals} and @code{rl_catch_sigwinch}. +@end deftypefun + +@deftypefun int rl_clear_signals (void) +Remove all of the Readline signal handlers installed by +@code{rl_set_signals()}. +@end deftypefun + +@node Custom Completers +@section Custom Completers +@cindex application-specific completion functions + +Typically, a program that reads commands from the user has a way of +disambiguating commands and data. If your program is one of these, then +it can provide completion for commands, data, or both. +The following sections describe how your program and Readline +cooperate to provide this service. + +@menu +* How Completing Works:: The logic used to do completion. +* Completion Functions:: Functions provided by Readline. +* Completion Variables:: Variables which control completion. +* A Short Completion Example:: An example of writing completer subroutines. +@end menu + +@node How Completing Works +@subsection How Completing Works + +In order to complete some text, the full list of possible completions +must be available. That is, it is not possible to accurately +expand a partial word without knowing all of the possible words +which make sense in that context. The Readline library provides +the user interface to completion, and two of the most common +completion functions: filename and username. For completing other types +of text, you must write your own completion function. This section +describes exactly what such functions must do, and provides an example. + +There are three major functions used to perform completion: + +@enumerate +@item +The user-interface function @code{rl_complete()}. This function is +called with the same arguments as other bindable Readline functions: +@var{count} and @var{invoking_key}. +It isolates the word to be completed and calls +@code{rl_completion_matches()} to generate a list of possible completions. +It then either lists the possible completions, inserts the possible +completions, or actually performs the +completion, depending on which behavior is desired. + +@item +The internal function @code{rl_completion_matches()} uses an +application-supplied @dfn{generator} function to generate the list of +possible matches, and then returns the array of these matches. +The caller should place the address of its generator function in +@code{rl_completion_entry_function}. + +@item +The generator function is called repeatedly from +@code{rl_completion_matches()}, returning a string each time. The +arguments to the generator function are @var{text} and @var{state}. +@var{text} is the partial word to be completed. @var{state} is zero the +first time the function is called, allowing the generator to perform +any necessary initialization, and a positive non-zero integer for +each subsequent call. The generator function returns +@code{(char *)NULL} to inform @code{rl_completion_matches()} that there are +no more possibilities left. Usually the generator function computes the +list of possible completions when @var{state} is zero, and returns them +one at a time on subsequent calls. Each string the generator function +returns as a match must be allocated with @code{malloc()}; Readline +frees the strings when it has finished with them. +Such a generator function is referred to as an +@dfn{application-specific completion function}. + +@end enumerate + +@deftypefun int rl_complete (int ignore, int invoking_key) +Complete the word at or before point. You have supplied the function +that does the initial simple matching selection algorithm (see +@code{rl_completion_matches()}). The default is to do filename completion. +@end deftypefun + +@deftypevar {rl_compentry_func_t *} rl_completion_entry_function +This is a pointer to the generator function for +@code{rl_completion_matches()}. +If the value of @code{rl_completion_entry_function} is +@code{NULL} then the default filename generator +function, @code{rl_filename_completion_function()}, is used. +An @dfn{application-specific completion function} is a function whose +address is assigned to @code{rl_completion_entry_function} and whose +return values are used to generate possible completions. +@end deftypevar + +@node Completion Functions +@subsection Completion Functions + +Here is the complete list of callable completion functions present in +Readline. + +@deftypefun int rl_complete_internal (int what_to_do) +Complete the word at or before point. @var{what_to_do} says what to do +with the completion. A value of @samp{?} means list the possible +completions. @samp{TAB} means do standard completion. @samp{*} means +insert all of the possible completions. @samp{!} means to display +all of the possible completions, if there is more than one, as well as +performing partial completion. @samp{@@} is similar to @samp{!}, but +possible completions are not listed if the possible completions share +a common prefix. +@end deftypefun + +@deftypefun int rl_complete (int ignore, int invoking_key) +Complete the word at or before point. You have supplied the function +that does the initial simple matching selection algorithm (see +@code{rl_completion_matches()} and @code{rl_completion_entry_function}). +The default is to do filename +completion. This calls @code{rl_complete_internal()} with an +argument depending on @var{invoking_key}. +@end deftypefun + +@deftypefun int rl_possible_completions (int count, int invoking_key) +List the possible completions. See description of @code{rl_complete +()}. This calls @code{rl_complete_internal()} with an argument of +@samp{?}. +@end deftypefun + +@deftypefun int rl_insert_completions (int count, int invoking_key) +Insert the list of possible completions into the line, deleting the +partially-completed word. See description of @code{rl_complete()}. +This calls @code{rl_complete_internal()} with an argument of @samp{*}. +@end deftypefun + +@deftypefun int rl_completion_mode (rl_command_func_t *cfunc) +Returns the appropriate value to pass to @code{rl_complete_internal()} +depending on whether @var{cfunc} was called twice in succession and +the values of the @code{show-all-if-ambiguous} and +@code{show-all-if-unmodified} variables. +Application-specific completion functions may use this function to present +the same interface as @code{rl_complete()}. +@end deftypefun + +@deftypefun {char **} rl_completion_matches (const char *text, rl_compentry_func_t *entry_func) +Returns an array of strings which is a list of completions for +@var{text}. If there are no completions, returns @code{NULL}. +The first entry in the returned array is the substitution for @var{text}. +The remaining entries are the possible completions. The array is +terminated with a @code{NULL} pointer. + +@var{entry_func} is a function of two args, and returns a +@code{char *}. The first argument is @var{text}. The second is a +state argument; it is zero on the first call, and non-zero on subsequent +calls. @var{entry_func} returns a @code{NULL} pointer to the caller +when there are no more matches. +@end deftypefun + +@deftypefun {char *} rl_filename_completion_function (const char *text, int state) +A generator function for filename completion in the general case. +@var{text} is a partial filename. +The Bash source is a useful reference for writing application-specific +completion functions (the Bash completion functions call this and other +Readline functions). +@end deftypefun + +@deftypefun {char *} rl_username_completion_function (const char *text, int state) +A completion generator for usernames. @var{text} contains a partial +username preceded by a random character (usually @samp{~}). As with all +completion generators, @var{state} is zero on the first call and non-zero +for subsequent calls. +@end deftypefun + +@node Completion Variables +@subsection Completion Variables + +@deftypevar {rl_compentry_func_t *} rl_completion_entry_function +A pointer to the generator function for @code{rl_completion_matches()}. +@code{NULL} means to use @code{rl_filename_completion_function()}, +the default filename completer. +@end deftypevar + +@deftypevar {rl_completion_func_t *} rl_attempted_completion_function +A pointer to an alternative function to create matches. +The function is called with @var{text}, @var{start}, and @var{end}. +@var{start} and @var{end} are indices in @code{rl_line_buffer} defining +the boundaries of @var{text}, which is a character string. +If this function exists and returns @code{NULL}, or if this variable is +set to @code{NULL}, then @code{rl_complete()} will call the value of +@code{rl_completion_entry_function} to generate matches, otherwise the +array of strings returned will be used. +If this function sets the @code{rl_attempted_completion_over} +variable to a non-zero value, Readline will not perform its default +completion even if this function returns no matches. +@end deftypevar + +@deftypevar {rl_quote_func_t *} rl_filename_quoting_function +A pointer to a function that will quote a filename in an +application-specific fashion. This is called if filename completion is being +attempted and one of the characters in @code{rl_filename_quote_characters} +appears in a completed filename. The function is called with +@var{text}, @var{match_type}, and @var{quote_pointer}. The @var{text} +is the filename to be quoted. The @var{match_type} is either +@code{SINGLE_MATCH}, if there is only one completion match, or +@code{MULT_MATCH}. Some functions use this to decide whether or not to +insert a closing quote character. The @var{quote_pointer} is a pointer +to any opening quote character the user typed. Some functions choose +to reset this character. +@end deftypevar + +@deftypevar {rl_dequote_func_t *} rl_filename_dequoting_function +A pointer to a function that will remove application-specific quoting +characters from a filename before completion is attempted, so those +characters do not interfere with matching the text against names in +the filesystem. It is called with @var{text}, the text of the word +to be dequoted, and @var{quote_char}, which is the quoting character +that delimits the filename (usually @samp{'} or @samp{"}). If +@var{quote_char} is zero, the filename was not in an embedded string. +@end deftypevar + +@deftypevar {rl_linebuf_func_t *} rl_char_is_quoted_p +A pointer to a function to call that determines whether or not a specific +character in the line buffer is quoted, according to whatever quoting +mechanism the program calling Readline uses. The function is called with +two arguments: @var{text}, the text of the line, and @var{index}, the +index of the character in the line. It is used to decide whether a +character found in @code{rl_completer_word_break_characters} should be +used to break words for the completer. +@end deftypevar + +@deftypevar {rl_compignore_func_t *} rl_ignore_some_completions_function +This function, if defined, is called by the completer when real filename +completion is done, after all the matching names have been generated. +It is passed a @code{NULL} terminated array of matches. +The first element (@code{matches[0]}) is the +maximal substring common to all matches. This function can +re-arrange the list of matches as required, but each element deleted +from the array must be freed. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_directory_completion_hook +This function, if defined, is allowed to modify the directory portion +of filenames Readline completes. +It could be used to expand symbolic links or shell variables in pathnames. +It is called with the address of a string (the current directory name) as an +argument, and may modify that string. +If the string is replaced with a new string, the old value should be freed. +Any modified directory name should have a trailing slash. +The modified value will be used as part of the completion, replacing +the directory portion of the pathname the user typed. +At the least, even if no other expansion is performed, this function should +remove any quote characters from the directory name, because its result will +be passed directly to @code{opendir()}. + +The directory completion hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_directory_rewrite_hook; +If non-zero, this is the address of a function to call when completing +a directory name. This function takes the address of the directory name +to be modified as an argument. Unlike @code{rl_directory_completion_hook}, +it only modifies the directory name used in @code{opendir}, not what is +displayed when the possible completions are printed or inserted. It is +called before rl_directory_completion_hook. +At the least, even if no other expansion is performed, this function should +remove any quote characters from the directory name, because its result will +be passed directly to @code{opendir()}. + +The directory rewrite hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_icppfunc_t *} rl_filename_stat_hook +If non-zero, this is the address of a function for the completer to +call before deciding which character to append to a completed name. +This function modifies its filename name argument, and the modified value +is passed to @code{stat()} to determine the file's type and characteristics. +This function does not need to remove quote characters from the filename. + +The stat hook returns an integer that should be non-zero if +the function modifies its directory argument. +The function should not modify the directory argument if it returns 0. +@end deftypevar + +@deftypevar {rl_dequote_func_t *} rl_filename_rewrite_hook +If non-zero, this is the address of a function called when reading +directory entries from the filesystem for completion and comparing +them to the partial word to be completed. The function should +perform any necessary application or system-specific conversion on +the filename, such as converting between character sets or converting +from a filesystem format to a character input format. +The function takes two arguments: @var{fname}, the filename to be converted, +and @var{fnlen}, its length in bytes. +It must either return its first argument (if no conversion takes place) +or the converted filename in newly-allocated memory. The converted +form is used to compare against the word to be completed, and, if it +matches, is added to the list of matches. Readline will free the +allocated string. +@end deftypevar + +@deftypevar {rl_compdisp_func_t *} rl_completion_display_matches_hook +If non-zero, then this is the address of a function to call when +completing a word would normally display the list of possible matches. +This function is called in lieu of Readline displaying the list. +It takes three arguments: +(@code{char **}@var{matches}, @code{int} @var{num_matches}, @code{int} @var{max_length}) +where @var{matches} is the array of matching strings, +@var{num_matches} is the number of strings in that array, and +@var{max_length} is the length of the longest string in that array. +Readline provides a convenience function, @code{rl_display_match_list}, +that takes care of doing the display to Readline's output stream. +You may call that function from this hook. +@end deftypevar + +@deftypevar {const char *} rl_basic_word_break_characters +The basic list of characters that signal a break between words for the +completer routine. The default value of this variable is the characters +which break words for completion in Bash: +@code{" \t\n\"\\'`@@$><=;|&@{("}. +@end deftypevar + +@deftypevar {const char *} rl_basic_quote_characters +A list of quote characters which can cause a word break. +@end deftypevar + +@deftypevar {const char *} rl_completer_word_break_characters +The list of characters that signal a break between words for +@code{rl_complete_internal()}. The default list is the value of +@code{rl_basic_word_break_characters}. +@end deftypevar + +@deftypevar {rl_cpvfunc_t *} rl_completion_word_break_hook +If non-zero, this is the address of a function to call when Readline is +deciding where to separate words for word completion. It should return +a character string like @code{rl_completer_word_break_characters} to be +used to perform the current completion. The function may choose to set +@code{rl_completer_word_break_characters} itself. If the function +returns @code{NULL}, @code{rl_completer_word_break_characters} is used. +@end deftypevar + +@deftypevar {const char *} rl_completer_quote_characters +A list of characters which can be used to quote a substring of the line. +Completion occurs on the entire substring, and within the substring +@code{rl_completer_word_break_characters} are treated as any other character, +unless they also appear within this list. +@end deftypevar + +@deftypevar {const char *} rl_filename_quote_characters +A list of characters that cause a filename to be quoted by the completer +when they appear in a completed filename. The default is the null string. +@end deftypevar + +@deftypevar {const char *} rl_special_prefixes +The list of characters that are word break characters, but should be +left in @var{text} when it is passed to the completion function. +Programs can use this to help determine what kind of completing to do. +For instance, Bash sets this variable to "$@@" so that it can complete +shell variables and hostnames. +@end deftypevar + +@deftypevar int rl_completion_query_items +Up to this many items will be displayed in response to a +possible-completions call. After that, Readline asks the user for +confirmation before displaying them. +The default value is 100. A negative value +indicates that Readline should never ask for confirmation. +@end deftypevar + +@deftypevar {int} rl_completion_append_character +When a single completion alternative matches at the end of the command +line, this character is appended to the inserted completion text. The +default is a space character (@samp{ }). Setting this to the null +character (@samp{\0}) prevents anything being appended automatically. +This can be changed in application-specific completion functions to +provide the ``most sensible word separator character'' according to +an application-specific command line syntax specification. +It is set to the default before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_suppress_append +If non-zero, @var{rl_completion_append_character} is not appended to +matches at the end of the command line, as described above. +It is set to 0 before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_quote_character +When Readline is completing quoted text, as delimited by one of the +characters in @var{rl_completer_quote_characters}, it sets this variable +to the quoting character found. +This is set before any application-specific completion function is called. +@end deftypevar + +@deftypevar int rl_completion_suppress_quote +If non-zero, Readline does not append a matching quote character when +performing completion on a quoted string. +It is set to 0 before any application-specific completion function +is called, and may only be changed within such a function. +@end deftypevar + +@deftypevar int rl_completion_found_quote +When Readline is completing quoted text, it sets this variable +to a non-zero value if the word being completed contains or is delimited +by any quoting characters, including backslashes. +This is set before any application-specific completion function is called. +@end deftypevar + +@deftypevar int rl_completion_mark_symlink_dirs +If non-zero, a slash will be appended to completed filenames that are +symbolic links to directory names, subject to the value of the +user-settable @var{mark-directories} variable. +This variable exists so that application-specific completion functions +can override the user's global preference (set via the +@var{mark-symlinked-directories} Readline variable) if appropriate. +This variable is set to the user's preference before any +application-specific completion function is called, so unless that +function modifies the value, the user's preferences are honored. +@end deftypevar + +@deftypevar int rl_ignore_completion_duplicates +If non-zero, then duplicates in the matches are removed. +The default is 1. +@end deftypevar + +@deftypevar int rl_filename_completion_desired +Non-zero means that the results of the matches are to be treated as +filenames. This is @emph{always} zero when completion is attempted, +and can only be changed +within an application-specific completion function. If it is set to a +non-zero value by such a function, directory names have a slash appended +and Readline attempts to quote completed filenames if they contain any +characters in @code{rl_filename_quote_characters} and +@code{rl_filename_quoting_desired} is set to a non-zero value. +@end deftypevar + +@deftypevar int rl_filename_quoting_desired +Non-zero means that the results of the matches are to be quoted using +double quotes (or an application-specific quoting mechanism) if the +completed filename contains any characters in +@code{rl_filename_quote_chars}. This is @emph{always} non-zero +when completion is attempted, and can only be changed within an +application-specific completion function. +The quoting is effected via a call to the function pointed to +by @code{rl_filename_quoting_function}. +@end deftypevar + +@deftypevar int rl_attempted_completion_over +If an application-specific completion function assigned to +@code{rl_attempted_completion_function} sets this variable to a non-zero +value, Readline will not perform its default filename completion even +if the application's completion function returns no matches. +It should be set only by an application's completion function. +@end deftypevar + +@deftypevar int rl_sort_completion_matches +If an application sets this variable to 0, Readline will not sort the +list of completions (which implies that it cannot remove any duplicate +completions). The default value is 1, which means that Readline will +sort the completions and, depending on the value of +@code{rl_ignore_completion_duplicates}, will attempt to remove duplicate +matches. +@end deftypevar + +@deftypevar int rl_completion_type +Set to a character describing the type of completion Readline is currently +attempting; see the description of @code{rl_complete_internal()} +(@pxref{Completion Functions}) for the list of characters. +This is set to the appropriate value before any application-specific +completion function is called, allowing such functions to present +the same interface as @code{rl_complete()}. +@end deftypevar + +@deftypevar int rl_completion_invoking_key +Set to the final character in the key sequence that invoked one of the +completion functions that call @code{rl_complete_internal()}. This is +set to the appropriate value before any application-specific completion +function is called. +@end deftypevar + +@deftypevar int rl_inhibit_completion +If this variable is non-zero, completion is inhibited. The completion +character will be inserted as any other bound to @code{self-insert}. +@end deftypevar + +@node A Short Completion Example +@subsection A Short Completion Example + +Here is a small application demonstrating the use of the GNU Readline +library. It is called @code{fileman}, and the source code resides in +@file{examples/fileman.c}. This sample application provides +completion of command names, line editing features, and access to the +history list. + +@page +@smallexample +/* fileman.c -- A tiny application which demonstrates how to use the + GNU Readline library. This application interactively allows users + to manipulate files and their modes. */ + +#ifdef HAVE_CONFIG_H +# include +#endif + +#include +#ifdef HAVE_SYS_FILE_H +# include +#endif +#include + +#ifdef HAVE_UNISTD_H +# include +#endif + +#include +#include +#include +#include + +#if defined (HAVE_STRING_H) +# include +#else /* !HAVE_STRING_H */ +# include +#endif /* !HAVE_STRING_H */ + +#ifdef HAVE_STDLIB_H +# include +#endif + +#include + +#include +#include + +extern char *xmalloc PARAMS((size_t)); + +/* The names of functions that actually do the manipulation. */ +int com_list PARAMS((char *)); +int com_view PARAMS((char *)); +int com_rename PARAMS((char *)); +int com_stat PARAMS((char *)); +int com_pwd PARAMS((char *)); +int com_delete PARAMS((char *)); +int com_help PARAMS((char *)); +int com_cd PARAMS((char *)); +int com_quit PARAMS((char *)); + +/* A structure which contains information on the commands this program + can understand. */ + +typedef struct @{ + char *name; /* User printable name of the function. */ + rl_icpfunc_t *func; /* Function to call to do the job. */ + char *doc; /* Documentation for this function. */ +@} COMMAND; + +COMMAND commands[] = @{ + @{ "cd", com_cd, "Change to directory DIR" @}, + @{ "delete", com_delete, "Delete FILE" @}, + @{ "help", com_help, "Display this text" @}, + @{ "?", com_help, "Synonym for `help'" @}, + @{ "list", com_list, "List files in DIR" @}, + @{ "ls", com_list, "Synonym for `list'" @}, + @{ "pwd", com_pwd, "Print the current working directory" @}, + @{ "quit", com_quit, "Quit using Fileman" @}, + @{ "rename", com_rename, "Rename FILE to NEWNAME" @}, + @{ "stat", com_stat, "Print out statistics on FILE" @}, + @{ "view", com_view, "View the contents of FILE" @}, + @{ (char *)NULL, (rl_icpfunc_t *)NULL, (char *)NULL @} +@}; + +/* Forward declarations. */ +char *stripwhite (); +COMMAND *find_command (); + +/* The name of this program, as taken from argv[0]. */ +char *progname; + +/* When non-zero, this global means the user is done using this program. */ +int done; + +char * +dupstr (s) + char *s; +@{ + char *r; + + r = xmalloc (strlen (s) + 1); + strcpy (r, s); + return (r); +@} + +main (argc, argv) + int argc; + char **argv; +@{ + char *line, *s; + + setlocale (LC_ALL, ""); + + progname = argv[0]; + + initialize_readline (); /* Bind our completer. */ + + /* Loop reading and executing lines until the user quits. */ + for ( ; done == 0; ) + @{ + line = readline ("FileMan: "); + + if (!line) + break; + + /* Remove leading and trailing whitespace from the line. + Then, if there is anything left, add it to the history list + and execute it. */ + s = stripwhite (line); + + if (*s) + @{ + add_history (s); + execute_line (s); + @} + + free (line); + @} + exit (0); +@} + +/* Execute a command line. */ +int +execute_line (line) + char *line; +@{ + register int i; + COMMAND *command; + char *word; + + /* Isolate the command word. */ + i = 0; + while (line[i] && whitespace (line[i])) + i++; + word = line + i; + + while (line[i] && !whitespace (line[i])) + i++; + + if (line[i]) + line[i++] = '\0'; + + command = find_command (word); + + if (!command) + @{ + fprintf (stderr, "%s: No such command for FileMan.\n", word); + return (-1); + @} + + /* Get argument to command, if any. */ + while (whitespace (line[i])) + i++; + + word = line + i; + + /* Call the function. */ + return ((*(command->func)) (word)); +@} + +/* Look up NAME as the name of a command, and return a pointer to that + command. Return a NULL pointer if NAME isn't a command name. */ +COMMAND * +find_command (name) + char *name; +@{ + register int i; + + for (i = 0; commands[i].name; i++) + if (strcmp (name, commands[i].name) == 0) + return (&commands[i]); + + return ((COMMAND *)NULL); +@} + +/* Strip whitespace from the start and end of STRING. Return a pointer + into STRING. */ +char * +stripwhite (string) + char *string; +@{ + register char *s, *t; + + for (s = string; whitespace (*s); s++) + ; + + if (*s == 0) + return (s); + + t = s + strlen (s) - 1; + while (t > s && whitespace (*t)) + t--; + *++t = '\0'; + + return s; +@} + +/* **************************************************************** */ +/* */ +/* Interface to Readline Completion */ +/* */ +/* **************************************************************** */ + +char *command_generator PARAMS((const char *, int)); +char **fileman_completion PARAMS((const char *, int, int)); + +/* Tell the GNU Readline library how to complete. We want to try to complete + on command names if this is the first word in the line, or on filenames + if not. */ +initialize_readline () +@{ + /* Allow conditional parsing of the ~/.inputrc file. */ + rl_readline_name = "FileMan"; + + /* Tell the completer that we want a crack first. */ + rl_attempted_completion_function = fileman_completion; +@} + +/* Attempt to complete on the contents of TEXT. START and END bound the + region of rl_line_buffer that contains the word to complete. TEXT is + the word to complete. We can use the entire contents of rl_line_buffer + in case we want to do some simple parsing. Return the array of matches, + or NULL if there aren't any. */ +char ** +fileman_completion (text, start, end) + const char *text; + int start, end; +@{ + char **matches; + + matches = (char **)NULL; + + /* If this word is at the start of the line, then it is a command + to complete. Otherwise it is the name of a file in the current + directory. */ + if (start == 0) + matches = rl_completion_matches (text, command_generator); + + return (matches); +@} + +/* Generator function for command completion. STATE lets us know whether + to start from scratch; without any state (i.e. STATE == 0), then we + start at the top of the list. */ +char * +command_generator (text, state) + const char *text; + int state; +@{ + static int list_index, len; + char *name; + + /* If this is a new word to complete, initialize now. This includes + saving the length of TEXT for efficiency, and initializing the index + variable to 0. */ + if (!state) + @{ + list_index = 0; + len = strlen (text); + @} + + /* Return the next name which partially matches from the command list. */ + while (name = commands[list_index].name) + @{ + list_index++; + + if (strncmp (name, text, len) == 0) + return (dupstr(name)); + @} + + /* If no names matched, then return NULL. */ + return ((char *)NULL); +@} + +/* **************************************************************** */ +/* */ +/* FileMan Commands */ +/* */ +/* **************************************************************** */ + +/* String to pass to system (). This is for the LIST, VIEW and RENAME + commands. */ +static char syscom[1024]; + +/* List the file(s) named in arg. */ +com_list (arg) + char *arg; +@{ + if (!arg) + arg = ""; + + sprintf (syscom, "ls -FClg %s", arg); + return (system (syscom)); +@} + +com_view (arg) + char *arg; +@{ + if (!valid_argument ("view", arg)) + return 1; + +#if defined (__MSDOS__) + /* more.com doesn't grok slashes in pathnames */ + sprintf (syscom, "less %s", arg); +#else + sprintf (syscom, "more %s", arg); +#endif + return (system (syscom)); +@} + +com_rename (arg) + char *arg; +@{ + too_dangerous ("rename"); + return (1); +@} + +com_stat (arg) + char *arg; +@{ + struct stat finfo; + + if (!valid_argument ("stat", arg)) + return (1); + + if (stat (arg, &finfo) == -1) + @{ + perror (arg); + return (1); + @} + + printf ("Statistics for `%s':\n", arg); + + printf ("%s has %d link%s, and is %d byte%s in length.\n", + arg, + finfo.st_nlink, + (finfo.st_nlink == 1) ? "" : "s", + finfo.st_size, + (finfo.st_size == 1) ? "" : "s"); + printf ("Inode Last Change at: %s", ctime (&finfo.st_ctime)); + printf (" Last access at: %s", ctime (&finfo.st_atime)); + printf (" Last modified at: %s", ctime (&finfo.st_mtime)); + return (0); +@} + +com_delete (arg) + char *arg; +@{ + too_dangerous ("delete"); + return (1); +@} + +/* Print out help for ARG, or for all of the commands if ARG is + not present. */ +com_help (arg) + char *arg; +@{ + register int i; + int printed = 0; + + for (i = 0; commands[i].name; i++) + @{ + if (!*arg || (strcmp (arg, commands[i].name) == 0)) + @{ + printf ("%s\t\t%s.\n", commands[i].name, commands[i].doc); + printed++; + @} + @} + + if (!printed) + @{ + printf ("No commands match `%s'. Possibilities are:\n", arg); + + for (i = 0; commands[i].name; i++) + @{ + /* Print in six columns. */ + if (printed == 6) + @{ + printed = 0; + printf ("\n"); + @} + + printf ("%s\t", commands[i].name); + printed++; + @} + + if (printed) + printf ("\n"); + @} + return (0); +@} + +/* Change to the directory ARG. */ +com_cd (arg) + char *arg; +@{ + if (chdir (arg) == -1) + @{ + perror (arg); + return 1; + @} + + com_pwd (""); + return (0); +@} + +/* Print out the current working directory. */ +com_pwd (ignore) + char *ignore; +@{ + char dir[1024], *s; + + s = getcwd (dir, sizeof(dir) - 1); + if (s == 0) + @{ + printf ("Error getting pwd: %s\n", dir); + return 1; + @} + + printf ("Current directory is %s\n", dir); + return 0; +@} + +/* The user wishes to quit using this program. Just set DONE non-zero. */ +com_quit (arg) + char *arg; +@{ + done = 1; + return (0); +@} + +/* Function which tells you that you can't do this. */ +too_dangerous (caller) + char *caller; +@{ + fprintf (stderr, + "%s: Too dangerous for me to distribute. Write it yourself.\n", + caller); +@} + +/* Return non-zero if ARG is a valid argument for CALLER, else print + an error message and return zero. */ +int +valid_argument (caller, arg) + char *caller, *arg; +@{ + if (!arg || !*arg) + @{ + fprintf (stderr, "%s: Argument required.\n", caller); + return (0); + @} + + return (1); +@} +@end smallexample diff -pruN 16.3-5/readline/readline/doc/rluser.texi 16.3-5ubuntu1/readline/readline/doc/rluser.texi --- 16.3-5/readline/readline/doc/rluser.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/rluser.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,2488 @@ +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rluser.info +@comment %**end of header (This is for running Texinfo on a region.) +@ignore +This file documents the end user interface to the GNU command line +editing features. It is to be an appendix to manuals for programs which +use these features. There is a document entitled "readline.texinfo" +which contains both end-user and programmer documentation for the +GNU Readline Library. + +Copyright (C) 1988--2022 Free Software Foundation, Inc. + +Authored by Brian Fox and Chet Ramey. + +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission notice +identical to this one except for the removal of this paragraph (this +paragraph not being relevant to the printed manual). + +Permission is granted to make and distribute verbatim copies of this manual +provided the copyright notice and this permission notice are preserved on +all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided also that the +GNU Copyright statement is available to the distributee, and provided that +the entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ignore + +@comment If you are including this manual as an appendix, then set the +@comment variable readline-appendix. + +@ifclear BashFeatures +@defcodeindex bt +@end ifclear + +@node Command Line Editing +@chapter Command Line Editing + +This chapter describes the basic features of the @sc{gnu} +command line editing interface. +@ifset BashFeatures +Command line editing is provided by the Readline library, which is +used by several different programs, including Bash. +Command line editing is enabled by default when using an interactive shell, +unless the @option{--noediting} option is supplied at shell invocation. +Line editing is also used when using the @option{-e} option to the +@code{read} builtin command (@pxref{Bash Builtins}). +By default, the line editing commands are similar to those of Emacs. +A vi-style line editing interface is also available. +Line editing can be enabled at any time using the @option{-o emacs} or +@option{-o vi} options to the @code{set} builtin command +(@pxref{The Set Builtin}), or disabled using the @option{+o emacs} or +@option{+o vi} options to @code{set}. +@end ifset + +@menu +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. +@ifset BashFeatures +* Programmable Completion:: How to specify the possible completions for + a specific command. +* Programmable Completion Builtins:: Builtin commands to specify how to + complete arguments for a particular command. +* A Programmable Completion Example:: An example shell function for + generating possible completions. +@end ifset +@end menu + +@node Introduction and Notation +@section Introduction to Line Editing + +The following paragraphs describe the notation used to represent +keystrokes. + +The text @kbd{C-k} is read as `Control-K' and describes the character +produced when the @key{k} key is pressed while the Control key +is depressed. + +The text @kbd{M-k} is read as `Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the @key{k} +key is pressed. +The Meta key is labeled @key{ALT} on many keyboards. +On keyboards with two keys labeled @key{ALT} (usually to either side of +the space bar), the @key{ALT} on the left side is generally set to +work as a Meta key. +The @key{ALT} key on the right may also be configured to work as a +Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + +If you do not have a Meta or @key{ALT} key, or another key working as +a Meta key, the identical keystroke can be generated by typing @key{ESC} +@emph{first}, and then typing @key{k}. +Either process is known as @dfn{metafying} the @key{k} key. + +The text @kbd{M-C-k} is read as `Meta-Control-k' and describes the +character produced by @dfn{metafying} @kbd{C-k}. + +In addition, several keys have their own names. Specifically, +@key{DEL}, @key{ESC}, @key{LFD}, @key{SPC}, @key{RET}, and @key{TAB} all +stand for themselves when seen in this text, or in an init file +(@pxref{Readline Init File}). +If your keyboard lacks a @key{LFD} key, typing @key{C-j} will +produce the desired character. +The @key{RET} key may be labeled @key{Return} or @key{Enter} on +some keyboards. + +@node Readline Interaction +@section Readline Interaction +@cindex interaction, readline + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press @key{RET}. You do not have to be at the +end of the line to press @key{RET}; the entire line is accepted +regardless of the location of the cursor within the line. + +@menu +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. +@end menu + +@node Readline Bare Essentials +@subsection Readline Bare Essentials +@cindex notation, readline +@cindex command editing +@cindex editing command lines + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your +erase character to back up and delete the mistyped character. + +Sometimes you may mistype a character, and +not notice the error until you have typed several other characters. In +that case, you can type @kbd{C-b} to move the cursor to the left, and then +correct your mistake. Afterwards, you can move the cursor to the right +with @kbd{C-f}. + +When you add text in the middle of a line, you will notice that characters +to the right of the cursor are `pushed over' to make room for the text +that you have inserted. Likewise, when you delete text behind the cursor, +characters to the right of the cursor are `pulled back' to fill in the +blank space created by the removal of the text. A list of the bare +essentials for editing the text of an input line follows. + +@table @asis +@item @kbd{C-b} +Move back one character. +@item @kbd{C-f} +Move forward one character. +@item @key{DEL} or @key{Backspace} +Delete the character to the left of the cursor. +@item @kbd{C-d} +Delete the character underneath the cursor. +@item @w{Printing characters} +Insert the character into the line at the cursor. +@item @kbd{C-_} or @kbd{C-x C-u} +Undo the last editing command. You can undo all the way back to an +empty line. +@end table + +@noindent +(Depending on your configuration, the @key{Backspace} key might be set to +delete the character to the left of the cursor and the @key{DEL} key set +to delete the character underneath the cursor, like @kbd{C-d}, rather +than the character to the left of the cursor.) + +@node Readline Movement Commands +@subsection Readline Movement Commands + + +The above table describes the most basic keystrokes that you need +in order to do editing of the input line. For your convenience, many +other commands have been added in addition to @kbd{C-b}, @kbd{C-f}, +@kbd{C-d}, and @key{DEL}. Here are some commands for moving more rapidly +about the line. + +@table @kbd +@item C-a +Move to the start of the line. +@item C-e +Move to the end of the line. +@item M-f +Move forward a word, where a word is composed of letters and digits. +@item M-b +Move backward a word. +@item C-l +Clear the screen, reprinting the current line at the top. +@end table + +Notice how @kbd{C-f} moves forward a character, while @kbd{M-f} moves +forward a word. It is a loose convention that control keystrokes +operate on characters while meta keystrokes operate on words. + +@node Readline Killing Commands +@subsection Readline Killing Commands + +@cindex killing text +@cindex yanking text + +@dfn{Killing} text means to delete the text from the line, but to save +it away for later use, usually by @dfn{yanking} (re-inserting) +it back into the line. +(`Cut' and `paste' are more recent jargon for `kill' and `yank'.) + +If the description for a command says that it `kills' text, then you can +be sure that you can get the text back in a different (or the same) +place later. + +When you use a kill command, the text is saved in a @dfn{kill-ring}. +Any number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill +ring is not line specific; the text that you killed on a previously +typed line is available to be yanked back later, when you are typing +another line. +@cindex kill ring + +Here is the list of commands for killing text. + +@table @kbd +@item C-k +Kill the text from the current cursor position to the end of the line. + +@item M-d +Kill from the cursor to the end of the current word, or, if between +words, to the end of the next word. +Word boundaries are the same as those used by @kbd{M-f}. + +@item M-@key{DEL} +Kill from the cursor to the start of the current word, or, if between +words, to the start of the previous word. +Word boundaries are the same as those used by @kbd{M-b}. + +@item C-w +Kill from the cursor to the previous whitespace. This is different than +@kbd{M-@key{DEL}} because the word boundaries differ. + +@end table + +Here is how to @dfn{yank} the text back into the line. Yanking +means to copy the most-recently-killed text from the kill buffer. + +@table @kbd +@item C-y +Yank the most recently killed text back into the buffer at the cursor. + +@item M-y +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is @kbd{C-y} or @kbd{M-y}. +@end table + +@node Readline Arguments +@subsection Readline Arguments + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the @i{sign} of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type @samp{M-- C-k}. + +The general way to pass numeric arguments to a command is to type meta +digits before the command. If the first `digit' typed is a minus +sign (@samp{-}), then the sign of the argument will be negative. Once +you have typed one meta digit to get the argument started, you can type +the remainder of the digits, and then the command. For example, to give +the @kbd{C-d} command an argument of 10, you could type @samp{M-1 0 C-d}, +which will delete the next ten characters on the input line. + +@node Searching +@subsection Searching for Commands in the History + +Readline provides commands for searching through the command history +@ifset BashFeatures +(@pxref{Bash History Facilities}) +@end ifset +for lines containing a specified string. +There are two search modes: @dfn{incremental} and @dfn{non-incremental}. + +Incremental searches begin before the user has finished typing the +search string. +As each character of the search string is typed, Readline displays +the next entry from the history matching the string typed so far. +An incremental search requires only as many characters as needed to +find the desired history entry. +To search backward in the history for a particular string, type +@kbd{C-r}. Typing @kbd{C-s} searches forward through the history. +The characters present in the value of the @code{isearch-terminators} variable +are used to terminate an incremental search. +If that variable has not been assigned a value, the @key{ESC} and +@kbd{C-J} characters will terminate an incremental search. +@kbd{C-g} will abort an incremental search and restore the original line. +When the search is terminated, the history entry containing the +search string becomes the current line. + +To find other matching entries in the history list, type @kbd{C-r} or +@kbd{C-s} as appropriate. +This will search backward or forward in the history for the next +entry matching the search string typed so far. +Any other key sequence bound to a Readline command will terminate +the search and execute that command. +For instance, a @key{RET} will terminate the search and accept +the line, thereby executing the command from the history list. +A movement command will terminate the search, make the last line found +the current line, and begin editing. + +Readline remembers the last incremental search string. If two +@kbd{C-r}s are typed without any intervening characters defining a new +search string, any remembered search string is used. + +Non-incremental searches read the entire search string before starting +to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + +@node Readline Init File +@section Readline Init File +@cindex initialization file, readline + +Although the Readline library comes with a set of Emacs-like +keybindings installed by default, it is possible to use a different set +of keybindings. +Any user can customize programs that use Readline by putting +commands in an @dfn{inputrc} file, +conventionally in their home directory. +The name of this +@ifset BashFeatures +file is taken from the value of the shell variable @env{INPUTRC}. If +@end ifset +@ifclear BashFeatures +file is taken from the value of the environment variable @env{INPUTRC}. If +@end ifclear +that variable is unset, the default is @file{~/.inputrc}. If that +file does not exist or cannot be read, the ultimate default is +@file{/etc/inputrc}. +@ifset BashFeatures +The @w{@code{bind}} builtin command can also be used to set Readline +keybindings and variables. +@xref{Bash Builtins}. +@end ifset + +When a program which uses the Readline library starts up, the +init file is read, and the key bindings are set. + +In addition, the @code{C-x C-r} command re-reads this init file, thus +incorporating any changes that you might have made to it. + +@menu +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. +@end menu + +@node Readline Init File Syntax +@subsection Readline Init File Syntax + +There are only a few basic constructs allowed in the +Readline init file. Blank lines are ignored. +Lines beginning with a @samp{#} are comments. +Lines beginning with a @samp{$} indicate conditional +constructs (@pxref{Conditional Init Constructs}). Other lines +denote variable settings and key bindings. + +@table @asis +@item Variable Settings +You can modify the run-time behavior of Readline by +altering the values of variables in Readline +using the @code{set} command within the init file. +The syntax is simple: + +@example +set @var{variable} @var{value} +@end example + +@noindent +Here, for example, is how to +change from the default Emacs-like key binding to use +@code{vi} line editing commands: + +@example +set editing-mode vi +@end example + +Variable names and values, where appropriate, are recognized without regard +to case. Unrecognized variable names are ignored. + +Boolean variables (those that can be set to on or off) are set to on if +the value is null or empty, @var{on} (case-insensitive), or 1. Any other +value results in the variable being set to off. + +@ifset BashFeatures +The @w{@code{bind -V}} command lists the current Readline variable names +and values. @xref{Bash Builtins}. +@end ifset + +A great deal of run-time behavior is changeable with the following +variables. + +@cindex variables, readline +@table @code + +@item active-region-start-color +@vindex active-region-start-color +A string variable that controls the text color and background when displaying +the text in the active region (see the description of +@code{enable-active-region} below). +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal before displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that puts the terminal in standout mode, +as obtained from the terminal's terminfo description. +A sample value might be @samp{\e[01;33m}. + +@item active-region-end-color +@vindex active-region-end-color +A string variable that "undoes" the effects of @code{active-region-start-color} +and restores "normal" terminal display appearance after displaying text +in the active region. +This string must not take up any physical character positions on the display, +so it should consist only of terminal escape sequences. +It is output to the terminal after displaying the text in the active region. +This variable is reset to the default value whenever the terminal type changes. +The default value is the string that restores the terminal from standout mode, +as obtained from the terminal's terminfo description. +A sample value might be @samp{\e[0m}. + +@item bell-style +@vindex bell-style +Controls what happens when Readline wants to ring the terminal bell. +If set to @samp{none}, Readline never rings the bell. If set to +@samp{visible}, Readline uses a visible bell if one is available. +If set to @samp{audible} (the default), Readline attempts to ring +the terminal's bell. + +@item bind-tty-special-chars +@vindex bind-tty-special-chars +If set to @samp{on} (the default), Readline attempts to bind the control +characters treated specially by the kernel's terminal driver to their +Readline equivalents. + +@item blink-matching-paren +@vindex blink-matching-paren +If set to @samp{on}, Readline attempts to briefly move the cursor to an +opening parenthesis when a closing parenthesis is inserted. The default +is @samp{off}. + +@item colored-completion-prefix +@vindex colored-completion-prefix +If set to @samp{on}, when listing completions, Readline displays the +common prefix of the set of possible completions using a different color. +The color definitions are taken from the value of the @env{LS_COLORS} +environment variable. +If there is a color definition in @env{LS_COLORS} for the custom suffix +@samp{readline-colored-completion-prefix}, Readline uses this color for +the common prefix instead of its default. +The default is @samp{off}. + +@item colored-stats +@vindex colored-stats +If set to @samp{on}, Readline displays possible completions using different +colors to indicate their file type. +The color definitions are taken from the value of the @env{LS_COLORS} +environment variable. +The default is @samp{off}. + +@item comment-begin +@vindex comment-begin +The string to insert at the beginning of the line when the +@code{insert-comment} command is executed. The default value +is @code{"#"}. + +@item completion-display-width +@vindex completion-display-width +The number of screen columns used to display possible matches +when performing completion. +The value is ignored if it is less than 0 or greater than the terminal +screen width. +A value of 0 will cause matches to be displayed one per line. +The default value is -1. + +@item completion-ignore-case +@vindex completion-ignore-case +If set to @samp{on}, Readline performs filename matching and completion +in a case-insensitive fashion. +The default value is @samp{off}. + +@item completion-map-case +@vindex completion-map-case +If set to @samp{on}, and @var{completion-ignore-case} is enabled, Readline +treats hyphens (@samp{-}) and underscores (@samp{_}) as equivalent when +performing case-insensitive filename matching and completion. +The default value is @samp{off}. + +@item completion-prefix-display-length +@vindex completion-prefix-display-length +The length in characters of the common prefix of a list of possible +completions that is displayed without modification. When set to a +value greater than zero, common prefixes longer than this value are +replaced with an ellipsis when displaying possible completions. + +@item completion-query-items +@vindex completion-query-items +The number of possible completions that determines when the user is +asked whether the list of possibilities should be displayed. +If the number of possible completions is greater than or equal to this value, +Readline will ask whether or not the user wishes to view them; +otherwise, they are simply listed. +This variable must be set to an integer value greater than or equal to zero. +A zero value means Readline should never ask; negative values are +treated as zero. +The default limit is @code{100}. + +@item convert-meta +@vindex convert-meta +If set to @samp{on}, Readline will convert characters with the +eighth bit set to an @sc{ascii} key sequence by stripping the eighth +bit and prefixing an @key{ESC} character, converting them to a +meta-prefixed key sequence. +The default value is @samp{on}, but +will be set to @samp{off} if the locale is one that contains +eight-bit characters. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item disable-completion +@vindex disable-completion +If set to @samp{On}, Readline will inhibit word completion. +Completion characters will be inserted into the line as if they had +been mapped to @code{self-insert}. The default is @samp{off}. + +@item echo-control-characters +@vindex echo-control-characters +When set to @samp{on}, on operating systems that indicate they support it, +Readline echoes a character corresponding to a signal generated from the +keyboard. The default is @samp{on}. + +@item editing-mode +@vindex editing-mode +The @code{editing-mode} variable controls which default set of +key bindings is used. By default, Readline starts up in Emacs editing +mode, where the keystrokes are most similar to Emacs. This variable can be +set to either @samp{emacs} or @samp{vi}. + +@item emacs-mode-string +@vindex emacs-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when emacs editing mode is active. The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{@@}. + +@item enable-active-region +@vindex enable-active-region +The @dfn{point} is the current cursor position, and @dfn{mark} refers +to a saved cursor position (@pxref{Commands For Moving}). +The text between the point and mark is referred to as the @dfn{region}. +When this variable is set to @samp{On}, Readline allows certain commands +to designate the region as @dfn{active}. +When the region is active, Readline highlights the text in the region using +the value of the @code{active-region-start-color}, which defaults to the +string that enables +the terminal's standout mode. +The active region shows the text inserted by bracketed-paste and any +matching text found by incremental and non-incremental history searches. +The default is @samp{On}. + +@item enable-bracketed-paste +@vindex enable-bracketed-paste +When set to @samp{On}, Readline configures the terminal to insert each +paste into the editing buffer as a single string of characters, instead +of treating each character as if it had been read from the keyboard. +This is called putting the terminal into @dfn{bracketed paste mode}; +it prevents Readline from executing any editing commands bound to key +sequences appearing in the pasted text. +The default is @samp{On}. + +@item enable-keypad +@vindex enable-keypad +When set to @samp{on}, Readline will try to enable the application +keypad when it is called. Some systems need this to enable the +arrow keys. The default is @samp{off}. + +@item enable-meta-key +When set to @samp{on}, Readline will try to enable any meta modifier +key the terminal claims to support when it is called. On many terminals, +the meta key is used to send eight-bit characters. +The default is @samp{on}. + +@item expand-tilde +@vindex expand-tilde +If set to @samp{on}, tilde expansion is performed when Readline +attempts word completion. The default is @samp{off}. + +@item history-preserve-point +@vindex history-preserve-point +If set to @samp{on}, the history code attempts to place the point (the +current cursor position) at the +same location on each history line retrieved with @code{previous-history} +or @code{next-history}. The default is @samp{off}. + +@item history-size +@vindex history-size +Set the maximum number of history entries saved in the history list. +If set to zero, any existing history entries are deleted and no new entries +are saved. +If set to a value less than zero, the number of history entries is not +limited. +By default, the number of history entries is not limited. +If an attempt is made to set @var{history-size} to a non-numeric value, +the maximum number of history entries will be set to 500. + +@item horizontal-scroll-mode +@vindex horizontal-scroll-mode +This variable can be set to either @samp{on} or @samp{off}. Setting it +to @samp{on} means that the text of the lines being edited will scroll +horizontally on a single screen line when they are longer than the width +of the screen, instead of wrapping onto a new screen line. +This variable is automatically set to @samp{on} for terminals of height 1. +By default, this variable is set to @samp{off}. + +@item input-meta +@vindex input-meta +@vindex meta-flag +If set to @samp{on}, Readline will enable eight-bit input (it +will not clear the eighth bit in the characters it reads), +regardless of what the terminal claims it can support. The +default value is @samp{off}, but Readline will set it to @samp{on} if the +locale contains eight-bit characters. +The name @code{meta-flag} is a synonym for this variable. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item isearch-terminators +@vindex isearch-terminators +The string of characters that should terminate an incremental search without +subsequently executing the character as a command (@pxref{Searching}). +If this variable has not been given a value, the characters @key{ESC} and +@kbd{C-J} will terminate an incremental search. + +@item keymap +@vindex keymap +Sets Readline's idea of the current keymap for key binding commands. +Built-in @code{keymap} names are +@code{emacs}, +@code{emacs-standard}, +@code{emacs-meta}, +@code{emacs-ctlx}, +@code{vi}, +@code{vi-move}, +@code{vi-command}, and +@code{vi-insert}. +@code{vi} is equivalent to @code{vi-command} (@code{vi-move} is also a +synonym); @code{emacs} is equivalent to @code{emacs-standard}. +Applications may add additional names. +The default value is @code{emacs}. +The value of the @code{editing-mode} variable also affects the +default keymap. + +@item keyseq-timeout +Specifies the duration Readline will wait for a character when reading an +ambiguous key sequence (one that can form a complete key sequence using +the input read so far, or can take additional input to complete a longer +key sequence). +If no input is received within the timeout, Readline will use the shorter +but complete key sequence. +Readline uses this value to determine whether or not input is +available on the current input source (@code{rl_instream} by default). +The value is specified in milliseconds, so a value of 1000 means that +Readline will wait one second for additional input. +If this variable is set to a value less than or equal to zero, or to a +non-numeric value, Readline will wait until another key is pressed to +decide which key sequence to complete. +The default value is @code{500}. + +@item mark-directories +If set to @samp{on}, completed directory names have a slash +appended. The default is @samp{on}. + +@item mark-modified-lines +@vindex mark-modified-lines +This variable, when set to @samp{on}, causes Readline to display an +asterisk (@samp{*}) at the start of history lines which have been modified. +This variable is @samp{off} by default. + +@item mark-symlinked-directories +@vindex mark-symlinked-directories +If set to @samp{on}, completed names which are symbolic links +to directories have a slash appended (subject to the value of +@code{mark-directories}). +The default is @samp{off}. + +@item match-hidden-files +@vindex match-hidden-files +This variable, when set to @samp{on}, causes Readline to match files whose +names begin with a @samp{.} (hidden files) when performing filename +completion. +If set to @samp{off}, the leading @samp{.} must be +supplied by the user in the filename to be completed. +This variable is @samp{on} by default. + +@item menu-complete-display-prefix +@vindex menu-complete-display-prefix +If set to @samp{on}, menu completion displays the common prefix of the +list of possible completions (which may be empty) before cycling through +the list. The default is @samp{off}. + +@item output-meta +@vindex output-meta +If set to @samp{on}, Readline will display characters with the +eighth bit set directly rather than as a meta-prefixed escape +sequence. +The default is @samp{off}, but Readline will set it to @samp{on} if the +locale contains eight-bit characters. +This variable is dependent on the @code{LC_CTYPE} locale category, and +may change if the locale is changed. + +@item page-completions +@vindex page-completions +If set to @samp{on}, Readline uses an internal @code{more}-like pager +to display a screenful of possible completions at a time. +This variable is @samp{on} by default. + +@item print-completions-horizontally +If set to @samp{on}, Readline will display completions with matches +sorted horizontally in alphabetical order, rather than down the screen. +The default is @samp{off}. + +@item revert-all-at-newline +@vindex revert-all-at-newline +If set to @samp{on}, Readline will undo all changes to history lines +before returning when @code{accept-line} is executed. By default, +history lines may be modified and retain individual undo lists across +calls to @code{readline()}. The default is @samp{off}. + +@item show-all-if-ambiguous +@vindex show-all-if-ambiguous +This alters the default behavior of the completion functions. If +set to @samp{on}, +words which have more than one possible completion cause the +matches to be listed immediately instead of ringing the bell. +The default value is @samp{off}. + +@item show-all-if-unmodified +@vindex show-all-if-unmodified +This alters the default behavior of the completion functions in +a fashion similar to @var{show-all-if-ambiguous}. +If set to @samp{on}, +words which have more than one possible completion without any +possible partial completion (the possible completions don't share +a common prefix) cause the matches to be listed immediately instead +of ringing the bell. +The default value is @samp{off}. + +@item show-mode-in-prompt +@vindex show-mode-in-prompt +If set to @samp{on}, add a string to the beginning of the prompt +indicating the editing mode: emacs, vi command, or vi insertion. +The mode strings are user-settable (e.g., @var{emacs-mode-string}). +The default value is @samp{off}. + +@item skip-completed-text +@vindex skip-completed-text +If set to @samp{on}, this alters the default completion behavior when +inserting a single match into the line. It's only active when +performing completion in the middle of a word. If enabled, Readline +does not insert characters from the completion that match characters +after point in the word being completed, so portions of the word +following the cursor are not duplicated. +For instance, if this is enabled, attempting completion when the cursor +is after the @samp{e} in @samp{Makefile} will result in @samp{Makefile} +rather than @samp{Makefilefile}, assuming there is a single possible +completion. +The default value is @samp{off}. + +@item vi-cmd-mode-string +@vindex vi-cmd-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in command mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{(cmd)}. + +@item vi-ins-mode-string +@vindex vi-ins-mode-string +If the @var{show-mode-in-prompt} variable is enabled, +this string is displayed immediately before the last line of the primary +prompt when vi editing mode is active and in insertion mode. +The value is expanded like a +key binding, so the standard set of meta- and control prefixes and +backslash escape sequences is available. +Use the @samp{\1} and @samp{\2} escapes to begin and end sequences of +non-printing characters, which can be used to embed a terminal control +sequence into the mode string. +The default is @samp{(ins)}. + +@item visible-stats +@vindex visible-stats +If set to @samp{on}, a character denoting a file's type +is appended to the filename when listing possible +completions. The default is @samp{off}. + +@end table + +@item Key Bindings +The syntax for controlling key bindings in the init file is +simple. First you need to find the name of the command that you +want to change. The following sections contain tables of the command +name, the default keybinding, if any, and a short description of what +the command does. + +Once you know the name of the command, simply place on a line +in the init file the name of the key +you wish to bind the command to, a colon, and then the name of the +command. +There can be no space between the key name and the colon -- that will be +interpreted as part of the key name. +The name of the key can be expressed in different ways, depending on +what you find most comfortable. + +In addition to command names, Readline allows keys to be bound +to a string that is inserted when the key is pressed (a @var{macro}). + +@ifset BashFeatures +The @w{@code{bind -p}} command displays Readline function names and +bindings in a format that can be put directly into an initialization file. +@xref{Bash Builtins}. +@end ifset + +@table @asis +@item @w{@var{keyname}: @var{function-name} or @var{macro}} +@var{keyname} is the name of a key spelled out in English. For example: +@example +Control-u: universal-argument +Meta-Rubout: backward-kill-word +Control-o: "> output" +@end example + +In the example above, @kbd{C-u} is bound to the function +@code{universal-argument}, +@kbd{M-DEL} is bound to the function @code{backward-kill-word}, and +@kbd{C-o} is bound to run the macro +expressed on the right hand side (that is, to insert the text +@samp{> output} into the line). + +A number of symbolic character names are recognized while +processing this key binding syntax: +@var{DEL}, +@var{ESC}, +@var{ESCAPE}, +@var{LFD}, +@var{NEWLINE}, +@var{RET}, +@var{RETURN}, +@var{RUBOUT}, +@var{SPACE}, +@var{SPC}, +and +@var{TAB}. + +@item @w{"@var{keyseq}": @var{function-name} or @var{macro}} +@var{keyseq} differs from @var{keyname} above in that strings +denoting an entire key sequence can be specified, by placing +the key sequence in double quotes. Some @sc{gnu} Emacs style key +escapes can be used, as in the following example, but the +special character names are not recognized. + +@example +"\C-u": universal-argument +"\C-x\C-r": re-read-init-file +"\e[11~": "Function Key 1" +@end example + +In the above example, @kbd{C-u} is again bound to the function +@code{universal-argument} (just as it was in the first example), +@samp{@kbd{C-x} @kbd{C-r}} is bound to the function @code{re-read-init-file}, +and @samp{@key{ESC} @key{[} @key{1} @key{1} @key{~}} is bound to insert +the text @samp{Function Key 1}. + +@end table + +The following @sc{gnu} Emacs style escape sequences are available when +specifying key sequences: + +@table @code +@item @kbd{\C-} +control prefix +@item @kbd{\M-} +meta prefix +@item @kbd{\e} +an escape character +@item @kbd{\\} +backslash +@item @kbd{\"} +@key{"}, a double quotation mark +@item @kbd{\'} +@key{'}, a single quote or apostrophe +@end table + +In addition to the @sc{gnu} Emacs style escape sequences, a second +set of backslash escapes is available: + +@table @code +@item \a +alert (bell) +@item \b +backspace +@item \d +delete +@item \f +form feed +@item \n +newline +@item \r +carriage return +@item \t +horizontal tab +@item \v +vertical tab +@item \@var{nnn} +the eight-bit character whose value is the octal value @var{nnn} +(one to three digits) +@item \x@var{HH} +the eight-bit character whose value is the hexadecimal value @var{HH} +(one or two hex digits) +@end table + +When entering the text of a macro, single or double quotes must +be used to indicate a macro definition. +Unquoted text is assumed to be a function name. +In the macro body, the backslash escapes described above are expanded. +Backslash will quote any other character in the macro text, +including @samp{"} and @samp{'}. +For example, the following binding will make @samp{@kbd{C-x} \} +insert a single @samp{\} into the line: +@example +"\C-x\\": "\\" +@end example + +@end table + +@node Conditional Init Constructs +@subsection Conditional Init Constructs + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key +bindings and variable settings to be performed as the result +of tests. There are four parser directives used. + +@table @code +@item $if +The @code{$if} construct allows bindings to be made based on the +editing mode, the terminal being used, or the application using +Readline. The text of the test, after any comparison operator, +extends to the end of the line; +unless otherwise noted, no characters are required to isolate it. + +@table @code +@item mode +The @code{mode=} form of the @code{$if} directive is used to test +whether Readline is in @code{emacs} or @code{vi} mode. +This may be used in conjunction +with the @samp{set keymap} command, for instance, to set bindings in +the @code{emacs-standard} and @code{emacs-ctlx} keymaps only if +Readline is starting out in @code{emacs} mode. + +@item term +The @code{term=} form may be used to include terminal-specific +key bindings, perhaps to bind the key sequences output by the +terminal's function keys. The word on the right side of the +@samp{=} is tested against both the full name of the terminal and +the portion of the terminal name before the first @samp{-}. This +allows @code{sun} to match both @code{sun} and @code{sun-cmd}, +for instance. + +@item version +The @code{version} test may be used to perform comparisons against +specific Readline versions. +The @code{version} expands to the current Readline version. +The set of comparison operators includes +@samp{=} (and @samp{==}), @samp{!=}, @samp{<=}, @samp{>=}, @samp{<}, +and @samp{>}. +The version number supplied on the right side of the operator consists +of a major version number, an optional decimal point, and an optional +minor version (e.g., @samp{7.1}). If the minor version is omitted, it +is assumed to be @samp{0}. +The operator may be separated from the string @code{version} and +from the version number argument by whitespace. +The following example sets a variable if the Readline version being used +is 7.0 or newer: +@example +$if version >= 7.0 +set show-mode-in-prompt on +$endif +@end example + +@item application +The @var{application} construct is used to include +application-specific settings. Each program using the Readline +library sets the @var{application name}, and you can test for +a particular value. +This could be used to bind key sequences to functions useful for +a specific program. For instance, the following command adds a +key sequence that quotes the current or previous word in Bash: +@example +$if Bash +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +$endif +@end example + +@item variable +The @var{variable} construct provides simple equality tests for Readline +variables and values. +The permitted comparison operators are @samp{=}, @samp{==}, and @samp{!=}. +The variable name must be separated from the comparison operator by +whitespace; the operator may be separated from the value on the right hand +side by whitespace. +Both string and boolean variables may be tested. Boolean variables must be +tested against the values @var{on} and @var{off}. +The following example is equivalent to the @code{mode=emacs} test described +above: +@example +$if editing-mode == emacs +set show-mode-in-prompt on +$endif +@end example +@end table + +@item $endif +This command, as seen in the previous example, terminates an +@code{$if} command. + +@item $else +Commands in this branch of the @code{$if} directive are executed if +the test fails. + +@item $include +This directive takes a single filename as an argument and reads commands +and bindings from that file. +For example, the following directive reads from @file{/etc/inputrc}: +@example +$include /etc/inputrc +@end example +@end table + +@node Sample Init File +@subsection Sample Init File + +Here is an example of an @var{inputrc} file. This illustrates key +binding, variable assignment, and conditional syntax. + +@example +@page +# This file controls the behaviour of line input editing for +# programs that use the GNU Readline library. Existing +# programs include FTP, Bash, and GDB. +# +# You can re-read the inputrc file with C-x C-r. +# Lines beginning with '#' are comments. +# +# First, include any system-wide bindings and variable +# assignments from /etc/Inputrc +$include /etc/Inputrc + +# +# Set various bindings for emacs mode. + +set editing-mode emacs + +$if mode=emacs + +Meta-Control-h: backward-kill-word Text after the function name is ignored + +# +# Arrow keys in keypad mode +# +#"\M-OD": backward-char +#"\M-OC": forward-char +#"\M-OA": previous-history +#"\M-OB": next-history +# +# Arrow keys in ANSI mode +# +"\M-[D": backward-char +"\M-[C": forward-char +"\M-[A": previous-history +"\M-[B": next-history +# +# Arrow keys in 8 bit keypad mode +# +#"\M-\C-OD": backward-char +#"\M-\C-OC": forward-char +#"\M-\C-OA": previous-history +#"\M-\C-OB": next-history +# +# Arrow keys in 8 bit ANSI mode +# +#"\M-\C-[D": backward-char +#"\M-\C-[C": forward-char +#"\M-\C-[A": previous-history +#"\M-\C-[B": next-history + +C-q: quoted-insert + +$endif + +# An old-style binding. This happens to be the default. +TAB: complete + +# Macros that are convenient for shell interaction +$if Bash +# edit the path +"\C-xp": "PATH=$@{PATH@}\e\C-e\C-a\ef\C-f" +# prepare to type a quoted word -- +# insert open and close double quotes +# and move to just after the open quote +"\C-x\"": "\"\"\C-b" +# insert a backslash (testing backslash escapes +# in sequences and macros) +"\C-x\\": "\\" +# Quote the current or previous word +"\C-xq": "\eb\"\ef\"" +# Add a binding to refresh the line, which is unbound +"\C-xr": redraw-current-line +# Edit variable on current line. +"\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" +$endif + +# use a visible bell if one is available +set bell-style visible + +# don't strip characters to 7 bits when reading +set input-meta on + +# allow iso-latin1 characters to be inserted rather +# than converted to prefix-meta sequences +set convert-meta off + +# display characters with the eighth bit set directly +# rather than as meta-prefixed characters +set output-meta on + +# if there are 150 or more possible completions for a word, +# ask whether or not the user wants to see all of them +set completion-query-items 150 + +# For FTP +$if Ftp +"\C-xg": "get \M-?" +"\C-xt": "put \M-?" +"\M-.": yank-last-arg +$endif +@end example + +@node Bindable Readline Commands +@section Bindable Readline Commands + +@menu +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. +@end menu + +This section describes Readline commands that may be bound to key +sequences. +@ifset BashFeatures +You can list your key bindings by executing +@w{@code{bind -P}} or, for a more terse format, suitable for an +@var{inputrc} file, @w{@code{bind -p}}. (@xref{Bash Builtins}.) +@end ifset +Command names without an accompanying key sequence are unbound by default. + +In the following descriptions, @dfn{point} refers to the current cursor +position, and @dfn{mark} refers to a cursor position saved by the +@code{set-mark} command. +The text between the point and mark is referred to as the @dfn{region}. + +@node Commands For Moving +@subsection Commands For Moving +@ftable @code +@item beginning-of-line (C-a) +Move to the start of the current line. + +@item end-of-line (C-e) +Move to the end of the line. + +@item forward-char (C-f) +Move forward a character. + +@item backward-char (C-b) +Move back a character. + +@item forward-word (M-f) +Move forward to the end of the next word. +Words are composed of letters and digits. + +@item backward-word (M-b) +Move back to the start of the current or previous word. +Words are composed of letters and digits. + +@ifset BashFeatures +@item shell-forward-word (M-C-f) +Move forward to the end of the next word. +Words are delimited by non-quoted shell metacharacters. + +@item shell-backward-word (M-C-b) +Move back to the start of the current or previous word. +Words are delimited by non-quoted shell metacharacters. +@end ifset + +@item previous-screen-line () +Attempt to move point to the same physical screen column on the previous +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if point is not +greater than the length of the prompt plus the screen width. + +@item next-screen-line () +Attempt to move point to the same physical screen column on the next +physical screen line. This will not have the desired effect if the current +Readline line does not take up more than one physical line or if the length +of the current Readline line is not greater than the length of the prompt +plus the screen width. + +@item clear-display (M-C-l) +Clear the screen and, if possible, the terminal's scrollback buffer, +then redraw the current line, +leaving the current line at the top of the screen. + +@item clear-screen (C-l) +Clear the screen, +then redraw the current line, +leaving the current line at the top of the screen. + +@item redraw-current-line () +Refresh the current line. By default, this is unbound. + +@end ftable + +@node Commands For History +@subsection Commands For Manipulating The History + +@ftable @code +@item accept-line (Newline or Return) +@ifset BashFeatures +Accept the line regardless of where the cursor is. +If this line is +non-empty, add it to the history list according to the setting of +the @env{HISTCONTROL} and @env{HISTIGNORE} variables. +If this line is a modified history line, then restore the history line +to its original state. +@end ifset +@ifclear BashFeatures +Accept the line regardless of where the cursor is. +If this line is +non-empty, it may be added to the history list for future recall with +@code{add_history()}. +If this line is a modified history line, the history line is restored +to its original state. +@end ifclear + +@item previous-history (C-p) +Move `back' through the history list, fetching the previous command. + +@item next-history (C-n) +Move `forward' through the history list, fetching the next command. + +@item beginning-of-history (M-<) +Move to the first line in the history. + +@item end-of-history (M->) +Move to the end of the input history, i.e., the line currently +being entered. + +@item reverse-search-history (C-r) +Search backward starting at the current line and moving `up' through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. + +@item forward-search-history (C-s) +Search forward starting at the current line and moving `down' through +the history as necessary. This is an incremental search. +This command sets the region to the matched text and activates the mark. + +@item non-incremental-reverse-search-history (M-p) +Search backward starting at the current line and moving `up' +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. + +@item non-incremental-forward-search-history (M-n) +Search forward starting at the current line and moving `down' +through the history as necessary using a non-incremental search +for a string supplied by the user. +The search string may match anywhere in a history line. + +@item history-search-forward () +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-search-backward () +Search backward through the history for the string of characters +between the start of the current line and the point. +The search string must match at the beginning of a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-substring-search-forward () +Search forward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item history-substring-search-backward () +Search backward through the history for the string of characters +between the start of the current line and the point. +The search string may match anywhere in a history line. +This is a non-incremental search. +By default, this command is unbound. + +@item yank-nth-arg (M-C-y) +Insert the first argument to the previous command (usually +the second word on the previous line) at point. +With an argument @var{n}, +insert the @var{n}th word from the previous command (the words +in the previous command begin with word 0). A negative argument +inserts the @var{n}th word from the end of the previous command. +Once the argument @var{n} is computed, the argument is extracted +as if the @samp{!@var{n}} history expansion had been specified. + +@item yank-last-arg (M-. or M-_) +Insert last argument to the previous command (the last word of the +previous history entry). +With a numeric argument, behave exactly like @code{yank-nth-arg}. +Successive calls to @code{yank-last-arg} move back through the history +list, inserting the last word (or the word specified by the argument to +the first call) of each line in turn. +Any numeric argument supplied to these successive calls determines +the direction to move through the history. A negative argument switches +the direction through the history (back or forward). +The history expansion facilities are used to extract the last argument, +as if the @samp{!$} history expansion had been specified. + +@item operate-and-get-next (C-o) +Accept the current line for return to the calling application as if a +newline had been entered, +and fetch the next line relative to the current line from the history +for editing. +A numeric argument, if supplied, specifies the history entry to use instead +of the current line. + +@item fetch-history () +With a numeric argument, fetch that entry from the history list +and make it the current line. +Without an argument, move back to the first entry in the history list. + +@end ftable + +@node Commands For Text +@subsection Commands For Changing Text + +@ftable @code + +@item @i{end-of-file} (usually C-d) +The character indicating end-of-file as set, for example, by +@code{stty}. If this character is read when there are no characters +on the line, and point is at the beginning of the line, Readline +interprets it as the end of input and returns @sc{eof}. + +@item delete-char (C-d) +Delete the character at point. If this function is bound to the +same character as the tty @sc{eof} character, as @kbd{C-d} +commonly is, see above for the effects. + +@item backward-delete-char (Rubout) +Delete the character behind the cursor. A numeric argument means +to kill the characters instead of deleting them. + +@item forward-backward-delete-char () +Delete the character under the cursor, unless the cursor is at the +end of the line, in which case the character behind the cursor is +deleted. By default, this is not bound to a key. + +@item quoted-insert (C-q or C-v) +Add the next character typed to the line verbatim. This is +how to insert key sequences like @kbd{C-q}, for example. + +@ifclear BashFeatures +@item tab-insert (M-@key{TAB}) +Insert a tab character. +@end ifclear + +@item self-insert (a, b, A, 1, !, @dots{}) +Insert yourself. + +@item bracketed-paste-begin () +This function is intended to be bound to the "bracketed paste" escape +sequence sent by some terminals, and such a binding is assigned by default. +It allows Readline to insert the pasted text as a single unit without treating +each character as if it had been read from the keyboard. The characters +are inserted as if each one was bound to @code{self-insert} instead of +executing any editing commands. + +Bracketed paste sets the region (the characters between point and the mark) +to the inserted text. It uses the concept of an @emph{active mark}: when the +mark is active, Readline redisplay uses the terminal's standout mode to +denote the region. + +@item transpose-chars (C-t) +Drag the character before the cursor forward over +the character at the cursor, moving the +cursor forward as well. If the insertion point +is at the end of the line, then this +transposes the last two characters of the line. +Negative arguments have no effect. + +@item transpose-words (M-t) +Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. + +@item upcase-word (M-u) +Uppercase the current (or following) word. With a negative argument, +uppercase the previous word, but do not move the cursor. + +@item downcase-word (M-l) +Lowercase the current (or following) word. With a negative argument, +lowercase the previous word, but do not move the cursor. + +@item capitalize-word (M-c) +Capitalize the current (or following) word. With a negative argument, +capitalize the previous word, but do not move the cursor. + +@item overwrite-mode () +Toggle overwrite mode. With an explicit positive numeric argument, +switches to overwrite mode. With an explicit non-positive numeric +argument, switches to insert mode. This command affects only +@code{emacs} mode; @code{vi} mode does overwrite differently. +Each call to @code{readline()} starts in insert mode. + +In overwrite mode, characters bound to @code{self-insert} replace +the text at point rather than pushing the text to the right. +Characters bound to @code{backward-delete-char} replace the character +before point with a space. + +By default, this command is unbound. + +@end ftable + +@node Commands For Killing +@subsection Killing And Yanking + +@ftable @code + +@item kill-line (C-k) +Kill the text from point to the end of the line. +With a negative numeric argument, kill backward from the cursor to the +beginning of the current line. + +@item backward-kill-line (C-x Rubout) +Kill backward from the cursor to the beginning of the current line. +With a negative numeric argument, kill forward from the cursor to the +end of the current line. + +@item unix-line-discard (C-u) +Kill backward from the cursor to the beginning of the current line. + +@item kill-whole-line () +Kill all characters on the current line, no matter where point is. +By default, this is unbound. + +@item kill-word (M-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as @code{forward-word}. + +@item backward-kill-word (M-@key{DEL}) +Kill the word behind point. +Word boundaries are the same as @code{backward-word}. + +@ifset BashFeatures +@item shell-kill-word (M-C-d) +Kill from point to the end of the current word, or if between +words, to the end of the next word. +Word boundaries are the same as @code{shell-forward-word}. + +@item shell-backward-kill-word () +Kill the word behind point. +Word boundaries are the same as @code{shell-backward-word}. +@end ifset + +@item shell-transpose-words (M-C-t) +Drag the word before point past the word after point, +moving point past that word as well. +If the insertion point is at the end of the line, this transposes +the last two words on the line. +Word boundaries are the same as @code{shell-forward-word} and +@code{shell-backward-word}. + +@item unix-word-rubout (C-w) +Kill the word behind point, using white space as a word boundary. +The killed text is saved on the kill-ring. + +@item unix-filename-rubout () +Kill the word behind point, using white space and the slash character +as the word boundaries. +The killed text is saved on the kill-ring. + +@item delete-horizontal-space () +Delete all spaces and tabs around point. By default, this is unbound. + +@item kill-region () +Kill the text in the current region. +By default, this command is unbound. + +@item copy-region-as-kill () +Copy the text in the region to the kill buffer, so it can be yanked +right away. By default, this command is unbound. + +@item copy-backward-word () +Copy the word before point to the kill buffer. +The word boundaries are the same as @code{backward-word}. +By default, this command is unbound. + +@item copy-forward-word () +Copy the word following point to the kill buffer. +The word boundaries are the same as @code{forward-word}. +By default, this command is unbound. + +@item yank (C-y) +Yank the top of the kill ring into the buffer at point. + +@item yank-pop (M-y) +Rotate the kill-ring, and yank the new top. You can only do this if +the prior command is @code{yank} or @code{yank-pop}. +@end ftable + +@node Numeric Arguments +@subsection Specifying Numeric Arguments +@ftable @code + +@item digit-argument (@kbd{M-0}, @kbd{M-1}, @dots{} @kbd{M--}) +Add this digit to the argument already accumulating, or start a new +argument. @kbd{M--} starts a negative argument. + +@item universal-argument () +This is another way to specify an argument. +If this command is followed by one or more digits, optionally with a +leading minus sign, those digits define the argument. +If the command is followed by digits, executing @code{universal-argument} +again ends the numeric argument, but is otherwise ignored. +As a special case, if this command is immediately followed by a +character that is neither a digit nor minus sign, the argument count +for the next command is multiplied by four. +The argument count is initially one, so executing this function the +first time makes the argument count four, a second time makes the +argument count sixteen, and so on. +By default, this is not bound to a key. +@end ftable + +@node Commands For Completion +@subsection Letting Readline Type For You + +@ftable @code +@item complete (@key{TAB}) +Attempt to perform completion on the text before point. +The actual completion performed is application-specific. +@ifset BashFeatures +Bash attempts completion treating the text as a variable (if the +text begins with @samp{$}), username (if the text begins with +@samp{~}), hostname (if the text begins with @samp{@@}), or +command (including aliases and functions) in turn. If none +of these produces a match, filename completion is attempted. +@end ifset +@ifclear BashFeatures +The default is filename completion. +@end ifclear + +@item possible-completions (M-?) +List the possible completions of the text before point. +When displaying completions, Readline sets the number of columns used +for display to the value of @code{completion-display-width}, the value of +the environment variable @env{COLUMNS}, or the screen width, in that order. + +@item insert-completions (M-*) +Insert all completions of the text before point that would have +been generated by @code{possible-completions}. + +@item menu-complete () +Similar to @code{complete}, but replaces the word to be completed +with a single match from the list of possible completions. +Repeated execution of @code{menu-complete} steps through the list +of possible completions, inserting each match in turn. +At the end of the list of completions, the bell is rung +(subject to the setting of @code{bell-style}) +and the original text is restored. +An argument of @var{n} moves @var{n} positions forward in the list +of matches; a negative argument may be used to move backward +through the list. +This command is intended to be bound to @key{TAB}, but is unbound +by default. + +@item menu-complete-backward () +Identical to @code{menu-complete}, but moves backward through the list +of possible completions, as if @code{menu-complete} had been given a +negative argument. + +@item delete-char-or-list () +Deletes the character under the cursor if not at the beginning or +end of the line (like @code{delete-char}). +If at the end of the line, behaves identically to +@code{possible-completions}. +This command is unbound by default. + +@ifset BashFeatures +@item complete-filename (M-/) +Attempt filename completion on the text before point. + +@item possible-filename-completions (C-x /) +List the possible completions of the text before point, +treating it as a filename. + +@item complete-username (M-~) +Attempt completion on the text before point, treating +it as a username. + +@item possible-username-completions (C-x ~) +List the possible completions of the text before point, +treating it as a username. + +@item complete-variable (M-$) +Attempt completion on the text before point, treating +it as a shell variable. + +@item possible-variable-completions (C-x $) +List the possible completions of the text before point, +treating it as a shell variable. + +@item complete-hostname (M-@@) +Attempt completion on the text before point, treating +it as a hostname. + +@item possible-hostname-completions (C-x @@) +List the possible completions of the text before point, +treating it as a hostname. + +@item complete-command (M-!) +Attempt completion on the text before point, treating +it as a command name. Command completion attempts to +match the text against aliases, reserved words, shell +functions, shell builtins, and finally executable filenames, +in that order. + +@item possible-command-completions (C-x !) +List the possible completions of the text before point, +treating it as a command name. + +@item dynamic-complete-history (M-@key{TAB}) +Attempt completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. + +@item dabbrev-expand () +Attempt menu completion on the text before point, comparing +the text against lines from the history list for possible +completion matches. + +@item complete-into-braces (M-@{) +Perform filename completion and insert the list of possible completions +enclosed within braces so the list is available to the shell +(@pxref{Brace Expansion}). + +@end ifset +@end ftable + +@node Keyboard Macros +@subsection Keyboard Macros +@ftable @code + +@item start-kbd-macro (C-x () +Begin saving the characters typed into the current keyboard macro. + +@item end-kbd-macro (C-x )) +Stop saving the characters typed into the current keyboard macro +and save the definition. + +@item call-last-kbd-macro (C-x e) +Re-execute the last keyboard macro defined, by making the characters +in the macro appear as if typed at the keyboard. + +@item print-last-kbd-macro () +Print the last keyboard macro defined in a format suitable for the +@var{inputrc} file. + +@end ftable + +@node Miscellaneous Commands +@subsection Some Miscellaneous Commands +@ftable @code + +@item re-read-init-file (C-x C-r) +Read in the contents of the @var{inputrc} file, and incorporate +any bindings or variable assignments found there. + +@item abort (C-g) +Abort the current editing command and +ring the terminal's bell (subject to the setting of +@code{bell-style}). + +@item do-lowercase-version (M-A, M-B, M-@var{x}, @dots{}) +If the metafied character @var{x} is upper case, run the command +that is bound to the corresponding metafied lower case character. +The behavior is undefined if @var{x} is already lower case. + +@item prefix-meta (@key{ESC}) +Metafy the next character typed. This is for keyboards +without a meta key. Typing @samp{@key{ESC} f} is equivalent to typing +@kbd{M-f}. + +@item undo (C-_ or C-x C-u) +Incremental undo, separately remembered for each line. + +@item revert-line (M-r) +Undo all changes made to this line. This is like executing the @code{undo} +command enough times to get back to the beginning. + +@ifset BashFeatures +@item tilde-expand (M-&) +@end ifset +@ifclear BashFeatures +@item tilde-expand (M-~) +@end ifclear +Perform tilde expansion on the current word. + +@item set-mark (C-@@) +Set the mark to the point. If a +numeric argument is supplied, the mark is set to that position. + +@item exchange-point-and-mark (C-x C-x) +Swap the point with the mark. The current cursor position is set to +the saved position, and the old cursor position is saved as the mark. + +@item character-search (C-]) +A character is read and point is moved to the next occurrence of that +character. A negative argument searches for previous occurrences. + +@item character-search-backward (M-C-]) +A character is read and point is moved to the previous occurrence +of that character. A negative argument searches for subsequent +occurrences. + +@item skip-csi-sequence () +Read enough characters to consume a multi-key sequence such as those +defined for keys like Home and End. Such sequences begin with a +Control Sequence Indicator (CSI), usually ESC-[. If this sequence is +bound to "\e[", keys producing such sequences will have no effect +unless explicitly bound to a Readline command, instead of inserting +stray characters into the editing buffer. This is unbound by default, +but usually bound to ESC-[. + +@item insert-comment (M-#) +Without a numeric argument, the value of the @code{comment-begin} +variable is inserted at the beginning of the current line. +If a numeric argument is supplied, this command acts as a toggle: if +the characters at the beginning of the line do not match the value +of @code{comment-begin}, the value is inserted, otherwise +the characters in @code{comment-begin} are deleted from the beginning of +the line. +In either case, the line is accepted as if a newline had been typed. +@ifset BashFeatures +The default value of @code{comment-begin} causes this command +to make the current line a shell comment. +If a numeric argument causes the comment character to be removed, the line +will be executed by the shell. +@end ifset + +@item dump-functions () +Print all of the functions and their key bindings to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@item dump-variables () +Print all of the settable variables and their values to the +Readline output stream. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@item dump-macros () +Print all of the Readline key sequences bound to macros and the +strings they output. If a numeric argument is supplied, +the output is formatted in such a way that it can be made part +of an @var{inputrc} file. This command is unbound by default. + +@ifset BashFeatures +@item spell-correct-word (C-x s) +Perform spelling correction on the current word, treating it as a directory +or filename, in the same way as the @code{cdspell} shell option. +Word boundaries are the same as those used by @code{shell-forward-word}. + +@item glob-complete-word (M-g) +The word before point is treated as a pattern for pathname expansion, +with an asterisk implicitly appended. This pattern is used to +generate a list of matching file names for possible completions. + +@item glob-expand-word (C-x *) +The word before point is treated as a pattern for pathname expansion, +and the list of matching file names is inserted, replacing the word. +If a numeric argument is supplied, a @samp{*} is appended before +pathname expansion. + +@item glob-list-expansions (C-x g) +The list of expansions that would have been generated by +@code{glob-expand-word} is displayed, and the line is redrawn. +If a numeric argument is supplied, a @samp{*} is appended before +pathname expansion. + +@item display-shell-version (C-x C-v) +Display version information about the current instance of Bash. + +@item shell-expand-line (M-C-e) +Expand the line as the shell does. +This performs alias and history expansion as well as all of the shell +word expansions (@pxref{Shell Expansions}). + +@item history-expand-line (M-^) +Perform history expansion on the current line. + +@item magic-space () +Perform history expansion on the current line and insert a space +(@pxref{History Interaction}). + +@item alias-expand-line () +Perform alias expansion on the current line (@pxref{Aliases}). + +@item history-and-alias-expand-line () +Perform history and alias expansion on the current line. + +@item insert-last-argument (M-. or M-_) +A synonym for @code{yank-last-arg}. + +@item edit-and-execute-command (C-x C-e) +Invoke an editor on the current command line, and execute the result as shell +commands. +Bash attempts to invoke +@code{$VISUAL}, @code{$EDITOR}, and @code{emacs} +as the editor, in that order. + +@end ifset + +@ifclear BashFeatures +@item emacs-editing-mode (C-e) +When in @code{vi} command mode, this causes a switch to @code{emacs} +editing mode. + +@item vi-editing-mode (M-C-j) +When in @code{emacs} editing mode, this causes a switch to @code{vi} +editing mode. + +@end ifclear + +@end ftable + +@node Readline vi Mode +@section Readline vi Mode + +While the Readline library does not have a full set of @code{vi} +editing functions, it does contain enough to allow simple editing +of the line. The Readline @code{vi} mode behaves as specified in +the @sc{posix} standard. + +@ifset BashFeatures +In order to switch interactively between @code{emacs} and @code{vi} +editing modes, use the @samp{set -o emacs} and @samp{set -o vi} +commands (@pxref{The Set Builtin}). +@end ifset +@ifclear BashFeatures +In order to switch interactively between @code{emacs} and @code{vi} +editing modes, use the command @kbd{M-C-j} (bound to emacs-editing-mode +when in @code{vi} mode and to vi-editing-mode in @code{emacs} mode). +@end ifclear +The Readline default is @code{emacs} mode. + +When you enter a line in @code{vi} mode, you are already placed in +`insertion' mode, as if you had typed an @samp{i}. Pressing @key{ESC} +switches you into `command' mode, where you can edit the text of the +line with the standard @code{vi} movement keys, move to previous +history lines with @samp{k} and subsequent lines with @samp{j}, and +so forth. + +@ifset BashFeatures +@node Programmable Completion +@section Programmable Completion +@cindex programmable completion + +When word completion is attempted for an argument to a command for +which a completion specification (a @var{compspec}) has been defined +using the @code{complete} builtin (@pxref{Programmable Completion Builtins}), +the programmable completion facilities are invoked. + +First, the command name is identified. +If a compspec has been defined for that command, the +compspec is used to generate the list of possible completions for the word. +If the command word is the empty string (completion attempted at the +beginning of an empty line), any compspec defined with +the @option{-E} option to @code{complete} is used. +If the command word is a full pathname, a compspec for the full +pathname is searched for first. +If no compspec is found for the full pathname, an attempt is made to +find a compspec for the portion following the final slash. +If those searches do not result in a compspec, any compspec defined with +the @option{-D} option to @code{complete} is used as the default. +If there is no default compspec, Bash attempts alias expansion +on the command word as a final resort, and attempts to find a compspec +for the command word from any successful expansion + +Once a compspec has been found, it is used to generate the list of +matching words. +If a compspec is not found, the default Bash completion +described above (@pxref{Commands For Completion}) is performed. + +First, the actions specified by the compspec are used. +Only matches which are prefixed by the word being completed are +returned. +When the @option{-f} or @option{-d} option is used for filename or +directory name completion, the shell variable @env{FIGNORE} is +used to filter the matches. +@xref{Bash Variables}, for a description of @env{FIGNORE}. + +Any completions specified by a filename expansion pattern to the +@option{-G} option are generated next. +The words generated by the pattern need not match the word being completed. +The @env{GLOBIGNORE} shell variable is not used to filter the matches, +but the @env{FIGNORE} shell variable is used. + +Next, the string specified as the argument to the @option{-W} option +is considered. +The string is first split using the characters in the @env{IFS} +special variable as delimiters. +Shell quoting is honored within the string, in order to provide a +mechanism for the words to contain shell metacharacters or characters +in the value of @env{IFS}. +Each word is then expanded using +brace expansion, tilde expansion, parameter and variable expansion, +command substitution, and arithmetic expansion, +as described above (@pxref{Shell Expansions}). +The results are split using the rules described above +(@pxref{Word Splitting}). +The results of the expansion are prefix-matched against the word being +completed, and the matching words become the possible completions. + +After these matches have been generated, any shell function or command +specified with the @option{-F} and @option{-C} options is invoked. +When the command or function is invoked, the @env{COMP_LINE}, +@env{COMP_POINT}, @env{COMP_KEY}, and @env{COMP_TYPE} variables are +assigned values as described above (@pxref{Bash Variables}). +If a shell function is being invoked, the @env{COMP_WORDS} and +@env{COMP_CWORD} variables are also set. +When the function or command is invoked, the first argument ($1) is the +name of the command whose arguments are being completed, the +second argument ($2) is the word being completed, and the third argument +($3) is the word preceding the word being completed on the current command +line. +No filtering of the generated completions against the word being completed +is performed; the function or command has complete freedom in generating +the matches. + +Any function specified with @option{-F} is invoked first. +The function may use any of the shell facilities, including the +@code{compgen} and @code{compopt} builtins described below +(@pxref{Programmable Completion Builtins}), to generate the matches. +It must put the possible completions in the @env{COMPREPLY} array +variable, one per array element. + +Next, any command specified with the @option{-C} option is invoked +in an environment equivalent to command substitution. +It should print a list of completions, one per line, to +the standard output. +Backslash may be used to escape a newline, if necessary. + +After all of the possible completions are generated, any filter +specified with the @option{-X} option is applied to the list. +The filter is a pattern as used for pathname expansion; a @samp{&} +in the pattern is replaced with the text of the word being completed. +A literal @samp{&} may be escaped with a backslash; the backslash +is removed before attempting a match. +Any completion that matches the pattern will be removed from the list. +A leading @samp{!} negates the pattern; in this case any completion +not matching the pattern will be removed. +If the @code{nocasematch} shell option +(see the description of @code{shopt} in @ref{The Shopt Builtin}) +is enabled, the match is performed without regard to the case +of alphabetic characters. + +Finally, any prefix and suffix specified with the @option{-P} and @option{-S} +options are added to each member of the completion list, and the result is +returned to the Readline completion code as the list of possible +completions. + +If the previously-applied actions do not generate any matches, and the +@option{-o dirnames} option was supplied to @code{complete} when the +compspec was defined, directory name completion is attempted. + +If the @option{-o plusdirs} option was supplied to @code{complete} when +the compspec was defined, directory name completion is attempted and any +matches are added to the results of the other actions. + +By default, if a compspec is found, whatever it generates is returned to +the completion code as the full set of possible completions. +The default Bash completions are not attempted, and the Readline default +of filename completion is disabled. +If the @option{-o bashdefault} option was supplied to @code{complete} when +the compspec was defined, the default Bash completions are attempted +if the compspec generates no matches. +If the @option{-o default} option was supplied to @code{complete} when the +compspec was defined, Readline's default completion will be performed +if the compspec (and, if attempted, the default Bash completions) +generate no matches. + +When a compspec indicates that directory name completion is desired, +the programmable completion functions force Readline to append a slash +to completed names which are symbolic links to directories, subject to +the value of the @var{mark-directories} Readline variable, regardless +of the setting of the @var{mark-symlinked-directories} Readline variable. + +There is some support for dynamically modifying completions. This is +most useful when used in combination with a default completion specified +with @option{-D}. It's possible for shell functions executed as completion +handlers to indicate that completion should be retried by returning an +exit status of 124. If a shell function returns 124, and changes +the compspec associated with the command on which completion is being +attempted (supplied as the first argument when the function is executed), +programmable completion restarts from the beginning, with an +attempt to find a new compspec for that command. This allows a set of +completions to be built dynamically as completion is attempted, rather than +being loaded all at once. + +For instance, assuming that there is a library of compspecs, each kept in a +file corresponding to the name of the command, the following default +completion function would load completions dynamically: + +@example +_completion_loader() +@{ + . "/etc/bash_completion.d/$1.sh" >/dev/null 2>&1 && return 124 +@} +complete -D -F _completion_loader -o bashdefault -o default +@end example + +@node Programmable Completion Builtins +@section Programmable Completion Builtins +@cindex completion builtins + +Three builtin commands are available to manipulate the programmable completion +facilities: one to specify how the arguments to a particular command are to +be completed, and two to modify the completion as it is happening. + +@table @code +@item compgen +@btindex compgen +@example +@code{compgen [@var{option}] [@var{word}]} +@end example + +Generate possible completion matches for @var{word} according to +the @var{option}s, which may be any option accepted by the +@code{complete} +builtin with the exception of @option{-p} and @option{-r}, and write +the matches to the standard output. +When using the @option{-F} or @option{-C} options, the various shell variables +set by the programmable completion facilities, while available, will not +have useful values. + +The matches will be generated in the same way as if the programmable +completion code had generated them directly from a completion specification +with the same flags. +If @var{word} is specified, only those completions matching @var{word} +will be displayed. + +The return value is true unless an invalid option is supplied, or no +matches were generated. + +@item complete +@btindex complete +@example +@code{complete [-abcdefgjksuv] [-o @var{comp-option}] [-DEI] [-A @var{action}] [-G @var{globpat}] +[-W @var{wordlist}] [-F @var{function}] [-C @var{command}] [-X @var{filterpat}] +[-P @var{prefix}] [-S @var{suffix}] @var{name} [@var{name} @dots{}]} +@code{complete -pr [-DEI] [@var{name} @dots{}]} +@end example + +Specify how arguments to each @var{name} should be completed. +If the @option{-p} option is supplied, or if no options are supplied, existing +completion specifications are printed in a way that allows them to be +reused as input. +The @option{-r} option removes a completion specification for +each @var{name}, or, if no @var{name}s are supplied, all +completion specifications. +The @option{-D} option indicates that other supplied options and actions should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The @option{-E} option indicates that other supplied options and actions should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The @option{-I} option indicates that other supplied options and actions should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I}. +If any of @option{-D}, @option{-E}, or @option{-I} are supplied, any other +@var{name} arguments are ignored; these completions only apply to the case +specified by the option. + +The process of applying these completion specifications when word completion +is attempted is described above (@pxref{Programmable Completion}). + +Other options, if specified, have the following meanings. +The arguments to the @option{-G}, @option{-W}, and @option{-X} options +(and, if necessary, the @option{-P} and @option{-S} options) +should be quoted to protect them from expansion before the +@code{complete} builtin is invoked. + + +@table @code +@item -o @var{comp-option} +The @var{comp-option} controls several aspects of the compspec's behavior +beyond the simple generation of completions. +@var{comp-option} may be one of: + +@table @code + +@item bashdefault +Perform the rest of the default Bash completions if the compspec +generates no matches. + +@item default +Use Readline's default filename completion if the compspec generates +no matches. + +@item dirnames +Perform directory name completion if the compspec generates no matches. + +@item filenames +Tell Readline that the compspec generates filenames, so it can perform any +filename-specific processing (like adding a slash to directory names, +quoting special characters, or suppressing trailing spaces). +This option is intended to be used with shell functions specified +with @option{-F}. + +@item noquote +Tell Readline not to quote the completed words if they are filenames +(quoting filenames is the default). + +@item nosort +Tell Readline not to sort the list of possible completions alphabetically. + +@item nospace +Tell Readline not to append a space (the default) to words completed at +the end of the line. + +@item plusdirs +After any matches defined by the compspec are generated, +directory name completion is attempted and any +matches are added to the results of the other actions. + +@end table + +@item -A @var{action} +The @var{action} may be one of the following to generate a list of possible +completions: + +@table @code +@item alias +Alias names. May also be specified as @option{-a}. + +@item arrayvar +Array variable names. + +@item binding +Readline key binding names (@pxref{Bindable Readline Commands}). + +@item builtin +Names of shell builtin commands. May also be specified as @option{-b}. + +@item command +Command names. May also be specified as @option{-c}. + +@item directory +Directory names. May also be specified as @option{-d}. + +@item disabled +Names of disabled shell builtins. + +@item enabled +Names of enabled shell builtins. + +@item export +Names of exported shell variables. May also be specified as @option{-e}. + +@item file +File names. May also be specified as @option{-f}. + +@item function +Names of shell functions. + +@item group +Group names. May also be specified as @option{-g}. + +@item helptopic +Help topics as accepted by the @code{help} builtin (@pxref{Bash Builtins}). + +@item hostname +Hostnames, as taken from the file specified by the +@env{HOSTFILE} shell variable (@pxref{Bash Variables}). + +@item job +Job names, if job control is active. May also be specified as @option{-j}. + +@item keyword +Shell reserved words. May also be specified as @option{-k}. + +@item running +Names of running jobs, if job control is active. + +@item service +Service names. May also be specified as @option{-s}. + +@item setopt +Valid arguments for the @option{-o} option to the @code{set} builtin +(@pxref{The Set Builtin}). + +@item shopt +Shell option names as accepted by the @code{shopt} builtin +(@pxref{Bash Builtins}). + +@item signal +Signal names. + +@item stopped +Names of stopped jobs, if job control is active. + +@item user +User names. May also be specified as @option{-u}. + +@item variable +Names of all shell variables. May also be specified as @option{-v}. +@end table + +@item -C @var{command} +@var{command} is executed in a subshell environment, and its output is +used as the possible completions. +Arguments are passed as with the @option{-F} option. + +@item -F @var{function} +The shell function @var{function} is executed in the current shell +environment. +When it is executed, $1 is the name of the command whose arguments are +being completed, $2 is the word being completed, and $3 is the word +preceding the word being completed, as described above +(@pxref{Programmable Completion}). +When it finishes, the possible completions are retrieved from the value +of the @env{COMPREPLY} array variable. + +@item -G @var{globpat} +The filename expansion pattern @var{globpat} is expanded to generate +the possible completions. + +@item -P @var{prefix} +@var{prefix} is added at the beginning of each possible completion +after all other options have been applied. + +@item -S @var{suffix} +@var{suffix} is appended to each possible completion +after all other options have been applied. + +@item -W @var{wordlist} +The @var{wordlist} is split using the characters in the +@env{IFS} special variable as delimiters, and each resultant word +is expanded. +The possible completions are the members of the resultant list which +match the word being completed. + +@item -X @var{filterpat} +@var{filterpat} is a pattern as used for filename expansion. +It is applied to the list of possible completions generated by the +preceding options and arguments, and each completion matching +@var{filterpat} is removed from the list. +A leading @samp{!} in @var{filterpat} negates the pattern; in this +case, any completion not matching @var{filterpat} is removed. +@end table + +The return value is true unless an invalid option is supplied, an option +other than @option{-p} or @option{-r} is supplied without a @var{name} +argument, an attempt is made to remove a completion specification for +a @var{name} for which no specification exists, or +an error occurs adding a completion specification. + +@item compopt +@btindex compopt +@example +@code{compopt} [-o @var{option}] [-DEI] [+o @var{option}] [@var{name}] +@end example +Modify completion options for each @var{name} according to the +@var{option}s, or for the currently-executing completion if no @var{name}s +are supplied. +If no @var{option}s are given, display the completion options for each +@var{name} or the current completion. +The possible values of @var{option} are those valid for the @code{complete} +builtin described above. +The @option{-D} option indicates that other supplied options should +apply to the ``default'' command completion; that is, completion attempted +on a command for which no completion has previously been defined. +The @option{-E} option indicates that other supplied options should +apply to ``empty'' command completion; that is, completion attempted on a +blank line. +The @option{-I} option indicates that other supplied options should +apply to completion on the initial non-assignment word on the line, or after a +command delimiter such as @samp{;} or @samp{|}, which is usually command +name completion. + +If multiple options are supplied, the @option{-D} option takes precedence +over @option{-E}, and both take precedence over @option{-I} + +The return value is true unless an invalid option is supplied, an attempt +is made to modify the options for a @var{name} for which no completion +specification exists, or an output error occurs. + +@end table + +@node A Programmable Completion Example +@section A Programmable Completion Example + +The most common way to obtain additional completion functionality beyond +the default actions @code{complete} and @code{compgen} provide is to use +a shell function and bind it to a particular command using @code{complete -F}. + +The following function provides completions for the @code{cd} builtin. +It is a reasonably good example of what shell functions must do when +used for completion. This function uses the word passed as @code{$2} +to determine the directory name to complete. You can also use the +@code{COMP_WORDS} array variable; the current word is indexed by the +@code{COMP_CWORD} variable. + +The function relies on the @code{complete} and @code{compgen} builtins +to do much of the work, adding only the things that the Bash @code{cd} +does beyond accepting basic directory names: +tilde expansion (@pxref{Tilde Expansion}), +searching directories in @var{$CDPATH}, which is described above +(@pxref{Bourne Shell Builtins}), +and basic support for the @code{cdable_vars} shell option +(@pxref{The Shopt Builtin}). +@code{_comp_cd} modifies the value of @var{IFS} so that it contains only +a newline to accommodate file names containing spaces and tabs -- +@code{compgen} prints the possible completions it generates one per line. + +Possible completions go into the @var{COMPREPLY} array variable, one +completion per array element. The programmable completion system retrieves +the completions from there when the function returns. + +@example +# A completion function for the cd builtin +# based on the cd completion function from the bash_completion package +_comp_cd() +@{ + local IFS=$' \t\n' # normalize IFS + local cur _skipdot _cdpath + local i j k + + # Tilde expansion, which also expands tilde to full pathname + case "$2" in + \~*) eval cur="$2" ;; + *) cur=$2 ;; + esac + + # no cdpath or absolute pathname -- straight directory completion + if [[ -z "$@{CDPATH:-@}" ]] || [[ "$cur" == @@(./*|../*|/*) ]]; then + # compgen prints paths one per line; could also use while loop + IFS=$'\n' + COMPREPLY=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + # CDPATH+directories in the current directory if not in CDPATH + else + IFS=$'\n' + _skipdot=false + # preprocess CDPATH to convert null directory names to . + _cdpath=$@{CDPATH/#:/.:@} + _cdpath=$@{_cdpath//::/:.:@} + _cdpath=$@{_cdpath/%:/:.@} + for i in $@{_cdpath//:/$'\n'@}; do + if [[ $i -ef . ]]; then _skipdot=true; fi + k="$@{#COMPREPLY[@@]@}" + for j in $( compgen -d -- "$i/$cur" ); do + COMPREPLY[k++]=$@{j#$i/@} # cut off directory + done + done + $_skipdot || COMPREPLY+=( $(compgen -d -- "$cur") ) + IFS=$' \t\n' + fi + + # variable names if appropriate shell option set and no completions + if shopt -q cdable_vars && [[ $@{#COMPREPLY[@@]@} -eq 0 ]]; then + COMPREPLY=( $(compgen -v -- "$cur") ) + fi + + return 0 +@} +@end example + +We install the completion function using the @option{-F} option to +@code{complete}: + +@example +# Tell readline to quote appropriate and append slashes to directories; +# use the bash default completion for other arguments +complete -o filenames -o nospace -o bashdefault -F _comp_cd cd +@end example + +@noindent +Since we'd like Bash and Readline to take care of some +of the other details for us, we use several other options to tell Bash +and Readline what to do. The @option{-o filenames} option tells Readline +that the possible completions should be treated as filenames, and quoted +appropriately. That option will also cause Readline to append a slash to +filenames it can determine are directories (which is why we might want to +extend @code{_comp_cd} to append a slash if we're using directories found +via @var{CDPATH}: Readline can't tell those completions are directories). +The @option{-o nospace} option tells Readline to not append a space +character to the directory name, in case we want to append to it. +The @option{-o bashdefault} option brings in the rest of the "Bash default" +completions -- possible completions that Bash adds to the default Readline +set. These include things like command name completion, variable completion +for words beginning with @samp{$} or @samp{$@{}, completions containing pathname +expansion patterns (@pxref{Filename Expansion}), and so on. + +Once installed using @code{complete}, @code{_comp_cd} will be called every +time we attempt word completion for a @code{cd} command. + +Many more examples -- an extensive collection of completions for most of +the common GNU, Unix, and Linux commands -- are available as part of the +bash_completion project. This is installed by default on many GNU/Linux +distributions. Originally written by Ian Macdonald, the project now lives +at @url{https://github.com/scop/bash-completion/}. There are ports for +other systems such as Solaris and Mac OS X. + +An older version of the bash_completion package is distributed with bash +in the @file{examples/complete} subdirectory. + +@end ifset diff -pruN 16.3-5/readline/readline/doc/rluserman.info 16.3-5ubuntu1/readline/readline/doc/rluserman.info --- 16.3-5/readline/readline/doc/rluserman.info 1970-01-01 00:00:00.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/rluserman.info 2025-04-20 17:25:31.000000000 +0000 @@ -0,0 +1,2087 @@ +This is rluserman.info, produced by makeinfo version 6.8 from +rluserman.texi. + +This manual describes the end user interface of the GNU Readline Library +(version 8.2, 19 September 2022), a library which aids in the +consistency of user interface across discrete programs which provide a +command line interface. + + Copyright (C) 1988-2022 Free Software Foundation, Inc. + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free Documentation License, + Version 1.3 or any later version published by the Free Software + Foundation; with no Invariant Sections, no Front-Cover Texts, and + no Back-Cover Texts. A copy of the license is included in the + section entitled "GNU Free Documentation License". + +INFO-DIR-SECTION Libraries +START-INFO-DIR-ENTRY +* RLuserman: (rluserman). The GNU readline library User's Manual. +END-INFO-DIR-ENTRY + + +File: rluserman.info, Node: Top, Next: Command Line Editing, Up: (dir) + +GNU Readline Library +******************** + +This document describes the end user interface of the GNU Readline +Library, a utility which aids in the consistency of user interface +across discrete programs which provide a command line interface. The +Readline home page is . + +* Menu: + +* Command Line Editing:: GNU Readline User's Manual. +* GNU Free Documentation License:: License for copying this manual. + + +File: rluserman.info, Node: Command Line Editing, Next: GNU Free Documentation License, Prev: Top, Up: Top + +1 Command Line Editing +********************** + +This chapter describes the basic features of the GNU command line +editing interface. + +* Menu: + +* Introduction and Notation:: Notation used in this text. +* Readline Interaction:: The minimum set of commands for editing a line. +* Readline Init File:: Customizing Readline from a user's view. +* Bindable Readline Commands:: A description of most of the Readline commands + available for binding +* Readline vi Mode:: A short description of how to make Readline + behave like the vi editor. + + +File: rluserman.info, Node: Introduction and Notation, Next: Readline Interaction, Up: Command Line Editing + +1.1 Introduction to Line Editing +================================ + +The following paragraphs describe the notation used to represent +keystrokes. + + The text 'C-k' is read as 'Control-K' and describes the character +produced when the key is pressed while the Control key is depressed. + + The text 'M-k' is read as 'Meta-K' and describes the character +produced when the Meta key (if you have one) is depressed, and the +key is pressed. The Meta key is labeled on many keyboards. On +keyboards with two keys labeled (usually to either side of the +space bar), the on the left side is generally set to work as a +Meta key. The key on the right may also be configured to work as +a Meta key or may be configured as some other modifier, such as a +Compose key for typing accented characters. + + If you do not have a Meta or key, or another key working as a +Meta key, the identical keystroke can be generated by typing +_first_, and then typing . Either process is known as "metafying" +the key. + + The text 'M-C-k' is read as 'Meta-Control-k' and describes the +character produced by "metafying" 'C-k'. + + In addition, several keys have their own names. Specifically, , +, , , , and all stand for themselves when seen +in this text, or in an init file (*note Readline Init File::). If your +keyboard lacks a key, typing will produce the desired +character. The key may be labeled or on some +keyboards. + + +File: rluserman.info, Node: Readline Interaction, Next: Readline Init File, Prev: Introduction and Notation, Up: Command Line Editing + +1.2 Readline Interaction +======================== + +Often during an interactive session you type in a long line of text, +only to notice that the first word on the line is misspelled. The +Readline library gives you a set of commands for manipulating the text +as you type it in, allowing you to just fix your typo, and not forcing +you to retype the majority of the line. Using these editing commands, +you move the cursor to the place that needs correction, and delete or +insert the text of the corrections. Then, when you are satisfied with +the line, you simply press . You do not have to be at the end of +the line to press ; the entire line is accepted regardless of the +location of the cursor within the line. + +* Menu: + +* Readline Bare Essentials:: The least you need to know about Readline. +* Readline Movement Commands:: Moving about the input line. +* Readline Killing Commands:: How to delete text, and how to get it back! +* Readline Arguments:: Giving numeric arguments to commands. +* Searching:: Searching through previous lines. + + +File: rluserman.info, Node: Readline Bare Essentials, Next: Readline Movement Commands, Up: Readline Interaction + +1.2.1 Readline Bare Essentials +------------------------------ + +In order to enter characters into the line, simply type them. The typed +character appears where the cursor was, and then the cursor moves one +space to the right. If you mistype a character, you can use your erase +character to back up and delete the mistyped character. + + Sometimes you may mistype a character, and not notice the error until +you have typed several other characters. In that case, you can type +'C-b' to move the cursor to the left, and then correct your mistake. +Afterwards, you can move the cursor to the right with 'C-f'. + + When you add text in the middle of a line, you will notice that +characters to the right of the cursor are 'pushed over' to make room for +the text that you have inserted. Likewise, when you delete text behind +the cursor, characters to the right of the cursor are 'pulled back' to +fill in the blank space created by the removal of the text. A list of +the bare essentials for editing the text of an input line follows. + +'C-b' + Move back one character. +'C-f' + Move forward one character. + or + Delete the character to the left of the cursor. +'C-d' + Delete the character underneath the cursor. +Printing characters + Insert the character into the line at the cursor. +'C-_' or 'C-x C-u' + Undo the last editing command. You can undo all the way back to an + empty line. + +(Depending on your configuration, the key might be set to +delete the character to the left of the cursor and the key set to +delete the character underneath the cursor, like 'C-d', rather than the +character to the left of the cursor.) + + +File: rluserman.info, Node: Readline Movement Commands, Next: Readline Killing Commands, Prev: Readline Bare Essentials, Up: Readline Interaction + +1.2.2 Readline Movement Commands +-------------------------------- + +The above table describes the most basic keystrokes that you need in +order to do editing of the input line. For your convenience, many other +commands have been added in addition to 'C-b', 'C-f', 'C-d', and . +Here are some commands for moving more rapidly about the line. + +'C-a' + Move to the start of the line. +'C-e' + Move to the end of the line. +'M-f' + Move forward a word, where a word is composed of letters and + digits. +'M-b' + Move backward a word. +'C-l' + Clear the screen, reprinting the current line at the top. + + Notice how 'C-f' moves forward a character, while 'M-f' moves forward +a word. It is a loose convention that control keystrokes operate on +characters while meta keystrokes operate on words. + + +File: rluserman.info, Node: Readline Killing Commands, Next: Readline Arguments, Prev: Readline Movement Commands, Up: Readline Interaction + +1.2.3 Readline Killing Commands +------------------------------- + +"Killing" text means to delete the text from the line, but to save it +away for later use, usually by "yanking" (re-inserting) it back into the +line. ('Cut' and 'paste' are more recent jargon for 'kill' and 'yank'.) + + If the description for a command says that it 'kills' text, then you +can be sure that you can get the text back in a different (or the same) +place later. + + When you use a kill command, the text is saved in a "kill-ring". Any +number of consecutive kills save all of the killed text together, so +that when you yank it back, you get it all. The kill ring is not line +specific; the text that you killed on a previously typed line is +available to be yanked back later, when you are typing another line. + + Here is the list of commands for killing text. + +'C-k' + Kill the text from the current cursor position to the end of the + line. + +'M-d' + Kill from the cursor to the end of the current word, or, if between + words, to the end of the next word. Word boundaries are the same + as those used by 'M-f'. + +'M-' + Kill from the cursor to the start of the current word, or, if + between words, to the start of the previous word. Word boundaries + are the same as those used by 'M-b'. + +'C-w' + Kill from the cursor to the previous whitespace. This is different + than 'M-' because the word boundaries differ. + + Here is how to "yank" the text back into the line. Yanking means to +copy the most-recently-killed text from the kill buffer. + +'C-y' + Yank the most recently killed text back into the buffer at the + cursor. + +'M-y' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'C-y' or 'M-y'. + + +File: rluserman.info, Node: Readline Arguments, Next: Searching, Prev: Readline Killing Commands, Up: Readline Interaction + +1.2.4 Readline Arguments +------------------------ + +You can pass numeric arguments to Readline commands. Sometimes the +argument acts as a repeat count, other times it is the sign of the +argument that is significant. If you pass a negative argument to a +command which normally acts in a forward direction, that command will +act in a backward direction. For example, to kill text back to the +start of the line, you might type 'M-- C-k'. + + The general way to pass numeric arguments to a command is to type +meta digits before the command. If the first 'digit' typed is a minus +sign ('-'), then the sign of the argument will be negative. Once you +have typed one meta digit to get the argument started, you can type the +remainder of the digits, and then the command. For example, to give the +'C-d' command an argument of 10, you could type 'M-1 0 C-d', which will +delete the next ten characters on the input line. + + +File: rluserman.info, Node: Searching, Prev: Readline Arguments, Up: Readline Interaction + +1.2.5 Searching for Commands in the History +------------------------------------------- + +Readline provides commands for searching through the command history for +lines containing a specified string. There are two search modes: +"incremental" and "non-incremental". + + Incremental searches begin before the user has finished typing the +search string. As each character of the search string is typed, +Readline displays the next entry from the history matching the string +typed so far. An incremental search requires only as many characters as +needed to find the desired history entry. To search backward in the +history for a particular string, type 'C-r'. Typing 'C-s' searches +forward through the history. The characters present in the value of the +'isearch-terminators' variable are used to terminate an incremental +search. If that variable has not been assigned a value, the and +'C-J' characters will terminate an incremental search. 'C-g' will abort +an incremental search and restore the original line. When the search is +terminated, the history entry containing the search string becomes the +current line. + + To find other matching entries in the history list, type 'C-r' or +'C-s' as appropriate. This will search backward or forward in the +history for the next entry matching the search string typed so far. Any +other key sequence bound to a Readline command will terminate the search +and execute that command. For instance, a will terminate the +search and accept the line, thereby executing the command from the +history list. A movement command will terminate the search, make the +last line found the current line, and begin editing. + + Readline remembers the last incremental search string. If two 'C-r's +are typed without any intervening characters defining a new search +string, any remembered search string is used. + + Non-incremental searches read the entire search string before +starting to search for matching history lines. The search string may be +typed by the user or be part of the contents of the current line. + + +File: rluserman.info, Node: Readline Init File, Next: Bindable Readline Commands, Prev: Readline Interaction, Up: Command Line Editing + +1.3 Readline Init File +====================== + +Although the Readline library comes with a set of Emacs-like keybindings +installed by default, it is possible to use a different set of +keybindings. Any user can customize programs that use Readline by +putting commands in an "inputrc" file, conventionally in their home +directory. The name of this file is taken from the value of the +environment variable 'INPUTRC'. If that variable is unset, the default +is '~/.inputrc'. If that file does not exist or cannot be read, the +ultimate default is '/etc/inputrc'. + + When a program which uses the Readline library starts up, the init +file is read, and the key bindings are set. + + In addition, the 'C-x C-r' command re-reads this init file, thus +incorporating any changes that you might have made to it. + +* Menu: + +* Readline Init File Syntax:: Syntax for the commands in the inputrc file. + +* Conditional Init Constructs:: Conditional key bindings in the inputrc file. + +* Sample Init File:: An example inputrc file. + + +File: rluserman.info, Node: Readline Init File Syntax, Next: Conditional Init Constructs, Up: Readline Init File + +1.3.1 Readline Init File Syntax +------------------------------- + +There are only a few basic constructs allowed in the Readline init file. +Blank lines are ignored. Lines beginning with a '#' are comments. +Lines beginning with a '$' indicate conditional constructs (*note +Conditional Init Constructs::). Other lines denote variable settings +and key bindings. + +Variable Settings + You can modify the run-time behavior of Readline by altering the + values of variables in Readline using the 'set' command within the + init file. The syntax is simple: + + set VARIABLE VALUE + + Here, for example, is how to change from the default Emacs-like key + binding to use 'vi' line editing commands: + + set editing-mode vi + + Variable names and values, where appropriate, are recognized + without regard to case. Unrecognized variable names are ignored. + + Boolean variables (those that can be set to on or off) are set to + on if the value is null or empty, ON (case-insensitive), or 1. Any + other value results in the variable being set to off. + + A great deal of run-time behavior is changeable with the following + variables. + + 'active-region-start-color' + A string variable that controls the text color and background + when displaying the text in the active region (see the + description of 'enable-active-region' below). This string + must not take up any physical character positions on the + display, so it should consist only of terminal escape + sequences. It is output to the terminal before displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that puts the terminal in standout mode, + as obtained from the terminal's terminfo description. A + sample value might be '\e[01;33m'. + + 'active-region-end-color' + A string variable that "undoes" the effects of + 'active-region-start-color' and restores "normal" terminal + display appearance after displaying text in the active region. + This string must not take up any physical character positions + on the display, so it should consist only of terminal escape + sequences. It is output to the terminal after displaying the + text in the active region. This variable is reset to the + default value whenever the terminal type changes. The default + value is the string that restores the terminal from standout + mode, as obtained from the terminal's terminfo description. A + sample value might be '\e[0m'. + + 'bell-style' + Controls what happens when Readline wants to ring the terminal + bell. If set to 'none', Readline never rings the bell. If + set to 'visible', Readline uses a visible bell if one is + available. If set to 'audible' (the default), Readline + attempts to ring the terminal's bell. + + 'bind-tty-special-chars' + If set to 'on' (the default), Readline attempts to bind the + control characters treated specially by the kernel's terminal + driver to their Readline equivalents. + + 'blink-matching-paren' + If set to 'on', Readline attempts to briefly move the cursor + to an opening parenthesis when a closing parenthesis is + inserted. The default is 'off'. + + 'colored-completion-prefix' + If set to 'on', when listing completions, Readline displays + the common prefix of the set of possible completions using a + different color. The color definitions are taken from the + value of the 'LS_COLORS' environment variable. If there is a + color definition in 'LS_COLORS' for the custom suffix + 'readline-colored-completion-prefix', Readline uses this color + for the common prefix instead of its default. The default is + 'off'. + + 'colored-stats' + If set to 'on', Readline displays possible completions using + different colors to indicate their file type. The color + definitions are taken from the value of the 'LS_COLORS' + environment variable. The default is 'off'. + + 'comment-begin' + The string to insert at the beginning of the line when the + 'insert-comment' command is executed. The default value is + '"#"'. + + 'completion-display-width' + The number of screen columns used to display possible matches + when performing completion. The value is ignored if it is + less than 0 or greater than the terminal screen width. A + value of 0 will cause matches to be displayed one per line. + The default value is -1. + + 'completion-ignore-case' + If set to 'on', Readline performs filename matching and + completion in a case-insensitive fashion. The default value + is 'off'. + + 'completion-map-case' + If set to 'on', and COMPLETION-IGNORE-CASE is enabled, + Readline treats hyphens ('-') and underscores ('_') as + equivalent when performing case-insensitive filename matching + and completion. The default value is 'off'. + + 'completion-prefix-display-length' + The length in characters of the common prefix of a list of + possible completions that is displayed without modification. + When set to a value greater than zero, common prefixes longer + than this value are replaced with an ellipsis when displaying + possible completions. + + 'completion-query-items' + The number of possible completions that determines when the + user is asked whether the list of possibilities should be + displayed. If the number of possible completions is greater + than or equal to this value, Readline will ask whether or not + the user wishes to view them; otherwise, they are simply + listed. This variable must be set to an integer value greater + than or equal to zero. A zero value means Readline should + never ask; negative values are treated as zero. The default + limit is '100'. + + 'convert-meta' + If set to 'on', Readline will convert characters with the + eighth bit set to an ASCII key sequence by stripping the + eighth bit and prefixing an character, converting them + to a meta-prefixed key sequence. The default value is 'on', + but will be set to 'off' if the locale is one that contains + eight-bit characters. This variable is dependent on the + 'LC_CTYPE' locale category, and may change if the locale is + changed. + + 'disable-completion' + If set to 'On', Readline will inhibit word completion. + Completion characters will be inserted into the line as if + they had been mapped to 'self-insert'. The default is 'off'. + + 'echo-control-characters' + When set to 'on', on operating systems that indicate they + support it, Readline echoes a character corresponding to a + signal generated from the keyboard. The default is 'on'. + + 'editing-mode' + The 'editing-mode' variable controls which default set of key + bindings is used. By default, Readline starts up in Emacs + editing mode, where the keystrokes are most similar to Emacs. + This variable can be set to either 'emacs' or 'vi'. + + 'emacs-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when emacs editing mode is active. The value is + expanded like a key binding, so the standard set of meta- and + control prefixes and backslash escape sequences is available. + Use the '\1' and '\2' escapes to begin and end sequences of + non-printing characters, which can be used to embed a terminal + control sequence into the mode string. The default is '@'. + + 'enable-active-region' + The "point" is the current cursor position, and "mark" refers + to a saved cursor position (*note Commands For Moving::). The + text between the point and mark is referred to as the + "region". When this variable is set to 'On', Readline allows + certain commands to designate the region as "active". When + the region is active, Readline highlights the text in the + region using the value of the 'active-region-start-color', + which defaults to the string that enables the terminal's + standout mode. The active region shows the text inserted by + bracketed-paste and any matching text found by incremental and + non-incremental history searches. The default is 'On'. + + 'enable-bracketed-paste' + When set to 'On', Readline configures the terminal to insert + each paste into the editing buffer as a single string of + characters, instead of treating each character as if it had + been read from the keyboard. This is called putting the + terminal into "bracketed paste mode"; it prevents Readline + from executing any editing commands bound to key sequences + appearing in the pasted text. The default is 'On'. + + 'enable-keypad' + When set to 'on', Readline will try to enable the application + keypad when it is called. Some systems need this to enable + the arrow keys. The default is 'off'. + + 'enable-meta-key' + When set to 'on', Readline will try to enable any meta + modifier key the terminal claims to support when it is called. + On many terminals, the meta key is used to send eight-bit + characters. The default is 'on'. + + 'expand-tilde' + If set to 'on', tilde expansion is performed when Readline + attempts word completion. The default is 'off'. + + 'history-preserve-point' + If set to 'on', the history code attempts to place the point + (the current cursor position) at the same location on each + history line retrieved with 'previous-history' or + 'next-history'. The default is 'off'. + + 'history-size' + Set the maximum number of history entries saved in the history + list. If set to zero, any existing history entries are + deleted and no new entries are saved. If set to a value less + than zero, the number of history entries is not limited. By + default, the number of history entries is not limited. If an + attempt is made to set HISTORY-SIZE to a non-numeric value, + the maximum number of history entries will be set to 500. + + 'horizontal-scroll-mode' + This variable can be set to either 'on' or 'off'. Setting it + to 'on' means that the text of the lines being edited will + scroll horizontally on a single screen line when they are + longer than the width of the screen, instead of wrapping onto + a new screen line. This variable is automatically set to 'on' + for terminals of height 1. By default, this variable is set + to 'off'. + + 'input-meta' + If set to 'on', Readline will enable eight-bit input (it will + not clear the eighth bit in the characters it reads), + regardless of what the terminal claims it can support. The + default value is 'off', but Readline will set it to 'on' if + the locale contains eight-bit characters. The name + 'meta-flag' is a synonym for this variable. This variable is + dependent on the 'LC_CTYPE' locale category, and may change if + the locale is changed. + + 'isearch-terminators' + The string of characters that should terminate an incremental + search without subsequently executing the character as a + command (*note Searching::). If this variable has not been + given a value, the characters and 'C-J' will terminate + an incremental search. + + 'keymap' + Sets Readline's idea of the current keymap for key binding + commands. Built-in 'keymap' names are 'emacs', + 'emacs-standard', 'emacs-meta', 'emacs-ctlx', 'vi', 'vi-move', + 'vi-command', and 'vi-insert'. 'vi' is equivalent to + 'vi-command' ('vi-move' is also a synonym); 'emacs' is + equivalent to 'emacs-standard'. Applications may add + additional names. The default value is 'emacs'. The value of + the 'editing-mode' variable also affects the default keymap. + + 'keyseq-timeout' + Specifies the duration Readline will wait for a character when + reading an ambiguous key sequence (one that can form a + complete key sequence using the input read so far, or can take + additional input to complete a longer key sequence). If no + input is received within the timeout, Readline will use the + shorter but complete key sequence. Readline uses this value + to determine whether or not input is available on the current + input source ('rl_instream' by default). The value is + specified in milliseconds, so a value of 1000 means that + Readline will wait one second for additional input. If this + variable is set to a value less than or equal to zero, or to a + non-numeric value, Readline will wait until another key is + pressed to decide which key sequence to complete. The default + value is '500'. + + 'mark-directories' + If set to 'on', completed directory names have a slash + appended. The default is 'on'. + + 'mark-modified-lines' + This variable, when set to 'on', causes Readline to display an + asterisk ('*') at the start of history lines which have been + modified. This variable is 'off' by default. + + 'mark-symlinked-directories' + If set to 'on', completed names which are symbolic links to + directories have a slash appended (subject to the value of + 'mark-directories'). The default is 'off'. + + 'match-hidden-files' + This variable, when set to 'on', causes Readline to match + files whose names begin with a '.' (hidden files) when + performing filename completion. If set to 'off', the leading + '.' must be supplied by the user in the filename to be + completed. This variable is 'on' by default. + + 'menu-complete-display-prefix' + If set to 'on', menu completion displays the common prefix of + the list of possible completions (which may be empty) before + cycling through the list. The default is 'off'. + + 'output-meta' + If set to 'on', Readline will display characters with the + eighth bit set directly rather than as a meta-prefixed escape + sequence. The default is 'off', but Readline will set it to + 'on' if the locale contains eight-bit characters. This + variable is dependent on the 'LC_CTYPE' locale category, and + may change if the locale is changed. + + 'page-completions' + If set to 'on', Readline uses an internal 'more'-like pager to + display a screenful of possible completions at a time. This + variable is 'on' by default. + + 'print-completions-horizontally' + If set to 'on', Readline will display completions with matches + sorted horizontally in alphabetical order, rather than down + the screen. The default is 'off'. + + 'revert-all-at-newline' + If set to 'on', Readline will undo all changes to history + lines before returning when 'accept-line' is executed. By + default, history lines may be modified and retain individual + undo lists across calls to 'readline()'. The default is + 'off'. + + 'show-all-if-ambiguous' + This alters the default behavior of the completion functions. + If set to 'on', words which have more than one possible + completion cause the matches to be listed immediately instead + of ringing the bell. The default value is 'off'. + + 'show-all-if-unmodified' + This alters the default behavior of the completion functions + in a fashion similar to SHOW-ALL-IF-AMBIGUOUS. If set to + 'on', words which have more than one possible completion + without any possible partial completion (the possible + completions don't share a common prefix) cause the matches to + be listed immediately instead of ringing the bell. The + default value is 'off'. + + 'show-mode-in-prompt' + If set to 'on', add a string to the beginning of the prompt + indicating the editing mode: emacs, vi command, or vi + insertion. The mode strings are user-settable (e.g., + EMACS-MODE-STRING). The default value is 'off'. + + 'skip-completed-text' + If set to 'on', this alters the default completion behavior + when inserting a single match into the line. It's only active + when performing completion in the middle of a word. If + enabled, Readline does not insert characters from the + completion that match characters after point in the word being + completed, so portions of the word following the cursor are + not duplicated. For instance, if this is enabled, attempting + completion when the cursor is after the 'e' in 'Makefile' will + result in 'Makefile' rather than 'Makefilefile', assuming + there is a single possible completion. The default value is + 'off'. + + 'vi-cmd-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in command mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(cmd)'. + + 'vi-ins-mode-string' + If the SHOW-MODE-IN-PROMPT variable is enabled, this string is + displayed immediately before the last line of the primary + prompt when vi editing mode is active and in insertion mode. + The value is expanded like a key binding, so the standard set + of meta- and control prefixes and backslash escape sequences + is available. Use the '\1' and '\2' escapes to begin and end + sequences of non-printing characters, which can be used to + embed a terminal control sequence into the mode string. The + default is '(ins)'. + + 'visible-stats' + If set to 'on', a character denoting a file's type is appended + to the filename when listing possible completions. The + default is 'off'. + +Key Bindings + The syntax for controlling key bindings in the init file is simple. + First you need to find the name of the command that you want to + change. The following sections contain tables of the command name, + the default keybinding, if any, and a short description of what the + command does. + + Once you know the name of the command, simply place on a line in + the init file the name of the key you wish to bind the command to, + a colon, and then the name of the command. There can be no space + between the key name and the colon - that will be interpreted as + part of the key name. The name of the key can be expressed in + different ways, depending on what you find most comfortable. + + In addition to command names, Readline allows keys to be bound to a + string that is inserted when the key is pressed (a MACRO). + + KEYNAME: FUNCTION-NAME or MACRO + KEYNAME is the name of a key spelled out in English. For + example: + Control-u: universal-argument + Meta-Rubout: backward-kill-word + Control-o: "> output" + + In the example above, 'C-u' is bound to the function + 'universal-argument', 'M-DEL' is bound to the function + 'backward-kill-word', and 'C-o' is bound to run the macro + expressed on the right hand side (that is, to insert the text + '> output' into the line). + + A number of symbolic character names are recognized while + processing this key binding syntax: DEL, ESC, ESCAPE, LFD, + NEWLINE, RET, RETURN, RUBOUT, SPACE, SPC, and TAB. + + "KEYSEQ": FUNCTION-NAME or MACRO + KEYSEQ differs from KEYNAME above in that strings denoting an + entire key sequence can be specified, by placing the key + sequence in double quotes. Some GNU Emacs style key escapes + can be used, as in the following example, but the special + character names are not recognized. + + "\C-u": universal-argument + "\C-x\C-r": re-read-init-file + "\e[11~": "Function Key 1" + + In the above example, 'C-u' is again bound to the function + 'universal-argument' (just as it was in the first example), + ''C-x' 'C-r'' is bound to the function 're-read-init-file', + and ' <[> <1> <1> <~>' is bound to insert the text + 'Function Key 1'. + + The following GNU Emacs style escape sequences are available when + specifying key sequences: + + '\C-' + control prefix + '\M-' + meta prefix + '\e' + an escape character + '\\' + backslash + '\"' + <">, a double quotation mark + '\'' + <'>, a single quote or apostrophe + + In addition to the GNU Emacs style escape sequences, a second set + of backslash escapes is available: + + '\a' + alert (bell) + '\b' + backspace + '\d' + delete + '\f' + form feed + '\n' + newline + '\r' + carriage return + '\t' + horizontal tab + '\v' + vertical tab + '\NNN' + the eight-bit character whose value is the octal value NNN + (one to three digits) + '\xHH' + the eight-bit character whose value is the hexadecimal value + HH (one or two hex digits) + + When entering the text of a macro, single or double quotes must be + used to indicate a macro definition. Unquoted text is assumed to + be a function name. In the macro body, the backslash escapes + described above are expanded. Backslash will quote any other + character in the macro text, including '"' and '''. For example, + the following binding will make ''C-x' \' insert a single '\' into + the line: + "\C-x\\": "\\" + + +File: rluserman.info, Node: Conditional Init Constructs, Next: Sample Init File, Prev: Readline Init File Syntax, Up: Readline Init File + +1.3.2 Conditional Init Constructs +--------------------------------- + +Readline implements a facility similar in spirit to the conditional +compilation features of the C preprocessor which allows key bindings and +variable settings to be performed as the result of tests. There are +four parser directives used. + +'$if' + The '$if' construct allows bindings to be made based on the editing + mode, the terminal being used, or the application using Readline. + The text of the test, after any comparison operator, extends to the + end of the line; unless otherwise noted, no characters are required + to isolate it. + + 'mode' + The 'mode=' form of the '$if' directive is used to test + whether Readline is in 'emacs' or 'vi' mode. This may be used + in conjunction with the 'set keymap' command, for instance, to + set bindings in the 'emacs-standard' and 'emacs-ctlx' keymaps + only if Readline is starting out in 'emacs' mode. + + 'term' + The 'term=' form may be used to include terminal-specific key + bindings, perhaps to bind the key sequences output by the + terminal's function keys. The word on the right side of the + '=' is tested against both the full name of the terminal and + the portion of the terminal name before the first '-'. This + allows 'sun' to match both 'sun' and 'sun-cmd', for instance. + + 'version' + The 'version' test may be used to perform comparisons against + specific Readline versions. The 'version' expands to the + current Readline version. The set of comparison operators + includes '=' (and '=='), '!=', '<=', '>=', '<', and '>'. The + version number supplied on the right side of the operator + consists of a major version number, an optional decimal point, + and an optional minor version (e.g., '7.1'). If the minor + version is omitted, it is assumed to be '0'. The operator may + be separated from the string 'version' and from the version + number argument by whitespace. The following example sets a + variable if the Readline version being used is 7.0 or newer: + $if version >= 7.0 + set show-mode-in-prompt on + $endif + + 'application' + The APPLICATION construct is used to include + application-specific settings. Each program using the + Readline library sets the APPLICATION NAME, and you can test + for a particular value. This could be used to bind key + sequences to functions useful for a specific program. For + instance, the following command adds a key sequence that + quotes the current or previous word in Bash: + $if Bash + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + $endif + + 'variable' + The VARIABLE construct provides simple equality tests for + Readline variables and values. The permitted comparison + operators are '=', '==', and '!='. The variable name must be + separated from the comparison operator by whitespace; the + operator may be separated from the value on the right hand + side by whitespace. Both string and boolean variables may be + tested. Boolean variables must be tested against the values + ON and OFF. The following example is equivalent to the + 'mode=emacs' test described above: + $if editing-mode == emacs + set show-mode-in-prompt on + $endif + +'$endif' + This command, as seen in the previous example, terminates an '$if' + command. + +'$else' + Commands in this branch of the '$if' directive are executed if the + test fails. + +'$include' + This directive takes a single filename as an argument and reads + commands and bindings from that file. For example, the following + directive reads from '/etc/inputrc': + $include /etc/inputrc + + +File: rluserman.info, Node: Sample Init File, Prev: Conditional Init Constructs, Up: Readline Init File + +1.3.3 Sample Init File +---------------------- + +Here is an example of an INPUTRC file. This illustrates key binding, +variable assignment, and conditional syntax. + + # This file controls the behaviour of line input editing for + # programs that use the GNU Readline library. Existing + # programs include FTP, Bash, and GDB. + # + # You can re-read the inputrc file with C-x C-r. + # Lines beginning with '#' are comments. + # + # First, include any system-wide bindings and variable + # assignments from /etc/Inputrc + $include /etc/Inputrc + + # + # Set various bindings for emacs mode. + + set editing-mode emacs + + $if mode=emacs + + Meta-Control-h: backward-kill-word Text after the function name is ignored + + # + # Arrow keys in keypad mode + # + #"\M-OD": backward-char + #"\M-OC": forward-char + #"\M-OA": previous-history + #"\M-OB": next-history + # + # Arrow keys in ANSI mode + # + "\M-[D": backward-char + "\M-[C": forward-char + "\M-[A": previous-history + "\M-[B": next-history + # + # Arrow keys in 8 bit keypad mode + # + #"\M-\C-OD": backward-char + #"\M-\C-OC": forward-char + #"\M-\C-OA": previous-history + #"\M-\C-OB": next-history + # + # Arrow keys in 8 bit ANSI mode + # + #"\M-\C-[D": backward-char + #"\M-\C-[C": forward-char + #"\M-\C-[A": previous-history + #"\M-\C-[B": next-history + + C-q: quoted-insert + + $endif + + # An old-style binding. This happens to be the default. + TAB: complete + + # Macros that are convenient for shell interaction + $if Bash + # edit the path + "\C-xp": "PATH=${PATH}\e\C-e\C-a\ef\C-f" + # prepare to type a quoted word -- + # insert open and close double quotes + # and move to just after the open quote + "\C-x\"": "\"\"\C-b" + # insert a backslash (testing backslash escapes + # in sequences and macros) + "\C-x\\": "\\" + # Quote the current or previous word + "\C-xq": "\eb\"\ef\"" + # Add a binding to refresh the line, which is unbound + "\C-xr": redraw-current-line + # Edit variable on current line. + "\M-\C-v": "\C-a\C-k$\C-y\M-\C-e\C-a\C-y=" + $endif + + # use a visible bell if one is available + set bell-style visible + + # don't strip characters to 7 bits when reading + set input-meta on + + # allow iso-latin1 characters to be inserted rather + # than converted to prefix-meta sequences + set convert-meta off + + # display characters with the eighth bit set directly + # rather than as meta-prefixed characters + set output-meta on + + # if there are 150 or more possible completions for a word, + # ask whether or not the user wants to see all of them + set completion-query-items 150 + + # For FTP + $if Ftp + "\C-xg": "get \M-?" + "\C-xt": "put \M-?" + "\M-.": yank-last-arg + $endif + + +File: rluserman.info, Node: Bindable Readline Commands, Next: Readline vi Mode, Prev: Readline Init File, Up: Command Line Editing + +1.4 Bindable Readline Commands +============================== + +* Menu: + +* Commands For Moving:: Moving about the line. +* Commands For History:: Getting at previous lines. +* Commands For Text:: Commands for changing text. +* Commands For Killing:: Commands for killing and yanking. +* Numeric Arguments:: Specifying numeric arguments, repeat counts. +* Commands For Completion:: Getting Readline to do the typing for you. +* Keyboard Macros:: Saving and re-executing typed characters +* Miscellaneous Commands:: Other miscellaneous commands. + +This section describes Readline commands that may be bound to key +sequences. Command names without an accompanying key sequence are +unbound by default. + + In the following descriptions, "point" refers to the current cursor +position, and "mark" refers to a cursor position saved by the 'set-mark' +command. The text between the point and mark is referred to as the +"region". + + +File: rluserman.info, Node: Commands For Moving, Next: Commands For History, Up: Bindable Readline Commands + +1.4.1 Commands For Moving +------------------------- + +'beginning-of-line (C-a)' + Move to the start of the current line. + +'end-of-line (C-e)' + Move to the end of the line. + +'forward-char (C-f)' + Move forward a character. + +'backward-char (C-b)' + Move back a character. + +'forward-word (M-f)' + Move forward to the end of the next word. Words are composed of + letters and digits. + +'backward-word (M-b)' + Move back to the start of the current or previous word. Words are + composed of letters and digits. + +'previous-screen-line ()' + Attempt to move point to the same physical screen column on the + previous physical screen line. This will not have the desired + effect if the current Readline line does not take up more than one + physical line or if point is not greater than the length of the + prompt plus the screen width. + +'next-screen-line ()' + Attempt to move point to the same physical screen column on the + next physical screen line. This will not have the desired effect + if the current Readline line does not take up more than one + physical line or if the length of the current Readline line is not + greater than the length of the prompt plus the screen width. + +'clear-display (M-C-l)' + Clear the screen and, if possible, the terminal's scrollback + buffer, then redraw the current line, leaving the current line at + the top of the screen. + +'clear-screen (C-l)' + Clear the screen, then redraw the current line, leaving the current + line at the top of the screen. + +'redraw-current-line ()' + Refresh the current line. By default, this is unbound. + + +File: rluserman.info, Node: Commands For History, Next: Commands For Text, Prev: Commands For Moving, Up: Bindable Readline Commands + +1.4.2 Commands For Manipulating The History +------------------------------------------- + +'accept-line (Newline or Return)' + Accept the line regardless of where the cursor is. If this line is + non-empty, it may be added to the history list for future recall + with 'add_history()'. If this line is a modified history line, the + history line is restored to its original state. + +'previous-history (C-p)' + Move 'back' through the history list, fetching the previous + command. + +'next-history (C-n)' + Move 'forward' through the history list, fetching the next command. + +'beginning-of-history (M-<)' + Move to the first line in the history. + +'end-of-history (M->)' + Move to the end of the input history, i.e., the line currently + being entered. + +'reverse-search-history (C-r)' + Search backward starting at the current line and moving 'up' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'forward-search-history (C-s)' + Search forward starting at the current line and moving 'down' + through the history as necessary. This is an incremental search. + This command sets the region to the matched text and activates the + mark. + +'non-incremental-reverse-search-history (M-p)' + Search backward starting at the current line and moving 'up' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'non-incremental-forward-search-history (M-n)' + Search forward starting at the current line and moving 'down' + through the history as necessary using a non-incremental search for + a string supplied by the user. The search string may match + anywhere in a history line. + +'history-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string must match at the beginning of a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-forward ()' + Search forward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'history-substring-search-backward ()' + Search backward through the history for the string of characters + between the start of the current line and the point. The search + string may match anywhere in a history line. This is a + non-incremental search. By default, this command is unbound. + +'yank-nth-arg (M-C-y)' + Insert the first argument to the previous command (usually the + second word on the previous line) at point. With an argument N, + insert the Nth word from the previous command (the words in the + previous command begin with word 0). A negative argument inserts + the Nth word from the end of the previous command. Once the + argument N is computed, the argument is extracted as if the '!N' + history expansion had been specified. + +'yank-last-arg (M-. or M-_)' + Insert last argument to the previous command (the last word of the + previous history entry). With a numeric argument, behave exactly + like 'yank-nth-arg'. Successive calls to 'yank-last-arg' move back + through the history list, inserting the last word (or the word + specified by the argument to the first call) of each line in turn. + Any numeric argument supplied to these successive calls determines + the direction to move through the history. A negative argument + switches the direction through the history (back or forward). The + history expansion facilities are used to extract the last argument, + as if the '!$' history expansion had been specified. + +'operate-and-get-next (C-o)' + Accept the current line for return to the calling application as if + a newline had been entered, and fetch the next line relative to the + current line from the history for editing. A numeric argument, if + supplied, specifies the history entry to use instead of the current + line. + +'fetch-history ()' + With a numeric argument, fetch that entry from the history list and + make it the current line. Without an argument, move back to the + first entry in the history list. + + +File: rluserman.info, Node: Commands For Text, Next: Commands For Killing, Prev: Commands For History, Up: Bindable Readline Commands + +1.4.3 Commands For Changing Text +-------------------------------- + +'end-of-file (usually C-d)' + The character indicating end-of-file as set, for example, by + 'stty'. If this character is read when there are no characters on + the line, and point is at the beginning of the line, Readline + interprets it as the end of input and returns EOF. + +'delete-char (C-d)' + Delete the character at point. If this function is bound to the + same character as the tty EOF character, as 'C-d' commonly is, see + above for the effects. + +'backward-delete-char (Rubout)' + Delete the character behind the cursor. A numeric argument means + to kill the characters instead of deleting them. + +'forward-backward-delete-char ()' + Delete the character under the cursor, unless the cursor is at the + end of the line, in which case the character behind the cursor is + deleted. By default, this is not bound to a key. + +'quoted-insert (C-q or C-v)' + Add the next character typed to the line verbatim. This is how to + insert key sequences like 'C-q', for example. + +'tab-insert (M-)' + Insert a tab character. + +'self-insert (a, b, A, 1, !, ...)' + Insert yourself. + +'bracketed-paste-begin ()' + This function is intended to be bound to the "bracketed paste" + escape sequence sent by some terminals, and such a binding is + assigned by default. It allows Readline to insert the pasted text + as a single unit without treating each character as if it had been + read from the keyboard. The characters are inserted as if each one + was bound to 'self-insert' instead of executing any editing + commands. + + Bracketed paste sets the region (the characters between point and + the mark) to the inserted text. It uses the concept of an _active + mark_: when the mark is active, Readline redisplay uses the + terminal's standout mode to denote the region. + +'transpose-chars (C-t)' + Drag the character before the cursor forward over the character at + the cursor, moving the cursor forward as well. If the insertion + point is at the end of the line, then this transposes the last two + characters of the line. Negative arguments have no effect. + +'transpose-words (M-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. + +'upcase-word (M-u)' + Uppercase the current (or following) word. With a negative + argument, uppercase the previous word, but do not move the cursor. + +'downcase-word (M-l)' + Lowercase the current (or following) word. With a negative + argument, lowercase the previous word, but do not move the cursor. + +'capitalize-word (M-c)' + Capitalize the current (or following) word. With a negative + argument, capitalize the previous word, but do not move the cursor. + +'overwrite-mode ()' + Toggle overwrite mode. With an explicit positive numeric argument, + switches to overwrite mode. With an explicit non-positive numeric + argument, switches to insert mode. This command affects only + 'emacs' mode; 'vi' mode does overwrite differently. Each call to + 'readline()' starts in insert mode. + + In overwrite mode, characters bound to 'self-insert' replace the + text at point rather than pushing the text to the right. + Characters bound to 'backward-delete-char' replace the character + before point with a space. + + By default, this command is unbound. + + +File: rluserman.info, Node: Commands For Killing, Next: Numeric Arguments, Prev: Commands For Text, Up: Bindable Readline Commands + +1.4.4 Killing And Yanking +------------------------- + +'kill-line (C-k)' + Kill the text from point to the end of the line. With a negative + numeric argument, kill backward from the cursor to the beginning of + the current line. + +'backward-kill-line (C-x Rubout)' + Kill backward from the cursor to the beginning of the current line. + With a negative numeric argument, kill forward from the cursor to + the end of the current line. + +'unix-line-discard (C-u)' + Kill backward from the cursor to the beginning of the current line. + +'kill-whole-line ()' + Kill all characters on the current line, no matter where point is. + By default, this is unbound. + +'kill-word (M-d)' + Kill from point to the end of the current word, or if between + words, to the end of the next word. Word boundaries are the same + as 'forward-word'. + +'backward-kill-word (M-)' + Kill the word behind point. Word boundaries are the same as + 'backward-word'. + +'shell-transpose-words (M-C-t)' + Drag the word before point past the word after point, moving point + past that word as well. If the insertion point is at the end of + the line, this transposes the last two words on the line. Word + boundaries are the same as 'shell-forward-word' and + 'shell-backward-word'. + +'unix-word-rubout (C-w)' + Kill the word behind point, using white space as a word boundary. + The killed text is saved on the kill-ring. + +'unix-filename-rubout ()' + Kill the word behind point, using white space and the slash + character as the word boundaries. The killed text is saved on the + kill-ring. + +'delete-horizontal-space ()' + Delete all spaces and tabs around point. By default, this is + unbound. + +'kill-region ()' + Kill the text in the current region. By default, this command is + unbound. + +'copy-region-as-kill ()' + Copy the text in the region to the kill buffer, so it can be yanked + right away. By default, this command is unbound. + +'copy-backward-word ()' + Copy the word before point to the kill buffer. The word boundaries + are the same as 'backward-word'. By default, this command is + unbound. + +'copy-forward-word ()' + Copy the word following point to the kill buffer. The word + boundaries are the same as 'forward-word'. By default, this + command is unbound. + +'yank (C-y)' + Yank the top of the kill ring into the buffer at point. + +'yank-pop (M-y)' + Rotate the kill-ring, and yank the new top. You can only do this + if the prior command is 'yank' or 'yank-pop'. + + +File: rluserman.info, Node: Numeric Arguments, Next: Commands For Completion, Prev: Commands For Killing, Up: Bindable Readline Commands + +1.4.5 Specifying Numeric Arguments +---------------------------------- + +'digit-argument (M-0, M-1, ... M--)' + Add this digit to the argument already accumulating, or start a new + argument. 'M--' starts a negative argument. + +'universal-argument ()' + This is another way to specify an argument. If this command is + followed by one or more digits, optionally with a leading minus + sign, those digits define the argument. If the command is followed + by digits, executing 'universal-argument' again ends the numeric + argument, but is otherwise ignored. As a special case, if this + command is immediately followed by a character that is neither a + digit nor minus sign, the argument count for the next command is + multiplied by four. The argument count is initially one, so + executing this function the first time makes the argument count + four, a second time makes the argument count sixteen, and so on. + By default, this is not bound to a key. + + +File: rluserman.info, Node: Commands For Completion, Next: Keyboard Macros, Prev: Numeric Arguments, Up: Bindable Readline Commands + +1.4.6 Letting Readline Type For You +----------------------------------- + +'complete ()' + Attempt to perform completion on the text before point. The actual + completion performed is application-specific. The default is + filename completion. + +'possible-completions (M-?)' + List the possible completions of the text before point. When + displaying completions, Readline sets the number of columns used + for display to the value of 'completion-display-width', the value + of the environment variable 'COLUMNS', or the screen width, in that + order. + +'insert-completions (M-*)' + Insert all completions of the text before point that would have + been generated by 'possible-completions'. + +'menu-complete ()' + Similar to 'complete', but replaces the word to be completed with a + single match from the list of possible completions. Repeated + execution of 'menu-complete' steps through the list of possible + completions, inserting each match in turn. At the end of the list + of completions, the bell is rung (subject to the setting of + 'bell-style') and the original text is restored. An argument of N + moves N positions forward in the list of matches; a negative + argument may be used to move backward through the list. This + command is intended to be bound to , but is unbound by + default. + +'menu-complete-backward ()' + Identical to 'menu-complete', but moves backward through the list + of possible completions, as if 'menu-complete' had been given a + negative argument. + +'delete-char-or-list ()' + Deletes the character under the cursor if not at the beginning or + end of the line (like 'delete-char'). If at the end of the line, + behaves identically to 'possible-completions'. This command is + unbound by default. + + +File: rluserman.info, Node: Keyboard Macros, Next: Miscellaneous Commands, Prev: Commands For Completion, Up: Bindable Readline Commands + +1.4.7 Keyboard Macros +--------------------- + +'start-kbd-macro (C-x ()' + Begin saving the characters typed into the current keyboard macro. + +'end-kbd-macro (C-x ))' + Stop saving the characters typed into the current keyboard macro + and save the definition. + +'call-last-kbd-macro (C-x e)' + Re-execute the last keyboard macro defined, by making the + characters in the macro appear as if typed at the keyboard. + +'print-last-kbd-macro ()' + Print the last keyboard macro defined in a format suitable for the + INPUTRC file. + + +File: rluserman.info, Node: Miscellaneous Commands, Prev: Keyboard Macros, Up: Bindable Readline Commands + +1.4.8 Some Miscellaneous Commands +--------------------------------- + +'re-read-init-file (C-x C-r)' + Read in the contents of the INPUTRC file, and incorporate any + bindings or variable assignments found there. + +'abort (C-g)' + Abort the current editing command and ring the terminal's bell + (subject to the setting of 'bell-style'). + +'do-lowercase-version (M-A, M-B, M-X, ...)' + If the metafied character X is upper case, run the command that is + bound to the corresponding metafied lower case character. The + behavior is undefined if X is already lower case. + +'prefix-meta ()' + Metafy the next character typed. This is for keyboards without a + meta key. Typing ' f' is equivalent to typing 'M-f'. + +'undo (C-_ or C-x C-u)' + Incremental undo, separately remembered for each line. + +'revert-line (M-r)' + Undo all changes made to this line. This is like executing the + 'undo' command enough times to get back to the beginning. + +'tilde-expand (M-~)' + Perform tilde expansion on the current word. + +'set-mark (C-@)' + Set the mark to the point. If a numeric argument is supplied, the + mark is set to that position. + +'exchange-point-and-mark (C-x C-x)' + Swap the point with the mark. The current cursor position is set + to the saved position, and the old cursor position is saved as the + mark. + +'character-search (C-])' + A character is read and point is moved to the next occurrence of + that character. A negative argument searches for previous + occurrences. + +'character-search-backward (M-C-])' + A character is read and point is moved to the previous occurrence + of that character. A negative argument searches for subsequent + occurrences. + +'skip-csi-sequence ()' + Read enough characters to consume a multi-key sequence such as + those defined for keys like Home and End. Such sequences begin + with a Control Sequence Indicator (CSI), usually ESC-[. If this + sequence is bound to "\e[", keys producing such sequences will have + no effect unless explicitly bound to a Readline command, instead of + inserting stray characters into the editing buffer. This is + unbound by default, but usually bound to ESC-[. + +'insert-comment (M-#)' + Without a numeric argument, the value of the 'comment-begin' + variable is inserted at the beginning of the current line. If a + numeric argument is supplied, this command acts as a toggle: if the + characters at the beginning of the line do not match the value of + 'comment-begin', the value is inserted, otherwise the characters in + 'comment-begin' are deleted from the beginning of the line. In + either case, the line is accepted as if a newline had been typed. + +'dump-functions ()' + Print all of the functions and their key bindings to the Readline + output stream. If a numeric argument is supplied, the output is + formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'dump-variables ()' + Print all of the settable variables and their values to the + Readline output stream. If a numeric argument is supplied, the + output is formatted in such a way that it can be made part of an + INPUTRC file. This command is unbound by default. + +'dump-macros ()' + Print all of the Readline key sequences bound to macros and the + strings they output. If a numeric argument is supplied, the output + is formatted in such a way that it can be made part of an INPUTRC + file. This command is unbound by default. + +'emacs-editing-mode (C-e)' + When in 'vi' command mode, this causes a switch to 'emacs' editing + mode. + +'vi-editing-mode (M-C-j)' + When in 'emacs' editing mode, this causes a switch to 'vi' editing + mode. + + +File: rluserman.info, Node: Readline vi Mode, Prev: Bindable Readline Commands, Up: Command Line Editing + +1.5 Readline vi Mode +==================== + +While the Readline library does not have a full set of 'vi' editing +functions, it does contain enough to allow simple editing of the line. +The Readline 'vi' mode behaves as specified in the POSIX standard. + + In order to switch interactively between 'emacs' and 'vi' editing +modes, use the command 'M-C-j' (bound to emacs-editing-mode when in 'vi' +mode and to vi-editing-mode in 'emacs' mode). The Readline default is +'emacs' mode. + + When you enter a line in 'vi' mode, you are already placed in +'insertion' mode, as if you had typed an 'i'. Pressing switches +you into 'command' mode, where you can edit the text of the line with +the standard 'vi' movement keys, move to previous history lines with 'k' +and subsequent lines with 'j', and so forth. + + +File: rluserman.info, Node: GNU Free Documentation License, Prev: Command Line Editing, Up: Top + +Appendix A GNU Free Documentation License +***************************************** + + Version 1.3, 3 November 2008 + + Copyright (C) 2000, 2001, 2002, 2007, 2008 Free Software Foundation, Inc. + + + Everyone is permitted to copy and distribute verbatim copies + of this license document, but changing it is not allowed. + + 0. PREAMBLE + + The purpose of this License is to make a manual, textbook, or other + functional and useful document "free" in the sense of freedom: to + assure everyone the effective freedom to copy and redistribute it, + with or without modifying it, either commercially or + noncommercially. Secondarily, this License preserves for the + author and publisher a way to get credit for their work, while not + being considered responsible for modifications made by others. + + This License is a kind of "copyleft", which means that derivative + works of the document must themselves be free in the same sense. + It complements the GNU General Public License, which is a copyleft + license designed for free software. + + We have designed this License in order to use it for manuals for + free software, because free software needs free documentation: a + free program should come with manuals providing the same freedoms + that the software does. But this License is not limited to + software manuals; it can be used for any textual work, regardless + of subject matter or whether it is published as a printed book. We + recommend this License principally for works whose purpose is + instruction or reference. + + 1. APPLICABILITY AND DEFINITIONS + + This License applies to any manual or other work, in any medium, + that contains a notice placed by the copyright holder saying it can + be distributed under the terms of this License. Such a notice + grants a world-wide, royalty-free license, unlimited in duration, + to use that work under the conditions stated herein. The + "Document", below, refers to any such manual or work. Any member + of the public is a licensee, and is addressed as "you". You accept + the license if you copy, modify or distribute the work in a way + requiring permission under copyright law. + + A "Modified Version" of the Document means any work containing the + Document or a portion of it, either copied verbatim, or with + modifications and/or translated into another language. + + A "Secondary Section" is a named appendix or a front-matter section + of the Document that deals exclusively with the relationship of the + publishers or authors of the Document to the Document's overall + subject (or to related matters) and contains nothing that could + fall directly within that overall subject. (Thus, if the Document + is in part a textbook of mathematics, a Secondary Section may not + explain any mathematics.) The relationship could be a matter of + historical connection with the subject or with related matters, or + of legal, commercial, philosophical, ethical or political position + regarding them. + + The "Invariant Sections" are certain Secondary Sections whose + titles are designated, as being those of Invariant Sections, in the + notice that says that the Document is released under this License. + If a section does not fit the above definition of Secondary then it + is not allowed to be designated as Invariant. The Document may + contain zero Invariant Sections. If the Document does not identify + any Invariant Sections then there are none. + + The "Cover Texts" are certain short passages of text that are + listed, as Front-Cover Texts or Back-Cover Texts, in the notice + that says that the Document is released under this License. A + Front-Cover Text may be at most 5 words, and a Back-Cover Text may + be at most 25 words. + + A "Transparent" copy of the Document means a machine-readable copy, + represented in a format whose specification is available to the + general public, that is suitable for revising the document + straightforwardly with generic text editors or (for images composed + of pixels) generic paint programs or (for drawings) some widely + available drawing editor, and that is suitable for input to text + formatters or for automatic translation to a variety of formats + suitable for input to text formatters. A copy made in an otherwise + Transparent file format whose markup, or absence of markup, has + been arranged to thwart or discourage subsequent modification by + readers is not Transparent. An image format is not Transparent if + used for any substantial amount of text. A copy that is not + "Transparent" is called "Opaque". + + Examples of suitable formats for Transparent copies include plain + ASCII without markup, Texinfo input format, LaTeX input format, + SGML or XML using a publicly available DTD, and standard-conforming + simple HTML, PostScript or PDF designed for human modification. + Examples of transparent image formats include PNG, XCF and JPG. + Opaque formats include proprietary formats that can be read and + edited only by proprietary word processors, SGML or XML for which + the DTD and/or processing tools are not generally available, and + the machine-generated HTML, PostScript or PDF produced by some word + processors for output purposes only. + + The "Title Page" means, for a printed book, the title page itself, + plus such following pages as are needed to hold, legibly, the + material this License requires to appear in the title page. For + works in formats which do not have any title page as such, "Title + Page" means the text near the most prominent appearance of the + work's title, preceding the beginning of the body of the text. + + The "publisher" means any person or entity that distributes copies + of the Document to the public. + + A section "Entitled XYZ" means a named subunit of the Document + whose title either is precisely XYZ or contains XYZ in parentheses + following text that translates XYZ in another language. (Here XYZ + stands for a specific section name mentioned below, such as + "Acknowledgements", "Dedications", "Endorsements", or "History".) + To "Preserve the Title" of such a section when you modify the + Document means that it remains a section "Entitled XYZ" according + to this definition. + + The Document may include Warranty Disclaimers next to the notice + which states that this License applies to the Document. These + Warranty Disclaimers are considered to be included by reference in + this License, but only as regards disclaiming warranties: any other + implication that these Warranty Disclaimers may have is void and + has no effect on the meaning of this License. + + 2. VERBATIM COPYING + + You may copy and distribute the Document in any medium, either + commercially or noncommercially, provided that this License, the + copyright notices, and the license notice saying this License + applies to the Document are reproduced in all copies, and that you + add no other conditions whatsoever to those of this License. You + may not use technical measures to obstruct or control the reading + or further copying of the copies you make or distribute. However, + you may accept compensation in exchange for copies. If you + distribute a large enough number of copies you must also follow the + conditions in section 3. + + You may also lend copies, under the same conditions stated above, + and you may publicly display copies. + + 3. COPYING IN QUANTITY + + If you publish printed copies (or copies in media that commonly + have printed covers) of the Document, numbering more than 100, and + the Document's license notice requires Cover Texts, you must + enclose the copies in covers that carry, clearly and legibly, all + these Cover Texts: Front-Cover Texts on the front cover, and + Back-Cover Texts on the back cover. Both covers must also clearly + and legibly identify you as the publisher of these copies. The + front cover must present the full title with all words of the title + equally prominent and visible. You may add other material on the + covers in addition. Copying with changes limited to the covers, as + long as they preserve the title of the Document and satisfy these + conditions, can be treated as verbatim copying in other respects. + + If the required texts for either cover are too voluminous to fit + legibly, you should put the first ones listed (as many as fit + reasonably) on the actual cover, and continue the rest onto + adjacent pages. + + If you publish or distribute Opaque copies of the Document + numbering more than 100, you must either include a machine-readable + Transparent copy along with each Opaque copy, or state in or with + each Opaque copy a computer-network location from which the general + network-using public has access to download using public-standard + network protocols a complete Transparent copy of the Document, free + of added material. If you use the latter option, you must take + reasonably prudent steps, when you begin distribution of Opaque + copies in quantity, to ensure that this Transparent copy will + remain thus accessible at the stated location until at least one + year after the last time you distribute an Opaque copy (directly or + through your agents or retailers) of that edition to the public. + + It is requested, but not required, that you contact the authors of + the Document well before redistributing any large number of copies, + to give them a chance to provide you with an updated version of the + Document. + + 4. MODIFICATIONS + + You may copy and distribute a Modified Version of the Document + under the conditions of sections 2 and 3 above, provided that you + release the Modified Version under precisely this License, with the + Modified Version filling the role of the Document, thus licensing + distribution and modification of the Modified Version to whoever + possesses a copy of it. In addition, you must do these things in + the Modified Version: + + A. Use in the Title Page (and on the covers, if any) a title + distinct from that of the Document, and from those of previous + versions (which should, if there were any, be listed in the + History section of the Document). You may use the same title + as a previous version if the original publisher of that + version gives permission. + + B. List on the Title Page, as authors, one or more persons or + entities responsible for authorship of the modifications in + the Modified Version, together with at least five of the + principal authors of the Document (all of its principal + authors, if it has fewer than five), unless they release you + from this requirement. + + C. State on the Title page the name of the publisher of the + Modified Version, as the publisher. + + D. Preserve all the copyright notices of the Document. + + E. Add an appropriate copyright notice for your modifications + adjacent to the other copyright notices. + + F. Include, immediately after the copyright notices, a license + notice giving the public permission to use the Modified + Version under the terms of this License, in the form shown in + the Addendum below. + + G. Preserve in that license notice the full lists of Invariant + Sections and required Cover Texts given in the Document's + license notice. + + H. Include an unaltered copy of this License. + + I. Preserve the section Entitled "History", Preserve its Title, + and add to it an item stating at least the title, year, new + authors, and publisher of the Modified Version as given on the + Title Page. If there is no section Entitled "History" in the + Document, create one stating the title, year, authors, and + publisher of the Document as given on its Title Page, then add + an item describing the Modified Version as stated in the + previous sentence. + + J. Preserve the network location, if any, given in the Document + for public access to a Transparent copy of the Document, and + likewise the network locations given in the Document for + previous versions it was based on. These may be placed in the + "History" section. You may omit a network location for a work + that was published at least four years before the Document + itself, or if the original publisher of the version it refers + to gives permission. + + K. For any section Entitled "Acknowledgements" or "Dedications", + Preserve the Title of the section, and preserve in the section + all the substance and tone of each of the contributor + acknowledgements and/or dedications given therein. + + L. Preserve all the Invariant Sections of the Document, unaltered + in their text and in their titles. Section numbers or the + equivalent are not considered part of the section titles. + + M. Delete any section Entitled "Endorsements". Such a section + may not be included in the Modified Version. + + N. Do not retitle any existing section to be Entitled + "Endorsements" or to conflict in title with any Invariant + Section. + + O. Preserve any Warranty Disclaimers. + + If the Modified Version includes new front-matter sections or + appendices that qualify as Secondary Sections and contain no + material copied from the Document, you may at your option designate + some or all of these sections as invariant. To do this, add their + titles to the list of Invariant Sections in the Modified Version's + license notice. These titles must be distinct from any other + section titles. + + You may add a section Entitled "Endorsements", provided it contains + nothing but endorsements of your Modified Version by various + parties--for example, statements of peer review or that the text + has been approved by an organization as the authoritative + definition of a standard. + + You may add a passage of up to five words as a Front-Cover Text, + and a passage of up to 25 words as a Back-Cover Text, to the end of + the list of Cover Texts in the Modified Version. Only one passage + of Front-Cover Text and one of Back-Cover Text may be added by (or + through arrangements made by) any one entity. If the Document + already includes a cover text for the same cover, previously added + by you or by arrangement made by the same entity you are acting on + behalf of, you may not add another; but you may replace the old + one, on explicit permission from the previous publisher that added + the old one. + + The author(s) and publisher(s) of the Document do not by this + License give permission to use their names for publicity for or to + assert or imply endorsement of any Modified Version. + + 5. COMBINING DOCUMENTS + + You may combine the Document with other documents released under + this License, under the terms defined in section 4 above for + modified versions, provided that you include in the combination all + of the Invariant Sections of all of the original documents, + unmodified, and list them all as Invariant Sections of your + combined work in its license notice, and that you preserve all + their Warranty Disclaimers. + + The combined work need only contain one copy of this License, and + multiple identical Invariant Sections may be replaced with a single + copy. If there are multiple Invariant Sections with the same name + but different contents, make the title of each such section unique + by adding at the end of it, in parentheses, the name of the + original author or publisher of that section if known, or else a + unique number. Make the same adjustment to the section titles in + the list of Invariant Sections in the license notice of the + combined work. + + In the combination, you must combine any sections Entitled + "History" in the various original documents, forming one section + Entitled "History"; likewise combine any sections Entitled + "Acknowledgements", and any sections Entitled "Dedications". You + must delete all sections Entitled "Endorsements." + + 6. COLLECTIONS OF DOCUMENTS + + You may make a collection consisting of the Document and other + documents released under this License, and replace the individual + copies of this License in the various documents with a single copy + that is included in the collection, provided that you follow the + rules of this License for verbatim copying of each of the documents + in all other respects. + + You may extract a single document from such a collection, and + distribute it individually under this License, provided you insert + a copy of this License into the extracted document, and follow this + License in all other respects regarding verbatim copying of that + document. + + 7. AGGREGATION WITH INDEPENDENT WORKS + + A compilation of the Document or its derivatives with other + separate and independent documents or works, in or on a volume of a + storage or distribution medium, is called an "aggregate" if the + copyright resulting from the compilation is not used to limit the + legal rights of the compilation's users beyond what the individual + works permit. When the Document is included in an aggregate, this + License does not apply to the other works in the aggregate which + are not themselves derivative works of the Document. + + If the Cover Text requirement of section 3 is applicable to these + copies of the Document, then if the Document is less than one half + of the entire aggregate, the Document's Cover Texts may be placed + on covers that bracket the Document within the aggregate, or the + electronic equivalent of covers if the Document is in electronic + form. Otherwise they must appear on printed covers that bracket + the whole aggregate. + + 8. TRANSLATION + + Translation is considered a kind of modification, so you may + distribute translations of the Document under the terms of section + 4. Replacing Invariant Sections with translations requires special + permission from their copyright holders, but you may include + translations of some or all Invariant Sections in addition to the + original versions of these Invariant Sections. You may include a + translation of this License, and all the license notices in the + Document, and any Warranty Disclaimers, provided that you also + include the original English version of this License and the + original versions of those notices and disclaimers. In case of a + disagreement between the translation and the original version of + this License or a notice or disclaimer, the original version will + prevail. + + If a section in the Document is Entitled "Acknowledgements", + "Dedications", or "History", the requirement (section 4) to + Preserve its Title (section 1) will typically require changing the + actual title. + + 9. TERMINATION + + You may not copy, modify, sublicense, or distribute the Document + except as expressly provided under this License. Any attempt + otherwise to copy, modify, sublicense, or distribute it is void, + and will automatically terminate your rights under this License. + + However, if you cease all violation of this License, then your + license from a particular copyright holder is reinstated (a) + provisionally, unless and until the copyright holder explicitly and + finally terminates your license, and (b) permanently, if the + copyright holder fails to notify you of the violation by some + reasonable means prior to 60 days after the cessation. + + Moreover, your license from a particular copyright holder is + reinstated permanently if the copyright holder notifies you of the + violation by some reasonable means, this is the first time you have + received notice of violation of this License (for any work) from + that copyright holder, and you cure the violation prior to 30 days + after your receipt of the notice. + + Termination of your rights under this section does not terminate + the licenses of parties who have received copies or rights from you + under this License. If your rights have been terminated and not + permanently reinstated, receipt of a copy of some or all of the + same material does not give you any rights to use it. + + 10. FUTURE REVISIONS OF THIS LICENSE + + The Free Software Foundation may publish new, revised versions of + the GNU Free Documentation License from time to time. Such new + versions will be similar in spirit to the present version, but may + differ in detail to address new problems or concerns. See + . + + Each version of the License is given a distinguishing version + number. If the Document specifies that a particular numbered + version of this License "or any later version" applies to it, you + have the option of following the terms and conditions either of + that specified version or of any later version that has been + published (not as a draft) by the Free Software Foundation. If the + Document does not specify a version number of this License, you may + choose any version ever published (not as a draft) by the Free + Software Foundation. If the Document specifies that a proxy can + decide which future versions of this License can be used, that + proxy's public statement of acceptance of a version permanently + authorizes you to choose that version for the Document. + + 11. RELICENSING + + "Massive Multiauthor Collaboration Site" (or "MMC Site") means any + World Wide Web server that publishes copyrightable works and also + provides prominent facilities for anybody to edit those works. A + public wiki that anybody can edit is an example of such a server. + A "Massive Multiauthor Collaboration" (or "MMC") contained in the + site means any set of copyrightable works thus published on the MMC + site. + + "CC-BY-SA" means the Creative Commons Attribution-Share Alike 3.0 + license published by Creative Commons Corporation, a not-for-profit + corporation with a principal place of business in San Francisco, + California, as well as future copyleft versions of that license + published by that same organization. + + "Incorporate" means to publish or republish a Document, in whole or + in part, as part of another Document. + + An MMC is "eligible for relicensing" if it is licensed under this + License, and if all works that were first published under this + License somewhere other than this MMC, and subsequently + incorporated in whole or in part into the MMC, (1) had no cover + texts or invariant sections, and (2) were thus incorporated prior + to November 1, 2008. + + The operator of an MMC Site may republish an MMC contained in the + site under CC-BY-SA on the same site at any time before August 1, + 2009, provided the MMC is eligible for relicensing. + +ADDENDUM: How to use this License for your documents +==================================================== + +To use this License in a document you have written, include a copy of +the License in the document and put the following copyright and license +notices just after the title page: + + Copyright (C) YEAR YOUR NAME. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.3 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover + Texts. A copy of the license is included in the section entitled ``GNU + Free Documentation License''. + + If you have Invariant Sections, Front-Cover Texts and Back-Cover +Texts, replace the "with...Texts." line with this: + + with the Invariant Sections being LIST THEIR TITLES, with + the Front-Cover Texts being LIST, and with the Back-Cover Texts + being LIST. + + If you have Invariant Sections without Cover Texts, or some other +combination of the three, merge those two alternatives to suit the +situation. + + If your document contains nontrivial examples of program code, we +recommend releasing these examples in parallel under your choice of free +software license, such as the GNU General Public License, to permit +their use in free software. + + + +Tag Table: +Node: Top909 +Node: Command Line Editing1431 +Node: Introduction and Notation2085 +Node: Readline Interaction3710 +Node: Readline Bare Essentials4903 +Node: Readline Movement Commands6694 +Node: Readline Killing Commands7656 +Node: Readline Arguments9579 +Node: Searching10625 +Node: Readline Init File12779 +Node: Readline Init File Syntax13936 +Node: Conditional Init Constructs37240 +Node: Sample Init File41438 +Node: Bindable Readline Commands44564 +Node: Commands For Moving45620 +Node: Commands For History47380 +Node: Commands For Text52345 +Node: Commands For Killing56049 +Node: Numeric Arguments58764 +Node: Commands For Completion59905 +Node: Keyboard Macros61875 +Node: Miscellaneous Commands62565 +Node: Readline vi Mode66494 +Node: GNU Free Documentation License67408 + +End Tag Table + + +Local Variables: +coding: utf-8 +End: diff -pruN 16.3-5/readline/readline/doc/rluserman.texi 16.3-5ubuntu1/readline/readline/doc/rluserman.texi --- 16.3-5/readline/readline/doc/rluserman.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/rluserman.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,70 @@ +\input texinfo @c -*-texinfo-*- +@comment %**start of header (This is for running Texinfo on a region.) +@setfilename rluserman.info +@settitle GNU Readline Library +@include version.texi +@comment %**end of header (This is for running Texinfo on a region.) + +@copying +This manual describes the end user interface of the GNU Readline Library +(version @value{VERSION}, @value{UPDATED}), a library which aids in the +consistency of user interface across discrete programs which provide +a command line interface. + +Copyright @copyright{} 1988--2022 Free Software Foundation, Inc. + +@quotation +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +A copy of the license is included in the section entitled +``GNU Free Documentation License''. + +@end quotation +@end copying + +@dircategory Libraries +@direntry +* RLuserman: (rluserman). The GNU readline library User's Manual. +@end direntry + +@titlepage +@title GNU Readline Library User Interface +@subtitle Edition @value{EDITION}, for @code{Readline Library} Version @value{VERSION}. +@subtitle @value{UPDATED-MONTH} +@author Chet Ramey, Case Western Reserve University +@author Brian Fox, Free Software Foundation + +@page +@vskip 0pt plus 1filll +@insertcopying + +@end titlepage + +@contents + +@ifnottex +@node Top +@top GNU Readline Library + +This document describes the end user interface of the GNU Readline Library, +a utility which aids in the consistency of user interface across discrete +programs which provide a command line interface. +The Readline home page is @url{http://www.gnu.org/software/readline/}. + +@menu +* Command Line Editing:: GNU Readline User's Manual. +* GNU Free Documentation License:: License for copying this manual. +@end menu +@end ifnottex + +@include rluser.texi + +@node GNU Free Documentation License +@appendix GNU Free Documentation License + +@include fdl.texi + +@bye diff -pruN 16.3-5/readline/readline/doc/version.texi 16.3-5ubuntu1/readline/readline/doc/version.texi --- 16.3-5/readline/readline/doc/version.texi 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/readline/readline/doc/version.texi 2024-12-29 02:50:07.000000000 +0000 @@ -1 +1,11 @@ +@ignore +Copyright (C) 1988-2022 Free Software Foundation, Inc. +@end ignore +@set EDITION 8.2 +@set VERSION 8.2 + +@set UPDATED 19 September 2022 +@set UPDATED-MONTH September 2022 + +@set LASTCHANGE Mon Sep 19 11:15:16 EDT 2022 diff -pruN 16.3-5/sim/ppc/psim.texinfo 16.3-5ubuntu1/sim/ppc/psim.texinfo --- 16.3-5/sim/ppc/psim.texinfo 2025-04-21 16:28:13.000000000 +0000 +++ 16.3-5ubuntu1/sim/ppc/psim.texinfo 2024-12-29 02:50:08.000000000 +0000 @@ -1 +1,1106 @@ +\input texinfo.tex @c -*-texinfo-*- +@comment %**start of header +@setfilename texinfo +@settitle Texinfo @value{edition} +@syncodeindex vr fn +@footnotestyle separate +@paragraphindent 2 +@smallbook +@comment %**end of header + +@c Set smallbook if printing in smallbook format so the example of the +@c smallbook font is actually written using smallbook; in bigbook, a kludge +@c is used for TeX output. +@set smallbook +@c @@clear smallbook + +@ignore +@ifinfo +@format +START-INFO-DIR-ENTRY +* Texinfo: (texinfo). The documentation format for the GNU Project. +END-INFO-DIR-ENTRY +@end format +@end ifinfo +@end ignore + +@set edition 2.21 +@set update-date 7 June 1995 +@set update-month June 1995 + +@c Experiment with smaller amounts of whitespace between chapters +@c and sections. +@tex +\global\chapheadingskip = 15pt plus 4pt minus 2pt +\global\secheadingskip = 12pt plus 3pt minus 2pt +\global\subsecheadingskip = 9pt plus 2pt minus 2pt +@end tex + +@c Experiment with smaller amounts of whitespace between paragraphs in +@c the 8.5 by 11 inch format. +@ifclear smallbook +@tex +\global\parskip 6pt plus 1pt +@end tex +@end ifclear + +@finalout + +@c Currently undocumented command, 5 December 1993: +@c +@c nwnode (Same as node, but no warnings; for `makeinfo'.) + +@ifinfo +This file documents Texinfo, a documentation system that uses a single +source file to produce both on-line information and a printed manual. + +Copyright (C) 1988--2024 Free Software Foundation, Inc. + +This is the second edition of the Texinfo documentation,@* +and is consistent with version 2 of @file{texinfo.tex}. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through TeX and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@end ifinfo + +@setchapternewpage odd + +@shorttitlepage Texinfo + +@titlepage +@c use the new format for titles +@title Texinfo +@subtitle The GNU Documentation Format +@subtitle Edition @value{edition}, for Texinfo Version Three +@subtitle @value{update-month} + +@author by Robert J. Chassell and Richard M. Stallman + +@comment Include the Distribution inside the titlepage so +@c that headings are turned off. + +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988, 1990, 1991, 1992, 1993, 1995, 2010, 2011 +Free Software Foundation, Inc. + +@sp 2 +This is the second edition of the Texinfo documentation,@* +and is consistent with version 2 of @file{texinfo.tex}. +@sp 2 + +Published by the Free Software Foundation @* +59 Temple Place Suite 330, @* +Boston, MA 02111-1307 USA @* +Printed copies are available for $15 each.@* +ISBN 1-882114-63-9 +@c ISBN number 1-882114-63-9 is for edition 2.20 of 28 February 1995 + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions, +except that this permission notice may be stated in a translation approved +by the Free Software Foundation. +@sp 2 +Cover art by Etienne Suvasa. +@end titlepage + +@ifinfo +@node Top, Copying, (dir), (dir) +@top Texinfo + +Texinfo is a documentation system that uses a single source file to +produce both on-line information and printed output.@refill + +The first part of this master menu lists the major nodes in this Info +document, including the @@-command and concept indices. The rest of +the menu lists all the lower level nodes in the document.@refill + +This is Edition @value{edition} of the Texinfo documentation, +@w{@value{update-date},} for Texinfo Version Three. +@end ifinfo + +@c Here is a spare copy of the chapter menu entry descriptions, +@c in case they are accidentally deleted +@ignore +Your rights. +Texinfo in brief. +How to use Texinfo mode. +What is at the beginning of a Texinfo file? +What is at the end of a Texinfo file? +How to create chapters, sections, subsections, + appendices, and other parts. +How to provide structure for a document. +How to write nodes. +How to write menus. +How to write cross references. +How to mark words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +How to write quotations, examples, etc. +How to write lists and tables. +How to create indices. +How to insert @@-signs, braces, etc. +How to indicate results of evaluation, + expansion of macros, errors, etc. +How to force and prevent line and page breaks. +How to describe functions and the like in a uniform manner. +How to write footnotes. +How to specify text for either @TeX{} or Info. +How to print hardcopy. +How to create an Info file. +How to install an Info file +A list of all the Texinfo @@-commands. +Hints on how to write a Texinfo document. +A sample Texinfo file to look at. +Tell readers they have the right to copy + and distribute. +How to incorporate other Texinfo files. +How to write page headings and footings. +How to find formatting mistakes. +All about paragraph refilling. +A description of @@-Command syntax. +Texinfo second edition features. +A menu containing commands and variables. +A menu covering many topics. +@end ignore + +@menu +* Copying:: Your rights. +* Overview:: Texinfo in brief. +* Texinfo Mode:: How to use Texinfo mode. +* Beginning a File:: What is at the beginning of a Texinfo file? +* Ending a File:: What is at the end of a Texinfo file? +* Structuring:: How to create chapters, sections, subsections, + appendices, and other parts. +* Nodes:: How to write nodes. +* Menus:: How to write menus. +* Cross References:: How to write cross references. +* Marking Text:: How to mark words and phrases as code, + keyboard input, meta-syntactic + variables, and the like. +* Quotations and Examples:: How to write quotations, examples, etc. +* Lists and Tables:: How to write lists and tables. +* Indices:: How to create indices. +* Insertions:: How to insert @@-signs, braces, etc. +* Glyphs:: How to indicate results of evaluation, + expansion of macros, errors, etc. +* Breaks:: How to force and prevent line and page breaks. +* Definition Commands:: How to describe functions and the like + in a uniform manner. +* Footnotes:: How to write footnotes. +* Conditionals:: How to specify text for either @TeX{} or Info. +* Format/Print Hardcopy:: How to convert a Texinfo file to a file + for printing and how to print that file. +* Create an Info File:: Convert a Texinfo file into an Info file. +* Install an Info File:: Make an Info file accessible to users. +* Command List:: All the Texinfo @@-commands. +* Tips:: Hints on how to write a Texinfo document. +* Sample Texinfo File:: A sample Texinfo file to look at. +* Sample Permissions:: Tell readers they have the right to copy + and distribute. +* Include Files:: How to incorporate other Texinfo files. +* Headings:: How to write page headings and footings. +* Catching Mistakes:: How to find formatting mistakes. +* Refilling Paragraphs:: All about paragraph refilling. +* Command Syntax:: A description of @@-Command syntax. +* Obtaining TeX:: How to Obtain @TeX{}. +* New Features:: Texinfo second edition features. +* Command and Variable Index:: A menu containing commands and variables. +* Concept Index:: A menu covering many topics. + + --- The Detailed Node Listing --- + +Overview of Texinfo + +* Using Texinfo:: Create a conventional printed book + or an Info file. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Formatting Commands:: @@-commands are used for formatting. +* Conventions:: General rules for writing a Texinfo file. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. +* Minimum:: What a Texinfo file must have. +* Six Parts:: Usually, a Texinfo file has six parts. +* Short Sample:: A short sample Texinfo file. +* Acknowledgements:: + +Using Texinfo Mode + +* Texinfo Mode Overview:: How Texinfo mode can help you. +* Emacs Editing:: Texinfo mode adds to GNU Emacs' general + purpose editing features. +* Inserting:: How to insert frequently used @@-commands. +* Showing the Structure:: How to show the structure of a file. +* Updating Nodes and Menus:: How to update or create new nodes and menus. +* Info Formatting:: How to format for Info. +* Printing:: How to format and print part or all of a file. +* Texinfo Mode Summary:: Summary of all the Texinfo mode commands. + +Updating Nodes and Menus + +* Updating Commands:: Five major updating commands. +* Updating Requirements:: How to structure a Texinfo file for + using the updating command. +* Other Updating Commands:: How to indent descriptions, insert + missing nodes lines, and update + nodes in sequence. + +Beginning a Texinfo File + +* Four Parts:: Four parts begin a Texinfo file. +* Sample Beginning:: Here is a sample beginning for a Texinfo file. +* Header:: The very beginning of a Texinfo file. +* Info Summary and Permissions:: Summary and copying permissions for Info. +* Titlepage & Copyright Page:: Creating the title and copyright pages. +* The Top Node:: Creating the `Top' node and master menu. +* Software Copying Permissions:: Ensure that you and others continue to + have the right to use and share software. + +The Texinfo File Header + +* First Line:: The first line of a Texinfo file. +* Start of Header:: Formatting a region requires this. +* setfilename:: Tell Info the name of the Info file. +* settitle:: Create a title for the printed work. +* setchapternewpage:: Start chapters on right-hand pages. +* paragraphindent:: An option to specify paragraph indentation. +* End of Header:: Formatting a region requires this. + +The Title and Copyright Pages + +* titlepage:: Create a title for the printed document. +* titlefont center sp:: The @code{@@titlefont}, @code{@@center}, + and @code{@@sp} commands. +* title subtitle author:: The @code{@@title}, @code{@@subtitle}, + and @code{@@author} commands. +* Copyright & Permissions:: How to write the copyright notice and + include copying permissions. +* end titlepage:: Turn on page headings after the title and + copyright pages. +* headings on off:: An option for turning headings on and off + and double or single sided printing. + +The `Top' Node and Master Menu + +* Title of Top Node:: Sketch what the file is about. +* Master Menu Parts:: A master menu has three or more parts. + +Ending a Texinfo File + +* Printing Indices & Menus:: How to print an index in hardcopy and + generate index menus in Info. +* Contents:: How to create a table of contents. +* File End:: How to mark the end of a file. + +Chapter Structuring + +* Tree Structuring:: A manual is like an upside down tree @dots{} +* Structuring Command Types:: How to divide a manual into parts. +* makeinfo top:: The @code{@@top} command, part of the `Top' node. +* chapter:: +* unnumbered & appendix:: +* majorheading & chapheading:: +* section:: +* unnumberedsec appendixsec heading:: +* subsection:: +* unnumberedsubsec appendixsubsec subheading:: +* subsubsection:: Commands for the lowest level sections. +* Raise/lower sections:: How to change commands' hierarchical level. + +Nodes + +* Two Paths:: Different commands to structure + Info output and printed output. +* Node Menu Illustration:: A diagram, and sample nodes and menus. +* node:: How to write a node, in detail. +* makeinfo Pointer Creation:: How to create node pointers with @code{makeinfo}. + +The @code{@@node} Command + +* Node Names:: How to choose node and pointer names. +* Writing a Node:: How to write an @code{@@node} line. +* Node Line Tips:: Keep names short. +* Node Line Requirements:: Keep names unique, without @@-commands. +* First Node:: How to write a `Top' node. +* makeinfo top command:: How to use the @code{@@top} command. +* Top Node Summary:: Write a brief description for readers. + +Menus + +* Menu Location:: Put a menu in a short node. +* Writing a Menu:: What is a menu? +* Menu Parts:: A menu entry has three parts. +* Less Cluttered Menu Entry:: Two part menu entry. +* Menu Example:: Two and three part menu entries. +* Other Info Files:: How to refer to a different Info file. + +Cross References + +* References:: What cross references are for. +* Cross Reference Commands:: A summary of the different commands. +* Cross Reference Parts:: A cross reference has several parts. +* xref:: Begin a reference with `See' @dots{} +* Top Node Naming:: How to refer to the beginning of another file. +* ref:: A reference for the last part of a sentence. +* pxref:: How to write a parenthetical cross reference. +* inforef:: How to refer to an Info-only file. + +@code{@@xref} + +* Reference Syntax:: What a reference looks like and requires. +* One Argument:: @code{@@xref} with one argument. +* Two Arguments:: @code{@@xref} with two arguments. +* Three Arguments:: @code{@@xref} with three arguments. +* Four and Five Arguments:: @code{@@xref} with four and five arguments. + +Marking Words and Phrases + +* Indicating:: How to indicate definitions, files, etc. +* Emphasis:: How to emphasize text. + +Indicating Definitions, Commands, etc. + +* Useful Highlighting:: Highlighting provides useful information. +* code:: How to indicate code. +* kbd:: How to show keyboard input. +* key:: How to specify keys. +* samp:: How to show a literal sequence of characters. +* var:: How to indicate a metasyntactic variable. +* file:: How to indicate the name of a file. +* dfn:: How to specify a definition. +* cite:: How to refer to a book that is not in Info. + +Emphasizing Text + +* emph & strong:: How to emphasize text in Texinfo. +* Smallcaps:: How to use the small caps font. +* Fonts:: Various font commands for printed output. +* Customized Highlighting:: How to define highlighting commands. + +Quotations and Examples + +* Block Enclosing Commands:: Use different constructs for + different purposes. +* quotation:: How to write a quotation. +* example:: How to write an example in a fixed-width font. +* noindent:: How to prevent paragraph indentation. +* Lisp Example:: How to illustrate Lisp code. +* smallexample & smalllisp:: Forms for the @code{@@smallbook} option. +* display:: How to write an example in the current font. +* format:: How to write an example that does not narrow + the margins. +* exdent:: How to undo the indentation of a line. +* flushleft & flushright:: How to push text flushleft or flushright. +* cartouche:: How to draw cartouches around examples. + +Making Lists and Tables + +* Introducing Lists:: Texinfo formats lists for you. +* itemize:: How to construct a simple list. +* enumerate:: How to construct a numbered list. +* Two-column Tables:: How to construct a two-column table. + +Making a Two-column Table + +* table:: How to construct a two-column table. +* ftable vtable:: How to construct a two-column table + with automatic indexing. +* itemx:: How to put more entries in the first column. + +Creating Indices + +* Index Entries:: Choose different words for index entries. +* Predefined Indices:: Use different indices for different kinds + of entry. +* Indexing Commands:: How to make an index entry. +* Combining Indices:: How to combine indices. +* New Indices:: How to define your own indices. + +Combining Indices + +* syncodeindex:: How to merge two indices, using @code{@@code} + font for the merged-from index. +* synindex:: How to merge two indices, using the + default font of the merged-to index. + +Special Insertions + +* Braces Atsigns Periods:: How to insert braces, @samp{@@} and periods. +* dmn:: How to format a dimension. +* Dots Bullets:: How to insert dots and bullets. +* TeX and copyright:: How to insert the @TeX{} logo + and the copyright symbol. +* minus:: How to insert a minus sign. +* math:: How to format a mathematical expression. + +Inserting @samp{@@}, Braces, and Periods + +* Inserting An Atsign:: +* Inserting Braces:: How to insert @samp{@{} and @samp{@}} +* Controlling Spacing:: How to insert the right amount of space + after punctuation within a sentence. + +Inserting Ellipsis, Dots, and Bullets + +* dots:: How to insert dots @dots{} +* bullet:: How to insert a bullet. + +Inserting @TeX{} and the Copyright Symbol + +* tex:: How to insert the @TeX{} logo. +* copyright symbol:: How to use @code{@@copyright}@{@}. + +Glyphs for Examples + +* Glyphs Summary:: +* result:: How to show the result of expression. +* expansion:: How to indicate an expansion. +* Print Glyph:: How to indicate printed output. +* Error Glyph:: How to indicate an error message. +* Equivalence:: How to indicate equivalence. +* Point Glyph:: How to indicate the location of point. + +Making and Preventing Breaks + +* Break Commands:: Cause and prevent splits. +* Line Breaks:: How to force a single line to use two lines. +* w:: How to prevent unwanted line breaks. +* sp:: How to insert blank lines. +* page:: How to force the start of a new page. +* group:: How to prevent unwanted page breaks. +* need:: Another way to prevent unwanted page breaks. + +Definition Commands + +* Def Cmd Template:: How to structure a description using a + definition command. +* Optional Arguments:: How to handle optional and repeated arguments. +* deffnx:: How to group two or more `first' lines. +* Def Cmds in Detail:: All the definition commands. +* Def Cmd Conventions:: Conventions for writing definitions. +* Sample Function Definition:: + +The Definition Commands + +* Functions Commands:: Commands for functions and similar entities. +* Variables Commands:: Commands for variables and similar entities. +* Typed Functions:: Commands for functions in typed languages. +* Typed Variables:: Commands for variables in typed languages. +* Abstract Objects:: Commands for object-oriented programming. +* Data Types:: The definition command for data types. + +Footnotes + +* Footnote Commands:: How to write a footnote in Texinfo. +* Footnote Styles:: Controlling how footnotes appear in Info. + +Conditionally Visible Text + +* Conditional Commands:: How to specify text for Info or @TeX{}. +* Using Ordinary TeX Commands:: You can use any and all @TeX{} commands. +* set clear value:: How to designate which text to format (for + both Info and @TeX{}); and how to set a + flag to a string that you can insert. + +@code{@@set}, @code{@@clear}, and @code{@@value} + +* ifset ifclear:: Format a region if a flag is set. +* value:: Replace a flag with a string. +* value Example:: An easy way to update edition information. + +Format and Print Hardcopy + +* Use TeX:: Use @TeX{} to format for hardcopy. +* Format with tex/texindex:: How to format in a shell. +* Format with texi2dvi:: A simpler way to use the shell. +* Print with lpr:: How to print. +* Within Emacs:: How to format and print from an Emacs shell. +* Texinfo Mode Printing:: How to format and print in Texinfo mode. +* Compile-Command:: How to print using Emacs's compile command. +* Requirements Summary:: @TeX{} formatting requirements summary. +* Preparing for TeX:: What you need to do to use @TeX{}. +* Overfull hboxes:: What are and what to do with overfull hboxes. +* smallbook:: How to print small format books and manuals. +* A4 Paper:: How to print on European A4 paper. +* Cropmarks and Magnification:: How to print marks to indicate the size + of pages and how to print scaled up output. + +Creating an Info File + +* makeinfo advantages:: @code{makeinfo} provides better error checking. +* Invoking makeinfo:: How to run @code{makeinfo} from a shell. +* makeinfo options:: Specify fill-column and other options. +* Pointer Validation:: How to check that pointers point somewhere. +* makeinfo in Emacs:: How to run @code{makeinfo} from Emacs. +* texinfo-format commands:: Two Info formatting commands written + in Emacs Lisp are an alternative + to @code{makeinfo}. +* Batch Formatting:: How to format for Info in Emacs Batch mode. +* Tag and Split Files:: How tagged and split files help Info + to run better. + +Installing an Info File + +* Directory file:: The top level menu for all Info files. +* New Info File:: Listing a new info file. +* Other Info Directories:: How to specify Info files that are + located in other directories. + +Sample Permissions + +* Inserting Permissions:: How to put permissions in your document. +* ifinfo Permissions:: Sample @samp{ifinfo} copying permissions. +* Titlepage Permissions:: Sample Titlepage copying permissions. + +Include Files + +* Using Include Files:: How to use the @code{@@include} command. +* texinfo-multiple-files-update:: How to create and update nodes and + menus when using included files. +* Include File Requirements:: What @code{texinfo-multiple-files-update} expects. +* Sample Include File:: A sample outer file with included files + within it; and a sample included file. +* Include Files Evolution:: How use of the @code{@@include} command + has changed over time. + +Page Headings + +* Headings Introduced:: Conventions for using page headings. +* Heading Format:: Standard page heading formats. +* Heading Choice:: How to specify the type of page heading. +* Custom Headings:: How to create your own headings and footings. + +Formatting Mistakes + +* makeinfo preferred:: @code{makeinfo} finds errors. +* Debugging with Info:: How to catch errors with Info formatting. +* Debugging with TeX:: How to catch errors with @TeX{} formatting. +* Using texinfo-show-structure:: How to use @code{texinfo-show-structure}. +* Using occur:: How to list all lines containing a pattern. +* Running Info-Validate:: How to find badly referenced nodes. + +Finding Badly Referenced Nodes + +* Using Info-validate:: How to run @code{Info-validate}. +* Unsplit:: How to create an unsplit file. +* Tagifying:: How to tagify a file. +* Splitting:: How to split a file manually. + +Second Edition Features + +* New Texinfo Mode Commands:: The updating commands are especially useful. +* New Commands:: Many newly described @@-commands. +@end menu + +@node Copying, Overview, Top, Top +@comment node-name, next, previous, up +@unnumbered Texinfo Copying Conditions +@cindex Copying conditions +@cindex Conditions for copying Texinfo + +The programs currently being distributed that relate to Texinfo include +portions of GNU Emacs, plus other separate programs (including +@code{makeinfo}, @code{info}, @code{texindex}, and @file{texinfo.tex}). +These programs are @dfn{free}; this means that everyone is free to use +them and free to redistribute them on a free basis. The Texinfo-related +programs are not in the public domain; they are copyrighted and there +are restrictions on their distribution, but these restrictions are +designed to permit everything that a good cooperating citizen would want +to do. What is not allowed is to try to prevent others from further +sharing any version of these programs that they might get from +you.@refill + + Specifically, we want to make sure that you have the right to give +away copies of the programs that relate to Texinfo, that you receive +source code or else can get it if you want it, that you can change these +programs or use pieces of them in new free programs, and that you know +you can do these things.@refill + + To make sure that everyone has such rights, we have to forbid you to +deprive anyone else of these rights. For example, if you distribute +copies of the Texinfo related programs, you must give the recipients all +the rights that you have. You must make sure that they, too, receive or +can get the source code. And you must tell them their rights.@refill + + Also, for our own protection, we must make certain that everyone finds +out that there is no warranty for the programs that relate to Texinfo. +If these programs are modified by someone else and passed on, we want +their recipients to know that what they have is not what we distributed, +so that any problems introduced by others will not reflect on our +reputation.@refill + + The precise conditions of the licenses for the programs currently +being distributed that relate to Texinfo are found in the General Public +Licenses that accompany them.@refill + +@node Overview, Texinfo Mode, Copying, Top +@comment node-name, next, previous, up +@chapter Overview of Texinfo +@cindex Overview of Texinfo +@cindex Texinfo overview + +@dfn{Texinfo}@footnote{Note that the first syllable of ``Texinfo'' is +pronounced like ``speck'', not ``hex''. This odd pronunciation is +derived from, but is not the same as, the pronunciation of @TeX{}. In +the word @TeX{}, the @samp{X} is actually the Greek letter ``chi'' +rather than the English letter ``ex''. Pronounce @TeX{} as if the +@samp{X} were the last sound in the name `Bach'; but pronounce Texinfo +as if the @samp{x} were a `k'. Spell ``Texinfo'' with a capital ``T'' +and write the other letters in lower case.} +is a documentation system that uses a single source file to produce both +on-line information and printed output. This means that instead of +writing two different documents, one for the on-line help or other on-line +information and the other for a typeset manual or other printed work, you +need write only one document. When the work is revised, you need revise +only one document. (You can read the on-line information, known as an +@dfn{Info file}, with an Info documentation-reading program.)@refill + +@menu +* Using Texinfo:: Create a conventional printed book + or an Info file. +* Info Files:: What is an Info file? +* Printed Books:: Characteristics of a printed book or manual. +* Formatting Commands:: @@-commands are used for formatting. +* Conventions:: General rules for writing a Texinfo file. +* Comments:: How to write comments and mark regions that + the formatting commands will ignore. +* Minimum:: What a Texinfo file must have. +* Six Parts:: Usually, a Texinfo file has six parts. +* Short Sample:: A short sample Texinfo file. +* Acknowledgements:: +@end menu + +@c ************************************************************************ + + + +\input texinfo @c -*-texinfo-*- +@c %**start of header +@setfilename psim.info +@settitle PSIM +@setchapternewpage odd +@c %**end of header + + + +@ifinfo +This file documents the program PSIM. + +Copyright (C) 1994-1996, Andrew Cagney. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, subject to the terms +of the GNU General Public License, which includes the provision that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo + + +@titlepage +@title PSIM +@subtitle Model of the PowerPC Environments +@author Andrew Cagney + +@page +@vskip Opt plus ifill +Copyright @copyright{} 1994-1996, Andrew Cagney + +This is the first edition of the PSIM manual and is consistent with PSIM +version 1.0. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, subject to the terms +of the GNU General Public License, which includes the provision that the +entire resulting derived work is distributed under the terms of a +permission notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage + + + +@menu + +* Copying:: Your rights and freedoms. +* First Chappeter:: Getting started .... +* Second Chapter:: Getting finished .... + + +@end menu + + +PSIM is a program written in extended ANSI-C that implements an +instruction level simulation of the PowerPC environment. It is freely +available in source code form under the terms of the GNU General +Public License (version 3 or later). + +The PowerPC Architecture is described as having three levels of +compliance: + + UEA - User Environment Architecture + VEA - Virtual Environment Architecture + OEA - Operating Environment Architecture + +PSIM both implements all three levels of the PowerPC and includes (for +each level) a corresponding simulated run-time environment. + +In addition, PSIM, to the execution unit level, models the performance +of most of the current PowerPC implementations (contributed by Michael +Meissner). This detailed performance monitoring (unlike many other +simulators) resulting in only a relatively marginal reduction in the +simulators performance. + + +A description of how to build PSIM is contained in the file: + + ftp://ftp.ci.com.au/pub/psim/INSTALL + or ftp://cambridge.cygnus.com/pub/psim/INSTALL + +while an overview of how to use PSIM is in: + + ftp://ftp.ci.com.au/pub/psim/RUN +or ftp://cambridge.cygnus.com/pub/psim/RUN + +This file is found in: + + ftp://ftp.ci.com.au/pub/psim/README +or ftp://cambridge.cygnus.com/pub/psim/README + + +Thanks goes firstly to: + + Corinthian Engineering Pty Ltd + Cygnus Support + Highland Logic Pty Ltd + +who provided the resources needed for making this software available +on the Internet. + +More importantly I'd like to thank the following individuals who each +contributed in their own unique way: + + Allen Briggs, Bett Koch, David Edelsohn, Gordon Irlam, + Michael Meissner, Bob Mercier, Richard Perini, Dale Rahn, + Richard Stallman, Mitchele Walker + + + Andrew Cagney + Feb, 1995 + + + ---------------------------------------------------------------------- + + + What features does PSIM include? + + Monitoring and modeling + + PSIM includes (thanks to Michael Meissner) + a detailed model of most of the PowerPC + implementations to the functional unit level. + + + SMP + + The PowerPC ISA defines SMP synchronizing instructions. + This simulator implements a limited, but functional, + subset of the PowerPC synchronization instructions + behaviour. Programs that restrict their synchronization + primitives to those that work with this functional + sub-set (eg P() and V()) are able to run on the SMP + version of PSIM. + + People intending to use this system should study + the code implementing the lwarx instruction. + + ENDIAN SUPPORT + + PSIM implements the PowerPC's big and little (xor + endian) modes and correctly simulates code that + switches between these two modes. + + In addition, psim can model a true little-endian + machine. + + ISA (Instruction Set Architecture) models + + PSIM includes a model of the UEA, VEA and OEA. This + includes the time base registers (VEA) and HTAB + and BATS (OEA). + + In addition, a preliminary model of the 64 bit + PowerPC architecture is implemented. + + IO Hardware + + PSIM's internals are based around the concept + of a Device Tree. This tree intentionally + resembles that of the Device Tree found in + OpenBoot firmware. PSIM is flexible enough + to allow the user to fully configure this device + tree (and consequently the hardware model) at + run time. + + Run-time environments: + + PSIM's UEA model includes emulation for BSD + based UNIX system calls. + + PSIM's OEA model includes emulation of either: + + o OpenBoot client interface + + o MOTO's BUG interface. + + + Floating point + + Preliminary support for floating point is included. + + + Who would be interested in PSIM? + + o the curious + + Using psim, gdb, gcc and binutils the curious + user can construct an environment that allows + them to play with PowerPC Environment without + the need for real hardware. + + + o the analyst + + PSIM includes many (contributed) monitoring + features which (unlike many other simulators) + do not come with a great penalty in performance. + + Thus the performance analyst is able to use + this simulator to analyse the performance of + the system under test. + + If PSIM doesn't monitor a components of interest, + the source code is freely available, and hence + there is no hindrance to changing things + to meet a specific analysts needs. + + + o the serious SW developer + + PSIM models all three levels of the PowerPC + Architecture: UEA, VEA and OEA. Further, + the internal design is such that PSIM can + be extended to support additional requirements. + + + What performance analysis measurements can PSIM perform? + + Below is the output from a recent analysis run + (contributed by Michael Meissner): + + For the following program: + + long + simple_rand () + { + static unsigned long seed = 47114711; + unsigned long this = seed * 1103515245 + 12345; + seed = this; + /* cut-cut-cut - see the file RUN.psim */ + } + + Here is the current output generated with the -I switch on a P90 + (the compiler used is the development version of GCC with a new + scheduler replacing the old one): + + CPU #1 executed 41,994 AND instructions. + CPU #1 executed 519,785 AND Immediate instructions. + . + . + . + CPU #1 executed 1 System Call instruction. + CPU #1 executed 207,746 XOR instructions. + + CPU #1 executed 23,740,856 cycles. + CPU #1 executed 10,242,780 stalls waiting for data. + CPU #1 executed 1 stall waiting for a function unit. + . + . + . + CPU #1 executed 3,136,229 branch functional unit instructions. + CPU #1 executed 16,949,396 instructions that were accounted for in timing info. + CPU #1 executed 871,920 data reads. + CPU #1 executed 971,926 data writes. + CPU #1 executed 221 icache misses. + CPU #1 executed 16,949,396 instructions in total. + + Simulator speed was 250,731 instructions/second + + + What motivated PSIM? + + As an idea, psim was first discussed seriously during mid + 1994. At that time its main objectives were: + + + o good performance + + Many simulators loose out by only providing + a binary interface to the internals. This + interface eventually becomes a bottle neck + in the simulators performance. + + It was intended that PSIM would avoid this + problem by giving the user access to the + full source code. + + Further, by exploiting the power of modern + compilers it was hoped that PSIM would achieve + good performance with out having to compromise + its internal design. + + + o practical portability + + Rather than try to be portable to every + C compiler on every platform, it was decided + that PSIM would restrict its self to supporting + ANSI compilers that included the extension + of a long long type. + + GCC is one such compiler, consequently PSIM + should be portable to any machine running GCC. + + + o flexibility in its design + + PSIM should allow the user to select the + features required and customise the build + accordingly. By having the source code, + the compiler is able to eliminate any un + used features of the simulator. + + After all, let the compiler do the work. + + + o SMP + + A model that allowed the simulation of + SMP platforms with out the large overhead + often encountered with such models. + + + PSIM achieves each of these objectives. + + + Is PSIM PowerPC Platform (PPCP) (nee CHRP) Compliant? + + No. + + Among other things it does not have an Apple ROM socket. + + + Could PSIM be extended so that it models a CHRP machine? + + Yes. + + PSIM has been designed with the CHRP spec in mind. To model + a CHRP desktop the following would need to be added: + + o An apple ROM socket :-) + + o Model of each of the desktop IO devices + + o An OpenPIC device. + + o RTAS (Run Time Abstraction Services). + + o A fully populated device tree. + + + Is the source code available? + + Yes. + + The source code to PSIM is available under the terms of + the GNU Public Licence. This allows you to distribute + the source code for free but with certain conditions. + + See the file: + + ftp://archie.au/gnu/COPYING + + For details of the terms and conditions. + + + Where do I send bugs or report problems? + + There is a mailing list (subscribe through majordomo@ci.com.au) at: + + powerpc-psim@ci.com.au + + If I get the ftp archive updated I post a note to that mailing list. + In addition your welcome to send bugs or problems either to me or to + that e-mail list. + + This list currently averages zero articles a day. + + + Does PSIM have any limitations or problems? + + PSIM can't run rs6000/AIX binaries - At present PSIM can only + simulate static executables. Since an AIX executable is + never static, PSIM is unable to simulate its execution. + + PSIM is still under development - consequently there are going + to be bugs. + + See the file BUGS (included in the distribution) for any + other outstanding issues. Binary files 16.3-5/zlib/contrib/dotzlib/DotZLib.chm and 16.3-5ubuntu1/zlib/contrib/dotzlib/DotZLib.chm differ